Skip to main content

ActivityWorker

Struct ActivityWorker 

Source
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

Source

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.

Source

pub fn register<A>(self, kind: impl Into<String>, activity: A) -> Self
where 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.

Source

pub fn with_worker_id(self, worker_id: impl Into<String>) -> Self

Override the worker identity sent on every call to the server.

Source

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).

Source

pub fn with_pools<I, S>(self, pools: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

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.

Source

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.

Source

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.

Source

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).

Source

pub fn worker_id(&self) -> &str

The identity this worker presents to the server.

Source

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.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<A, B, T> HttpServerConnExec<A, B> for T
where B: Body,

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more