Files
PaperClipAI/ui/src/lib/query-client.test.ts
T
Devin FoleyandClaude Opus 5.5 f58bbefc4e fix(ui): group failed-query Sentry reports by status and query name (#21475)
## 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>
2026-11-13 12:24:46 -08:00

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);
});
});