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¶
- Open
/ws/controlat the page's API origin withrfsentry-control-v1. Its WebSocketOriginmust be explicitly allowed; missing origins fail too. - Query
auth.statusfor the effective access policy. The workstation usesbrowser.sessionto resume a tab session or obtain anonymous local access when sign-in is disabled. When sign-in is required,browser.loginsends the appliance username and password over the secure control WebSocket. Receiver control requires administrator access. Native clients useauthwith a credential scoped to their operation. See browser access. - Request
stream.endpoint. Its payload suppliesport,scheme,pathandprotocol, not an arbitrary hostname or credential destination.resolveIqEndpointkeeps 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. session.openreturns an ack containingsessionIdand a separateiqToken. The asynchronoussession.readydescribes acquisition state; an open-session ack is not proof of ready IQ or decoder synchronization.- 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.