Skip to main content

Crate aurelia

Crate aurelia 

Source
Expand description

§Aurelia

An embeddable service mesh for Rust applications. Aurelia gives a Rust process a built-in, authenticated peer-to-peer fabric — no sidecar, no control plane, no extra runtime to deploy.

§Layer model

  • A0 — Transport authentication. mTLS over TCP, or PKCS#8 certificate-backed authentication over Unix domain sockets. A0 completes before any A1 frames are exchanged.
  • A1 — Message and blob transfer. Delivery, callis (per-peer connection flow), and taberna (named inbound endpoint) management.
  • A2 — Aurelia services. Higher-level capabilities built on A1 (in progress; the current release ships A0 and A1 with the wrapper API).
  • A3 — Application. Your code. All A3-to-A3 traffic transits A1.

§Quick start

Initialise the Aurelia runtime and build a Domus (the local peer) bound to a TCP address with PKCS#8 mTLS material:

use std::sync::Arc;
use aurelia::{Aurelia, DomusAddr, DomusConfigBuilder,
    Pkcs8AuthConfig, Pkcs8PemConfig, SimpleResolver};

let aurelia = Aurelia::new();

let config = DomusConfigBuilder::new().build()?;
let auth = Pkcs8AuthConfig::Pkcs8Pem(Pkcs8PemConfig {
    ca_pem: std::fs::read("ca.pem").unwrap(),
    cert_pem: std::fs::read("cert.pem").unwrap(),
    pkcs8_key_pem: std::fs::read("key.pem").unwrap().into(),
});

let domus = aurelia
    .domus_builder(
        config,
        DomusAddr::Tcp("127.0.0.1:7000".parse().unwrap()),
        auth,
        Arc::new(SimpleResolver::new()),
    )
    .build()
    .await?;

// Use `domus.taberna(...)` to register inbound endpoints, and
// `domus.send(...)` to dispatch messages to peers.

§Where to look next

Structs§

Aurelia
Runtime owner and entry point for the Aurelia library.
AureliaError
The single error type used across Aurelia. Carries a stable ErrorId discriminant and an optional human-readable message; the kind is the field applications match on.
BlobCallisSettingsReport
Snapshot of blob-callis settings reported alongside connection events.
BlobReceiver
Inbound blob stream attached to a callis. Implements AsyncRead.
BlobSender
Outbound blob stream attached to a callis. Implements AsyncWrite.
BlobWindowConfig
Blob chunk size and acknowledgment window configured as one pair.
Domus
A running Aurelia domus: the local peer’s representation in the mesh.
DomusBuilder
Builder for a Domus wired to the Aurelia runtime.
DomusConfig
Tunable parameters for a crate::peering::Domus. Construct via DomusConfigBuilder or start from DomusConfig::default and override individual fields.
DomusConfigAccess
Live handle to a running crate::peering::Domus’s configuration. Allows taking a current snapshot and applying validated updates without restarting the domus.
DomusConfigBuilder
Fluent builder for DomusConfig. Each setter overrides the matching field and returns Self for chaining; DomusConfigBuilder::build validates the final configuration.
DomusMetrics
Cumulative counters for a crate::peering::Domus, obtained via crate::peering::DomusReporting::snapshot.
DomusMetricsDelta
Counter deltas since the previous reset, obtained via crate::peering::DomusReporting::snapshot_and_reset. Cumulative counters report the increment over the prior reset interval; gauges (current_*, peak_* over the interval) report current values.
DomusReporting
Observability handle obtained from crate::peering::Domus::reporting. Provides snapshot access to metrics, enumeration of connected peers, and pub-sub access to the live event and error streams.
DomusReportingFeeds
Bundled live broadcast receivers for events and errors, returned by DomusBuilder::build_with_reporting or DomusReporting::feeds.
EncodedMessage
Wire-ready application message: a type discriminator plus its serialised payload.
PeerIdentityReport
Identity report for a connected peer, used when enumerating peers via crate::peering::observability::DomusReporting::connected_peers.
Pkcs8DerConfig
PKCS#8 mTLS material in DER form.
Pkcs8PemConfig
PKCS#8 mTLS material in PEM form.
Pkcs8PrivateKey
PKCS#8 private-key bytes that zeroize on drop after ownership is transferred.
SendOptions
Per-send flags controlling whether a callis carries an attached blob.
SimpleResolver
In-memory RouteResolver backed by a mutable map from TabernaId to DomusAddr. Suitable for tests, fixtures, and applications with a small static topology.
Taberna
A registered inbound endpoint on a Domus.
TabernaCompletion
Completion guard for a taberna request.
TabernaRequest
A single inbound delivery handed to the application. The application must acknowledge the request by calling either TabernaRequest::accept or TabernaRequest::reject; dropping the request without a decision is treated as rejection.
TabernaRequestParts
Application-owned pieces of a split TabernaRequest.

Enums§

DomusAddr
Network address of a domus peer, abstracting over the supported transports.
DomusReportingEvent
Event surfaced on the crate::peering::observability::DomusReporting event stream.
ErrorId
Stable error identifier carried by every AureliaError. Each variant corresponds to a distinct failure mode in the Aurelia stack; semantics are stable across releases so applications can match on them safely.
MessagePriorityClass
Priority class for a MessageType on the primary callis.
Pkcs8AuthConfig
PKCS#8 mTLS material supplied when building a crate::peering::Domus.
SendOutcome
Result of a successful send call.
TransportKind
Tag identifying which transport a DomusAddr uses.

Constants§

A1_MESSAGE_TYPE_MAX
Last MessageType in the A1 transport-control priority range.
A2_MESSAGE_TYPE_BASE
First MessageType in the A2 Aurelia-service priority range.
A2_MESSAGE_TYPE_MAX
Last MessageType in the A2 Aurelia-service priority range.
A3_MESSAGE_TYPE_BASE
First MessageType in the A3 application range.
A3_MESSAGE_TYPE_MAX_OFFSET
Largest offset accepted by a3_message_type and try_a3_message_type.

Traits§

MessageCodec
Application-supplied codec used by Aurelia to translate between typed application messages and the wire form transferred between peers.
RouteResolver
Application-supplied resolver that maps a target TabernaId to the DomusAddr of the peer hosting it. Aurelia calls this on every send so applications can implement service discovery as they see fit.

Functions§

a3_message_type
Returns the A3 application MessageType for an offset from A3_MESSAGE_TYPE_BASE.
classify_message_priority
Classifies a MessageType into the A1/A2/A3 outbound priority ranges.
try_a3_message_type
Returns the A3 application MessageType for offset, or None if it would exceed u32.

Type Aliases§

MessageType
Application-defined message type discriminator on the wire.
TabernaId
Stable identifier for a crate::ids::Taberna.