Native C++ gRPC server for Ωedit™, bundled as a Node.js package with a TypeScript launcher. This package provides the server binary that powers @omega-edit/client.

Most users should install @omega-edit/client instead — it depends on this package and re-exports server lifecycle functions (startServer, stopServerGraceful, etc.). Install @omega-edit/server directly only if you need standalone server management.

Install

npm install @omega-edit/server
# or
yarn add @omega-edit/server

Usage

From TypeScript/Node.js

The recommended way to use the server is through @omega-edit/client, which re-exports the server API:

import { startServer, stopServerGraceful } from '@omega-edit/client'

const pid = await startServer(9000)
// ... use @omega-edit/client to interact with the server ...
await stopServerGraceful()

If you need lower-level control, import directly:

import { runServer, runServerWithArgs, HeartbeatOptions } from '@omega-edit/server'

// Start on a specific host and port
const proc = await runServer(9000, '127.0.0.1', '/tmp/server.pid', {
  sessionTimeoutMs: 300000,
  cleanupIntervalMs: 60000,
  shutdownWhenNoSessions: true,
  maxChangeBytes: 16 * 1024 * 1024,
  maxViewportsPerSession: 64,
  logFile: '/tmp/omega-edit-server.log',
  logLevel: 'info',
})

// Or pass raw CLI arguments
const proc2 = await runServerWithArgs([
  '--interface=0.0.0.0',
  '--port=9000',
  '--unix-socket=/tmp/omega.sock',
])

Standalone Binary

The package includes a pre-built native binary. After install, locate it in node_modules/@omega-edit/server/bin/ (or out/bin/):

# Run directly
./node_modules/@omega-edit/server/bin/omega-edit-grpc-server --port=9000

# Or override with an environment variable
CPP_SERVER_BINARY=/path/to/custom/server node your-app.js

Server API

runServer(port, host?, pidfile?, heartbeat?)

Start the server on a TCP port. Returns the spawned ChildProcess.

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | port | number | — | TCP port to listen on | | host | string | '127.0.0.1' | Bind address | | pidfile | string | — | Path to write the server PID | | heartbeat | HeartbeatOptions | — | Session reaping and resource limit options |

runServerWithArgs(args, heartbeat?)

Start the server with arbitrary CLI arguments. Useful for Unix domain socket mode or custom flags.

HeartbeatOptions

interface HeartbeatOptions {
  sessionTimeoutMs?: number       // Idle timeout before reaping (0 = disabled)
  cleanupIntervalMs?: number      // Reaper sweep interval (0 = disabled)
  shutdownWhenNoSessions?: boolean // Exit when last session is reaped
  sessionEventQueueCapacity?: number // Buffered session events per subscription (0 = unbounded)
  viewportEventQueueCapacity?: number // Buffered viewport events per subscription (0 = unbounded)
  maxChangeBytes?: number        // Insert/overwrite payload limit in bytes (0 = unbounded)
  maxViewportsPerSession?: number // Viewport cap per session (0 = unbounded)
  logFile?: string               // Append native server lifecycle logs to this file
  logLevel?: string              // Native log level: debug, info, warn, error
  logConfigFile?: string         // Compatibility shim for logback-style XML config
}

Set these limits low in local tests to exercise edge cases quickly, then rely on the production defaults when the options are omitted.

CLI Flags

The native binary supports:

| Flag | Description | | --- | --- | | -i, --interface | Bind address (default: 127.0.0.1) | | -p, --port | TCP port (default: 9000) | | -f, --pidfile | Write PID to this file | | -u, --unix-socket | Path for Unix domain socket | | --unix-socket-only | Listen only on Unix socket (no TCP) | | --session-timeout | Idle session timeout in ms | | --cleanup-interval | Reaper interval in ms | | --shutdown-when-no-sessions | Exit after last session ends | | --session-event-queue-capacity | Buffered session events per subscription | | --viewport-event-queue-capacity | Buffered viewport events per subscription | | --max-change-bytes | Limit insert/overwrite payload size | | --max-viewports-per-session | Limit open viewports per session | | --log-file | Append native server logs to a file | | --log-level | Set native server log verbosity | | --log-config | Read log file/level from a logback-style XML config |

Platform Support

The package ships pre-built binaries. Binary names follow the pattern omega-edit-grpc-server-{platform}-{arch}:

| Platform | Architecture | Binary | | --- | --- | --- | | Linux | x64 | omega-edit-grpc-server-linux-x64 | | Linux | arm64 | omega-edit-grpc-server-linux-arm64 | | macOS | x64 | omega-edit-grpc-server-macos-x64 | | macOS | arm64 | omega-edit-grpc-server-macos-arm64 | | Windows | x64 | omega-edit-grpc-server-windows-x64.exe |

Running on an unsupported platform? Set CPP_SERVER_BINARY to the path of a custom-built server binary, or see CONTRIBUTING.md to build from source.

Development

See DEVELOPMENT.md for build, packaging, and contribution instructions.

Documentation

Full documentation is published at https://ctc-oss.github.io/omega-edit/.

Versioning

Ωedit™ follows Semantic Versioning.

License

Apache 2.0 — see LICENSE.txt.