Skip to content
Open
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
5 changes: 4 additions & 1 deletion docs/cli/local-control-plane.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
52 changes: 31 additions & 21 deletions packages/cli/src/commands/local/control-plane.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import {
receiverEnvelopeId,
receiverEnvelopeReceivedAt,
reportIngestStatus,
trackReceiverRequest,
type ReceiverEnvelope,
} from "./receiver-ingest.js";
import { type Context, Hono } from "hono";
Expand Down Expand Up @@ -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);
Expand Down
36 changes: 32 additions & 4 deletions packages/cli/src/commands/local/receiver-ingest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ type ReceiverState = {
generation: number;
queue: Promise<unknown>;
pending: Set<Promise<unknown>>;
/** Requests still reading their body or reporting their status. */
requests: Set<Promise<unknown>>;
};
const receivers = new WeakMap<ReceiverBuffer, ReceiverState>();
const oversizedListeners = new WeakMap<ReceiverBuffer, Set<() => void>>();
Expand Down Expand Up @@ -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) {
Expand All @@ -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<void> {
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<T>(
buffer: ReceiverBuffer,
request: () => Promise<T>,
): Promise<T> {
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. */
Expand All @@ -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 &&
Expand All @@ -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") {
Expand All @@ -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;
Expand Down
84 changes: 84 additions & 0 deletions packages/cli/test/commands/local/session-lifecycle.test.ts
Original file line number Diff line number Diff line change
@@ -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,
Expand Down Expand Up @@ -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<string, string> = {},
) {
const f = await fixture();
const tail = (await f.app.request(f.session.streamUrl)).text();
let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
let firstByteRead: () => void = () => {};
const reading = new Promise<void>((resolve) => {
firstByteRead = resolve;
});
const pending = f.app.request(f.session.ingestUrl, {
method: "POST",
headers,
body: new ReadableStream<Uint8Array>({
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");
Expand Down
Loading