Health checks for targets that don't speak HTTP (WebSocket-only services)

[spinosa]

The problem

Health checks send an HTTP GET and require a 2xx. A WebSocket-only target has no HTTP endpoint to offer — it answers a plain GET by closing the connection — so it can never become healthy.

This comes up with accessories, which are frequently not web apps. An MQTT broker fronted as wss:// is the case I ran into.

The usual workaround is to stand up a second, HTTP-only listener beside the real one purely so that something can be checked. That proves the second listener is up, and nothing about the port clients actually use — the two can diverge exactly when it matters.

Proposed solution

A --health-check-protocol websocket option that sends the WebSocket opening handshake and treats 101 Switching Protocols as healthy, so the check exercises the same listener as real traffic:

kamal-proxy deploy service1 --target broker:9001 --health-check-protocol websocket

Plus --health-check-websocket-subprotocol to set Sec-WebSocket-Protocol, which some servers require before they will complete the handshake.

Default stays http, and an unset value behaves as http, so nothing changes for existing users. An unrecognised protocol is rejected rather than silently falling back to HTTP.

Implementation

I have this working and tested, if it's of interest:

main...spinosa:kamal-proxy:websocket-health-checks

• Response validated per RFC 6455 §4.1 — Upgrade, the Connection token, Sec-WebSocket-Accept derived from a fresh random nonce, and no subprotocol that wasn't offered
• Validation at the deploy command and again in Router.DeployService, matching the ServiceOptions.Validate convention
• Full suite and go vet clean, race-clean; verified against a real Mosquitto broker

One subtlety I'd want a second opinion on: on a protocol switch Response.Body is the upgraded connection, so the usual drain has to be skipped for 101 — draining it blocks until the peer sends something. There's a regression test that holds the connection open, since an httptest server closes on handler return and hides the problem entirely.

There's a companion change on the Kamal side to pass the flags through from deploy.yml, which would need a release containing these flags before it can land.

Following CONTRIBUTING.md by opening this as a discussion first rather than a PR — happy to open one if you'd like to take it.

---

Written by me in collaboration with Claude. I've reviewed all of it myself — quickly, but all of it.