tapimo 0.7.0 → 0.7.2

package/src/internal/EdgeCache.test.ts

@@ -179,6 +179,23 @@ describe('middleware', () => {
     expect(store.gets).toMatchInlineSnapshot(`1`)
   })
 
+  test('bypasses the cache when its route key cannot be generated', async () => {
+    const { app, store, downstreamCalls } = createApp({
+      key: () => {
+        throw new Error('invalid query')
+      },
+    })
+
+    const first = await app.request('/cached')
+    const second = await app.request('/cached')
+
+    expect(first.status).toMatchInlineSnapshot(`200`)
+    expect(second.status).toMatchInlineSnapshot(`200`)
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
   test('answers conditional requests from a cached ETag with 304', async () => {
     const { app } = createApp()
 
@@ -219,7 +236,7 @@ describe('middleware', () => {
 
   test('rechecks route eligibility before every cache lookup', async () => {
     let eligible = true
-    const { app, downstreamCalls, store } = createApp({ eligibility: () => eligible })
+    const { app, downstreamCalls, store } = createApp({ eligibility: [() => eligible] })
 
     await app.request('/cached')
     eligible = false
@@ -229,6 +246,19 @@ describe('middleware', () => {
     expect(store.gets).toBe(1)
     expect(store.size).toBe(1)
   })
+
+  test('requires every route eligibility predicate to permit caching', async () => {
+    const { app, downstreamCalls, store } = createApp({
+      eligibility: [() => true, () => false],
+    })
+
+    await app.request('/cached')
+    await app.request('/cached')
+
+    expect(downstreamCalls()).toBe(2)
+    expect(store.gets).toBe(0)
+    expect(store.size).toBe(0)
+  })
 })
 
 type Environment = { Variables: EdgeCache.Variables }
@@ -263,7 +293,8 @@ function memoryStore() {
 
 function createApp(
   options: {
-    eligibility?: ((c: Context<Environment>) => boolean) | undefined
+    eligibility?: readonly ((c: Context<Environment>) => boolean)[] | undefined
+    key?: ((c: Context<Environment>) => Promise<string> | string) | undefined
     store?: Store.Store | undefined
   } = {},
 ) {
@@ -281,10 +312,11 @@ function createApp(
   // routes do; unmarked routes must skip the lookup entirely.
   const cacheable_marked = EdgeCache.markCacheable(
     createMiddleware<Environment>(async (_c, next) => next()),
+    { key: options.key as (c: Context) => Promise<string> | string },
   )
-  const cacheable = options.eligibility
-    ? EdgeCache.setEligibility(cacheable_marked, options.eligibility)
-    : cacheable_marked
+  for (const predicate of options.eligibility ?? [])
+    EdgeCache.setEligibility(cacheable_marked, predicate)
+  const cacheable = cacheable_marked
   app.get('/cached', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     c.header('Age', '123')

package/src/internal/EdgeCache.ts

@@ -87,7 +87,13 @@ export function middleware<environment extends Env>(
       // Query credentials must reach auth and never enter cache keys.
       !new URL(c.req.url).searchParams.has('key') &&
       isCacheableRoute(c)
-    const key = eligible ? cacheKey(c.req.url) : undefined
+    const key = eligible
+      ? await routeCacheKey(c).catch(() => {
+          // Key generators may parse request input before route validation runs.
+          // Bypass caching so the validation middleware can return its response.
+          return undefined
+        })
+      : undefined
 
     // Honor the standard request `Cache-Control` directives so a caller can
     // refresh a stale entry on the colo serving them without any out-of-band
@@ -142,6 +148,7 @@ export function middleware<environment extends Env>(
 // pays the store lookup only when a matched handler carries it.
 const cacheableSymbol = Symbol('tempoApi.edgeCacheable')
 const eligibility = new WeakMap<object, (c: Context) => boolean>()
+const keys = new WeakMap<object, (c: Context) => Promise<string> | string>()
 
 /**
  * Marks a route handler/middleware as publishing an edge-cache policy, so
@@ -150,16 +157,28 @@ const eligibility = new WeakMap<object, (c: Context) => boolean>()
  */
 export function markCacheable<const handler extends (...args: never[]) => unknown>(
   handler: handler,
+  options: markCacheable.Options = {},
 ): handler {
+  if (options.key) keys.set(handler, options.key)
   return Object.assign(handler, { [cacheableSymbol]: true })
 }
 
-/** Adds a request eligibility check to a cacheable route handler. */
+export declare namespace markCacheable {
+  /** Options for marking a route as edge-cacheable. */
+  type Options = {
+    /** Cache key generator. Defaults to the request URL. */
+    key?: ((c: Context) => Promise<string> | string) | undefined
+  }
+}
+
+/** Adds a request eligibility check; every check must permit caching. */
 export function setEligibility<const handler extends (...args: never[]) => unknown>(
   handler: handler,
   predicate: (c: Context) => boolean,
 ): handler {
-  if (cacheableSymbol in handler) eligibility.set(handler, predicate)
+  const existing = eligibility.get(handler)
+  if (cacheableSymbol in handler)
+    eligibility.set(handler, existing ? (c) => existing(c) && predicate(c) : predicate)
   return handler
 }
 
@@ -174,6 +193,16 @@ function isCacheableRoute(c: Context): boolean {
   return cacheable
 }
 
+async function routeCacheKey(c: Context) {
+  let requestUrl = c.req.url
+  for (const route of matchedRoutes(c)) {
+    if (!(cacheableSymbol in route.handler)) continue
+    const key = keys.get(route.handler)
+    if (key) requestUrl = await key(c)
+  }
+  return cacheKey(requestUrl)
+}
+
 export declare namespace middleware {
   /** Options for the edge-cache middleware. */
   type Options = {
@@ -220,7 +249,7 @@ function serveHit(ifNoneMatch: string | undefined, value: string): Response {
   const { body, encoding, headers, status } = JSON.parse(value) as Stored
   const responseHeaders = new Headers(headers)
   const etag = responseHeaders.get('etag')
-  if (etag && ifNoneMatch && etagMatches(etag, ifNoneMatch)) {
+  if (Etag.matches(etag, ifNoneMatch)) {
     const notModified = new Headers()
     for (const name of ['Cache-Control', 'ETag', 'Vary']) {
       const header = responseHeaders.get(name)
@@ -269,9 +298,12 @@ function getWaitUntil(c: { executionCtx?: { waitUntil(promise: Promise<unknown>)
   }
 }
 
-function etagMatches(etag: string, ifNoneMatch: string) {
-  const strip = (tag: string) => tag.trim().replace(/^W\//, '')
-  return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag))
+namespace Etag {
+  export function matches(etag: string | null, ifNoneMatch: string | undefined) {
+    if (!etag || !ifNoneMatch) return false
+    const strip = (tag: string) => tag.trim().replace(/^W\//, '')
+    return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag))
+  }
 }
 
 /**

package/src/internal/Id.ts

@@ -22,3 +22,17 @@ export function generate(prefix: string): string {
 export function random(): string {
   return segment()
 }
+
+/**
+ * Generates a time-prefixed resource id (`{prefix}_{epoch ms}_{24 base62
+ * chars}`). The epoch-ms is zero-padded to 15 digits (headroom past the year
+ * 5138) so lexical id order is chronological, letting newest-first lists page
+ * by keyset on the id alone.
+ *
+ * @param prefix - The resource-type prefix (e.g. `wh`, `ftr`).
+ * @param now - The timestamp to embed.
+ * @returns The generated id.
+ */
+export function generateSortable(prefix: string, now: Date = new Date()): string {
+  return `${prefix}_${now.getTime().toString().padStart(15, '0')}_${random()}`
+}

package/src/internal/Idempotency.test.ts

@@ -0,0 +1,109 @@
+import { Hash, Hex } from 'ox'
+
+import * as Idempotency from './Idempotency.js'
+import * as Store from './Store.js'
+import * as Ttl from './Ttl.js'
+
+const identity = {
+  apiKeyId: 'key_test',
+  idempotencyKey: 'req_01j3j1k2l3m4n5p6q7r8s9t0u',
+  inputHash: `0x${'11'.repeat(32)}`,
+}
+
+function coordinator(namespace = 'test:v1') {
+  return Idempotency.create<{ id: string }>({
+    namespace,
+    pendingTtl: Ttl.minutes(1),
+    receiptTtl: Ttl.days(1),
+  })
+}
+
+describe('inputHash', () => {
+  test('binds semantic content instead of JSON property order', () => {
+    expect(Idempotency.inputHash({ a: 1, b: [{ d: 2, c: 3 }] })).toBe(
+      Idempotency.inputHash({ b: [{ c: 3, d: 2 }], a: 1 }),
+    )
+    expect(Idempotency.inputHash({ a: 1 })).not.toBe(Idempotency.inputHash({ a: 2 }))
+  })
+
+  test('rejects values JSON cannot represent', () => {
+    expect(() => Idempotency.inputHash({ callback: () => {} })).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Idempotency inputs must be JSON values.]`,
+    )
+    expect(() =>
+      Idempotency.inputHash({ values: [Number.NaN, Number.POSITIVE_INFINITY] }),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: Idempotency inputs must be JSON values.]`)
+  })
+})
+
+describe('create', () => {
+  test('claims, blocks parallel requests, and replays the completed response', async () => {
+    const state = Store.memory()
+    const requests = coordinator()
+
+    const claimed = await requests.claim({ identity, state })
+    expect(claimed.type).toBe('claimed')
+    if (claimed.type !== 'claimed') return
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+    await expect(
+      requests.claim({ identity: { ...identity, inputHash: `0x${'22'.repeat(32)}` }, state }),
+    ).resolves.toEqual({ type: 'mismatch' })
+
+    await requests.complete({ identity, response: { id: 'ftr_test' }, state, token: claimed.token })
+    await expect(requests.claim({ identity, state })).resolves.toEqual({
+      response: { id: 'ftr_test' },
+      type: 'replay',
+    })
+  })
+
+  test('fences completion and release by claim token', async () => {
+    const state = Store.memory()
+    const requests = coordinator()
+    const claimed = await requests.claim({ identity, state })
+    if (claimed.type !== 'claimed') throw new Error('Expected a claimed request.')
+
+    // A stale token can neither complete nor release the live claim.
+    await requests.complete({ identity, response: { id: 'stale' }, state, token: 'stale-token' })
+    await requests.release({ identity, state, token: 'stale-token' })
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+
+    await requests.release({ identity, state, token: claimed.token })
+    await expect(requests.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+  })
+
+  test('rejects responses JSON cannot represent before completing', async () => {
+    const state = Store.memory()
+    const requests = Idempotency.create<void>({
+      namespace: 'test:v1',
+      pendingTtl: Ttl.minutes(1),
+      receiptTtl: Ttl.days(1),
+    })
+    const claimed = await requests.claim({ identity, state })
+    if (claimed.type !== 'claimed') throw new Error('Expected a claimed request.')
+
+    await expect(
+      requests.complete({ identity, response: undefined, state, token: claimed.token }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Idempotency responses must be JSON values.]`,
+    )
+    await expect(requests.claim({ identity, state })).resolves.toEqual({ type: 'pending' })
+  })
+
+  test('isolates coordinators by namespace over one store', async () => {
+    const state = Store.memory()
+    const first = coordinator('first:v1')
+    const second = coordinator('second:v1')
+
+    await expect(first.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+    await expect(second.claim({ identity, state })).resolves.toMatchObject({ type: 'claimed' })
+  })
+
+  test('preserves the durable key format consumers already stored', async () => {
+    const state = Store.memory()
+    await coordinator('mpp:relay:v1').claim({ identity, state })
+    const digest = Hash.sha256(Hex.fromString(identity.idempotencyKey)).slice(2)
+    expect((await state.list()).keys.map((key) => key.name)).toEqual([
+      `mpp:relay:v1:${identity.apiKeyId}:${digest}`,
+    ])
+  })
+})

package/src/internal/Idempotency.ts

@@ -0,0 +1,237 @@
+import { Hash, Hex } from 'ox'
+
+import * as Store from './Store.js'
+
+/**
+ * API-level retry coordination for idempotent write endpoints, letting a
+ * caller recover a successful response after a transport timeout.
+ *
+ * A key moves from missing to pending to complete. Only the claim token may
+ * finish or release pending state, preventing an older request from
+ * overwriting a newer owner.
+ */
+
+/** Identity for one caller-supplied idempotent request. */
+export type Identity = {
+  /** API key that submitted the request. */
+  apiKeyId: string
+  /** Opaque caller-supplied idempotency key. */
+  idempotencyKey: string
+  /** Hash of the request content bound to this idempotency key. */
+  inputHash: string
+}
+
+/** Returns a stable digest without retaining request contents in durable state. */
+export function inputHash(input: unknown): string {
+  return Hash.sha256(Hex.fromString(canonicalJson(input)))
+}
+
+/** Creates an idempotency coordinator over one durable-store key namespace. */
+export function create<response>(options: create.Options) {
+  const { namespace, pendingTtl, receiptTtl } = options
+
+  function keyFor(identity: Identity) {
+    // Scope keys to the authenticated API key so different tenants can reuse
+    // the same client-generated value. Hashing keeps that opaque value out of
+    // durable-store key names and enumeration output.
+    const digest = Hash.sha256(Hex.fromString(identity.idempotencyKey)).slice(2)
+    return `${namespace}:${identity.apiKeyId}:${digest}`
+  }
+
+  /** Claims a request or returns its current outcome. */
+  async function claim(options: claim.Options): Promise<claim.Result<response>> {
+    const { identity, state } = options
+    const token = crypto.randomUUID()
+
+    return Store.change<claim.Result<response>>(
+      state,
+      keyFor(identity),
+      (current) => {
+        const currentRecord = record<response>(current)
+        // A completed request is the only cacheable terminal outcome. Failed
+        // attempts must be retried with the same input. Legacy records lack
+        // an input hash, so cannot be safely replayed.
+        if (currentRecord && currentRecord.inputHash !== identity.inputHash)
+          return { op: 'noop', result: { type: 'mismatch' } }
+        if (currentRecord?.type === 'complete')
+          return { op: 'noop', result: { response: currentRecord.response, type: 'replay' } }
+        // A parallel request must not settle the same caller operation while
+        // the first request still owns its pending claim.
+        if (currentRecord?.type === 'pending') return { op: 'noop', result: { type: 'pending' } }
+        return {
+          op: 'set',
+          result: { token, type: 'claimed' },
+          value: encode({ inputHash: identity.inputHash, token, type: 'pending' }),
+        }
+      },
+      { ttl: pendingTtl },
+    )
+  }
+
+  /** Persists a successful response for an owned request claim. */
+  async function complete(options: complete.Options<response>): Promise<void> {
+    const { identity, response, state, token } = options
+
+    await Store.change(
+      state,
+      keyFor(identity),
+      (current) => {
+        const currentRecord = record<response>(current)
+        // Claim tokens fence delayed requests: a request cannot complete a
+        // claim it no longer owns after expiry or a later retry.
+        if (
+          currentRecord?.type !== 'pending' ||
+          currentRecord.inputHash !== identity.inputHash ||
+          currentRecord.token !== token
+        )
+          return { op: 'noop', result: undefined }
+        canonicalJson(response, 'Idempotency responses must be JSON values.')
+        return {
+          op: 'set',
+          result: undefined,
+          value: encode({ inputHash: identity.inputHash, response, type: 'complete' }),
+        }
+      },
+      { ttl: receiptTtl },
+    )
+  }
+
+  /** Releases an owned retryable request claim. */
+  async function release(options: release.Options): Promise<void> {
+    const { identity, state, token } = options
+
+    await Store.change(state, keyFor(identity), (current) => {
+      const currentRecord = record<response>(current)
+      // Never delete a newer pending claim after this request has lost
+      // ownership through expiry and another caller has retried.
+      if (
+        currentRecord?.type !== 'pending' ||
+        currentRecord.inputHash !== identity.inputHash ||
+        currentRecord.token !== token
+      )
+        return { op: 'noop', result: undefined }
+      return { op: 'delete', result: undefined }
+    })
+  }
+
+  return { claim, complete, release }
+}
+
+export declare namespace create {
+  /** Coordinator configuration bound at creation. */
+  type Options = {
+    /** Durable-store key namespace (e.g. `mpp:relay:v1`). */
+    namespace: string
+    /** How long a pending claim blocks equivalent requests, in milliseconds. */
+    pendingTtl: number
+    /** How long a completed response replays, in milliseconds. */
+    receiptTtl: number
+  }
+}
+
+export declare namespace claim {
+  /** Dependencies for claiming one idempotency key. */
+  type Options = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+  }
+
+  /** Outcome from attempting to claim an idempotency key. */
+  type Result<response> =
+    | { token: string; type: 'claimed' }
+    | { type: 'mismatch' }
+    | { response: response; type: 'replay' }
+    | { type: 'pending' }
+}
+
+export declare namespace complete {
+  /** Dependencies for persisting one terminal response. */
+  type Options<response> = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Terminal successful response to replay. */
+    response: response
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+    /** Token returned by the successful claim. */
+    token: string
+  }
+}
+
+export declare namespace release {
+  /** Dependencies for releasing one idempotency claim. */
+  type Options = {
+    /** API-key-scoped idempotency identity. */
+    identity: Identity
+    /** Authoritative state with atomic compare-and-swap, normally a Durable Object. */
+    state: Store.State
+    /** Token returned by the successful claim. */
+    token: string
+  }
+}
+
+/** A completed request whose response may be replayed until expiry. */
+type CompleteRecord<response> = {
+  inputHash?: string
+  response: response
+  type: 'complete'
+}
+
+/** An in-flight request owned by the opaque claim token. */
+type PendingRecord = {
+  inputHash?: string
+  token: string
+  type: 'pending'
+}
+
+type ParsedRecord = {
+  inputHash?: unknown
+  response?: unknown
+  token?: unknown
+  type?: unknown
+}
+
+type JsonRecord = { [key: string]: unknown }
+
+function encode(record: CompleteRecord<unknown> | PendingRecord) {
+  return JSON.stringify(record)
+}
+
+function canonicalJson(
+  value: unknown,
+  errorMessage = 'Idempotency inputs must be JSON values.',
+): string {
+  if (value === null) return 'null'
+  if (typeof value === 'number' && !Number.isFinite(value)) throw new Error(errorMessage)
+  if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string')
+    return JSON.stringify(value)
+  if (Array.isArray(value))
+    return `[${value.map((item) => canonicalJson(item, errorMessage)).join(',')}]`
+  if (typeof value === 'object') {
+    const record = value as JsonRecord
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key], errorMessage)}`)
+      .join(',')}}`
+  }
+  throw new Error(errorMessage)
+}
+
+function record<response>(
+  value: null | string,
+): CompleteRecord<response> | PendingRecord | undefined {
+  if (value === null) return undefined
+
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!parsed || typeof parsed !== 'object') return undefined
+    const candidate = parsed as ParsedRecord
+    if (candidate.type === 'pending' && typeof candidate.token === 'string')
+      return candidate as PendingRecord
+    if (candidate.type === 'complete' && candidate.response !== undefined)
+      return candidate as CompleteRecord<response>
+  } catch {}
+  return undefined
+}

package/src/internal/Log.test-d.ts

@@ -1,21 +1,54 @@
-import type * as FundingQuotes from './FundingQuotes.js'
+import type * as FundingProvider from './funding/Provider.js'
 import type * as Log from './Log.js'
 
-test('bounds funding provider metric identifiers', () => {
-  const provider = null as never as FundingQuotes.ProviderId
+test('accepts deployment-supplied funding provider identifiers', () => {
+  const provider = null as never as FundingProvider.ProviderId
   const id: Log.FundingProviderAttempt['id'] = provider
-  const provider_roundTrip: FundingQuotes.ProviderId = id
+  const provider_roundTrip: FundingProvider.ProviderId = id
   void provider_roundTrip
 
   const attempt = {
     durationMs: 1,
     id: 'relay',
-    operation: 'quote/v2',
+    operation: 'getQuote',
     outcome: 'available',
   } satisfies Log.FundingProviderAttempt
   void attempt
 
-  // @ts-expect-error arbitrary provider names would create unbounded metric tags
-  const invalid: Log.FundingProviderAttempt['id'] = 'user-controlled-provider'
-  void invalid
+  const custom: Log.FundingProviderAttempt['id'] = 'custom-bridge'
+  void custom
+})
+
+test('bounds sponsorship diagnostics', () => {
+  const reasons = [
+    'api_key_forbidden',
+    'api_key_required',
+    'billing_past_due',
+    'billing_required',
+    'chain_id_unsupported',
+    'fee_token_unsupported',
+    'internal_error',
+    'production_api_key_required',
+    'spend_limit_exceeded',
+    'tx_fee_limit_exceeded',
+  ] as const satisfies readonly Log.SponsorshipReason[]
+  expectTypeOf<(typeof reasons)[number]>().toEqualTypeOf<Log.SponsorshipReason>()
+
+  const sponsorship = {
+    chainId: 4217,
+    method: 'eth_signRawTransaction',
+    outcome: 'rejected',
+    payloadHash: `0x${'aa'.repeat(32)}`,
+    reason: 'production_api_key_required',
+    rejections: 1,
+  } satisfies Log.Sponsorship
+  void sponsorship
+
+  // @ts-expect-error arbitrary method names would create unbounded log values
+  const method: Log.SponsorshipMethod = 'wallet_userControlled'
+  void method
+
+  // @ts-expect-error arbitrary reasons would create unbounded log values
+  const reason: Log.SponsorshipReason = 'user_controlled_reason'
+  void reason
 })