mirror of
https://github.com/PerpetualSoftware/pad.git
synced 2026-09-10 23:15:40 +00:00
xarmian
21001bc4c3
* feat(sessions): session-presence registry + GET /api/v1/sessions (PLAN-2558 S1)
Slice 1 of PLAN-2558 (IDEA-2544 Phase 3, web-UI push). The server can now
answer "is anything actually listening right now?" for the calling user.
WHY. `pad push` (Phase 1, da6ce642) is fire-and-forget with no
"no session connected" warning. That's a defensible contract for a CLI
verb typed by someone who knows whether their own session is running.
It is not a defensible contract for a web-UI button: "Push to Claude"
that silently goes nowhere is worse than the clipboard ferry it
replaces, because the user cannot tell the two outcomes apart. Presence
lets the UI answer the question before the click, and — once sessions
carry a label (S2) — turns the same data into the target picker S5 needs.
This also closes the substrate half of PLAN-2469 Phase 3 ("presence
surface: SessionStart hook -> live-sessions view", IDEA-2464). The two
Phase 3s were the same work; see PLAN-2558's opening section.
- internal/server/session_presence.go: SessionPresence interface +
MemorySessionPresence. Registered from handleWatchEventsStream,
bracketed to the SUBSCRIPTION's lifetime (defer pairs with
Unsubscribe's on the adjacent line) so every exit path — ctx.Done, a
failed SSE write, the replay-loop returns, the reval-tick paths —
releases both or neither. A leaked entry is the failure that matters:
it makes the UI promise a listener that is gone, i.e. the same silent
nowhere-push with a confident label on it.
- internal/server/handlers_sessions.go: GET /api/v1/sessions, self-scoped.
No ?user_id=, no admin bypass — who has an agent session open is a
presence signal about a person, and the same reasoning that made push
self-addressed only applies. 503 (not 200-with-empty-list) when no
registry is wired: "I can't tell" and "nobody is listening" must not
look the same to the UI, since collapsing them is exactly the
dishonesty this slice exists to remove.
Interface from day one because MemorySessionPresence is per-process.
Its doc comment states the boundary precisely rather than hand-waving
it: watchevents.Bus is blind in the SAME direction (a push published on
instance A never reaches a stream on instance B), so per-instance
presence is as accurate as per-instance delivery and both stop being
trustworthy at the same boundary — except that a load balancer may
route a POST and a GET to different instances, at which point they
disagree. A Redis-backed presence must therefore land WITH the Redis
watchevents.Bus that package already anticipates, not separately.
No pad-cloud change required (checked, not assumed): /api/v1/sessions is
a plain JSON GET served by nginx-router.conf's default `location /`
pass-through — the special long-lived-connection blocks are for
/api/v1/events and /api/v1/collab/ only.
Verified: go test ./... (SQLite) clean; make test-pg clean (25 pkgs,
exit 0); make lint 0 issues; new tests pass under -race. Live, on the
installed binary: 0 sessions with nothing connected -> 1 with one
stream open -> 2 with two, oldest-first -> back to 0 after both
disconnect, with a second user's list staying empty throughout.
* fix(sessions): no-store the presence response; document two lifetime constraints (PLAN-2558 S1)
Codex round 2 findings, both verified against source before acting.
P2 — Cache-Control. GET /api/v1/sessions set no cache header: writeJSON
sets none and the jsonContentType middleware only sets Content-Type, so
the response was heuristically cacheable. Now `private, no-store`,
matching the house pattern for per-user sensitive responses
(handlers_attachments.go:585). Wrong two ways without it: a shared cache
could serve one user's presence to another (the same boundary this
endpoint's absent admin view exists to hold), and a cached liveness
answer is exactly the confident-but-wrong "1 session connected" the
slice exists to prevent. Pinned by a test.
P2 — Shutdown, REFINED rather than adopted as reported. Server.Shutdown
delegates to http.Server.Shutdown, which does not cancel an in-flight
handler's context; SSE handlers therefore hang until their own ctx.Done
or a failed write. True, but for MemorySessionPresence it is HARMLESS,
and that is the useful half: the registry lives in the process that is
going away, so its entries die with it. There is nothing to reap. A
Redis-backed implementation does not inherit that — its entries outlive
the writing process, so a crash strands them permanently rather than for
30 seconds. Recorded as a hard constraint on the interface: any
out-of-process implementation must carry its own reaping story (TTL plus
heartbeat renewal, or instance-keyed ownership swept at startup).
Also documents the staleness window neither codex round surfaced, found
in my own pass: a clean disconnect deregisters immediately, an ungraceful
one is invisible until the next keepalive write fails, and the keepalive
is 30s. So the list can name a dead listener for up to ~30 seconds. That
bound is fine for a fire-and-forget channel — a push to a session that
died 5 seconds ago loses a message that was lost anyway — but consumers
must not upgrade it into a delivery guarantee. Shortening it means
shortening the keepalive, which taxes every idle connection; the right
answer for a consumer that needs delivery confidence is an ack, not a
faster heartbeat.
Verified: go build, go vet, make lint 0 issues, presence tests green
under -race.