Protocol

OpenPrinter version 1 is an ordered UTF-8 JSON message protocol. OPPA currently carries it over WebSocket, while the server SDK stays transport-neutral. Every message has an explicit discriminator and protocol version. Messages that participate in a request flow also carry a correlation ID.

Canonical definitions

The TypeBox schemas in @openprinter/protocol are the source of truth. They produce:

inferred TypeScript types
runtime validators and codecs
a deterministic JSON Schema for non-TypeScript consumers
fixture tests shared with oppa-protocol

Never change a Rust wire type alone. Update the canonical schema, regenerate the JSON Schema, update fixtures, and make both test suites pass.

Agent messages

server discovery, pairing, and pre-hello challenge authentication
heartbeat response
printer inventory snapshot or change
job received
job submitted
job failed
sanitized diagnostics summary

Server messages

server hello with bounded service brand name
heartbeat request
print job
cancel job
printer inventory request
configuration invalidation
disconnect reason

Negotiation

The first messages establish the supported protocol versions. An unsupported version is rejected with a clear protocol error; it is never silently interpreted as the current version.

The server hello also identifies the connected service with required OpenPrinterBrandMetadata. The metadata contains a display name only; icons and external resource URLs are excluded.

Limits

Decoders enforce a maximum encoded message size, bounded section and metadata counts, bounded text and image payloads, valid identifiers, and known discriminators. Unknown fields are rejected where they would weaken the remote command boundary.

Delivery states

Use received, submitted, and failed for agent acknowledgements. printed is not a universal protocol state because a successful operating-system or TCP submission does not prove physical output.