mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The browser app can report errors to Sentry. A final query error goes to Sentry when it is not an outage, a denial, or a missing item. > - Every failed API request throws an `ApiError` from the same frames in `api/client.ts`. > - Sentry groups errors by stack. Thus all unrelated server failures go into one issue, titled "ApiError: Internal server error". > - The report has no route, no query name, and no status. Breadcrumbs and URLs are removed for privacy. A person cannot find which endpoint failed. > - This pull request tags each failed-query report with its HTTP status and the static name of its query key. It also sets the Sentry fingerprint from these two values. > - The benefit: each failing endpoint gets its own Sentry issue, and a person can connect it to the server error. ## Linked Issues or Issue Description **What happened?** One browser Sentry issue collected unrelated server 500 errors from different pages and environments. The events had no route or query name. A person could not connect an event to a server error. **Steps to reproduce** 1. Turn on browser error monitoring with a Sentry DSN. 2. Make two different queries fail with a 500 response, for example the issues list and the agents list. 3. Look at Sentry. Both events are in one issue with the title "ApiError: Internal server error". Neither event shows which query failed. **Expected behavior** Each failing query has its own Sentry issue. The event shows the HTTP status and the static query name. It shows no IDs, refs, or filters. **Environment** The hosted browser app, staging and production builds. I searched open pull requests for duplicates. I found no pull request that changes browser query-error grouping. ## What Changed - `ui/src/lib/browser-error-context.ts`: add `queryKindFor`. It keeps only the first query-key part, and only when it is a lowercase word list such as `issues` or `agent-commentary`. Other values become `other`, so an ID, a ref, an email, or a typed value is never sent. - `ui/src/lib/browser-error-context.ts`: add `buildQueryErrorContext`. For an error with an HTTP status, it sets the `query_kind` and `api_status` tags and the fingerprint `["api-error", status, queryKind]`. For an error without a status, it sets only the `query_kind` tag and keeps default stack grouping. - `ui/src/lib/sentry.ts`: add `captureQueryException`. It uses the same serialized queue as `captureBrowserException`. Both functions now share one private capture step. - `ui/src/lib/query-client.ts`: `reportError` now also receives the query key. - `ui/src/main.tsx`: the query client reports through `captureQueryException`. - Tests for key sanitizing, the fingerprint, the reporter argument, and the gate call. ## Verification - Red before the fix: the 6 new assertions fail on the old source (`queryKindFor`, `buildQueryErrorContext` and `captureQueryException` do not exist, and `reportError` gets no key). - Green after the fix: `cd ui && npx vitest run src/lib/sentry.test.ts src/lib/browser-error-context.test.ts src/lib/query-client.test.ts` passes 3 files and 78 tests. - The privacy test makes sure that `company-uuid` and `PAP-1` from later key parts do not go into the Sentry call. It also makes sure that UUID, ref, email, and long heads become `other`. - `ui` typecheck: no errors in the changed files. The local install was filtered to the UI package, so unrelated packages (`plugin-sdk` build output, runner dependencies) could not resolve. Required CI supplies the full typecheck. - I did not run browser e2e suites. This change does not touch them. ## Risks - Low risk. Only the grouping and tags of browser query-error reports change. The app does not change what it shows to users. - Sentry opens new issues for future query errors, one for each status and query name. The old catch-all issue gets no new events. - A query key with a dynamic first part becomes `other`. Those errors still group together, but they keep the status tag. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with tool use, repository inspection, and shell code execution. ## 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 - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
182 lines
7.6 KiB
TypeScript
182 lines
7.6 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
import {
|
|
__resetPageDiagnostics,
|
|
buildBrowserErrorContext,
|
|
buildQueryErrorContext,
|
|
queryKindFor,
|
|
readPageLifecycle,
|
|
sanitizeComponentStack,
|
|
startPageDiagnostics,
|
|
takeRejectionEventSnapshot,
|
|
} from "./browser-error-context";
|
|
|
|
afterEach(() => {
|
|
__resetPageDiagnostics();
|
|
vi.restoreAllMocks();
|
|
vi.unstubAllGlobals();
|
|
document.documentElement.className = "";
|
|
});
|
|
|
|
describe("query error context", () => {
|
|
it("keeps only a static query key name", () => {
|
|
expect(queryKindFor(["issues", "company-uuid", "detail", "PAP-1"])).toBe("issues");
|
|
expect(queryKindFor(["agent-commentary", "company-uuid"])).toBe("agent-commentary");
|
|
expect(queryKindFor(["266ff1d0-6be9-47cb-b2ed-300fce5fbcd3"])).toBe("other");
|
|
expect(queryKindFor(["abcdefab-abcd-4bcd-abcd-abcdefabcdef"])).toBe("other");
|
|
expect(queryKindFor(["PAP-1"])).toBe("other");
|
|
expect(queryKindFor(["person@example.com"])).toBe("other");
|
|
expect(queryKindFor(["a".repeat(65)])).toBe("other");
|
|
expect(queryKindFor([{ companyId: "company-uuid" }])).toBe("other");
|
|
expect(queryKindFor([])).toBe("other");
|
|
});
|
|
|
|
it("fingerprints an HTTP failure by status and query name", () => {
|
|
const error = Object.assign(new Error("Internal server error"), { status: 500 });
|
|
expect(buildQueryErrorContext(error, ["issues", "company-uuid"])).toEqual({
|
|
tags: { query_kind: "issues", api_status: "500" },
|
|
fingerprint: ["api-error", "500", "issues"],
|
|
});
|
|
});
|
|
|
|
it("keeps default stack grouping for an error without an HTTP status", () => {
|
|
expect(buildQueryErrorContext(new TypeError("x is undefined"), ["issues"])).toEqual({
|
|
tags: { query_kind: "issues" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("browser error context", () => {
|
|
it("keeps React component names without locations or unrecognized content", () => {
|
|
const stack = `
|
|
at TaskDetail (https://tenant.example/assets/app.js?token=private-value:42:7)
|
|
at div (<anonymous>)
|
|
in AppShell (created by Router)
|
|
TaskPanel@https://tenant.example/tasks/private-task:12:3
|
|
at ErrorBoundary (/workspace/private/src/Boundary.tsx:15:9)
|
|
at https://tenant.example/private-page:17:3
|
|
unrecognized private content`;
|
|
expect(sanitizeComponentStack(stack)).toBe(
|
|
"\n at TaskDetail\n at div\n at AppShell\n at TaskPanel\n at ErrorBoundary",
|
|
);
|
|
});
|
|
|
|
it("bounds malformed and oversized component stacks", () => {
|
|
expect(sanitizeComponentStack(` at ${"a".repeat(101)} (private)`)).toBeUndefined();
|
|
expect(sanitizeComponentStack("x".repeat(16_384) + "\n at SecretSuffix")).toBeUndefined();
|
|
expect(sanitizeComponentStack("\n at TaskDetail (private)".repeat(100))?.match(/at TaskDetail/g)).toHaveLength(40);
|
|
});
|
|
|
|
it.each([undefined, null, "", "private unrecognized data"])("omits absent or unrecognized stacks: %s", (stack) => {
|
|
expect(sanitizeComponentStack(stack)).toBeUndefined();
|
|
});
|
|
|
|
it.each(["translated-ltr", "translated-rtl"])("records only a translation-marker boolean for %s", (marker) => {
|
|
document.documentElement.className = `${marker} private-customer-class`;
|
|
const result = buildBrowserErrorContext({ boundary: "route", componentStack: "\n at TaskDetail" });
|
|
expect(result).toMatchObject({
|
|
tags: { react_error_boundary: "route" },
|
|
contexts: { react: { componentStack: "\n at TaskDetail" }, browser_state: { translation_marker: true } },
|
|
});
|
|
expect(JSON.stringify(result)).not.toContain("private-customer-class");
|
|
});
|
|
|
|
it("captures a snapshot rather than reading changed DOM state later", () => {
|
|
vi.spyOn(document, "visibilityState", "get").mockReturnValue("hidden");
|
|
vi.spyOn(document, "readyState", "get").mockReturnValue("interactive");
|
|
const result = buildBrowserErrorContext({ boundary: "app" });
|
|
document.documentElement.classList.add("translated-ltr");
|
|
expect(result.contexts.browser_state).toEqual({
|
|
ready_state: "interactive", visibility_state: "hidden", translation_marker: false,
|
|
});
|
|
});
|
|
|
|
it("keeps the component trace when browser-state reads throw", () => {
|
|
vi.spyOn(document, "readyState", "get").mockImplementation(() => { throw new Error("unavailable"); });
|
|
vi.spyOn(document.documentElement, "classList", "get").mockImplementation(() => { throw new Error("unavailable"); });
|
|
expect(buildBrowserErrorContext({ boundary: "app", componentStack: "\n at TaskDetail" })).toEqual({
|
|
tags: { react_error_boundary: "app" },
|
|
contexts: {
|
|
react: { componentStack: "\n at TaskDetail" },
|
|
browser_state: { visibility_state: document.visibilityState },
|
|
page_lifecycle: expect.objectContaining({ pagehide_seen: false }),
|
|
},
|
|
});
|
|
});
|
|
|
|
it("does not require a browser document", () => {
|
|
vi.stubGlobal("document", undefined);
|
|
expect(buildBrowserErrorContext({ boundary: "app" }).contexts.browser_state).toEqual({});
|
|
});
|
|
});
|
|
|
|
/** A dispatched (untrusted) rejection event; jsdom has no PromiseRejectionEvent. */
|
|
function dispatchRejection(reason: unknown, promise?: unknown) {
|
|
const event = new Event("unhandledrejection");
|
|
Object.defineProperty(event, "reason", { value: reason });
|
|
Object.defineProperty(event, "promise", { value: promise });
|
|
window.dispatchEvent(event);
|
|
}
|
|
|
|
describe("page diagnostics", () => {
|
|
startPageDiagnostics();
|
|
|
|
function setNow(ms: number) {
|
|
vi.spyOn(performance, "now").mockReturnValue(ms);
|
|
}
|
|
|
|
it("records only the latest lifecycle transition with coarse timing", () => {
|
|
setNow(5_000);
|
|
expect(readPageLifecycle()).toEqual({ since_load: "1-10s", pagehide_seen: false });
|
|
|
|
vi.spyOn(document, "visibilityState", "get").mockReturnValue("hidden");
|
|
document.dispatchEvent(new Event("visibilitychange"));
|
|
setNow(65_000);
|
|
expect(readPageLifecycle()).toEqual({
|
|
since_load: "1-10m", pagehide_seen: false, last_transition: "hidden", since_transition: "1-10m",
|
|
});
|
|
|
|
document.dispatchEvent(new Event("freeze"));
|
|
document.dispatchEvent(new Event("resume"));
|
|
setNow(65_500);
|
|
expect(readPageLifecycle()).toMatchObject({ last_transition: "resume", since_transition: "<1s" });
|
|
});
|
|
|
|
it("keeps a pagehide marker until the page is shown again", () => {
|
|
setNow(1_000_000);
|
|
window.dispatchEvent(new Event("pagehide"));
|
|
expect(readPageLifecycle()).toEqual({
|
|
since_load: ">10m", pagehide_seen: true, last_transition: "pagehide", since_transition: "<1s",
|
|
});
|
|
window.dispatchEvent(new Event("pageshow"));
|
|
expect(readPageLifecycle()).toMatchObject({ pagehide_seen: false, last_transition: "pageshow" });
|
|
});
|
|
|
|
it.each([
|
|
["native", Promise.resolve()],
|
|
["subclass", new (class Custom<T> extends Promise<T> {})(() => {})],
|
|
["other", { then() {} }],
|
|
["missing", undefined],
|
|
])("classifies a %s rejection promise without reading the reason", (kind, promise) => {
|
|
setNow(100);
|
|
const reason = { get secret() { throw new Error("must not be read"); } };
|
|
dispatchRejection(reason, promise);
|
|
expect(takeRejectionEventSnapshot("object")).toEqual({ trusted: false, promise: kind });
|
|
});
|
|
|
|
it("pairs a snapshot once, with the same rejection kind, inside the pairing window", () => {
|
|
setNow(100);
|
|
dispatchRejection(undefined, Promise.resolve());
|
|
expect(takeRejectionEventSnapshot("undefined")).toEqual({ trusted: false, promise: "native" });
|
|
expect(takeRejectionEventSnapshot("undefined")).toBeUndefined();
|
|
|
|
dispatchRejection(undefined, Promise.resolve());
|
|
expect(takeRejectionEventSnapshot("string")).toBeUndefined();
|
|
|
|
dispatchRejection(undefined, Promise.resolve());
|
|
setNow(5_101);
|
|
expect(takeRejectionEventSnapshot("undefined")).toBeUndefined();
|
|
});
|
|
});
|