Crate vox

Expand description

vox — type-safe RPC with channels, virtual connections, and automatic schema evolution.

§Defining a service

Services are ordinary Rust traits annotated with #[vox::service]:

#[vox::service]
trait Hello {
    async fn say_hello(&self) -> String;
}

The macro generates a HelloClient (typed caller), a HelloDispatcher (request router), and serialization glue. You implement the trait on a struct and hand it to a dispatcher.

§Connecting

connect() is the fastest path to calling a remote service:

let client: HelloClient = vox::connect("127.0.0.1:9000").await?;
let reply = client.say_hello().await?;

The address string selects the transport:

Scheme	Transport
`tcp://host:port` (or bare `host:port`)	TCP stream
`local://path`	Unix socket / Windows named pipe
`ws://host:port/path`	WebSocket

§Serving

serve() accepts connections in a loop:

vox::serve("0.0.0.0:9000", HelloDispatcher::new(HelloService)).await?;

For multi-service routing, use acceptor_fn():

vox::serve("0.0.0.0:9000", vox::acceptor_fn(|req, conn| {
    match req.service() {
        "Hello" => { conn.handle_with(HelloDispatcher::new(HelloService)); Ok(()) }
        "Chat" => { conn.handle_with(ChatDispatcher::new(ChatService)); Ok(()) }
        _ => Err(vec![]),
    }
})).await?;

§Generated clients

Generated clients expose public fields for connection lifecycle:

client.caller.closed().await;     // wait for disconnect
client.caller.is_connected();     // check liveness
client.session.as_ref();          // access session handle (virtual connections)
client.say_hello().await?;        // service method — no name clash

§Lower-level APIs

For advanced use (custom transports, in-memory testing, virtual connections), use the builder APIs directly:

initiator_on() / acceptor_on() — establish over a raw Link
memory_link_pair() — in-process link pair for testing
Driver — run inbound RPC on a connection handle
SessionHandle — open/close virtual connections
proxy_connections() — bridge two connection handles

Re-exports§

pub use facet;
pub use facet_reflect;
pub use vox_postcard;

Modules§

channel
hash
schema_deser
session
transport: Transport implementations re-exported by the facade crate.

Structs§

AcceptorFn: Wrapper that turns a closure into a ConnectionAcceptor.
Attachment: One transport attachment consumed by LinkSource::next_link.
BareConduit: Wraps a Link with postcard serialization. No reconnect, no reliability.
Caller: Concrete caller type wrapping a DriverCaller with optional middleware.
ChannelId: ID of a channel between two peers.
ChannelListener: A VoxListener backed by a channel.
ChannelListenerSender: Sender half of a ChannelListener.
ClientContext: Borrowed per-call context exposed to client middleware.
ClientLogging
ClientLoggingOptions
ClientRequest: Borrowed request wrapper exposed to client middleware.
ConnectBuilder
ConnectionHandle
ConnectionId: Connection ID identifying a virtual connection on a link.
ConnectionRequest: Metadata wrapper with typed getters for well-known vox-* keys.
ConnectionSettings: Per-connection limits advertised by a peer.
ConnectionState: Static data for one active connection.
Driver: Per-connection driver. Tracks in-flight request attempts, dispatches incoming requests to a Handler, and manages channel state / flow control.
DriverCaller: Allocates a request ID, registers a response slot, sends one request attempt through the connection, and awaits the corresponding response.
DriverChannelSink: Concrete ChannelSink backed by a ConnectionSender.
DriverReplySink: Concrete ReplySink implementation for the driver.
Extensions: Per-request type-indexed storage shared across middleware hooks and handlers.
HandshakeResult: Result of a completed CBOR handshake.
InMemoryOperationStore: Default in-memory operation store.
MemoryLink: In-process Link backed by tokio mpsc channels.
MemoryLinkRx: Receiving half of a MemoryLink.
MemoryLinkRxError: MemoryLink never fails on recv — the only “error” is channel closed (returns None).
MemoryLinkTx: Sending half of a MemoryLink.
MessageFamily: Type-level tag for Message as a MsgFamily.
MessagePlan: Pre-built translation plan for deserializing the Message wire type.
MetadataEntry: A single metadata entry with a key, value, and flags.
MetadataFlags: Metadata entry flags.
MethodDescriptor: Static descriptor for a single RPC method.
MethodId: A unique method identifier — hash of service name, method name, arg shapes, return shape
NoopClient: Liveness-only client for a connection root.
Peek: A read-only view into a value with runtime type information.
PendingConnection: A connection that has been opened but not yet accepted.
RequestCall
RequestContext: Borrowed per-request context exposed to opted-in Rust service handlers.
RequestResponse
ResponseParts: A decoded response value paired with response metadata.
RetryPolicy: Static retry policy for a method.
Rx: Receiver handle: “I receive”. The holder of an Rx<T> receives items of type T.
SchemaRecvTracker: Tracks schemas received from the remote peer on the current connection.
SealedResponse: A sealed response stored in the operation store.
SelfRef: A decoded value T that may borrow from its own backing storage.
ServerLogging
ServerLoggingOptions
ServerRequest: Middleware-facing view of one decoded server request.
ServerResponse: Middleware-facing view of one outbound server response.
ServerResponseContext: Owned context available when observing an outbound server response.
ServiceDescriptor: Static descriptor for a vox RPC service.
Session: Session state machine.
SessionAcceptorBuilder
SessionConfig: Shared configuration for all session builders.
SessionHandle: Cloneable handle for opening and closing virtual connections.
SessionInitiatorBuilder
SessionKeepaliveConfig: Session-level protocol keepalive configuration.
SessionRegistry
SessionSourceInitiatorBuilder
SessionTransportAcceptorBuilder
SessionTransportInitiatorBuilder
SingleAttachmentSource: A one-shot LinkSource backed by a single attachment.
SinkCall: Concrete Call implementation backed by a ReplySink.
SplitLink: Link wrapper that re-combines pre-split Tx/Rx halves into a Link.
StableConduit
Tx: Sender handle: “I send”. The holder of a Tx<T> sends items of type T.
WithTracker: Pairs a value with the SchemaRecvTracker that was active when the value was received. Used to thread per-message schema context through the caller API without storing trackers on long-lived structs.

Enums§

Backing
BareConduitError
ChannelRetryMode
ClientCallOutcome
HandshakeError
MetadataValue: Metadata value.
OperationState: State of an operation in the store.
Parity: Whether a peer will use odd or even IDs for requests and channels on a given connection.
Payload: A payload — arguments for a request, or return type for a response.
RxError: Error when receiving from an Rx.
ServeError: Error returned by super::serve().
ServerCallOutcome: Outcome observed by server middleware after handler dispatch.
ServerResponsePayload: Reflective view of one outbound server response payload.
SessionAcceptOutcome
SessionError: Errors that can occur during session establishment or operation.
SessionRole: Whether the session is acting as initiator or acceptor.
StableConduitError
TransportMode: Requested conduit mode for the transport prologue.
TxError: Error when sending on a Tx.
VoxError: Protocol-level error wrapper distinguishing application errors from vox infrastructure errors.

Constants§

OPERATION_ID_METADATA_KEY
RETRY_SUPPORT_METADATA_KEY
RETRY_SUPPORT_VERSION
VOX_SERVICE_METADATA_KEY: Well-known metadata key for service name routing.

Traits§

Call: Represents an in-progress API-level call as seen by a server handler.
ClientMiddleware
Conduit: Bidirectional typed transport. Wraps a Link and owns serialization.
ConduitAcceptor: Yields new conduits from inbound connections.
ConduitRx
ConduitTx: Sending half of a Conduit.
ConnectionAcceptor
DynConduitRx
DynConduitTx
ErasedHandler: Object-safe version of Handler<DriverReplySink>.
FromVoxSession: Trait for constructing a typed client from a vox session.
Handler: Type-erased handler for incoming service calls.
IntoConduit: Converts a value into a vox_types::Conduit.
Link: Bidirectional raw-bytes transport.
LinkRx: Receiving half of a Link.
LinkSource
LinkTx: Sending half of a Link.
MaybeSend: Marker trait that requires Send on native targets, nothing on wasm32.
MaybeSync: Marker trait that requires Sync on native targets, nothing on wasm32.
MsgFamily: Maps a lifetime to a concrete message type.
OperationStore: Operation state backing for exactly-once delivery across session resumption.
ReplySink: Sink for sending the terminal response for one request attempt.
ServerMiddleware: Observe inbound server requests before and after dispatch.
VoxListener: A listener that accepts incoming connections for serve_listener().

Functions§

accept_transport
acceptor_conduit
acceptor_fn: Create a ConnectionAcceptor from a closure.
acceptor_on
acceptor_on_link: Convenience: perform CBOR handshake as acceptor on a raw link, then return a builder with the conduit ready to go.
acceptor_transport
channel: Create a channel pair with shared state.
connect: Connect to a remote vox service, returning a typed client.
ensure_channel_retry_mode
handshake_as_acceptor: Perform the CBOR handshake as the acceptor.
handshake_as_initiator: Perform the CBOR handshake as the initiator.
initiate_transport
initiator
initiator_conduit
initiator_on
initiator_on_link: Convenience: perform CBOR handshake as initiator on a raw link, then return a builder with the conduit ready to go.
initiator_transport
memory_link_pair: Create a pair of connected MemoryLinks.
metadata_get_str: Look up a string metadata value by key.
metadata_get_u64: Look up a u64 metadata value by key.
prepare_acceptor_attachment: Prepare an acceptor-side attachment from an inbound link.
proxy_connections: Forward all request/channel traffic between two connections.
recv_client_hello: Receive a stable conduit ClientHello from a link.
serve: Serve a vox service by address string, accepting connections in a loop.
serve_listener: Serve a vox service on a pre-bound listener.
set_channel_binder: Set the thread-local channel binder, returning a guard that restores the previous value on drop.
single_attachment_source: Build a one-shot LinkSource from a prepared attachment.
single_link_source: Build a one-shot initiator-side LinkSource from a raw link.
with_channel_binder: Set the thread-local channel binder for the duration of f.

Type Aliases§

BoxMiddlewareFuture
BoxSessionFuture: A pinned, boxed session future. On non-WASM this is Send + 'static; on WASM it’s 'static only (no Send requirement).
Metadata: A list of metadata entries.

Attribute Macros§

service: Marks a trait as a vox RPC service and generates all service code.

Crate vox

Crate vox Copy item path

§Defining a service

§Connecting

§Serving

§Generated clients

§Lower-level APIs

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate vox