Crate caravan_rpc 

Runtime SDK for the Caravan application-definition compiler.

A user declares a seam-interface trait, marks it with wagon, registers a concrete implementation via provide, and dispatches through client. Dispatch mode (inproc / http / lambda) is read from the CARAVAN_RPC_PEERS env var at the call site; when the env var is unset, client::<dyn I>() returns the registered Arc<dyn I> directly with no overhead (no-config inertness).

See https://github.com/paulxiep/caravan/blob/main/docs/poc_rpc_sdk.md for the wire contract and per-language surface.

M2 status

0.1.0 ships the runtime building blocks: codec (codec), peer-table parsing (peers), error types (errors), HTTP client dispatchers (dispatch, behind the client feature). The proc-macro that turns #[wagon] into server + client adapters lands in M2 Session 3+. Until then, client::<dyn T>() returns the inproc-registered impl regardless of peer-table mode — switching to HTTP happens only after the proc-macro wires per-trait HTTP adapter discovery.

Lambda mode panics with an M7 pointer (forward-compat marker).

use std::sync::Arc;
use caravan_rpc::{wagon, provide, client};

#[wagon]
pub trait Embedder: Send + Sync {
    fn embed(&self, text: &str) -> Vec<f32>;
}

struct InMemoryEmbedder;
impl Embedder for InMemoryEmbedder {
    fn embed(&self, _text: &str) -> Vec<f32> { vec![0.0; 8] }
}

// startup
provide::<dyn Embedder>(Arc::new(InMemoryEmbedder));

// call site
let v = client::<dyn Embedder>().embed("hello");
assert_eq!(v.len(), 8);

Re-exports

pub use errors::RpcError;

pub use errors::RpcRemoteError;

pub use errors::RpcTransportError;

pub use peers::PeerEntry;

pub use peers::peer_for;

pub use resources::BlobError;

pub use resources::BlobStore;

pub use resources::LocalFsBlobStore;

pub use resources::MessageQueue;

pub use resources::QueueError;

pub use resources::auto_register_resources;

Modules

codec

Wire-format codec for Caravan RPC v1.

dispatch

HTTP client dispatchers used by macro-generated client adapters.

errors

Caravan RPC error types.

peers

Parse and look up the CARAVAN_RPC_PEERS env var.

resources

Caravan-shipped resource seams + concrete impls.

server

Axum-based HTTP server for hosting @wagon impls as peer services.

Structs

HttpAdapterFactory

Factory entry for a #[wagon] trait’s remote client adapter.

HttpServerFactory

Factory entry for a #[wagon] trait’s server-side router. Mirrors HttpAdapterFactory but for the server direction.

Constants

VERSION

Version of this crate.

Functions

client

Return an Arc<dyn T> to dispatch through.

is_provided

Whether an impl has been registered for trait object T.

provide

Register impl_ as the inproc provider for trait object T.

run_or_serve

Run the user’s main, OR start a peer HTTP server, based on the CARAVAN_RPC_ROLE env var.

try_client

Return an Arc<dyn T> to dispatch through, or None if no impl is available (neither locally provide()-ed nor wired via HTTP through #[wagon]’s inventory factory).

Attribute Macros

wagon

Mark a trait as a Caravan RPC seam interface.