Skip to content

fix(server): graceful, awaitable, race-free HTTP stop (2/5 of #66) - #75

Closed
ofriw wants to merge 13 commits into
pr/66-codec-storagefrom
pr/66-http-stop
Closed

ofriw wants to merge 13 commits into
pr/66-codec-storagefrom
pr/66-http-stop

Conversation

@ofriw

@ofriw ofriw commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Part 2 of the #66 split. Independent of the codec/storage work; base is main.

What changed

Graceful HTTP stop. stop() now drains in-flight requests and responses before closing the listener, rejects new arrivals with a single 503 (Service Unavailable + connection: close), and accepts force/timeoutMs. timeoutMs bounds the drain only, never the final listener close, and neither force nor timeout cancels application handlers.

One lifecycle owner. A new BaseHttpServer<L> holds the drain, the start/stop gate and the signal wiring; Deno and Node keep only _bind/_close. Both runtimes therefore produce an identical rejection response. Deno's _bind races onListen against server.finished, so a busy port rejects instead of hanging. Node's _bind clears its listeners after a failed bind, so a retry starts clean.

Ordering. StartStopGate is FIFO: every start/stop runs alone, in call order, and a rejected op does not block the queue. Without this, a restart queued behind a pending stop could bind a listener that the stop never closed. The first op of an idle gate still runs synchronously, so stop() clears port/address before returning.

Input validation. validateStopTimeout rejects a non-integer, negative, or above 2^31-1 budget before any state change (a 32-bit timer overflow used to fire after ~1 ms and silently force-close). The stop promise rejects and the server keeps serving.

Start rollback. Server._start starts services into a rollback list, binds, and only then commits _abortController and logs ServerStarted. A failure stops what started, clears _stopping, logs ServerStartFailed, and rethrows. Previously a failed bind left the server looking started, so a retry returned immediately while nothing listened.

ALB health checks match the parsed host and path (http/https, any port, query ignored, case-sensitive path).

Breaking

HttpServerInstance.stop() and Server.stop() return Promise<void> and must be awaited; the promise resolves only after the port is free.

Verification

  • deno task check clean; deno publish --dry-run clean (the new exported class fields carry explicit types); npm run build:npm (tsup + DTS) clean, which also required dropping a Deno.ServeTcpOptions annotation the npm Deno stub does not declare.
  • Deno 616/616, Node 616/616, browser 288/288.
  • HttpServerStop covers: drain and 503 during drain, timeout and force interrupt a partial stream, force does not cancel handlers, idempotent stop releases the port, restart after stop, stop racing start, a pre-aborted signal leaves no listener, bind failure then same-instance retry, Server.start rollback then retry, invalid budgets leave the listener bound, the max budget still waits for an active request, gate FIFO order and rejection sanitization.
  • The gate and the start-rollback tests fail on the pre-fix code.

Stack

Independent of #74. pr/66-path-branding (last in the stack) expects this branch to be merged before it.

Stack position

Second layer of GitHub stack #80 (main ← #74 ← #75 ← #76 ← #77 ← #78).

ofriw added 13 commits October 27, 2026 14:31
Extract BaseHttpServer: drain, start/stop gate, idempotent stop and signal
wiring are runtime independent. Deno and Node keep only bind and close.

Also export the single 503 response used by both drain gates, so a client
cannot tell which runtime rejected it, and route the post-bind server error
through logging/ instead of console.error.
The gate chained every stop on an in-flight start only, so a start issued
while a stop was pending could bind before that stop ran, leaving a listener
the stop never closed. Queue every op behind the previous one and sanitize
the tail so a failed op does not block the queue. The first op of an idle
gate still runs synchronously, keeping stop()'s state change observable.
setTimeout overflows above 2^31-1 and fires in about a millisecond, so a
long budget silently became an immediate force-close. Validate timeoutMs
before any escalation or state change: an integer in [0, 2^31-1], else the
stop promise rejects and the listener keeps serving.
A failed start left the abort controller set and the services running, so a
retry returned early: the server reported success while nothing listened.
Start the services into a rollback list, bind, then commit the controller and
log the start metric. On failure stop what started, clear the stopping flag,
log ServerStartFailed and rethrow. A failed bind now rejects instead of
resolving without a listener.
@ofriw
ofriw changed the base branch from main to pr/66-codec-storage October 27, 2026 12:37
@ofriw
ofriw added this pull request to stack #80 October 27, 2026 12:38
@ofriw

ofriw commented Oct 29, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded by the reviewed, fully verified replacement stack: https://github.com/goatplatform/goatdb/stack/92

Each complete replacement tip passed full Deno + Node + browser suites on current Deno2.9.1 and actual floor2.3.3, with Node24.14.1 and Playwright1.64.1. Exact tip hashes, scope, dependencies, gates and breaking/data notices are in the new PR bodies. Final tip9e9a759f has 0 failures on all six full runs; the 49-source-commit content audit and independent review passed. Remote Actions status is separate from these measured local gates.

Review bottom-up. This replaces the old split, not just its last diff. No PR was merged, no issue was edited, and original remote branches are retained.

@ofriw ofriw closed this Oct 29, 2026
@ofriw
ofriw removed this pull request from stack #80 October 29, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant