Direct-dial resolve-and-call: shared internals for macula_request/macula_response, macula_streamer/ macula_stream_sink, and macula_feeder/macula_download.

Not a public API on its own — macula_request:start_link_direct/6,7,8, macula_response:advertise_direct/6,7, macula_stream_sink:start_link_direct/5,6, macula_streamer:advertise_direct/6,7, macula_download:start_link_direct/4,5, and macula_feeder:start_link_direct/5,6 are the entry points. Factored out because RPC, streaming, and content-download all need the same shape of resolve sequence (find_records -> verify -> read the record -> build a quic:// dial URL). Streaming and RPC share the IDENTICAL discovery mechanism — a procedure_advertisement does not distinguish RPC from streaming, only the eventual dial (call_station/7 vs call_stream_station/6) does — so publish_advertisement/4,5 is reused as-is by both providers, and call/6/call_stream/6 share the same candidate resolution and "Trust model" below. Content has no publish step here at all — see "Content" further down.

Resolution

Every advertisement that passes trust filtering is a candidate, in the order the DHT returns them. A candidate whose station_endpoint can't be resolved, or whose link doesn't connect ({error, not_connected} from call_station/7 or call_stream_station/6), is passed over for the next one, but only before the request is sent: once a CALL or a stream has gone out, its outcome is returned as it is. When no candidate qualifies, or every one failed before sending, resolution asks the DHT again after a pause that doubles from 100 ms to at most 1 s, and tries a candidate that already failed again only when its advertisement or its station_endpoint record has changed. A record just published on the provider's station has not necessarily replicated to the caller's station yet, so a miss is not final until the deadline. One deadline bounds all of it: each DHT lookup, each candidate's endpoint lookup and connect wait (within a share of the time that remains, at least one second while that much remains), and the request. At the deadline the result is, in this order, the most recent candidate's failure, why the latest answered DHT lookup found nothing qualifying, the latest failed lookup's error, or {error, {unresolved, timeout}}. A failed lookup is retried like an empty pass, and one the deadline cuts off records nothing.

Trust model

Two independent checks, both mandatory, cover what the QUIC/TLS layer cannot: (1) every candidate procedure_advertisement must carry a valid Ed25519 signature before its serving_station is trusted at all — otherwise any identity able to sign SOME record could name a real, legitimate station as the server for a procedure it has no authority over, and the station_endpoint check below would still pass (it only proves we reached the station we were told to reach, not that whoever told us so was authorized to); (2) the resolved station_endpoint must be signed by the station itself (verify_and_build/2, unchanged). The actual QUIC dial trusts NEITHER the TLS certificate (pin_tls_cert => false — a production station's TLS is terminated by an unrelated PKI, e.g. Let's Encrypt, so pinning the cert key can never succeed) NOR nothing (verify => none alone would trust whoever answers): trust is enforced at the application layer instead, via the cryptographically signed CONNECT/HELLO handshake (the peer identity binding in macula_peering_conn) checked against the exact pubkey the signed DHT chain above resolved.

A third check is available but OPT-IN, via Opts (managed realms only — see macula_record:verify_advertisement_cert_chain/3): verify_cert_chain => {RealmCaPem, Org} additionally requires the advertisement's embedded X.509 service-cert chain to verify to RealmCaPem under Org (Slice 7c Direction B), proving the ADVERTISER — not just the station it names — is an org/realm- authorized identity. Without it, (1) above still rejects an unsigned or badly-signed advertisement, but not one signed by an unauthorized (if self-consistent) identity; unmanaged realms have no realm CA to check against, so this stays opt-in rather than mandatory.

Content

put_content/4 has no resolve step at all — unlike a GET, a PUT names its OWN target: the caller already knows (or is choosing) which station to seed, so it takes Station directly and resolves only that station's own station_endpoint (resolve_station_endpoint/2,3, the same machinery call/6 uses internally for serving_station).

get_content/3 and fetch_content/4 resolve and fetch deliberately WITHOUT the cert-chain machinery above — content's threat model genuinely differs from RPC's. An RPC reply is opaque and unverifiable except by trusting whoever answered, so proving the ADVERTISER is authorized matters. Content is content-addressed, and the fetched bytes are checked against the MCID client-side regardless of which peer served them. Single-block content is re-hashed against the MCID (in macula_content_transfer). For chunked content the fetched manifest is used only if its MCID, recomputed from its canonical fields, is the one requested (macula_manifest:verify_mcid/2); each chunk is then hashed against that manifest, and the reassembled bytes are checked against its size and root hash (macula_manifest:verify/2). A rogue or unauthorized announcer can at most refuse to serve or waste a dial; it cannot make a caller accept content that does not match the MCID it asked for. The same holds for trying the next provider after a fetch that fails, so every announced provider is a candidate the way advertisements are for calls. What still matters, and is still mandatory, is (1)'s analogue for content_announcement: the signer must equal the announcer_node it claims (the check macula:find_content_providers/2 makes too), so an attacker cannot at least misattribute who is claiming to serve what.