octoturge
9fd3a628f8
The `hello` frame carried a `token` field holding the edge JWT. It is gone: the token now travels in an `Authorization: Bearer` header on the WebSocket upgrade request. A token in the first frame means the backend has already accepted a socket, allocated state for it and run its JSON through this schema and a switch statement for a peer that has proved nothing. Every message type refused to act without a verified farm, so nothing could be done with such a connection - but "it cannot do anything" is a weaker guarantee than "it does not exist", and it needed a timeout to stop anyone holding sockets open for free. Verified at the handshake, an unauthenticated peer gets an HTTP 401 and no socket at all. The alternative of a `?token=` query parameter was rejected outright: a bearer credential in a URL lands in access logs, proxy logs and error breadcrumbs, which is exactly what continuum-proxy's hand-written `Debug` for `PrinterCommand` exists to avoid for presigned URLs. `Authorization` is the header every log tool already knows to redact. `farm_id` stays on the message even though the token carries the same claim. It is checked against the token rather than trusted, so sending it is how a misconfigured gateway gets caught instead of silently working against the wrong farm. A browser cannot set headers on a WebSocket, so a future user-facing socket cannot copy this exactly; its equivalent is the subprotocol field, `new WebSocket(url, ["bearer", token])`, which is also verified at the upgrade. Breaking change to the edge protocol, which is free right now: nothing is deployed. `npm run typecheck` and `npm run build` clean.
146 lines
6.1 KiB
JSON
146 lines
6.1 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "https://git.octoturge.com/Continuum/continuum-schemas/raw/branch/main/schemas/continuum/v1/edge/client_message.schema.json",
|
|
"title": "EdgeClientMessage",
|
|
"description": "What a continuum-proxy gateway sends up to continuum-backend's /ws/edge/v1 route. Discriminated on 'type'. Field names are snake_case, matching every other schema in this repository - note that this differs from the camelCase the backend's HTTP routes use, because this wire format is shared with a Rust consumer whose serde structs derive these names directly.",
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"title": "Hello",
|
|
"description": "First message on every connection, before anything else is accepted. Carries NO credential: the edge JWT minted by POST /auth/edge-token goes in an Authorization: Bearer header on the WebSocket upgrade request, and is verified before the socket exists, so an unauthenticated peer gets an HTTP 401 and no socket at all. This message used to carry a 'token' field; it was removed, because a token in the first frame means a live socket and a parsed message for a peer that has proved nothing. farm_id here is redundant with the token's own claim and is checked against it rather than trusted - a gateway naming a farm its token was not minted for is refused.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "hello"
|
|
},
|
|
"gateway_id": {
|
|
"type": "string"
|
|
},
|
|
"farm_id": {
|
|
"type": "string"
|
|
},
|
|
"stream_base_url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "Where this gateway serves camera restreams, e.g. http://gateway.local:1984 - the base of a go2rtc instance the gateway supervises. Optional: a gateway with no cameras configured, or with go2rtc not installed, omits it. Reported by the gateway rather than configured in the cloud because only the gateway knows the address it is actually reachable at. NOTE the consequence, which is a real limit and not a bug: this is a LAN address. A browser on the same network as the gateway can play the stream directly; one outside it cannot, and making that work needs a relay that does not exist yet. Anything surfacing this to a user has to cope with it being unreachable."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"gateway_id",
|
|
"farm_id"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "Heartbeat",
|
|
"properties": {
|
|
"type": {
|
|
"const": "heartbeat"
|
|
},
|
|
"seq": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Monotonic per connection, restarting at 1 on reconnect. Echoed back in heartbeat_ack so the gateway can tell a stalled connection from a slow one."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"seq"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "Telemetry",
|
|
"description": "One snapshot per printer that has something to report, on a timer. Sent as a batch rather than a message per printer: a farm has one uplink and many printers, and the backend wants a coherent picture of the farm at an instant more than it wants the lowest possible latency per machine.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "telemetry"
|
|
},
|
|
"printers": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "./printer_telemetry.schema.json"
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"printers"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "CommandResult",
|
|
"description": "The reply to a server 'command'. Correlated by command_id, which the backend generates - unlike Bambu's sequence_id, Continuum owns both ends of this protocol, so the side that needs the correlation gets to choose it.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "command_result"
|
|
},
|
|
"command_id": {
|
|
"type": "string"
|
|
},
|
|
"ok": {
|
|
"type": "boolean"
|
|
},
|
|
"error": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Present only when ok is false. A human-readable message, not a code: its only destination is an operator looking at why a command did not take. Readers must accept an explicit null here as equivalent to the key being absent: a gateway omits what it has no value for, but a serde-derived Rust producer emits null unless every field is annotated, and rejecting a whole batch over that is not worth it."
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"command_id",
|
|
"ok"
|
|
]
|
|
},
|
|
{
|
|
"type": "object",
|
|
"title": "FrameBatch",
|
|
"description": "Camera stills already uploaded to object storage, handed over for the AI worker to score. Not yet sent by any gateway - continuum-proxy restreams cameras through go2rtc and has no frame-capture path yet - but the backend consumes it, so it is part of the contract.",
|
|
"properties": {
|
|
"type": {
|
|
"const": "frame_batch"
|
|
},
|
|
"printer_id": {
|
|
"type": "string"
|
|
},
|
|
"print_job_id": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"format": "uuid",
|
|
"description": "Readers must accept an explicit null here as equivalent to the key being absent: a gateway omits what it has no value for, but a serde-derived Rust producer emits null unless every field is annotated, and rejecting a whole batch over that is not worth it."
|
|
},
|
|
"frames": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"object_key": {
|
|
"type": "string"
|
|
},
|
|
"captured_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
"required": [
|
|
"object_key",
|
|
"captured_at"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"printer_id",
|
|
"frames"
|
|
]
|
|
}
|
|
]
|
|
}
|