orbit-link 0.6.8

Named reusable duplex sessions between members of an Orbit fleet.
Documentation

orbit-link

orbit-link provides named, bounded dispatch and reusable duplex sessions between members of one Orbit fleet. Applications normally use it through the Orbitive facade as orbitive::link.

It owns the layer immediately above orbit-stream:

caller: choose an advertised lane by depth -> create side A
caller: put an application frame containing the ticket in that lane's inbox
target: read the frame -> open side B -> exchange application bytes
caller: side B releases -> rearm the retained slot -> dispatch it again

Each fleet member owns one inbox lane. A full lane refuses rather than overwriting, and an unowned lane refuses rather than accepting work nobody can answer. The directory exposes service identity, role, incarnation and current depth; selection policy remains with the caller. A kernel-held lane lock is the death signal, so a new join can reclaim the exact incarnation and end its streams without a timeout.

The fleet name and lane are the rendezvous. No descriptor is inherited or passed, and all application bytes remain in shared memory. With tokio, both the inbox and the attached stream use named Unix-datagram bells to wake the runtime directly. A bell carries one meaningless byte, never an application frame or stream payload; SHM remains authoritative and wakes may coalesce. A writer keeps one socket connected to each lane it has rung, so a ring does not name the lane again; a process therefore holds one descriptor for each lane it wakes.

LinkSegment::receiver(lane) binds the one async receiver that owns a lane. Its recv checks SHM before arming the bell and checks the lane generation again before awaiting readiness, so a write that crosses either boundary is not lost. Cancelling the future consumes no frame: the next call checks SHM first. Blocking integrations may continue to use the lane's wake word.

LinkSegment::watch() gives a process that holds no lane a DirectoryWatcher, woken by the same claims and releases. Being woken is not being connected: the watcher takes a slot of its own, serves nothing and never appears in the directory. DirectoryWatcher::next() reports a changed directory generation; the caller reads the directory to determine which services are currently available.

The crate deliberately defines no application frame. HTTP heads, invocation envelopes, resource leases and routing policy belong to adapters. It also does not own an upstream connection pool: reoffering retains bounded SHM capacity, not a TCP connection or its TLS/protocol state.

Every link requires a LinkSpec: fleet capacity, inbox geometry and kind, and the stream table's StreamSpec. The two kinds must differ. This crate reserves no default kinds because kind ownership and incompatible geometry migrations belong to the deployment composing the tables. A changed physical layout uses a new kind while old and new processes may coexist.

Inbox depth is sampled consumer-first (read, then reserve). Both counters only move forward, so this ordering may conservatively overstate a concurrent producer but cannot pair an old reservation with a newer read and underflow into a false Full. Admission and write reservation use the same ordering.

Receiver-owned work admission

join_with_capacity declares a per-receiver exchange bound, or None for no execution bound. A positive bound cannot exceed spec.inbox.capacity, the physical number of admission records per receiver. This is separate from unread inbox frames and creator-side body slots.

A joined sender calls LinkSegment::reserve_work(target, origin) before taking a body slot. CapacityFull means wait for capacity; NoConsumer means the member left. WorkReservation::publish attaches its exact ticket to the inbox slot without changing the application payload. Dropping an unpublished reservation rolls it back. After publication, the receiver uses InboxReceiver::next or Inbox::read_frame, then LinkSegment::accept_work. The returned WorkExecution holds capacity until dropped. Keep it through the complete body or session, not just through production of a response head.

Work admission never gates reading event/control frames. A protocol adapter must require an admission ticket for its work frames on a bounded receiver. The plain read and recv conveniences reject admitted frames rather than silently discard their tickets.

When full, register Inbox::watch_capacity(target, origin) and recheck before parking. Received::Capacity reports a change through the origin's existing inbox bell; several local waits share one member interest. Cancelling one wait must not clear another's interest. No polling, second queue, descriptor or capacity-driver thread is added. Callers own any declared waiting budget.

Only the receiver completes accepted work. Recovery under a dead member's kernel hold cancels its unaccepted reservations, while its accepted work on a live receiver stays counted. Receiver death retires its own admissions. Claim generations never wrap or reset on lane reuse; old completion cannot free a new admission. The owner must drain accepted work before releasing its lane hold. Native exit handling must invoke the existing exact-member recovery APIs; elapsed time is not death evidence.

LinkSegment::update_work_capacity(&joined, limit) changes a positive bound without replacing the receiver. Growth notifies waiting callers. On shrink, claims above the new boundary finish before lower slots are refilled; accepted work is never cancelled. Switching an unbounded receiver to bounded admission requires rejoining, because its earlier work has no admission tickets. Physical inbox and stream geometry remains fixed for the segment's lifetime.

Interrupted producers

Opening a LinkSegment also holds a producer registration, including for a publisher that serves no lane. Each mapping has inbox.capacity intent records; the table admits at most twice fleet_capacity registrations. Capacity or exhausted contention budget returns InboxFull. Claim races help the winner and try another turn, with at most inbox.capacity attempts; no attempt waits for another producer to complete. A retry requires observed cursor progress; a stalled claim is refused without polling it. There is no parking or unbounded spin loop. Reuse mappings rather than opening a new one per frame. Open them after fork.

If retained work exhausts producer registrations, opening performs a bounded recovery pass before retrying registration once. A reader's free kernel hold proves it can no longer consume its queue: recovery retires its queued frames and ends its exact stream incarnation, including when it withdrew before exit. A live reader's queued work and a draining reader's held lane are preserved. True live-capacity pressure still returns InboxFull.

Intent records publish atomic, version-checked snapshots. Slot turns and owner generations remain full-width; exhausted counters refuse rather than wrap. Consumer replacement keeps queue positions monotonic, and old destination work is discarded without taking payload ownership away from a live producer. Retirement uses the same handoff rules and never waits for a live producer to finish a reservation. Incomplete work stays fenced by its old destination epoch.

After a native process-exit notification, call LinkSegment::recover_producers(Some(pid)) (also done by reclaim_process). Cold joins scan dead registrations too. Recovery takes the registration's kernel hold, cancels unfinished claims, preserves committed frames and repeats their wake. It is idempotent if its own actor dies. There is no automatic timed recovery scan, PID liveness probe or timeout-based cancellation of live writers.

This is inbox layout version 8. Existing segments are not converted in place: use a new kind for coexistence, or stop all users before removing the old named resources. Neither opening nor recovery unlinks a running fleet's resources.

Dedicated cross-user Links

LinkSegment::open remains owner-only. To connect trusted processes running as different OS users, explicitly select GroupAccess for one dedicated Link:

use orbit_link::{GroupAccess, LinkSegment};
# fn example(spec: orbit_link::LinkSpec) -> orbit_link::Result<()> {
// Operator-provisioned parent, explicit resource owner and shared OS group.
let access = GroupAccess::new(1001, 2000, "/run/example/ipc")?;
let link = LinkSegment::open_group("example", spec, access)?;
let joined = link.join("example-service", "worker", 1)?;
let bodies = link.bodies(joined.lane, 1)?;
# let _ = bodies;
# Ok(())
# }

The owner starts first and creates the inbox, duplex stream table, lock files and wake directories. Other users attach existing resources only; a missing owner resource is an error, not permission to create it under another UID. Use link.bodies(...) so body streams and crash recovery inherit the same access scope; the owner-only LinkBodies::for_name is not interchangeable. No HTTP or event schema is required. Event bridges can retain private event rings in their respective fleets while sharing only this Link.

This policy does not alter Fleet constructors, unrelated SHM kinds, account credentials, process umask or existing resource permissions. The SHM namespace includes the configured owner, group, canonical parent/directory, fleet name and kind. Different IPC directories cannot supply competing lane locks for the same group-shared segment. These names differ from owner-only names.

Deployment requirements:

  • Provision the parent directory on a trusted path, traversable by every peer but not replaceable by untrusted users. All peers use the same path and GID.
  • The resource owner must be allowed to assign the selected group. On macOS it must be the owner's effective group because POSIX SHM permissions cannot be repaired with fchown/fchmod after creation.
  • Run participants with a creation mask preserving group write, for example 0007. The library never changes it. Inadequate permissions are rejected.
  • The owner creates a 0750 IPC directory containing 0660 lock files and a separate setgid 2770 bells directory. Group members can lock but cannot replace lock inodes. Wake sockets use that directory on every Unix platform, including Linux; they carry readiness only, not application data.
  • Keep lock files for the lifetime of the deployment. Do not remove or replace them on restart: death proof depends on all peers locking the same inode. Only the owner removes SHM names, after every participant has stopped.

Every group writer is trusted with this Link's shared state. Role/service names are routing declarations, not authenticated user identities. Group sharing is not a sandbox between malicious peers and does not grant kernel capabilities, access to other fleets or access to a consumer's private files. Applications must still validate every requested operation.

The test suite covers group-scoped inbox/stream wakes, owner-only isolation, permissions, symlink refusal, scope separation and killed-owner reclamation. cross_uid_group_transport is an explicitly ignored privileged test: on an authorized isolated host, run it as root with the test-name filter and --ignored. It adopts numeric UIDs/GIDs in child processes only, creates no accounts and changes no host services. This test must pass on a target OS before declaring cross-user deployment validated.

Benchmark

cargo bench -p orbit-link --bench transport --features tokio,probe measures one request and its reply between two processes, with no HTTP: a connected Unix socket, a held stream, and a named call through the inbox, stage by stage, with the CPU both processes spent. What each row is and how to read the columns is in docs/benches.

orbit-stream's own transport benchmark answers a different question. It compares the exchange payload arena with sockets across body size, application chunk size and concurrency. orbit-link uses StreamSpec duplex byte rings, not that exchange arena.

Downstream measurements through a full server, with their environments and limits, are in BENCHMARKS.md.