@brass-build/client 0.4.0 → 0.5.0

package/src/api-fetch.ts

@@ -13,6 +13,12 @@ export interface ApiRequest {
   path: string;
   // JSON-encoded when present; sets `content-type: application/json`.
   body?: unknown;
+  // Attempts a GET gets when it is refused as throttled or fails in the
+  // network, including the first. Defaults to `fetchWithRetry`'s.
+  maxAttempts?: number;
+  // A POST that changes nothing (a read whose ids travel in the body), so it
+  // is retried as a GET is.
+  idempotent?: boolean;
 }
 
 interface ApiFetchOptions {
@@ -47,8 +53,11 @@ export function createApiFetch(opts: ApiFetchOptions): ApiFetch {
     // rather than surfacing it as a hard failure; a write is never
     // replayed here.
     const response =
-      method === 'GET'
-        ? await fetchWithRetry(() => fetch(url, init))
+      method === 'GET' || req.idempotent === true
+        ? await fetchWithRetry(
+            () => fetch(url, init),
+            req.maxAttempts !== undefined ? { maxAttempts: req.maxAttempts } : {},
+          )
         : await fetch(url, init);
     if (response.status === 204) return undefined as T;
 
@@ -82,7 +91,38 @@ function isErrorBody(body: unknown): body is { error: string } {
 // through here so the server's machine-readable denials, in particular
 // `code: "app_not_installed"`, survive into the error the caller (and
 // the SDK's own install-consent offer) can branch on.
+// What a 409 to an import claim says about the client holding it: how long
+// ago it last claimed or refreshed, and whether its output is being sealed.
+export interface ClaimHolder {
+  refreshedMsAgo: number;
+  expiresInMs: number;
+  sealing: boolean;
+}
+
+const claimHolders = new WeakMap<BrassError, ClaimHolder>();
+
+export function claimHolderOf(err: unknown): ClaimHolder | null {
+  return err instanceof BrassError ? (claimHolders.get(err) ?? null) : null;
+}
+
+function readClaimHolder(body: unknown): ClaimHolder | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const b = body as Record<string, unknown>;
+  const ago = b['refreshed_ms_ago'];
+  const lapses = b['expires_in_ms'];
+  if (b['pending'] !== true || typeof ago !== 'number' || !Number.isFinite(ago)) return null;
+  if (typeof lapses !== 'number' || !Number.isFinite(lapses)) return null;
+  return { refreshedMsAgo: ago, expiresInMs: lapses, sealing: b['sealing'] === true };
+}
+
 export function brassErrorFromBody(status: number, parsed: unknown): BrassError {
+  const err = brassErrorOf(status, parsed);
+  const holder = status === 409 ? readClaimHolder(parsed) : null;
+  if (holder !== null) claimHolders.set(err, holder);
+  return err;
+}
+
+function brassErrorOf(status: number, parsed: unknown): BrassError {
   const message = isErrorBody(parsed) ? parsed.error : 'Request failed';
   if (isNotInstalledBody(parsed)) {
     return new BrassError(message, {
@@ -99,7 +139,17 @@ export function brassErrorFromBody(status: number, parsed: unknown): BrassError
       ...(typeof title === 'string' ? { title } : {}),
     });
   }
-  return new BrassError(message, { status });
+  const code = serverCode(parsed);
+  return new BrassError(message, { status, ...(code !== null ? { code } : {}) });
+}
+
+// The code a refusal body carries, when it is one: a short snake_case token.
+const SERVER_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+
+function serverCode(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const code = (value as { code?: unknown }).code;
+  return typeof code === 'string' && SERVER_CODE.test(code) ? code : null;
 }
 
 // The platform refuses to join a document this app's declared schema cannot

package/src/auth-flow.ts

@@ -40,7 +40,7 @@ interface RefreshResponse {
 }
 
 // The credential the SDK presents to POST /refresh.
-//   - `cookie`: the default; the browser attaches the `brass_auth` cookie
+//   - `cookie`: the default; the browser attaches the `__Host-brass_auth` cookie
 //      and nothing is sent in the body. Works wherever the third-party
 //      cookie is allowed.
 //   - `code`: a one-time `brass_code` from the sign-in redirect, exchanged

package/src/batched-get.ts

@@ -0,0 +1,117 @@
+// Answers `documents.get` calls made in the same turn with one request per
+// `BATCH_SIZE` ids. An app reading the record of each of several hundred
+// documents calls `get` for each, usually all at once, and one request per
+// document spends the API's request budget for the app's other calls and
+// every other caller's. The server reads a batch's documents on one
+// invocation, so a smaller batch spreads that work across invocations.
+//
+// A lone call is sent as its own read. Each id in a batch resolves or rejects
+// exactly as its own read would, from the status and body the server answered
+// for it. A platform that does not serve the batch route answers 404 for the
+// whole request, and its ids are then read one at a time.
+
+import type { ApiFetch } from './api-fetch.js';
+import { brassErrorFromBody } from './api-fetch.js';
+import { BrassError } from './errors.js';
+import type { RequestLane } from './request-lane.js';
+
+export const BATCH_SIZE = 20;
+
+interface Pending<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (err: unknown) => void;
+}
+
+interface BatchResult {
+  doc_id: string;
+  status: number;
+  body: unknown;
+}
+
+export interface BatchedGetOptions {
+  apiFetch: ApiFetch;
+  lane: RequestLane;
+  // Reads one document on its own: the lone call, and the fallback.
+  single: (docId: string) => Promise<unknown>;
+  // Attempts the batch request makes against a throttled API.
+  maxAttempts: number;
+}
+
+export function createBatchedGet<T>(opts: BatchedGetOptions): (docId: string) => Promise<T> {
+  let waiting = new Map<string, Pending<T>>();
+  let scheduled = false;
+
+  const settle = (entry: Pending<T>, run: () => Promise<unknown>): void => {
+    run().then((value) => entry.resolve(value as T), entry.reject);
+  };
+
+  const sendBatch = async (ids: string[], entries: Map<string, Pending<T>>): Promise<void> => {
+    let results: BatchResult[];
+    try {
+      const answer = await opts.lane.run(`batch:${ids.join(',')}`, () =>
+        opts.apiFetch<{ results: BatchResult[] }>({
+          method: 'POST',
+          path: '/documents/details',
+          body: { doc_ids: ids },
+          idempotent: true,
+          maxAttempts: opts.maxAttempts,
+        }),
+      );
+      results = answer.results;
+    } catch (err) {
+      if (err instanceof BrassError && err.status === 404) {
+        for (const id of ids) settle(entries.get(id)!, () => opts.single(id));
+        return;
+      }
+      for (const id of ids) entries.get(id)!.reject(err);
+      return;
+    }
+    const byId = new Map(results.map((r) => [r.doc_id, r]));
+    for (const id of ids) {
+      const entry = entries.get(id)!;
+      const result = byId.get(id);
+      if (result === undefined) {
+        entry.reject(new BrassError('Request failed', { status: 500 }));
+      } else if (result.status >= 200 && result.status < 300) {
+        entry.resolve(result.body as T);
+      } else {
+        entry.reject(brassErrorFromBody(result.status, result.body));
+      }
+    }
+  };
+
+  const flush = (): void => {
+    scheduled = false;
+    const entries = waiting;
+    waiting = new Map();
+    const ids = [...entries.keys()];
+    if (ids.length === 1) {
+      settle(entries.get(ids[0]!)!, () => opts.single(ids[0]!));
+      return;
+    }
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+      void sendBatch(ids.slice(i, i + BATCH_SIZE), entries);
+    }
+  };
+
+  return (docId: string): Promise<T> => {
+    const pending = waiting.get(docId);
+    if (pending !== undefined) return pending.promise;
+    let resolve!: (value: T) => void;
+    let reject!: (err: unknown) => void;
+    const promise = new Promise<T>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    waiting.set(docId, { promise, resolve, reject });
+    if (!scheduled) {
+      scheduled = true;
+      // A task rather than a microtask, so a call made from a promise callback
+      // before the next task (a handler per input, a loop after an await)
+      // joins the same batch.
+      setTimeout(flush, 0);
+    }
+    return promise;
+  };
+}

package/src/call-service.ts

@@ -149,6 +149,10 @@ export interface CallServiceDeps {
     host: string,
   ) => Promise<boolean>;
   fetchImpl?: typeof fetch;
+  /** Injected for tests; defaults to the real timer. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injected for tests; defaults to `Date.now`. */
+  now?: () => number;
 }
 
 export async function callService(
@@ -187,7 +191,7 @@ export async function callService(
     });
   };
 
-  const response = await send();
+  const response = await sendThroughFrontDoor(send, deps);
   // The service's own status is the answer, so nothing here throws on one.
   // The exceptions are the refusals that are a question for the person rather
   // than a result for the app: offer the hosted surface that asks it, and send
@@ -197,13 +201,84 @@ export async function callService(
   const ask = response.headers.get(BRASS_ASK_HEADER);
   if (ask === 'credential') {
     return (await deps.offerServiceCredential(organizationId, host))
-      ? send()
+      ? sendThroughFrontDoor(send, deps)
       : response;
   }
   if (ask !== 'install') return response;
   const denial = await notInstalledDenial(response);
   if (!denial) return response;
-  return (await deps.offerInstallConsent(denial)) ? send() : response;
+  return (await deps.offerInstallConsent(denial))
+    ? sendThroughFrontDoor(send, deps)
+    : response;
+}
+
+// Every answer from Brass carries this header, and the broker drops any header
+// under that prefix a service sends. Without it, in the gateway's own body, the
+// answer came from the gateway in front of Brass: a `429` from its rate limit,
+// or a quick `503` from a call it could not start because the brokered call's
+// concurrency was all in use. Nothing behind the gateway ran for either, so
+// sending it again is safe whatever the method. The gateway's `503` for a call
+// that ran past its 30s limit has the same body, and that call may have reached
+// the service, so a `503` counts only when it came back well inside that limit.
+const ANSWERED_BY_BRASS_HEADER = 'x-brass-answered';
+
+// A quick 503 lasts until a call already running ends, which is within the
+// gateway's 30s limit, so the resend lasts that long. The backoff stays short
+// so the call starts soon after room frees.
+const FRONT_DOOR_WINDOW_MS = 30_000;
+const FRONT_DOOR_BASE_DELAY_MS = 300;
+const FRONT_DOOR_MAX_DELAY_MS = 2_000;
+const FRONT_DOOR_MESSAGES: Record<number, string> = {
+  429: 'Too Many Requests',
+  503: 'Service Unavailable',
+};
+const FRONT_DOOR_503_WITHIN_MS = 10_000;
+
+async function shedByFrontDoor(response: Response, elapsedMs: number): Promise<boolean> {
+  const message = FRONT_DOOR_MESSAGES[response.status];
+  if (message === undefined || response.headers.has(ANSWERED_BY_BRASS_HEADER)) return false;
+  if (response.status === 503 && elapsedMs >= FRONT_DOOR_503_WITHIN_MS) return false;
+  try {
+    const body = (await response.clone().json()) as unknown;
+    return (
+      typeof body === 'object' &&
+      body !== null &&
+      Object.keys(body).length === 1 &&
+      (body as { message?: unknown }).message === message
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function sendThroughFrontDoor(
+  send: () => Promise<Response>,
+  deps: Pick<CallServiceDeps, 'sleep' | 'now'>,
+): Promise<Response> {
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const firstSentAt = now();
+  let response: Response;
+  for (let attempt = 0; ; attempt += 1) {
+    const startedAt = now();
+    response = await send();
+    if (!(await shedByFrontDoor(response, now() - startedAt))) return response;
+    const delay =
+      Math.min(FRONT_DOOR_BASE_DELAY_MS * 2 ** attempt, FRONT_DOOR_MAX_DELAY_MS) +
+      Math.random() * FRONT_DOOR_BASE_DELAY_MS;
+    if (now() + delay - firstSentAt > FRONT_DOOR_WINDOW_MS) break;
+    await sleep(delay);
+  }
+  // Still shed after the window: answered with the code of Brass's own
+  // limit, so an app branches on one `code` for both, and with an `error`
+  // naming the gateway's status, so a report says which one turned it away.
+  return new Response(
+    JSON.stringify({
+      error: `The gateway in front of Brass turned the call away (${response.status})`,
+      code: 'rate_limited',
+    }),
+    { status: 429, headers: { 'content-type': 'application/json' } },
+  );
 }
 
 // No organization resolved, for a caller that did not ask for the chooser.