Protocols and SDKs

Mainframe exposes a client connection at /ws and a provider connection at /provider/ws. Both use schema-validated JSON frames. Use the SDKs for reconnects, subscriptions, command correlation, and heartbeat handling.

Client connection

Terminal authenticates with a cookie session. Consuming modules authenticate with their own API keys and grants. A subscription starts with a snapshot and continues with delta frames. Registry, state, document watches, and events all use this pattern.

Use @workspace/client/index to connect, subscribe, edit documents, query history, and issue commands. Its timeline context chooses live time or a replay cursor. Mainframe refuses commands that arrive with a replay context.

Provider connection

A provider opens /provider/ws with an Authorization: Bearer … header and registers its module ID and initial entities. It can then announce, update, retire, and publish for entities it owns. Another provider’s external ID does not grant ownership.

import { connectProvider } from "@workspace/provider/index"

const provider = connectProvider({
  url: process.env.MAINFRAME_PROVIDER_URL!,
  apiKey: process.env.MAINFRAME_API_KEY!,
  module: "weather",
  entities: [],
})

await provider.ready()
provider.health("ok")

Choose a module identity and key that have been provisioned in Mainframe. The example illustrates connection setup; an actual module also announces entities and publishes channels defined by their capabilities.

Register command handlers with onCommand. The SDK validates parameters and sends executing, succeeded, or failed acknowledgements. Long operations receive a cancellation signal and progress callback. Continuous controls use a separate handler and a deadman timeout.

Commands are asynchronous

HTTP command acceptance means Mainframe validated and accepted the request. It does not prove a physical action completed. Follow command events and telemetry to determine the outcome. A disconnected provider cannot receive a new command; Mainframe does not silently queue flight commands for later delivery.

HTTP surfaces

Path	Purpose
/api/auth/*	Login and sessions
/api/registry	Authorized entity list
/api/entities/:id/commands/:name	Operator command submission
/api/docs/:collection/:id	Revision-checked document reads and writes
/api/history/*	Samples, series, state, and events
/api/cursors/*	Replay cursor lifecycle
/api/media/*	Media signaling, indexes, and authorized playback
/api/health	Core dependency checks
/metrics	Internal Prometheus metrics; blocked by the public proxy

The executable contracts are in packages/schema/src/protocol/ and apps/mainframe/src/app.ts. Consult them for complete frame shapes and route parameters.