OpenPrinterPrivate OPPA agent gateway
The checked-in AsyncAPI snapshot for the private WebSocket transport used between Neplex OpenPrinter Cloud and OPPA.
The agent gateway is the narrow, private WebSocket connection between a paired OPPA installation and an OpenPrinter server. It carries agent authentication, session negotiation, printer inventory, job delivery, and delivery results.
Build an OPPA-compatible agent
Implement pairing, authentication, handshake, inventory, and job delivery.
Browse the operation reference
Open every server-to-agent and agent-to-server message with its schema and example.
Use the public REST API
Create durable jobs and manage project access without speaking the private socket protocol.
Gateway at a glance
Private socket
Only a paired OPPA agent connects to this gateway. Application servers use the public REST API.
Authenticated session
Every connection starts with a socket-bound Ed25519 challenge before normal protocol traffic.
At-least-once delivery
The server may retry a job until OPPA confirms durable local persistence.
Connection flow
The gateway has two phases: a short authentication exchange, followed by the versioned OpenPrinter session. The private key stays in the operating system key store throughout the exchange.
The handshake is ordered
Send agent.hello on every authenticated connection, including
reconnects. Wait for server.hello before sending inventory,
diagnostics, or job acknowledgements. Authentication frames are
special and do not use the normal versioned application envelope.
Job lifecycle
The gateway reports protocol milestones rather than a universal
physical print result. Use jobId and idempotencyKey to make local
persistence and processing safe when delivery is retried.
agent.job_received
Durable local receipt
OPPA has safely persisted the complete job in its local queue. The server can stop redelivering this job.
agent.job_submitted
Local backend handoff
An enabled local printer backend accepted the job. This does not claim that paper was physically produced.
agent.job_failed
Bounded failure report
Local processing stopped with a sanitized error and a retryable
hint for the server.
Message conventions
After authentication, normal application messages use the same envelope:
| Field | Meaning |
|---|---|
protocolVersion | Negotiated OpenPrinter protocol version. |
messageId | Stable identity for this message and its retries. |
sentAt | RFC 3339 timestamp generated by the sender. |
type | Stable message discriminator such as server.print_job. |
payload | Message-specific data validated against the operation schema. |
correlationId | Optional request identity when this message is a response. |
Operation map
The complete reference is generated from the checked-in
apps/www/asyncapi/openprinter-cloud.yml snapshot. The sidebar keeps
every operation grouped by lifecycle area.
Authentication
Challenge, signature, acceptance, and rejection.
Session and inventory
Hello, heartbeats, printer snapshots, changes, and disconnects.
Jobs and diagnostics
Delivery, acknowledgements, cancellation, invalidation, and health.
Public API boundary
Use the Neplex OpenPrinter Cloud REST API for project API keys, durable job creation, job listing, errors, and the TypeScript SDK. The private gateway is an agent transport, not a replacement for that API.