ice-rpc 0.2.0

Zero-copy RPC over iceoryx2 with automatic reconnection, service discovery and HTTP gateway
Documentation

ice-rpc

High-performance, zero-copy RPC framework over iceoryx2 shared memory.

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 a cross-platform kernel watchdog (Windows Mutex / Unix flock).

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 (kernel named lock).
  • Three proxy modes: Provider, Consumer, ProviderNodeJs.
  • Optional HTTP gateway (http feature) built on trillium (runtime-agnostic, no tokio required).
  • Optional consumer-side TTL cache (cache feature) via the #[cache(ttl = "60s")] method attribute.

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.

Runtime-agnostic

The ice-rpc core has no dependency on a specific async runtime. By default, the execution facade (ice_rpc::rt) is backed by async-global-executor (task spawning), std::thread (blocking IPC threads) and futures-timer (timers), so it runs on any executor: tokio, smol, or even pollster.

Optional Cargo features switch the facade to a dedicated runtime:

ice-rpc = { version = "0.1" }                           # agnostic (default)
ice-rpc = { version = "0.1", features = ["smol"] }      # smol (native facade)
ice-rpc = { version = "0.1", features = ["tokio"] }     # tokio facade
ice-rpc = { version = "0.1", features = ["http"] }      # trillium gateway (runtime-agnostic)
ice-rpc = { version = "0.1", features = ["cache"] }     # consumer-side TTL cache
ice-rpc = { version = "0.1", features = ["full"] }      # http + cache + tokio

full is a convenience feature that enables http, cache and tokio in one shot.

  • Service methods return ice_rpc::Stream<T, E> — an async_channel::Receiver. Create the stream with ice_rpc::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 three optional parameters:

  • allow_large_payload (bool, default false) — creates the second shared-memory segment (_large) for payloads above LARGE_PAYLOAD_THRESHOLD;
  • default_size_message (integer, in KiB) — initial slice size of the _default shared-memory segment publisher;
  • version (integer, default 1) — service interface version carried in the RPC header. An incompatible peer is rejected with RpcError::IncompatibleVersion.
#[service("MyService", allow_large_payload = true, default_size_message = 8, version = 1)]
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> {
        let (tx, rx) = ice_rpc::channel::<String, MyError>(2);
        ice_rpc::rt::spawn(async move {
            let _ = tx.send(ice_rpc::Event::Next(format!("Hello {} !", name))).await;
            let _ = tx.send(ice_rpc::Event::Complete).await;
        });
        Ok(rx)
    }
}

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

3. Call from a consumer

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    ice_rpc::init();
    let guard = ice_rpc::ShutdownGuard::new();

    let proxy = ice_rpc::locator()
        .get::<MyServiceProxy>().await
        .expect("MyService unknown");

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

    guard.shutdown().await;
    Ok(())
}

Core concepts

Concept Description
NodeId Process identity (PID), unique across the machine.
Observable<T, E> RPC stream: Result<Receiver<Event<T, E>>, RpcError>.
Event<T, E> Next(T) / Complete / Error(E) / RpcError(RpcError).
ConnectionState Client connection state machine (Unknown / Discovering / Ready / Dead / Reconnecting).
ServiceLocator Global registry, dependency resolution and initialization.
NodeHub Central IPC hub: publishers, request/response handlers, dispatch loop.
Proxy Single entry point with 3 modes (Provider / Consumer / ProviderNodeJs).

Consumption helpers

  • take_one!(observable) and take_one_or_cancel!(observable, cancel) extract the first value of a stream.
  • #[timeout("30s")] on a method sets the service-location timeout (default RPC_CALL_TIMEOUT_SECS = 30s).

Error semantics

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

Variant Meaning Retryable
TransportError iceoryx2 I/O failure yes
DiscoveryError discovery cycle failure yes
ProviderUnavailable provider node unreachable yes
Timeout deadline exceeded yes
ServiceNotFound service not registered on any node no
Cancelled global shutdown (Ctrl+C) no
SerializationError rkyv serialization/deserialization failure no
PayloadTooLarge payload above the shared-memory limit no
ProtocolMismatch incompatible protocol/service version no
Internal unexpected internal error no

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, initialize with init() and register with provide_with_init:

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

Clean shutdown

Use the RAII ShutdownGuard to cancel the IPC threads on drop and, on success path, wait for their termination:

let guard = ice_rpc::ShutdownGuard::new();
// ... use ice-rpc ...
guard.shutdown().await; // waits for the IPC threads and releases the iceoryx2 node

Consumer-side cache (optional)

Enable the cache feature:

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

Then annotate a service method with #[cache(ttl = "60s")]. On the consumer side, the generated client caches successful Next values keyed by the serialized arguments, so subsequent identical calls skip the IPC round-trip until the TTL expires.

use ice_rpc::{cache, service, Observable};

#[service("MyService")]
pub trait MyService: Send + Sync + 'static {
    #[cache(ttl = "60s", max_entries = 128)]
    async fn get(&self, key: String) -> Observable<String, MyError>;
}
  • ttl — lifetime of a cached entry (e.g. "60s", "5min");
  • max_entries — optional maximum number of entries (default 1024).

The cache is a local, thread-safe RpcCache (ice_rpc::RpcCache) with lazy expiry; it is intended for idempotent reads.

HTTP gateway (optional)

Enable the http feature:

ice-rpc = { version = "0.1", features = ["http"] }
ice_rpc::init();
ice_rpc::start_http_gateway!(8080, MyServiceProxy).await;

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