cartethyia 2.4.5 → 2.5.0

package/src/console/providers/oauth/callback-listener.ts

@@ -25,6 +25,7 @@
  * already spent.
  */
 import { log } from "../../../observability/logger";
+import { ConsoleDomainError } from "../../shared/errors";
 
 /** A loopback endpoint a callback can actually be delivered to. */
 export interface LoopbackCallbackEndpoint {
@@ -224,10 +225,15 @@ export class OAuthCallbackListener {
     try {
       servers.push(this.#serve({ hostname: "127.0.0.1", port: endpoint.port, fetch: handler }));
     } catch (cause) {
-      throw new Error(
+      // A domain error, not a bare Error: the console route maps an untyped
+      // failure to a generic `internal_error`, which hid an actionable "free
+      // the port" message behind "Failed to start OAuth".
+      throw new ConsoleDomainError(
+        "oauth_callback_port_unavailable",
+        409,
         `OAuth callback port ${endpoint.port} is in use, so the login redirect to ${endpoint.path} cannot be delivered. ` +
           `Free port ${endpoint.port} and retry.`,
-        { cause },
+        { port: endpoint.port, path: endpoint.path },
       );
     }
     try {
@@ -253,7 +259,16 @@ export class OAuthCallbackListener {
     }
     const error = url.searchParams.get("error");
     const state = url.searchParams.get("state") ?? "";
-    const code = url.searchParams.get("code") ?? "";
+    /**
+     * Not every authorization server hands back a `code`. Trae's page redirects
+     * with the refresh token already in the query (`?isRedirect=true&
+     * refreshToken=…`), and the client's parser reads the whole query. So an
+     * absent `code` falls back to the query itself — the client decides whether
+     * it can redeem it, and one that cannot still fails with its own message
+     * rather than a bare 400 here.
+     */
+    const codeParam = url.searchParams.get("code") ?? "";
+    const code = codeParam.length > 0 ? codeParam : url.search.slice(1);
     if (error !== null) {
       // A denial carries the state only when the server echoes one; clear it
       // when present so a retry starts a fresh flow.

package/src/console/providers/oauth/routes.ts

@@ -28,14 +28,22 @@ import type { ConsoleAccessResolver } from "../../auth/access";
  * identity the provider itself reports (an email or org name), which is stable
  * across logins, so it is what a re-login replaces.
  *
- * A provider that reports no label falls back to the refresh-token fingerprint,
- * which is the old behaviour and still catches an exact replay. Renaming an
- * account in the console changes the stored label, so a later login is treated
- * as a new account rather than silently overwriting the rename — the same
- * tradeoff the unique index has always had, now stated where it is decided.
+ * A label the provider never resolved is *not* that identity. Callers fill the
+ * gap with the provider id (`cursor`, `github`), and hashing that made every
+ * login of every account of that provider collide: the second login matched the
+ * first row and replaced it, so adding an account silently consumed the one
+ * already there. Only a label the provider actually reported — or the refresh
+ * token, which still catches an exact replay — may be the identity.
+ *
+ * Test seam: exported so the merge rule can be pinned without a database.
  */
-function oauthIdentityFingerprint(input: { readonly label: string } & OAuthExchangeResult): string {
-  return hashSecret(input.label.trim().length > 0 ? input.label.trim() : input.refresh);
+export function oauthIdentityFingerprint(input: {
+  readonly label: string;
+  readonly providerId: string;
+} & OAuthExchangeResult): string {
+  const label = input.label.trim();
+  const resolved = label.length > 0 && label.toLowerCase() !== input.providerId.trim().toLowerCase();
+  return hashSecret(resolved ? label : input.refresh);
 }
 
 export class DrizzleOAuthAccountStore implements OAuthAccountStore {
@@ -46,7 +54,7 @@ export class DrizzleOAuthAccountStore implements OAuthAccountStore {
     providerId: string,
     input: { readonly label: string } & OAuthExchangeResult,
   ): Promise<PersistedOAuthAccount> {
-    const credentialFingerprint = oauthIdentityFingerprint(input);
+    const credentialFingerprint = oauthIdentityFingerprint({ ...input, providerId });
     const sameAccount = and(
       eq(providerAccounts.providerId, providerId),
       // The identity index coalesces a null tenant to a sentinel, so "same
@@ -375,12 +383,32 @@ export function createOAuthLoginOperations(config: OAuthLoginConfig) {
         }
         const state = generateOAuthState();
         const { codeVerifier, codeChallenge } = generatePkcePair();
+        /**
+         * A client whose authorize URL depends on an upstream discovery runs it
+         * here, before the URL is built: `buildAuthorizeUrl` is synchronous by
+         * contract, so a client cannot fetch inside it.
+         *
+         * Trae is the reason this is wired up: its login host comes from
+         * `GetLoginGuidance`, and without this step the URL was built with no
+         * host and the login failed at the first click. Kiro declares the hook
+         * as a no-op, so nothing that already worked changes.
+         */
+        const authorizeRequest = {
+          state,
+          codeChallenge,
+          redirectUri: client.browserRedirectUri ?? browserAuthorizeRedirectUri(),
+          ...(parameters === undefined ? {} : { parameters }),
+        };
+        const prepared =
+          typeof client.prepareAuthorize === "function"
+            ? await client.prepareAuthorize(authorizeRequest)
+            : authorizeRequest;
         // A client that names its own allowlisted redirect URI wins over the
         // gateway default: OpenAI registers exactly `http://localhost:1455/auth/callback`
         // for the Codex client and answers any other value with
         // `invalid_request` before consent, so the shared default cannot serve
         // every provider.
-        const redirectUri = client.browserRedirectUri ?? browserAuthorizeRedirectUri();
+        const redirectUri = authorizeRequest.redirectUri;
         // Bind the redirect's loopback port before the flow is recorded. The
         // advertised URI names the operator's own machine, so a login that only
         // advertises it leaves the browser on a dead page and the code stranded
@@ -404,12 +432,7 @@ export function createOAuthLoginOperations(config: OAuthLoginConfig) {
         // deliver itself; a non-loopback redirect (a custom scheme, a remote
         // host) returns false and keeps the manual path.
         return {
-          authorizeUrl: client.buildAuthorizeUrl({
-            state,
-            codeChallenge,
-            redirectUri,
-            ...(parameters === undefined ? {} : { parameters }),
-          }),
+          authorizeUrl: client.buildAuthorizeUrl(prepared),
           state,
         };
       },

package/src/console/quota/account-quota-tenant.ts

@@ -29,6 +29,7 @@ import type { ProviderId } from "../../providers/provider-contracts";
 import {
   DAILY_CHECKIN_PROVIDER_IDS,
   checkinAttemptedToday,
+  checkinAttemptedTodayBatch,
   dailyCheckinEgressForPass,
   markCheckinAttempted,
 } from "../../workers/daily-checkin";
@@ -334,12 +335,14 @@ export function registerAccountQuotaTenantRoutes(
       // request; only check-in-capable accounts can carry one, so only they
       // are read.
       const checkinCandidates = rows.filter((row) => supportsAccountCheckin(row.providerId));
-      const checkinAttempted = new Map<string, boolean>();
-      await Promise.all(
-        checkinCandidates.map(async (row) => {
-          checkinAttempted.set(row.id, await todayCheckinAttempted(db, redis, row.id));
-        }),
-      );
+      // One batched read for the whole page. Per-account reads made opening
+      // this route scale with the account count — a round trip each, on the
+      // route the dashboard polls — for a marker that is one key per account.
+      const checkinAttempted = await checkinAttemptedTodayBatch({
+        db,
+        redis,
+        accountIds: checkinCandidates.map((row) => row.id),
+      });
       // Real credit deductions, read from the stored snapshots rather than from
       // the upstream: the page renders every account at once, and re-hitting the
       // billing endpoint per account would make opening it scale with the

package/src/console/quota/refresh.ts

@@ -377,6 +377,25 @@ async function runQuotaRefresh(
   // unsupported") is itself the answer the page must render, and caching it
   // stops every page open from re-hitting a provider that just refused us.
   await setCachedQuota(targetLens(target), target.accountId, quota, deps.redis);
+  // Persist the plan the provider reported, because routing gates on it: some
+  // upstreams refuse a model on a free plan and nothing but the account's own
+  // plan says which. The cache above is a short in-process TTL and empty after
+  // a restart, so it cannot be the only copy — the row is what survives one.
+  //
+  // A failed fetch leaves the last known plan in place rather than clearing
+  // it. The refresh failing is evidence about the network or the credential,
+  // not evidence that the account's plan changed, and clearing on failure
+  // would drop the router back to "unknown" on every transient error.
+  if (quota.plan !== null) {
+    try {
+      await deps.db
+        .update(providerAccounts)
+        .set({ quotaPlan: quota.plan })
+        .where(eq(providerAccounts.id, target.accountId));
+    } catch (error) {
+      log.warn(`[quota] failed to record plan for account=${target.accountId}`, error as Error);
+    }
+  }
   // A quota surface that names the account adopts the identity — but only over
   // a default label. An operator's custom rename is never overwritten, and the
   // CASE keeps the read and the write in one statement so a concurrent rename

package/src/console/response-compression.ts

@@ -9,6 +9,18 @@
  * what the browser spends its time receiving, and shaving microseconds off a
  * handler cannot compete with removing 94% of the bytes.
  *
+ * ## Why the gate is a path allowlist inside the function
+ *
+ * The wrap is mounted on the console Elysia instance (`console-router.ts`),
+ * but Elysia's `use()` merges the child's `hoc` into the **root** app's ext
+ * (`node_modules/elysia/dist/base.js:886-887`). Measured: the wrap therefore
+ * runs for `/v1/*` too, so instance-level scoping cannot express "console
+ * only". A path test can, and it lives inside `gzipResponse` — the one place
+ * that runs on every request.
+ *
+ * Consequence: `/v1/models` was previously compressed as a side effect of
+ * that `hoc` propagation. It deliberately is not now.
+ *
  * ## Why this is scoped to the console, not the proxy
  *
  * `/v1/*` is deliberately excluded, for two independent reasons:
@@ -26,9 +38,26 @@
  * Below `MIN_COMPRESSIBLE_BYTES` the envelope, the header, and the CPU are all
  * pure loss: a 200-byte reply is not worth a gzip stream plus a browser
  * decompression step. The threshold sits where the saving stops being noise.
+ *
+ * ## Opting a route out
+ *
+ * A route that knows its body is already compressed — or is an encoded
+ * envelope that would gain nothing — sets {@link NO_COMPRESS_HEADER}. The
+ * honest-sounding alternative, declaring `content-encoding: gzip`, is a lie
+ * when the bytes on the wire are not gzip, and the client that believes it
+ * fails trying to inflate them.
  */
 import { gzipSync } from "node:zlib";
 
+/**
+ * Header a route sets to say "do not compress this", popped before the
+ * response leaves.
+ *
+ * Deleted rather than left on the response, so it stays an internal signal
+ * between two layers in this process and never reaches a client or a cache.
+ */
+export const NO_COMPRESS_HEADER = "x-cartethyia-no-compress";
+
 /**
  * Smallest body worth compressing.
  *
@@ -37,6 +66,19 @@ import { gzipSync } from "node:zlib";
  */
 export const MIN_COMPRESSIBLE_BYTES = 1024;
 
+/**
+ * Largest body this module will compress, as a ceiling on the event-loop
+ * stall.
+ *
+ * `gzipSync` is synchronous, so its cost is paid out of the request's own
+ * turn and is not interruptible. `/console/api/backup/export` answers with a
+ * multi-MB JSON document; at that size level 6 costs tens of milliseconds,
+ * which is longer than an entire dashboard poll. Those bytes go to disk
+ * rather than being polled, so the compression ratio is the wrong thing to
+ * optimise — above this size the response is returned as-is.
+ */
+export const MAX_COMPRESSIBLE_BYTES = 1024 * 1024;
+
 /** Content types worth compressing, matched by prefix. */
 const COMPRESSIBLE_TYPES: readonly string[] = [
   "application/json",
@@ -99,20 +141,42 @@ export function isCompressible(contentType: string | null, bodyLength: number):
  * type: `text/event-stream` is not in {@link COMPRESSIBLE_TYPES}, so a stream
  * can never reach the buffering path.
  *
- * The size gate runs on the **actual** byte length, not a declared
+ * The size gate runs on the **actual** byte length, not only a declared
  * `content-length`: Elysia does not set that header for a serialized object
- * (measured), so gating on it rejected every route worth compressing. The
+ * (measured), so gating on it alone rejected every route worth compressing. A
+ * declared length is still used as a fast path — it can skip the read for a
+ * small reply — but silence from the header must never mean "too small". The
  * content-type gate is what keeps a stream from being read here, and it is
  * checked before the body is touched.
  */
 export async function gzipResponse(request: Request, response: Response): Promise<Response> {
+  // Scoped to the paths this module documents. Instance-level scoping is not
+  // available here: the wrap's `hoc` propagates to the root app, so every
+  // route in the process — `/v1/*` included — reaches this function.
+  const pathname = new URL(request.url).pathname;
+  if (!pathname.startsWith("/console/api/") && pathname !== "/metrics") return response;
   if (request.method === "HEAD") return response;
   if (response.status === 204 || response.status === 304) return response;
   // Already encoded — by a route or by an upstream. Never encode twice.
   if (response.headers.has("content-encoding")) return response;
+  // A route that knows better: the body is an encoded envelope, or already
+  // compressed in a form this wire layer cannot describe. Deleted here so the
+  // signal stays internal and never reaches a client or a cache.
+  if (response.headers.has(NO_COMPRESS_HEADER)) {
+    response.headers.delete(NO_COMPRESS_HEADER);
+    return response;
+  }
   if (!acceptsGzip(request.headers.get("accept-encoding"))) return response;
   // Type first, before any read: this is what keeps an event stream out.
   if (!isCompressibleType(response.headers.get("content-type"))) return response;
+  // A bodiless reply has nothing to compress, and `arrayBuffer()` on a null
+  // body yields a 0-byte buffer that would rebuild into a non-null body.
+  if (response.body === null) return response;
+  // A declared length below the threshold skips the read entirely. It cannot
+  // be the only gate — Elysia sets no `content-length` for a serialized
+  // object (measured) — so the byte-length read below still has to exist.
+  const declared = response.headers.get("content-length");
+  if (declared !== null && Number(declared) < MIN_COMPRESSIBLE_BYTES) return response;
 
   const body = await response.arrayBuffer();
   // Below the threshold the envelope, the header, and the CPU are all pure
@@ -120,6 +184,9 @@ export async function gzipResponse(request: Request, response: Response): Promis
   // than compressed. A response that was read must always be rebuilt, or the
   // client would receive an empty body.
   if (body.byteLength < MIN_COMPRESSIBLE_BYTES) return rebuild(response, body);
+  // Above the ceiling the synchronous `gzipSync` stall costs more than the
+  // bytes it would save. Same rebuild obligation as the threshold path.
+  if (body.byteLength > MAX_COMPRESSIBLE_BYTES) return rebuild(response, body);
 
   const compressed = gzipSync(new Uint8Array(body), { level: GZIP_LEVEL });
   const headers = new Headers(response.headers);

package/src/console/routing/pools/probe-verdict.ts

@@ -58,3 +58,75 @@ export function classifyProviderProbeAnswer(httpStatus: number, body: string): P
     reason: `Reachable; upstream answered ${httpStatus} for the probe body`,
   };
 }
+
+/**
+ * Error codes that mean "this attempt never reached the upstream", not "the
+ * upstream refused this address".
+ *
+ * Every one of them is worth a second attempt, and the reason is the same in
+ * each case: the failure is a property of one socket, not of the egress. A
+ * proxy that has just been dialled for the first time has to resolve, open a
+ * tunnel, and complete a TLS handshake, and any of those steps can be refused
+ * or reset by a middlebox that accepts the very next attempt — which is exactly
+ * the "fails once, works on retry" report. Retiring the pool on the first one
+ * blames the address for a cold-start race.
+ */
+const RETRYABLE_TRANSPORT_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETRESET",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ECONNECT_TIMEOUT",
+]);
+/** How many `cause` links to follow; wraps are shallow in practice. */
+const PROBE_ERROR_CAUSE_DEPTH = 5;
+
+/**
+ * Whether one probe error should be retried before it becomes a verdict.
+ *
+ * Deliberately narrow: an abort is *our* deadline firing, so retrying it would
+ * spend the whole probe budget on a slow egress, and an unknown error is left
+ * alone rather than guessed at. Only transport codes that describe a single
+ * dead connection qualify.
+ */
+export function isRetryableProbeError(error: unknown): boolean {
+
+  // Walk the `cause` chain: a transport failure is routinely wrapped — the
+  // proxy layer raises `ProxyConnectHandshakeError` whose *message* carries the
+  // real code, with nothing on `code`. Checking only the top error would miss
+  // exactly the failure this exists for.
+  let current: unknown = error;
+  for (let depth = 0; depth < PROBE_ERROR_CAUSE_DEPTH && current !== undefined && current !== null; depth += 1) {
+    if (!(current instanceof Error)) break;
+    if (current.name === "AbortError" || current.name === "TimeoutError") return false;
+    // `code` is not on the base `Error`; narrow before reading it rather than
+    // asserting a shape the runtime may not have.
+    const code: string | undefined =
+      "code" in current && typeof current.code === "string" ? current.code : undefined;
+    if (code !== undefined && RETRYABLE_TRANSPORT_CODES.has(code.toUpperCase())) return true;
+    const message = String(current.message ?? "");
+    // The wrapped code is often only in the message, so match it there too.
+    for (const candidate of RETRYABLE_TRANSPORT_CODES) {
+      if (message.includes(candidate)) return true;
+    }
+    if (
+      message.includes("fetch failed") ||
+      message.includes("socket connection was closed unexpectedly") ||
+      message.includes("other side closed") ||
+      message.startsWith("terminated") ||
+      /connection (?:was|is) closed/i.test(message)
+    ) {
+      return true;
+    }
+    current = current.cause;
+  }
+  return false;
+}
+

package/src/console/share/share-router.ts

@@ -33,11 +33,14 @@ import {
 const MIN_TOKEN_LENGTH = 20;
 
 /**
- * Cadence of the share stats SSE snapshot. Short enough to read as live;
- * the rollup itself is a handful of indexed aggregates, so re-reading on this
- * interval is cheap next to the per-request telemetry insert it summarizes.
+ * Cadence of the share stats SSE snapshot.
+ *
+ * Raised with `SHARE_STATS_CACHE_TTL_SECONDS` (10 s). At 2 s the tick was
+ * shorter than the rollup's own cache TTL, so every push re-parsed the whole
+ * retained telemetry window — the interval was the thing making this read
+ * expensive, not the number of viewers. Short enough to still read as live.
  */
-const SHARE_STATS_STREAM_INTERVAL_MS = 2_000;
+const SHARE_STATS_STREAM_INTERVAL_MS = 10_000;
 
 /**
  * Context and capabilities for one allowed model, sourced from the public

package/src/console/share/share-stats.ts

@@ -227,12 +227,19 @@ const TOP_IPS_LIMIT = 50;
 const HOURS_WINDOW = 24;
 
 /**
- * Cache lifetime for one family's rollup. Equal to the share page's 2 s SSE
- * tick: a viewer cannot observe staleness longer than the refresh it already
- * accepts, while every viewer of one link shares a single computation. Declared
- * here rather than imported from the router so this port does not depend on it.
+ * Cache lifetime for one family's rollup.
+ *
+ * Matched to the share page's SSE tick, which was the point of the old 2 s
+ * value — but at 2 s the cache expired on every tick, so every single push was
+ * a full parse of the retained telemetry window. A share page's numbers move
+ * when a request does, not every 2 s; 10 s still reads as live, and cuts the
+ * parse rate by five.
+ *
+ * Declared here rather than imported from the router so this port does not
+ * depend on it. `SHARE_STATS_STREAM_INTERVAL_MS` must be raised with it, or
+ * the two drift apart and the cache expires between ticks for no reason.
  */
-export const SHARE_STATS_CACHE_TTL_SECONDS = 2;
+export const SHARE_STATS_CACHE_TTL_SECONDS = 10;
 
 /**
  * Cache key for one family's rollup. Both inputs change the payload — `keyIds`

package/src/console/shared/read-through-cache.ts

@@ -10,8 +10,26 @@
  * A Redis that is slow or down must never fail a request: every cache step
  * falls through to computing the answer, which is exactly what the request
  * would have done before there was a cache.
+ *
+ * ## Validators
+ *
+ * The endpoints answer dashboard polls that repeat every few seconds while the
+ * underlying telemetry window changes every minute. Without a validator every
+ * poll ships the whole payload — 8.8 KiB to 150 KiB of it — even when nothing
+ * changed. An ETag turns that into a ~200-byte `304`.
+ *
+ * Strong, not weak: the hash covers the exact serialized bytes the client
+ * would otherwise have received, so a matching validator means byte-identical
+ * content. A weaker or unstable hash would answer `304` for changed data and
+ * leave the dashboard showing stale numbers, which is worse than the bytes it
+ * saves.
+ *
+ * The ETag is computed **once per write**, never per read: hashing a 150 KiB
+ * body on every poll would move the cost off the wire and onto the CPU.
  */
 
+import { createHash } from "node:crypto";
+
 /** The slice of Redis this cache needs, so it can be tested without a server. */
 export interface ReadThroughCacheClient {
   get(key: string): Promise<string | null>;
@@ -25,25 +43,133 @@ export interface ReadThroughCacheClient {
  */
 export const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
 
-/** `undefined` when the row was never cached, so a computed `null` is cacheable. */
-export async function cachedRead<T>(
+/** The cached value plus the strong validator for the bytes it serializes to. */
+export interface CachedResult<T> {
+  readonly value: T;
+  readonly etag: string;
+}
+
+/** Quoted per RFC 9110: an entity-tag is always `"…"`. */
+function etagFor(bytes: string): string {
+  // SHA-256 over the exact serialized bytes. Not the FNV-1a in
+  // `payload-store.ts` — that one is module-private, and adding a second hash
+  // implementation would risk two different collision profiles for one
+  // purpose. SHA-256 is already used in `share-stats.ts` for cache identity.
+  return `"${createHash("sha256").update(bytes, "utf8").digest("hex").slice(0, 32)}"`;
+}
+
+/** The sibling key holding the validator, so a cached body is never re-hashed. */
+export function etagKey(key: string): string {
+  return `${key}:etag`;
+}
+
+/**
+ * Reads through the cache and returns a strong validator alongside the value.
+ *
+ * The validator is computed once, at the moment the body is written, and read
+ * back from its own key: a hit never hashes the payload. On a validator miss
+ * with a body hit — a partial eviction, or a row written by an older build —
+ * the body is re-hashed rather than discarded, so the pair cannot disagree.
+ *
+ * With no cache configured (`client === undefined`) the value is computed and
+ * the validator is still returned, so conditional requests keep working for
+ * the length of the client's own polling loop; only the cross-instance sharing
+ * is lost.
+ */
+export async function cachedReadWithEtag<T>(
   client: ReadThroughCacheClient | undefined,
   key: string,
   compute: () => Promise<T>,
   ttlSeconds: number = READ_THROUGH_DEFAULT_TTL_SECONDS,
-): Promise<T> {
-  if (client === undefined) return compute();
+): Promise<CachedResult<T>> {
+  if (client === undefined) {
+    const fresh = await compute();
+    return { value: fresh, etag: etagFor(JSON.stringify(fresh) ?? "null") };
+  }
   try {
     const hit = await client.get(key);
-    if (hit !== null) return JSON.parse(hit) as T;
+    if (hit !== null) {
+      const value = JSON.parse(hit) as T;
+      try {
+        const stored = await client.get(etagKey(key));
+        return { value, etag: stored ?? etagFor(hit) };
+      } catch {
+        return { value, etag: etagFor(hit) };
+      }
+    }
   } catch {
-    return compute();
+    // A cache read must never fail a request; compute instead.
   }
   const value = await compute();
+  const bytes = JSON.stringify(value) ?? "null";
+  const etag = etagFor(bytes);
   try {
-    await client.set(key, JSON.stringify(value), "EX", ttlSeconds);
+    await client.set(key, bytes, "EX", ttlSeconds);
+    await client.set(etagKey(key), etag, "EX", ttlSeconds);
   } catch {
     // A cache write must never fail a request that already has its answer.
   }
+  return { value, etag };
+}
+
+/** `undefined` when the row was never cached, so a computed `null` is cacheable. */
+export async function cachedRead<T>(
+  client: ReadThroughCacheClient | undefined,
+  key: string,
+  compute: () => Promise<T>,
+  ttlSeconds: number = READ_THROUGH_DEFAULT_TTL_SECONDS,
+): Promise<T> {
+  const { value } = await cachedReadWithEtag(client, key, compute, ttlSeconds);
   return value;
 }
+
+/**
+ * `cache-control` for a cached console read.
+ *
+ * `no-cache`, not `no-store`: the response may be stored, it simply must be
+ * revalidated, which is exactly what the ETag is for. `no-store` would forbid
+ * storing and so forbid the `304` this exists to enable.
+ */
+const CACHE_CONTROL = "no-cache";
+
+/**
+ * Answers a conditional GET from a {@link CachedResult}.
+ *
+ * A match returns a bodiless `304`. An `If-None-Match` that does not match, or
+ * a request that sent none, returns the body with the validator attached so
+ * the next poll can be the cheap one.
+ *
+ * `If-None-Match` may carry several validators or the `*` form, so the header
+ * is parsed rather than compared as one string.
+ */
+export function conditionalResponse<T>(
+  ifNoneMatch: string | null,
+  result: CachedResult<T>,
+  body: unknown,
+): Response {
+  if (matchesEtag(ifNoneMatch, result.etag)) {
+    return new Response(null, {
+      status: 304,
+      headers: { etag: result.etag, "cache-control": CACHE_CONTROL },
+    });
+  }
+  const response = Response.json(body);
+  response.headers.set("etag", result.etag);
+  response.headers.set("cache-control", CACHE_CONTROL);
+  return response;
+}
+
+/** True when an `If-None-Match` header names this validator. */
+export function matchesEtag(header: string | null, etag: string): boolean {
+  if (header === null) return false;
+  const trimmed = header.trim();
+  if (trimmed === "*") return true;
+  for (const part of trimmed.split(",")) {
+    // The weak prefix is stripped: a weak validator still names the same
+    // representation, and the client that sent it asked to be told if the
+    // current one matches.
+    const candidate = part.trim().replace(/^W\//, "");
+    if (candidate === etag) return true;
+  }
+  return false;
+}