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](https://github.com/iadev09/orbitive) facade as `orbitive::link`.

It owns the layer immediately above `orbit-stream`:

```text
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:

```rust,no_run
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](docs/benches/README.md).

`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](BENCHMARKS.md).