@crvouga/mockingbird-service-sentry

Local emulators. Real API contracts. Part of Mockingbird.

A stateful Sentry SDK transport and event/issue assertion emulator. This initial package is wip: its bounded surface follows the official envelope protocol and Relay responses, not the entire Sentry product. No vendor account, container, secret or outbound call is needed for tests.

Install

bun add -d @crvouga/mockingbird-service-sentry

Usage

import * as Sentry from "@sentry/node"
import { DEFAULT_PROJECT } from "@crvouga/mockingbird-service-sentry"
import { createServer } from "@crvouga/mockingbird-service-sentry/server"

// Test setup: the emulator, and a DSN that points the Sentry SDK at it.
const server = await createServer()
const dsn = `${server.url.replace("://", `://${DEFAULT_PROJECT.publicKey}@`)}/1`

// The app's own Sentry calls.
Sentry.init({ dsn })
Sentry.captureMessage("Fixture failure", { fingerprint: ["fixture-group"] })
await Sentry.flush(2000)

// The test asserts on what the emulator captured.
const captured = await (await fetch(`${server.url}/__admin/events?project=1`)).json()
console.log(captured.events.length) // 1
await Sentry.close()
await server.close()

The official @sentry/nextjs and @sentry/node SDKs both take that DSN: start createServer() from the /server entry and set SENTRY_DSN to http://<DEFAULT_PROJECT.publicKey>@127.0.0.1:<port>/1, or give it to init/NodeClient. Both SDKs are tested at 11.4.0 (the report supplied no pinned version). Use SDK flush() to finish submission, then POST /__admin/flush {"eventIds": […], "count": n} for an immediate assertion: flushed: false means the condition is not met; it never sleeps.

REST requests use Authorization: Bearer fixture-rest-token. projects and restTokens options replace these constructor fixtures. Each project includes its organization, numeric-string ID, slug, name and 32-hex public key. The defaults are obviously synthetic. Each namespace receives its own constructor fixtures and returns to them on reset.

mockingbird-sentry serve --port 8810

Routes and behavior

• POST /api/{project}/envelope/: byte-accurate envelope parsing, implicit or explicit lengths, UTF-8 JSON headers, binary attachments, unknown item retention, event/transaction/session/ sessions/client-report items. Gzip/deflate request compression is supported. Responses are 200 {"id": "<event ID>"} when an ID applies, or 200 {} for session/report-only envelopes.
• POST /api/{project}/store/: JSON event ingestion; generates a deterministic 32-hex event ID when absent. Legacy message: false is accepted and ignored, matching Relay LogEntry; raw input attributes cannot overwrite normalized REST fields. Event IDs dedupe per project, including concurrent retries: a replay returns the same ID without a second capture, issue count or attachment.
• POST /api/{project}/minidump/: raw native minidump or multipart upload_file_minidump, optional sentry JSON and additional files. Returns the hyphenated event UUID as plain text, like Relay. Validates the MDMP/PMDM magic and retains bytes; native crash symbolication is not simulated.
• GET /api/0/projects/{organization}/{project}/events/: error events newest first, bare array, full=true caps a page at 10. Transactions remain available in event detail and admin search.
• GET /api/0/projects/{organization}/{project}/events/{event}/: event ID, message/title, exception/stacktrace entries, contexts, breadcrumbs, tags and fixture user identity.
• GET /api/0/projects/{organization}/{project}/issues/: bare-array groups; defaults to is:unresolved, query= includes all statuses. Explicit fingerprints take priority; fallback grouping is deterministically based on exception title/frames, or message when configured.
• GET/PUT /api/0/issues/{issue}/ and /api/0/organizations/{organization}/issues/{issue}/: read or set status to unresolved, resolved, or ignored. Resolving persists until an explicit status update; automatic regression detection is outside this initial emulator.
• GET /api/0/projects/{organization}/{project}/events/{event}/attachments/ and /{attachment}/: attachment metadata; ?download=1 on detail returns the original bytes to the authenticated caller.

Read pagination uses limit (1–100), cursor=0:<offset>:<previous flag> and Sentry's Link header with both rel="previous" and rel="next", their cursors, and results="true|false". Stable insertion order avoids duplicates when walking a fixed result set. Links preserve filters and the selected namespace, including a custom admin prefix. The emulator supports release/tag/trace and status filters; production search syntax, sampling, trend/rank sorting and statistics are not silently represented as implemented features (see boundaries below).

Ingest auth accepts X-Sentry-Auth: Sentry sentry_key=…, sentry_version=7, query sentry_key with optional sentry_version, or a self-authenticated envelope DSN. Conflicting header/query credentials, missing auth, malformed keys, incompatible protocol versions, bad envelopes and unknown project keys receive Relay-shaped {"detail": "…"} errors. There is no invented generic API error code or request ID: the ingest response's id is the vendor event identifier. Exact production quota, filter-reason details and REST error text beyond the documented cases are bounded approximations. The default payload ceiling is 20 MiB, configurable with maxPayloadBytes.

Test controls

All internal endpoints move together with adminPrefix (default /__admin). Namespace carriers: x-mockingbird-namespace, /__admin/ns/<suite>/…, or DSN query/header credentials and REST tokens mapped with PUT /__admin/credentials. Self-authenticated envelope-only DSNs use header/path namespaces; credential mapping cannot inspect a body before the shared runtime selects a namespace. Clock, reset, Timeline checkpoints/branches and snapshot aliases, request journal, metrics, admin UI, collection introspection and generic faults are the shared service contract.

• GET /__admin/events?project=1&release=…&tag=key:value&trace=…: normalized captured errors and transactions. All listed fields, timestamps, fingerprints, tags, contexts and breadcrumbs survive subject to redaction; user retains only the fake fixture id.
• GET /__admin/issues: matching groups with current resolution state, using the same filters.
• GET /__admin/envelopes?project=1: item/header metadata and rejection flags; never raw bytes.
• GET/PUT /__admin/settings: grouping: "exception"|"message", sensitivePaths (dot paths; defaults request.data, request.cookies) and rejectItems (types to discard while accepting other items with 200). These are synthetic controls, not public Sentry settings APIs.
• POST /__admin/flush {eventIds?, count?, project?}: immediate capture condition/result.
• POST /__admin/issues/{id}/status {status}: resolve/reopen/ignore.
• POST /__admin/projects/{id}/clear: clear that project's telemetry while retaining its fixture.

Presets: rate_limited (429, Retry-After: 60, X-Sentry-Rate-Limits: 60:error:organization), server_error (503), network_reset (socket drop) and item_rejected (synthetic 403 filter). Each is scoped to ingestion and operates before writes. Generic faults can force other 5xx/429 responses. The official SDK test proves error-category quotas drop further errors without blocking transactions. It verifies behavior immediately, without retry sleeps.

Raw capture and redaction

Authorization/cookies and credential-named fields are filtered recursively, including header pairs. Configured sensitive body paths are filtered before normalized data enters storage or vendor/admin diagnostics. Personal email, name and IP attributes are dropped. Journals/log sinks contain request metadata and resource IDs only, never bodies, headers or attachment bytes. Raw wire bodies and attachment bytes are retained encrypted with AES-GCM in ordinary Collections, so reset/Timeline cover them without disclosing plaintext through generic state diagnostics. runtime.instance(namespace).rawEnvelope(id) is explicit programmatic owner access to original wire bytes; it is not exposed by an admin HTTP route. Supply a captureKey from createCaptureKey() when reopening persistent SQLite storage; the default key lives only for that runtime's lifetime. Treat this explicit raw access as sensitive test-owner access. Normal event/detail/search paths return redacted data, while authenticated attachment download is an explicit byte retrieval.

Oracle evidence

• Official envelope grammar and item rules.
• Official transport rate limits.
• Official pagination headers and cursor examples.
• Project event list, project issue list and issue detail.
• Relay envelope response, auth status/messages, ingest errors, quota headers and minidump response.
• Relay legacy message normalization explicitly ignores message: false; its CI-discovered seed is retained in the regression registry.
• Official npm SDK source for @sentry/node, @sentry/core and @sentry/nextjs 11.4.0; served tests use the actual clients and transport, not a reimplementation of SDK quota handling.

bun run parity:service -- sentry requires SENTRY_API_URL, SENTRY_AUTH_TOKEN, SENTRY_ORGANIZATION_SLUG, SENTRY_PROJECT_ID and SENTRY_PROJECT_SLUG. The runner compares only safe reads and never submits to a live vendor. Tests need none of these keys. Live parity has not been claimed without access; docs and SDK source are the initial oracle.

Deliberately not modelled

Vendor dashboards/billing, full organization/project/release management, production quotas, complete search DSL and search time windows, sort modes other than newest/last-seen, statistical series/sampling, source-map/native symbolication, sessions aggregate analytics, profiling/replays, full crash dump validation, legacy compressed-base64 store ingestion, automatic issue regressions, alert-rule evaluation or optional issue-alert webhooks. Unknown envelope items are retained, not processed as unsupported product features. Group fallback rules and forced filter behavior are explicit deterministic test policies, not Sentry's production grouping algorithm. Issues are explicitly resolved/reopened by controls or vendor PUT, and never invent asynchronous workers.

API

Main entry runtime exports: SentryAPI (fetch, reset, rawEnvelope, captured, issueWire, sqlite, state, app), createRuntime, SENTRY_NAMESPACE, SENTRY_PRESETS, DEFAULT_PROJECT, createCaptureKey, sentryCredential, document and supportedOperationIds. Types include SentryAPIOptions, SentryRuntime, SentryRuntimeOptions, ProjectFixture, SentrySettings, CapturedEvent, CapturedEnvelope, and IssueRecord. Server entry runtime exports: createServer, DEFAULT_PORT, serveTarget. Server types: SentryServer, SentryServerOptions. createServer returns {url, runtime, close, …}; close the server after each test. The CLI entry runs serve with the common host/port/admin-prefix options.