tapimo 0.14.0 → 0.15.1

package/src/internal/Mpp.ts

@@ -14,6 +14,9 @@ const attributionTag = '0xef1ed712'
 /** The live MPP service directory endpoint. */
 const directoryUrl = 'https://mpp.dev/api/services'
 
+/** Maximum duration for an MPP directory cache read or cache-miss flight. */
+const directoryTimeout = 1_000
+
 /**
  * Whether a `TransferWithMemo` memo is an MPP attribution memo: a full 32-byte
  * value prefixed with the {@link attributionTag}.
@@ -83,32 +86,26 @@ export async function fingerprintMap(
 ): Promise<Record<string, string>> {
   const { store, ttl = Ttl.minutes(10), url = directoryUrl } = options
   return Store.memoize(
-    async () => {
-      const controller = new AbortController()
-      const timeout = setTimeout(() => controller.abort(), 1_000)
-      try {
-        const response = await fetch(url, {
-          headers: { accept: 'application/json' },
-          signal: controller.signal,
-        })
-        if (!response.ok) throw new UpstreamError(response.status)
-        const data = (await response.json()) as fingerprintMap.Directory
-        const map: Record<string, string> = {}
-        for (const service of data.services) {
-          // A service without an explicit realm (or the shared default realm)
-          // derives its realm from its id under the canonical MPP domain.
-          const realm =
-            service.realm && service.realm !== 'mpp.tempo.xyz'
-              ? service.realm
-              : `${service.id}.mpp.tempo.xyz`
-          map[fingerprintForRealm(realm)] = service.name
-        }
-        return map
-      } finally {
-        clearTimeout(timeout)
+    async (signal) => {
+      const response = await fetch(url, {
+        headers: { accept: 'application/json' },
+        ...(signal ? { signal } : {}),
+      })
+      if (!response.ok) throw new UpstreamError(response.status)
+      const data = (await response.json()) as fingerprintMap.Directory
+      const map: Record<string, string> = {}
+      for (const service of data.services) {
+        // A service without an explicit realm (or the shared default realm)
+        // derives its realm from its id under the canonical MPP domain.
+        const realm =
+          service.realm && service.realm !== 'mpp.tempo.xyz'
+            ? service.realm
+            : `${service.id}.mpp.tempo.xyz`
+        map[fingerprintForRealm(realm)] = service.name
       }
+      return map
     },
-    { key: 'mpp-services:v1', store, ttl },
+    { flightTimeout: directoryTimeout, key: 'mpp-services:v1', store, ttl },
   )
 }
 

package/src/internal/OpenApi.ts

@@ -3,6 +3,7 @@ import type { HasRequiredKeys } from 'hono/utils/types'
 import {
   describeRoute as core_describeRoute,
   type DescribeRouteOptions,
+  type HandlerUniqueProperty,
   resolver,
   type ResponsesWithResolver,
   uniqueSymbol,
@@ -22,7 +23,7 @@ import * as Schema from './Schema.js'
  * registered `examples` back onto the node's JSON Schema, so every parameter
  * surfaces its example regardless of the underlying schema shape.
  */
-function recoverExamples(ctx: { jsonSchema: { examples?: unknown }; zodSchema: unknown }) {
+export function recoverExamples(ctx: { jsonSchema: { examples?: unknown }; zodSchema: unknown }) {
   if (ctx.jsonSchema.examples !== undefined) return
   const meta = z.globalRegistry.get(ctx.zodSchema as never) as { examples?: unknown } | undefined
   if (meta?.examples === undefined) return
@@ -87,6 +88,24 @@ export function describeRoute(spec: DescribeRouteOptions): MiddlewareHandler {
   return handler
 }
 
+/** Documents a JSON request body without parsing or changing the request at runtime. */
+export function documentJsonRequest<const schema extends z.ZodMiniType>(
+  schema: schema,
+): MiddlewareHandler<Env, string, validate.Input<'json', schema>> {
+  const documented = validator('json', schema, undefined, schemaOptions)
+  const metadata = (documented as typeof documented & { [uniqueSymbol]: HandlerUniqueProperty })[
+    uniqueSymbol
+  ]
+  const middleware: MiddlewareHandler<Env, string, validate.Input<'json', schema>> = async (
+    _c,
+    next,
+  ) => next()
+  Object.defineProperty(middleware, uniqueSymbol, {
+    get: () => metadata,
+  })
+  return middleware
+}
+
 /** Emits a named OpenAPI component and uses its `$ref` wherever the schema appears. */
 export function component<const schema extends z.ZodMiniType>(
   schema: schema,
@@ -148,6 +167,7 @@ export const errorCodes = {
   500: ['internal_error'],
   501: ['billing_unconfigured'],
   502: ['upstream_error'],
+  503: ['service_unavailable'],
   504: ['request_timeout'],
 } as const satisfies Record<number, readonly [string, ...string[]]>
 
@@ -221,6 +241,7 @@ const standardErrorNames = {
   500: 'InternalError',
   501: 'NotImplementedError',
   502: 'UpstreamError',
+  503: 'ServiceUnavailableError',
   504: 'RequestTimeoutError',
 } as const satisfies Record<keyof typeof errorCodes, string>
 
@@ -247,20 +268,25 @@ function errorName(status: number, codes: readonly string[]) {
   return name
 }
 
-function errorSchema(status: number, codes: readonly [string, ...string[]] | undefined) {
+function errorSchema(
+  status: number,
+  codes: readonly [string, ...string[]] | undefined,
+  name?: string,
+) {
   const defaults = errorCodes[status as keyof typeof errorCodes]
   if (!codes && !defaults) {
-    const cached = errorSchemas.get('*')
+    const key = name ? `${name}\0*` : '*'
+    const cached = errorSchemas.get(key)
     if (cached) return cached
-    const schema = component(Schema.errorResponse(), 'ErrorResponse')
-    errorSchemas.set('*', schema)
+    const schema = component(Schema.errorResponse(), name ?? 'ErrorResponse')
+    errorSchemas.set(key, schema)
     return schema
   }
   const normalized = [...(codes ?? defaults ?? [])].sort() as [string, ...string[]]
-  const key = normalized.join('\0')
+  const key = `${name ?? ''}\0${normalized.join('\0')}`
   const cached = errorSchemas.get(key)
   if (cached) return cached
-  const schema = component(Schema.errorResponse(normalized), errorName(status, normalized))
+  const schema = component(Schema.errorResponse(normalized), name ?? errorName(status, normalized))
   errorSchemas.set(key, schema)
   return schema
 }
@@ -281,10 +307,11 @@ function errorContent(
   status: number,
   codes: readonly [string, ...string[]] | undefined,
   message: string,
+  name?: string,
 ) {
   return {
     'application/json': {
-      schema: resolver(errorSchema(status, codes), schemaOptions),
+      schema: resolver(errorSchema(status, codes, name), schemaOptions),
       example: { error: { code: codes?.[0] ?? 'error', message }, requestId: exampleRequestId },
     },
   }
@@ -345,7 +372,7 @@ export const paymentChallengeRef = responseRef('PaymentRequired')
  * `components.responses` entries.
  */
 export function standardError(
-  status: keyof typeof errorCodes,
+  status: keyof typeof errorCodes | 409 | 412 | 413 | 415,
   description: string,
   codes?: readonly [string, ...string[]],
 ): ResponsesWithResolver[string] {
@@ -379,8 +406,9 @@ export function responses<schema extends z.ZodMiniType>(
     const description =
       typeof override === 'string' ? override : (override?.description ?? fallback)
     const codes = mergeErrorCodes(status, typeof override === 'object' ? override.codes : undefined)
+    const name = typeof override === 'object' ? override.name : undefined
     return {
-      content: errorContent(status, codes, description),
+      content: errorContent(status, codes, description, name),
       description,
     }
   }
@@ -413,6 +441,7 @@ export function responses<schema extends z.ZodMiniType>(
     500: responseRef('InternalError'),
     ...(errors?.[501] && { 501: error(501, 'Not implemented.') }),
     502: error(502, 'Upstream data failure.'),
+    ...(errors?.[503] && { 503: error(503, 'Service unavailable.') }),
     504: responseRef('RequestTimeout'),
   }
 }
@@ -425,10 +454,12 @@ export declare namespace responses {
   type ErrorOverride =
     | string
     | {
-        /** Human-readable description of the error response. */
-        description?: string | undefined
         /** Operation-specific `error.code` values for this status. */
         codes?: readonly string[] | undefined
+        /** Human-readable description of the error response. */
+        description?: string | undefined
+        /** OpenAPI schema component name for the error response. */
+        name?: string | undefined
       }
 
   /** Options for building a standard OpenAPI responses map. */
@@ -461,6 +492,8 @@ export declare namespace responses {
           501?: ErrorOverride | undefined
           /** Override for the 502 response. */
           502?: ErrorOverride | undefined
+          /** Override for the 503 response. Setting this includes 503 in the map. */
+          503?: ErrorOverride | undefined
         }
       | undefined
     /** 200 response schema and description. */

package/src/internal/Provider.test.ts

@@ -1,7 +1,7 @@
 import * as Provider from './Provider.js'
 
 describe('from', () => {
-  test.each(['exchange', 'funding'] as const)('preserves %s provider identity', (type) => {
+  test.each(['exchange', 'routes'] as const)('preserves %s provider identity', (type) => {
     expect(
       Provider.from({
         id: 'relay',

package/src/internal/Provider.ts

@@ -9,7 +9,7 @@ export type Provider<id extends string = string, type extends ProviderType = Pro
 }
 
 /** Capability categories supported by registered providers. */
-export type ProviderType = 'exchange' | 'funding'
+export type ProviderType = 'exchange' | 'routes'
 
 /** Defines a provider while preserving its concrete identity and capabilities. */
 export function from<const provider extends Provider>(options: provider): provider {

package/src/internal/RateLimit.test.ts

@@ -1,4 +1,4 @@
-import { RateLimit, Store } from 'tapimo'
+import { RateLimit, Store } from 'tapimo/server'
 
 describe('memory', () => {
   test('tracks fixed-minute quota in a store', async () => {
@@ -102,9 +102,19 @@ describe('edge', () => {
     return { limit: vi.fn(async (_: { key: string }) => ({ success })) }
   }
 
-  function request(options: { asn?: number | undefined; ip?: string | undefined } = {}) {
+  function request(
+    options: {
+      asn?: number | undefined
+      forwardedAsn?: number | undefined
+      ip?: string | undefined
+    } = {},
+  ) {
+    const headers = new Headers()
+    if (options.forwardedAsn !== undefined)
+      headers.set('tempo-client-asn', String(options.forwardedAsn))
+    if (options.ip) headers.set('cf-connecting-ip', options.ip)
     const value = new Request('https://api.tempo.xyz/v1/health', {
-      headers: options.ip ? { 'cf-connecting-ip': options.ip } : {},
+      headers,
     })
     if (options.asn) Object.assign(value, { cf: { asn: options.asn } })
     return value
@@ -167,6 +177,14 @@ describe('edge', () => {
     expect(asn.limit).not.toHaveBeenCalled()
   })
 
+  test('uses an ASN forwarded by a trusted service binding', async () => {
+    const asn = binding()
+
+    await RateLimit.edge(request({ forwardedAsn: 64512 }), { asn })
+
+    expect(asn.limit).toHaveBeenCalledWith({ key: 'asn:64512' })
+  })
+
   test('keys unknown clients together when the ip header is missing', async () => {
     const ip = binding()
 

package/src/internal/RateLimit.ts

@@ -112,7 +112,7 @@ export async function edge(request: Request, options: edge.Options): Promise<Res
   try {
     const checks: Promise<{ success: boolean }>[] = []
     if (options.ip) checks.push(options.ip.limit({ key: clientKey(request) }))
-    const asn = (request as Request & { cf?: CfProperties }).cf?.asn
+    const asn = clientAsn(request)
     if (options.asn && asn !== undefined) checks.push(options.asn.limit({ key: `asn:${asn}` }))
     if (options.global) checks.push(options.global.limit({ key: 'global' }))
 
@@ -143,6 +143,17 @@ export declare namespace edge {
 /** Cloudflare-enriched request properties; absent outside Workers (tests, service bindings). */
 type CfProperties = { asn?: number | undefined }
 
+function clientAsn(request: Request): number | undefined {
+  const direct = (request as Request & { cf?: CfProperties }).cf?.asn
+  if (direct !== undefined) return direct
+  // Public Worker requests carry `cf`; this fallback is for trusted service
+  // bindings whose callers overwrite the forwarded header.
+  const forwarded = request.headers.get('tempo-client-asn')
+  if (forwarded === null) return undefined
+  const parsed = Number(forwarded)
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined
+}
+
 /** IPv4 clients key by address; IPv6 clients by /64 prefix so they cannot rotate within their allocation. */
 function clientKey(request: Request): string {
   const ip = request.headers.get('cf-connecting-ip')

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

@@ -1,5 +1,5 @@
 import type { Store as MppStore } from 'mppx'
-import { Store } from 'tapimo'
+import { Store } from 'tapimo/server'
 
 declare const namespace: Store.durableObject.Namespace
 

package/src/internal/Store.test.ts

@@ -1,5 +1,5 @@
 import { HonoRequest } from 'hono/request'
-import { Store } from 'tapimo'
+import { Store } from 'tapimo/server'
 import * as TestStore from '../../test/Store.js'
 import * as Timeout from './Timeout.js'
 
@@ -71,6 +71,25 @@ describe('increment', () => {
   })
 })
 
+describe('getMany', () => {
+  test('falls back to serial reads when the store has no native bulk operation', async () => {
+    const store = Store.memory({
+      entries: [
+        ['a', 'alpha'],
+        ['b', 'beta'],
+      ],
+    })
+
+    expect(await Store.getMany(store, ['a', 'missing', 'b'])).toMatchInlineSnapshot(`
+      Map {
+        "a" => "alpha",
+        "missing" => null,
+        "b" => "beta",
+      }
+    `)
+  })
+})
+
 describe('update', () => {
   test('falls back to a get + put read-modify-write without a native swap', async () => {
     const cells = new Map<string, string>()
@@ -223,6 +242,28 @@ describe('memory', () => {
         ],
       }
     `)
+    expect(await store.list({ limit: 1, prefix: 'secret:' })).toMatchInlineSnapshot(`
+      {
+        "cursor": "secret:1",
+        "keys": [
+          {
+            "name": "secret:1",
+          },
+        ],
+        "listComplete": false,
+      }
+    `)
+    expect(await store.list({ cursor: 'secret:1', limit: 1, prefix: 'secret:' }))
+      .toMatchInlineSnapshot(`
+      {
+        "keys": [
+          {
+            "name": "secret:2",
+          },
+        ],
+        "listComplete": true,
+      }
+    `)
     expect(await store.get('missing')).toMatchInlineSnapshot(`null`)
     expect(await store.get('secret:1')).toMatchInlineSnapshot(`"alpha"`)
   })
@@ -245,13 +286,19 @@ describe('cloudflareKv', () => {
       ['secret:1', 'alpha'],
     ])
     const writes: unknown[] = []
+    function get(key: string): Promise<null | string>
+    function get(keys: string[]): Promise<Map<string, null | string>>
+    async function get(
+      key: string | string[],
+    ): Promise<Map<string, null | string> | null | string> {
+      if (typeof key === 'string') return cells.get(key) ?? null
+      return new Map(key.map((name) => [name, cells.get(name) ?? null]))
+    }
     const namespace = {
       async delete(key) {
         cells.delete(key)
       },
-      async get(key) {
-        return cells.get(key) ?? null
-      },
+      get,
       async list(options = {}) {
         return {
           keys: Array.from(cells.keys())
@@ -284,6 +331,12 @@ describe('cloudflareKv', () => {
       ]
     `)
     expect(await store.get('other:1')).toMatchInlineSnapshot(`null`)
+    expect(await Store.getMany(store, ['secret:1', 'missing'])).toMatchInlineSnapshot(`
+      Map {
+        "secret:1" => "alpha",
+        "missing" => null,
+      }
+    `)
     expect(await store.list({ prefix: 'secret:' })).toMatchInlineSnapshot(`
       {
         "keys": [
@@ -305,11 +358,17 @@ describe('cloudflareKv', () => {
 
   test('lists every Cloudflare Workers KV page', async () => {
     const calls: unknown[] = []
+    function get(key: string): Promise<null | string>
+    function get(keys: string[]): Promise<Map<string, null | string>>
+    async function get(
+      key: string | string[],
+    ): Promise<Map<string, null | string> | null | string> {
+      if (typeof key === 'string') return null
+      return new Map(key.map((name) => [name, null]))
+    }
     const namespace = {
       async delete() {},
-      async get() {
-        return null
-      },
+      get,
       async list(options = {}) {
         calls.push(options)
         if (options.cursor === 'page-2')
@@ -352,6 +411,38 @@ describe('cloudflareKv', () => {
       ]
     `)
   })
+
+  test('batches native bulk reads at the Cloudflare limit', async () => {
+    const calls: string[][] = []
+    function get(key: string): Promise<null | string>
+    function get(keys: string[]): Promise<Map<string, null | string>>
+    async function get(
+      key: string | string[],
+    ): Promise<Map<string, null | string> | null | string> {
+      if (typeof key === 'string') return key
+      calls.push(key)
+      return new Map(key.map((name) => [name, name]))
+    }
+    const namespace = {
+      async delete() {},
+      get,
+      async list() {
+        return { keys: [], list_complete: true }
+      },
+      async put() {},
+    } satisfies Store.cloudflareKv.Namespace
+    const store = Store.cloudflareKv(namespace)
+    const keys = Array.from({ length: 201 }, (_, index) => `key:${index}`)
+
+    expect((await Store.getMany(store, keys)).size).toBe(201)
+    expect(calls.map((batch) => batch.length)).toMatchInlineSnapshot(`
+      [
+        100,
+        100,
+        1,
+      ]
+    `)
+  })
 })
 
 describe('durableObject', () => {
@@ -602,7 +693,7 @@ describe('durableObject', () => {
         return new Proxy(stub, {
           get(target, method: string) {
             calls.push({ method, name })
-            return target[method as keyof Store.durableObject.Stub]
+            return target[method as keyof typeof stub]
           },
         })
       },
@@ -809,6 +900,33 @@ describe('memoize', () => {
     `)
   })
 
+  test('does not share cache-miss flights across request wrappers', async () => {
+    const source = Store.memory()
+    const firstStore = Store.withRequest(
+      source,
+      new HonoRequest(new Request('https://api.tempo.xyz/first')),
+    )
+    const secondStore = Store.withRequest(
+      source,
+      new HonoRequest(new Request('https://api.tempo.xyz/second')),
+    )
+    const pending = deferred<void>()
+    let calls = 0
+    const fetch = async () => {
+      const value = ++calls
+      await pending.promise
+      return { value }
+    }
+
+    const first = Store.memoize(fetch, { key: 'memo:test', store: firstStore, ttl: 60_000 })
+    const second = Store.memoize(fetch, { key: 'memo:test', store: secondStore, ttl: 60_000 })
+    await Promise.resolve()
+    pending.resolve()
+
+    expect(await Promise.all([first, second])).toEqual([{ value: 1 }, { value: 2 }])
+    expect(calls).toBe(2)
+  })
+
   test('hands cache persistence to waitUntil without retaining the resolved flight', async () => {
     const pending = deferred<void>()
     const waited: Promise<unknown>[] = []
@@ -932,6 +1050,31 @@ describe('memoize', () => {
     }
   })
 
+  test('times out a stalled cache read', async () => {
+    vi.useFakeTimers()
+    try {
+      const pending = deferred<string | null>()
+      const store = Store.from({
+        ...Store.memory(),
+        get: () => pending.promise,
+      })
+      const failure = expect(
+        Store.memoize(async () => ({ value: 'unexpected' }), {
+          flightTimeout: 100,
+          key: 'memo:stalled-read',
+          store,
+          ttl: 60_000,
+        }),
+      ).rejects.toBeInstanceOf(Store.MemoizeTimeoutError)
+
+      await vi.advanceTimersByTimeAsync(100)
+      await failure
+      pending.resolve(null)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   test('retains a timed-out flight until a cache mutation settles', async () => {
     vi.useFakeTimers()
     try {