@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/server/system/request-cache.ts

@@ -0,0 +1,139 @@
+// Per-request memoization: a domain query called several times within the same
+// HTTP request reads once. The cache lives on the H3 event context, so it is
+// scoped to the current request and discarded when the request ends — no
+// cross-request state, no staleness. Requires `experimental.asyncContext`.
+//
+// Caveat: the cache is held for the whole request, so a flow that reads, writes,
+// then reads again would see pre-write state. Every repository that memoizes a
+// read therefore evicts or revises it on write: the app sends a whole screen in
+// one document, and a mutation document can carry several writes in a row (the
+// book sheet corrects, then rates), each of which must see the one before.
+//
+// Shared in flight: the app opens on about ten requests at once, and each of
+// them used to scan the same library — some 230 documents a request, decoded ten
+// times over by the one instance serving them all. A read asked with
+// `shareInFlight` is shared by the requests asking the same key while it is in
+// flight, and forgotten the moment it answers: nothing is kept between requests.
+//
+// Sharing must not cost a reader their own writes. A request sent once a
+// mutation answered has to see it, as a read of its own would, but a read in
+// flight may have started before that mutation committed — on another instance,
+// where nothing tells. So a request joins only a read started after it arrived,
+// or less than `JOINABLE_BEFORE_ARRIVAL_MS` before: shorter than any round trip
+// from a phone, so the read started after anything the phone saw committed. On
+// this instance a write also forgets the read in flight under its key, and the
+// request that wrote never joins one: it reads on its own, as it always did.
+
+const JOINABLE_BEFORE_ARRIVAL_MS = 10
+
+type RequestContext = {
+  _queryCache?: Record<string, unknown>
+  _writtenKeys?: Set<string>
+  /** When this request first used the cache: no earlier than it arrived. */
+  _arrivedAt?: number
+}
+
+const contextOrUndefined = (): RequestContext | undefined => {
+  try {
+    return useEvent().context as RequestContext
+  } catch {
+    // No request context (e.g. migration scripts, tests).
+    return undefined
+  }
+}
+
+/** The reads in flight that concurrent requests share, by key. */
+const inFlight = new Map<string, { read: Promise<unknown>; startedAt: number }>()
+
+const sharedInFlight = <T>(key: string, read: () => Promise<T>, arrivedAt: number): Promise<T> => {
+  const pending = inFlight.get(key)
+  if (pending && pending.startedAt >= arrivedAt - JOINABLE_BEFORE_ARRIVAL_MS)
+    return pending.read as Promise<T>
+  const started = read().finally(() => {
+    if (inFlight.get(key)?.read === started) inFlight.delete(key)
+  })
+  inFlight.set(key, { read: started, startedAt: performance.now() })
+  return started
+}
+
+export const memoizedPerRequest = <T>(
+  key: string,
+  fn: () => T,
+  options: { shareInFlight?: boolean } = {},
+): T => {
+  const context = contextOrUndefined()
+  // No request context — run uncached.
+  if (!context) return fn()
+  context._arrivedAt ??= performance.now()
+  if (!context._queryCache) context._queryCache = {}
+  const cache = context._queryCache as Record<string, T>
+  if (!(key in cache))
+    cache[key] =
+      options.shareInFlight && !context._writtenKeys?.has(key)
+        ? (sharedInFlight(key, fn as () => Promise<unknown>, context._arrivedAt) as T)
+        : fn()
+  return cache[key]
+}
+
+/** A write under the key: the read in flight may hold what stood before it,
+ *  so no request joins it any more, and this one never joins one again. */
+const markWritten = (key: string) => {
+  inFlight.delete(key)
+  const context = contextOrUndefined()
+  if (!context) return
+  if (!context._writtenKeys) context._writtenKeys = new Set()
+  context._writtenKeys.add(key)
+}
+
+export const isInRequestCache = (key: string): boolean => {
+  try {
+    const event = useEvent()
+    return Boolean(
+      event.context._queryCache && key in (event.context._queryCache as Record<string, unknown>),
+    )
+  } catch {
+    return false
+  }
+}
+
+export const evictFromRequestCache = (key: string) => {
+  markWritten(key)
+  const context = contextOrUndefined()
+  if (context?._queryCache) delete context._queryCache[key]
+}
+
+/** Remember what a direct write just stored, so the rest of the request reads
+ *  it without asking Firestore again. Only for a write already applied: a
+ *  batched one is not visible until its commit, and must evict instead. */
+export const rememberInRequestCache = <T>(key: string, value: T) => {
+  evictFromRequestCache(key)
+  memoizedPerRequest(key, () => value)
+}
+
+/** Apply a write to a memoized value rather than dropping it, so the rest of the
+ *  request reads what was written without paying the read again. A no-op when
+ *  nothing is memoized under the key. */
+export const reviseInRequestCache = <T>(key: string, revise: (value: T) => T) => {
+  markWritten(key)
+  const cache = contextOrUndefined()?._queryCache as Record<string, T> | undefined
+  if (cache && key in cache) cache[key] = revise(cache[key])
+}
+
+/** Run `fn` with a cache of its own, dropped when it returns. For a request that
+ *  walks many accounts in turn — the nightly sync — which would otherwise hold
+ *  every library it passed over until the very end. */
+export const withRequestCacheScope = async <T>(fn: () => Promise<T>): Promise<T> => {
+  let event: ReturnType<typeof useEvent>
+  try {
+    event = useEvent()
+  } catch {
+    return fn()
+  }
+  const outer = event.context._queryCache
+  event.context._queryCache = {}
+  try {
+    return await fn()
+  } finally {
+    event.context._queryCache = outer
+  }
+}

package/templates/backend/server/system/request-cache.unit.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  evictFromRequestCache,
+  isInRequestCache,
+  memoizedPerRequest,
+  reviseInRequestCache,
+} from './request-cache'
+
+// The request cache reads the current H3 event via the auto-imported useEvent().
+// In unit tests there is no request, so we stub a fake event on the global.
+const withRequest = (context: Record<string, unknown> = {}) => {
+  ;(globalThis as unknown as { useEvent: () => unknown }).useEvent = () => ({ context })
+}
+
+describe('memoizedPerRequest', () => {
+  afterEach(() => {
+    delete (globalThis as unknown as { useEvent?: unknown }).useEvent
+  })
+
+  test('runs the factory once and reuses the value within a request', () => {
+    withRequest()
+    let calls = 0
+    const read = () => ++calls
+    expect(memoizedPerRequest('k', read)).toBe(1)
+    expect(memoizedPerRequest('k', read)).toBe(1)
+    expect(calls).toBe(1)
+  })
+
+  test('caches the promise so concurrent reads dedupe', async () => {
+    withRequest()
+    let calls = 0
+    const read = () => {
+      calls++
+      return Promise.resolve('value')
+    }
+    const [a, b] = await Promise.all([memoizedPerRequest('p', read), memoizedPerRequest('p', read)])
+    expect(a).toBe('value')
+    expect(b).toBe('value')
+    expect(calls).toBe(1)
+  })
+
+  test('different keys are cached independently', () => {
+    withRequest()
+    let calls = 0
+    memoizedPerRequest('a', () => ++calls)
+    memoizedPerRequest('b', () => ++calls)
+    expect(calls).toBe(2)
+  })
+
+  test('isInRequestCache and evictFromRequestCache track entries', () => {
+    withRequest()
+    memoizedPerRequest('k', () => 1)
+    expect(isInRequestCache('k')).toBe(true)
+    evictFromRequestCache('k')
+    expect(isInRequestCache('k')).toBe(false)
+  })
+
+  test('runs uncached when there is no request context', () => {
+    let calls = 0
+    memoizedPerRequest('k', () => ++calls)
+    memoizedPerRequest('k', () => ++calls)
+    expect(calls).toBe(2)
+    expect(isInRequestCache('k')).toBe(false)
+  })
+})
+
+describe('memoizedPerRequest shared in flight', () => {
+  // Each call runs as its own request, as the app's requests sent together do.
+  const requests = new AsyncLocalStorage<Record<string, unknown>>()
+  const inRequest = <T>(call: () => Promise<T>) => requests.run({}, call)
+
+  beforeEach(() => {
+    ;(globalThis as unknown as { useEvent: () => unknown }).useEvent = () => {
+      const context = requests.getStore()
+      if (!context) throw new Error('no request')
+      return { context }
+    }
+  })
+
+  afterEach(() => {
+    delete (globalThis as unknown as { useEvent?: unknown }).useEvent
+  })
+
+  /** A read that answers when `answer` is called, counting how often it ran. */
+  const pendingRead = () => {
+    const read = { calls: 0, answer: (_value: string) => {} }
+    const run = () => {
+      read.calls++
+      return new Promise<string>((resolve) => {
+        read.answer = resolve
+      })
+    }
+    return { read, run }
+  }
+
+  const sharing = { shareInFlight: true }
+
+  test('requests sent together share one read while it is in flight', async () => {
+    const { read, run } = pendingRead()
+    const first = inRequest(() => memoizedPerRequest('library', run, sharing))
+    const second = inRequest(() => memoizedPerRequest('library', run, sharing))
+    read.answer('shelf')
+    expect(await Promise.all([first, second])).toEqual(['shelf', 'shelf'])
+    expect(read.calls).toBe(1)
+  })
+
+  test('a read that answered is not kept for the next request', async () => {
+    let calls = 0
+    const run = async () => `shelf ${++calls}`
+    expect(await inRequest(() => memoizedPerRequest('library', run, sharing))).toBe('shelf 1')
+    expect(await inRequest(() => memoizedPerRequest('library', run, sharing))).toBe('shelf 2')
+  })
+
+  test('a request arriving well after a read started reads on its own', async () => {
+    const { read, run } = pendingRead()
+    const early = inRequest(() => memoizedPerRequest('library', run, sharing))
+    await Bun.sleep(30)
+    const late = inRequest(() => memoizedPerRequest('library', async () => 'its own', sharing))
+    read.answer('started early')
+    expect(await Promise.all([early, late])).toEqual(['started early', 'its own'])
+  })
+
+  test('a write forgets the read in flight for the requests after it', async () => {
+    const { read, run } = pendingRead()
+    const before = inRequest(() => memoizedPerRequest('library', run, sharing))
+    await inRequest(async () => evictFromRequestCache('library'))
+    const after = inRequest(() => memoizedPerRequest('library', async () => 'fresh', sharing))
+    read.answer('stale')
+    expect(await Promise.all([before, after])).toEqual(['stale', 'fresh'])
+  })
+
+  test('a request that wrote never joins a read started before its write', async () => {
+    const { read, run } = pendingRead()
+    const before = inRequest(() => memoizedPerRequest('library', run, sharing))
+    const writer = inRequest(async () => {
+      reviseInRequestCache('library', (shelf: string) => shelf)
+      return memoizedPerRequest('library', async () => 'after the write', sharing)
+    })
+    read.answer('before the write')
+    expect(await Promise.all([before, writer])).toEqual(['before the write', 'after the write'])
+  })
+
+  test('an evicted key is read again by that request on its own', async () => {
+    const { read, run } = pendingRead()
+    const other = inRequest(() => memoizedPerRequest('library', run, sharing))
+    const writer = inRequest(async () => {
+      evictFromRequestCache('library')
+      return memoizedPerRequest('library', async () => 'fresh', sharing)
+    })
+    read.answer('stale')
+    expect(await Promise.all([other, writer])).toEqual(['stale', 'fresh'])
+    expect(read.calls).toBe(1)
+  })
+
+  test('nothing is shared without a request context', async () => {
+    delete (globalThis as unknown as { useEvent?: unknown }).useEvent
+    let calls = 0
+    const run = async () => ++calls
+    await Promise.all([
+      memoizedPerRequest('library', run, sharing),
+      memoizedPerRequest('library', run, sharing),
+    ])
+    expect(calls).toBe(2)
+  })
+})

package/templates/backend/server/system/secret-box.ts

@@ -0,0 +1,49 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+
+/** Authenticated encryption for the few secrets {{APP_NAME}} has to keep on behalf of a
+ *  reader rather than about them — today, the Amazon device credentials an Audible
+ *  connection is made of.
+ *
+ *  A Firestore export is a plausible way for those to leak, and a leaked refresh
+ *  token plus device key is a standing grant on somebody's Amazon account. They
+ *  are therefore never written in the clear: the key lives in Secret Manager and
+ *  reaches the function as an environment variable, so reading the database is not
+ *  enough to use what it holds.
+ *
+ *  AES-256-GCM rather than CBC: the tag makes a tampered payload fail to open
+ *  instead of decrypting into garbage the caller then has to recognize. */
+
+const ALGORITHM = 'aes-256-gcm'
+const KEY_BYTES = 32
+const IV_BYTES = 12
+/** Versioned so a future key rotation can tell the two formats apart rather than
+ *  guessing from the field's shape. */
+const FORMAT = 'v1'
+
+export const encryptionKeyOf = (base64Key: string): Buffer => {
+  const key = Buffer.from(base64Key, 'base64')
+  if (key.length !== KEY_BYTES)
+    throw new Error(`encryption key must be ${KEY_BYTES} bytes, base64-encoded`)
+  return key
+}
+
+export const seal = (plaintext: string, key: Buffer): string => {
+  const iv = randomBytes(IV_BYTES)
+  const cipher = createCipheriv(ALGORITHM, key, iv)
+  const sealed = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  return [FORMAT, iv, cipher.getAuthTag(), sealed]
+    .map((part) => (typeof part === 'string' ? part : part.toString('base64url')))
+    .join('.')
+}
+
+export const unseal = (sealed: string, key: Buffer): string => {
+  const [format, iv, tag, payload] = sealed.split('.')
+  if (format !== FORMAT || !iv || !tag || !payload)
+    throw new Error('sealed value is not in the expected format')
+  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(iv, 'base64url'))
+  decipher.setAuthTag(Buffer.from(tag, 'base64url'))
+  return Buffer.concat([
+    decipher.update(Buffer.from(payload, 'base64url')),
+    decipher.final(),
+  ]).toString('utf8')
+}

package/templates/backend/server/system/secret-box.unit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test'
+import { randomBytes } from 'node:crypto'
+import { encryptionKeyOf, seal, unseal } from '~/system/secret-box'
+
+const key = randomBytes(32)
+
+describe('sealing a secret', () => {
+  test('reads back exactly what was sealed', () => {
+    const secret = JSON.stringify({ refreshToken: 'Atnr|…', serial: 'ABC123' })
+
+    expect(unseal(seal(secret, key), key)).toBe(secret)
+  })
+
+  // Same plaintext twice must not produce the same ciphertext, or a Firestore
+  // export would show at a glance which accounts share a value.
+  test('seals the same value differently every time', () => {
+    expect(seal('same', key)).not.toBe(seal('same', key))
+  })
+
+  test('refuses to open a payload that was tampered with', () => {
+    const sealed = seal('same', key)
+    const [format, iv, tag, payload] = sealed.split('.')
+
+    expect(() => unseal(`${format}.${iv}.${tag}.${payload}00`, key)).toThrow()
+  })
+
+  test('refuses to open with another key', () => {
+    expect(() => unseal(seal('same', key), randomBytes(32))).toThrow()
+  })
+
+  test('refuses a value that is not in the sealed format', () => {
+    expect(() => unseal('plain text', key)).toThrow('sealed value is not in the expected format')
+  })
+})
+
+describe('reading the key', () => {
+  test('accepts a base64 256-bit key', () => {
+    expect(encryptionKeyOf(randomBytes(32).toString('base64'))).toHaveLength(32)
+  })
+
+  test('refuses a key of the wrong length, rather than padding it', () => {
+    expect(() => encryptionKeyOf(randomBytes(16).toString('base64'))).toThrow(
+      'encryption key must be 32 bytes',
+    )
+  })
+})

package/templates/backend/server/test/bdd.ts

@@ -0,0 +1,12 @@
+// Static import only — `await import()` of this module hangs: the `then`
+// export makes the module namespace a thenable that never resolves.
+import { describe, test } from 'bun:test'
+
+export const feature = describe
+export const scenario = test
+
+export const given = (description: string) => console.log(`  Given ${description}`)
+export const when = (description: string) => console.log(`  When ${description}`)
+// biome-ignore lint/suspicious/noThenProperty: BDD DSL function, not a thenable
+export const then = (description: string) => console.log(`  Then ${description}`)
+export const and = (description: string) => console.log(`  And ${description}`)