mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +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>
332 lines
14 KiB
TypeScript
332 lines
14 KiB
TypeScript
import { onlineManager, QueryObserver, MutationObserver, type QueryClient } from "@tanstack/react-query";
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import { ApiError } from "@/api/client";
|
|
import { ApiUnavailableError } from "@/api/response";
|
|
import { createConnectivityStore, type ConnectivityStore, type ProbeResult } from "./connectivity";
|
|
import {
|
|
bindConnectivity,
|
|
createAppQueryClient,
|
|
reconnectDelayFor,
|
|
retryDelayFor,
|
|
shouldReportQueryError,
|
|
QueryNotReadyError,
|
|
shouldRetryRequest,
|
|
TRANSIENT_RETRY_DELAYS_MS,
|
|
type MutationErrorToast,
|
|
} from "./query-client";
|
|
|
|
const gatewayDown = () => new ApiError("Paperclip is restarting", 503, { error: "tenant_app_unavailable" });
|
|
|
|
describe("retry policy", () => {
|
|
it("retries transient errors for about 30 seconds", () => {
|
|
const error = new ApiUnavailableError(502);
|
|
const retries = TRANSIENT_RETRY_DELAYS_MS.length;
|
|
expect(shouldRetryRequest(retries - 1, error)).toBe(true);
|
|
expect(shouldRetryRequest(retries, error)).toBe(false);
|
|
const total = TRANSIENT_RETRY_DELAYS_MS.reduce((sum, delay) => sum + delay, 0);
|
|
expect(total).toBeGreaterThanOrEqual(25_000);
|
|
expect(total).toBeLessThanOrEqual(35_000);
|
|
});
|
|
|
|
it.each([400, 401, 403, 404, 409, 422])("never retries a %s", (status) => {
|
|
expect(shouldRetryRequest(0, new ApiError("No", status, null))).toBe(false);
|
|
});
|
|
|
|
it("retries the gateway code even when it arrives with a 4xx", () => {
|
|
expect(shouldRetryRequest(0, new ApiError("x", 404, { error: "tenant_app_unavailable" }))).toBe(true);
|
|
});
|
|
|
|
it("retries unexpected failures briefly and aborts never", () => {
|
|
expect(shouldRetryRequest(0, new ApiError("boom", 500, null))).toBe(true);
|
|
expect(shouldRetryRequest(2, new ApiError("boom", 500, null))).toBe(false);
|
|
expect(shouldRetryRequest(0, new DOMException("Aborted", "AbortError"))).toBe(false);
|
|
});
|
|
|
|
it("backs off and honors Retry-After", () => {
|
|
const error = new ApiUnavailableError(503);
|
|
expect(retryDelayFor(0, error)).toBe(1_000);
|
|
expect(retryDelayFor(4, error)).toBe(15_000);
|
|
expect(retryDelayFor(9, error)).toBe(15_000);
|
|
const throttled = new ApiError("Slow down", 429, null, { retryAfterMs: 6_000 });
|
|
expect(retryDelayFor(0, throttled)).toBe(6_000);
|
|
// A rate-limit window longer than the normal backoff is waited out in full.
|
|
const minuteWindow = new ApiError("Slow down", 429, null, { retryAfterMs: 55_000 });
|
|
expect(retryDelayFor(0, minuteWindow)).toBe(55_000);
|
|
expect(retryDelayFor(0, new ApiUnavailableError(503, 20_000))).toBe(20_000);
|
|
expect(reconnectDelayFor(0, throttled)).toBe(6_000);
|
|
expect(reconnectDelayFor(3, new ApiUnavailableError(503))).toBe(10_000);
|
|
});
|
|
|
|
it("reports only unexpected query errors to Sentry", () => {
|
|
expect(shouldReportQueryError(new ApiError("boom", 500, null))).toBe(true);
|
|
expect(shouldReportQueryError(new Error("parse failure"))).toBe(true);
|
|
expect(shouldReportQueryError(new QueryNotReadyError("Not ready"))).toBe(false);
|
|
expect(shouldReportQueryError(gatewayDown())).toBe(false);
|
|
expect(shouldReportQueryError(new TypeError("Failed to fetch"))).toBe(false);
|
|
expect(shouldReportQueryError(new ApiError("Not found", 404, null))).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("createAppQueryClient", () => {
|
|
let store: ConnectivityStore;
|
|
let probe: ReturnType<typeof vi.fn<() => Promise<ProbeResult>>>;
|
|
let client: QueryClient;
|
|
let unbind: () => void;
|
|
let notifyMutationError: ReturnType<typeof vi.fn<(toast: MutationErrorToast) => void>>;
|
|
let reportError: ReturnType<typeof vi.fn<(error: unknown, queryKey: readonly unknown[]) => void>>;
|
|
|
|
beforeEach(() => {
|
|
vi.useFakeTimers();
|
|
probe = vi.fn<() => Promise<ProbeResult>>().mockResolvedValue({ reachable: false, retryAfterMs: null });
|
|
store = createConnectivityStore({ probe, browserOnline: true });
|
|
notifyMutationError = vi.fn<(toast: MutationErrorToast) => void>();
|
|
reportError = vi.fn<(error: unknown, queryKey: readonly unknown[]) => void>();
|
|
client = createAppQueryClient({ connectivity: store, notifyMutationError, reportError });
|
|
client.mount();
|
|
unbind = bindConnectivity(client, store);
|
|
});
|
|
|
|
afterEach(() => {
|
|
unbind();
|
|
store.dispose();
|
|
client.unmount();
|
|
client.clear();
|
|
onlineManager.setOnline(true);
|
|
vi.useRealTimers();
|
|
});
|
|
|
|
it("pauses a failing query during an outage and refreshes it on recovery", async () => {
|
|
let down = true;
|
|
const queryFn = vi.fn(async () => {
|
|
if (down) throw gatewayDown();
|
|
return "fresh";
|
|
});
|
|
const observer = new QueryObserver(client, { queryKey: ["issue", "1"], queryFn });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
expect(onlineManager.isOnline()).toBe(false);
|
|
|
|
await vi.advanceTimersByTimeAsync(30_000);
|
|
// Paused, not failed, and not hammering the server.
|
|
expect(observer.getCurrentResult()).toMatchObject({ status: "pending", fetchStatus: "paused" });
|
|
expect(queryFn).toHaveBeenCalledTimes(1);
|
|
|
|
down = false;
|
|
probe.mockResolvedValue({ reachable: true });
|
|
await vi.advanceTimersByTimeAsync(15_000);
|
|
expect(store.getSnapshot().status).toBe("online");
|
|
expect(observer.getCurrentResult()).toMatchObject({ status: "success", data: "fresh" });
|
|
unsubscribe();
|
|
});
|
|
|
|
it("keeps cached data when a background refetch hits an outage", async () => {
|
|
let down = false;
|
|
const observer = new QueryObserver(client, {
|
|
queryKey: ["issue", "2"],
|
|
queryFn: async () => {
|
|
if (down) throw gatewayDown();
|
|
return "loaded";
|
|
},
|
|
});
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
down = true;
|
|
void observer.refetch();
|
|
await vi.advanceTimersByTimeAsync(5_000);
|
|
expect(observer.getCurrentResult()).toMatchObject({ data: "loaded", error: null });
|
|
unsubscribe();
|
|
});
|
|
|
|
it("refreshes active queries once on recovery", async () => {
|
|
const queryFn = vi.fn(async () => "ok");
|
|
const observer = new QueryObserver(client, { queryKey: ["list"], queryFn, staleTime: Infinity });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(queryFn).toHaveBeenCalledTimes(1);
|
|
store.reportError(gatewayDown());
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
probe.mockResolvedValue({ reachable: true });
|
|
await vi.advanceTimersByTimeAsync(1_000);
|
|
expect(queryFn).toHaveBeenCalledTimes(2);
|
|
unsubscribe();
|
|
});
|
|
|
|
it("does not treat setQueryData as proof the server is back", async () => {
|
|
store.reportError(gatewayDown());
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
client.setQueryData(["optimistic"], "local");
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
});
|
|
|
|
it("does not infer server recovery from an unrelated in-flight query", async () => {
|
|
let finish!: (value: null) => void;
|
|
const pending = new Promise<null>(resolve => { finish = resolve; });
|
|
const observer = new QueryObserver(client, { queryKey: ["npm-registry"], queryFn: () => pending });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
store.reportError(gatewayDown());
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
finish(null);
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
expect(onlineManager.isOnline()).toBe(false);
|
|
probe.mockResolvedValue({ reachable: true });
|
|
await vi.advanceTimersByTimeAsync(1_000);
|
|
expect(store.getSnapshot().status).toBe("online");
|
|
unsubscribe();
|
|
});
|
|
|
|
it("does not infer server recovery from an unrelated mutation", async () => {
|
|
store.reportError(gatewayDown());
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
const observer = new MutationObserver(client, { mutationFn: async () => "external success" });
|
|
await observer.mutate();
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
expect(onlineManager.isOnline()).toBe(false);
|
|
});
|
|
|
|
it("fails an ordinary mutation fast during an outage", async () => {
|
|
const mutationFn = vi.fn(async () => {
|
|
throw gatewayDown();
|
|
});
|
|
const observer = new MutationObserver(client, { mutationFn });
|
|
await expect(observer.mutate()).rejects.toBeInstanceOf(ApiError);
|
|
expect(mutationFn).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it("pauses an idempotent mutation across an outage and resends it on reconnect", async () => {
|
|
let down = true;
|
|
const mutationFn = vi.fn(async (value: string) => {
|
|
if (down) throw gatewayDown();
|
|
return value;
|
|
});
|
|
const observer = new MutationObserver(client, { mutationFn, meta: { replay: "idempotent" } });
|
|
const result = observer.mutate("title");
|
|
await vi.advanceTimersByTimeAsync(60_000);
|
|
expect(observer.getCurrentResult()).toMatchObject({ status: "pending", isPaused: true });
|
|
expect(mutationFn).toHaveBeenCalledTimes(1);
|
|
expect(store.getSnapshot().pendingWrites).toBe(1);
|
|
|
|
down = false;
|
|
probe.mockResolvedValue({ reachable: true });
|
|
await vi.advanceTimersByTimeAsync(15_000);
|
|
await expect(result).resolves.toBe("title");
|
|
expect(mutationFn).toHaveBeenCalledTimes(2);
|
|
expect(store.getSnapshot().pendingWrites).toBe(0);
|
|
});
|
|
|
|
it("toasts readable copy for a failed opted-in mutation without its own handler", async () => {
|
|
const observer = new MutationObserver(client, {
|
|
mutationFn: async () => {
|
|
throw new ApiError("Title is required", 422, { error: "Title is required" });
|
|
},
|
|
meta: { errorToast: true },
|
|
});
|
|
await observer.mutate().catch(() => undefined);
|
|
expect(notifyMutationError).toHaveBeenCalledWith({ title: "Check your input", body: "Title is required" });
|
|
});
|
|
|
|
it("toasts a transient failure the banner does not cover", async () => {
|
|
const observer = new MutationObserver(client, {
|
|
mutationFn: async () => {
|
|
throw new ApiError("Slow down", 429, null);
|
|
},
|
|
meta: { errorToast: true },
|
|
});
|
|
await observer.mutate().catch(() => undefined);
|
|
expect(notifyMutationError).toHaveBeenCalledWith({
|
|
title: "Connection interrupted",
|
|
body: "Paperclip is temporarily unavailable. Please try again in a moment.",
|
|
});
|
|
});
|
|
|
|
it("does not toast covered transient failures, handled mutations, or mutations that did not opt in", async () => {
|
|
const fail = (error: unknown) => async () => {
|
|
throw error;
|
|
};
|
|
store.reportError(gatewayDown());
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(store.getSnapshot().status).toBe("reconnecting");
|
|
await new MutationObserver(client, {
|
|
mutationFn: fail(gatewayDown()),
|
|
meta: { errorToast: true },
|
|
}).mutate().catch(() => undefined);
|
|
await new MutationObserver(client, {
|
|
mutationFn: fail(new ApiError("No", 403, null)),
|
|
onError: () => undefined,
|
|
meta: { errorToast: true },
|
|
}).mutate().catch(() => undefined);
|
|
// Surfaces that render `mutation.error` inline must not get a second copy.
|
|
await new MutationObserver(client, {
|
|
mutationFn: fail(new ApiError("No", 403, null)),
|
|
}).mutate().catch(() => undefined);
|
|
expect(notifyMutationError).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("reports an unexpected query error to Sentry once per query", async () => {
|
|
const queryFn = vi.fn(async () => {
|
|
throw new ApiError("boom", 500, { error: "boom" });
|
|
});
|
|
const observer = new QueryObserver(client, { queryKey: ["broken"], queryFn, retry: false });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
await observer.refetch();
|
|
expect(queryFn).toHaveBeenCalledTimes(2);
|
|
expect(reportError).toHaveBeenCalledTimes(1);
|
|
expect(reportError).toHaveBeenCalledWith(expect.any(ApiError), ["broken"]);
|
|
unsubscribe();
|
|
});
|
|
|
|
it("does not report a query that was cancelled without reverting", async () => {
|
|
const queryFn = vi.fn(() => new Promise<string>(() => {}));
|
|
const observer = new QueryObserver(client, { queryKey: ["issues", "detail", "PAP-1"], queryFn });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
await client.cancelQueries({ queryKey: ["issues", "detail"] }, { revert: false });
|
|
expect(observer.getCurrentResult().error?.message).toBe("CancelledError");
|
|
expect(reportError).not.toHaveBeenCalled();
|
|
unsubscribe();
|
|
});
|
|
|
|
it("leaves a cache-only alias stale instead of refetching it without a queryFn", async () => {
|
|
client.setQueryData(["issues", "detail", "issue-uuid"], { id: "issue-uuid", title: "Seeded" });
|
|
const queryFn = vi.fn(async () => "fetched");
|
|
client.setQueryData(["issues", "detail", "PAP-1"], "seeded");
|
|
await client.prefetchQuery({ queryKey: ["issues", "detail", "PAP-1"], queryFn, staleTime: 0 });
|
|
queryFn.mockClear();
|
|
|
|
void client.invalidateQueries({ queryKey: ["issues", "detail"], refetchType: "inactive" });
|
|
void client.refetchQueries({ queryKey: ["issues", "detail"], type: "all" });
|
|
await vi.advanceTimersByTimeAsync(60_000);
|
|
|
|
const alias = client.getQueryCache().find({ queryKey: ["issues", "detail", "issue-uuid"], exact: true });
|
|
expect(alias?.state.status).toBe("success");
|
|
expect(alias?.state.isInvalidated).toBe(true);
|
|
expect(alias?.state.data).toEqual({ id: "issue-uuid", title: "Seeded" });
|
|
expect(queryFn).toHaveBeenCalledTimes(2);
|
|
expect(reportError).not.toHaveBeenCalled();
|
|
|
|
const aliasQueryFn = vi.fn(async () => ({ id: "issue-uuid", title: "Fresh" }));
|
|
const observer = new QueryObserver(client, { queryKey: ["issues", "detail", "issue-uuid"], queryFn: aliasQueryFn });
|
|
const unsubscribe = observer.subscribe(() => {});
|
|
await vi.advanceTimersByTimeAsync(0);
|
|
expect(aliasQueryFn).toHaveBeenCalledTimes(1);
|
|
expect(observer.getCurrentResult().data).toEqual({ id: "issue-uuid", title: "Fresh" });
|
|
unsubscribe();
|
|
});
|
|
|
|
it("keeps the caller's refetch predicate", async () => {
|
|
const keep = vi.fn(async () => "keep");
|
|
const skip = vi.fn(async () => "skip");
|
|
await client.prefetchQuery({ queryKey: ["keep"], queryFn: keep });
|
|
await client.prefetchQuery({ queryKey: ["skip"], queryFn: skip });
|
|
|
|
await client.refetchQueries({ predicate: (query) => query.queryKey[0] === "keep" });
|
|
|
|
expect(keep).toHaveBeenCalledTimes(2);
|
|
expect(skip).toHaveBeenCalledTimes(1);
|
|
});
|
|
});
|