Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions planfile/api/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
):
Expand All @@ -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"},
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -949,6 +955,7 @@ def list_tickets(
view=effective_view,
allow_stale=browser_client,
allow_index_stale=legacy_unbounded_request,
require_fresh=require_fresh,
)


Expand Down
1 change: 1 addition & 0 deletions project/TICKETS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) | - | - | - | - | - |
<!-- AUTO:TICKET_INDEX:END -->
45 changes: 45 additions & 0 deletions project/ticket-274/README.md
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 25 additions & 0 deletions project/ticket-274/intent.json
Original file line number Diff line number Diff line change
@@ -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
}
46 changes: 46 additions & 0 deletions tests/test_sqlite_ticket_index.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Loading