ref(cache): centralize mutation invalidation at the HTTP layer (#792) (#801)

Closes #792. Follow-up to #788.

## Summary

The per-site `invalidate*` helpers in `api/issues.ts`,
`api/projects.ts`, and `api/dashboards.ts` are replaced by a single
post-mutation hook in `authenticatedFetch` that auto-invalidates the
cache for every successful non-GET. Prefix computation lives in a new
`src/lib/cache-keys.ts` module.

## Layer 1: HTTP-layer hook (new)

`invalidateAfterMutation` fires after `fetchWithRetry` returns a 2xx
non-GET response:

- **Hierarchy walk** — for
`/api/0/organizations/{org}/releases/1.0.0/deploys/`, sweeps the URL
path plus every ancestor down to the owner level (`releases/1.0.0/`,
`releases/`, `organizations/{org}/`). The bare top-level
`organizations/` root is deliberately **not** swept — sweeping it on
every mutation would evict unrelated cross-org caches.
- **Cross-endpoint rules** — tiny table for the 2 cases where a mutation
affects a different URL tree:
- `POST /api/0/teams/{org}/{team}/projects/` invalidates
`/api/0/organizations/{org}/projects/`
- `DELETE /api/0/projects/{org}/{project}/` invalidates
`/api/0/organizations/{org}/projects/`
- **Write-only endpoints skip invalidation** — sourcemap chunk uploads
and artifact-bundle assembly don't modify any cacheable state, so
they're short-circuited at the top of `computeInvalidationPrefixes`.
Without this, every chunk of a sourcemap upload (hundreds of POSTs at
N-way concurrency) would sweep the org's cache.

The hook is **awaited** before returning the response, so a subsequent
read in the same command sees fresh data. Identity-gated via the
existing sweep primitive (no cross-account eviction).

## Layer 2: Command-level override (deferred)

Issue #792 proposed an optional `invalidates` callback on `buildCommand`
for cross-endpoint fan-outs the HTTP layer can't know about. Turned out
the 2 hardcoded rules above cover every current case — deferred the
callback API to when a real use case emerges.

## Coverage

Every mutation in `src/lib/api/` is now covered for free, including ones
that had no invalidation before:

- `release create/update/delete`, `release deploy`, `set-commits*`
- `team create`, `member add`
- `dashboard create`
- `trial start`

`sentry api -X POST/PUT/DELETE ...` also gets auto-invalidation — users
of the raw escape hatch no longer need `--fresh` on follow-up reads.

## Removed

- `api/issues.ts`: `invalidateIssueCaches`,
`invalidateIssueDetailCaches`, `invalidateOrgIssueList` + their call
sites in `updateIssueStatus` / `mergeIssues`.
- `api/projects.ts`: `invalidateProjectCaches`,
`invalidateOrgProjectCache` + call sites in `createProject` /
`deleteProject`.
- `api/dashboards.ts`: inline `invalidateCachedResponse` in
`updateDashboard`.

## Tests

- `test/lib/cache-keys.test.ts` — 15 tests: hierarchy walk (with the
owner-level cap), cross-endpoint rules, write-only skip, query-string
stripping, unparseable URLs, self-hosted bases, dedup.
- `test/lib/sentry-client.invalidation.test.ts` — 5 integration tests:
successful mutation clears self + list, failed mutation leaves cache
alone, GET doesn't invalidate, cross-endpoint rule fires, identity
isolation holds.

Full unit suite: 5706 passing. `bun run typecheck`, `bun run lint`
clean.

## Follow-ups

One minor optimization deferred: when the hook computes multiple
prefixes, `Promise.all` kicks off independent
`invalidateCachedResponsesMatching` calls, each doing its own `readdir`
+ per-file parse. For typical cache sizes (few hundred entries) this is
negligible, but the natural shape is "read the dir once, match every
entry against ALL prefixes, unlink if any match." A future
`invalidateCachedResponsesMatchingAny(prefixes: string[])` API would
eliminate the redundant I/O. Not done here to keep the PR scoped.

Author: BYK

src/lib/api/dashboards.ts

@@ -27,7 +27,6 @@ import {
 } from "../../types/dashboard.js";
 import { stringifyUnknown } from "../errors.js";
 import { resolveOrgRegion } from "../region.js";
-import { invalidateCachedResponse } from "../response-cache.js";
 
 import {
   apiRequestToRegion,
@@ -125,14 +124,6 @@ export async function updateDashboard(
     method: "PUT",
     body,
   });
-
-  // Invalidate cached GET for this dashboard so subsequent view commands
-  // return fresh data instead of the pre-mutation cached response.
-  const normalizedBase = regionUrl.endsWith("/")
-    ? regionUrl.slice(0, -1)
-    : regionUrl;
-  await invalidateCachedResponse(`${normalizedBase}/api/0${path}`);
-
   return data;
 }
 

src/lib/api/infrastructure.ts

@@ -179,27 +179,6 @@ export async function getOrgSdkConfig(orgSlug: string) {
   return getSdkConfig(regionUrl);
 }
 
-/**
- * Build a full Sentry API URL from a region base and path segments.
- *
- * Each segment is passed through `encodeURIComponent`, so callers can
- * pass user-supplied slugs directly without worrying about slashes,
- * spaces, or other reserved characters. The `/api/0/` prefix and the
- * required trailing slash are added automatically.
- *
- * @example
- *   buildApiUrl(regionUrl, "organizations", orgSlug, "projects")
- *   // → `${regionUrl.replace(/\/$/,"")}/api/0/organizations/<org>/projects/`
- */
-export function buildApiUrl(regionUrl: string, ...segments: string[]): string {
-  const base = regionUrl.endsWith("/") ? regionUrl.slice(0, -1) : regionUrl;
-  if (segments.length === 0) {
-    return `${base}/api/0/`;
-  }
-  const path = segments.map(encodeURIComponent).join("/");
-  return `${base}/api/0/${path}/`;
-}
-
 /**
  * Maximum number of pages to follow when auto-paginating.
  *

src/lib/api/issues.ts

@@ -19,13 +19,14 @@ import {
   API_MAX_PER_PAGE,
   apiRequest,
   apiRequestToRegion,
-  buildApiUrl,
   getOrgSdkConfig,
   MAX_PAGINATION_PAGES,
   type PaginatedResponse,
   unwrapPaginatedResult,
 } from "./infrastructure.js";
 
+const TRAILING_SLASH_RE = /\/$/;
+
 /**
  * Sort options for issue listing, derived from the @sentry/api SDK types.
  * Uses the SDK type directly for compile-time safety against parameter drift.
@@ -566,22 +567,14 @@ export async function updateIssueStatus(
       `/organizations/${encodeURIComponent(options.orgSlug)}/issues/${encodeURIComponent(issueId)}/`,
       { method: "PUT", body }
     );
-    await invalidateIssueCaches(regionUrl, options.orgSlug, issueId);
     return data;
   }
 
-  // Legacy global endpoint — works without org but not region-aware,
-  // so we can only flush the legacy issue-detail URL. Region-scoped
-  // lists age out via their TTL. Prefix-sweep (not exact-match)
-  // because `getIssue` caches under `.../issues/{id}/?collapse=...`.
-  const legacyData = await apiRequest<SentryIssue>(
-    `/issues/${encodeURIComponent(issueId)}/`,
-    { method: "PUT", body }
-  );
-  await invalidateCachedResponsesMatching(
-    buildApiUrl(getApiBaseUrl(), "issues", issueId)
-  );
-  return legacyData;
+  // Legacy global endpoint — works without org but not region-aware.
+  return apiRequest<SentryIssue>(`/issues/${encodeURIComponent(issueId)}/`, {
+    method: "PUT",
+    body,
+  });
 }
 
 /** Result of a successful issue-merge operation. */
@@ -625,15 +618,21 @@ export async function mergeIssues(
       method: "PUT",
       body: { merge: 1 },
     });
-    // Flush detail caches for every affected ID (detail-only avoids
-    // N+1 list scans) then sweep the org-wide list once.
+    // HTTP-layer invalidation covers the region-scoped caches via the
+    // prefix sweep on `/organizations/{org}/issues/`, but it can't see
+    // the affected IDs (they're in query params, stripped from the
+    // URL the hook sees). Manually clear each affected issue's legacy
+    // cross-origin cache so subsequent `getIssue(id)` doesn't serve
+    // stale data.
+    const apiBase = getApiBaseUrl().replace(TRAILING_SLASH_RE, "");
     const affectedIds = data.merge.children.toSpliced(0, 0, data.merge.parent);
     await Promise.all(
       affectedIds.map((id) =>
-        invalidateIssueDetailCaches(regionUrl, orgSlug, id)
+        invalidateCachedResponsesMatching(
+          `${apiBase}/api/0/issues/${encodeURIComponent(id)}/`
+        )
       )
     );
-    await invalidateOrgIssueList(regionUrl, orgSlug);
     return data.merge;
   } catch (error) {
     // The bulk-mutate endpoint returns 204 when no matching issues are
@@ -693,77 +692,3 @@ export async function getSharedIssue(
 
   return (await response.json()) as { groupID: string };
 }
-
-/**
- * Flush both the org-scoped and legacy detail endpoints for one issue,
- * including all `collapse` query-param variants (`getIssueInOrg` caches
- * responses under URLs like `.../issues/{id}/?collapse=stats&...` so
- * exact-match invalidation would miss them). Does NOT sweep the
- * org-wide list — callers must call {@link invalidateOrgIssueList}
- * once per operation. Never throws.
- */
-async function invalidateIssueDetailCaches(
-  regionUrl: string,
-  orgSlug: string,
-  issueId: string
-): Promise<void> {
-  try {
-    await Promise.all([
-      invalidateCachedResponsesMatching(
-        buildApiUrl(regionUrl, "organizations", orgSlug, "issues", issueId)
-      ),
-      // Legacy `/api/0/issues/{id}/` is stored under the non-region base
-      // (see `apiRequest` → `getApiBaseUrl`), NOT the org's region URL.
-      invalidateCachedResponsesMatching(
-        buildApiUrl(getApiBaseUrl(), "issues", issueId)
-      ),
-    ]);
-  } catch {
-    /* best-effort: mutation already succeeded upstream */
-  }
-}
-
-/**
- * Flush detail + list caches for one issue. Use for single-issue
- * mutations (resolve, unresolve); batch mutations should use the
- * detail-only helper plus one final {@link invalidateOrgIssueList}.
- *
- * Minor redundancy: the org-scoped half of
- * {@link invalidateIssueDetailCaches} is already a prefix of the
- * {@link invalidateOrgIssueList} sweep. Accepted because the helpers
- * are each also used solo elsewhere, and the extra directory walk is
- * negligible.
- *
- * Never throws.
- */
-async function invalidateIssueCaches(
-  regionUrl: string,
-  orgSlug: string,
-  issueId: string
-): Promise<void> {
-  try {
-    await Promise.all([
-      invalidateIssueDetailCaches(regionUrl, orgSlug, issueId),
-      invalidateOrgIssueList(regionUrl, orgSlug),
-    ]);
-  } catch {
-    /* best-effort: mutation already succeeded upstream */
-  }
-}
-
-/**
- * Sweep every paginated variant of the org's issue-list endpoint.
- * Never throws.
- */
-async function invalidateOrgIssueList(
-  regionUrl: string,
-  orgSlug: string
-): Promise<void> {
-  try {
-    await invalidateCachedResponsesMatching(
-      buildApiUrl(regionUrl, "organizations", orgSlug, "issues")
-    );
-  } catch {
-    /* best-effort: mutation already succeeded upstream */
-  }
-}

src/lib/api/projects.ts

@@ -25,16 +25,13 @@ import { cacheProjectsForOrg } from "../db/project-cache.js";
 import { getCachedOrganizations } from "../db/regions.js";
 import { type AuthGuardSuccess, withAuthGuard } from "../errors.js";
 import { logger } from "../logger.js";
-import { resolveOrgRegion } from "../region.js";
-import { invalidateCachedResponsesMatching } from "../response-cache.js";
 import { getApiBaseUrl } from "../sentry-client.js";
 import { buildProjectUrl } from "../sentry-urls.js";
 import { isAllDigits } from "../utils.js";
 
 import {
   API_MAX_PER_PAGE,
   apiRequestToRegion,
-  buildApiUrl,
   getOrgSdkConfig,
   MAX_PAGINATION_PAGES,
   ORG_FANOUT_CONCURRENCY,
@@ -169,7 +166,6 @@ export async function createProject(
     body,
   });
   const data = unwrapResult(result, "Failed to create project");
-  await invalidateOrgProjectCache(orgSlug);
   return data as unknown as SentryProject;
 }
 
@@ -219,52 +215,6 @@ export async function deleteProject(
     },
   });
   unwrapResult(result, "Failed to delete project");
-  await invalidateProjectCaches(orgSlug, projectSlug);
-}
-
-/**
- * Flush the project-detail GET and the org-wide project list so
- * follow-up `project list` / `project view` reads don't see the
- * deleted project. Never throws.
- *
- * Uses prefix-matching on the project detail URL rather than an exact
- * match because `getProject()` appends `?collapse=organization`, and
- * the response cache keys entries by the full URL (including query
- * string). A prefix sweep catches the collapsed variant plus any
- * future query-parameter additions.
- */
-async function invalidateProjectCaches(
-  orgSlug: string,
-  projectSlug: string
-): Promise<void> {
-  try {
-    const regionUrl = await resolveOrgRegion(orgSlug);
-    await Promise.all([
-      invalidateCachedResponsesMatching(
-        buildApiUrl(regionUrl, "projects", orgSlug, projectSlug)
-      ),
-      invalidateCachedResponsesMatching(
-        buildApiUrl(regionUrl, "organizations", orgSlug, "projects")
-      ),
-    ]);
-  } catch {
-    /* best-effort: mutation already succeeded */
-  }
-}
-
-/**
- * Sweep every paginated variant of the org's project-list endpoint.
- * Used by `project create`. Never throws.
- */
-async function invalidateOrgProjectCache(orgSlug: string): Promise<void> {
-  try {
-    const regionUrl = await resolveOrgRegion(orgSlug);
-    await invalidateCachedResponsesMatching(
-      buildApiUrl(regionUrl, "organizations", orgSlug, "projects")
-    );
-  } catch {
-    /* best-effort: mutation already succeeded */
-  }
 }
 
 /** Result of searching for projects by slug across all organizations. */