diff --git a/docs/cli/local-control-plane.md b/docs/cli/local-control-plane.md index 0a65dc51f..333c4ccc5 100644 --- a/docs/cli/local-control-plane.md +++ b/docs/cli/local-control-plane.md @@ -210,7 +210,10 @@ The **Capture actions** menu labels each action by its scope: This action is available only to a loopback-served viewer with existing receiver permissions. If deletion fails, the view stays paused and offers Reconnect. - **Stop capture** stops scoped-session ingestion immediately: later ingestion - receives HTTP 410, including requests whose bodies finish after Stop. Saved + receives HTTP 410, including requests whose bodies finish after Stop. A + request that was still being read at Stop and turns out too large gets 413, + and its `sentry.local.oversized` event reaches stream readers before the + closing session event. Saved events remain readable for three hours from the first stop; retries and attempted ingestion do not extend that deadline. Reloading the archive does not resume capture. Duplicate stop requests are guarded and requests time out diff --git a/packages/cli/src/commands/local/control-plane.ts b/packages/cli/src/commands/local/control-plane.ts index ea6ed42ee..19f9ca51e 100644 --- a/packages/cli/src/commands/local/control-plane.ts +++ b/packages/cli/src/commands/local/control-plane.ts @@ -15,6 +15,7 @@ import { receiverEnvelopeId, receiverEnvelopeReceivedAt, reportIngestStatus, + trackReceiverRequest, type ReceiverEnvelope, } from "./receiver-ingest.js"; import { type Context, Hono } from "hono"; @@ -482,32 +483,41 @@ export function createLocalControlPlane({ return c.body(null, 401); } - const body = await readReceiverBody(c.req.raw, MAX_BODY_BYTES); - if (typeof body === "number") { - reportIngestStatus(sessionStore.getBuffer(reference), body); - return c.body(null, body); - } - const encoding = c.req.header("content-encoding"); - const browserBeacon = - c.req.query("sentry_client")?.startsWith("sentry.javascript.browser") && - c.req.header("origin"); - // Close can occur while the body is being read. Check at the commit boundary. - if (sessionStore.resolve(reference).state === "retained") - return c.json( + const isClosed = () => sessionStore.resolve(reference).state === "retained"; + const closed = () => + c.json( { error: "Session is closed; create a new session to capture events." }, 410, ); + if (isClosed()) return closed(); const buffer = sessionStore.getBuffer(reference); - const status = await ingestReceiverEnvelope(buffer, { - body, - contentType: browserBeacon - ? SENTRY_CONTENT_TYPE - : (c.req.header("content-type") ?? ""), - encoding, - receiverUrl: c.req.url, - userAgent: c.req.header("user-agent"), + const browserBeacon = + c.req.query("sentry_client")?.startsWith("sentry.javascript.browser") && + c.req.header("origin"); + // Close can occur while the body is being read or decoded. Tracking the + // request lets close drain it, so a 413 reaches readers before the closing + // frame. Retention still stops at the close. + const status = await trackReceiverRequest(buffer, async () => { + const body = await readReceiverBody(c.req.raw, MAX_BODY_BYTES); + const result = + typeof body === "number" + ? body + : await ingestReceiverEnvelope(buffer, { + body, + contentType: browserBeacon + ? SENTRY_CONTENT_TYPE + : (c.req.header("content-type") ?? ""), + encoding: c.req.header("content-encoding"), + receiverUrl: c.req.url, + userAgent: c.req.header("user-agent"), + // Bodies that arrived before close are kept, even if close + // lands while they wait in the queue or decode. + closed: isClosed(), + }); + reportIngestStatus(buffer, result); + return result; }); - reportIngestStatus(buffer, status); + if (status === 410) return closed(); if (status === 503) c.header("Retry-After", "1"); if (status === 204) sessionStore.recordActivity(reference); return c.body(null, status); diff --git a/packages/cli/src/commands/local/receiver-ingest.ts b/packages/cli/src/commands/local/receiver-ingest.ts index 3ddac4526..fb128245a 100644 --- a/packages/cli/src/commands/local/receiver-ingest.ts +++ b/packages/cli/src/commands/local/receiver-ingest.ts @@ -21,6 +21,8 @@ type ReceiverState = { generation: number; queue: Promise; pending: Set>; + /** Requests still reading their body or reporting their status. */ + requests: Set>; }; const receivers = new WeakMap(); const oversizedListeners = new WeakMap void>>(); @@ -86,6 +88,7 @@ function stateFor(buffer: ReceiverBuffer): ReceiverState { generation: 0, queue: Promise.resolve(), pending: new Set(), + requests: new Set(), }; receivers.set(buffer, state); for (const method of ["clear", "reset"] as const) { @@ -98,10 +101,29 @@ function stateFor(buffer: ReceiverBuffer): ReceiverState { return state; } -/** Wait only for writes and controls admitted before this call. */ +/** Wait only for requests, writes, and controls admitted before this call. */ export async function drainReceiver(buffer: ReceiverBuffer): Promise { const state = stateFor(buffer); - await Promise.allSettled([...state.pending, state.queue]); + await Promise.allSettled([...state.requests, ...state.pending, state.queue]); +} + +/** + * Count a request in this receiver's drain from its first body byte to its + * status report, so a close waits to tell readers why a delivery it already + * started reading was rejected. + */ +export function trackReceiverRequest( + buffer: ReceiverBuffer, + request: () => Promise, +): Promise { + const { requests } = stateFor(buffer); + const operation = request(); + requests.add(operation); + void operation.then( + () => requests.delete(operation), + () => requests.delete(operation), + ); + return operation; } /** Keep retention updates between earlier writes and later admissions. */ @@ -127,8 +149,13 @@ export function ingestReceiverEnvelope( /** URL the delivery was posted to, which identifies the receiver's own routes. */ receiverUrl?: string; userAgent?: string | undefined; + /** + * Capture had stopped by the time the body finished arriving. The size + * limits still apply first, so a late oversized delivery reports 413. + */ + closed?: boolean; }, -): Promise<204 | 400 | 413 | 415 | 503> { +): Promise<204 | 400 | 410 | 413 | 415 | 503> { const contentType = input.contentType?.split(";")[0]?.trim().toLowerCase(); if ( contentType && @@ -143,7 +170,7 @@ export function ingestReceiverEnvelope( if (state.pending.size >= MAX_PENDING) return Promise.resolve(503); const generation = state.generation; const operation = state.queue.then( - async (): Promise<204 | 400 | 413 | 503> => { + async (): Promise<204 | 400 | 410 | 413 | 503> => { if (generation !== state.generation) return 503; let body = input.body; if (encoding && encoding !== "identity") { @@ -169,6 +196,7 @@ export function ingestReceiverEnvelope( } if (generation !== state.generation) return 503; if (body.length > MAX_DECODED_BYTES) return 413; + if (input.closed) return 410; const delivery = input.receiverUrl ? withoutOwnDeliveries(body, input.receiverUrl) : body; diff --git a/packages/cli/test/commands/local/session-lifecycle.test.ts b/packages/cli/test/commands/local/session-lifecycle.test.ts index c360e8e16..f22429d38 100644 --- a/packages/cli/test/commands/local/session-lifecycle.test.ts +++ b/packages/cli/test/commands/local/session-lifecycle.test.ts @@ -1,5 +1,8 @@ +import { gzipSync } from "node:zlib"; import { describe, expect, test } from "vitest"; import { createLocalControlPlane } from "../../../src/commands/local/control-plane.js"; +import { MAX_BODY_BYTES } from "../../../src/commands/local/server.js"; +import { LOCAL_OVERSIZED_EVENT } from "../../../src/commands/local/viewer-protocol.js"; import { createLocalSessionStore, SESSION_RETENTION_MS, @@ -85,6 +88,87 @@ describe("Local session lifecycle", () => { ).toBe(0); }); + /** + * Start a chunked ingest with one byte, close the session while the body is + * still being read, then send the rest. The tail must hear about the 413 + * before the session's closing frame. + */ + async function closeDuringOversizedIngest( + body: Uint8Array, + headers: Record = {}, + ) { + const f = await fixture(); + const tail = (await f.app.request(f.session.streamUrl)).text(); + let controller: ReadableStreamDefaultController | undefined; + let firstByteRead: () => void = () => {}; + const reading = new Promise((resolve) => { + firstByteRead = resolve; + }); + const pending = f.app.request(f.session.ingestUrl, { + method: "POST", + headers, + body: new ReadableStream({ + start(value) { + controller = value; + value.enqueue(body.subarray(0, 1)); + }, + // Called once the receiver has taken the first byte and wants more. + pull: () => firstByteRead(), + }), + duplex: "half", + } as RequestInit & { duplex: "half" }); + await reading; + await f.action("close"); + controller!.enqueue(body.subarray(1)); + controller!.close(); + const status = (await pending).status; + const text = await tail; + expect( + f.store.getRetention(f.session.id).getSettings().retainedEnvelopes, + ).toBe(0); + return { status, text }; + } + + test("tells the tail about an encoded 413 that finishes after close", async () => { + const { status, text } = await closeDuringOversizedIngest( + new Uint8Array(MAX_BODY_BYTES + 1).fill(120), + ); + expect(status).toBe(413); + expect(text).toContain(`event: ${LOCAL_OVERSIZED_EVENT}`); + expect(text.indexOf(`event: ${LOCAL_OVERSIZED_EVENT}`)).toBeLessThan( + text.lastIndexOf('"state":"retained"'), + ); + }); + + test("tells the tail about a decoded 413 that finishes after close", async () => { + const { status, text } = await closeDuringOversizedIngest( + gzipSync(Buffer.alloc(33 * 1024 * 1024)), + { "Content-Encoding": "gzip" }, + ); + expect(status).toBe(413); + expect(text).toContain(`event: ${LOCAL_OVERSIZED_EVENT}`); + expect(text.indexOf(`event: ${LOCAL_OVERSIZED_EVENT}`)).toBeLessThan( + text.lastIndexOf('"state":"retained"'), + ); + }); + + test("keeps a delivery whose body arrived before close, even while it decodes", async () => { + const f = await fixture(); + const pending = f.app.request(f.session.ingestUrl, { + method: "POST", + headers: { "Content-Encoding": "gzip" }, + body: gzipSync(envelope("x".repeat(8 * 1024 * 1024))), + }); + // The in-memory body is read within microtasks, so close lands while the + // delivery is decoding. + await new Promise((resolve) => setImmediate(resolve)); + await f.action("close"); + expect((await pending).status).toBe(204); + expect( + f.store.getRetention(f.session.id).getSettings().retainedEnvelopes, + ).toBe(1); + }); + test("notifies every reader about reset and close, then replays a finite archive", async () => { const f = await fixture(); await f.ingest("before-reset");