Repository navigation
refactor: fold the five debug read routes onto one re-check helper - #31608
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS This is a refactor; nothing about what users see changes. The only behaviour change, a serialisation error now answered with 400 or 503 instead of 500, is declared and exposes no payload. What this change shipsInventory (6 items) — 5 justifiedIntent: make it impossible for a future debug read route to answer before it re-checks the caller's grant (#13526). This is a FIX, made by restructuring the code.
[FIRST-PRINCIPLES-REVIEWED] c6b8da8 Description read[DESCRIPTION-READ] 8430aeb7316b5ba0f554fd4403aacb45f16008c8f64b62da5b6bcea68d5474e3 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns. This is a behaviour-preserving refactor of private helpers, and the old name-scan test is replaced by a stricter shape test. [DESIGN-REVIEWED] c6b8da8 Description read[DESCRIPTION-READ] 7572222c6fa426e05ff0b46af675cd85277210ac2646dcb25ded9bef08c625bb 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
The five debug read routes each wrote out the same four steps -- authorize, build the payload off the loop, re-check the grant, answer -- and the only thing holding that order was a test that looked for the re-check's name in each route's source. That scan passes a route that re-checks after shaping its answer, and one that suspends by another spelling. The three steps after the gate now live in _offload_then_recheck: the route hands over its bound read, its own response shaping and its reads_past_own decision, and the shaping runs only once the re-check holds. api_debug_threads' four mode-dependent offloads become one bound read. Each route keeps its gate, its early exits and its own exception-to-status arms. Behaviour is unchanged at all five routes. The presence scan is replaced by the two route-shape rules the crew-log door uses: the re-check has exactly one caller, and the gate and the helper are the only places a debug route may suspend. A second test pins that a withdrawn grant stops the route's shaping from running at all. Closes #13526
6d8c700 to
c6b8da8
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved for the on-call. Review lanes pass on c6b8da8, no conflict, no open change request.
Problem / Motivation
Goal: Every debug read route builds its answer through one helper that re-checks the caller's grant before the route shapes or returns anything, and a test pins that shape instead of looking for a function name.
The five debug read routes in
handlers/debug.pyeach wrote out the same four steps: authorize, build the payload off the loop, re-check that the grant still holds, answer. The only guard on that order was a test that checked each route's source for the string_stale_grant_refusal. That scan passes a route that re-checks after it has already shaped its answer, and a route that suspends some other way (run_in_executor, an awaited coroutine,async with,async for).Why it matters
No hole is open today: all five routes do all four steps in order. The risk is the next route. The re-check exists because a caller can acquire a channel mirror while the read runs, and a route that answers without re-checking would publish host-wide state into that mirror. A name scan cannot catch that mistake.
Not a goal
reads_past_owndecision stay as they are.reads_past_own.refusals, which answers withoutredacttoday.What changed (motivation → approach → change)
_offload_then_recheck, the only caller of_stale_grant_refusalrespondshaping, andreads_past_own(refusalscomputes it, the rest take the default)api_debug_threadsto_threadcalls across three mode branches_threads_readbinds the requested mode into one readThe helper calls
respondonly after the re-check holds, so a withdrawn grant reaches the caller as the 403 and the route's shaping never sees the payload. Each route keeps its gate, its early exits (400, 422, 501) and its ownexceptarms. The three diag-backed routes share_redacted_json, which is the sameredact(json.dumps(..., default=str))they each ran.gatewaykeeps its own shaping withoutdefault=str, as on main.The new test parses the module and checks two things. First,
_stale_grant_refusalhas exactly one caller,_offload_then_recheck. Second, every function that calls_authorize_debug_readsuspends only at the gate and the helper. Anawaitof anything else is named back in the failure, and so areasync with,async forand async comprehensions. A control asserts the five routes are the ones that go through the helper.Backwards compatibility
Compatible: every route answers the same status and body for every request it answered before; the only difference is which error a failure in the shaping step reports. In
threadsandsnapshotsthe route'sexceptarms now surround the helper call, so aValueError/OSErrorraised while serialising an already re-checked payload (a circular reference, say) is answered with that route's 400/503 instead of an unhandled 500. Neither carries the payload.Removes nothing: the presence-scan test is replaced by a stricter one, and the only symbols added are private (
_offload_then_recheck,_redacted_json,_threads_read).Tests
test_a_debug_route_can_only_answer_through_the_recheckreplacestest_every_offload_is_followed_by_a_stale_grant_recheck. It fails on main, where five routes call the re-check. Checked by hand against three mutations: shaping before the re-check, arun_in_executorawait in a route, and an async comprehension in a route. Each one fails it by name.test_the_shaping_never_runs_when_the_grant_was_withdrawndrives the helper with a channel-linked caller and asserts a 403 withrespondnever called.test_a_dump_that_vanished_between_two_reads_is_a_404,test_a_malformed_window_value_is_the_callers_error_not_a_crash) and the self-narrowedrefusalsread (test_a_channel_linked_session_still_reads_its_own_refusals).-n0, and 10 times at-n 4 --dist loadgroup --max-worker-restart=2besidetest_crew_log_routes_facade.pyandtest_crew_log_routes_dispatch_fence.py. All 92 tests intest/test_mcp_debug.pypassed in a shuffled order (seed 21657).Proof: PROVEN test/test_mcp_debug.py::TestTheRouteAuthorizationShape::test_a_debug_route_can_only_answer_through_the_recheck (head 6d8c700)
Manual verification
N/A — unit coverage sufficient: the five routes are driven through their real handlers by the existing route tests, and the change has no UI.
Screenshots / video
N/A — backend-only change; no frontend path touched.
Related Issues
Closes #13526
Sibling sweep
Swept: git grep -n "_stale_grant_refusal" -- src/
Sibling: src/kiro_crew/dashboard/handlers/crew_log.py -- not affected -- the crew log door was folded onto its own helper by #13485
Sibling: src/kiro_crew/dashboard/handlers/crew_log_scope.py -- not affected -- defines the async crew log re-check; its only route caller is that helper
Pattern harvest
Not generalizable: the two route-shape rules are tied to the gate and helper each door owns, and both doors now pin their own.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.