Crate structfs_handles 

structfs-handles

Handle-store and streaming primitives for StructFS.

The deferred-operation pattern — write a request, get an outstanding/{id} handle path back, read the handle for results — is the backbone of every broker-shaped StructFS store. This crate makes it a primitive instead of a convention:

• HandleStore + HandleProtocol: generic outstanding/{id} scaffolding — id minting, routing, the no-overwrite rule, Null-write release with cancellation, listing.
• TailLog / TailPage: append-only event streams with atomic tail reads — items and terminal status in one operation, so the “close-out drain” race cannot exist.
• Gate / CancelToken: park-until-predicate with the enable-before-check ordering baked in (no lost wakeups), and cancellation that fails parked reads while leaving writes open.
• SyncBridge: run a detached async store from synchronous code on a blocking thread.
• conformance: certify any handle store against the protocol rules.

Modules

conformance

Conformance checks for the handle-store protocol.

Structs

ByteChunk

One ranged read’s result.

ByteStream

An append-only byte buffer with terminal state and parked ranged reads.

CancelToken

A cloneable cancellation token.

Cancelled

The wait was cancelled via its CancelToken.

DuplexStream

An endpoint owns both half-streams. Share it with Arc; dropping the last owner releases buffers and wakes both ends. A cancelled operation transfers no bytes; a successful write transfers the entire chunk atomically.

Gate

Park until a predicate holds.

HandleCx

Context handed to a protocol when a handle is opened.

HandleStore

Generic handle store over a HandleProtocol.

Path

A validated path in StructFS.

StreamReadiness

StreamStore

Paths relative to an explicitly granted stream handle: read rx/{max} -> Bytes (empty means EOF), write tx -> Bytes; read ready/{read|write|both} parks; write Null to shutdown half-closes, write Null to the root releases. No transport creates ambient network authority.

SyncBridge

Adapts a detached async store to the synchronous Reader/Writer traits by blocking on a tokio runtime handle.

TailLog

An append-only event log with terminal state and parked tail reads.

TailPage

One page of a tail read.

Enums

Error

Errors at the Core layer.

Record

A record that can be forwarded without parsing or parsed for inspection.

Value

A tree-shaped value that can be read from or written to a Store.

Traits

DetachedReader

Async reads whose futures are detached from the store.

DetachedStore

Combined detached read/write.

DetachedWriter

Async writes whose futures are detached from the store.

HandleProtocol

The store-specific half of a handle store.

Type Aliases

DetachedFuture

A boxed future that does not borrow the store that produced it.