orbit-link 0.5.2

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.

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.

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.

Benchmark

cargo bench -p orbit-link --bench dispatch compares a complete small request/reply dispatch with UnixStream::pair: lane lookup, ticket encoding, inbox publication, ticket parsing, stream opening and the duplex bytes are in the Orbit measurement. The UDS case has no separate routing envelope because the connected pair is already its address. Both fresh-slot and retained-slot paths are reported, so allocation and rearming are not conflated.

The benchmark uses representative production geometry: 128 inbox frames of 17 KiB, 128 duplex slots per node and a 64 KiB window in each direction. It is still a same-process, sequential protocol-cost benchmark. Its reader calls Inbox::read directly, so it does not measure a Tokio reactor wake, process scheduling, an application protocol or worker routing.

orbit-stream's 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. Those results inform stream and chunk geometry; they are not a substitute for a downstream named-link integration test.