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 ;
#
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/fchmodafter 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
0750IPC directory containing0660lock files and a separate setgid2770bellsdirectory. 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.