diff --git a/planfile/api/server.py b/planfile/api/server.py index 21f055da..8f3c65df 100644 --- a/planfile/api/server.py +++ b/planfile/api/server.py @@ -725,6 +725,7 @@ def _ticket_list_response( view: Literal["full", "operational", "summary"] = "full", allow_stale: bool = False, allow_index_stale: bool = False, + require_fresh: bool = False, ) -> Response: # FastAPI runs this sync endpoint in a worker pool. Serialize cache misses so # a burst of websocket-driven dashboard refreshes builds one 5+ MB response, @@ -752,8 +753,10 @@ def _ticket_list_response( ) signature = _ticket_snapshot_signature(pf, sprint) key = query_key + (signature,) - with _TICKET_LIST_RESPONSE_CACHE_LOCK: - cached = _TICKET_LIST_RESPONSE_CACHE.get(key) + cached = None + if not require_fresh: + with _TICKET_LIST_RESPONSE_CACHE_LOCK: + cached = _TICKET_LIST_RESPONSE_CACHE.get(key) if cached is not None: body, total, count = cached else: @@ -833,7 +836,9 @@ def _ticket_list_response( count = len(payload) except TicketIndexContentionError: if ( - latest is not None + (allow_stale or (view == "full" and not require_fresh)) + and not require_fresh + and latest is not None and time.monotonic() - latest[0] < _INDEX_REPAIR_STALE_WINDOW_SECONDS ): @@ -860,7 +865,7 @@ def _ticket_list_response( ) if stale_index_response is not None: return stale_index_response - if view == "full" or sprint == "all": + if require_fresh or view == "full" or sprint == "all": return JSONResponse( status_code=503, content={"detail": "ticket_index_repair_pending"}, @@ -913,6 +918,7 @@ def list_tickets( offset: int = Query(0, ge=0), limit: int | None = Query(None, ge=1, le=5000), view: Literal["full", "operational", "summary"] = Query("full"), + require_fresh: bool = Query(False), ): response.headers.update(NO_STORE_HEADERS) pf = get_planfile() @@ -949,6 +955,7 @@ def list_tickets( view=effective_view, allow_stale=browser_client, allow_index_stale=legacy_unbounded_request, + require_fresh=require_fresh, ) diff --git a/project/TICKETS.md b/project/TICKETS.md index 8958a275..560a5551 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -170,5 +170,6 @@ This file indexes governance tickets without taking ownership of | **ticket-267** | [`README.md`](./ticket-267/README.md) | - | - | - | - | - | | **ticket-270** | [`README.md`](./ticket-270/README.md) | - | - | - | - | - | | **ticket-271** | [`README.md`](./ticket-271/README.md) | - | - | - | - | - | +| **ticket-272** | [`README.md`](./ticket-272/README.md) | - | - | - | - | - | | **ticket-273** | [`README.md`](./ticket-273/README.md) | - | - | - | - | - | diff --git a/project/ticket-274/README.md b/project/ticket-274/README.md new file mode 100644 index 00000000..022bcc2d --- /dev/null +++ b/project/ticket-274/README.md @@ -0,0 +1,45 @@ +# Ticket 274: Serve the last complete ticket index to machine callers + +- **ID**: ticket-274 +- **Owner**: agent:opencode-agent +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION +- **Created**: 2026-11-02 +- **Planfile**: PLF-22058 + +## Goal and scope + +Measured on the deployed service: the ticket API answered **6 of 12 probes** +twenty seconds apart (`200 503 503 200 200 200 503 503 timeout 200 200 200`). + +Cause: a full view (`/tickets?sprint=current`, the default) has no durable +fallback, so while the projection is being repaired it answered +`503 ticket_index_repair_pending`. Only a **browser** user agent was allowed to +read the last complete index, and only inside a **30 s** window. Every machine +caller - campaigns, tooling, this session's probes - therefore saw the same +query succeed or fail depending on its user agent and on the moment. + +Scope: `planfile/api/server.py`, `tests/test_sqlite_ticket_index.py`. + +## Acceptance criteria + +- [x] AC-01: A full view may serve the last complete projection for as long as a + repairing index would have been acceptable (`_INDEX_REPAIR_STALE_WINDOW_SECONDS`), + not just the 30 s dashboard window, and marks it + `X-Planfile-Index-State: stale`. +- [x] AC-02: `require_fresh=true` is never served a stale body: it bypasses both + the response cache and the stale projection, and waits (503) or answers + from live sources without the stale marker. +- [x] AC-03: Summary and operational views keep their fresh durable fallback; + the existing fail-closed tests for an expired projection still pass. + +## Evidence + +- `pytest tests/test_sqlite_ticket_index.py` -> 75 passed (new: + `test_full_view_serves_the_last_complete_index_to_a_machine_caller`). +- Measurement that motivated it: 6/12 probes available, recorded in PLF-22058. + +## Non-goals + +- Making the projection cheaper to rebuild, or coalescing invalidations; those + remain in PLF-22058. diff --git a/project/ticket-274/intent.json b/project/ticket-274/intent.json new file mode 100644 index 00000000..762c188d --- /dev/null +++ b/project/ticket-274/intent.json @@ -0,0 +1,25 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-274", + "summary": "Serve the last complete ticket index to machine callers instead of refusing half the requests", + "workstream": "application", + "classification": { + "kind": "BUG", + "priority": "P1", + "origin": "requested" + }, + "allowedPaths": [ + "project/ticket-274/**", + "TODO.md", + "project/TICKETS.md", + "planfile/api/server.py", + "tests/test_sqlite_ticket_index.py" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/tests/test_sqlite_ticket_index.py b/tests/test_sqlite_ticket_index.py index 36d61c83..b3f0fc14 100644 --- a/tests/test_sqlite_ticket_index.py +++ b/tests/test_sqlite_ticket_index.py @@ -1548,3 +1548,49 @@ def no_marker(path, content): with pytest.raises(OSError, match="invalidation filesystem unavailable"): pf.update_ticket(ticket.id, name="After") assert pf.store._locate_ticket_source(ticket.id)[1]["name"] == "After" + + +def test_full_view_serves_the_last_complete_index_to_a_machine_caller(tmp_path, monkeypatch): + """A full view has no durable fallback: a stale projection used to answer 503. + + The same query succeeded for a browser (which was allowed to read the last complete + index) and failed for every other client, which is why the ticket API looked available + half of the time. It now serves the stale projection with an explicit marker, and only + an explicit `require_fresh` request is refused. + """ + pf = Planfile(str(tmp_path)) + _disable_archive(pf) + ticket = pf.create_ticket(name="Ticket before external edit") + pf.store.configure_ticket_index(True) + pf.store.ensure_ticket_index() + monkeypatch.setattr(server, "get_planfile", lambda: pf) + server._TICKET_LIST_RESPONSE_CACHE.clear() + server._TICKET_LIST_LATEST.clear() + client = TestClient(server.app) + + warm = client.get("/tickets?sprint=current&view=full&limit=10") + assert warm.status_code == 200 + + sprint_file = pf.store._sprint_file("current") + data = yaml.safe_load(sprint_file.read_text(encoding="utf-8")) + data["sprint"]["tickets"][ticket.id]["name"] = "Ticket after external edit" + sprint_file.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8") + mirror_path(sprint_file).unlink(missing_ok=True) + + # pretend the cached answer is older than the short dashboard window but still within + # the window a repairing projection is allowed to be served from + with server._TICKET_LIST_RESPONSE_CACHE_LOCK: + for key, (_, body, total, count) in list(server._TICKET_LIST_LATEST.items()): + server._TICKET_LIST_LATEST[key] = (time.monotonic() - 60.0, body, total, count) + + stale = client.get("/tickets?sprint=current&view=full&limit=10") + fresh = client.get("/tickets?sprint=current&view=full&limit=10&require_fresh=true") + + assert stale.status_code == 200 + assert stale.headers.get("X-Planfile-Index-State") == "stale" + # a caller that demands freshness is never served the stale projection: it is either + # asked to wait (503) or answered from the live sources, never marked as stale + assert fresh.headers.get("X-Planfile-Index-State") != "stale" + assert fresh.status_code in (200, 503) + if fresh.status_code == 503: + assert fresh.json() == {"detail": "ticket_index_repair_pending"}