Module station_link 

A client’s link to one macula station, as macula_station_link and macula-go’s stationlink are: a QUIC connection dialed to the station its target pins, one bidirectional control stream, the connection handshake on it (v5, or v4 once after a station refuses v5), then status statements both ways and every frame of the session.

After HELLO the link sends its own status statement at every reissue of the node’s statement issuer, and ends when the station’s statement is five minutes past its expiry or the station’s TLS binding reaches its not_after. On a v5 link no frame carries a neighbour signature: the session proofs authenticated the station once, and a neighbour-signed frame ends the link. On a v4 link, in pq_hybrid, every control frame is neighbour-signed with a sequence number per direction, from 0 after HELLO; a frame out of sequence ends the link. A liveness probe every 30 seconds ends the link after two misses in a row: on v5 a liveness_ping, on v4 a _macula.ping call.

Structs

Admission

One provider node’s request admission, shared by all its links.

AdmissionLimits

An admission’s bounds. The last four bound the streaming sessions a node serves, as macula_stream_sessions does: sessions at once per caller and in all, and the bytes their inboxes hold per caller and in all.

Call

One request: the realm and procedure, the node it targets (the station itself when zero, as for _dht.*; the provider’s node_id otherwise), its payload, how long to wait (the default when zero), a UCAN token and its delegation chain’s proofs for a gated procedure, and how it is kept. A call to a provider must state seal: sealed to the key its verified advertisement names, or clear by the application’s decision; one that states neither is refused no_signed_state before anything is sent. A call to the station is always clear.

ConfidentialityError

A call or an open that could not be kept confidential, and so was not made, or failed rather than be taken in the clear. advertised holds the key ids the trusted providers’ advertisements named; named is the key a provider’s refusal named, for a key mismatch.

Config

What a link is dialed with: the station to reach, the node’s identity key, the statement issuer that holds its CONNECT key and statements, and the realm membership endorsement to present, empty for none. Links of one node share their publication seq, admission and dedup; a link given none makes its own.

Event

A publication a subscription heard, verified: who published it (the key id its signature verified under), where, its seq and time, the payload, and how it arrived (direct or plumtree).

EventDedup

Remembers the publications a node delivered, by publication hash, until each expires, so an event heard on several links, or twice on one, is delivered once. The links of one node share one.

Link

A handshaked link to one station. Cloning it shares the link.

Offer

A procedure to serve: its realm and name, exactly one of a unary handler and a stream offer, and, for an org procedure, the realm key the org directory must be signed with, as the realm’s members pin it; a procedure in this node’s own namespace needs none.

Publication

What Link::publish sends: the realm and topic, the payload, and its time to live, None for macula’s 10 minutes.

PublicationSeq

Numbers one publisher’s publications: the first is the wall clock in microseconds, and each after is one more than the last, or the clock, whichever is later, as macula_publication_seq does. Links of one identity key share one, so their seqs never repeat.

Report

A caller’s seal report on one exchange, with the three fields every SDK names alike (macula’s sealed, provider, seal_key_id). sealed is 1 when the request that produced the result was sealed and its answer opened under the same key, whose id seal_key_id names, and 0, with no key id, for a clear exchange. provider is the node the request was addressed to: for a sealed result also the one whose answer opened, for a clear one the target and no claim about who answered.

Request

A CALL a served procedure answers: the caller (the key id its signature verified under), what it asked for, and its deadline in unix milliseconds.

Served

A procedure this link serves, until Served::stop or the link ends, or until its advertisement lapses because its authorization could not be found again. Cloning it shares the serving.

SignedPublication

A PUBLISH signed once, to be sent on several links of one node: every copy is the same publication, so a subscriber hearing it on several links delivers it once.

Stream

One streaming session, on either side. Cloning it shares the session.

StreamCall

A streaming session to open: the realm and procedure, the provider it targets, the mode, the open’s payload, how far ahead its deadline lies (DEFAULT_STREAM_DEADLINE when zero), a UCAN and its proofs for a gated procedure, and how it is kept, which an open must state as a call does (see super::Call). Its default mode is server_stream.

StreamOffer

A streaming procedure’s mode and handler. The advertisement is the one a unary procedure sends, which names no mode: a STREAM_OPEN of another mode is refused mode_mismatch.

Subscription

One subscription to a realm and topic on a link, until Subscription::unsubscribe or the link ends.

Enums

Confidentiality

How a procedure takes its requests, and how a pool’s call or open must be kept, as macula-go’s stationlink.Confidentiality.

ConfidentialityReason

Why a call could not be kept confidential, as macula’s {error, {confidentiality, Reason}} names it.

LinkError

Why a link or one of its operations failed.

ReportError

Why a stream has no seal report.

Seal

How a call or an open to a provider is kept.

StreamEvent

One frame the peer sent, verified: a chunk, the peer’s end (role Send ends its sending only, Both the stream), or the provider’s terminal value.

Constants

DEFAULT_CALL_TIMEOUT

macula’s default timeout for a call.

DEFAULT_STREAM_DEADLINE

How far ahead a STREAM_OPEN’s deadline lies when its StreamCall names none, as macula’s default.

HANDSHAKE_TIMEOUT

How long the handshake may take, as macula’s 30 seconds.

MAX_CALL_TIMEOUT

The longest a call waits: the far edge of a provider’s deadline window.

Functions

forget_v5_peer

Forgets that this process completed a handshake v5 with the station node_id, so a station deliberately rolled back below v5 is dialled again, falling back to v4. An operator action for a deliberate rollback, never automatic.

handler

A Handler from an async closure.

handshake_counters

This process’s handshake counters: links by version, v4 fallbacks, refused downgrades, and HELLO refusals by reason. This crate logs nothing, so these are where a repeated fallback or a refused downgrade shows.

is_clear_refusal

Whether code may answer a sealed request in the clear.

stream_handler

A StreamHandler from an async closure.

Type Aliases

BoxFuture

A future a handler returns.

Handler

Answers a Request with a result payload, or an error whose text the caller receives as a handler_error’s detail. A handler still running at the request’s deadline is dropped and answered handler_error.

StreamHandler

Serves one streaming session. When it returns Ok and has not ended the stream, the stream is closed on both sides; an Err or a panic aborts it with code error and the error’s text, as macula aborts a stream whose handler failed. A handler still running when its stream ends is dropped.