orbitive 0.3.12

Bounded same-host runtime state for Rust process fleets

Orbitive is a Rust facade for bounded, same-host runtime state shared by a fleet of sibling processes.

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.3.10", 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

The implementation crates are also published separately as orbit-core, orbit-cache, orbit-arena, orbit-cell, orbit-counter, orbit-events, orbit-invoke, orbit-lock, orbit-metrics, and orbit-rustls. 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.

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.

Read-only process observation

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.

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.

Repository: https://github.com/iadev09/orbitive