@volter/twin-sentry 0.1.37 → 1.0.1

package/src/sentry-budget.ts

@@ -1,171 +0,0 @@
-// Sentry's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
-// bindings `liveSentryExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
-// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
-// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
-// header for the full rationale AND for the honest list of what the guard does not guarantee (an
-// injected clock or ledger path still defeats it — it guards carelessness, not malice).
-//
-// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
-// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
-// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
-// that follows it; a BUDGET binds the code that does not.
-//
-// ── HOW THE CEILING WAS CHOSEN: NO SCALAR IS PUBLISHED ──────────────────────────────────────
-// Sentry does NOT publish a scalar limit. From https://docs.sentry.io/api/ratelimits/ (read
-// 2026-07-26): every request is rate limited on TWO axes — a requests-per-second fixed window and a
-// concurrency cap — and "each endpoint has its own maximum number of requests and window size". No
-// figure is stated anywhere. (Plan-dependence is widely reported but is NOT on that page, so it is
-// not quoted as if it were — §9 removed an earlier quotation mark around it, 2026-07-26.) Over the limit you get
-// 429 + `Retry-After`, and every response carries `X-Sentry-Rate-Limit-Limit` / `-Remaining` /
-// `-Reset` / `-ConcurrentLimit` / `-ConcurrentRemaining`. The docs' own advice is to prefer
-// webhooks over polling.
-//
-// So this budget deliberately does NOT model the vendor's limit, and the numbers below are NOT
-// derived from one. Because there is no documented figure to justify going higher, the ceiling is
-// pinned at the kernel's own undeclared fallback in every dimension: 60 weighted units per 60s at
-// `defaultWeight` 2 — 30 calls a minute, exactly `DEFAULT_RATE_BUDGET`, with no endpoint priced
-// CHEAPER than the fallback would price it. What this declaration adds over the fallback is
-// therefore not headroom, it is RESOLUTION: the paginated firehose gets priced up.
-//
-// The one thing the guard genuinely buys here is the COOLDOWN: `X-Sentry-Rate-Limit-Remaining: 0`
-// and `Retry-After` are both read off the response and turn into a persisted refusal, so the
-// vendor's first "back off" becomes a hard client-side stop instead of a retry storm — which is the
-// only correct response to a limit whose real value you cannot know client-side.
-//
-// ── HOW THE WEIGHTS WERE CHOSEN (a judgement call, stated as one) ────────────────────────────
-// Since no per-endpoint figure is published, no weight here can claim to be arithmetic. The single
-// rule prices the ISSUE/EVENT list reads at 4 — double the default. They are the cursor-paginated
-// firehose (an org's whole event stream, page after page), they are the thing the docs single out
-// as "use webhooks instead of polling this", and they play exactly the role `/images` renders
-// played in the Figma lockout: the endpoint a pagination bug turns into hundreds of calls. At
-// weight 4 at most 15 land in a window.
-import {
-  declareRateBudget,
-  rateBudgetPath,
-  rateBudgetWeight,
-  RateBudget,
-  type RateBudgetDeclaration,
-  type RateBudgetOptions,
-  type RateBudgetReservation,
-  type RateBudgetSnapshot,
-} from '@volter/world-core';
-
-const VENDOR = 'sentry';
-
-/** Rolling window, in ms. Spend older than this is pruned. */
-export const SENTRY_BUDGET_WINDOW_MS = 60_000;
-
-/**
- * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
- * EXACTLY the kernel's undeclared fallback, because Sentry publishes no scalar that would justify
- * more. See the header.
- */
-export const SENTRY_BUDGET_CEILING = 60;
-
-/** Seconds. A `Retry-After` above this means the token is throttled hard — fail loudly, don't sleep. */
-export const SENTRY_BUDGET_MAX_RETRY_AFTER_S = 300;
-
-/** Per-call cost, keyed by `"<METHOD> <path>"`. No figure here can claim to be published. */
-export const SENTRY_CALL_WEIGHTS = {
-  /** `…/issues/` and `…/events/` list reads — the cursor-paginated firehose the docs say not to poll. */
-  stream: 4,
-  /** Everything else: project/release/issue reads, issue updates. */
-  other: 2,
-} as const;
-
-/** THE PACK'S DECLARATION — pure data, the only Sentry-specific thing in the whole budget. */
-export const SENTRY_RATE_BUDGET: RateBudgetDeclaration = {
-  windowMs: SENTRY_BUDGET_WINDOW_MS,
-  ceiling: SENTRY_BUDGET_CEILING,
-  defaultWeight: SENTRY_CALL_WEIGHTS.other,
-  maxRetryAfterSeconds: SENTRY_BUDGET_MAX_RETRY_AFTER_S,
-  rules: [
-    // `(/|$)` rather than a bare trailing `/`: the pricer normalizes a trailing slash away (so
-    // `…/issues/` and `…/issues` are one endpoint), and a rule insisting on the slash would miss both.
-    // (§9 finding, 2026-07-26.)
-    { match: '^GET /api/0/(projects|organizations)/[^/]+/[^/]+/(issues|events)(/|$)', weight: SENTRY_CALL_WEIGHTS.stream },
-  ],
-  reason:
-    'Sentry publishes NO scalar limit (docs.sentry.io/api/ratelimits, read 2026-07-26): every request ' +
-    'is limited on a requests-per-second fixed window AND a concurrency cap, "each endpoint has its ' +
-    'own maximum number of requests and window size", and no figure is stated anywhere. ' +
-    'Over it: 429 + Retry-After, with X-Sentry-Rate-Limit-Limit/-Remaining/-Reset/-ConcurrentLimit ' +
-    'headers on every response, and the docs advise webhooks over polling. Because no published ' +
-    'figure justifies going higher, the ceiling is pinned at the kernel fallback in EVERY dimension ' +
-    '— 60 units / 60s at defaultWeight 2 = 30 calls/min, and no endpoint is priced cheaper than the ' +
-    'fallback would price it; the declaration buys resolution, not headroom. The issue/event LIST ' +
-    'reads cost 4 (the cursor-paginated firehose the docs single out, and the shape a pagination bug ' +
-    'turns into hundreds of calls) — a judgement call, not a published cost, since none exists. What ' +
-    "the guard genuinely buys here is the cooldown: the vendor's first back-off signal becomes a " +
-    'persisted client-side stop instead of a retry storm.',
-};
-
-// Declared at module load, so merely importing this module (which `sentry-connector.ts` does) is
-// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
-// takes effect the moment it lands, and constructing through the subclass below (which imports this
-// module) is what makes the ordering a non-issue in practice.
-declareRateBudget(VENDOR, SENTRY_RATE_BUDGET);
-
-/**
- * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
- * price by method without the kernel knowing anything about Sentry. An unclassified endpoint still
- * costs `defaultWeight` — nothing is ever free.
- */
-export function sentryCallWeight(method: string, path: string): number {
-  const { bare, query } = splitQuery(path);
-  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
-  // `execute('post', …)` really does issue a POST and must be priced as one.
-  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
-}
-
-/**
- * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the query.
- *
- * NORMALIZED, because the anchored rules are otherwise trivially evaded (§9 finding, 2026-07-26):
- * `fetch` upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE
- * that a `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor
- * while most routers treat it as the same endpoint. Both are input variations, not attacks, and
- * either one silently voids the "expensive endpoints are priced up" claim the ceiling rests on.
- */
-function splitQuery(path: string): { bare: string; query: Record<string, string> } {
-  const at = path.indexOf('?');
-  const query: Record<string, string> = {};
-  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
-  const raw = at === -1 ? path : path.slice(0, at);
-  // Collapse a trailing slash, but never turn the root path into the empty string.
-  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
-  return { bare, query };
-}
-
-/** Where Sentry's ledger lives. Token-keyed and cwd-independent by default (limits attach to the
- *  auth token's organization, so a cwd-scoped ledger would hand the same token a fresh allowance in
- *  every checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
-export function sentryBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
-  const o = typeof opts === 'string' ? { root: opts } : opts;
-  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
-  // excess-property check only catches object literals) must not redirect this pack's ledger to
-  // another vendor's file.
-  return rateBudgetPath({ ...o, vendor: VENDOR });
-}
-
-/** Construction options for Sentry's budget. The vendor is fixed; everything else may only TIGHTEN. */
-export type SentryBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
-
-/**
- * Sentry's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
- * not an alias, so `budget instanceof SentryBudget` in `liveSentryExecute` means "a budget that
- * accounts against SENTRY's ledger under SENTRY's ceiling": another vendor's `RateBudget` (with its
- * own, possibly larger, ceiling) is NOT assignable there.
- */
-export class SentryBudget extends RateBudget {
-  constructor(opts: SentryBudgetOptions = {}) {
-    super({ ...opts, vendor: VENDOR });
-  }
-}
-
-/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
- *  which one refused, and `err.kind` says why. */
-export { RateBudgetError as SentryBudgetError } from '@volter/world-core';
-export type { RateBudgetErrorKind as SentryBudgetErrorKind } from '@volter/world-core';
-export type SentryBudgetReservation = RateBudgetReservation;
-export type SentryBudgetSnapshot = RateBudgetSnapshot;