Skip to content

fix(design-tweak): fix the born-red HTTPServer bind ratchet via the sanctioned _Server subclass - #17909

Merged
chenmingwei23 merged 2 commits into
mainfrom
fix/http-server-bind-ratchet-baseline
Oct 8, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
fix/http-server-bind-ratchet-baseline

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make test_http_server_bind_ratchet pass on main by routing one bare HTTPServer construction through the sanctioned subclass, so the ratchet matches its recorded baseline again.

test/test_http_server_bind_ratchet.py::test_bare_http_server_constructions_match_the_recorded_count is deterministically red on main (current head a2ca1b77f), which blocks the shard-2 Backend Tests lane — and therefore PR Readiness — on every open PR. It records _BASELINE_SITES = 15 while the tree carries 16 bare HTTPServer((host, port), ...) / ThreadingHTTPServer((host, port), ...) constructions:

16 bare HTTPServer((host, port), ...) construction(s) (recorded: 15).

Why it matters

A base-side red on a shard-2 ratchet fails that lane for every PR, so Readiness can never converge for anyone until it is fixed. The ratchet also guards a real failure mode: http.server's server_bind resolves socket.getfqdn(host) between bind() and listen(), a system-resolver lookup that can stall on macOS runners while the socket is bound but refuses every connect — which a waiting parent reads as a server that never came up.

Not a goal

  • No bump of _BASELINE_SITES, and no conversion of the other 15 sites (test fixtures and one further preview bind); they remain the baselined 15.

What changed (motivation → approach → change)

Symptom: the ratchet is red (16 vs 15). Root cause: it was born red — the commit that introduced the test, #17450 (781294256), already contained 16 matching sites but recorded _BASELINE_SITES = 15. The count was recorded one low; all 16 sites are legitimate ephemeral-port ("127.0.0.1", 0) binds.

Approach: rather than bump the baseline, apply the fix the ratchet's own docstring prescribes — subclass and call socketserver.TCPServer.server_bind so no host name is resolved (mirrors plumb_cpu.LoopbackServer). The design-tweak backend already has a _Server(ThreadingHTTPServer) subclass (it overrides allow_reuse_address); extend it, and point one real production site at it.

Change:

  • server.py: add a server_bind override to _Server that binds through socketserver.TCPServer.server_bind and records the address directly, skipping getfqdn.
  • dev_preview.py: start_inject_proxy now constructs runtime._Server instead of the stock runtime.ThreadingHTTPServer.

That removes exactly one bare construction (16 → 15) and hardens the overlay-injecting dev proxy — a server a waiting parent depends on — against the stall the ratchet exists to prevent.

Second commit — also carries #17903's doc fix so both base reds clear together. Main had a second deterministic red: shard 6's test_session_control_doc.py::test_every_tabulated_refusal_code_is_one_the_source_raises, because #17662 deleted every session_control.py raise of remote_target_unsupported but the page still tabulated it. The open PR #17903 fixes that with a one-line doc deletion — but #17903 fails on shard 2 (the ratchet) and this PR failed on shard 6 (the doc row), so neither could go green alone (a deadlock). This PR's second commit applies the identical one-line deletion from session-control.md, so merging either PR first clears both reds.

Backwards compatibility

Removes nothing: the change swaps a stock ThreadingHTTPServer construction for its existing subclass and adds a server_bind override; no field, type, key, kind, or public function is rejected, renamed, or removed, and the dev proxy still binds an ephemeral port and returns the same (server, url) shape.

Tests

  • test/test_http_server_bind_ratchet.py — now passes (2/2); the scan finds 15 sites, matching _BASELINE_SITES.
  • test/test_design_tweak_relay_paths.py::TestStartInjectProxy — passes (8/8). test_bind_failure_returns_none's patch.object target moves with the construction (ThreadingHTTPServer → _Server); its assertion is unchanged.
  • test/test_builtin_backend_address_reuse.py — passes; _Server's address-reuse behaviour is unaffected.
  • test/test_session_control_doc.py — passes (10/10), including test_every_tabulated_refusal_code_is_one_the_source_raises, after the second commit removes the stale refusal row.

Manual verification

N/A — unit coverage sufficient; the change is a server-construction swap exercised by the tests above.

Pattern harvest

Not generalizable: this is a one-off off-by-one in a single ratchet's recorded baseline at the commit that introduced it, not a recurring code pattern.

Related Issues

Fixes #17908

…ver bind ratchet matches its baseline

test_http_server_bind_ratchet records _BASELINE_SITES = 15 but the tree
carries 16 bare HTTPServer((host, port), ...) constructions, so the ratchet
has been red on every main head since it was added in #17450 (which itself
shipped with 16 sites and a baseline of 15 -- the count was recorded one low).

Rather than bump the baseline, apply the fix the ratchet's own docstring
prescribes: subclass and call socketserver.TCPServer.server_bind so no host
name is resolved. _Server already subclasses ThreadingHTTPServer for the
address-reuse flag; give it the server_bind override (mirroring
plumb_cpu.LoopbackServer) and construct it from start_inject_proxy instead of
the stock ThreadingHTTPServer. That removes exactly one bare construction
(16 -> 15) and hardens the overlay-injecting dev proxy against the macOS
getfqdn stall the ratchet exists to prevent.

The bind-failure test's patch target moves with the construction
(ThreadingHTTPServer -> _Server); its assertion is unchanged.

Fixes #17908
@iamwhatever
iamwhatever requested a review from a team as a code owner October 7, 2026 22:29
@iamwhatever
iamwhatever requested a review from buluoray October 7, 2026 22:29
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 270d60f0eb2547a183025d2d77ec43d7fb181957 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 270d60f

Description read

[DESCRIPTION-READ] 4351ddf431679f48a738b9804b77cf5dd4866a01b296b92f38ccc5f4b662504b

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 270d60f0eb2547a183025d2d77ec43d7fb181957 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the inject proxy now sets SO_REUSEADDR on POSIX through _Server. On an ephemeral loopback port that should be harmless.

[DESIGN-REVIEWED] 270d60f

Description read

[DESCRIPTION-READ] a2c8e5b1d4f3dc39b9ad96da8471a0645407cbd07e3272d4c5336f7529eb4880

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 270d60f0eb2547a183025d2d77ec43d7fb181957 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check before merge: _Server is also the design-tweak app's main listener (server.py:1027), so that listener now skips getfqdn too. Nothing reads server_name (0 hits).

What this change ships

Inventory (3 items) — 1 justified

Intent: unblock every open PR by turning two deterministic base-side reds (shard 2 ratchet, shard 6 doc test) green. This is a FIX (#17908).

  1. The dev overlay proxy binds through _Server, so it no longer runs a host-name lookup between bind and listen, and the ratchet count drops from 16 to 15. — justified
  2. The design-tweak app's own loopback server (_Server(("127.0.0.1", PORT))) also stops the getfqdn lookup. — undeclared: the description only names the dev proxy as the server being hardened
  3. The stale remote_target_unsupported row is gone from src/kiro_crew/docs/session-control.md. — rides along: it clears the separate shard-6 red, and its source raise is already deleted (0 src/ hits)

[FIRST-PRINCIPLES-REVIEWED] 270d60f

Description read

[DESCRIPTION-READ] 406995a9a2a9b5782525835111e4e84792687b59a19e52e8734ecb7689002e94

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 270d60f0eb2547a183025d2d77ec43d7fb181957 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 270d60f

Verdict parsed from the review's SHA-scoped output markers for commit 270d60f0eb2547a183025d2d77ec43d7fb181957.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 270d60f0eb2547a183025d2d77ec43d7fb181957: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 270d60f0eb2547a183025d2d77ec43d7fb181957 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 270d60f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 270d60f0eb2547a183025d2d77ec43d7fb181957: <one-sentence reason>

#17662 deleted the turn relay and with it every session_control.py raise of
remote_target_unsupported, but the session-control page still tabulates it, so
test_session_control_doc.py::test_every_tabulated_refusal_code_is_one_the_source_raises
is red on main (shard 6, both Linux and Windows).

This is the same one-line deletion as the open PR #17903. Carrying it here lets
both base reds -- the HTTPServer bind ratchet (shard 2, this PR's own fix) and
the doc row (shard 6) -- clear together, since #17903 fails on shard 2 and this
PR failed on shard 6, so neither could go green alone.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review at head 270d60f (comment only; this account opened the PR).

Check Finding
Bind ratchet dev_preview.py builds the inject proxy with runtime._Server; _Server.server_bind calls socketserver.TCPServer.server_bind and sets server_name/server_port, the same shape as plumb_cpu.LoopbackServer. The tree has 15 sites again; _BASELINE_SITES stays 15.
Side effect The proxy now inherits allow_reuse_address = IS_POSIX. It binds port 0, so a reused address cannot collide. The main design-tweak server also skips getfqdn; nothing in design_tweak reads server_name.
Doc row Drops remote_target_unsupported; git grep finds no raise of it under src/.
Test test_bind_failure_returns_none patches _Server, matching the new constructor.
Local run test_http_server_bind_ratchet.py, test_session_control_doc.py, test_design_tweak_relay_paths.py: 54 passed.

No blocking findings. One leftover outside this diff: docs/feature-map/README.md still lists remote_target_unsupported among the reload refusals; no test reads it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): RECOMMEND APPROVE

Reviewed head 270d60f. The real problem was a bare ThreadingHTTPServer in dev_preview.py, which made the bind ratchet red on main. It now goes through the sanctioned _Server. _Server.server_bind also skips getfqdn, the same way plumb_cpu.LoopbackServer does, so a slow macOS resolver can no longer stall a loopback listener between bind and listen. server_name and server_port are still set. All three AI lanes PASS. One scope note: the diff also drops the stale remote_target_unsupported row from session-control.md, because that code is gone since #17642. But docs/feature-map/README.md still names it, so please drop it there too, or move both edits to a docs PR.

@iamwhatever
iamwhatever enabled auto-merge (squash) October 7, 2026 23:59
@chenmingwei23
chenmingwei23 merged commit a0c41ff into main Oct 8, 2026
104 of 112 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/http-server-bind-ratchet-baseline branch October 8, 2026 00:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 8, 2026
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.

test_http_server_bind_ratchet born red on main: 16 bare HTTPServer sites vs recorded baseline 15

3 participants