Struct Worker 

pub struct Worker { /* private fields */ }

Runs registered Flow Step and RPC handlers through outbound task streams.

A Worker owns an internal Tokio runtime and is one-shot. Self::start negotiates the Server protocol, synchronizes Attribute indexes, then blocks while serving. Call Self::stop from another thread to request graceful shutdown. The Worker runs at most the configured number of handlers concurrently and needs only an outbound connection to Dex. See crate::PullWorkerOptions.

Examples

use dex_sdk::{BlobCache, BlobCacheConfig, Registry, Worker, WorkerOptions};
use std::sync::Arc;

let cache = Arc::new(BlobCache::open(BlobCacheConfig::new(
    "/tmp/dex-blobs", 64 * 1024 * 1024, 0,
)?)?);
let worker = Worker::try_new(Registry::new(), cache, WorkerOptions::new())?;
worker.start()?;

Implementations

impl Worker

pub fn new( registry: Registry, blob_cache: Arc<BlobCache>, options: WorkerOptions, ) -> Self

Creates a Worker or panics when options or runtime initialization are invalid.

Panics

Panics for invalid pull options, zero index-sync timeout, invalid Dex endpoint, or Tokio runtime creation failure. Invalid TLS settings also panic. Prefer Self::try_new for recoverable startup.

pub fn try_new( registry: Registry, blob_cache: Arc<BlobCache>, options: WorkerOptions, ) -> SdkResult<Self>

Creates a one-shot pull Worker with a lazy outbound connection.

Errors

Returns SdkError::FlowDefinition for invalid Worker options, or Service for runtime and endpoint initialization failures. Invalid TLS options return SdkError::InvalidArgument. The connection is lazy; certificate and handshake failures occur during Self::start.

pub fn start(&self) -> SdkResult<()>

Negotiates protocol, synchronizes Attribute indexes, and serves until stopped or failed.

Changed in 1.23.0: busy streams send transport keepalives during handler execution. These preserve the connection; handlers must still record progress within their heartbeat timeout.

Stream errors are logged and retried. After Self::stop, this method drains active handlers for the configured timeout, cancels any remaining handlers, and waits for them to return. Call this method only once, on a dedicated thread.

Errors

Returns FlowDefinition if called more than once, or Service for index synchronization, timeout, incompatible Server protocol, and server failures. An unreachable Server returns the Service error carrying the original gRPC status code, such as UNAVAILABLE. Startup also fails with a Service error whose code is FAILED_PRECONDITION when max_concurrent_tasks exceeds the Server setting matching.maxConcurrentTasksCap. The first registered stream reports that setting; the Worker then half-closes its streams. Returns a service error exposing SdkError::pull_registration_error after draining when permanent-rejection shutdown is enabled.

pub async fn wait_pull_registered(&self) -> SdkResult<()>

Waits until a Step-and-RPC slot and, when reserved, an RPC-only slot have registered once.

Safe before or after Self::start and for concurrent callers. Start the Worker on a dedicated thread. Drop this future to cancel the wait, or use tokio::time::timeout. Completion remains latched after shutdown; use Self::pull_registration_state for probes.

Errors

Returns a service error exposing SdkError::pull_registration_error for a permanent rejection without another registered stream before readiness. Returns the startup error if startup fails, or InvalidArgument for shutdown before readiness. When max_concurrent_tasks exceeds the Server setting matching.maxConcurrentTasksCap, readiness is never reported and this returns the same FAILED_PRECONDITION Service error as Self::start.

tokio::time::timeout(std::time::Duration::from_secs(10), worker.wait_pull_registered()).await??;
assert!(worker.pull_registration_state().is_ready);

pub fn pull_reserved_rpc_declines(&self) -> u64

👎Deprecated:

reserved slots never decline for capacity; this counter is always zero

Returns zero for the obsolete reserved-RPC decline counter.

Deprecated: the Server assigns work to reserved slots, and the Worker never declines tasks for capacity. This method remains callable after shutdown and is safe for concurrent reads. Remove calls to it; existing callers keep compiling with a deprecation warning.

#[expect(deprecated, reason = "the counter is kept for source compatibility")]
let declines: u64 = worker.pull_reserved_rpc_declines();
assert_eq!(declines, 0);

pub fn pull_registration_state(&self) -> PullRegistrationState

Returns an independent snapshot of current pull slot-kind registrations.

Readiness latches after each required slot kind registers once. Only a permanent rejection with no registered stream makes it false. Successful registration clears that slot kind’s error. Transient disconnects and Stop do not clear readiness. See Self::wait_pull_registered for a startup and probe example.

pub fn stop(&self)

Requests shutdown of a running Worker and returns immediately.

Calling stop before or after start is safe; Self::start observes the shutdown signal. No new handler starts after this request. Idle streams half-close immediately; busy streams finish their handler and send its final output before half-closing. Task frames arriving after Stop are dropped without invoking a handler, including after half-close. Streams keep reading until the Server ends them or the drain deadline expires. At that deadline, busy streams whose final output is not yet queued are reset and their handlers are cancelled; Self::start waits for their return. Dex treats a task on a reset stream as one that may have run. A busy stream whose final output is already queued still sends it and half-closes. A stream whose last final output Dex has not yet acknowledged with a new task waits up to five seconds past the drain deadline for the Server to end it, even after its handler has returned. Self::start can therefore return up to five seconds after the drain deadline. Every other stream still open at the deadline, including one blocked on a send, is reset. Stop is idempotent. Changed in 1.35.0: tasks received after Stop are returned without running or consuming a retry. Draining preserves final output before the stream closes. Use this method for graceful shutdown and join the thread running Self::start before releasing resources.