OpenPrinterAgent Lifecycle
Runtime states, reconnect behavior, restart recovery, and graceful shutdown.
oppa-agent owns the runtime state machine. Desktop UI labels are
projections of this state, not a second source of truth.
| State | Meaning |
|---|---|
| Unconfigured | No paired local key and agent identity exist |
| Pairing | Local key generation and code redemption are active |
| Disconnected | Paired but no gateway session exists |
| Connecting | Transport establishment is in progress |
| Connected | Gateway and local processing are healthy |
| Degraded | The core loop runs, but one subsystem needs attention |
| Shutting down | New work is stopped while current resources close |
Startup
The agent loads the embedded product, opens and migrates SQLite, restores printer bindings, restores pending jobs, checks the local key, starts enabled printer-discovery providers, discovers the configured server, and connects to its current gateway.
The desktop connection flow separately exposes idle, discovering,
discovery_failed, unpaired, pairing, paired, connecting,
authenticating, connected, authentication_failed, and
credential_revoked so setup failures are never collapsed into one
ambiguous flag.
Incomplete jobs are reconciled conservatively. A job persisted as received but not submitted can be retried. A job whose submission outcome is unknown after a crash is not blindly declared successful; the idempotency and recovery policy determines the next safe action.
Reconnect
Transport reconnect uses bounded exponential backoff with jitter and a maximum delay. Successful traffic resets the backoff. Sleep and wake signals may trigger a fresh connection rather than waiting for a stale socket timeout.
Shutdown
Shutdown stops new delivery, closes the WebSocket cleanly, lets bounded local operations complete, flushes state and logs, then releases resources. A disappearing printer or failed close is a structured error, never a panic.
The desktop window can close while the agent remains active in the system tray. Choosing Quit is the explicit process shutdown action.