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 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, filter: &WorkflowFilter, page: ListPage, ) -> Result<Vec<WorkflowSummary>, ClientError>

Lists workflows matching a filter.

Errors

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