Struct Client 

pub struct Client { /* private fields */ }

One semantic session: handshake, snapshot publishing, render markers.

The client owns the revision counter; an adapter never picks its own.

Implementations

impl Client

pub fn new( endpoint: impl Into<String>, token: impl Into<String>, options: Options, ) -> Self

Build a client for an explicit endpoint and token.

pub fn from_env(options: Options) -> Option<Self>

Build a client from TERMWRIGHT_*, or None when not instrumented.

This is the dormant rule in one function: no endpoint or no token means no client, and the caller must then open nothing and emit nothing.

pub fn from_values( endpoint: Option<&str>, token: Option<&str>, options: Options, ) -> Option<Self>

Build a client from explicit endpoint and token values, applying the same dormant rule as Client::from_env.

Use this when the process manages its own environment, or in tests. A missing or empty endpoint or token yields None.

pub fn connect(&mut self, timeout: Duration) -> Result<(), Error>

Connect, send hello, and wait for hello-ack.

Errors

Returns Error::Io when the endpoint is unreachable and Error::HandshakeTimeout when the driver does not answer. A failed side-channel must not take the application down: callers are expected to carry on rendering.

pub fn connected(&self) -> bool

Whether the handshake completed and the link is still up.

pub fn session_id(&self) -> Option<&str>

The id the driver assigned, or None before the handshake.

pub fn revision(&self) -> i64

The last revision this client published.

pub fn log_budget(&self) -> Option<LogBudget>

The log-channel allowance the driver granted, or None when logs are disabled — which is the case unless the adapter announced logs.

pub fn limits(&self) -> &Limits

The ceilings in force, as negotiated by hello-ack.

pub fn close(&mut self)

Drop the session. The application keeps running.

pub fn fail( &mut self, code: &str, message: impl Into<String>, ) -> Result<(), Error>

Send a typed fatal producer-contract error and close the channel.

pub fn publish( &mut self, snapshot: &mut Snapshot, ) -> Result<Option<String>, Error>

Publish a snapshot for the next revision and return its marker.

Write the marker to stdout after the render’s last byte: it commits the bytes that precede it. session_id and revision on the snapshot are overwritten with the session’s own.

Returns Ok(None) when there is no live session or the driver did not ask for markers, so a dormant app takes no branch.

Errors

Returns Error::Validation if the snapshot is invalid — that is an adapter bug, so it is loud rather than silent — or Error::Io if the channel broke.

pub fn snapshots_sent(&self) -> u64

Whole trees this client has published.

pub fn logs_dropped(&self) -> u64

Records this adapter dropped locally, for being over budget or over a limit. Each one left a gap in the sequence.

pub fn log(&mut self, record: LogRecord) -> bool

Forward one application log record, if the driver asked for logs.

Returns whether the record went out. A record is dropped when the session is not live, when the driver granted no budget, when this adapter is over its rate, or when the record breaks a limit.

Every attempt consumes a sequence number, dropped or not: the gap left in seq is precisely how the driver learns records were lost here rather than in transit.

seq is assigned here whatever the caller set, because the adapter is the only authority on it: the channel is open to several publishers, and two of them can pick the same number in good faith. A caller’s own number is kept as the origin.seq attribute, which is a diagnostic rather than a promise — it is dropped rather than allowed to push the record over a limit.

pub fn log_message( &mut self, level: LogLevel, message: impl Into<String>, ) -> bool

Convenience for the common call: a level and a message.

pub fn poll(&mut self) -> Result<(), Error>

Read and answer whatever the driver has sent, without blocking.

Call it on every render tick, or whenever convenient, to process driver control messages without blocking.

Errors

Returns Error::Io if the channel broke, or Error::Parse if the driver sent something the contract forbids.

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.