api

Overview ¶

Package api pkg/deployment/ar/api/api.go c4-net-discovery

Package api pkg/deployment/ar/api/bind_ingest.go c4-net-discovery

AR-bind-over-CXO ingest: the server side of the fan-in path where visors publish their AR bindings as a CXO feed instead of re-registering over a fresh dmsg stream on a timer (each with a full Noise handshake — the secp256k1 handshakeResponder that dominates AR CPU). The CXO aggregator (pkg/deployment/ar/regcxo) calls IngestBindFromCXO for each bind leaf it replicates.

This is purely ADDITIVE and dual-write: the HTTP POST /bind and the SUDPH UDP registration remain the authoritative path and keep writing the same store. The CXO ingest therefore never clobbers a fresh HTTP/UDP bind:

• When a record already exists (the common case — HTTP/UDP bound first), the CXO ingest is a keepalive: it re-writes the STORED VisorData to refresh its TTL, off a warm CXO connection instead of a fresh handshake. It writes back exactly what is there, so it can never overwrite a newer HTTP/UDP address (mirrors dmsg-discovery's equal-sequence keepalive, which refreshes off the stored entry, not the incoming one).
• When no record exists yet, only the address-POST types (STCPR/QUIC/WT) take a fresh insert, reconstructed from the visor's DECLARED addresses exactly as the HTTP bind handler does in the production dmsg-routed case (where the observed source is the dmsg bridge and the handler falls back to the declared PublicIP). SUDPH is keepalive-only: its stored address is the UDP-observed NAT-mapped endpoint, which the declared payload cannot reproduce, so a fresh SUDPH record is left to the UDP path.

Package api pkg/deployment/ar/api/charts.go

Package api pkg/deployment/ar/api/cxo_publisher.go c4-net-discovery

CXO publisher for the address-resolver's bindings, keyed by peer public key.

Until now the AR published no CXO feed at all: visors push their bindings in over CXO (pkg/deployment/ar/regcxo) and nothing comes back, so the ~1.5k warm CXO connections the AR already holds carry traffic in one direction only. This adds the read side, in the shape a per-dial address lookup wants — see pkg/deployment/ar/arfeed for the tree layout and why it is 256 always-present buckets rather than a flat per-peer level or a per-server batch.

Purely additive: HTTP GET /resolve stays authoritative and unchanged, and the feed is inert until something subscribes to or previews it.

Where the data comes from ¶

Two sources, because neither alone is both fresh and correct:

• Every write to the store marks (peer, type) dirty. The worker resolves the STORED record for that pair on the next flush and re-encodes the peer's bucket. Resolving rather than trusting the value passed to Bind matters: the redis store merges IPv4/IPv6 families across two separate binds, so only the stored record is the whole truth.
• A periodic full resync rebuilds the state from the per-type index. This is what removes peers whose binding TTL'd out — an expiry never calls DelBind, so an incremental-only publisher would keep stale addresses forever.

Both run on one worker goroutine, so the state map needs no lock, and the store writes never block on the publisher: marks go through a buffered channel and are dropped (counted) on overflow. A dropped mark costs at most one resync interval of staleness for that peer.

Package api pkg/deployment/ar/api/dial_assist_log.go c4-net-discovery

Rate accounting for the SUDPH reverse dial-assist, whose "peer is not connected" outcome used to be logged once per attempt.

On a /resolve of type sudph the AR also nudges the RECEIVER to dial the sender, so both sides punch at once. That nudge needs a live UDP control connection from the receiver; when the receiver is offline (or its AR record is stale) there is none and askToDialUDP returns ErrNotConnected. The sender's /resolve response has already been written at that point — nothing is lost but the simultaneous-open optimisation, and the sender still dials. It is a routine outcome of a network where visors come and go.

Measured on the live deployment it was also 94,752 log lines in ten minutes — ~9,475/min against 2,450/min for the entire transport-discovery and 38/min for the route-finder. That is a real disk and IO cost, and it buried every other address-resolver diagnostic.

A per-peer rate limit was rejected: the cardinality IS the signal here (thousands of distinct offline peers), so per-peer state would grow with the fleet while still emitting a line per newly-seen peer. A plain demotion to Debug was rejected too: it makes the condition invisible at the level operators actually run, and the RATE is what tells them whether something is wrong (a jump from ~9k/min to ~90k/min matters; the individual line does not). Aggregation keeps the rate, the distinct-peer count and the worst offenders, at one line per window; the individual event stays available at Debug for anyone who raises the level.

Package api pkg/deployment/ar/api/reach.go c4-net-discovery

The reach book: per peer, what is known about whether it can actually be transported, published as the reach feed (see arfeed/reach.go for the record and why each type is judged the way it is).

Three inputs, all local to the AR:

• probes — every stcpr / squicr / swtr binding is dialed back from here when it appears or its address changes, and again every probeEvery.
• the sudph UDP control connection — up or down, as the UDP loop sees it.
• the visor's own declaration, the "reach" leaf of its AR-bind feed.

A peer's record is dropped once it has neither a binding nor a fresh declaration. Everything is in memory: after a restart the probes re-run as bindings are refreshed and every visor's feed is re-filled, so the book rebuilds itself within one keepalive.

Package api pkg/deployment/ar/api/udp_resolve.go