pub struct ActivityWorker { /* private fields */ }Expand description
A durable worker that claims leased tasks from the rusty-agent-server task queue and executes them behind heartbeats.
This is the pull-based counterpart to crate::serve: instead of
answering one-shot /execute calls, it polls POST /tasks/claim, runs
the Activity registered for the claimed task’s kind, renews the
lease via a background heartbeat every lease / 3, and settles with
complete or fail (classified error). See the
module documentation for the full protocol and semantics.
Run several instances for parallelism; pool routing keeps them on disjoint queues.
Implementations§
Source§impl ActivityWorker
impl ActivityWorker
Sourcepub fn new(base_url: impl Into<String>) -> Self
pub fn new(base_url: impl Into<String>) -> Self
A worker claiming tasks from the rusty-agent-server at base_url (e.g.
"http://127.0.0.1:8080").
Register at least one Activity with ActivityWorker::register
before running. The worker id defaults to worker-{uuid}; set a
stable one with ActivityWorker::with_worker_id if operators
should recognize the worker across restarts.
Sourcepub fn register<A>(self, kind: impl Into<String>, activity: A) -> Selfwhere
A: Activity + 'static,
pub fn register<A>(self, kind: impl Into<String>, activity: A) -> Selfwhere
A: Activity + 'static,
Register the activity executed for tasks of kind.
Accepts any Activity implementation — including plain async
closures via the blanket impl. Registering the same kind twice
replaces the previous handler.
Sourcepub fn with_worker_id(self, worker_id: impl Into<String>) -> Self
pub fn with_worker_id(self, worker_id: impl Into<String>) -> Self
Override the worker identity sent on every call to the server.
Sourcepub fn with_lease(self, lease: Duration) -> Self
pub fn with_lease(self, lease: Duration) -> Self
Override the requested lease duration. Heartbeats renew the lease
from a background task every lease / 3 (clamped to ≥ 1 ms), so a
lease must comfortably outlive three heartbeat intervals of clock
drift and scheduling jitter — the DEFAULT_LEASE of 30 s is a good
floor for real deployments. The value is clamped to the server’s
accepted range (100 ms – 1 h).
Sourcepub fn with_pools<I, S>(self, pools: I) -> Self
pub fn with_pools<I, S>(self, pools: I) -> Self
Restrict claiming to the named pools ("pools": [...] on the claim
call). With no pools configured the claim omits the field and the
server’s default pool applies.
Sourcepub fn with_worker_version(self, version: impl Into<String>) -> Self
pub fn with_worker_version(self, version: impl Into<String>) -> Self
Advertise this worker’s version on every claim (R0.6 wave 3). The
server matches it exactly against a task’s worker_version
pin: tasks a run pinned to this version are leased to this worker
(and its version-mates) until the run finishes, so a mid-run deploy
never changes semantics under an in-flight execution; unpinned
tasks remain claimable regardless. With no version configured the
claim omits the field and the worker takes unpinned work only —
a worker that should serve pinned runs must advertise the version
it actually runs. Free-form string, but make it the real build
identity (crate version, image tag): a stale advertisement defeats
the pin’s purpose.
Sourcepub fn with_claim_backoff(self, base: Duration, max: Duration) -> Self
pub fn with_claim_backoff(self, base: Duration, max: Duration) -> Self
Override the claim-poll backoff: empty or failed polls wait roughly
base * 2^n (capped at max) until a task is claimed.
Sourcepub fn with_drain_grace(self, grace: Duration) -> Self
pub fn with_drain_grace(self, grace: Duration) -> Self
Override the drain grace (default DEFAULT_DRAIN_GRACE): how long
an in-flight activity may keep running after the shutdown token
fires before the worker aborts it and exits. An aborted attempt is
deliberately not settled — it returns to visibility at lease
expiry for another worker — so keep the grace under the lease:
beyond the lease the abort buys nothing (the server would reassign
at the same moment either way).
Sourcepub async fn run(self, shutdown: CancellationToken)
pub async fn run(self, shutdown: CancellationToken)
Run the claim → execute → settle loop until shutdown is cancelled,
then drain: stop claiming, settle any in-flight activity, and return.
Cancelling shutdown is the drain request — there is no separate
drain() because the token already is the control: idempotent
(cancelling twice changes nothing), race-safe (a cancel racing an
in-flight claim poll still wins, because the claim itself is
select!ed against the token), and shareable (every clone of the
token observes the same signal). Wire it to SIGTERM/SIGINT in the
embedding binary; see the crate’s activity_worker_demo example.
Drain semantics: claiming stops immediately; an in-flight activity
keeps heartbeating and settles normally, bounded by
ActivityWorker::with_drain_grace. An attempt still running when
the grace expires is aborted and deliberately not settled —
reporting it ErrorClass::Cancelled would kill the task
(cancelled is terminal: never retried, never dead-lettered), which
is exactly what a deployment must not do. Left unsettled, the
attempt returns to visibility at lease expiry and another worker
picks it up — the design’s “releases the rest, which return to
visibility for other workers”.
The loop never gives up on the server: claim/heartbeat/settle transport failures are logged and retried with backoff, because in a durable system the server coming back is the normal case.