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

[conallob]

Closes #1520

Summary

With the Serial Console extension loaded, the extension port UART (/dev/ttyS3) can be reached over the network. A new Network Access setting offers Disabled (default), ser2net (TCP) or Web console. A JetKVM, or a rack of them, can then act as a serial console server without developer mode, SSH or an external daemon.

ser2net mode: a TCP listener built into the app. 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): telnet option negotiation, IAC escaping, and IAC BRK sends a real serial break (e.g. SysRq). RFC 2217 clients such as pyserial's rfc2217:// can change baud rate, data bits, parity and stop bits for their session; the configured settings come back when they disconnect.
• There is no authentication, and the UI warns about this. The listener honours "loopback only" (same bind logic as the web server) and rejects ports 22, 80 and 443.

Web mode: GET /serial/ws uses the existing auth middleware and cookie, with the WebSocket library's default same-origin check, so another site can't use the cookie to reach the UART. Frames carry raw UART bytes in both directions. 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.

Design

• One reader. Everything goes through the existing SerialMux, which stays the only reader and writer of the port. This fixes the problem described in the issue, where a second process (microcom) lost most reads to jetkvm_app. Network clients subscribe to that one reader, so each client gets every byte.
• Raw bytes, not lines. Network clients read from SerialMux before ConsoleBroker, so they get no line splitting, RX:/TX: labels or control-character rewriting. Terminals, expect scripts and full-screen ANSI output work unchanged. The in-session WebRTC console is unaffected.
• Slow clients can't stall the port. A hub fans out UART reads without ever blocking the reader; a client that falls 256 reads behind is disconnected.
• Client limit. 1 by default, configurable up to 8 (e.g. an interactive session plus log capture). Extra clients are refused with a message (TCP) or close code 1013 (WebSocket).
• Lifecycle. Changing mode, port or protocol, or unloading the extension, closes the listener and drops clients. Saving unchanged settings keeps existing sessions.
• Settings live in serialSettings.json with the other Serial Console settings. Older files get the defaults, so the feature is off after upgrade.
• Status RPC. getSerialNetworkStatus reports whether it is running, the listen address, any bind error and the connected clients. The UI polls it.

Prometheus metrics

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

Port and network metrics are computed when Prometheus scrapes. go.bug.st/serial can't report a port's current settings, so every open, close and mode change now goes through setSerialPortMode, which records them. The metrics show what 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.

Related fixes

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

Out of scope

• The Aruba CX USB-C console from the issue discussion. That port is a USB-to-serial adapter on the switch side, so JetKVM would need to act as a USB host; better tracked separately.
• mDNS/DNS-SD advertisement of the ser2net port for discovering units across a fleet.
• RFC 2217 line-state and modem-state notifications. The extension port has no modem lines, so SET-CONTROL requests are acknowledged but have no effect.

Testing

• serial_server_test.go and serial_metrics_test.go have no build tag, so they run in amd64 CI. They cover:

  • the telnet/RFC 2217 handling: IAC escaping, CR NUL, negotiation without loops, commands split across reads, line settings, rejected modes, BREAK
  • settings validation
  • disconnecting a client that falls behind
  • raw TCP in both directions, the client limit, stop, and saving unchanged settings
  • a full RFC 2217 session, including restoring line settings
  • the WebSocket in both directions, the client limit, and closing on a mode change
  • the metrics output for a closed port and for an open, reconfigured one, plus promlint

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

• go vet and golangci-lint (repo config): 0 issues.

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

• Tried /serial in Chromium against a mock backend: it connects, shows UART output, and typed input round-trips.

• Not yet tested on hardware against a real /dev/ttyS3, and make test_e2e hasn't been run.

Checklist

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

[CLAassistant]

All committers have signed the CLA.

[justarandomgeek]

is this in a state you'd like someone to try it on real hardware? i'd be happy to give it a go if you're ready / if you've got instructions for that! :)

[conallob]

@justarandomgeek I believe it's ready to test on hardware. I need to set up one of my newer PoE KVMs for experimenting before I start testing on hardware though

Depending on which generation you have, #1536 may be a factor when testing though

[justarandomgeek]

yeah i have the PoE one, and i've already got the serial cable made up for it to the common adapter i use for everything, i just need to lay my hands on one more ethernet cable than i had, apparently...