feat(serial): serve the extension port UART over the network (ser2net or web console)

[conallob]

Closes jetkvm#1520

Summary

With the Serial Console extension loaded, the extension port UART (/dev/ttyS3) can now be reached over the network. A new Network Access setting has three options: Disabled (the default), ser2net (TCP) or Web console. This turns a JetKVM, or a rack of them, into a serial console server without SSH/developer mode or an external daemon.

ser2net mode: a native Go TCP listener. The port is configurable (default 2217), and so is the protocol:

• Raw TCP: bytes pass straight through (socat -,raw,echo=0 tcp:<ip>:2217).
• Telnet (RFC 2217): option negotiation (BINARY/ECHO/SGA/COM-PORT-OPTION), IAC escaping, and IAC BRK sends a real serial break (SysRq). RFC 2217 clients such as pyserial's rfc2217:// can set baud rate, data bits, parity and stop bits for the length of their session. The configured settings come back when they disconnect.
• There is no authentication, and the UI warns about this. The listener honours the "loopback only" setting (same bind logic as the web server). Ports 22, 80 and 443 are rejected.

Web mode: GET /serial/ws sits behind the existing auth middleware and cookie. It uses the library's default same-origin check (no InsecureSkipVerify), so another site can't use the auth cookie to reach the UART. Frames carry raw UART bytes both ways. A new device-only route, /serial, is a full-page xterm console on top of it, so the UART works in a plain browser tab without a WebRTC KVM session. The extension panel has an "Open Web Console" button.

Shared design

• Everything goes through the existing SerialMux, which stays the only reader and writer of the port. Network clients, the in-session WebRTC console and quick buttons don't race on the fd (this answers the concurrency question in the issue). Network input is echoed into the in-session console like typed input.
• UART reads are fanned out by a hub that never blocks the reader. A client that falls 256 reads behind is disconnected, so it can't stall the other clients.
• Concurrent clients are capped at 1 by default, configurable up to 8; for example, one interactive session plus log capture. Extra clients are refused with a message (TCP) or close code 1013 (WebSocket).
• Changing the mode, port or protocol, or unloading the extension, closes the listener and drops the connected clients. Re-applying unchanged settings keeps the sessions.
• A new RPC, getSerialNetworkStatus, reports whether it is running, the listen address, any bind error and the connected clients. The UI polls it.
• The settings live in serialSettings.json with the other Serial Console settings. Older files get the defaults, so the feature stays disabled.

Prometheus metrics (on the existing /metrics endpoint)

Metric	Type	Labels
jetkvm_serial_port_open	gauge 0/1	device
jetkvm_serial_port_info	info (1)	device, baud_rate, data_bits, parity, stop_bits, extension
jetkvm_serial_port_baud_rate	gauge	device
jetkvm_serial_network_info	info (1)	mode, protocol, listen_address
jetkvm_serial_network_up	gauge 0/1	mode
jetkvm_serial_network_max_clients	gauge	none
jetkvm_serial_network_clients	gauge	transport
jetkvm_serial_network_bytes_total	counter	transport, direction

The port and network metrics come from a collector that runs at scrape time. go.bug.st/serial can't read back a port's mode, so every open, close and SetMode now goes through setSerialPortMode and a small tracker. The metrics then show the settings the port is actually running at, including a session-only RFC 2217 change, and the info series disappears rather than going stale when the port closes. Example fleet query: count by (mode) (jetkvm_serial_network_up == 1).

Small fixes this change needs

• The stored Serial Console settings are now applied at boot when the extension is loaded. Before, they were only applied once the UI next opened the extension, so a network client after a reboot would have seen 115200 8N1.
• A missing serialSettings.json no longer returns an error from getSerialSettings; the defaults apply.
• SerialMux.Enqueue no longer blocks forever once the mux has been closed.
• Setting the port mode is skipped when /dev/ttyS3 failed to open, instead of panicking. This also covers the ATX and DC extension mounts.

Not included (possible follow-ups): mDNS/DNS-SD advertisement of the ser2net port for fleet discovery, and RFC 2217 NOTIFY-LINESTATE/MODEMSTATE. The extension port has no modem lines, so SET-CONTROL requests are acknowledged but have no effect.

How this answers the issue discussion

• Lost reads with microcom (@justarandomgeek): jetkvm_app already holds the fd and wins most read()s, so a second process only sees fragments. This PR doesn't add another reader; network clients subscribe to SerialMux's one reader, so every client gets every byte.
• "ConsoleBroker seems to handle things in lines": correct. The network paths tap SerialMux before ConsoleBroker, so ser2net and web clients get the raw byte stream with no line splitting, RX:/TX: labels or control-character normalisation. Terminals, expect scripts and ANSI/curses output work unchanged. The broker still feeds the in-session WebRTC console as before.
• "Hook into the existing auth/session model rather than a separate unauthenticated listener?": the web mode does exactly that (same auth cookie and middleware as the rest of the device API, same-origin WebSocket). The ser2net mode is for tooling that can only speak TCP/RFC 2217, so it's a separate, off-by-default choice with a warning in the UI, and it respects loopback-only.
• Aruba CX USB-C console: out of scope. Those are device-mode USB-serial ports, so JetKVM would need to act as a USB host. Agreed in the issue to track separately; the network server here is transport-agnostic and could front such a port later.

Testing

• serial_server_test.go and serial_metrics_test.go (no build tag, so they run on amd64 CI) cover:

  • the telnet/RFC 2217 codec: IAC escaping, CR NUL handling, negotiation without loops, commands split across reads, line settings and rejected modes, BREAK
  • settings validation
  • disconnecting a client that falls behind
  • raw TCP in both directions, the client limit, stop and no-op re-apply
  • a full RFC 2217 session, including restoring the line settings
  • the WebSocket in both directions, the client limit and closing on a mode change
  • the collector's exposition output, checked line by line against the expected text for a closed port and for an open, reconfigured one, plus promlint on the metric names and help text

  The server tests pass 30 runs in a row under -race.

• go vet, golangci-lint (repo config) → 0 issues.

• UI: tsc, oxlint (0 new warnings), oxfmt.

• Smoke-tested /serial in Chromium against a mock backend: it connects, shows UART output, and typed input reaches the backend and is echoed back.

• ⚠️ Not yet run on hardware: nothing has been tried against a real /dev/ttyS3, and make test_e2e hasn't been run.

Checklist

• Ran make test_e2e locally and passed. Not run (needs a device).
• Linked to issue(s) above by issue number
• One problem per PR (the small fixes above are ones this feature depends on)
• Lints pass; CI green (local lints pass; CI pending)
• Tricky parts are commented in code

🤖 Generated with Claude Code

https://claude.ai/code/session_01C3BNwaCJdCFHEuH7EZcR7j

[conallob]

Superceded by jetkvm#1660 to upstream