Struct Client 

pub struct Client { /* private fields */ }

Reusable caller-side SDK client for an aion-server deployment.

Examples

use aion_client::{ClientAuth, ClientBuilder};

let client = ClientBuilder::new("https://aion.example.com")
    .with_auth(ClientAuth::bearer("secret-token"))
    .with_namespace("tenant-a")
    .build()
    .await?;

let shared = client.clone();

Implementations

impl Client

pub fn builder(endpoint: impl Into<String>) -> ClientBuilder

Creates a builder for an aion-server endpoint.

pub fn embedded(engine: Arc<Engine>) -> Self

Creates a client backed by an in-process embedded engine.

impl Client

pub async fn signal( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, name: impl Into<String>, payload: Payload, ) -> Result<(), ClientError>

Sends a signal to the latest run, or to run_id when supplied.

Errors

Returns ClientError when transport, server, or request conversion fails.

pub async fn signal_typed<T>( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, name: impl Into<String>, value: &T, ) -> Result<(), ClientError>

where T: Serialize + ?Sized,

Serializes value as JSON and sends it as a signal payload.

Errors

Returns ClientError::InvalidArgument when serialization fails, or the delegated signal error otherwise.

pub async fn query( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, name: impl Into<String>, args: Payload, deadline: Duration, ) -> Result<Payload, ClientError>

Queries the latest run, or run_id when supplied, with a local deadline.

args is the argument document handed to the workflow’s registered query handler. A query that takes no arguments passes Payload::json_null — the canonical “nothing supplied” document every carrier agrees on. The server refuses arguments that are not a well-formed JSON document with ClientError::InvalidArgument.

Errors

Returns ClientError::QueryTimeout when deadline elapses.

pub async fn query_typed<A, R>( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, name: impl Into<String>, args: &A, deadline: Duration, ) -> Result<R, ClientError>

where A: Serialize + ?Sized, R: DeserializeOwned,

Serializes args as JSON, queries a workflow, and deserializes the JSON result.

Errors

Returns ClientError::InvalidArgument when serialization or result decoding fails, or the delegated query error otherwise.

pub async fn cancel( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, reason: impl Into<String>, ) -> Result<(), ClientError>

Requests cancellation of the latest run, or run_id when supplied.

Success means the server accepted the cancellation request; it is not a confirmation that the workflow has reached a terminal cancelled state.

Errors

Returns ClientError when transport, server, or request conversion fails.

pub async fn retire_workloop( &self, workflow_id: &WorkflowId, reason: impl Into<String>, ) -> Result<String, ClientError>

Retires a WORKLOOP: the declared way to stop a loop, which is not failure.

Runs the loop’s declared retire body (when its deployed document declares one), records LoopRetired and the run’s terminal in one atomic batch, and withdraws the loop from the sweep set. Returns the reason recorded, so a caller that supplied none learns what the loop’s history now says.

There is deliberately no argument selecting whether the body runs: that is decided by the deployed document. A caller able to skip a declared cleanup is how a lease is lost.

Errors

Returns ClientError when transport or server fails — including the typed refusals for a workflow that is not a registered workloop, a run that already recorded a terminal, and a declared retire body that failed (in which case NO terminal is recorded and the loop stays registered).

pub async fn reopen( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, ) -> Result<ReopenOutcome, ClientError>

Reopens a terminal-reopenable run (Failed or Cancelled), re-driving it from where it left off. Targets the latest run, or run_id when supplied.

Returns the reopened run and its projected status (Running). A run that is not a reopenable terminal (not terminal, terminal for a non-reopenable reason, or already Running) returns ClientError::InvalidState; an absent workflow returns ClientError::NotFound.

Errors

Returns ClientError when transport, server, or response conversion fails.

pub async fn pause( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, reason: impl Into<String>, ) -> Result<PauseOutcome, ClientError>

Pauses a live Running run, durably holding new activity dispatch (#204). Targets the latest run, or run_id when supplied. Returns the run and its projected status (Paused). A run that is not Running returns ClientError::InvalidState; an absent workflow returns ClientError::NotFound.

Errors

Returns ClientError when transport, server, or response conversion fails.

pub async fn resume( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, ) -> Result<ResumeOutcome, ClientError>

Resumes a Paused run, releasing the dispatch hold (#204). Targets the latest run, or run_id when supplied. Returns the run and its projected status (Running). A run that is not Paused returns ClientError::InvalidState; an absent workflow returns ClientError::NotFound.

Errors

Returns ClientError when transport, server, or response conversion fails.

pub async fn list( &self, request: ListRequest, ) -> Result<WorkflowListPage, ClientError>

Lists one page of workflows in the client’s namespace.

The page carries the rows in the requested order, the cursor for the next page (absent on the last), and the total matching the filter.

Errors

Returns ClientError::InvalidArgument for a zero limit or a cursor minted under a different filter or sort, and ClientError when transport, server, or response conversion fails.

pub async fn describe( &self, workflow_id: &WorkflowId, run_id: Option<&RunId>, ) -> Result<WorkflowDescription, ClientError>

Describes the latest run, or run_id when supplied.

Errors

Returns ClientError when transport, server, or response conversion fails.

pub async fn read_history( &self, workflow_id: &WorkflowId, from_seq: Option<u64>, limit: Option<u32>, ) -> Result<HistoryPage, ClientError>

Reads one bounded page of workflow history.

Errors

Returns ClientError when transport, server, or event conversion fails.

pub fn subscribe_workflow(&self, workflow_id: &WorkflowId) -> EventStream

Subscribes to events for a workflow.

pub fn subscribe_workflow_from( &self, workflow_id: &WorkflowId, resume_from: NonZeroU64, ) -> EventStream

Subscribes to events for a workflow, attaching from an explicit per-workflow sequence cursor.

resume_from is the first sequence number wanted (resume_from_seq on the wire); 1 replays the workflow’s full recorded history before splicing into the live stream, gap-free and duplicate-free.

pub fn subscribe(&self, filter: WorkflowFilter) -> EventStream

Subscribes to events selected by the supplied workflow filter.

pub fn subscribe_firehose(&self) -> EventStream

Subscribes to every event visible to this client namespace.

impl Client

pub async fn start( &self, workflow_type: impl Into<String>, input: Payload, opts: StartOptions, ) -> Result<StartOutcome, ClientError>

Starts a workflow and returns the assigned workflow and run identifiers.

Returns a StartOutcome rather than a bare handle so an idempotent replay can report a display name it did NOT apply (#211) instead of dropping it silently — see StartOutcome::display_name_not_applied.

Errors

Returns ClientError when transport, server, or response conversion fails.

pub async fn start_typed<T>( &self, workflow_type: impl Into<String>, input: &T, opts: StartOptions, ) -> Result<StartOutcome, ClientError>

where T: Serialize + ?Sized,

Starts a workflow after serializing input as JSON.

Errors

Returns ClientError::InvalidArgument when serialization fails, or the delegated start error otherwise.

impl Client

pub async fn subscribe_transcript( &self, target: TranscriptTarget, ) -> Result<TranscriptStream, ClientError>

Opens one typed transcript WebSocket subscription.

Event frames and lag frames are decoded strictly. An unknown kind, unknown field, malformed body, terminal wire error, or abnormal socket close is returned as a named ClientError; no frame is discarded. A TranscriptStreamItem::Lagged item is recoverable per leg: callers should announce it and open a fresh subscription with their last applied store_seq as TranscriptTarget::after_seq.

Errors

Returns ClientError::InvalidArgument for a missing/invalid stream endpoint, ClientError::Unauthenticated for a rejected upgrade, or ClientError::Unavailable when the socket cannot be established.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.