feat(service): hold requests for a sleeping service and wake it on demand

[mhenrixon]

Summary

The Service half of scale-to-zero (#19): the request gate, the options, the persisted state, and the CLI surface the gem is waiting on.

One chunk remains after this — the Router installing a ContainerLifecycle — so nothing sleeps yet.

The flag is --sleep-after, not --idle-timeout

The gem side needs this correction. kamal#68 assumed kamal-proxy would grow --idle-timeout. It cannot: run --idle-timeout already exists for HTTP keep-alive (config.go, DefaultIdleTimeout = 60s). Two flags sharing one name with two unrelated meanings is an operator trap no compiler catches.

Command	Flag	Default
deploy	--sleep-after	0 (never)
deploy	--wake-timeout	30s
deploy	--sleep-container (repeatable)	infer from target
run	--docker-socket (env DOCKER_SOCKET)	empty (disabled)

--sleep-after also puts the flag, the persisted state name (sleeping) and the log lines in one vocabulary.

Gate placement is the load-bearing decision

The gate sits in serviceRequestWithTarget, after handlePausedAndStoppedRequests and before target selection.

Everything above it therefore runs first — basic auth, IP allow list, rate limit, redirects, request deadline, the ACME HTTP handler. So a blocked, throttled, unauthenticated or redirected request can never spend a container start. Upstream basecamp#228 puts this a layer up in ServeHTTP, where an anonymous client, a rate-limited flood, or an ACME HTTP-01 challenge each start containers — a denial-of-wallet vector this fork does not inherit.

Being above target selection is what keeps the request byte-for-byte intact: net/http does not read a body until the handler asks, so a chunked POST parked for three seconds is handed on unread. No buffering, no TeeReader.

Health checks: answered, never held, never waking

An uptime monitor polling /up would otherwise pin a service awake forever. Holding the probe instead would make a load balancer in front evict a service that is sleeping exactly as intended. So a sleeping service answers 200 itself.

The other half matters as much: once a wake has actually failed, the health check reports unhealthy. Otherwise a service that can no longer start reports green to its monitoring forever while 503ing every real request.

The 503 leaks nothing

The wake error carries container references and up to 4 KB of daemon output, and that response is reachable by anyone who can open a connection. It is logged, not rendered — with a test asserting neither the container name nor docker.sock appears in the body.

Test plan

• ValidateSleep — table: negatives, --sleep-container without --sleep-after, and the TLS on-demand combination (a sleeping backend cannot answer an on-demand check, and waking one would let any SNI on the internet start a container)
• NormalizeDefaultsTheWakeTimeout
• SleepingServiceWakesOnARequest — one start, state returns to active
• HealthCheckNeitherWakesNorIsHeld + HealthCheckReportsUnhealthyAfterAFailedWake
• WakeFailureDoesNotLeakDaemonDetailToTheClient
• InternalRequestsDoNotWake — the proxy's own TLS probe
• ContainerRefsPreferTheExplicitOverride, TestTarget_ContainerRef (table; IP literals rejected)
• IdleStateRoundTrip + StateFileWithoutIdleStateRestoresAwake
• gofmt, go vet clean; go test -race — 1301 pass

Deviations & judgment calls

• Refs are recomputed in UpdateLoadBalancer, not only initialize. initialize runs before a load balancer exists on a first deploy, so refs were empty and a "wake" reported success having started nothing. I caught it because a test asserted the helper had actually derived some refs — worth noting, since the symptom is a silent success, not a failure. A redeploy pointing at new containers lands here too, which is exactly when the controller needs telling.
• Normalize only defaults a zero wake-timeout. It first defaulted anything <= 0, which swallowed a negative and made its own validation unreachable. A negative is a typo; rejecting it beats silently turning it into 30s.
• UnmarshalJSON deliberately builds no controller. The lifecycle is nil at that point, so one built there could reach StopContainer on a nil interface. SetContainerLifecycle creates it after the whole state file is decoded. Add opt-in scale-to-zero for idle services basecamp/kamal-proxy#228 built it in unmarshal and had exactly that exposure.
• Test helpers must pass --sleep-container explicitly. httptest backends listen on 127.0.0.1, which ContainerRef correctly refuses as an address rather than a container. That is the override's real purpose, so the tests exercise the real path rather than a fixture.
• MarshalJSON still assumes s.active is non-nil. I hit the nil deref writing a test that built a Service with no load balancer, and fixed the test rather than adding a defensive check — the router always installs one before state is saved, and the coding rules say not to nil-check states that cannot happen. Flagging it because I did consider the guard.
• No label-selector support yet. Derived refs plus --sleep-container only. The selector — which also closes the kamal rollback hole kamal#68 names — is the immediate follow-up, additive: one DockerClient method and one flag.

Refs #19