What downtime actually means

"Zero downtime" is a claim that needs a definition before it can be tested, and the useful definition is narrower and more demanding than the usual one.

Three things people mean by it

The site never returns an error. This is the weakest version and the easiest to achieve.

No request is ever refused or dropped. This is stronger, because it includes requests already in flight when the old process is asked to stop.

No user notices anything. This is the strongest, and it includes things outside the request cycle entirely: a form that was open, a page in the middle of a Turbo navigation, a background job that was halfway done.

Most deployment tooling delivers the first, claims the second and doesn't address the third.

The four windows

A deploy has four moments where something can be lost, and they need different answers.

Requests in flight when the old container is told to stop must be allowed to finish.

Requests arriving during the swap need the proxy to have somewhere to send them.

Jobs running when the worker stops must finish or be safely retried.

Old code meets a new schema. The senior course "Migrations at scale: gh-ost" covered this one at length.

flowchart TB
  D["a deploy"] --> A["in-flight requests: must finish"]
  D --> B["arriving requests: proxy must have a target"]
  D --> C["running jobs: finish or retry safely"]
  D --> E["old code, new schema: expand and contract"]
  A --> Z["all four, or it is not zero downtime"]
  B --> Z
  C --> Z
  E --> Z

Where this application stands on each

The proxy handles the second window. kamal-proxy keeps the old container serving until the new one passes /up, so there's never a moment with no target.

Puma handles the first, and the next lesson is about how.

The third is the interesting one here. plugin :solid_queue runs the job supervisor inside Puma, so stopping Puma stops the job worker, and the request drain and the job drain are the same shutdown.

The fourth is a discipline, not a mechanism, and it's the only one no tool can do for you.

Why the definition matters

A deploy that returns no errors while silently killing a half-finished job hasn't achieved zero downtime. It has achieved zero visible downtime, and the difference shows up later as data that's wrong.

Being specific about which of the four windows you've closed is the whole skill. "We deploy with no downtime" is a claim. "In-flight requests drain, jobs are retried at least once, and we never ship a breaking schema change" is a description.

Key takeaways

• Zero downtime has three meanings, and most tooling delivers the weakest and claims the middle one.
• There are four windows: in-flight requests, arriving requests, running jobs, and old code with a new schema.
• kamal-proxy closes the arriving-requests window by keeping the old container until /up passes.
• Solid Queue inside Puma means the request drain and the job drain are one shutdown.
• Zero visible downtime and zero downtime differ, and the difference appears later as bad data.