Task module

Source: modules/task/.

At a glance


CLI	`shc task`
Subcommands	2
HTTP endpoints	see the route reference
Events emitted	—
Error codes	see the error code reference
Service classes	—
Cross-module deps	—

Source layout

modules/task/
├── command.go
├── router.go
├── models.go
└── commands/

CLI entry points

shc task — inspect background tasks and workers
- CLI reference

HTTP API

Routes are listed in the generated route reference; request/response notes live in the API reference.

Responsibilities

The task module is read-only visibility into SHC’s async task queue. It does not own queue semantics itself — those live in subsystems/impl/queue.go (plus task_publisher.go / task_resolver.go alongside it), TaskModel, and WorkerModel in the shared models package. This module’s router and CLI simply query those tables and present them in two views:

GET /api/resource/Task (ListTasks) — enumerate queued, in-flight, completed, or dead tasks, optionally filtered by status, the node of the worker that claimed them, dead=true for failures/timeouts, and a limit. Only tasks claimed by a worker show a node; unclaimed-pending tasks have no node association.
GET /api/resource/Worker (ListWorkers) — enumerate the distributed workers that pull tasks, their last heartbeat, and their node.

The CLI (shc task ls, shc task workers) is a thin formatter over the same endpoints. Humans use shc task ls --node <id> during operations to see “what is this node actually doing right now?”

What the task module does not own: enqueuing tasks, claiming them, running them, retry logic, dead-letter handling, or worker liveness heuristics — all of that lives in subsystems/impl/queue.go and the daemon subsystem that runs the workers. If you need to change behavior of the queue, that’s not here. If you need to change presentation, it is.

Queue model

SHC follows a leader schedules, all workers execute model:

Leader node — only the current leader schedules and enqueues cron-driven tasks.
Worker nodes — any available worker (the leader included) can claim and execute a pending task.
Hot reload — changes to database-backed schedules are reloaded immediately by the leader; no restart required.

Triggers and registration

Trigger	Registration	Description
Event	`events.Register("event.code", ...)`	Success events (V- and A-prefixed)
Error	`events.RegisterError("error.code", ...)`	Specific error codes / failure events
Warning	`events.RegisterWarning("code", ...)`	System warnings
Internal cron	`schedule.RegisterInternal(...)`	Hardcoded system tasks (e.g., cleanup)
Schedule	(database row)	User-defined periodic tasks via `shc schedule add`

Internal scheduled handlers are strictly internal and separate from user-defined database schedules. Duplicate schedules between internal tasks and user schedules are allowed and treated as distinct tasks.

Manual enqueue

Programmatic invocation:

queue.Enqueue(ctx, "task_name", data)

See the Pattern 6: Task System section of the communication-patterns doc for the full enqueue/dispatch flow.