ice-rpc 0.3.0

RPC over iceoryx2 shared memory: zero-copy header, rkyv payload, reconnection, discovery and more
Documentation

ice-rpc

High-performance RPC framework over iceoryx2 shared memory: zero-copy header, rkyv payload, in-place decoding when the payload is aligned.

From a single #[service]-annotated trait, the procedural macro generates the entire IPC code: client, server, proxy and lifecycle. Automatic reconnection after a provider crash (including SIGKILL) is provided by iceoryx2's native node monitoring: the OS releases the node's monitoring file lock when the process dies, and Node::list reports it as NodeState::Dead.

Features

  • Zero-copy IPC transport through iceoryx2 shared memory.
  • Code generation with #[service]: Request enum, Client, Server, Proxy and lifecycle.
  • Service discovery with a registry per node and dependency-aware topological initialization.
  • Crash detection & reconnection without heartbeat (native iceoryx2 node monitoring).
  • Three proxy modes: Provider, Consumer, ProviderNodeJs — the last one only when the nodejs feature is on.
  • Optional HTTP gateway (http plus one http-* adapter) built on trillium. http-tokio runs the server on the application's tokio runtime; the trillium-smol adapters run it on the executor trillium embeds, while the ice-rpc tasks stay on the executor of the selected mode. The feature also generates the HttpCallable implementation of every proxy, which is what keeps serde_json's conversion code out of a binary that never speaks HTTP.
  • Optional Node.js gateway (nodejs feature): #[service] also generates the rkyv ↔ serde_json::Value converters and the ProviderNodeJs mode the gateway_nodejs bridge calls. Off by default: a Rust-only deployment does not carry them, and they are about half of the generated code of a service.
  • Optional out-of-band monitoring (monitoring feature): #[service] also generates a {Service}Decoder (and Display on the request enum) so an external observer renders the observed payloads in clear text — with each type's Display implementation when it has one, with its Debug one otherwise. Off by default: a plain provider/consumer never calls that code.
  • Optional call tracing (tracing feature): the provider handler enters one tracing span per call, carrying the ids the caller propagated (correlation, trace, span, parent) plus the service and the method. The implementation's own tracing / log events land in that span without it writing a line — and the ids are the framework's own, so no OpenTelemetry stack is needed to obtain them. Off by default: a deployment that collects no spans pays neither the dependency nor the span. examples/tracing-demo.rs shows both halves across two hops.

Installation

[dependencies]

ice-rpc = "0.1"

# Required to derive Archive/Serialize/Deserialize on your own types:

rkyv = { version = "0.8", features = ["std"] }

# Required by the code generated by #[service] (it references `::log`):

log = "0.4"

The generated code references log directly (::log::…), and your own types derive rkyv traits, so both crates must be declared in your Cargo.toml.

Execution modes

The core names no runtime outside one façade (ice_rpc::rt). A façade cannot be runtime-neutral: a detached task has to be polled by someone, and "who polls" is the only thing a runtime is asked for here. So instead of one lowest-common-denominator executor, there is one full mode per host runtime, plus a fallback for a deployment that has none. "Full" means the process then runs one pool, not three.

ice-rpc = { version = "0.1" }                              # rt-threads (default)

ice-rpc = { version = "0.1", features = ["tokio"] }        # tokio only

ice-rpc = { version = "0.1", features = ["smol"] }         # smol only

Mode Task spawning, timers, blocking pool
rt-threads (default) an async-executor instance owned by the crate, run by available_parallelism() OS threads (ICE_RPC_THREADS overrides the count), futures-timer for sleep, blocking for the pool. No third-party runtime, and no I/O reactor: the core performs no async I/O.
tokio tokio::spawn, tokio::time::sleep, tokio's blocking pool
smol smol::spawn on smol's global executor — so the tasks share the pool of an application that already runs smol — smol::Timer, smol::unblock. Set SMOL_THREADS: that executor runs one thread by default.

The modes are exclusive: tokio + smol is a compile error. Enabling a mode does not remove the fallback from the dependency graph, because Cargo features are additive; a build that carries one runtime and nothing else says so:

ice-rpc = { version = "0.1", default-features = false, features = ["tokio"] }

The two long-lived IPC loops own a std::thread and block on an iceoryx2 WaitSet: they never go through a runtime. #[ice_rpc::main] drives main with ice_rpc::rt::block_on (no runtime required, any mode), #[ice_rpc::main(tokio)] builds a multi-thread tokio runtime, and any fn(Future) -> T can be given instead, e.g. #[ice_rpc::main(pollster::block_on)].

  • Service methods return ice_rpc::Observable<T, E>. Build one with the stream constructors of the Rx layer (of, from, throw_error, Subject); an advanced provider may use the raw channel via ice_rpc::gen::channel::<T, E>(capacity).
  • ice_rpc::rt exposes spawn, spawn_blocking, sleep, timeout, block_on, oneshot and CancellationToken.

Quick start

1. Define a service

use ice_rpc::{service, Observable};
use rkyv::{Archive, Deserialize, Serialize};

#[derive(Debug, Archive, Deserialize, Serialize)]
pub enum MyError {
    NotFound,
}

#[service("MyService")]
pub trait MyService: Send + Sync + 'static {
    async fn hello(&self, name: String) -> Observable<String, MyError>;
}

The macro generates MyServiceRequest, MyServiceClient, MyServiceServer, MyServiceProxy and MyServiceMode.

#[service] also accepts two optional parameters:

  • version (integer, default 1) — service interface version carried in the RPC header. An incompatible peer is rejected with RpcError::IncompatibleVersion;
  • group (string, default: the service name) — the channel shared with the other services of the same group: one request channel, one response channel and one dispatch thread, with the samples routed by the service id.
#[service("MyService", version = 1, group = "db")]
pub trait MyService: Send + Sync + 'static {
    async fn hello(&self, name: String) -> Observable<String, MyError>;
}

2. Start a provider

struct MyServiceImpl;

#[async_trait::async_trait]
impl MyService for MyServiceImpl {
    async fn hello(&self, name: String) -> Observable<String, MyError> {
        // Single response: this is just
        //     ice_rpc::of(format!("Hello {name} !"))
        // The raw channel stays available for long-lived push streams:
        let (tx, rx) = ice_rpc::gen::channel::<String, MyError>(1);
        ice_rpc::rt::spawn(async move {
            let _ = tx.send_complete_with(format!("Hello {} !", name)).await;
        });
        rx // no Result: a service returns the observable itself
    }
}

#[ice_rpc::main(tokio)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // `#[ice_rpc::main]` bootstraps ice-rpc (init + runtime) and shuts it down
    // on exit; `run_provider!` starts the services and waits for Ctrl+C.
    ice_rpc::run_provider!(
        MyServiceProxy::provide(MyServiceImpl),
    ).await
}

3. Call from a consumer

#[ice_rpc::main(tokio)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let proxy = ice_rpc::locator()
        .get::<MyServiceProxy>().await
        .expect("MyService unknown");

    let response: String = proxy.hello("Alice".into()).await.first_value().await?;
    println!("Response: {}", response);

    Ok(()) // `#[ice_rpc::main]` shuts ice-rpc down on exit
}

Core concepts

Concept Description
Observable<T, E> The composable stream, and the return type of service methods (no Result).
Event<T, E> Consumer-facing: Next(T) / Complete / Error(ObservableError<E>) where ObservableError is Business(E) or Technical(RpcError).
ObservableError<E> Terminal error of first_value(): Business(E) / Technical(RpcError) / Empty.
ServiceLocator Global registry, reached through locator(): locator().get::<MyProxy>().
ServiceInit The only trait a developer implements: dependencies() + the on_init hook.
Proxy Single entry point with 3 modes (Provider / Consumer / ProviderNodeJs).

Internal concepts (NodeId, WireEvent, the transport entry points, …) are exposed through the doc-hidden ice_rpc::gen module and used by ice-rpc-macros. The transport itself is a publish/subscribe pair of channels per service, correlated by a 16-byte id: see ice_rpc::transport.

Consumption

Consuming a stream is done natively on ice_rpc::Observable, whose operators are inherent methods (nothing to import); a call never fails at the call site — a connection/transport failure becomes an in-stream technical error:

let value = proxy.hello("Alice".into()).await.first_value().await?;
let all   = proxy.list().await.collect().await?; // Vec<T>
  • first_value() -> Result<T, ObservableError<E>> (Empty when the stream completes without a value);
  • collect() -> Result<Vec<T>, ObservableError<E>>;
  • the timeout and take_until operators bound the response wait and cancel a stream;
  • dropping a response stream whose call is still in flight cancels the call on the provider: the handler's future is dropped, so the work stops instead of running on for a caller that no longer listens. A call whose terminal event was read is released silently — nothing is sent. The implementation honours the signal by reading CallContext::cancellation(); examples/remote_cancel.rs shows both halves.

Error semantics

Errors travel inside the flux. Event::Error(ObservableError<E>) carries either a business error (Business(E)) or a technical one (Technical(RpcError)), so a single match detects a failure and the caller refines with the two variants.

RpcError classifies technical failures so callers can choose a policy (retry / fallback / log / fatal) via RpcError::is_retryable().

Every variant the enum declares, in declaration order:

Variant Meaning Retryable
SerializationError rkyv serialization/deserialization failure no
TransportError iceoryx2 I/O failure (loan, send, receive, port creation) yes
Timeout deadline exceeded yes
Cancelled cancelled by a global shutdown (SIGINT/SIGTERM or programmatic), a take_until token or a timeout; a remote Cancel published by a consumer that abandoned the call is handled by the provider and stays silent no
Internal unexpected internal error / invariant violation no
ProtocolMismatch the service already on the bus was created by another build, or by a process killed while it held it; no amount of retrying resolves it — see docs/wire-compat.md no

Four names that appeared in an earlier version of this table — DiscoveryError, ProviderUnavailable, ServiceNotFound, PayloadTooLarge — have no variant. Addressing is static: a provider that is not running is not a distinct error, it surfaces as a TransportError reading no subscriber connected once the provider wait (ICE_RPC_PROVIDER_WAIT_MS, 30 s) elapses, and an oversized payload as an iceoryx2 failure. A match on RpcError is exhaustive, so the compiler settles the question rather than this table.

Service initialization

Implement ServiceInit on your service type to declare dependencies and run an initialization hook:

#[async_trait::async_trait]
impl ice_rpc::ServiceInit for MyServiceImpl {
    fn dependencies(&self) -> Vec<&'static str> {
        vec!["ConfigService"]
    }

    async fn on_init(&self) -> bool {
        // Return false to trigger a retry.
        true
    }
}

For services that consume other services, register with provide_with_init. #[ice_rpc::main] bootstraps ice-rpc (init + runtime) and owns the clean shutdown, while run_provider! starts the services and waits for Ctrl+C:

ice_rpc::run_provider!(
    MyServiceProxy::provide_with_init(MyServiceImpl),
).await

Clean shutdown

#[ice_rpc::main] shuts ice-rpc down for you, including on an early return or ?:

#[ice_rpc::main(tokio)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let proxy = ice_rpc::locator().get::<MyServiceProxy>().await?;
    // ...
    Ok(())
}

For a hand-written main (one calling std::process::exit, the N-API gateway, tests), the lifecycle lives in ice_rpc::gen: let guard = ice_rpc::gen::init(); … guard.shutdown().await;.

HTTP gateway (optional)

Enable the http feature and one adapter, http-<mode>: trillium needs one, and letting the bare feature pick would contradict the mode chosen above.

ice-rpc = { version = "0.1", features = ["tokio", "http-tokio"] }

ice-rpc = { version = "0.1", features = ["smol", "http-smol"] }

ice-rpc = { version = "0.1", features = ["http-threads"] }   # the default mode

#[ice_rpc::main(tokio)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ice_rpc::start_http_gateway!(8080, MyServiceProxy).await;
    Ok(())
}

Services are then reachable through /{service}/{method}.

Configuration

The iceoryx2 root path is resolved in this order:

  1. ICE_RPC_ROOT_PATH environment variable (explicit override);
  2. %APPDATA%\ice-rpc\iceoryx2 on Windows, $XDG_DATA_HOME/ice-rpc/iceoryx2 (or ~/.local/share/ice-rpc/iceoryx2) on Unix;
  3. iceoryx2 default.

License

Apache-2.0