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.
ChannelDebugContext
ChannelDebugSnapshot
ChannelEventContext
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
ConnectionDebugSnapshot
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.
Fd: A file descriptor that can be sent across a vox connection.
FdAdapter: Adapter that bridges Fd through the opaque field contract (modelled on PayloadAdapter in message.rs).
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.
RequestDebugSnapshot
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.
ServeBuilder
ServeListenerBuilder
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: One-shot link source: hands out its single attachment, then errors on every subsequent call.
SinkCall: Concrete Call implementation backed by a ReplySink.
SourceLocation
TracingObserver
Tx: Sender handle: “I send”. The holder of a Tx<T> sends items of type T.
VoxDebugSnapshot
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
ChannelCloseReason
ChannelEvent
ChannelReceiverState
ChannelResetReason
ChannelRetryMode
ChannelSendOutcome
ChannelTrySendOutcome
ClientCallOutcome
ConnectionCloseReason
ConnectionDebugState
DecodeErrorKind
DriverEvent
DriverTaskStatus
EncodeErrorKind
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.
ProtocolErrorKind
RequestDebugState
RpcEvent
RpcOutcome
RpcSide
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.
TransportEvent
TransportMode: Requested conduit mode for the transport prologue.
TrySendError: Error returned by Tx::try_send.
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
SCM_MAX_FD: Maximum number of descriptors carried in a single SCM_RIGHTS control message. The kernel hard-caps this (SCM_MAX_FD); we surface a clean error rather than silently chunking across sendmsg calls.
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: Source of transport links. With reconnect machinery removed there’s only ever one call to next_link per session, but the trait remains so existing code paths don’t have to special-case the single-link case.
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 within a single process.
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().
VoxObserver

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.
collect_fds: Install an empty fd collector for the duration of f, returning what f produced together with the descriptors it gathered.
connect: Connect to a remote vox service, returning a typed client.
ensure_channel_retry_mode
frame_fds_len: Number of descriptors in a frame’s fd set (0 off-Unix).
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.
provide_fds: Provide the descriptors received with a frame for the duration of f (typed payload decoding). Each Fd decoded inside claims one by index.
proxy_connections: Forward all request/channel traffic between two connections.
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
single_link_source
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).
FrameFds: The descriptors carried with one frame. Vec<OwnedFd> on Unix; () elsewhere (no transport can pass descriptors off-Unix).
Metadata: A list of metadata entries.
VoxObserverHandle

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