Skip to content

API and browser contracts

This page summarizes the primary runtime boundaries. JSON schemas under components/rfsentry-web/schemas/ remain the machine-readable authority for decoder and analysis records.

The component transport reference describes the control handshake and binary IQ frames in detail.

HTTP endpoints

The same gateway process exposes two external TLS listeners. Public API_PORT / STREAM_PORT come from /etc/rfsentry/appliance.conf; the generated gateway configuration calls the API port PORT. Defaults are 8443/8444, not fixed endpoints or additional receiver connections.

Listener Path Purpose
API / React application
API /docs/ this static documentation
API /healthz bounded gateway health response
API /api/v1/enrichment/capabilities canonical origin/FCC relay capability
API /api/v1/enrichment/fcc/amateur fixed-source bounded FCC relay
API /ws/control JSON WebSocket, rfsentry-control-v1
API /ws/records Decoded-record delivery, rfsentry-records-v1
IQ /ws/iq session-bound WebSocket, rfsentry-iq-v1

The IQ listener is not another UI/API server. Ordinary HTTP there returns 404; the IQ protocol checks the dedicated listener, exact /ws/iq path and allowed UI origin. The API listener rejects IQ. There is no silent fallback to the API port. Both listeners share the certificate and existing receiver leases.

Static docs use their own narrow security headers because Material's generated bootstrap is inline; the React application retains its stricter application CSP and cross-origin isolation. Both load runtime assets only from the same origin. The separate IQ port is an intentional WebSocket connection, not a second browser-storage origin. See identity/TLS and IQ priority for provisioning and activation.

Discovery, authentication, and binding

  1. Open /ws/control at the page's API origin with rfsentry-control-v1. Its WebSocket Origin must be explicitly allowed; missing origins fail too.
  2. Query auth.status for the effective access policy. The workstation uses browser.session to resume a tab session or obtain anonymous local access when sign-in is disabled. When sign-in is required, browser.login sends the appliance username and password over the secure control WebSocket. Receiver control requires administrator access. Native clients use auth with a credential scoped to their operation. See browser access.
  3. Request stream.endpoint. Its payload supplies port, scheme, path and protocol, not an arbitrary hostname or credential destination. resolveIqEndpoint keeps the page hostname, requires a different valid port, exact path/protocol and matching WSS scheme. Plain WS is permitted only for the explicit loopback test path. Discovery failure closes control.
  4. session.open returns an ack containing sessionId and a separate iqToken. The asynchronous session.ready describes acquisition state; an open-session ack is not proof of ready IQ or decoder synchronization.
  5. The lane's ingress worker opens the discovered IQ socket, then sends {"type":"stream.bind","token":"<session iqToken>"} as its first text message. The gateway binds the token to an active, currently unbound session. Binary framed IQ then arrives independently of control events.

The gateway issues an iqToken for each open session, including sessions opened under anonymous local access. Keep session and machine credentials out of URLs, logs and exports. The bind has a ten-second server timeout; a second application message after binding closes that IQ connection. An ingress connected notification means the socket opened and binding was sent, not that the server acknowledged binding or a valid frame arrived.

Multiple adapters reuse these same two listening ports. Each active lane has its own session/token, IQ socket and bounded queue, using the existing receiver lease rather than opening another SDR. Control disconnect releases only its owned sessions; IQ disconnect releases its bound session. An IQ-only reconnect can use surviving authorized control, but needs a new session/token. A new control connection repeats authentication/discovery. Never reuse a released token or reset another lane. Explicit session.close honors route release grace; disconnect requests immediate gateway release, followed by the demand manager's own idle/deep-idle deadlines.

Control envelope

Requests use version 1. This example's route must exist in receiver.list; it is not a universal receiver or a request to start a protocol decoder:

{
  "id": "web-17",
  "type": "session.open",
  "version": 1,
  "payload": {
    "laneId": "primary",
    "rfHz": 1090000000,
    "sampleRate": 2400000,
    "centerOffsetHz": 0,
    "routeId": "adsb1-direct",
    "mode": "WFM"
  }
}

After authorization, tuning clients use stream.endpoint, receiver.list, session.open, session.tune, and session.close. receiver.configure uses the tune handler; ping is a control health request. Explicit appliance job.* configuration/status controls and their distinct read/control credentials are documented in continuous decoding. Job commands use /ws/control. Readers subscribe to decoded output on the same API listener through /ws/records. Responses are ack or error correlated by requestId. Asynchronous events carry gateway-wide eventSequence, not a lane-contiguous IQ sequence or sample counter. No per-lane event-sequence gap should be interpreted as lost IQ.

session.ready reports observed receiver/route state including RF center, tuner frequency, sample rate, tuner capability/type, supported gain steps, requested/applied gain, offset-tuning capability/request/effect, physical LO where derived, and a UTC/monotonic clock anchor. Readback fields remain false when the underlying RTL-TCP protocol cannot prove hardware readback. A derived physicalTunerLoHz is separate from the commanded tunerHz in IQ headers.

Binary IQ frame

The live gateway emits v1.0: an 80-byte big-endian header followed by unsigned 8-bit interleaved I, Q payload. Maximum live payload is 65,536 bytes (32,768 complex samples); a post-quarantine frame may be shorter. Browser protocol definitions also support CS16LE/CF32LE for other paths, but the current live gateway emits CU8 only.

Offset Field
0 magic WSDR
4 / 5 major / minor version (u8 each; emitted 1 / 0)
6 header length (u16, 80)
8 transient frame flags (u32)
12 sample format (u32; 1 = CU8)
16 frame sequence (u64)
24 first payload complex-sample counter (u64)
32 completed block's monotonic timestamp ns (u64), not UTC
40 commanded tuner center Hz (u64), not driver-offset physical LO
48 logical capture RF center Hz (i64), not the independently selected browser VFO
56 sample rate Hz (u32)
60 complex sample count (u32)
64 gain in tenths of dB (i32 representation)
68 PPM × 1000 (i32 representation)
72 payload bytes (u32)
76 capture options, including offset tuning (u32)

The gain field is command-path metadata, not measured gain readback; INT32_MIN (-2147483648) denotes automatic tuner gain. Transient flag bits are Gap 0x01, Overflow 0x02, Retuned 0x04, SettingsChanged 0x08, Replay 0x10 and End 0x20. Replay is defined in the browser protocol, not emitted by the live gateway; a live socket close is not a promise of a final End frame. Capture-options bit 0x01 records the applied driver-offset-tuning state persistently, not a one-frame change or independent hardware verification.

The browser parser checks magic, major version, header length, sample format and exact payload length. decodeIQFrameView returns a non-owning payload view; its backing transport slot must remain valid until consumption finishes. decodeIQFrame returns an owning payload copy for other callers. These checks validate transport framing, not protocol CRC/FEC or receiver continuity.

Queueing and release

Each session's source-rate-sized queue targets two seconds plus framing rounding. Capacity is ceil(sampleRate × 2 / 32768) + 1 full-frame slots: 148 at 2.4 MS/s, 197 at 3.2 MS/s. This is a finite scheduling cushion, not end-to-end latency or a loss-free guarantee. At 2.4 MS/s the nominal CU8 payload rate is 4.8 MB/s; queue slots/headers, socket/TLS buffers and browser consumers add their own allocations. These are calculated sizes, not measured resident memory.

Overflow drops a complete oldest queued frame, increments drop counters and marks the newly enqueued frame Gap/Overflow. Older queued frames may be sent first; sequence/sample-counter discontinuities identify the actual lost range. More than 512 consecutive enqueue overflows sets the slow-client close flag; dequeuing a frame resets that counter. Writable processing closes that IQ peer, whose disconnect releases only its session. The reader continues draining upstream instead of letting the queue grow indefinitely.

Quarantine advances the sample counter over discarded settling samples and keeps the next change flags. Session release frees its queue; other lanes keep their independent queues/leases. See failure boundaries for the wider required isolation/acceptance contract.

Source anchors: gateway src/server.c, src/receiver.c, src/util.c and include/rfsentry_api.h; browser src/api/RfsentryClient.ts, src/transport/iq.ingress.worker.ts and src/protocol/iqFrame.ts. Regression references include test_iq.c, the mock integration harness, rfsentryClient.test.ts and iqFrame.test.ts. This documentation reconciliation does not imply a new live/auth/continuity qualification.

Decoder manifest and event schemas

Manifest v2 declares:

  • identity, version, families, and description;
  • domain, exact rational sample rates, modes, bandwidth and channel policy;
  • UTC/continuity requirements;
  • ABI target, content-addressed asset, build inputs and hashes;
  • outputs and event kinds;
  • automatic launch and recommendation evidence;
  • receiver/path compatibility;
  • memory/time/queue/media/event limits; and
  • SPDX/source/revision/notice provenance.

Machine-readable sources are schemas/decoder-manifest-v2.schema.json, schemas/decoder-event-v2.schema.json and src/decoder/types.ts under the browser component. The draft WEBSDR field lists are not additional schema properties. Per-decoder gain/AGC/squelch/de-emphasis/follow defaults are not manifest fields today; shared receiver and assisted-activation policy own them.

Event fields and presentation

Actual v2 field Meaning / display boundary
eventId, decoderId, jobId, laneId, receiverSerial, pathProfileId, target stable event/job/input identity; a receiver alias is joined from inventory, not a universal event field
capture sample/capture/clock epochs, exact rational source position, capture UTC or explicit absence, uncertainty and discontinuity
signal.rfReferenceHz, decoderReferenceHz, inputRateHz, inputBandwidthHz RF and decoder/input reference geometry in Hz; not interchangeable with audio frequency
signal.frequencyOffsetHz, timeOffsetMs, snrDb, ber, merDb nullable decoder-supplied metrics with domain-specific meaning; DT is not arrival delay or a sample counter
signal.serviceId, programId nullable service/program identity where applicable
validation separate synchronization, CRC, FEC and explicit validated state
observedAt event timestamp; interpretation depends on the producer and available capture clock
kind, confidence typed event class and nullable decoder score; neither is validation or a calibrated probability
payload, media bounded protocol detail and media descriptors; text, callsigns, grid/position or product fields exist only where supplied

There is no universal top-level mode, decoded text, callsign, location, summary or search string. Manifest/job context supplies mode/input semantics; protocol adapters interpret payloads for station, aviation and SATCOM consumers. Their shared map adapters do not imply implemented AIS/APRS/radiosonde decoders.

decoderEventPresentation.ts derives concise summaries, searchable text and evidence from normalized records and caches them by event-object identity with WeakMap. These are presentation projections, not new persisted schema fields. Decoder-aware columns can hide irrelevant values; JSON/CSV export still preserves the normalized record. Raw-payload formatting stays on explicit detail inspection, not every incoming row.

Validation and timestamp boundaries

Synchronization is none, searching, locked or lost. CRC is not-applicable, unknown, passed or failed; FEC additionally distinguishes corrected. validation.validated is an explicit decoder verdict, used by Validated only. A message event, sync lock, unknown check, corrected frame and completed product are not equivalent validation stages.

For generic protocol events, decoder.worker.ts uses capture UTC for observedAt when available and a processing-time fallback otherwise. FT events use their slot timestamp. The fallback does not repair missing capture time: capture.sampleTimeUnixNs and clockQuality remain the evidence authority. Never relabel processing/arrival time as acquisition UTC or use repeated display timestamps to reconstruct source sample timing.

Time contract

Gateway sessions pair realtime and monotonic nanoseconds plus uncertainty and an epoch. The pair refreshes during active sessions; a material realtime step creates a new epoch. Decoder block timing maps exact channelizer delay and rational resampler phase back into the hardware sample domain.

Anchors and sample counters

session.ready and periodic clock.anchor events carry decimal nanosecond strings for the paired UTC/monotonic clocks and measured uncertainty. The gateway samples monotonic time around its realtime read: the midpoint forms the pair and half the span contributes uncertainty. That clock-pair measurement does not prove the SDR's absolute sample acquisition time.

IQ-header monotonic time describes a completed transport block, including callback/scheduling effects. DecoderClockMapper derives its first-sample estimate using the exact block duration, binds UTC once per capture epoch, and advances subsequent times from source sample-counter differences and rate. Block duration contributes explicit transport uncertainty. Rebinding every received block independently to UTC would turn callback jitter into gaps or negative timing offsets.

ABI 1.2 block metadata includes:

Field Meaning
decoderSampleCounter job-local first output-sample counter
sampleTimeUnixNs first output-sample UTC, or null when unavailable
sourceSamplePositionNumerator / sourceSamplePositionDenominator exact position in the source-IQ sample domain, including resampler phase/delay
clockEpoch / epochId clock pairing and capture continuity identities
discontinuity / reason source, timing, settings, queue, or presentation boundary

WasmDecoderChannelizer accounts for multistage FIR group delay and rational phase when mapping output back to source positions. Splitting identical IQ into different transport frames must not alter that mapping. FT8/FT4 then bind their UTC-slot sample bias once and advance from decoderSampleCounter, rather than placing each incoming chunk independently on the slot grid.

Missing time and discontinuities

Source gaps/overflows, counter/rate changes, retunes, settings changes, material clock-epoch changes, and historical seeks invalidate affected stream/slot state. Source-IQ loss, decoder-queue loss, clock changes, and reset counts remain separate diagnostics; a total sample count is not proof of contiguous reception.

SigMF capture datetime or an explicit raw-capture timestamp supplies replay-metadata timing. Absent or malformed metadata remains unavailable; UTC-required manifests reject an absent or overly uncertain anchor. An event's display/processing timestamp must never be treated as capture UTC when its capture stamp says unavailable. Browser arrival time is not an undisclosed replacement evidence clock.

Keep suppressed-carrier/VFO RF, occupied bounds, decoder search bounds, and protocol grid/dial references distinct. An asymmetric real-audio search window and a complex-IQ bandwidth have different Nyquist geometry; validation uses the manifested input domain, not one universal bandwidth check.

JavaScript cannot safely represent arbitrary nanosecond u64 values as ordinary numbers, so API types retain them as strings or BigInt at the appropriate boundary. Millisecond-rounded display is not the evidence clock.

Source and acceptance reconciliation

ADR 0007-session-sample-clock.md records the original anchor design. Its then-future periodic refresh is implemented by server.c and the later accepted 6B.1A — Exact Timing and Reference Contracts in docs/roadmap/decoders.md. Read that checkpoint and 6B.1B alongside the ADR; do not reintroduce per-frame UTC rebinding or promote substrate timing proof into protocol qualification.

Implementation: components/rfsentry-api/src/util.c and server.c, plus src/decoder/ClockMapper.ts, WasmDecoderChannelizer.ts, and FtxDecoder.ts under the browser component. decoderClock.test.ts, decoderChannelizer.test.ts, decoderContinuity.test.ts and ftxDecoder.test.ts cover the corresponding contracts. These are regression references, not tests newly run for this page.