Skip to main content

​
Process Lifecycle

Phonefarm exposes a normalized process model so callers do not need to reason about every internal queue state.

​
Public Status Enum

These are the public statuses returned by GET /processes/{process_id}:
StatusMeaning
queuedThe request is accepted and not yet terminal.
executingWork is currently executing.
retryingWork is waiting for a retry attempt.
completedAll work completed successfully.
failed_terminalExecution ended in a terminal failure or partial failure.
cancelledThe process was cancelled.

​
Internal to Public Mapping

Internally, Phonefarm uses richer request and queue states. The current mapping is:
Internal statusPublic status
QUEUEDqueued
PLANNEDqueued
CLAIMEDqueued
EXECUTINGexecuting
RETRYABLEretrying
DONEcompleted
PARTIALfailed_terminal
DEAD_LETTERfailed_terminal
CANCELLEDcancelled

​
Idempotency

Phonefarm uses different idempotency keys depending on endpoint family.

​
Process APIs

  • POST /capability-requests/enqueue
  • POST /maintenance/requests
Idempotency key: 
(process_type, requested_by.system, request_id)
Duplicate requests return the existing process instead of creating a new one.

​
Legacy Queue APIs

  • POST /ingest
Idempotency key: 
(account_id, content_id)

​
Partial Progress

A public process can represent fanout or multi-step work. That means binary success and failure is not always enough. When a process ends in partial completion:
  • public status becomes failed_terminal
  • partial_progress remains available for consumers
  • linked_ids shows queue-item relationships
If your system needs exact operator-facing messaging, use status, error, partial_progress, and linked_ids together.

​
Timestamp Semantics

The timestamps object is milestone-derived.
FieldMeaning
created_atThe row creation time.
accepted_atThe accepted milestone time.
queued_atThe planned milestone time.
executing_atThe queue-materialization milestone time.
retrying_atRetry timestamp when present.
cancel_requested_atTime cancel was requested.
finished_atDerived from terminal row update time.
Important: executing_at is not guaranteed to be the exact time of first device interaction.

​
Terminal Behavior

Terminal outcomes are:
  • completed
  • failed_terminal
  • cancelled
Process-aware cancellation may first enter a non-terminal cancel_requested path internally before settling into a final public status.