orbitive 0.5.3

Bounded same-host coordination for Rust process fleets

Orbitive is a Rust facade for bounded, same-host coordination shared by a fleet of sibling processes. orbit-core is the primitive substrate; the workspace also contains optional semantic and application-facing layers built from those primitives. Cache coherence, locks, reusable links, rustls session sharing and outbound client pools therefore remain separate crates while the orbitive facade provides one deliberate public entry point.

It provides two storage shapes:

• rings for recent, append-only history;
• fixed-capacity tables for current keyed state.

Both shapes can run in process memory or over POSIX shared memory. They are intended for ephemeral runtime coordination where a database or network broker would be unnecessary. They do not provide durability or network replication.

The facade is published as orbitive. Its runtime model and public type names use the established Orbit vocabulary, such as Fleet, OrbitTyped, and OrbitEpoch.

Add the facade

[dependencies]
orbitive = { version = "0.5.3", features = ["events", "lock"] }

Core types used by most integrations are available at the crate root. The full low-level surface remains under orbitive::core.

use std::sync::Arc;

use orbitive::events::FleetEventBus;
use orbitive::Fleet;

let fleet = Arc::new(Fleet::join("example", 1)?);
let bus = FleetEventBus::new(fleet);
bus.publish("worker.ready", b"worker-1")?;

# Ok::<(), Box<dyn std::error::Error>>(())

Feature modules

auth can be enabled individually and is included in full. It shares authentication trust across domains and protocols through encrypted, audience/purpose-scoped tokens and a local decoded cache plus shared session, refresh and replay state. Backing follows the supplied Fleet. Cookie, Bearer, WebSocket and internal transport extraction remain in adapters; see orbit-auth.

stream is the transport primitive: it provides bounded duplex byte flow and typed paired exchanges without deciding why an application moves those bytes. The optional pool-stream composition binds a fleet-owned resource lease to an exchange. It is not enabled by full; applications opt in when remotely owned resources execute over Orbit streams.

client-pool is also opt-in and requires Tokio. The base orbitive facade and orbit-core remain independent of an async runtime. The local layer owns real client objects inside their process; client-pool-fleet adds Orbit admission and carries operations to a remote owner without pretending that a client object can move through shared memory. Neither layer knows HTTP, database, mail or application protocol formats.

The implementation crates are also published separately as orbit-core, orbit-cache, orbit-arena, orbit-cell, orbit-counter, orbit-events, orbit-invoke, orbit-link, orbit-lock, orbit-metrics, orbit-pool, orbit-client-pool, orbit-rustls, and orbit-stream. Direct dependencies are supported when an integration needs a single narrow layer; applications can otherwise use the facade and enable only the modules they need.

The optional orbit-auth implementation is also available as a narrow direct dependency, with backing selected by the supplied Fleet.

Compile-time geometry

The default shared-memory geometry can be selected once for an entire downstream Cargo build graph. Put the desired values in the application's .cargo/config.toml; ordinary cargo build, cargo test, and cargo run commands then compile every Orbit dependency with the same values:

[env]
ORBIT_EVENT_RING_CAPACITY = { value = "1024", force = true }
ORBIT_EVENT_RING_PAYLOAD_CAPACITY = { value = "512", force = true }

ORBIT_COUNTER_CAPACITY = { value = "1024", force = true }
ORBIT_COUNTER_KEY_MAX = { value = "240", force = true }

ORBIT_INVOKE_RING_CAPACITY = { value = "256", force = true }
ORBIT_INVOKE_RING_PAYLOAD_CAPACITY = { value = "8192", force = true }

ORBIT_CACHE_MUTATION_RING_CAPACITY = { value = "1024", force = true }
ORBIT_CACHE_MUTATION_RING_PAYLOAD_CAPACITY = { value = "1024", force = true }
ORBIT_CACHE_PAYLOAD_RING_CAPACITY = { value = "1024", force = true }
ORBIT_CACHE_PAYLOAD_RING_PAYLOAD_CAPACITY = { value = "4096", force = true }

ORBIT_LOCK_EVENT_RING_CAPACITY = { value = "1024", force = true }
ORBIT_LOCK_EVENT_RING_PAYLOAD_CAPACITY = { value = "1024", force = true }
ORBIT_LOCK_STATE_CAPACITY = { value = "256", force = true }
ORBIT_LOCK_STATE_PAYLOAD_CAPACITY = { value = "960", force = true }

ORBIT_METRIC_SNAPSHOT_RING_CAPACITY = { value = "1024", force = true }
ORBIT_KEYED_METRIC_RING_CAPACITY = { value = "4096", force = true }

ORBIT_RUSTLS_SESSION_SET_COUNT = { value = "256", force = true }
ORBIT_RUSTLS_SESSION_WAYS = { value = "8", force = true }
ORBIT_RUSTLS_SESSION_DOMAIN_CAPACITY = { value = "64", force = true }
ORBIT_RUSTLS_SESSION_KEY_CAPACITY = { value = "64", force = true }
ORBIT_RUSTLS_SESSION_VALUE_CAPACITY = { value = "16384", force = true }

Every key is optional and retains the documented default when absent. Values are decimal byte or entry counts and may contain _ separators. Invalid values fail compilation. These settings are part of the fleet wire contract: all peers that open the same fleet must be built with the same geometry, and existing SHM objects must be cleared before a geometry change takes effect.

Command-line inspection

The separately published orbitive-cli package installs the orbit command. It can inspect Orbit POSIX shared-memory objects without joining the fleet:

cargo install orbitive-cli
orbit list example
orbit list example --kind 231

It can also remove one object or every object belonging to a stopped fleet:

orbit clear example --kind 231
orbit clear example --all --yes

Do not clear a running fleet. Existing POSIX mappings survive unlink while a later process can create a different object under the same name.

External read-only observation (no fleet join)

On Unix, an independent Rust process can inspect an existing SHM ring without joining as a writer or reproducing the producer's fleet geometry:

use orbitive::FleetObserver;
use orbitive::ring::cursor::{RingCursor, poll_ring};

let observer = FleetObserver::attach_existing("example")?;
let ring = observer.ring(221)?;

for lane_index in 0..ring.metadata().lane_count {
    let lane = ring.lane(lane_index)?;
    let mut cursor = RingCursor::from_counter(lane.retained_range().start);
    for frame in poll_ring(&lane, &mut cursor).frames {
        println!("{lane_index}: {frame:?}");
    }
}

# Ok::<(), Box<dyn std::error::Error>>(())

The observer opens exact existing objects read-only. It cannot create, reset, publish, or unlink, and dropping it only unmaps local memory. Raw frame access belongs to core; the crate that owns a kind remains responsible for payload decoding and freshness or liveness judgments. A consumer linked to the same typed contract can use observer.typed_ring::<T>() for an additional OrbitTyped::RING_SPEC check.

This is intentionally observation rather than another form of Fleet::join: the external process receives no node id, holds no fleet membership, owns no writer lane, and does not keep the fleet alive. ring(kind) opens only that already-existing uid-scoped object. Use attach_existing_for_uid when an operator process is permitted to inspect a different user's namespace.

Runtime contract

Every process joining the same shared fleet must agree on the immutable fleet capacity, node ownership, stable kind numbers, and ring or table layouts. Capacity reserves physical node lanes; it does not assert current membership or liveness. Storage is bounded: old ring frames may be overwritten, caches may miss, and session entries may be evicted. Callers must treat those outcomes according to the semantic module they use.

Shared-memory operation currently targets Unix. Native readiness is available on Linux, FreeBSD, and macOS 14.4 or later. On older macOS, readiness creation returns io::ErrorKind::Unsupported; callers can use polling where the semantic module permits it.