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
3 changes: 3 additions & 0 deletions apps/cli-docs/src/fragments/commands/local.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,9 @@ Events with an exception type are `"type":"error"` records. Events without one,
such as `captureMessage` calls and Python `logging` records, are
`"type":"message"`. `-f error` returns both, so a script that keeps errors with
`jq 'select(.type=="error")'` should also keep `"message"` if it wants them.
An event whose payload is not JSON is a `"type":"invalid"` record with
`"level":"invalid"`, in this stream and in `event list`. `-f error` still shows
it, but `--verify` does not count it as an event from your app.

In JSON mode, event records are versioned NDJSON on standard output. Startup,
connection, and shutdown messages stay on standard error, so an agent can pipe
Expand Down
9 changes: 6 additions & 3 deletions docs/cli/local-control-plane.md
Original file line number Diff line number Diff line change
Expand Up @@ -393,13 +393,16 @@ sampled function rows are not counted.
Receiver ingestion bounds encoded bodies to 10 MiB and decoded bodies to 32 MiB.
Accepted envelopes get 200 with `{"id":"<event_id>"}`, or `{}` when the header
has no event ID, as Relay answers; sentry-elixir retries anything else.
Invalid compression returns 400, oversized bodies 413, unsupported media or
A body that is empty, whose first line is not a JSON object, or that fails to
decompress gets 400 with an `{"error":"…"}` reason, and the receiver keeps
nothing for it. Oversized bodies get 413, unsupported media or
encoding 415, and temporary admission overload 503. SDKs drop an envelope that
gets 413 without retrying, so `local run` and `local serve` print a warning in
their tail when that happens, at most one line every five seconds. Drops in
between are counted and printed as one line when the five seconds end. Session tails
get the notice from the daemon as a `sentry.local.oversized` stream event. Malformed envelopes remain
available for raw inspection and byte-exact download through their receiver IDs.
get the notice from the daemon as a `sentry.local.oversized` stream event. Envelopes whose items
are malformed remain available for raw inspection and byte-exact download through
their receiver IDs. An event item that is not JSON shows as `invalid`, not as an error.
Receivers drop `http.client` spans and breadcrumbs for requests to their own
loopback `/_local/` and `/stream` routes on the same port, which SDKs record for
their own deliveries, and do not retain an envelope that has nothing else left.
Expand Down
3 changes: 2 additions & 1 deletion packages/cli/src/commands/local/control-plane.ts
Original file line number Diff line number Diff line change
Expand Up @@ -572,7 +572,8 @@ export function createLocalControlPlane({
return result;
});
if (outcome === 410) return closed();
if (typeof outcome === "object") sessionStore.recordActivity(id);
if (typeof outcome === "object" && outcome.status === 200)
sessionStore.recordActivity(id);
return ingestResponse(c, outcome);
};
for (const path of SESSION_INGEST_PATHS) app.post(path, ingest);
Expand Down
22 changes: 14 additions & 8 deletions packages/cli/src/commands/local/envelope.ts
Original file line number Diff line number Diff line change
Expand Up @@ -418,8 +418,10 @@ export function withoutOwnDeliveries(
* that DSN holds the ingest capability, and session envelopes reach holders of
* the read capability, so drop the key. Only the header line is rewritten.
*/
export function withoutDsnHeader(body: Buffer): Buffer {
const parsed = readEnvelopeHeader(body);
export function withoutDsnHeader(
body: Buffer,
parsed = readEnvelopeHeader(body),
): Buffer {
if (!parsed || !("dsn" in parsed.header)) return body;
delete parsed.header["dsn"];
return Buffer.concat([
Expand All @@ -432,20 +434,24 @@ export function withoutDsnHeader(body: Buffer): Buffer {
* The envelope header's `event_id` as Relay prints it: 32 lowercase hex digits
* without hyphens. Undefined when the header has no valid event id.
*/
export function envelopeEventId(body: Buffer): string | undefined {
const eventId = readEnvelopeHeader(body)?.header["event_id"];
export function envelopeEventId(
header: Record<string, unknown>,
): string | undefined {
const eventId = header["event_id"];
if (typeof eventId !== "string") return;
const simple = eventId.replaceAll("-", "").toLowerCase();
return /^[0-9a-f]{32}$/.test(simple) ? simple : undefined;
}

/** The parsed first line of an envelope and where that line ends. */
export type EnvelopeHeader = { header: Record<string, unknown>; end: number };

/**
* Parse only the first line, without frame(): it would parse every item and
* reject envelopes that still have a usable header.
* reject envelopes that still have a usable header. Undefined when that line
* is not a JSON object, which Relay also rejects.
*/
function readEnvelopeHeader(
body: Buffer,
): { header: Record<string, unknown>; end: number } | undefined {
export function readEnvelopeHeader(body: Buffer): EnvelopeHeader | undefined {
const newline = body.indexOf(10);
const end = newline < 0 ? body.length : newline;
let header: unknown;
Expand Down
9 changes: 9 additions & 0 deletions packages/cli/src/commands/local/event-kind.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,15 @@ export function readMessageText(value: unknown): string | undefined {
return undefined;
}

/**
* Whether an `event` item could not be decoded. The receiver keeps an item
* that is not JSON as `{ data }`, without the `type` it adds to every decoded
* item, so it is neither an exception nor a message.
*/
export function isUndecodedEvent(event: Record<string, unknown>): boolean {
return !("type" in event) && typeof event["data"] === "string";
}

/** How an event reads: its kind, thrown type, and the text to show for it. */
export type EventDescription = {
kind: "exception" | "message" | undefined;
Expand Down
50 changes: 35 additions & 15 deletions packages/cli/src/commands/local/receiver-ingest.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { logger } from "../../lib/logger.js";
import {
createReceiverEnvelope,
envelopeEventId,
readEnvelopeHeader,
type ReceiverBuffer,
withoutDsnHeader,
withoutOwnDeliveries,
Expand All @@ -28,10 +29,21 @@ type ReceiverState = {
requests: Set<Promise<unknown>>;
};
/**
* Relay's body for an accepted envelope. SDKs such as sentry-elixir accept a
* An accepted envelope gets Relay's body. SDKs such as sentry-elixir accept a
* delivery only on HTTP 200 with this JSON, and retry anything else.
*/
type ReceiverAccepted = { id?: string };
type ReceiverAccepted = { status: 200; body: { id?: string } };
/** A body that is not an envelope: its JSON has the shape of Local's 410 body. */
type ReceiverRejected = { status: 400; body: { error: string } };
/** How the receiver answers a delivery: a JSON response or a bare status. */
export type IngestResult =
| ReceiverAccepted
| ReceiverRejected
| 400
| 410
| 413
| 415
| 503;
const receivers = new WeakMap<ReceiverBuffer, ReceiverState>();
const oversizedListeners = new WeakMap<ReceiverBuffer, Set<() => void>>();

Expand All @@ -52,22 +64,23 @@ export function onOversizedEnvelope(
/** Tell this receiver's listeners when a delivery got HTTP 413. */
export function reportIngestStatus(
buffer: ReceiverBuffer,
result: number | ReceiverAccepted,
result: IngestResult,
): void {
if (result !== 413) return;
for (const listener of oversizedListeners.get(buffer) ?? []) listener();
}

/** Answer an ingest request: 200 with the accepted JSON, otherwise the bare status. */
export function ingestResponse(
c: Context,
result: ReceiverAccepted | 400 | 410 | 413 | 415 | 503,
): Response {
if (typeof result === "object") return c.json(result);
/** Answer an ingest request with its JSON body, or with the bare status. */
export function ingestResponse(c: Context, result: IngestResult): Response {
if (typeof result === "object") return c.json(result.body, result.status);
if (result === 503) c.header("Retry-After", "1");
return c.body(null, result);
}

function rejected(error: string): ReceiverRejected {
return { status: 400, body: { error } };
}

/** Stop consuming chunked input as soon as its encoded body exceeds the limit. */
export async function readReceiverBody(
request: Request,
Expand Down Expand Up @@ -175,7 +188,7 @@ export function ingestReceiverEnvelope(
*/
closed?: boolean;
},
): Promise<ReceiverAccepted | 400 | 410 | 413 | 415 | 503> {
): Promise<Exclude<IngestResult, 400>> {
const contentType = input.contentType?.split(";")[0]?.trim().toLowerCase();
if (
contentType &&
Expand All @@ -190,7 +203,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<ReceiverAccepted | 400 | 410 | 413 | 503> => {
async (): Promise<Exclude<IngestResult, 400 | 415>> => {
if (generation !== state.generation) return 503;
let body = input.body;
if (encoding && encoding !== "identity") {
Expand All @@ -211,15 +224,22 @@ export function ingestReceiverEnvelope(
"code" in error &&
error.code === "ERR_BUFFER_TOO_LARGE"
? 413
: 400;
: rejected("The body could not be decompressed.");
}
}
if (generation !== state.generation) return 503;
if (body.length > MAX_DECODED_BYTES) return 413;
if (input.closed) return 410;
const eventId = envelopeEventId(body);
const accepted = eventId ? { id: eventId } : {};
if (input.dropDsnHeader) body = withoutDsnHeader(body);
// Reject bodies that are not envelopes, as Relay does, and retain nothing.
if (!body.length) return rejected("The envelope is empty.");
const header = readEnvelopeHeader(body);
if (!header) return rejected("The envelope header is not a JSON object.");
const eventId = envelopeEventId(header.header);
const accepted: ReceiverAccepted = {
status: 200,
body: eventId ? { id: eventId } : {},
};
if (input.dropDsnHeader) body = withoutDsnHeader(body, header);
const delivery = input.receiverUrl
? withoutOwnDeliveries(body, input.receiverUrl)
: body;
Expand Down
38 changes: 28 additions & 10 deletions packages/cli/src/lib/formatters/local.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
/** Tail formatters for the local dev server. */

import { describeEvent } from "../../commands/local/event-kind.js";
import {
describeEvent,
isUndecodedEvent,
} from "../../commands/local/event-kind.js";
import {
exceptionValues,
frameFile,
Expand Down Expand Up @@ -377,12 +380,14 @@ type ExceptionValue = {
*
* `kind` is `message` for events with no typed exception: `captureMessage`,
* Python `logging` records, and JavaScript messages that carry only a
* synthetic stack. It is `error` otherwise, with the exception type in
* `errorType` (`Error` when the event names none).
* synthetic stack. It is `invalid`, with level `invalid`, when the payload is
* not JSON, and `error` otherwise, with the exception type in `errorType`
* (`Error` when the event names none).
*/
type EventSummary = (
| { kind: "message" }
| { kind: "error"; errorType: string }
| { kind: "invalid" }
) & {
/** Event level (`fatal`, `error`, `warning`, `info`, `debug`); `error` when unset. */
level: string;
Expand All @@ -396,6 +401,13 @@ type EventSummary = (

/** Summarize an `event` item for its tail line, JSON record, or `event list` entry. */
export function summarizeEvent(event: Record<string, unknown>): EventSummary {
if (isUndecodedEvent(event)) {
return {
kind: "invalid",
level: "invalid",
text: "Event payload is not JSON",
};
}
// Exceptions are ordered oldest→newest; the last one is what was thrown.
const last = exceptionValues(event["exception"]).at(-1) as
| ExceptionValue
Expand Down Expand Up @@ -1195,7 +1207,8 @@ function formatJsonObservation(
/**
* Format an `event` item as a JSON object, including the best stack frame.
* Exceptions get `type: "error"` and an `error_type`; messages get
* `type: "message"` and no `error_type`.
* `type: "message"` and no `error_type`. An item that is not JSON gets
* `type: "invalid"` and `level: "invalid"`.
*/
function formatErrorJson(
payload: Record<string, unknown>,
Expand Down Expand Up @@ -1539,7 +1552,8 @@ const NOT_TELEMETRY_ITEM_TYPES = new Set([
/**
* Whether an envelope shows the app is set up: it holds an item the active
* filters let through, or, with no filters, any item that is not
* housekeeping.
* housekeeping. An event that is not JSON never counts, even though the tail
* shows it under `-f error`.
*/
export function envelopeHasTelemetry(
container: {
Expand All @@ -1550,11 +1564,15 @@ export function envelopeHasTelemetry(
activeFilters: ReadonlySet<FilterValue>,
): boolean {
const items = container.getParsedEnvelope()?.envelope[1] ?? [];
return items.some(([{ type }, payload]) =>
activeFilters.size > 0
? isItemIncluded(type, activeFilters, payload as Record<string, unknown>)
: type !== undefined && !NOT_TELEMETRY_ITEM_TYPES.has(type),
);
return items.some(([{ type }, payload]) => {
const item = payload as Record<string, unknown>;
if (ERROR_TYPES.has(type ?? "") && isUndecodedEvent(item)) {
return false;
}
return activeFilters.size > 0
? isItemIncluded(type, activeFilters, item)
: type !== undefined && !NOT_TELEMETRY_ITEM_TYPES.has(type);
});
}

/**
Expand Down
30 changes: 30 additions & 0 deletions packages/cli/test/commands/local/control-plane.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,36 @@ describe("Local control plane", () => {
expect(await gzipped.json()).toEqual({});
});

test("session ingest answers 200 with the id, and 400 to bodies that are not envelopes", async () => {
const plane = createLocalControlPlane({ controlToken: CONTROL_TOKEN });
const created = await plane.app.request("/_local/v1/sessions", {
method: "POST",
headers: controlHeaders(),
body: JSON.stringify({ label: "malformed", cwd: "/malformed" }),
});
const { id, ingestUrl } = await created.json();
const post = (body: string) =>
plane.app.request(ingestUrl, {
method: "POST",
headers: { "Content-Type": "application/x-sentry-envelope" },
body,
});
const eventId = "0b6e5f9cb8d44f4e9a6f3e1c2d7a8b90";
const valid = await post(
`{"event_id":"${eventId}"}\n{"type":"event"}\n{"message":"ok"}`,
);
expect(valid.status).toBe(200);
expect(await valid.json()).toEqual({ id: eventId });
for (const body of ["", '{not json\n{"type":"event"}\n{}']) {
const response = await post(body);
expect(response.status).toBe(400);
expect(await response.json()).toEqual({ error: expect.any(String) });
}
expect(plane.sessionStore.getBuffer(id).read({ all: true })).toHaveLength(
1,
);
});

test("replaces expired clientId sessions with usable fresh capabilities on creation", async () => {
let now = 1000;
const sessionStore = createLocalSessionStore({ now: () => now });
Expand Down
Loading
Loading