Module source 

CommandSource — worker-only abstraction over how the worker receives the next command to run.

This module is worker-only. The CLI does NOT consume types from here — its local-mode runner is a tree walker that doesn’t need a pull-model command source. See § H.10 of the global hybrid cloud blueprint for the architectural rationale.

The worker (R-1.2 PR-2d-2) implements a NATS-backed CommandSource that pulls from a durable consumer and uses the control-plane HTTP API to claim individual commands. Future worker implementations (e.g. an HTTP-poll source for serverless deployments under § H.2’s Cloud Run compute substrate) implement the same trait.

R-1.2 PR-2d-1 — trait redesign

The 0.2.x version of this module had a thin next() -> Result<Option<Command>> trait. The worker’s real NATS pull loop turned out to need:

1. Per-pull ack/nack lifecycle distinct from next() so the caller can ack BEFORE executing the command (NATS redelivery semantics) or nack on transient claim failures.
2. A 4-state outcome because claiming a command can succeed (Claimed), be raced by another worker (AlreadyClaimed), fail transiently and warrant redelivery (RetryLater), or fail terminally (Failed) — each maps to a different follow-up.
3. A richer Command shape with render_context (variables rendered against the merged step context) and attempts (for backoff decisions in the dispatcher).

The 0.3.0 redesign captures all three. The breaking change is safe because no production consumer exists yet — noetl-worker 1.1.2 doesn’t import this module; PR-2d-2 will be its first adoption.

Structs

Command

One command the worker will dispatch to a tool.

Pulled

One pulled item from the source — a claim outcome plus the opaque handle the caller passes back to ack or nack.

Enums

ClaimOutcome

Outcome of an attempt to claim a command from the source.

Traits

CommandSource

Pull-model command source.