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
14 changes: 13 additions & 1 deletion planfile/api/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -467,7 +467,13 @@ def _validate_completion_receipt(receipt: dict[str, Any] | None, ticket_id: str)
_TICKET_LIST_RESPONSE_MIN_MAX_BYTES = 1024 * 1024
_TICKET_LIST_RESPONSE_MAX_MAX_BYTES = 512 * 1024 * 1024
_DASHBOARD_STALE_WINDOW_SECONDS = 30.0
_INDEX_REPAIR_STALE_WINDOW_SECONDS = 300.0
# A repair on the production store (about 22k tickets, 517 MB) takes 5-9 minutes, so a
# five-minute window expires in the middle of it: the projection is still a coherent
# last-known-good snapshot, yet machine callers were answered with 503 and clients saw an
# API that flapped on every write. The window stays bounded - a permanently broken index
# must still fail closed, and `require_fresh` never accepts stale data - but it now covers
# a real repair rather than a guess at one.
_INDEX_REPAIR_STALE_WINDOW_SECONDS = 3600.0
_SPRINT_SUMMARY_CACHE: dict[str, tuple[tuple[int, int], dict[str, Any]]] = {}
_SPRINT_SUMMARY_CACHE_LOCK = RLock()

Expand Down Expand Up @@ -666,8 +672,13 @@ def _bounded_stale_index_response(
limit: int | None,
view: Literal["full", "operational", "summary"],
allow_unbounded_summary: bool = False,
require_fresh: bool = False,
) -> Response | None:
"""Serve a recent, coherent projection while its source index is repaired."""
if require_fresh:
# The caller asked for freshness, not for availability: a marked-stale body is
# still stale data, so it must fall through to the explicit 503 instead.
return None
archive_queue = sprint == "all" and limit is not None
legacy_summary = allow_unbounded_summary and view == "summary"
if view == "full" or not (archive_queue or legacy_summary):
Expand Down Expand Up @@ -862,6 +873,7 @@ def _ticket_list_response(
limit=limit,
view=view,
allow_unbounded_summary=allow_stale or allow_index_stale,
require_fresh=require_fresh,
)
if stale_index_response is not None:
return stale_index_response
Expand Down
1 change: 1 addition & 0 deletions project/TICKETS.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,4 +172,5 @@ This file indexes governance tickets without taking ownership of
| **ticket-271** | [`README.md`](./ticket-271/README.md) | - | - | - | - | - |
| **ticket-272** | [`README.md`](./ticket-272/README.md) | - | - | - | - | - |
| **ticket-273** | [`README.md`](./ticket-273/README.md) | - | - | - | - | - |
| **ticket-274** | [`README.md`](./ticket-274/README.md) | - | - | - | - | - |
<!-- AUTO:TICKET_INDEX:END -->
42 changes: 42 additions & 0 deletions project/ticket-275/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Ticket 275: Keep the stale index window longer than a real rebuild

- **ID**: ticket-275
- **Owner**: agent:opencode-agent
- **Status**: IN_PROGRESS
- **Workflow state**: PUBLICATION

## Goal

The Planfile HTTP API flapped between 200 and 503 while an index rebuild was running, even
though a coherent last-known-good snapshot existed the whole time.

Two defects sit behind that:

1. `_INDEX_REPAIR_STALE_WINDOW_SECONDS` was `300.0`, but a rebuild of the production store
(about 22 358 tickets, 517 MB) takes **5-9 minutes** (measured twice on 2026-11-02:
~5 min and ~9 min). The window therefore expired *inside* the repair, and machine callers
were answered `503`.
2. `_bounded_stale_index_response()` never received `require_fresh`, so a caller that asked
for freshness was served a **stale** body with `200` and `X-Planfile-Index-State: stale`.
The freshness guarantee only covered the in-memory cache path.

## Change

- The stale window now covers a real repair (1 hour). It stays bounded: a permanently
broken index still fails closed, and `require_fresh` never accepts stale data.
- `require_fresh=True` returns `None` from the stale helper so the request falls through to
the explicit `503` instead of receiving stale content.

## Acceptance criteria

- [x] AC-01: a 20-minute-old coherent snapshot is served with `X-Planfile-Index-State: stale`
instead of `503` (previously impossible: 300 s window).
- [x] AC-02: `require_fresh=true` never returns stale data - it answers `503`.
- [x] AC-03: the in-memory stale path keeps its existing `require_fresh` guard.

## Evidence

- `pytest tests/test_sqlite_ticket_index.py` -> 76 passed (includes the new
`test_stale_index_survives_a_repair_longer_than_five_minutes_but_never_lies`).
- Live measurement before/after: `12/12` probes at 0.07-0.53 s once `current`, then `503`
at 5-19 s during the next repair; the window is the difference between those two states.
25 changes: 25 additions & 0 deletions project/ticket-275/intent.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"schema": "new-project.intent/v3",
"ticket": "ticket-275",
"summary": "Keep the stale index window longer than a real rebuild so the API stops flapping with 503",
"workstream": "application",
"classification": {
"kind": "BUG",
"priority": "P1",
"origin": "health"
},
"allowedPaths": [
"project/ticket-275/**",
"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
}
44 changes: 44 additions & 0 deletions tests/test_sqlite_ticket_index.py
Original file line number Diff line number Diff line change
Expand Up @@ -841,6 +841,50 @@ def test_stale_archive_queue_reads_use_recent_index_without_query_cache(
assert pf.store.ticket_index_status()["current"] is False


def test_stale_index_survives_a_repair_longer_than_five_minutes_but_never_lies(
tmp_path, monkeypatch
):
"""A repair takes 5-9 minutes, so a 300 s window handed machine callers a 503 mid-repair."""
pf = Planfile(str(tmp_path))
_disable_archive(pf)
ticket = pf.create_ticket(name="Last known good after a long repair")
pf.store.configure_ticket_index(True)

sprint_file = pf.store._sprint_file("current")
data = yaml.safe_load(sprint_file.read_text(encoding="utf-8"))
data["sprint"]["tickets"][ticket.id]["name"] = "New durable value"
sprint_file.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
mirror_path(sprint_file).unlink(missing_ok=True)

index = pf.store._sqlite_ticket_index()
aged_ns = time.time_ns() - 20 * 60 * 1_000_000_000
with sqlite3.connect(index.path) as connection:
connection.execute(
"UPDATE meta SET value = ? WHERE key = 'source_indexed_at_ns'",
(str(aged_ns),),
)

monkeypatch.setattr(server, "get_planfile", lambda: pf)
monkeypatch.setattr(
pf.store,
"_ticket_index_records",
lambda: (_ for _ in ()).throw(AssertionError("request-triggered rebuild")),
)
server._TICKET_LIST_RESPONSE_CACHE.clear()
server._TICKET_LIST_LATEST.clear()
client = TestClient(server.app)

stale = client.get("/tickets?sprint=all&view=summary&limit=100")

assert stale.status_code == 200
assert stale.json()[0]["name"] == "Last known good after a long repair"
assert stale.headers["X-Planfile-Index-State"] == "stale"

fresh = client.get("/tickets?sprint=all&view=summary&limit=100&require_fresh=true")

assert fresh.status_code == 503


def test_legacy_archive_dashboard_uses_recent_current_index_without_cache(
tmp_path, monkeypatch
):
Expand Down
Loading