mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The browser UI loads plugin UI modules. The host fetches each module, rewrites its imports, and imports it from a random `blob:` URL > - Browser errors go to Sentry. A stack frame from a plugin module names only that random blob URL > - So a Sentry report cannot tell which plugin raised an error. For example, a plugin can abort its own request during an unmount, and the report shows only `blob:https://<host>/<uuid>` > - This pull request records each blob URL with its plugin key, and tags the Sentry event with that plugin key > - The benefit is that a plugin error can go to the correct plugin owner, and the blob URL is never sent ## Linked Issues or Issue Description Refs #22380, which marks the announcement card's own aborts as intentional. Some events in the same Sentry group come from a plugin module instead, and #22380 cannot cover them. **What happened?** Hosted browsers report `AbortError: signal is aborted without reason` as an unhandled rejection. The innermost frame is a React effect cleanup in a `blob:` module at line 5590. Only plugin UI modules run from `blob:` URLs in the main thread. The event has no data that names the plugin. **Expected behavior** A Sentry event from a plugin module names the plugin, so the plugin owner can fix the plugin. **Steps to reproduce** 1. Install a plugin with a UI slot whose effect cleanup calls `controller.abort()` on a pending `fetch` and does not catch the rejection. 2. Open a page with that slot. Then go to a page without it. 3. Sentry records an unhandled `AbortError` whose frame is a `blob:` URL and no plugin key. ## What Changed - `ui/src/lib/plugin-module-origins.ts`: a new, bounded registry (100 recent modules). `rememberPluginModuleUrl` records a blob URL with its plugin key. `readPluginModuleOrigin` finds the innermost `blob:` frame of an event and returns its plugin key, `unmapped`, or nothing. It never throws. - `ui/src/plugins/slots.tsx`: `importPluginModule` records the blob URL with the plugin key before the import. - `ui/src/lib/sentry.ts`: `beforeSend` sets the `browser_plugin_module` tag when an event has a `blob:` frame. The tag holds the plugin key (at most 200 characters) or `unmapped`. It never holds the URL. - Tests for the registry, the loader, and the Sentry hook. ## Verification - `cd ui && npx vitest run src/lib/plugin-module-origins.test.ts src/lib/sentry.test.ts src/plugins/slots-loading.test.tsx src/plugins/slots.test.ts src/hooks/useAnnouncement.test.tsx`: 69/69 pass. - Red first: with the source changes removed and the new tests kept, the Sentry test and the loader test fail (`expected 'unmapped' to be 'fixture.navigation'`). - `cd ui && npx vitest run src/lib src/plugins`: 279 files, 3231 tests pass. - `npx tsc --noEmit -p ui/tsconfig.json`: no errors in the changed files. ## Risks - Low risk. The change adds one tag. It does not drop, group, or change any event. - The tag holds a plugin key, which is a manifest identifier. It holds no URL, path, or user data. - The registry keeps at most 100 entries, so memory stays bounded when modules reload. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution, in Claude Code. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
306 lines
13 KiB
TypeScript
306 lines
13 KiB
TypeScript
// Optional Sentry error monitoring for the browser.
|
|
//
|
|
// Activated only when the signed-in session carries a Sentry DSN. `SentryGate`
|
|
// reads the DSN off `GET /api/auth/get-session` and calls
|
|
// `initBrowserErrorMonitoring` once. A signed-out browser, or a browser with
|
|
// no DSN, calls this module never — see `SentryGate.tsx`.
|
|
//
|
|
// Sign-out must stop monitoring, not just stop starting it: `SentryGate`
|
|
// calls `teardownBrowserErrorMonitoring` when the session's DSN goes away.
|
|
// The function detaches the client from the current scope first
|
|
// (`Sentry.getCurrentScope().setClient(undefined)`), then closes that same
|
|
// client (`client.close()`), so a signed-out page's global handlers find no
|
|
// attached client at any point. Detach runs first because a client stays
|
|
// attached, and stays enabled, for the whole close call — closing first
|
|
// would leave the signed-out page able to send one more event to Sentry for
|
|
// as long as the close call takes. Both calls are built-in Sentry client
|
|
// calls — no custom filter code.
|
|
//
|
|
// `initBrowserErrorMonitoring`, `teardownBrowserErrorMonitoring`,
|
|
// `captureBrowserException`, and `captureQueryException` each queue their
|
|
// work on one shared promise chain (`enqueue`) instead of running at once.
|
|
// One operation runs at a time, in call order, so no operation can ever
|
|
// observe another one part-finished — a sign-out always closes the client a
|
|
// sign-in already finished starting, never one still starting.
|
|
//
|
|
// `@sentry/browser` loads through a dynamic import, so Vite puts it in a
|
|
// separate chunk that a browser with no DSN never fetches.
|
|
//
|
|
// Default-integration privacy note: two default integrations copy values
|
|
// this app does not want inside a Sentry event, so the initializer removes
|
|
// them with a built-in Sentry option — no custom filter code:
|
|
// - `Breadcrumbs` turns a console call, a click, and a fetch call into a
|
|
// breadcrumb with the raw arguments and the raw request URL.
|
|
// - `HttpContext` copies the page URL, the query string, and the referrer
|
|
// onto every event.
|
|
// The initializer keeps every other default integration, so the browser
|
|
// still captures `window.onerror` and `window.onunhandledrejection`
|
|
// (`GlobalHandlers`), the two React error boundaries, deduplicates a repeat
|
|
// event (`Dedupe`), and links a caused-by chain (`LinkedErrors`).
|
|
//
|
|
// Without `Breadcrumbs`, nothing in the SDK wraps `fetch`, so a browser's
|
|
// stackless `TypeError: Failed to fetch` arrives with no caller. Once a DSN
|
|
// starts monitoring, `fetch-rejection-origin.ts` wraps `fetch` itself and
|
|
// tags an unhandled rejection with an enum for who started the request. It
|
|
// sends no URL, path, or stack text.
|
|
//
|
|
// Plugin UI modules run from random `blob:` URLs. `plugin-module-origins.ts`
|
|
// maps such a frame back to its plugin key and tags the event with it.
|
|
|
|
import {
|
|
buildBrowserErrorContext,
|
|
buildQueryErrorContext,
|
|
classifyRejectionReason,
|
|
readBrowserErrorState,
|
|
readPageLifecycle,
|
|
startPageDiagnostics,
|
|
takeRejectionEventSnapshot,
|
|
type BrowserErrorDetails,
|
|
} from "./browser-error-context";
|
|
import {
|
|
readFetchInitiator,
|
|
readFetchWrapperState,
|
|
startFetchRejectionDiagnostics,
|
|
} from "./fetch-rejection-origin";
|
|
import { isIntentionalAbortReason } from "./intentional-abort";
|
|
import { readPluginModuleOrigin } from "./plugin-module-origins";
|
|
|
|
let queue: Promise<void> = Promise.resolve();
|
|
|
|
/** Run gate operations one at a time, in call order. */
|
|
function enqueue(op: () => Promise<void>): Promise<void> {
|
|
const next = queue.then(op);
|
|
queue = next.catch(() => {});
|
|
return next;
|
|
}
|
|
|
|
/** The `@sentry/browser` module shape, resolved once. */
|
|
type SentryBrowserModule = typeof import("@sentry/browser");
|
|
|
|
/**
|
|
* The `Sentry.init` options this gate builds. `Sentry.init`'s parameter is
|
|
* optional, so `Parameters<...>[0]` alone carries an `| undefined` arm this
|
|
* gate never returns. `NonNullable` removes only that arm — the object shape
|
|
* underneath stays the true `@sentry/browser` option type.
|
|
*/
|
|
type BrowserSentryInitOptions = NonNullable<Parameters<SentryBrowserModule["init"]>[0]>;
|
|
|
|
let sentry: SentryBrowserModule | null = null;
|
|
|
|
/**
|
|
* Load `@sentry/browser` and start the client with the given DSN. Idempotent
|
|
* — the session query can refetch and call this again, and a second call is
|
|
* a no-op because a client is already started.
|
|
*/
|
|
export function initBrowserErrorMonitoring(dsn: string, environment?: string | null): Promise<void> {
|
|
return enqueue(async () => {
|
|
if (sentry) return;
|
|
try {
|
|
const Sentry = await import("@sentry/browser");
|
|
// Before init: the rejection snapshot listener must precede the SDK's
|
|
// `onunhandledrejection` handler. Diagnostics never block monitoring.
|
|
try {
|
|
startPageDiagnostics();
|
|
} catch { /* diagnostic unavailable */ }
|
|
try {
|
|
startFetchRejectionDiagnostics();
|
|
} catch { /* diagnostic unavailable */ }
|
|
Sentry.init(buildBrowserSentryInitOptions(dsn, environment));
|
|
sentry = Sentry;
|
|
} catch (err) {
|
|
// The dynamic import or the init call failed. Fall through with a
|
|
// single diagnostic. The gate fails open — the app keeps running
|
|
// without error monitoring rather than crashing on an opt-in feature.
|
|
// eslint-disable-next-line no-console
|
|
console.error("[paperclip] Sentry browser bootstrap failed", err);
|
|
}
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Stop browser error monitoring and forget the started client. Call this on
|
|
* sign-out, so the browser sends Sentry no more events and no more
|
|
* breadcrumbs after the session ends. A no-op when monitoring never started.
|
|
*
|
|
* Detaches the client from the current scope, then closes that same client.
|
|
* A client stays attached, and stays enabled, for the whole close call — a
|
|
* signed-out page's `window.onerror` or `window.onunhandledrejection`
|
|
* handler would still reach it for as long as the close call takes.
|
|
* Detaching first removes that window instead of leaving it open.
|
|
*/
|
|
export function teardownBrowserErrorMonitoring(): Promise<void> {
|
|
return enqueue(async () => {
|
|
const Sentry = sentry;
|
|
sentry = null;
|
|
if (!Sentry) return;
|
|
// Read the client before detaching it. The scope holds no client after
|
|
// detach, so the close step below needs this reference to flush and
|
|
// close the right client.
|
|
const client = Sentry.getClient();
|
|
// Detach first, close second — the opposite order from a plain
|
|
// `Sentry.close()` call, which reads the client off the current scope
|
|
// and would find nothing to close if detach ran first. A separate
|
|
// guarded try keeps this step unable to reject, unlike a bare finally
|
|
// block: a thrown error here would still reach the caller, and
|
|
// `SentryGate.tsx` discards this function's returned promise with a
|
|
// bare `void` call, so a rejection would surface as an unhandled
|
|
// promise rejection in the browser.
|
|
try {
|
|
Sentry.getCurrentScope().setClient(undefined);
|
|
} catch (err) {
|
|
// eslint-disable-next-line no-console
|
|
console.error("[paperclip] Sentry client detach failed", err);
|
|
}
|
|
// A second, separate guarded try, for the same reason as the one
|
|
// above: this step must never reject the returned promise.
|
|
try {
|
|
// Awaiting matters: the client flushes buffered events to Sentry
|
|
// during close; a caller that does not wait may navigate away, or
|
|
// the page may unload, before the flush finishes.
|
|
await client?.close(2_000);
|
|
} catch (err) {
|
|
// eslint-disable-next-line no-console
|
|
console.error("[paperclip] Sentry teardownBrowserErrorMonitoring failed", err);
|
|
}
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Report an error to Sentry. Never throws — observability must not change
|
|
* control flow. A no-op before the gate opens, when the gate never opens (no
|
|
* DSN on the session), or when bootstrap failed.
|
|
*/
|
|
export function captureBrowserException(error: unknown, details?: BrowserErrorDetails): void {
|
|
let context: ReturnType<typeof buildBrowserErrorContext> | undefined;
|
|
try {
|
|
if (details) context = buildBrowserErrorContext(details);
|
|
} catch {
|
|
// Diagnostics must never replace the original exception or its recovery UI.
|
|
}
|
|
enqueueCapture(error, context);
|
|
}
|
|
|
|
/**
|
|
* Report a failed query, grouped by its HTTP status and the static name of
|
|
* its query key. Never throws, and is a no-op until the gate opens.
|
|
*/
|
|
export function captureQueryException(error: unknown, queryKey: readonly unknown[]): void {
|
|
let context: ReturnType<typeof buildQueryErrorContext> | undefined;
|
|
try {
|
|
context = buildQueryErrorContext(error, queryKey);
|
|
} catch {
|
|
// Diagnostics must never replace the original exception.
|
|
}
|
|
enqueueCapture(error, context);
|
|
}
|
|
|
|
function enqueueCapture(
|
|
error: unknown,
|
|
context: ReturnType<typeof buildBrowserErrorContext> | ReturnType<typeof buildQueryErrorContext> | undefined,
|
|
): void {
|
|
void enqueue(async () => {
|
|
try {
|
|
if (context) sentry?.captureException(error, context);
|
|
else sentry?.captureException(error);
|
|
} catch (err) {
|
|
// eslint-disable-next-line no-console
|
|
console.error("[paperclip] Sentry captureException failed", err);
|
|
}
|
|
});
|
|
}
|
|
|
|
const POSTHOG_REQUEST_TIMEOUT_MESSAGE = /^PostHog request timed out(?: after \d+ms)?$/;
|
|
|
|
export function isPostHogRequestTimeout(reason: unknown): boolean {
|
|
try {
|
|
return reason instanceof Error
|
|
&& reason.name === "AbortError"
|
|
&& POSTHOG_REQUEST_TIMEOUT_MESSAGE.test(reason.message);
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Build the `Sentry.init` options object. A pure function, split out from
|
|
* `initBrowserErrorMonitoring` so a test can call it with the real
|
|
* `@sentry/browser` module and assert the resolved integration list and the
|
|
* captured-event shape against the true SDK, not a stand-in.
|
|
*/
|
|
export function buildBrowserSentryInitOptions(
|
|
dsn: string,
|
|
environment?: string | null,
|
|
): BrowserSentryInitOptions {
|
|
return {
|
|
dsn,
|
|
environment: environment ?? undefined,
|
|
// Use the loaded bundle's build, even when the server has since deployed.
|
|
release:
|
|
typeof __PAPERCLIP_BUILD_COMMIT__ === "string"
|
|
? __PAPERCLIP_BUILD_COMMIT__
|
|
: undefined,
|
|
tracesSampleRate: 0,
|
|
sendDefaultPii: false,
|
|
ignoreErrors: ["__firefox__"],
|
|
beforeSend: (event, hint) => {
|
|
const isUnhandledRejection = event.exception?.values?.some((value) =>
|
|
value.mechanism?.type === "onunhandledrejection"
|
|
|| value.mechanism?.type === "auto.browser.global_handlers.onunhandledrejection",
|
|
) ?? false;
|
|
if (
|
|
isUnhandledRejection
|
|
&& (isIntentionalAbortReason(hint.originalException) || isPostHogRequestTimeout(hint.originalException))
|
|
) {
|
|
takeRejectionEventSnapshot(classifyRejectionReason(hint.originalException));
|
|
return null;
|
|
}
|
|
// Global handlers do not pass through our React boundaries. Give their
|
|
// reports the same bounded document state, without URLs or breadcrumbs.
|
|
// Preserve a boundary's earlier snapshot across the asynchronous queue.
|
|
try {
|
|
event.contexts = {
|
|
...event.contexts,
|
|
browser_state: event.contexts?.browser_state ?? readBrowserErrorState(),
|
|
page_lifecycle: event.contexts?.page_lifecycle ?? readPageLifecycle(),
|
|
};
|
|
event.tags = {
|
|
...event.tags,
|
|
browser_build_mode: import.meta.env.DEV ? "development" : "production",
|
|
};
|
|
// A plugin UI module runs from a random `blob:` URL. Name the plugin
|
|
// whose module holds the innermost such frame, never the URL.
|
|
const pluginModule = readPluginModuleOrigin(event.exception?.values);
|
|
if (pluginModule) event.tags.browser_plugin_module = pluginModule;
|
|
if (isUnhandledRejection) {
|
|
// The SDK supplies the rejected value directly. Classify without
|
|
// reading object properties, coercing strings, or copying its value.
|
|
const kind = classifyRejectionReason(hint.originalException);
|
|
event.tags.browser_rejection_kind = kind;
|
|
if (kind === "object") {
|
|
// A stackless network error carries no caller. Record who started
|
|
// the request, as an enum, and whether another script wraps fetch.
|
|
event.tags.browser_fetch_initiator = readFetchInitiator(hint.originalException);
|
|
const wrapper = readFetchWrapperState();
|
|
if (wrapper) event.tags.browser_fetch_wrapper = wrapper;
|
|
}
|
|
// Whether the browser or a script dispatched the event, and which
|
|
// promise implementation carried it. Without a stack these are the
|
|
// remaining attribution facts for an `undefined` rejection.
|
|
const rejection = takeRejectionEventSnapshot(kind);
|
|
if (rejection) {
|
|
event.tags.browser_rejection_event = rejection.trusted ? "trusted" : "synthetic";
|
|
event.contexts.rejection_event = rejection;
|
|
}
|
|
}
|
|
} catch {
|
|
// Diagnostics must not replace or discard the original error.
|
|
}
|
|
return event;
|
|
},
|
|
integrations: (defaults) =>
|
|
defaults.filter(
|
|
(integration) => integration.name !== "HttpContext" && integration.name !== "Breadcrumbs",
|
|
),
|
|
};
|
|
}
|