# headgate

> Policy-aware distributed job queues for Rust and Go

- [Introduction](https://headgate.mintlify.app/docs/introduction.md): A policy-aware distributed job queue for Rust and Go, backed by PostgreSQL, MySQL, or Redis.
- [Quickstart](https://headgate.mintlify.app/docs/quickstart.md): Run a typed job locally in Rust or Go without external services.
- [Installation](https://headgate.mintlify.app/docs/installation.md): Choose a language and storage backend, then apply the matching migrations.
- [Architecture](https://headgate.mintlify.app/docs/concepts/architecture.md): How producer clients, stores, workers, APIs, and the console share one contract.
- [Jobs and lifecycle](https://headgate.mintlify.app/docs/concepts/jobs-and-lifecycle.md): Understand envelopes, state transitions, attempts, retention, and payload privacy.
- [Atomic admission](https://headgate.mintlify.app/docs/concepts/admission.md): The store-side decision that combines policy, claim, and lease.
- [Workers and leases](https://headgate.mintlify.app/docs/concepts/workers-and-leases.md): Capacity reporting, lease renewal, fencing, graceful shutdown, and crash recovery.
- [Fleet policies](https://headgate.mintlify.app/docs/concepts/policies.md): Rate limits, fairness, concurrency, queue controls, priority, and quarantine.
- [Handler outcomes](https://headgate.mintlify.app/docs/concepts/outcomes.md): Success, retry, skip, revoke, snooze, undecodable, rate-limited, and lease-lost.
- [Typed handlers](https://headgate.mintlify.app/docs/guides/handlers.md): Register task kinds, decode payload versions, access job context, and return outcomes.
- [Handler context](https://headgate.mintlify.app/docs/guides/handler-context.md): Access clients, dependency extractors, task data, output, and tracking inside handlers.
- [Enqueueing](https://headgate.mintlify.app/docs/guides/enqueueing.md): Create jobs safely with IDs, uniqueness, transactions, policy, and producer hooks.
- [Transactions and ORMs](https://headgate.mintlify.app/docs/guides/transactions-and-orms.md): Commit jobs, application writes, effects, and checkpoints atomically.
- [Events and subscriptions](https://headgate.mintlify.app/docs/guides/events-and-subscriptions.md): React to persisted outcomes without blocking worker acknowledgements.
- [Plugins and middleware](https://headgate.mintlify.app/docs/guides/plugins-and-middleware.md): Build, scope, install, and test reusable producer extensions in Rust and Go.
- [Resumable work](https://headgate.mintlify.app/docs/guides/resumable-work.md): Named steps, cursor checkpoints, and transactionally guarded side effects.
- [Results and progress](https://headgate.mintlify.app/docs/guides/results-and-progress.md): Persist final results, mid-run output, progress, and attempt-scoped logs safely.
- [Execution reliability](https://headgate.mintlify.app/docs/guides/execution-reliability.md): Retries, crashes, deadlines, leases, shutdown, isolation, and terminal handlers.
- [Dead-letter queue](https://headgate.mintlify.app/docs/guides/dead-letter-queue.md): Understand archived jobs, inspect failures, redrive safely, and configure retention.
- [Batch handlers](https://headgate.mintlify.app/docs/guides/batch-handlers.md): Coalesce independently durable jobs into bounded handler calls.
- [Periodic jobs](https://headgate.mintlify.app/docs/guides/periodic-jobs.md): Durable schedules, singleton scheduler duties, missed ticks, and enqueue history.
- [Workflows](https://headgate.mintlify.app/docs/guides/workflows.md): Build durable fan-out and fan-in DAGs from ordinary pending jobs.
- [Encryption at rest](https://headgate.mintlify.app/docs/guides/encryption-at-rest.md): Encrypt job payloads before they reach a Headgate store and rotate keys safely.
- [Migrations](https://headgate.mintlify.app/docs/operations/migrations.md): Install, upgrade, validate, and adopt headgate schemas safely.
- [Testing](https://headgate.mintlify.app/docs/operations/testing.md): Use the in-memory runtime path or isolated live PostgreSQL, MySQL, and Redis resources.
- [OpenTelemetry](https://headgate.mintlify.app/docs/operations/observability.md): Connect Headgate producers and workers to an OpenTelemetry SDK, exporter, and trace context.
- [Connection budgets](https://headgate.mintlify.app/docs/operations/connection-budget.md): Size SQL pools so transactional handlers cannot starve lease renewal or control traffic.
- [Multiple installations](https://headgate.mintlify.app/docs/operations/multi-instance.md): Isolate jobs, policies, duties, schedules, workers, migrations, and wakeups.
- [Queue and runtime management](https://headgate.mintlify.app/docs/operations/queue-and-runtime-management.md): Pause intake, delete safely, retain audit data, and roll workers without losing control.
- [Operations console](https://headgate.mintlify.app/docs/operations/console.md): Embed the TanStack Start console in Go or Rust and mount it behind your authentication boundary.
- [Rust SDK overview](https://headgate.mintlify.app/docs/sdk/rust/overview.md): The facade crate, optional adapters, and the main producer/runtime types.
- [Rust tasks](https://headgate.mintlify.app/docs/sdk/rust/tasks.md): Derive typed JSON tasks and create durable envelopes.
- [Rust worker](https://headgate.mintlify.app/docs/sdk/rust/worker.md): Register handlers and run a capacity-aware worker with graceful shutdown.
- [Go SDK overview](https://headgate.mintlify.app/docs/sdk/go/overview.md): The core module, separate drivers, and main producer/runtime types.
- [Go tasks](https://headgate.mintlify.app/docs/sdk/go/tasks.md): Define typed JSON tasks and create durable envelopes.
- [Go runner](https://headgate.mintlify.app/docs/sdk/go/runner.md): Register typed handlers and run a capacity-aware worker.
- [PostgreSQL](https://headgate.mintlify.app/docs/backends/postgres.md): Reference backend with transactional application work and push notifications.
- [MySQL](https://headgate.mintlify.app/docs/backends/mysql.md): SQL transactions and inspection with a polling-first worker path.
- [Redis](https://headgate.mintlify.app/docs/backends/redis.md): Atomic Lua admission for Redis-native fleets.
- [Examples](https://headgate.mintlify.app/docs/examples/overview.md): Runnable Rust, Go, workflow, encryption, and console scenarios.
- [Basic worker](https://headgate.mintlify.app/docs/examples/basic.md): Run one typed job through admission, dispatch, and fenced completion in Rust or Go.
- [Workflow example](https://headgate.mintlify.app/docs/examples/workflow.md): Prepare and inspect the same fan-out/fan-in DAG in Rust and Go.
- [Encryption example](https://headgate.mintlify.app/docs/examples/encryption.md): Run the Rust and Go payload-encryption examples locally.
- [Console example](https://headgate.mintlify.app/docs/examples/ui-console.md): Run the embedded dashboard with realistic in-memory API data.
- [List queues with backlog derivatives](https://headgate.mintlify.app/api-reference/list-queues-with-backlog-derivatives.md)
- [Change a queue's fleet-wide selection weight.](https://headgate.mintlify.app/api-reference/change-a-queues-fleet-wide-selection-weight.md): Weight chooses BETWEEN queues inside the atomic admission gate. It never changes per-job priority ordering within a queue and is unrelated to a job envelope's rate-budget weight.
- [Delete an empty queue, or start an audited bounded deletion with force.](https://headgate.mintlify.app/api-reference/delete-an-empty-queue-or-start-an-audited-bounded-deletion-with-force.md)
- [Refresh bounded, explicitly-triggered queue memory samples.](https://headgate.mintlify.app/api-reference/refresh-bounded-explicitly-triggered-queue-memory-samples.md)
- [Bound exact unfinished jobs accepted for a queue.](https://headgate.mintlify.app/api-reference/bound-exact-unfinished-jobs-accepted-for-a-queue.md): Store-evaluated producer backpressure. The verdict and enqueue are one atomic unit and use maintained scalar counters, never an O(queue depth) count. A limit below current depth is valid and stops growth until drain catches up. Zero is an intake kill switch; it does not pause workers.
- [Disable enqueue backpressure for a queue.](https://headgate.mintlify.app/api-reference/disable-enqueue-backpressure-for-a-queue.md)
- [Post queues pause](https://headgate.mintlify.app/api-reference/post-queues-pause.md)
- [Post queues resume](https://headgate.mintlify.app/api-reference/post-queues-resume.md)
- [List jobs. ALWAYS paginated; `limit` is capped server-side.](https://headgate.mintlify.app/api-reference/list-jobs-always-paginated;-`limit`-is-capped-server-side.md)
- [Enqueue over HTTP.](https://headgate.mintlify.app/api-reference/enqueue-over-http.md): River supports polyglot insertion, and apalis-board's only mutation is enqueue — yet the first draft of this spec had no way to enqueue at all. This is how a Python or TypeScript service submits work without a native client, and how an operator re-submits a repaired payload. Requires Idempotency-Key…
- [Job detail — attempts timeline, errors, and per-attempt logs.](https://headgate.mintlify.app/api-reference/job-detail-—-attempts-timeline-errors-and-per-attempt-logs.md): River's detail view shows a timeline plus a per-attempt section with timing, the error, and execution logs (its `riverlog` middleware persists them to the job). Per-attempt logs are the difference between "it failed again" and knowing why, so the envelope carries them rather than sending the operato…
- [Delete jobs](https://headgate.mintlify.app/api-reference/delete-jobs.md)
- [Post jobs retry](https://headgate.mintlify.app/api-reference/post-jobs-retry.md)
- [Make an explicitly pending job available.](https://headgate.mintlify.app/api-reference/make-an-explicitly-pending-job-available.md)
- [Explicitly read versioned result bytes recorded by a successful job.](https://headgate.mintlify.app/api-reference/explicitly-read-versioned-result-bytes-recorded-by-a-successful-job.md): Result bytes are never included in job detail or list responses. They remain available only while the retained terminal job exists.
- [Explicitly read the latest versioned output persisted by a running attempt.](https://headgate.mintlify.app/api-reference/explicitly-read-the-latest-versioned-output-persisted-by-a-running-attempt.md): Output writes replace the previous value only under the current job lease and fence. `fence` identifies the attempt that authored the visible value and `updated_at_ms` is store-clock time. Ordinary job detail/list responses never include output bytes.
- [Read the latest operator-facing progress reported by a running attempt.](https://headgate.mintlify.app/api-reference/read-the-latest-operator-facing-progress-reported-by-a-running-attempt.md): Progress is an exact `current / total` pair with an optional short status message. Writes replace the previous report only under the current job lease and fence. The report may outlive its writing attempt; `fence` identifies that attempt and `updated_at_ms` is store-clock time. Ordinary job detail/l…
- [Cancel a RUNNING job. apalis dropped this capability between 0.7.4 and 1.0-rc.](https://headgate.mintlify.app/api-reference/cancel-a-running-job-apalis-dropped-this-capability-between-074-and-10-rc.md)
- [Post jobs reschedule](https://headgate.mintlify.app/api-reference/post-jobs-reschedule.md)
- [Edit-then-retry. Supplying a schema_version with no upcast path is a 422.](https://headgate.mintlify.app/api-reference/edit-then-retry-supplying-a-schema_version-with-no-upcast-path-is-a-422.md)
- [List live fleet-wide rate budgets.](https://headgate.mintlify.app/api-reference/list-live-fleet-wide-rate-budgets.md)
- [Change a fleet-wide rate limit at runtime.](https://headgate.mintlify.app/api-reference/change-a-fleet-wide-rate-limit-at-runtime.md): The flagship feature of this system is a shared rate limit, and the first version of this API could only display it. During an incident the operator's action is to raise, lower, or drain a limit — and if that requires a redeploy, the honest summary is that the feature does not exist operationally. R…
- [Change a global concurrency ceiling at runtime.](https://headgate.mintlify.app/api-reference/change-a-global-concurrency-ceiling-at-runtime.md)
- [List global concurrency ceilings and their saturation strategies.](https://headgate.mintlify.app/api-reference/list-global-concurrency-ceilings-and-their-saturation-strategies.md)
- [Show which partitions are being throttled and by how much.](https://headgate.mintlify.app/api-reference/show-which-partitions-are-being-throttled-and-by-how-much.md)
- [List fingerprints that have repeatedly crashed workers.](https://headgate.mintlify.app/api-reference/list-fingerprints-that-have-repeatedly-crashed-workers.md)
- [Release a quarantined fingerprint. Deliberate operator action.](https://headgate.mintlify.app/api-reference/release-a-quarantined-fingerprint-deliberate-operator-action.md)
- [Get workers](https://headgate.mintlify.app/api-reference/get-workers.md)
- [Show fleet capacity and queues with no live workers.](https://headgate.mintlify.app/api-reference/show-fleet-capacity-and-queues-with-no-live-workers.md): The registry answers "what is each worker doing"; this answers the fleet-level question an operator asks during an incident. A queue with a growing backlog and no consumer looks exactly like a slow queue until you know it is unserved, so `queues` lists every queue the store knows about UNIONED with…
- [Send control to a worker on its next heartbeat.](https://headgate.mintlify.app/api-reference/send-control-to-a-worker-on-its-next-heartbeat.md): Faktory's BEAT carries quiet/terminate; here it is one column on the worker row, read back by the heartbeat upsert. `quiet` pauses admission (in-flight work finishes), `resume` resumes, `terminate` shuts the worker down gracefully, and `resign` releases only this worker's singleton duty leases for i…
- [Stream control-plane events over one shared SSE subscription.](https://headgate.mintlify.app/api-reference/stream-control-plane-events-over-one-shared-sse-subscription.md)
- [Discover the active backend's supported capabilities.](https://headgate.mintlify.app/api-reference/discover-the-active-backends-supported-capabilities.md): Backends declare capabilities and a backend that cannot honor one does not have it. The UI needs that at runtime or it will render a "enqueue in transaction" affordance against Redis. apalis ships a `reenqueue_orphaned_after()` knob that is never called; this endpoint is the antidote to that class o…
- [Counts by state, for the state sidebar.](https://headgate.mintlify.app/api-reference/counts-by-state-for-the-state-sidebar.md): Both River UI and apalis-board lead with a state filter carrying live counts. Served from incrementally maintained aggregates and honest about it: `approximate` is set rather than paying for an exact scan.
- [Explain why a job is not running.](https://headgate.mintlify.app/api-reference/explain-why-a-job-is-not-running.md): When dequeue is a policy decision, "it is available but not running" has a specific, knowable cause. Without this, a job held back by a misconfigured rate class is indistinguishable from a slow worker -- which is the failure mode that makes operators distrust a limiter and turn it off.
- [Act on an explicit list of job IDs. The common case.](https://headgate.mintlify.app/api-reference/act-on-an-explicit-list-of-job-ids-the-common-case.md): River UI lets you tick 12 rows and hit Retry. The selector-based /jobs/bulk below cannot express that, and it was the only bulk route this spec had — selecting specific rows is what operators actually do, while filter-based bulk is the rarer and far more dangerous operation. Synchronous, because the…
- [Bulk retry/archive/delete/cancel. ASYNCHRONOUS by construction.](https://headgate.mintlify.app/api-reference/bulk-retryarchivedeletecancel-asynchronous-by-construction.md): asynq has RunAllScheduledTasks/DeleteAllRetryTasks/ArchiveAllPendingTasks and this spec originally had no equivalent — retrying 100k jobs one HTTP call at a time is not an API. A synchronous unbounded write is unsafe, so a bulk request returns an operation to poll rather than blocking. Requires Idem…
- [Progress of a bulk operation.](https://headgate.mintlify.app/api-reference/progress-of-a-bulk-operation.md)
- [Return queue history for backlog and throughput trends.](https://headgate.mintlify.app/api-reference/return-queue-history-for-backlog-and-throughput-trends.md): The UI leads with time-to-drain rather than depth. That is a rate, and a rate needs history — which the first draft of this spec had no way to serve. Backed by incrementally maintained counters, never by a queue-depth scan.
- [Registered periodic/cron entries.](https://headgate.mintlify.app/api-reference/registered-periodiccron-entries.md)
- [Idempotently create or update a schedule.](https://headgate.mintlify.app/api-reference/idempotently-create-or-update-a-schedule.md): Re-upserting with an unchanged spec keeps the schedule's phase (next_run is not reset); a changed spec re-anchors it. Specs are "@every:<ms>" (epoch-aligned) or a cron expression with five fields, or six fields when second-level precision is needed.
- [Delete periodic](https://headgate.mintlify.app/api-reference/delete-periodic.md)
- [Fire a periodic entry now, out of schedule.](https://headgate.mintlify.app/api-reference/fire-a-periodic-entry-now-out-of-schedule.md)
- [Newest durable scheduler enqueue attempts for one periodic entry.](https://headgate.mintlify.app/api-reference/newest-durable-scheduler-enqueue-attempts-for-one-periodic-entry.md): Bounded to the newest 100 records per schedule and ordered newest first. History survives schedule deletion. `enqueued` means the Store confirmed the exact job is durable and includes an idempotent same-ID replay; `deduplicated` is a unique key or changed-content ID collision. Reasons are stable cla…
- [Liveness. Never touches the store.](https://headgate.mintlify.app/api-reference/liveness-never-touches-the-store.md)
- [Readiness. Cheapest possible store round-trip, never a count.](https://headgate.mintlify.app/api-reference/readiness-cheapest-possible-store-round-trip-never-a-count.md)
- [Project map](https://headgate.mintlify.app/docs/reference/project-map.md): Every Rust crate, Go module, shared specification, and generated artifact.
- [Configuration](https://headgate.mintlify.app/docs/reference/configuration.md): Worker, producer, store, API, and console configuration boundaries.
- [Control API](https://headgate.mintlify.app/docs/reference/control-api.md): Operate queues, jobs, policies, workers, schedules, and workflows over one versioned contract.
- [Feature index](https://headgate.mintlify.app/docs/reference/feature-index.md): A public map of implemented capabilities and the guide that explains each area.
- [Capabilities](https://headgate.mintlify.app/docs/reference/capabilities.md): How headgate keeps backend and feature claims honest.
- [Verification](https://headgate.mintlify.app/docs/reference/verification.md): Run examples, unit tests, generated-artifact checks, and live conformance.
- [Documentation development](https://headgate.mintlify.app/docs/reference/documentation.md): Preview, validate, and deploy the Mintlify developer portal from the monorepo.

## OpenAPI Specs

- [headgate.openapi](/api/headgate.openapi.yaml)