Crate ergo_aeron_cluster

Expand description

§ergo-aeron-cluster

Experimental Rust client for Aeron Cluster on rusteron_client 0.2 (latest 0.2.x), using ergo-sbe-generated session codecs (schema 111).

§Documentation

ergo-sbe book — cluster client guide
Overview · SessionBuilder · Egress listeners · Chained decoding
Crate README

⚠️ Prototype. LLM-assisted and less tested than the Java reference. Bugs in Rusteron pub/sub or this reimplementation may cause undefined behaviour, segfaults, or data loss. Replace when official Cluster C client bindings are suitable for your deployment.

§Client-only — the Java process is the cluster

This crate implements the client side of the Aeron Cluster protocol only — parity with Java io.aeron.cluster.client (connect, offer/try_claim, poll egress, leader failover, keep-alive, admin snapshot, challenge-response auth). It does not implement — and never will — the cluster server: no consensus module (Raft), no clustered-service container, no leader election, no snapshots/recovery, no archive, no backup node, no ClusterTool CLI. You run all of that as the Java Aeron process; this client connects to it over the standard Aeron wire protocol.

§Hot path

AeronCluster::try_claim — SessionMessageHeader into the claim via ergo-sbe
Egress decode (egress / poller / controlled) — SessionEvent, NewLeader, app
Keep-alive encode — periodic
Connect / auth / failover — cold path (correctness over nanoseconds)

§Codecs

Production modules: codecs::session (schema 111) and codecs::mark, generated in build.rs from the vendored Aeron schemas. The sbe-tool reference runtime lives at cluster/benches/reference_sbe/ (Criterion-private — never imported from library, test, or example code).

§Quick connect

use std::sync::Arc;
use ergo_aeron_cluster::{
    SessionBuilder,
    NullCredentialsSupplier,
    StaticCredentials,
};
fn demo() -> Result<(), ergo_aeron_cluster::ClusterError> {
    let builder = SessionBuilder::default()
        .ingress_channel("aeron:udp?endpoint=localhost:9010")?
        .egress_channel("aeron:udp?endpoint=localhost:9020")?
        .credentials(Arc::new(StaticCredentials::from_utf8("user:pass")))
        .message_timeout(std::time::Duration::from_secs(5))?;
    builder.validate()
}
demo().expect("valid config");

use ergo_aeron_cluster::{AeronCluster, ClusterError, SessionBuilder};

fn publish(aeron_dir: &str, app_bytes: &[u8]) -> Result<(), ClusterError> {
    let builder = SessionBuilder::default()
        .ingress_channel("aeron:udp?endpoint=localhost:9010")?
        .egress_channel("aeron:udp?endpoint=localhost:9020")?;
    let mut client = AeronCluster::connect(&builder, aeron_dir)?;
    let mut claim = client.try_claim(app_bytes.len())?;
    claim.payload_mut().copy_from_slice(app_bytes);
    claim.commit()?;
    Ok(())
}

See the book and crate README for recipes, maintained benches, and the HA sample.

Re-exports§

pub use client::AeronCluster;
pub use client::AsyncClusterConnect;
pub use client::ClusterClaim;
pub use client::ConnectStep;
pub use config::SessionBuilder;
pub use controlled::ControlledEgressAdapter;
pub use controlled::ControlledEgressListener;
pub use controlled::ControlledPollAction;
pub use credentials::CredentialsSupplier;
pub use credentials::NullCredentialsSupplier;
pub use credentials::StaticCredentials;
pub use egress::EgressAdapter;
pub use egress::EgressListener;
pub use egress::NullListener;
pub use endpoints::IngressEndpoint;
pub use endpoints::parse_ingress_endpoints;
pub use error::AeronErrorSource;
pub use error::ClusterError;
pub use error::PublicationFailure;
pub use idle::default_idle;
pub use idle::poll_connect_until_done;
pub use poller::EgressEvent;
pub use poller::parse_event;
pub use state::SessionState;

Modules§

client: High-level cluster client: connect, try_claim, offer, keep-alive, close. The AeronCluster client — owns the Aeron transport and drives the full SBE session handshake. Java-parity entry point for the Ergo Aeron Cluster client (experimental prototype on rusteron-client):
config: SessionBuilder configuration for connect. SessionBuilder — channel/stream/timeout configuration for connect.
controlled: Controlled egress poll (Java ControlledEgressAdapter analogue). Controlled egress polling — mirrors Java ControlledEgressAdapter / ControlledEgressListener. Callbacks return a ControlledPollAction so the application can apply backpressure (Abort) or stop (Break).
credentials: Credential supplier traits for challenge-response auth. Credential suppliers for cluster authentication.
egress: Egress adapter + listener dispatch for session and app messages. Egress fragment dispatch to an EgressListener.
endpoints: Multi-member ingress endpoint maps (0=host:port,…). Multi-member ingress endpoint maps ("0=host:port,1=host:port").
error: Cluster client error type. Cluster client error type (ClusterError).
idle: Poll-loop idle helpers (rusteron_client::IdleStrategy). Poll-loop idle helpers (Aeron IdleStrategy — not Tokio).
poller: Low-level egress event parse helpers (SessionEvent, NewLeader, redirects). EgressPoller — single-fragment poller used during the connect handshake. Captures the next SessionEvent, Challenge, or NewLeaderEvent so the caller can react.
state: SessionState machine for connected / new-leader / closed. Client-side session state machine (SessionState).

Statics§

AERON_IPC_STREAM: IPC channel — re-export of rusteron’s zero-cost c"aeron:ipc".