GET /v0/beads/events:watch holds a text/event-stream response open and emits
each committed mutation as it lands, so a consumer learns about a write when it
happens instead of on its next interval. It is a SIBLING of the paged read, not
a mode of it: `follow=true` would have given one operationId two media types,
two lifetimes, two limit rules and two capacity stories, and a client generated
from the document could not have described either.
THE CURSOR IS STILL THE CONTRACT, which is what makes this cheap to publish.
The server keeps no per-consumer state and remembers no subscription; a stream
is the `since` reads a poller would have performed, performed on its behalf
against the same ReadEventsJournalPage through the same read-only cursor. Every
event carries `id: <seq>`, so the checkpoint a client holds while streaming is
the number it would have held while polling, and `Last-Event-ID` — the header a
browser's EventSource resends by itself — takes exactly the value `since` takes.
That header WINS over the parameter, because the client that sends it did not
choose to: an EventSource reconnects to the URL it was built with, so honoring
`since` there would replay every record since the consumer started, on every
reconnect, forever. A nonempty unparseable one is a 400 naming the header rather
than a silent fallback, which would start a stream somewhere the client did not
ask for and never tell it; an EMPTY one means "no id yet" and defers to `since`,
because a client that always sets the header sends it empty on its first
connect and refusing that would break the request the header exists to serve.
Delivery is at-least-once against the client's own checkpoint: exactly once and
in order within a stream, duplicates only across a reconnect. No engine or
storage change — this consumes the poll read path.
EVERY REFUSAL IS DECIDED BEFORE THE FIRST BYTE — validation, the disabled 409,
the flush check, the stream cap, and then the first read, which is what turns a
pruned-past cursor into the paged read's own 410 rather than a 200 that
immediately reports its own failure. Exactly one failure can arrive after the
status is spent: a prune racing an open stream, emitted as a NAMED `truncated`
event carrying the 410's own body in the same encoding on one line (asserted
against Write's output, not merely agreeing with it), behind a raised `retry`
and followed by a close. Naming only the exception is what lets a bare
`onmessage` consumer treat an unrecognized event as "stop, this is not a
record"; one that ignores it does not lose records silently, it stalls loudly on
connect-time 410s, slowly. The other unreportable failure — a stored payload
that will not encode — ends the stream too, and names its seq in the log,
because it will end every stream that reaches that row and nothing else would
say which one it is.
THREE LIMITS HAD TO MOVE, and the middle one is the trap.
- requestDeadline (60s) does not apply to a streaming row. For every other
operation it is the backstop against a request holding resources forever;
here it would do nothing but sever the stream. Each READ carries a 15s
deadline instead — a liveness budget rather than a database one, since it
also bounds how long a stream can go without a heartbeat and how long it can
ignore a shutdown.
- http.Server.ReadTimeout (30s) had to be cleared per request, BEFORE the
connect read. There is no WriteTimeout on this server — statusWriter rolls a
deadline forward before every write, which bounds one stalled write rather
than a stream, and needs nothing here — but ReadTimeout is a deadline on the
WHOLE request, and net/http keeps a background read running while a handler
writes: the read that notices a disconnect. Its expiry cancels the request
context, so an idle stream would end itself at thirty seconds with no client
involved, and a database wedged during the connect read would be booked as
`client_closed`. Clearing it costs no disconnect detection — a client that
leaves still produces a read error — and a peer that vanishes without a FIN
is reaped by TCP keepalive, which Go's listener enables by default
(measured: 15s idle, 15s interval, 9 probes; ~150s).
- The database slot moves from the request to the read. Sixteen slots and
forty-eight stream places means one slot per open stream would let a handful
of idle consumers starve every other operation for hours with /healthz
green; a stream now takes a slot for the moment of each poll and gives it
back, and slot pressure delays a pass instead of ending a stream.
Streams are capped at 48, SIXTEEN BELOW the 64-connection limit, and the gap is
load-bearing arithmetic rather than caution: LimitListener returns a connection
slot only when the connection closes, which is after the handler returned and
after this counter came down, so a cap at maxConns could never be observed — the
connect that should earn the 503 would never be accepted, and neither would the
poll it is told to fall back to, nor a mutation, nor a fresh-connection
/healthz. The headroom makes the refusal deliverable; `events_watch_admitted`
carries the live gauge on every connect so accumulation is visible before the
cliff. Each stream jitters its own poll phase by ±10%, because consumers
reconnect together after a restart on one shared `retry` and a fixed interval
would march them into a single read burst per second forever. And a graceful
shutdown signals its streams (RegisterOnShutdown) rather than waiting them out;
the loop consults that signal and the client on EVERY pass, including the
draining ones, so a week-old backlog stays cancellable within one batch.
Tests: handler-level over live delivery (mutations land AFTER the connect),
id=seq, heartbeats, Last-Event-ID precedence including a stale header against a
live `since` and the empty-header polarity, the 400/409/410 connect legs, a
prune under an open stream, the cap and its 503, the cap's headroom against
maxConns, backlog drains cancelled by both a hangup and a shutdown, slot release
on every exit, a stream sharing a single-slot semaphore with a paged read, the
flusher refusal, the read-deadline clear and its ordering against the connect
read, jitter spread, and a clean drain with a stream open — all under -race.
Framing is pinned against a record whose payload carries literal newlines, a CR
and a `data:` line of its own. Two e2e legs through a real `bd serve`: mutate on
one connection while streaming on another under a 10s arrival bound, then
reconnect with Last-Event-ID and require the resume, plus the disabled refusal.
Mutated and each caught: the mid-stream truncated event, Last-Event-ID
precedence, the empty-header polarity, the cap decrement, the cap's headroom,
the drain-cancel fast path, the read-deadline clear and its ordering, the poll
jitter, the shutdown exit, and the deadline exemption.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
194 lines
9.3 KiB
Go
194 lines
9.3 KiB
Go
package httpapi
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"io"
|
|
"net/http"
|
|
|
|
"github.com/steveyegge/beads/internal/eventsjournal"
|
|
"github.com/steveyegge/beads/internal/storage"
|
|
)
|
|
|
|
// The durable events journal, published as a read.
|
|
//
|
|
// This is the operation that lets a hosted consumer stop shelling out to
|
|
// `bd events tail`. The records it serves are the SAME records that command
|
|
// prints — literally, through eventsjournal.NewRecord, which is the one
|
|
// projection from a stored row onto the published envelope and is byte-pinned
|
|
// by the CLI's golden fixture. There is no wire struct in this package for a
|
|
// journal record and there must never be one: a mirror here would satisfy its
|
|
// own tests while serving a `ts` in a different shape or a `dep` that appeared
|
|
// when empty, and the consumer that notices is the one reconciling an HTTP
|
|
// mirror against a CLI export at three in the morning.
|
|
//
|
|
// WHAT IS NOT HERE, in the reads.go tradition. No seq arithmetic, no gap
|
|
// detection, no decision about whether a page is contiguous: that is
|
|
// issueops.ComputeEventsTruncation, which every read plumbing runs, and it
|
|
// reaches this file as a typed error that problem.go maps. A handler that
|
|
// decided for itself whether a batch was continuous would be a second retention
|
|
// contract, and the failure mode of getting it wrong is silent record loss —
|
|
// which is the one thing this feature exists to prevent.
|
|
//
|
|
// NO FOLLOW MODE ON THIS OPERATION, and adding one is not the way to get a
|
|
// push feed: `follow=true` would give one operationId two contracts — two media
|
|
// types, two lifetimes, two limit rules — and a client generated from the
|
|
// document could not describe either. The push feed is a SIBLING operation,
|
|
// events_watch.go, which consumes this same read path. `head` is what makes
|
|
// polling cheap to pace: a consumer that sees its last seq equal to `head`
|
|
// knows it is caught up and can back off, instead of inferring it from a short
|
|
// page.
|
|
//
|
|
// A poller is still the path that is always needed — it is what a dropped
|
|
// stream reconnects through, and it holds nothing between requests — which is
|
|
// why it landed first and why the stream's saturation refusal points back here.
|
|
|
|
// Journal paging bounds. There is no unlimited read here, unlike the issue
|
|
// listings: a caller resuming from an old checkpoint would otherwise ask one
|
|
// process to buffer the entire retained window — a hundred thousand records
|
|
// under the shipped retain-rows floor — and encode it into one response.
|
|
//
|
|
// The default is deliberately much larger than the issue listings' 50. A
|
|
// journal consumer is a machine draining a backlog in order, not a person
|
|
// reading a page, and its cost per record is a fraction of an issue row's; the
|
|
// interesting number for it is round trips to catch up, which at 50 would be
|
|
// two thousand for a full window.
|
|
const (
|
|
defaultEventsLimit = 1000
|
|
maxEventsLimit = 10000
|
|
)
|
|
|
|
// handleListEvents answers GET /v0/beads/events.
|
|
func (s *Server) handleListEvents(w http.ResponseWriter, r *http.Request) {
|
|
q := newQuery(r.URL.Query())
|
|
|
|
// Read BOTH parameters before deciding anything, so an unknown third one is
|
|
// still reported by the shared rule rather than shadowed by the `since`
|
|
// refusal below.
|
|
since := q.integer64("since")
|
|
limit := q.boundedLimit(defaultEventsLimit, maxEventsLimit)
|
|
|
|
if !s.acceptQuery(w, r, q) {
|
|
return
|
|
}
|
|
// `since` is required, and its absence is refused HERE rather than defaulted
|
|
// to 0 — the tree walker's argument for `root_id`, with more at stake. A
|
|
// missing checkpoint defaulted to zero would serve the whole retained window
|
|
// to a consumer that meant to resume, which reads as a flood of duplicate
|
|
// records rather than as an error.
|
|
//
|
|
// A NEGATIVE checkpoint is refused for the reason `bd events tail --since`
|
|
// refuses one: it is almost always arithmetic on an empty cursor, and
|
|
// `seq > -5` would quietly serve everything as though it were a legitimate
|
|
// resume. q.integer64 has already refused a value that is not an integer at
|
|
// all, so reaching here with a non-nil pointer means it parsed.
|
|
if since == nil || *since < 0 {
|
|
requestInfo(r.Context()).refuse("since")
|
|
s.fail(w, r, InvalidArgument("since", ReasonInvalidValue,
|
|
"since is required and must be zero or a positive sequence number; use 0 to read from the beginning"))
|
|
return
|
|
}
|
|
|
|
// The activation gate, BEFORE the read. A disabled journal answers zero rows
|
|
// and a head of zero, which is indistinguishable from an enabled journal
|
|
// nothing has written to yet — so a consumer would poll a workspace that
|
|
// will never produce a record and call itself caught up. This is the only
|
|
// place the difference is knowable, and it costs no database round trip.
|
|
if !s.cfg.EventsJournalEnabled {
|
|
s.fail(w, r, EventsJournalDisabled())
|
|
return
|
|
}
|
|
|
|
cursor, err := s.eventsJournalCursor(r)
|
|
if err != nil {
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
page, err := cursor.ReadEventsJournalPage(r.Context(), *since, limit)
|
|
if err != nil {
|
|
// A pruned-past checkpoint arrives as *storage.EventsJournalTruncatedError
|
|
// and leaves as the 410 with its window attached; ClassifyError owns that
|
|
// row, so this handler has no special case for it.
|
|
s.failErr(w, r, err)
|
|
return
|
|
}
|
|
|
|
writeEventsPage(w, page)
|
|
}
|
|
|
|
// writeEventsPage streams the answer instead of building it.
|
|
//
|
|
// writeJSON would cost two further whole-page copies on top of the rows the
|
|
// seam already handed back: one []Record slice, whose json.RawMessage members
|
|
// copy every stored payload out of its string, and then encoding/json's own
|
|
// buffer, which assembles the entire body before a byte reaches the socket. At
|
|
// the 10000-record ceiling with issue payloads of a few hundred bytes that is
|
|
// tens of megabytes of transient garbage per request, times the sixteen
|
|
// requests this server admits at once. Here each record is projected and
|
|
// encoded on its way out, so the live cost is one record rather than the page.
|
|
//
|
|
// FULL CURSOR STREAMING — reading rows off the database cursor and emitting
|
|
// them without materializing the page at all — is deliberately NOT what this
|
|
// does, and cannot be until the retention contract changes. The truncation
|
|
// check needs the whole batch in memory: firstEventsSeqGap makes a linear pass
|
|
// looking for an interior hole, and it must reach a verdict BEFORE the first
|
|
// byte of a 200 is written, because a gap discovered halfway through a body is
|
|
// no longer expressible as the 410 the contract promises. Materialized rows
|
|
// are bounded by the limit cap; the two copies removed here were not bounded
|
|
// by anything the caller could not raise.
|
|
//
|
|
// The member names, their order and the `head` type all come from
|
|
// apigen.EventsPage, which is the document's shape — not from this function's
|
|
// opinion of it. TestEventsStreamsExactlyTheGeneratedEnvelope encodes the same
|
|
// data through that generated struct and requires the two to be byte-identical,
|
|
// so this stays one wire shape rather than a second one that agrees today.
|
|
func writeEventsPage(w http.ResponseWriter, page storage.EventsJournalPage) {
|
|
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
|
w.WriteHeader(http.StatusOK)
|
|
|
|
// `head` LEADS, because that is the order the generated envelope serializes
|
|
// its fields in and this body must be the same bytes. It happens to be the
|
|
// better order for a streaming reader too — the pacing number arrives before
|
|
// the page it describes — but the reason it is written this way is the pin.
|
|
//
|
|
// gosec's taint analysis flags every direct write to a ResponseWriter as a
|
|
// possible XSS sink, because it cannot see a Content-Type. It is
|
|
// application/json here, set above, and both writes below are the output of
|
|
// encoding/json — a decimal integer and one marshaled record — never a
|
|
// caller string reflected into a document. writeJSON is unflagged only
|
|
// because the encoder hides the write, which is the same bytes.
|
|
//nolint:gosec // G705: application/json body, JSON-encoded content, no HTML sink.
|
|
if _, err := fmt.Fprintf(w, `{"head":%d,"records":[`, page.Head); err != nil {
|
|
return
|
|
}
|
|
for i, row := range page.Rows {
|
|
// json.Marshal rather than an Encoder: Encode appends a newline per
|
|
// value, and while that is insignificant JSON whitespace it would put
|
|
// this body one byte per record away from the generated envelope's, and
|
|
// the byte-identity test below is what keeps the two one shape.
|
|
encoded, err := json.Marshal(eventsjournal.NewRecord(row))
|
|
if err != nil {
|
|
// Unreachable for a well-formed row, and a truncated 200 is all the
|
|
// client can be told either way: the status is already on the wire.
|
|
// The alternative — buffering the whole body to keep the option of
|
|
// a 500 — is the cost this function exists to avoid, and writeJSON
|
|
// does not buy it either.
|
|
return
|
|
}
|
|
if i > 0 {
|
|
if _, err := w.Write([]byte(",")); err != nil {
|
|
return
|
|
}
|
|
}
|
|
//nolint:gosec // G705: as above — encoding/json output into an application/json body.
|
|
if _, err := w.Write(encoded); err != nil {
|
|
return
|
|
}
|
|
}
|
|
// `records` is never null: an empty page closes an empty array here, so a
|
|
// caught-up consumer decodes a list of length zero rather than having to
|
|
// treat a missing member as one. The trailing newline is writeJSON's, kept
|
|
// so this body and a generated one are the same BYTES rather than merely
|
|
// the same document.
|
|
_, _ = io.WriteString(w, "]}\n")
|
|
}
|