Starbase Worker Binary Responsibilities

The Worker binary handles all asynchronous, long-running background jobs:

• Build orchestration — Picks up build jobs from queue, calls Starforge (BuildService port) to submit build to Depot SaaS, relays build logs live to the dashboard and archives them to DO Spaces (one object per build, §16.6) as they arrive, polls for completion, updates desired state when image is ready
• Cluster provisioning — Provisions customer Talos clusters (droplets via DO API + cloud-init machine config; self-installs Cilium/CCM/CSI, Envoy Gateway, telemetry agents, Shuttle; registers cluster as active). MVP = manual talosctl; post-MVP automated by Shipyard
• Database provisioning — Creates DO Managed Postgres instances, configures connection pools, injects connection strings into desired state
• Billing aggregation — Monthly cron that materializes dedicated-DB cents from the FR-076 ledger, sums usage_totals, applies the plan credit, and generates Stripe invoices (Billing › Calculation · Stripe lifecycle); no proration machinery — plan changes are next-cycle, size changes accrue naturally via snapshots
• Cleanup jobs — Removes orphaned resources, suspends services for failed payments, deletes data for cancelled accounts after grace period

The job queue

A Postgres table at MVP (INSERT to enqueue, SKIP LOCKED to dequeue; RabbitMQ when volume justifies it), with real crash semantics:

• Lease: a Worker takes a job by setting locked_until (heartbeat-extended). If the Worker dies, the lease expires and the job becomes runnable again.
• Poison-job stop: attempts/max_attempts — exhaustion marks the job failed and fires a platform alert.
• Debounce: dedupe_key implements §16.11's push debounce — a new push cancels the queued job for the same service + branch.
• Resumable builds: once depot_build_id is in the payload, a retried job re-polls the running build instead of rebuilding.

Ops · job queue with leases · Starbase Postgres

jobs (
    id           UUID PRIMARY KEY,
    type         TEXT NOT NULL,         -- build | provision_db | provision_cluster | billing_cron | cleanup …
    payload      JSONB NOT NULL,
    status       TEXT NOT NULL DEFAULT 'queued'
                 CHECK (status IN ('queued','running','done','failed','cancelled')),
    run_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),   -- debounce: NOW() + 5s (§16.11)
    attempts     INT NOT NULL DEFAULT 0,
    max_attempts INT NOT NULL DEFAULT 3,
    locked_until TIMESTAMPTZ,           -- the lease; expired ⇒ re-runnable
    locked_by    TEXT,                  -- worker instance id
    dedupe_key   TEXT,                  -- e.g. "deploy:<service_id>:<branch>"
    last_error   TEXT,
    created_at   TIMESTAMPTZ DEFAULT NOW(),
    finished_at  TIMESTAMPTZ
);

-- dequeue:
--   SELECT * FROM jobs
--   WHERE status = 'queued' AND run_at <= now()
--      OR (status = 'running' AND locked_until < now())          -- expired lease: crash recovery
--   ORDER BY run_at FOR UPDATE SKIP LOCKED LIMIT 1;
--   → set status='running', attempts=attempts+1, locked_by, locked_until=now()+interval '2 min'

---

Cross-references

The sync counterpart → §13 · the build pipeline this binary drives → Starforge §16 · build logs (live relay + DO Spaces archive) → Starforge §16.6 · billing roll-up → Billing §36 · the desired state a finished build updates → §32.