Connector protocol and lifecycle
Build a supervised zero-grant sidecar with bounded messages, explicit capabilities, health, and graceful recovery.
Process model
Station launches the connector as a child process with a controlled environment and line-delimited protocol. The sidecar begins without account, package, Attempt, Sprint, Station-store, OBS, or arbitrary host authority.
crates/cm-station-connector-sdk/src/lib.rsExact public message types, lifecycle helpers, protocol limits, and canonical serialization.
examples/station-reference-sidecarMinimal implementation of handshake, configure, start, health, observation, stop, and shutdown.
apps/station-core/src/bin/cm-station-connector-lab.rsIndependent native lifecycle and diagnostic harness.
protocol/station/v1-fixtures.jsonRepresentative valid and invalid host/sidecar messages.
Lifecycle
Handshake
The sidecar reports protocol version, connector identity/version, supported observation contracts, requested capability classes, and implementation metadata. Station rejects unsupported or contradictory declarations.
Configure
Station supplies only reviewed source configuration and opaque grant references. The connector validates before opening a source.
Start
The sidecar opens exactly the granted source and reports transition through starting to ready or degraded health.
Observe
Each source event becomes one bounded observation with stable identity, canonical payload, source timestamp when available, and connector provenance.
Stop
Stop closes the source and returns to a configured state without losing process protocol integrity.
Shutdown
Shutdown releases every resource and exits. Station treats refusal or timeout as a supervised process failure and terminates it.
Message discipline
- Parse every inbound message through the public SDK.
- Emit only bounded protocol messages on stdout.
- Write human diagnostics to the designated diagnostic channel, never mixed into protocol output.
- Never log credentials, authorization headers, complete sensitive payloads, or account identity.
- Treat unknown message types and versions as errors, not forward-compatible guesses.
- Use stable codes and safe summaries for health/diagnostics.
No hidden routing
The sidecar does not receive a member ID, Sprint ID, or active Practice Mode. Station and the host bind a discovered source to an authorized input route after compatibility and live verification succeed.