orchestrata_ultimate.gateway
Reference › orchestrata_ultimate › gateway
Orchestrata WebSocket Gateway -- SPEC-014.
The gateway package is the real-time control plane of Orchestrata (SPEC-014). It is a WebSocket JSON-RPC server on port 8765 and never serves HTML; the VizInt UI is served separately, on port 5000, and connects to it. Clients such as the UI, the terminal UI and tooling send JSON-RPC requests and receive responses and pushed events. The gateway reaches the kernel over the cxpt direct transport and falls back to the in-process PipelineKernelClient when the kernel cannot be reached. The MCP transport, orchestrata-mcp (ADR-0099), is a separate stdio process that forwards MCP tool calls to the running gateway.
Parts, by role:
- Composition and entry: server (
WebSocketGateway), cli, config and kernel_reprobe. - Authentication: auth and auth_handler, selected by the
GATEWAY_AUTH_MODEsetting. - Protocol and routing: models, protocol, rpc, method_spec, method_table, error_taxonomy and exceptions; the per-domain handlers are in the handlers subpackage.
- State and events: session (connections), pubsub, ring_buffer, audit, runtime_config, workflow_types and test_runner.
- Operations: http_surface (health, readiness and metrics routes) and metrics.
- MCP: mcp_transport, mcp_tool_spec, mcp_approval_gate and mcp_ledger.
Flow: WebSocketGateway accepts a socket, authenticates it, registers it, and passes each frame either to RPCHandler (JSON-RPC) or to MessageProcessor. RPCHandler looks the method up in the table built from METHODS and calls the handler. Background pumps in the server push kernel replies, pipeline events and config changes to subscribers through PubSubManager. The entry points are cli.main (the serve command) and mcp_transport.main. Start reading at server, then rpc. The narrative is in gateway.
Curated narrative
The hand-written story of this package: orchestrata_ultimate.gateway.
49 modules, 12,376 lines of code.
Subpackages
| Package | Modules | LOC |
|---|---|---|
handlers |
22 | 5,346 |
Modules
| Module | Summary | LOC |
|---|---|---|
__init__ |
Orchestrata WebSocket Gateway -- SPEC-014. | 24 |
audit |
Graph audit writer for WebSocket gateway events. | 210 |
auth |
Token-based authentication for WebSocket connections. | 357 |
auth_handler |
Authentication handlers for WebSocket gateway connections. | 366 |
cli |
Thin CLI wrapper for the WebSocket gateway. | 112 |
config |
Gateway configuration from environment variables. | 455 |
error_taxonomy |
SPEC-098 FR-006/FR-007 — the gateway's error schema and code categories. | 106 |
exceptions |
Custom exceptions for orchestrata-gateway. | 55 |
http_surface |
Gateway HTTP surface — /health, /api/v1/health, /ready, /metrics. |
157 |
kernel_reprobe |
Bounded background re-probe: upgrade the in-process fallback to the real kernel. | 139 |
mcp_approval_gate |
McpApprovalGate -- single-use, tool-bound approval tokens. | 56 |
mcp_ledger |
McpLedger -- append-only ndjson ledger of MCP tool calls. | 74 |
mcp_tool_spec |
McpToolSpec -- one generated MCP tool, adapted from a MethodSpec. | 58 |
mcp_transport |
McpTransport -- the gateway's MCP transport over stdio (ADR-0099). | 275 |
method_spec |
MethodSpec -- one row of the gateway's declarative method table. | 70 |
method_table |
The gateway's declarative method table (ADR-0099 rules 2 and 3). | 445 |
metrics |
Prometheus instruments for the WebSocket gateway (SPEC-014 US-009). | 214 |
models |
Data models for the WebSocket gateway protocol. | 176 |
protocol |
WebSocket message processing and broadcast logic. | 244 |
pubsub |
In-process pub/sub for WebSocket gateway topics. | 357 |
ring_buffer |
Redis ring buffer with read/write using streams. | 191 |
rpc |
Thin RPC dispatcher for the WebSocket gateway. | 486 |
runtime_config |
Runtime configuration service -- Redis-backed get/set/watch (SPEC-014 US-014-005, REQ-014-081..085). | 301 |
server |
WebSocket gateway server -- ties all subsystems together. | 1462 |
session |
WebSocket connection lifecycle management. | 185 |
test_runner |
Async pytest runner with real-time progress broadcasting. | 357 |
workflow_types |
Workflow control types for the SPEC-014 resurrection (US-014-005). | 98 |
Dependency diagram
Truncated: showing 28 of 28 modules/subpackages (most connected first) and 10 of 13 outside packages.