Relationships
#4810 serve: swamp serve reload rotates the TLS certificate, key and CA certificate without a restart
Opened by stack72 · 11/16/2026
Follow-up from #4439, which asked: "TLS: re-read the certificate and key on reload, for rotation." This is the one ask from #4439 still open.
Problem
tls.cert-file, tls.key-file and tls.ca-cert are restart-only in the reload setting catalogue (src/serve/serve_settings_reload.ts). A reload that changes them reports "restart serve to change it; it needs a new process". So rotating a certificate needs a restart.
On Linux a rolling restart with --reuse-port makes that harmless. On macOS and Windows --reuse-port is unavailable, so each rotation briefly refuses connections. Short-lived certificates (ACME, internal CAs rotating daily) make that frequent.
Ask
swamp serve reload re-reads the certificate and key, and the CA certificate, and new TLS connections use them. Existing connections keep the certificate they started with.
- A changed path, or the same path whose file changed, applies. Rotation tools usually rewrite the file in place.
- The new pair is checked before anything changes: both files are readable, the key matches the certificate, and the PEM is valid. A bad pair refuses the reload and the old certificate stays in force, as with any refused serve.yaml.
- Turning TLS on or off still needs a restart, since the listener's scheme changes. So does changing
hostorport. - The reload report lists
tls.cert-file/tls.key-fileas applied. An audit event records the rotation, naming the files and the certificate's fingerprint and expiry, never the key. - The CA certificate (
tls.ca-cert) applies to outbound TLS that serve sets up after the reload.
The plan needs to establish how to swap the certificate on a running Deno listener: whether Deno.serve or Deno.listenTls can change certificates in place, or whether serve needs a second listener on the same port, or a TLS layer of its own. If no supported way exists, the issue becomes "re-bind the TLS listener in place".
Tests
- A cert and key rewritten in place and reloaded are served to the next connection; an open connection keeps working.
- A mismatched key, an unreadable file or invalid PEM refuses the reload, and the old certificate is still served.
- Turning TLS off, or changing the port, is reported as needing a restart.
Closed
No activity in this phase yet.
stack72 commented 11/17/2026, 12:22:38 PM
Closing as not feasible on Deno today. A spike on Deno 2.9.8, the version swamp pins, found:
- No live certificate swap.
Deno.serveandDeno.listenTlstakecert/keyonce, at listen time. There is no SNI resolver, no certificate callback and no update call, and there is no server-sideDeno.startTls. - A second listener on the same port (
reusePort) works on Linux only; macOS refuses it withAddrInUse. On Linux this is what a rolling restart with--reuse-portalready does. - Closing the listener and re-binding in-process refuses new connections for about 9 ms. It also closes every open WebSocket:
shutdown()on the oldDeno.serveclosed an upgraded socket, so workers, attached--serverclients and the dashboard would all reconnect. That is most of a restart's disruption, without its run handoff. node:httpswithsetSecureContextdoes swap a live server's certificate with no gap in Deno's Node layer. Using it means moving serve's HTTP and WebSocket stack offDeno.serve, a large rewrite for one feature.
To rotate serve's own certificate:
- Linux: a rolling restart with
--reuse-port. No request fails, and runs are parked and continued (#4737). - Frequent rotation (ACME, short-lived internal certificates): terminate TLS at a proxy in front of serve and set
trust-proxy. - macOS / Windows: a restart. Connections are refused briefly; runs still survive it.
Reopen this if Deno adds a certificate resolver or update API to Deno.serve.
Sign in to post a ripple.