Module direct_dial 

Direct-dial resolve-and-call: resolving a signed procedure_advertisement DHT record and its serving station’s own signed station_endpoint, then dialing that station in one hop — instead of depending on ordinary advertise-gossip having propagated a route between whichever two stations happen to be involved.

Ported from macula-io/macula’s macula_direct_dial.erl, cross-checked against macula-go’s own port of the same reference (directdial/directdial.go) — see that file’s doc for the fuller reasoning behind each design choice made here.

Trust model (see macula_direct_dial.erl’s module doc for the full reasoning): every candidate procedure_advertisement must carry a valid Ed25519 signature before its serving_station is trusted at all, and the resolved station_endpoint must be signed by the station itself. The actual QUIC dial trusts neither the TLS certificate (a production station’s TLS is terminated by an unrelated PKI) nor nothing — trust is enforced at the application layer, by checking the freshly dialed session’s own signature-verified HELLO identity against the exact pubkey the signed DHT chain resolved.

cert_chain-based org/realm authorization (Slice 7c Direction B, macula_record:verify_advertisement_cert_chain/3 on the Erlang side) is opt-in here too, matching the reference and macula-go’s own port — see resolve_with_cert_chain/call_with_cert_chain/ advertise_direct_with_cert_chain. Plain resolve/call/ advertise_direct are completely unaffected.

Structs

ContentNotAnnounced

mcid has no live, verifiable content_announcement in the DHT — either nobody announced it (common: a single-block content put alone is never announced, matching macula_content_transfer:put_single_block/3), or every candidate found failed signature/self-consistency verification.

Resolved

One resolved direct-dial target: the station’s own node id plus a dialable host/port.

Enums

AdvertiseDirectError

CallError

DialAndVerifyError

The dial-then-pin sequence every direct-dial call shape needs after resolving: dial resolved’s host:port, then check the freshly connected session’s own signature-verified HELLO identity against resolved.station — factored out here (unlike call/ call_with_cert_chain, which had it inline before this existed) because open_stream_direct/put_direct/get_direct all need the identical sequence against a station identity that isn’t necessarily reached via resolve.

GetDirectError

OpenStreamDirectError

PutDirectError

ResolveError

Functions

advertise_direct

Publishes a signed procedure_advertisement naming session’s own currently-connected station (session.station.node_id) as procedure’s server, discoverable by any caller’s resolve/call. Mirrors macula_response:advertise_direct/6,7 + macula_direct_dial:publish_advertisement/4,5 — unlike the Erlang reference’s pool (many links, one chosen by connected_station/1), a Session is always exactly one connection, so there is no link-selection step: the session’s own verified HELLO identity IS the serving station.

advertise_direct_with_cert_chain

advertise_direct plus an embedded X.509 service-cert chain, for Slice 7c Direction B managed-realm authorization — see resolve_with_cert_chain/call_with_cert_chain for the corresponding checks. Opt-in: plain advertise_direct is unaffected.

call

Resolves procedure’s provider via direct-dial (through resolve_via, used only to query the DHT) and calls it there, in one hop, in a SEPARATE connection from resolve_via. The provider must have advertised via advertise_direct (or the Erlang macula_response:advertise_direct/6,7) — a plain advertise publishes no discoverable record and resolve will return ResolveError::ProcedureNotAdvertised.

call_with_cert_chain

call, resolved via resolve_with_cert_chain instead of resolve — see both for the full contract. Opt-in managed-realm authorization; call itself is unaffected.

call_with_ucan

call, presenting ucan_token to a provider gated with {ucan_required, Issuer}. Every hecate-om capability is advertised via advertise_direct, so this is the only way a UCAN-gated capability is reachable through this crate at all – call itself has no token parameter, and Session::call_with_ucan is the plain, non-direct path, which cannot resolve a direct-dial-only advertisement to begin with.

get_direct

Fetches and verifies the content addressed by mcid from whichever station a signed content_announcement names as its host, dialing that station in one hop instead of relaying through resolve_via’s own station. Mirrors macula_direct_dial:get_content/3.

keep_advertised_direct

Calls advertise_direct immediately, then again every interval, until stop resolves. Rust has nothing equivalent to macula_response’s reuse_sup to worry about here, because advertise_direct (unlike Erlang’s advertise/5, which spawns a real per-call OTP supervisor) is already a stateless, side-effect-free-on- repeat async function: nothing is created per tick that could leak — same reasoning macula-go’s KeepAdvertisedDirect already applied and verified live.

open_stream_direct

Resolves procedure’s provider via direct-dial (through resolve_via, used only to query the DHT) and opens a stream there, in one hop, in a SEPARATE connection from resolve_via — the streaming-RPC counterpart to call. The provider must have advertised via advertise_direct: streaming’s provider side (macula_streamer.erl) shares the identical procedure_advertisement mechanism RPC uses (confirmed against macula_streamer.erl/macula_stream_sink.erl’s own advertise_direct/ start_link_direct — both are macula_response:advertise_direct/ macula_direct_dial:call_stream under the hood, nothing stream-specific added), so no separate stream-shaped advertise function exists or is needed.

open_stream_direct_with_cert_chain

open_stream_direct, resolved via resolve_with_cert_chain instead of resolve — see both for the full contract. Opt-in managed-realm authorization; open_stream_direct itself is unaffected.

put_direct

Stores data at a KNOWN station directly, in one hop, instead of going through whatever station resolve_via happens to be connected to. Mirrors macula_feeder:start_link_direct/5,6, which — unlike procedure/stream direct-dial — takes the target station’s pubkey directly rather than resolving one via a procedure_advertisement: content has no “procedure” to advertise, so there is nothing to resolve here beyond the station’s own station_endpoint (resolve_station_endpoint). resolve_via is used only to query the DHT for station’s station_endpoint; it does not need to already be connected to station.

resolve

Finds procedure’s currently-advertised serving station and its dialable host/port, retrying past DHT propagation lag. realm and procedure must match exactly what the provider passed to advertise_direct (or the Erlang equivalent) — the discovery URI they derive must agree. session is used only to query the DHT; it does not need to be connected to the same station that will end up serving the call.

resolve_with_cert_chain

resolve plus Slice 7c Direction B managed-realm authorization: only an advertisement whose embedded cert chain validates to realm_ca_pem and names expected_org is trusted. Opt-in — resolve itself is unaffected and remains the right choice for unmanaged realms.