Durable operations
A unary invocation is an admission-sized interaction. A job that renders for minutes belongs in operations: reserve durable intent, return an operation identity, and let a bounded worker submit and observe the job.
The lifecycle
OperationService exposes start, status, list, log, plan, and cancel verbs. OperationJournal stores intent and outcomes. OperationRunner performs background submission and observation through your JobAdapter. OperationLogs stores bounded, offset-addressed log pages.
| State | Meaning |
|---|---|
queued | Intent was reserved; work is awaiting execution |
running | The backend job is being observed |
succeeded | The operation completed with a validated result |
failed | A known failure was recorded |
cancelled | Cancellation reached its terminal outcome |
interrupted | Restart ended the original worker lifecycle; observation is needed |
Supply a backend adapter
Implement JobAdapter for your actual job system. The adapter handles submission, observation, and cancellation. Persist the external job reference when known. Redact log data before it enters the SDK’s retained log store.
Read operations never launch work. Effect verbs have a separate authority check. Make a plan describe the normalized intent and bounds that approval will bind to; a plan is not execution.
Idempotency and uncertainty
Operation identity is scoped to the installed node, exact descriptor, and canonical input digest. Repeating an id with the same input returns the existing status. Reusing it for different input is refused. Retention pruning does not make an old operation id available again.
Submission tracks pending, uncertain, and accepted. If a backend might have accepted a request but no response arrived, record uncertainty. Automatically submitting again can create a duplicate resource or job.
Restart and cancellation
Restart marks queued and running rows interrupted; it does not replay effects. Reconcile against the backend’s actual state. Cancellation goes through the backend adapter. Never signal a process group that the operation does not exclusively own.
Output and retention bounds
Results are capped at 8 KiB. Status input echoes are capped at 24 KiB, log chunks at 8 KiB, and list pages at 16 entries. Larger media needs an artifact reference. Bounds apply before bytes enter the wire envelope; do not truncate a semantically complete result to make it fit.
Operations API reference describes adapter and service signatures, including failure conditions.