Skip to content

worker

Start a scan worker. A worker subscribes to the NATS JetStream job queue, claims scheduled tasks, and runs the analysis pipeline for each one.

worker
  Start a scan worker

You can run any number of workers; they form a NATS queue group (crap-workers) and share the load.

What it does

  1. Connect to NATS (nats_url) and Postgres (dsn) and run migrations.
  2. Subscribe to the job queue and wait for messages.
  3. For each job: claim the task (only a queued task can be claimed), acquire the Postgres repo lock, ensure the repo is cloned in the shared cache, run go test -coverprofile (skipped on a coverage-profile hit), run go-crap scan, and save the result.
  4. Publish status events to the crap_events stream and release the lock.

Heartbeat and status

Each worker publishes a heartbeat every 5 seconds with its ID, hostname, PID, CPU count, and status:

Status Meaning
ready idle and consuming
busy running a scan
paused paused (commands stop)
offline published once on shutdown

While a scan runs, the worker also heartbeats the task's updated_at so the reconciler does not expire a legitimately long scan as a dead worker.

Pause / unpause

Workers receive per-worker commands on crap.worker.cmd.<workerID>. Pausing one worker stops only that worker — the others keep consuming.

# via the HTTP API (see HTTP API reference)
curl -X POST http://localhost:8080/api/workers/<id>/pause
curl -X POST http://localhost:8080/api/workers/<id>/unpause

On pause the worker stops consuming; on unpause it re-subscribes to the queue and resumes.

Example

export GCTD_NATS_URL=nats://localhost:4222
export GCTD_DSN=postgres://postgres:postgres@localhost:5432/crap_tracker?sslmode=disable
export GCTD_CACHE_DIRECTORY=./cache
./go-crap-tracker worker
  • Task Lifecycle — the states a task moves through while a worker handles it.
  • Repo Cache — the shared cache and Postgres locking workers rely on.