Module station_link 

A client’s link to one macula 12 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 v4 handshake on it, 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. 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, a _macula.ping call every 30 seconds, ends the link after two misses in a row.

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), and a UCAN token and its delegation chain’s proofs for a gated procedure.

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.

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), and a UCAN and its proofs for a gated procedure. 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

LinkError

Why a link or one of its operations failed.

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

handler

A Handler from an async closure.

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.