@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/server/system/app-support.ts

@@ -0,0 +1,17 @@
+/**
+ * Oldest iOS build the currently deployed GraphQL schema still supports.
+ *
+ * The build number is `CFBundleVersion`, set by CI to `git rev-list --count HEAD`
+ * at tag time, so it grows monotonically with every commit. Builds below this
+ * floor are shown a blocking "update required" screen by the app (see
+ * `GET /app-config` and `AppSupportGate.swift`).
+ *
+ * Raised only by the removal commit of the deprecation routine, to the value
+ * `bun run deprecations` proposes: a build that no longer asks for what is
+ * removed, on the App Store for two weeks. The Deploy workflow refuses a floor
+ * above the build on sale — see docs/api-evolution.md.
+ */
+export const MINIMUM_SUPPORTED_IOS_BUILD = 1
+
+/** Direct App Store link, opened by the update screen. */
+export const APP_STORE_URL = 'https://apps.apple.com/app/id{{APP_STORE_ID}}'

package/templates/backend/server/system/config/index.ts

@@ -0,0 +1,18 @@
+import { AdminToken, PublicBaseUrl, SentryDsn, SentryRelease } from '~/system/config/primitives'
+
+/** Every value the server reads from its environment, validated once. A new
+ *  variable is added here, in nitro.config.ts, in .env.example, in
+ *  infra/variables.tf and in the deploy workflow, in the same commit. */
+export const config = () => {
+  const runtimeConfig = useRuntimeConfig()
+  return {
+    adminToken: runtimeConfig.adminToken ? AdminToken(runtimeConfig.adminToken) : undefined,
+    sentryDsn: runtimeConfig.sentryDsn ? SentryDsn(runtimeConfig.sentryDsn) : undefined,
+    sentryRelease: runtimeConfig.sentryRelease
+      ? SentryRelease(runtimeConfig.sentryRelease)
+      : undefined,
+    devUserId: runtimeConfig.devUserId || undefined,
+    gcpProjectId: runtimeConfig.firebaseProjectId || undefined,
+    publicBaseUrl: PublicBaseUrl(runtimeConfig.publicBaseUrl),
+  }
+}

package/templates/backend/server/system/config/primitives.ts

@@ -0,0 +1,20 @@
+import { make } from 'ts-brand'
+import { z } from 'zod'
+import type {
+  AdminToken as AdminTokenType,
+  PublicBaseUrl as PublicBaseUrlType,
+  SentryDsn as SentryDsnType,
+  SentryRelease as SentryReleaseType,
+} from '~/system/config/types'
+
+export const AdminToken = (value: unknown) => make<AdminTokenType>()(z.string().min(1).parse(value))
+
+// Any non-empty string: Sentry.init validates the DSN itself (warns and disables
+// on a bad one) rather than throwing, so a malformed value cannot take config() down.
+export const SentryDsn = (value: unknown) => make<SentryDsnType>()(z.string().min(1).parse(value))
+
+export const SentryRelease = (value: unknown) =>
+  make<SentryReleaseType>()(z.string().min(1).parse(value))
+
+export const PublicBaseUrl = (value: unknown) =>
+  make<PublicBaseUrlType>()(z.string().url().parse(value))

package/templates/backend/server/system/config/primitives.unit.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'bun:test'
+import { AdminToken, PublicBaseUrl } from '~/system/config/primitives'
+
+describe('config primitives', () => {
+  test('an admin token is any non-empty string', () => {
+    expect(AdminToken('x') as string).toBe('x')
+    expect(() => AdminToken('')).toThrow()
+  })
+  test('the public base url must be a url', () => {
+    expect(() => PublicBaseUrl('localhost')).toThrow()
+    expect(PublicBaseUrl('http://127.0.0.1:3000') as string).toBe('http://127.0.0.1:3000')
+  })
+})

package/templates/backend/server/system/config/types.ts

@@ -0,0 +1,8 @@
+import type { Brand } from 'ts-brand'
+
+export type AdminToken = Brand<string, 'AdminToken'>
+export type SentryDsn = Brand<string, 'SentryDsn'>
+/** The deployed revision, as `<app>-node@<git sha>`: ties errors to source maps. */
+export type SentryRelease = Brand<string, 'SentryRelease'>
+/** Development only: the origin this server is reachable at from the simulator. */
+export type PublicBaseUrl = Brand<string, 'PublicBaseUrl'>

package/templates/backend/server/system/firebase.ts

@@ -0,0 +1,19 @@
+import { getApps, initializeApp } from 'firebase-admin/app'
+import {
+  DocumentReference,
+  Firestore,
+  getFirestore,
+  Query,
+  Transaction,
+} from 'firebase-admin/firestore'
+import { meterFirestoreReads } from '~/system/read-meter'
+
+if (getApps().length === 0) initializeApp()
+
+export const db = () => getFirestore()
+
+// The client exports `AggregateQuery` as a type only; its class is taken from
+// an instance, which `count()` builds without any network call.
+const AggregateQuery = Object.getPrototypeOf(db().collection('_').count()).constructor
+
+meterFirestoreReads({ Firestore, Query, AggregateQuery, Transaction, DocumentReference })

package/templates/backend/server/system/identity.ts

@@ -0,0 +1,18 @@
+import { getAuth } from 'firebase-admin/auth'
+
+// The auth identity provider (Firebase Auth), kept separate from the Firestore
+// module so the "Firestore only through repositories" boundary stays about data.
+// getAuth() resolves the default app that ~/system/firebase initializes; the user
+// repository imports both, so the app is always initialized before this runs.
+
+// Delete the Firebase Auth user — the identity behind an account deletion.
+// Idempotent: an already-absent user (a retried deletion) counts as done rather
+// than an error, so the account wipe can be replayed safely after a partial failure.
+export const deleteAuthUser = async (uid: string): Promise<void> => {
+  try {
+    await getAuth().deleteUser(uid)
+  } catch (error) {
+    if ((error as { code?: string }).code === 'auth/user-not-found') return
+    throw error
+  }
+}

package/templates/backend/server/system/logger.ts

@@ -0,0 +1,119 @@
+import * as Sentry from '@sentry/node'
+import { consola } from 'consola'
+
+/** What a log line carries besides its message: the error that caused it, and
+ *  whatever identifies the case — a reader, an ISBN, a saga. Kept apart from
+ *  the message so the message stays the same from one case to the next, and
+ *  Sentry gathers every occurrence of a problem into one issue. */
+export type LogContext = { error?: unknown } & Record<string, unknown>
+
+export type Report = (
+  level: 'warning' | 'error',
+  tag: string,
+  message: string,
+  context: LogContext,
+) => void
+
+let reportedSinceFlush = false
+
+/** Every warning and error goes to Sentry, not only to the logs: a problem the
+ *  code catches and recovers from — a model call that failed, a cover lookup
+ *  that answered 500, a dashboard left stale — is still a problem, and one
+ *  nobody reads the logs for. An error the line carries is reported with its
+ *  stack; a line with none is reported as a message. An error naming its own
+ *  `fingerprint` is one problem wherever it is caught, and is grouped so. A no-op until the Sentry
+ *  plugin initialized the SDK, so a local run reports nothing. */
+const sentryReport: Report = (level, tag, message, { error, ...extra }) => {
+  reportedSinceFlush = true
+  Sentry.withScope((scope) => {
+    scope.setLevel(level)
+    scope.setTag('logger', tag)
+    scope.setExtras({ ...extra, message })
+    const fingerprint = (error as { fingerprint?: unknown } | undefined)?.fingerprint
+    if (Array.isArray(fingerprint)) scope.setFingerprint(fingerprint)
+    if (error instanceof Error) Sentry.captureException(error)
+    else {
+      if (error !== undefined) scope.setExtra('error', String(error))
+      Sentry.captureMessage(`[${tag}] ${message}`)
+    }
+  })
+}
+
+/** Sends what the logger reported before the instance loses its CPU: Cloud
+ *  Functions throttles it once the response is out, and a queued event would
+ *  then never leave. Waits on nothing when nothing was reported. */
+export const flushReports = async (): Promise<void> => {
+  if (!reportedSinceFlush) return
+  reportedSinceFlush = false
+  await Sentry.flush(2000)
+}
+
+export type Severity = 'INFO' | 'WARNING' | 'ERROR'
+
+const serializedError = (error: unknown) =>
+  error instanceof Error
+    ? { name: error.name, message: error.message, stack: error.stack }
+    : String(error)
+
+/** One log as the single JSON line Cloud Logging parses into a structured
+ *  entry: `severity` makes `severity>=WARNING` work, the context keys land
+ *  under `jsonPayload` where they can be filtered and summed, and the stack
+ *  travels inside the one entry instead of being split into one per line. */
+export const structuredLine = (
+  severity: Severity,
+  tag: string,
+  message: string,
+  { error, ...context }: LogContext = {},
+): string => {
+  const entry = {
+    ...context,
+    ...(error === undefined ? {} : { error: serializedError(error) }),
+    severity,
+    message: `[${tag}] ${message}`,
+    tag,
+  }
+  try {
+    return JSON.stringify(entry)
+  } catch {
+    // A context that cannot be serialized (a cycle, a bigint) still logs its message.
+    return JSON.stringify({ severity, message: entry.message, tag })
+  }
+}
+
+type Write = (severity: Severity, tag: string, message: string, context?: LogContext) => void
+
+const prettyWrite = (tag: string): Write => {
+  const logger = consola.withTag(tag)
+  return (severity, _tag, message, context) => {
+    const rest = context === undefined ? [] : [context]
+    if (severity === 'INFO') logger.info(message, ...rest)
+    else if (severity === 'WARNING') logger.warn(message, ...rest)
+    else logger.error(message, ...rest)
+  }
+}
+
+const structuredWrite: Write = (severity, tag, message, context) => {
+  process.stdout.write(`${structuredLine(severity, tag, message, context)}\n`)
+}
+
+/** A built bundle writes JSON lines for Cloud Logging; a dev server keeps
+ *  consola's pretty output. `import.meta.dev` is compiled to `false` in a
+ *  build and left undefined under `bun test`, which keeps the pretty output. */
+const writeFor = (tag: string): Write =>
+  import.meta.dev === false ? structuredWrite : prettyWrite(tag)
+
+export const createLogger = (
+  tag: string,
+  report: Report = sentryReport,
+  write: Write = writeFor(tag),
+) => ({
+  info: (message: string, context?: LogContext) => write('INFO', tag, message, context),
+  warn: (message: string, context?: LogContext) => {
+    write('WARNING', tag, message, context)
+    report('warning', tag, message, context ?? {})
+  },
+  error: (message: string, context?: LogContext) => {
+    write('ERROR', tag, message, context)
+    report('error', tag, message, context ?? {})
+  },
+})

package/templates/backend/server/system/logger.unit.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'bun:test'
+import { createLogger, type LogContext, structuredLine } from '~/system/logger'
+
+const recorded = () => {
+  const reports: { level: string; tag: string; message: string; context: LogContext }[] = []
+  const logger = createLogger(
+    'scan',
+    (level, tag, message, context) => reports.push({ level, tag, message, context }),
+    () => {},
+  )
+  return { logger, reports }
+}
+
+describe('the logger', () => {
+  // A problem the code recovers from is still one somebody has to hear about.
+  test('reports every warning and error, with its error and context', () => {
+    const { logger, reports } = recorded()
+    const cause = new Error('Gemini returned no content')
+
+    logger.warn('catalogue failed', { error: cause, series: 'Dune' })
+    logger.error('scan failed')
+
+    expect(reports).toEqual([
+      {
+        level: 'warning',
+        tag: 'scan',
+        message: 'catalogue failed',
+        context: { error: cause, series: 'Dune' },
+      },
+      { level: 'error', tag: 'scan', message: 'scan failed', context: {} },
+    ])
+  })
+
+  test('reports nothing for information', () => {
+    const { logger, reports } = recorded()
+
+    logger.info('usage recorded', { tokens: 12 })
+
+    expect(reports).toEqual([])
+  })
+})
+
+describe('a structured log line', () => {
+  // Cloud Logging reads one JSON object per line: severity drives `severity>=WARNING`,
+  // and every context key becomes a `jsonPayload` field.
+  test('carries the severity, the tagged message and the context as fields', () => {
+    const line = structuredLine('INFO', 'scan', 'gemini usage', { step: 'cover', searches: 4 })
+
+    expect(line).not.toContain('\n')
+    expect(JSON.parse(line)).toEqual({
+      step: 'cover',
+      searches: 4,
+      severity: 'INFO',
+      message: '[scan] gemini usage',
+      tag: 'scan',
+    })
+  })
+
+  test('keeps the error and its stack in the one entry', () => {
+    const cause = new TypeError('fetch failed')
+
+    const entry = JSON.parse(structuredLine('ERROR', 'scan', 'scan failed', { error: cause }))
+
+    expect(entry.severity).toBe('ERROR')
+    expect(entry.error).toEqual({ name: 'TypeError', message: 'fetch failed', stack: cause.stack })
+  })
+
+  test('writes an error that is not an Error as text', () => {
+    const entry = JSON.parse(structuredLine('WARNING', 'scan', 'odd', { error: 404 }))
+
+    expect(entry.error).toBe('404')
+  })
+
+  test('never lets the context overwrite the severity or the message', () => {
+    const entry = JSON.parse(
+      structuredLine('WARNING', 'scan', 'odd', { severity: 'DEBUG', message: 'other' }),
+    )
+
+    expect(entry).toMatchObject({ severity: 'WARNING', message: '[scan] odd' })
+  })
+
+  test('still logs the message when the context cannot be serialized', () => {
+    const cycle: Record<string, unknown> = {}
+    cycle.self = cycle
+
+    expect(JSON.parse(structuredLine('INFO', 'scan', 'loop', { cycle }))).toEqual({
+      severity: 'INFO',
+      message: '[scan] loop',
+      tag: 'scan',
+    })
+  })
+})
+
+describe('the logger writing', () => {
+  test('writes every level with its severity', () => {
+    const written: string[] = []
+    const logger = createLogger(
+      'scan',
+      () => {},
+      (severity, tag, message) => written.push(`${severity} ${tag} ${message}`),
+    )
+
+    logger.info('a')
+    logger.warn('b')
+    logger.error('c')
+
+    expect(written).toEqual(['INFO scan a', 'WARNING scan b', 'ERROR scan c'])
+  })
+})

package/templates/backend/server/system/migration/migrations/index.ts

@@ -0,0 +1,6 @@
+import type { Migration } from '~/system/migration/types'
+
+// Forward-only, sequential, no rollback. Adding a new optional field or a new
+// collection needs no migration; renaming, restructuring or removing stale data
+// does. Each migration lives beside its .int.test.ts and is listed here in order.
+export const migrations: Migration[] = []

package/templates/backend/server/system/migration/primitives.ts

@@ -0,0 +1,18 @@
+import { make } from 'ts-brand'
+import { z } from 'zod'
+import type {
+  MigrationName as MigrationNameType,
+  MigrationVersion as MigrationVersionType,
+} from '~/system/migration/types'
+
+export const MigrationVersion = (value: unknown) => {
+  const validatedValue = z
+    .preprocess((v) => (typeof v === 'string' ? Number(v) : v), z.number().int().min(0))
+    .parse(value)
+  return make<MigrationVersionType>()(validatedValue)
+}
+
+export const MigrationName = (value: unknown) => {
+  const validatedValue = z.string().min(1).parse(value)
+  return make<MigrationNameType>()(validatedValue)
+}

package/templates/backend/server/system/migration/runner.ts

@@ -0,0 +1,52 @@
+import { sortBy } from 'lodash-es'
+import { db } from '~/system/firebase'
+import { createLogger } from '~/system/logger'
+import { MigrationVersion } from '~/system/migration/primitives'
+import type { Migration, MigrationMeta } from '~/system/migration/types'
+
+const log = createLogger('migration')
+
+const META_COLLECTION = 'migration-meta'
+const META_DOC_ID = 'state'
+
+export const runMigrations = async (migrations: Migration[]) => {
+  const firestore = db()
+  const metaRef = firestore.collection(META_COLLECTION).doc(META_DOC_ID)
+
+  const snap = await metaRef.get()
+  const current = (snap.data() as MigrationMeta | undefined) ?? {
+    version: MigrationVersion(0),
+    appliedAt: new Date(0),
+  }
+  const fromVersion = current.version
+
+  const pending = sortBy(
+    migrations.filter((m) => m.version > fromVersion),
+    (m) => m.version,
+  )
+  if (pending.length === 0) return { outcome: 'up-to-date' as const }
+
+  for (const migration of pending) {
+    try {
+      const result = await migration.migrate({ db: firestore })
+      if (!result.ok)
+        return { outcome: 'failed' as const, version: migration.version, error: result.error }
+      await metaRef.set({ version: migration.version, appliedAt: new Date() })
+      // Only output of the runner: visible in Cloud Logging (CI reads the HTTP
+      // response of POST /admin/migrate instead).
+      log.info(
+        `Applied v${migration.version} "${migration.name}" (${result.transformed} transformed)`,
+      )
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return { outcome: 'failed' as const, version: migration.version, error: message }
+    }
+  }
+  const lastVersion = pending[pending.length - 1].version
+  return {
+    outcome: 'migrated' as const,
+    from: fromVersion,
+    to: lastVersion,
+    applied: pending.length,
+  }
+}

package/templates/backend/server/system/migration/types.ts

@@ -0,0 +1,16 @@
+import type { Firestore } from 'firebase-admin/firestore'
+import type { Brand } from 'ts-brand'
+
+export type MigrationVersion = Brand<number, 'MigrationVersion'>
+export type MigrationName = Brand<string, 'MigrationName'>
+
+export type MigrationContext = { db: Firestore }
+
+export type Migration = {
+  version: MigrationVersion
+  name: MigrationName
+  migrate: (ctx: MigrationContext) => Promise<MigrationResult>
+}
+
+export type MigrationMeta = { version: MigrationVersion; appliedAt: Date }
+export type MigrationResult = { ok: true; transformed: number } | { ok: false; error: string }

package/templates/backend/server/system/read-meter.ts

@@ -0,0 +1,100 @@
+// Per-request count of the Firestore reads a request made, so a slow screen can
+// be told apart from an expensive one. The meter lives on the H3 event context,
+// like the request cache, so the requests an instance serves at once never add
+// to each other's count. Requires `experimental.asyncContext`.
+//
+// Firestore has no read hook, so the count is taken by wrapping the client's
+// public read methods once, at startup. Every read of the app goes through one
+// of them: `DocumentReference.get()` is itself a `Firestore.getAll()` of one,
+// and a transaction reads through its own methods, never through those.
+
+export type ReadMeter = {
+  /** Documents fetched by reference: `get()`, `getAll()`, a transaction's read. */
+  docReads: number
+  /** Query round-trips, aggregations included. */
+  queryReads: number
+  /** Documents the queries returned — with `docReads`, what Firestore bills. */
+  queryDocs: number
+}
+
+const currentMeter = (): ReadMeter | undefined => {
+  try {
+    return useEvent().context._readMeter as ReadMeter | undefined
+  } catch {
+    // No request context (e.g. migration scripts, tests) — nothing to count into.
+    return undefined
+  }
+}
+
+/** Start counting the reads of the current request, from zero. Returns the
+ *  meter, which keeps counting until the request ends. */
+export const startReadMeter = (context: Record<string, unknown>): ReadMeter => {
+  const meter: ReadMeter = { docReads: 0, queryReads: 0, queryDocs: 0 }
+  context._readMeter = meter
+  return meter
+}
+
+type Read = (this: unknown, ...args: unknown[]) => Promise<unknown>
+type Readable = { prototype: object }
+
+/** What the wrapped methods read, told from their arguments and their answer. */
+type Tally = (meter: ReadMeter, args: unknown[], result: unknown) => void
+
+const sizeOf = (result: unknown) => (result as { size?: number } | undefined)?.size ?? 0
+
+const byReference: Tally = (meter, args) => {
+  // `getAll` takes the references, then optionally a `{ fieldMask }`.
+  meter.docReads += args.filter((arg) => (arg as { path?: unknown })?.path !== undefined).length
+}
+
+const byQuery: Tally = (meter, _args, result) => {
+  meter.queryReads += 1
+  meter.queryDocs += sizeOf(result)
+}
+
+const wrapped = Symbol('readMeter')
+
+const meter = (type: Readable, method: string, tally: Tally) => {
+  const prototype = type.prototype as Record<string, Read> & { [wrapped]?: Set<string> }
+  const read = prototype[method]
+  if (typeof read !== 'function') throw new Error(`Firestore has no ${method} to meter`)
+  if (!Object.hasOwn(prototype, wrapped)) prototype[wrapped] = new Set()
+  if (prototype[wrapped]?.has(method)) return
+  prototype[wrapped]?.add(method)
+  prototype[method] = function (this: unknown, ...args: unknown[]) {
+    // Taken before the read starts: the request context is certain here.
+    const current = currentMeter()
+    const pending = read.apply(this, args)
+    if (!current) return pending
+    return pending.then((result) => {
+      tally(current, args, result)
+      return result
+    })
+  }
+}
+
+/** The Firestore client classes whose reads are metered. */
+export type FirestoreClasses = {
+  Firestore: Readable
+  Query: Readable
+  AggregateQuery: Readable
+  Transaction: Readable
+  DocumentReference: Readable
+}
+
+/** Wrap the client's read methods so each read adds to the current request's
+ *  meter. Idempotent: a second call wraps nothing again. */
+export const meterFirestoreReads = (classes: FirestoreClasses) => {
+  const { Firestore, Query, AggregateQuery, Transaction, DocumentReference } = classes
+  meter(Firestore, 'getAll', byReference)
+  meter(Query, 'get', byQuery)
+  meter(AggregateQuery, 'get', (current) => {
+    current.queryReads += 1
+  })
+  meter(Transaction, 'getAll', byReference)
+  meter(Transaction, 'get', (current, [target], result) => {
+    if (target instanceof (DocumentReference as unknown as new () => object)) current.docReads += 1
+    else if (target instanceof (Query as unknown as new () => object)) byQuery(current, [], result)
+    else current.queryReads += 1
+  })
+}

package/templates/backend/server/system/read-meter.unit.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { meterFirestoreReads, startReadMeter } from './read-meter'
+
+// Stand-ins for the Firestore client classes: the meter wraps their prototypes
+// exactly as it wraps the real ones.
+class DocumentReference {
+  constructor(readonly path: string) {}
+}
+class Query {
+  constructor(readonly size: number) {}
+  async get() {
+    return { size: this.size }
+  }
+}
+class AggregateQuery {
+  async get() {
+    return { data: () => ({ count: 12 }) }
+  }
+}
+class Firestore {
+  async getAll(...refs: unknown[]) {
+    return refs
+  }
+}
+class Transaction {
+  async get(target: unknown) {
+    return target instanceof Query ? { size: target.size } : { exists: true }
+  }
+  async getAll(...refs: unknown[]) {
+    return refs
+  }
+}
+
+meterFirestoreReads({ Firestore, Query, AggregateQuery, Transaction, DocumentReference })
+// A second call wraps nothing again, or every read would count twice.
+meterFirestoreReads({ Firestore, Query, AggregateQuery, Transaction, DocumentReference })
+
+// The meter reads the current H3 event via the auto-imported useEvent().
+const inRequest = (context: Record<string, unknown>) => {
+  ;(globalThis as unknown as { useEvent: () => unknown }).useEvent = () => ({ context })
+}
+
+describe('meterFirestoreReads', () => {
+  afterEach(() => {
+    delete (globalThis as unknown as { useEvent?: unknown }).useEvent
+  })
+
+  test('counts documents read by reference and the documents queries return', async () => {
+    const context = {}
+    const meter = startReadMeter(context)
+    inRequest(context)
+
+    await new Firestore().getAll(new DocumentReference('a/1'), new DocumentReference('a/2'), {
+      fieldMask: ['title'],
+    })
+    await new Query(7).get()
+    await new Query(0).get()
+    await new AggregateQuery().get()
+
+    expect(meter).toEqual({ docReads: 2, queryReads: 3, queryDocs: 7 })
+  })
+
+  test('counts a transaction reading a document, a query and a batch', async () => {
+    const context = {}
+    const meter = startReadMeter(context)
+    inRequest(context)
+    const tx = new Transaction()
+
+    await tx.get(new DocumentReference('a/1'))
+    await tx.get(new Query(4))
+    await tx.getAll(new DocumentReference('a/2'), new DocumentReference('a/3'))
+
+    expect(meter).toEqual({ docReads: 3, queryReads: 1, queryDocs: 4 })
+  })
+
+  test('keeps concurrent requests apart', async () => {
+    const first = {}
+    const second = {}
+    const firstMeter = startReadMeter(first)
+    const secondMeter = startReadMeter(second)
+
+    // Each read is attributed to the request it started in, even when the two
+    // interleave and finish in the other order.
+    inRequest(first)
+    const slow = new Query(5).get()
+    inRequest(second)
+    const fast = new Firestore().getAll(new DocumentReference('a/1'))
+    await Promise.all([fast, slow])
+
+    expect(firstMeter).toEqual({ docReads: 0, queryReads: 1, queryDocs: 5 })
+    expect(secondMeter).toEqual({ docReads: 1, queryReads: 0, queryDocs: 0 })
+  })
+
+  test('reads outside a request still answer, counted nowhere', async () => {
+    expect(await new Query(3).get()).toEqual({ size: 3 })
+  })
+})