node-red-contrib-ntrip 0.2.2 → 0.2.7

package/doc/architecture/behavioural-design.md

@@ -0,0 +1,226 @@
+# Behavioural Design
+
+## Node-RED node lifecycle
+
+Every node in this package follows Node-RED's standard lifecycle:
+
+```
+deploy / restart
+      │
+      ▼
+   constructor(config)              ← create network resources, reset counters
+      │
+      ▼
+   on('input', msg) ──── many ────► (transform / forward / write to socket)
+      │
+      ▼
+   on('close', done)                ← release resources, clear status, done()
+```
+
+The constructor receives a `config` object built from the editor form. The
+input handler is called for every message flowing into the node. The close
+handler runs on flow redeploy or Node-RED shutdown.
+
+## NtripClient — handshake state machine
+
+The `NtripClient` node intercepts the caster's first reply line and uses it to
+set its own status. Prior to v0.2.5 this check ran on **every** inbound TCP
+packet, which both inflated the message counter and risked dropping RTCM bytes
+that shared a TCP segment with the handshake reply. The current design is a
+two-state machine:
+
+```
+              start
+                │
+                ▼
+          ┌──────────────┐  data: "ICY 200 OK\r\n\r\n..."   ┌─────────────┐
+          │ disconnected │ ───────────────────────────────► │  connected  │
+          │              │  data: "ICY 406 ..."             │             │
+          │              │ ──────► error, stay disconnected │             │
+          │              │  data: "SOURCETABLE 200 OK..."   │             │
+          │              │ ──────► error, stay disconnected │             │
+          │              │  data: anything else             │             │
+          │              │ ──────► forward, transition to ─►│             │
+          └──────────────┘                                  └──────┬──────┘
+                ▲                                                  │
+                │              socket close / error                │
+                └──────────────────────────────────────────────────┘
+```
+
+Key behaviours:
+
+- **Transitional bytes are not lost.** When the handshake reply and the first
+  RTCM frame share a TCP segment (common), the node splits at the `\r\n\r\n`
+  header terminator and forwards the trailing RTCM bytes on the output.
+- **Reset on close.** The `connected` flag is set back to `false` when the
+  socket closes, so the next reconnect runs the handshake recognition again.
+- **Counters track Rx and Tx separately.** `messagesReceived` is only bumped
+  for data forwarded after handshake (not control replies). `messagesSent` is
+  bumped per input message written to the caster.
+
+See [ADR-0004](adr/0004-stateful-handshake-interception.md).
+
+## NtripClient — input handling
+
+```
+   msg.payload arrives
+       │
+       ▼
+   payload nullish? ─yes─► drop (no-op)
+       │ no
+       ▼
+   Array.isArray(payload)? ─yes─► client.setXYZ(payload)   # update GGA seed
+       │ no
+       ▼
+   client.write(payload)
+       │
+       ▼
+   node.passthrough? ─yes─► node.send(msg)                 # echo on output
+       │ no
+       ▼
+   updateStatus()
+```
+
+An `Array` payload is interpreted as a coordinate triple `[x, y, z]` and routed
+to the underlying client's `setXYZ` method — used by Sapos and other VRS
+casters that gate the stream on a `GGA` from the client. A non-array payload
+is written verbatim to the caster.
+
+## NtripClient — outbound write error handling
+
+`net.Socket.write` is asynchronous; runtime failures (ECONNRESET, EPIPE) come
+through the socket's `error` event rather than as synchronous throws. The node
+therefore has two error paths:
+
+- **Synchronous** — the try/catch around `client.write` catches misuse
+  (`client` undefined, wrong-shape payload), reports via `node.error` and
+  flashes the status badge red.
+- **Asynchronous** — the socket `error` listener calls `node.error` with the
+  same wording. `AggregateError` instances (e.g. from happy-eyeballs DNS
+  resolution failures) are expanded into one log line per inner error.
+
+## RtcmDecoder — frame reassembly across input events
+
+RTCM 3 frames are variable-length and routinely cross TCP packet boundaries.
+The decoder keeps a `pendingBuffer` on the node instance and reassembles:
+
+```
+   on('input', msg):
+       chunk = msg.payload                            (Buffer or coerced)
+       buffer = concat(pendingBuffer, chunk)
+
+       loop while buffer not empty:
+           try: [message, length] = RtcmTransport.decode(buffer)
+           on throw:
+               if buffer.length > 64KB:
+                   emit error on output 2
+                   buffer = empty
+               break   # keep remainder for next input event
+           if length not positive or > buffer.length:
+               break   # defensive zero-length guard
+           emit decoded message on output 1
+           buffer = buffer.slice(length)
+
+       pendingBuffer = buffer
+       updateStatus()
+```
+
+- **Partial-frame tolerance.** A throw is interpreted as "frame may be incomplete";
+  bytes stay in `pendingBuffer` to be re-tried with the next chunk.
+- **Garbage cap.** If `pendingBuffer` grows past 64 KB without ever decoding a
+  frame, the data is flushed to the error output and the buffer is cleared —
+  prevents runaway memory if the upstream feeds non-RTCM bytes indefinitely.
+- **Forward-progress guarantee.** A non-positive or oversized `length` from the
+  decoder breaks the loop rather than spinning.
+
+See [ADR-0005](adr/0005-rtcm-partial-frame-buffer.md).
+
+## NmeaDecoder — multi-sentence splitting
+
+A single input chunk may carry several `\r\n`-delimited sentences. The decoder
+splits and decodes each independently:
+
+```
+   on('input', msg):
+       rawInput = msg.payload.nmeaMessage ?? msg.payload   (preserved untouched)
+       rawString = Buffer? rawInput.toString('utf8') : rawInput
+
+       for each sentence in rawString.split(/\r?\n/):
+           sentence = sentence.trim()
+           skip if empty
+           try: NmeaTransport.decode(sentence) → emit on output 1
+           on throw: emit on output 2 with
+                input:       rawInput   (Buffer if Buffer was supplied)
+                inputString: rawString  (utf8 form)
+```
+
+- **`input` preservation.** The original payload (`Buffer` if a `Buffer` was
+  supplied) is carried through to the error output unchanged — restored in
+  v0.2.6 after a regression in v0.2.5 forced everything through `toString`
+  before storing.
+
+See [ADR-0006](adr/0006-nmea-multi-sentence-split.md).
+
+## NmeaEncoder — instance passthrough vs construction
+
+The encoder accepts two input shapes:
+
+- A pre-constructed `NmeaMessage*` instance — passed straight to
+  `NmeaTransport.encode` without inspection.
+- A plain field object plus a `messageType` discriminator — fed through a
+  `switch (messageType)` that maps to the right `NmeaMessage*.construct(input)`
+  factory.
+
+```
+   on('input', msg):
+       require payload, payload.nmeaMessage, payload.messageType  (else error output)
+
+       try:
+           messageType = String(payload.messageType).toUpperCase()
+           input = payload.nmeaMessage
+
+           if input instanceof NmeaMessage:
+               nmeaMessage = input
+           else:
+               nmeaMessage = NmeaMessage<Type>.construct(input)
+               unknown messageType → throw (caught and routed to error)
+
+           message = NmeaTransport.encode(nmeaMessage)
+           emit on output 1
+
+       on throw: emit on output 2 (no node.error)
+```
+
+## Two-output error routing
+
+Every decoder/encoder uses the `[ok, error]` two-output convention rather than
+calling `node.error()` for per-message failures. The reason is that high-rate
+streams routinely emit mismatched binary (the README explicitly suggests
+wiring an NMEA decoder onto an RTK2Go stream as a demonstration) — calling
+`node.error` for each failure floods the Node-RED `[error]` log. The error
+output is the channel; wire it to a debug or downstream handler.
+
+See [ADR-0003](adr/0003-two-output-decoder-design.md).
+
+## Status badge convention
+
+All four nodes follow the same rule for the badge under the node in the
+Node-RED editor:
+
+| State | Fill | Shape | Text |
+|-------|------|-------|------|
+| starting | yellow | ring | `connecting...` (NtripClient only) |
+| running | green | ring | counters, e.g. `Rx 123 Tx 4` / `NMEA: 12 Invalid: 0` |
+| connected (NtripClient) | green | ring | `NTRIP server connected.` |
+| handshake error | red | ring | `NTRIP server rejected connection.` or `No mountpoint <name>` |
+| write/decode error | red | ring | error message |
+| closed | (cleared) | — | — |
+
+## Close behaviour
+
+| Node | On `close` |
+|------|------------|
+| NtripClient | `client.removeAllListeners()`, then `client.close()`, clear status. |
+| RtcmDecoder | Discard `pendingBuffer`, clear status. |
+| NmeaDecoder | Clear status. |
+| NmeaEncoder | Clear status. |

package/doc/architecture/errors-and-weaknesses.md

@@ -0,0 +1,71 @@
+# Errors and Weaknesses
+
+This chapter inventories known limitations. Items are grouped by severity and
+labelled by status (Open / Fixed-in-vX.Y.Z / Accepted as design constraint).
+
+## Critical
+
+| ID | Description | Status |
+|----|-------------|--------|
+| C-1 | `NmeaEncoder` instance passthrough was broken (`input.prototype instanceof NmeaMessage` always false) | Fixed in 0.2.4 |
+| C-2 | `NmeaEncoder` catch block referenced an out-of-scope `input`, crashing on every encoder failure | Fixed in 0.2.4 |
+| C-3 | `NtripClient` crashed at construction when `mode` was neither `download` nor `upload` (`client.on('data',…)` on `undefined`) | Fixed in 0.2.5 |
+| C-4 | `RtcmDecoder` dropped any partial frame at TCP packet boundaries (no carry-over) | Fixed in 0.2.5 |
+| C-5 | `NmeaDecoder` only decoded the first sentence of a multi-sentence chunk despite documentation claiming otherwise | Fixed in 0.2.5 |
+| C-6 | `NmeaDecoder` and `RtcmDecoder` called `node.error()` for every decode failure — flooded the Node-RED log when fed mismatched binary (the README's own demo wiring) | Fixed in 0.2.6 |
+| C-7 | `NmeaDecoder` error output stored the `toString`-converted form on `input`, losing the original `Buffer` | Fixed in 0.2.6 |
+
+## High
+
+| ID | Description | Status |
+|----|-------------|--------|
+| H-1 | Always-on handshake check on every data packet — risked dropping RTCM bytes that shared a TCP segment with the `ICY 200 OK` reply | Fixed in 0.2.5 |
+| H-2 | Coordinate guard `x && y && z` silently dropped axis-aligned positions (e.g. equator) | Fixed in 0.2.5 |
+| H-3 | `NmeaEncoder` unknown `messageType` silently emitted `nmeaMessage: undefined` on the success output | Fixed in 0.2.4 |
+| H-4 | `client.write` rejection errors were not visible (async — not caught by the surrounding `try`) | **Open.** Async write failures now surface via the socket `error` listener, but no per-input error feedback. |
+| H-5 | RTCM/NMEA decoder loop had no zero-length-progress guard — theoretical infinite loop | Fixed in 0.2.5 |
+
+## Medium
+
+| ID | Description | Status |
+|----|-------------|--------|
+| M-1 | Password input rendered as `type="text"` in the editor form | Fixed in 0.2.5 |
+| M-2 | CR/LF injection possible via `mountpoint`/`username`/`password` (interpolated into the handshake string) | Fixed in 0.2.5 — rejected at construct time |
+| M-3 | `AggregateError` referenced unconditionally; ReferenceError on Node ≤ 14 | Fixed in 0.2.5 — `typeof` guard, and `engines.node` bumped to ≥ 18 |
+| M-4 | `host` accepted as `""`/`null`; `interval` forwarded as a raw string | Fixed in 0.2.5 |
+| M-5 | Counter `messagesReceived` mixed inbound, outbound, and handshake replies | Fixed in 0.2.5 — split into `Rx`/`Tx` |
+| M-6 | No connection-state event on the `NtripClient` output — downstream flows can only react to the status badge text | **Open.** See [Future Improvements](future-improvements.md). |
+| M-7 | Listener leaks on `client.close()` — accumulated across reconnects | Fixed in 0.2.5 — `removeAllListeners` on close |
+
+## Low
+
+| ID | Description | Status |
+|----|-------------|--------|
+| L-1 | `engines.node: ">=7.6.0"` was inconsistent with code that uses `AggregateError` and the CI matrix (18/20/22) | Fixed in 0.2.5 — bumped to `>=18.0.0` |
+| L-2 | Editor help text was stubs (`<p>.</p>`) for three of four nodes | Fixed in 0.2.6 — full `<dl class="message-properties">` blocks |
+| L-3 | Decoders/encoder kept the original input attached to every output message (memory pressure for high-rate streams) | **Open.** Cost is one Buffer reference per emission. |
+| L-4 | `'socket timeouted'` typo in the upstream socket error message | Fixed in 0.2.5 |
+| L-5 | NMEA case `'Object'` was unreachable because `messageType.toUpperCase()` ran first | Fixed in 0.2.4 |
+
+## Open design-level constraints
+
+These are *accepted* limitations — documented rather than fixed, because the
+fix would be a significant architectural change.
+
+- **NTRIP over plaintext TCP only.** No NTRIPS / TLS support. NTRIP V2 over TLS
+  is a real protocol but the upstream `ntrip-client` package does not implement
+  it, and this contrib does not bring its own transport layer. See
+  [Future Improvements](future-improvements.md).
+- **`_connect()` full replacement** (not delegation) in
+  [ntrip/lib/ntrip-client.js](../../ntrip/lib/ntrip-client.js). Improvements to
+  the upstream client's connection logic (keep-alive, IPv6 handling, TLS
+  upgrade) won't propagate into the uploader path. See
+  [ADR-0002](adr/0002-ntrip-uploader-extension.md).
+- **`credentials` block must be declared in two places** — both the JS
+  `registerType` and the HTML `RED.nodes.registerType`. Drift is detectable
+  only at runtime when persistence silently fails.
+- **No per-node integration tests for `NtripClient`** — the unit test stack
+  covers the three pure transformer nodes only. The client requires a fake TCP
+  server for meaningful testing; see [Future Improvements](future-improvements.md).
+- **Editor HTML help text duplicates much of the runtime documentation** — any
+  schema change to a `payload` shape needs two updates (code + help text).

package/doc/architecture/future-improvements.md

@@ -0,0 +1,130 @@
+# Future Improvements
+
+These are *new capability* items rather than refactors. They would change
+behaviour visible to the user, and most warrant a minor version bump
+(0.3.0+) or a major one if they break the public message shape.
+
+## Protocol / network
+
+### NTRIPS (NTRIP over TLS)
+
+NTRIP V2 may run over TLS (typically port 2102, sometimes 443). The package
+currently relies on plaintext TCP via `net.createConnection`. Adding TLS would
+need:
+
+- A toggle in the editor form (`useTls: boolean`).
+- A separate `tls.connect` path in [ntrip/lib/ntrip-client.js](../../ntrip/lib/ntrip-client.js).
+- Optional CA bundle / SNI / certificate-pinning settings.
+- Documentation that NTRIPS handshake is identical to NTRIP V2 once the TLS
+  tunnel is established.
+
+Breaks no existing flow — pure additive.
+
+### Connection-state event output
+
+Today, downstream Node-RED flows cannot react to `NtripClient` reconnects,
+rejections, or handshake completion except by scraping the status badge text.
+Three implementation options, in order of disruption:
+
+1. Emit a tagged message on the existing output:
+   `{ payload: null, state: 'connected' | 'rejected' | 'reconnecting' }`.
+   Slightly viral — every downstream node must filter `payload != null`.
+2. Add a second output port for state events. Breaks layout of existing flows.
+3. Surface state via Node-RED's runtime event bus (`RED.events.emit`).
+   Non-breaking but requires opt-in from consumers.
+
+### NTRIP source-table fetch / mountpoint picker
+
+The branch `prepared getMountpoints: postponed…` (commit `38a243b`) indicates a
+prior attempt at fetching a caster's source table to populate a dropdown in
+the editor. The hold-up was that credentials are stored server-side and the
+editor JS can't access them. A workable approach: add a small admin endpoint
+(`RED.httpAdmin.get('/ntrip/sourcetable')`) that performs the fetch on the
+server using the stored credentials.
+
+## Test / quality
+
+### NtripClient integration tests
+
+Use `net.createServer` to stand up a fake caster that the test harness fully
+controls. Worth-testing scenarios:
+
+- Each `authmode` writes the correct handshake string.
+- `ICY 200 OK\r\n\r\n<rtcm>` reply: trailing bytes are forwarded.
+- `ICY 406`: error logged, status red, no data forwarded.
+- Mid-stream socket close: `connected` resets so the next handshake reply
+  re-enters the state machine.
+- `msg.payload = [x, y, z]` routes to `setXYZ` (verify via the upstream
+  client's internal GGA emission).
+- CR/LF in credentials: rejected at construct, no socket opened.
+
+### Coverage reporting
+
+Add `c8` (or `nyc`) as a dev dep and a `coverage` npm script. Currently
+Statistics shows "not measured"; a single CI badge changes that. Suggest a
+70 % statement coverage floor as a soft target — high enough to be useful, low
+enough not to require gymnastics on the rare error paths.
+
+### Linting
+
+Adopt `eslint` with `eslint-config-node-red-contribs` or the maintainer's own
+preference. Would have caught most of the regressions from 0.2.4 / 0.2.5
+(unused vars, `let` vs `const`, missing returns).
+
+### TypeScript types (`.d.ts`)
+
+The four nodes have a public message-shape contract (the `payload` schemas
+documented in the help text). Publishing JSDoc-derived `.d.ts` files would let
+TypeScript users in Node-RED's `function` nodes get autocomplete for
+`msg.payload.messageType`, `msg.payload.message.staX`, etc. Lightweight to
+add via `// @ts-check` and JSDoc on the existing JS source.
+
+## Editor UX
+
+### Per-node info-sidebar fixtures
+
+Add small example payloads to the help text so users can copy them straight
+into an `inject` node:
+
+```javascript
+// Example NmeaEncoder input
+msg.payload = { messageType: 'GGA', nmeaMessage: { /* fields */ } };
+```
+
+The HTML stubs added in 0.2.6 are documentation but no example flows are
+linked from the editor — only from the README. A `<a href="…/examples/…">`
+link inside each help block would close that gap.
+
+### Hide credentials when not needed
+
+When `mode === 'download'` and the caster doesn't require auth, the
+Username/Password fields are still shown. A small `oneditprepare` hide rule
+keyed on a "Requires authentication" checkbox would declutter the dialog.
+
+## Codec coverage
+
+### More NMEA sentence types
+
+The current encoder supports 17 sentence types. The `@gnss/nmea` library has
+more (e.g. `VBW`, `VDR`, `WCV`, …). Adding a case is one import + one
+`switch` arm; the test suite already covers the through-path, so each new
+type is ~5 LOC.
+
+### RTCM message-type filter
+
+A `messageTypeFilter: number[]` config (e.g. `[1005, 1077, 1087]`) on the
+decoder would let users drop frame types they don't care about *before* they
+reach downstream nodes. Reduces flow noise and downstream work.
+
+## Distribution / packaging
+
+### Publish `node-red` entries
+
+[package.json](../../package.json) `keywords` includes `"mmea"` (typo — should
+be `"nmea"`). Catalogue search misses are real downloads lost.
+
+### CI: publish on tag
+
+The `.github/workflows/npm-publish.yml` (out of scope here) already exists.
+Worth pairing with semantic-release or a manual tag-driven publish so the
+release cycle is auditable from GitHub.

package/doc/architecture/overview.md

@@ -0,0 +1,77 @@
+# Overview
+
+## What this package is
+
+`node-red-contrib-ntrip` is a Node-RED contribution package that adds four
+GNSS-related nodes to a Node-RED palette. The package is distributed via npm
+and consumed by users through Node-RED's "Manage palette" UI — there is no
+standalone application binary.
+
+The four nodes:
+
+| Node | Direction | Library | Purpose |
+|------|-----------|---------|---------|
+| `NtripClient` | network ↔ flow | [`ntrip-client`](https://github.com/dxhbiz/ntrip-client) (extended) | Connect to an NTRIP caster as either a *client* (download corrections) or a *server* (upload corrections to a mountpoint). |
+| `RtcmDecoder` | binary → object | [`@gnss/rtcm`](https://github.com/node-ntrip/rtcm) | Decode RTCM 3 binary frames into JavaScript objects. |
+| `NmeaDecoder` | text → object | [`@gnss/nmea`](https://github.com/node-ntrip/nmea) | Decode NMEA 0183 ASCII sentences into JavaScript objects. |
+| `NmeaEncoder` | object → text | [`@gnss/nmea`](https://github.com/node-ntrip/nmea) | The inverse — emit a NMEA sentence string from an object. |
+
+## Who uses it
+
+Practitioners building RTK/PPP/DGNSS pipelines in Node-RED — typically:
+
+- Receiving correction streams from a public NTRIP caster (RTK2Go, SAPOS,
+  Centipede, Onocoy) and forwarding them to a rover (e.g. an ESP32-XBee, an
+  RTKLib instance, a u-blox receiver) over TCP, Serial, MQTT.
+- Operating a private base station (e.g. RTKBase) and pushing corrections to a
+  caster for others to consume.
+- Logging or inspecting GNSS messages live for monitoring or debugging.
+
+## How the nodes fit together
+
+A typical flow looks like:
+
+```
+                                   ┌────────────────┐
+                                   │  RTCM Decoder  │──► (per-frame objects, output 1)
+                                   │                │──► (decode errors,    output 2)
+   ┌────────────────┐  RTCM bytes  └────────────────┘
+   │  NTRIP Client  │──────────────►
+   │   (download)   │              ┌────────────────┐
+   └────────────────┘              │  NMEA Decoder  │──► (per-sentence objects, output 1)
+                                   │                │──► (decode errors,        output 2)
+                                   └────────────────┘
+```
+
+```
+   ┌─────────────────┐   RTCM bytes  ┌────────────────┐
+   │  TCP In / RTK   │──────────────►│  NTRIP Client  │──► (caster replies, optional pass-through)
+   │  Base / etc.    │               │   (upload)     │
+   └─────────────────┘               └────────────────┘
+```
+
+For VRS / network-RTK casters that require a position fix from the client:
+
+```
+   ┌─────────────┐ msg.payload=[x,y,z] ┌────────────────┐
+   │ Position    │────────────────────►│  NTRIP Client  │──(internal: synthesise NMEA GGA periodically)──► caster
+   │ source      │                     │   (download)   │
+   └─────────────┘                     └────────────────┘
+```
+
+## Runtime model
+
+- **Pure JavaScript, no build step.** Files in [ntrip/](../../ntrip/) are loaded by Node-RED at startup.
+- **Single registration entry point** — [ntrip/99-ntrip.js](../../ntrip/99-ntrip.js) `require`s the four node implementations and calls `RED.nodes.registerType` for each. See [ADR-0001](adr/0001-single-registration-file.md).
+- **Editor HTML co-located** — all four node configuration dialogs and help text live in [ntrip/99-ntrip.html](../../ntrip/99-ntrip.html).
+- **Node ≥ 18** — runtime requires `AggregateError` and modern syntax.
+- **Stateless across restarts** — node configuration is persisted by Node-RED's flow file; the nodes themselves carry only in-memory state (counters, the NTRIP socket, the RTCM pending buffer).
+
+## Reading order for new contributors
+
+1. This file.
+2. [Structural Design](structural-design.md) — how files and modules relate.
+3. [Behavioural Design](behavioural-design.md) — runtime flow, state machines, error paths.
+4. [Architecture Decisions](architecture-decisions.md) — links to each ADR.
+5. [Errors and Weaknesses](errors-and-weaknesses.md) — current known limitations.
+6. [Statistics](statistics.md) — LOC, test count, and a simple quality index.

package/doc/architecture/refactoring-recommendations.md

@@ -0,0 +1,114 @@
+# Refactoring Recommendations
+
+Items below are *recommendations*, not blockers. They are ordered by leverage —
+the changes near the top would simplify the code or unlock further improvements;
+the ones near the bottom are nice-to-have polish.
+
+## 1. Split `NtripClient` node into mode-specific handlers
+
+[ntrip/nodes/ntrip-client-node.js](../../ntrip/nodes/ntrip-client-node.js) is the
+biggest file in the package (~180 LOC) and mixes:
+
+- Configuration parsing and validation
+- Coordinate gating
+- Download vs upload branching
+- Handshake state machine
+- Status badge updates
+- Input dispatch (Array → `setXYZ` vs Buffer → `write`)
+- Error coercion (AggregateError vs plain Error)
+- Close cleanup
+
+Suggested decomposition:
+
+```
+ntrip-client-node.js          (90 LOC — wiring, lifecycle, status)
+  ├── parse-config.js         (50 LOC — host/port/coords validation, returns options)
+  ├── handshake-state.js      (40 LOC — the `connected` machine + buffer-tail splitter)
+  └── input-router.js         (30 LOC — Array→setXYZ vs Buffer→write)
+```
+
+This unlocks per-piece unit tests (you can test `handshake-state.js` without a
+socket) and makes future protocol additions (e.g. NTRIP V2 keep-alive
+heartbeat) localisable.
+
+## 2. Pull the handshake protocol bytes into a constants module
+
+The four authentication-mode handshake strings live as template literals
+inside [ntrip/lib/ntrip-client.js](../../ntrip/lib/ntrip-client.js) `_connect`.
+Moving them to a `lib/handshake-protocols.js` table makes them:
+
+- testable without standing up a TCP server
+- comparable side-by-side
+- replaceable per-protocol when a caster requires a quirk header
+
+```javascript
+// lib/handshake-protocols.js
+module.exports = {
+    legacy:   ({mp, user, pw}) => user || pw
+        ? `SOURCE ${pw} /${mp}\r\nSource-Agent: NTRIP ${user}\r\n\r\n`
+        : `SOURCE ${mp}\r\n\r\n`,
+    hybrid:   ({mp, auth}) => `SOURCE ${mp}\r\nAuthorization: Basic ${auth}\r\n\r\n`,
+    ntripv1:  ({mp, ua, auth}) => `POST /${mp} HTTP/1.0\r\n...`,
+    ntripv2:  ({mp, host, port, ua, auth}) => `POST /${mp} HTTP/1.1\r\nHost: ${host}:${port}\r\n...`,
+};
+```
+
+## 3. Delegate `_connect` instead of replacing it
+
+Today `NtripClientUploader._connect()` is a full re-implementation of the
+upstream `NtripClient._connect()` — copy-paste of timeout/connect/data/end/
+close/error wiring with only the on-connect handshake string differing. Any
+fix to the upstream socket lifecycle won't reach the uploader.
+
+A delegation refactor: override only `_buildHandshake()` (a new hook) and call
+`super._connect()`. Requires either upstream cooperation or carefully scoping a
+local fork. See [ADR-0002](adr/0002-ntrip-uploader-extension.md).
+
+## 4. Generate the editor HTML from a schema
+
+[ntrip/99-ntrip.html](../../ntrip/99-ntrip.html) is ~470 lines, most of which
+is repeated `<dl class="message-properties">` markup for help text. A small
+build step (`prebuild` npm script + JS that reads a JSON/JS schema) would
+shrink the source and eliminate drift between code and help text. Trade-off:
+introduces a build step the package currently doesn't have.
+
+## 5. Stop attaching the raw `input` Buffer to every emitted message
+
+Decoders today emit `payload.input = <slice of the consumed buffer>` on
+success. For high-rate RTCM streams (~100 frames/s) this means each downstream
+node holds a reference to that buffer until it discards the message — extra GC
+pressure for no functional reason. An emit-on-error-only policy would halve
+memory churn.
+
+Caveat: callers may be using `input` for round-trip or replay tooling — would
+need a deprecation cycle.
+
+## 6. Pull the `updateStatus` helper into a shared mixin
+
+All four node files have a near-identical `updateStatus()` function. Extracting
+it to `lib/node-helpers.js` saves ~12 LOC × 4 files and provides one place to
+adjust the badge format. Marginal savings, but it also unlocks a single place
+to gate badge updates (e.g. throttle to 1 Hz for noisy streams).
+
+## 7. Validate the editor form on save, not on connect
+
+Currently the editor `validate:` callbacks only run for `host`/`mountpoint`/
+`port` (and were missing on `host`/`mountpoint` before 0.2.5). Stricter
+front-end validation (CR/LF rejection, mountpoint character class) avoids the
+"saved fine, fails at runtime" failure mode and surfaces errors in the editor
+ribbon.
+
+## 8. Replace `node.passthrough = config.passthrough || false` with a tagged
+   pass-through message
+
+When upload-mode pass-through is enabled, written bytes are re-emitted on the
+same output as caster replies, with no tag distinguishing them. A
+`msg._upload_echo = true` flag (or a second output port — breaking change) lets
+downstream nodes tell the streams apart without sniffing the payload.
+
+## 9. Extract common Mocha test helpers
+
+The three spec files share boilerplate (`helper.startServer` / `helper.unload`,
+flow factory, `helper.load(..., () => ... )` promise wrapping). A
+`test/helpers/load-node.js` that returns `{n1, ok, err, done}` would cut the
+spec files by ~30%.