tapimo 0.15.1 → 0.18.1

package/src/internal/RateLimit.ts

@@ -1,5 +1,7 @@
+import { Hash, Hex } from 'ox'
 import * as z from 'zod/mini'
 
+import type * as Metrics from '../Metrics.js'
 import * as Store from './Store.js'
 
 /** Zod schemas owned by the rate-limit module. */
@@ -46,6 +48,10 @@ export namespace RateLimitStore {
     key: string
     /** Rate-limit policy. */
     limit: Limit
+    /** Caller the quota belongs to, grouping its quotas on one object; defaults to the key. */
+    principal?: string | undefined
+    /** Keeps a deferred increment alive past the response; omitted, it runs unattended. */
+    waitUntil?: ((promise: Promise<unknown>) => void) | undefined
   }
 }
 
@@ -65,29 +71,199 @@ export function memory(options: memory.Options = {}): RateLimitStore {
   return {
     async consume(options) {
       const time = now().getTime()
-      const window = options.limit.period === 'second' ? 1_000 : 60_000
-      const bucket = Math.floor(time / window)
+      const { bucket, expiresAt, reset } = window(options.limit, time)
       // The bucket isolates window counts if the backing store applies the TTL
       // after the next window starts.
       const count = await Store.increment(
         store,
         `ratelimit:${options.limit.period}:${bucket}:${options.key}`,
-        {
-          ttl: (bucket + 1) * window - time,
-        },
+        { ttl: expiresAt - time },
       )
-      const limit = options.limit.limit
+      return result(options.limit, count, reset)
+    },
+  }
+}
 
-      return {
-        allowed: count <= limit,
-        limit,
-        remaining: Math.max(limit - count, 0),
-        reset: Math.ceil(((bucket + 1) * window) / 1_000),
+/**
+ * Creates a rate-limit store over quota Durable Objects, one object per
+ * principal holding a row per quota, so a caller's counters stay on one warm
+ * object across scopes and windows.
+ */
+export function durableObject(
+  namespace: durableObject.Namespace,
+  options: durableObject.Options = {},
+): RateLimitStore {
+  const { metrics, name = (principal: string) => `tempo-api:rate-limiter:${principal}` } = options
+  // Last known count per object and quota for the current window, plus the
+  // increments this isolate has sent there and not yet heard back on.
+  const locals = new Map<string, Local>()
+  return {
+    async consume(options) {
+      const { bucket, reset } = window(options.limit, Date.now())
+      const object = name(options.principal ?? options.key)
+      const quota = `${options.limit.period}:${options.key}`
+      const local = localFor(locals, `${object}\n${quota}`, bucket)
+      // Unsettled increments may already be in the reported count; counting
+      // them again errs toward waiting, never toward admitting.
+      const known = (local.count ?? 0) + local.pending + 1
+      // Deferring needs a lifetime for the increment and fewer unanswered
+      // increments than the margin, which bounds any overshoot, even before
+      // the counter has reported a count for this window.
+      const deferred =
+        options.waitUntil !== undefined &&
+        local.pending < margin(options.limit) &&
+        defers(options.limit, known)
+      local.pending++
+      const start = performance.now()
+      // Stubs are request-scoped I/O objects in Workers, so resolve one per call.
+      const run = Store.durableObjectRetry(() =>
+        namespace.getByName(object).consume({ bucket, quota }),
+      ).then(
+        (outcome) => {
+          if (local.count === undefined || outcome.count > local.count) local.count = outcome.count
+          // Best effort once the caller has stopped waiting: metrics buffer
+          // until the request flushes, so a late reply lands in a later flush
+          // or not at all.
+          metrics?.histogram('rate_limit_rpc_ms', performance.now() - start, { cold: outcome.cold })
+          metrics?.count('rate_limit_consume_count', 1, {
+            cold: outcome.cold,
+            deferred,
+            outcome: 'ok',
+          })
+          return outcome
+        },
+        (error: unknown) => {
+          // A fast rejection fails open upstream without the 300 ms timing
+          // marker, so it leaves its own signal here.
+          metrics?.count('rate_limit_consume_count', 1, { deferred, outcome: 'error' })
+          throw error
+        },
+      )
+      const settled = run
+        .catch(() => {})
+        .finally(() => {
+          local.pending--
+        })
+      if (!deferred) {
+        const outcome = await run
+        return result(options.limit, outcome.count, reset)
       }
+      // Far from the limit the answer cannot change the response, so the
+      // request proceeds on the local estimate while the increment lands.
+      options.waitUntil?.(settled)
+      return result(options.limit, known, reset)
     },
   }
 }
 
+export declare namespace durableObject {
+  /** Quota Durable Object namespace. */
+  type Namespace = {
+    /** Gets the stub for one principal's object. */
+    getByName(name: string): Stub
+  }
+
+  /** Quota Durable Object RPC surface. */
+  type Stub = {
+    /** Counts one request in the given window. */
+    consume(options: Stub.ConsumeOptions): Promise<Outcome>
+  }
+
+  namespace Stub {
+    /** Window selected by the caller, so the object needs no clock of its own. */
+    type ConsumeOptions = {
+      /** Fixed-window number; the object keeps only the newest it has seen per quota. */
+      bucket: number
+      /** Quota within the principal's object: the period plus the quota key. */
+      quota: string
+    }
+  }
+
+  /** One counted request. */
+  type Outcome = {
+    /** Whether the object was constructed to serve this call. */
+    cold: boolean
+    /** Requests counted in the window, including this one. */
+    count: number
+  }
+
+  /** Options for creating a quota Durable Object store. */
+  type Options = {
+    /** Receives round-trip and cold-start metrics. */
+    metrics?: Metrics.Metrics | undefined
+    /** Maps a principal to its object name. */
+    name?: ((principal: string) => string) | undefined
+  }
+}
+
+/** Limits at or below this always wait for the counter: one overshoot would be visible. */
+const exactLimit = 10
+
+/** Most unanswered increments one isolate may defer per quota before a consume waits for the counter. */
+function margin(limit: Limit): number {
+  return Math.max(1, Math.ceil(limit.limit / 100))
+}
+
+/**
+ * Whether a consume may proceed on the local estimate `known` (last known
+ * count plus unanswered increments plus this request) instead of waiting for
+ * the counter. Small limits and anything within the margin wait.
+ */
+export function defers(limit: Limit, known: number): boolean {
+  return limit.limit > exactLimit && known < limit.limit - margin(limit)
+}
+
+/** Isolate-local view of one object's quota in the current window. */
+type Local = {
+  /** Window the view belongs to. */
+  bucket: number
+  /** Largest count the counter has reported for the window; unknown until the first reply. */
+  count?: number | undefined
+  /** Increments sent and not yet settled. */
+  pending: number
+}
+
+/** Cap on tracked identities per isolate; the oldest is dropped past it. */
+const localsMax = 10_000
+
+function localFor(locals: Map<string, Local>, identity: string, bucket: number): Local {
+  const existing = locals.get(identity)
+  if (existing?.bucket === bucket) return existing
+  if (!existing && locals.size >= localsMax) locals.delete(locals.keys().next().value as string)
+  const local: Local = { bucket, pending: 0 }
+  locals.set(identity, local)
+  return local
+}
+
+/** Fixed-window boundaries for one limit at one instant. */
+export function window(limit: Limit, time: number): window.ReturnType {
+  const width = limit.period === 'second' ? 1_000 : 60_000
+  const bucket = Math.floor(time / width)
+  const expiresAt = (bucket + 1) * width
+  return { bucket, expiresAt, reset: Math.ceil(expiresAt / 1_000) }
+}
+
+export declare namespace window {
+  /** One fixed window. */
+  type ReturnType = {
+    /** Window number since the epoch. */
+    bucket: number
+    /** Epoch milliseconds the window ends. */
+    expiresAt: number
+    /** Window end in Unix seconds, as published in `RateLimit-Reset`. */
+    reset: number
+  }
+}
+
+function result(limit: Limit, count: number, reset: number): Result {
+  return {
+    allowed: count <= limit.limit,
+    limit: limit.limit,
+    remaining: Math.max(limit.limit - count, 0),
+    reset,
+  }
+}
+
 export declare namespace memory {
   /** Options for creating an in-memory fixed-window rate-limit store. */
   type Options = {
@@ -109,23 +285,68 @@ export type Binding = {
  * when any configured layer denies; fails open when a binding errors.
  */
 export async function edge(request: Request, options: edge.Options): Promise<Response | undefined> {
-  try {
+  const check = async (run: () => Promise<{ success: boolean }>[]) => {
+    try {
+      const results = await Promise.all(run())
+      if (results.some((result) => !result.success))
+        return new Response('Rate limit exceeded', {
+          headers: { 'retry-after': '10' },
+          status: 429,
+        })
+    } catch (error) {
+      console.error('Edge rate limit check failed:', error)
+    }
+    return undefined
+  }
+
+  if (!options.resolvePartition)
+    return check(() => {
+      const checks: Promise<{ success: boolean }>[] = []
+      if (options.ip) checks.push(options.ip.limit({ key: clientKey(request) }))
+      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' }))
+      return checks
+    })
+
+  const [global, network] = await Promise.all([
+    check(() => (options.global ? [options.global.limit({ key: 'global' })] : [])),
+    check(() => {
+      const checks: Promise<{ success: boolean }>[] = []
+      if (options.ip) checks.push(options.ip.limit({ key: clientKey(request) }))
+      const asn = clientAsn(request)
+      if (options.asn && asn !== undefined) checks.push(options.asn.limit({ key: `asn:${asn}` }))
+      return checks
+    }),
+  ])
+  if (global) return global
+  if (!network) return undefined
+
+  // Credential lookups get a separate network budget so rotating invalid
+  // tokens cannot turn an exhausted transport bucket into backend fan-out.
+  const admission = await check(() => {
     const checks: Promise<{ success: boolean }>[] = []
-    if (options.ip) checks.push(options.ip.limit({ key: clientKey(request) }))
+    if (options.ip)
+      checks.push(options.ip.limit({ key: partitionKey(clientKey(request), 'credential-probe') }))
     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' }))
-
-    const results = await Promise.all(checks)
-    if (results.some((result) => !result.success))
-      return new Response('Rate limit exceeded', {
-        headers: { 'retry-after': '10' },
-        status: 429,
-      })
-  } catch (error) {
-    console.error('Edge rate limit check failed:', error)
-  }
-  return undefined
+    if (options.asn && asn !== undefined)
+      checks.push(options.asn.limit({ key: partitionKey(`asn:${asn}`, 'credential-probe') }))
+    return checks
+  })
+  if (admission) return network
+
+  const resolved = await options.resolvePartition()
+  if (resolved === undefined) return network
+
+  return check(() => {
+    const checks: Promise<{ success: boolean }>[] = []
+    if (options.ip)
+      checks.push(options.ip.limit({ key: partitionKey(clientKey(request), resolved) }))
+    const asn = clientAsn(request)
+    if (options.asn && asn !== undefined)
+      checks.push(options.asn.limit({ key: partitionKey(`asn:${asn}`, resolved) }))
+    return checks
+  })
 }
 
 export declare namespace edge {
@@ -137,12 +358,19 @@ export declare namespace edge {
     global?: Binding | undefined
     /** Per-client limit, keyed by IPv4 address or IPv6 /64 prefix. */
     ip?: Binding | undefined
+    /** Resolves a confirmed credential partition when the shared network limit rejects. */
+    resolvePartition?: (() => Promise<string | undefined>) | undefined
   }
 }
 
 /** Cloudflare-enriched request properties; absent outside Workers (tests, service bindings). */
 type CfProperties = { asn?: number | undefined }
 
+/** Hashes a network and credential partition into Cloudflare's 64-byte binding-key limit. */
+function partitionKey(network: string, partition: string): string {
+  return Hash.sha256(Hex.fromString(`${network}:partition:${partition}`)).slice(2)
+}
+
 function clientAsn(request: Request): number | undefined {
   const direct = (request as Request & { cf?: CfProperties }).cf?.asn
   if (direct !== undefined) return direct

package/src/internal/Store.ts

@@ -891,12 +891,11 @@ function durableObjectStub(
 }
 
 /**
- * Runs a Durable Object stub call, retrying once when workerd marks the error
- * retryable (transient transport failures, e.g. "Network connection lost.")
- * and not overloaded. Callers pass a thunk so the retry resolves a fresh
- * stub: a stub that threw is disconnected.
+ * Runs a Durable Object call, retrying once when workerd marks the error
+ * retryable and not overloaded. Callers pass a thunk so the retry resolves a
+ * fresh stub: a stub that threw is disconnected.
  */
-async function durableObjectRetry<value>(call: () => Promise<value>): Promise<value> {
+export async function durableObjectRetry<value>(call: () => Promise<value>): Promise<value> {
   try {
     return await call()
   } catch (error) {

package/src/internal/Timing.test.ts

@@ -97,3 +97,35 @@ describe('middleware', () => {
     }
   })
 })
+
+describe('record', () => {
+  test('adds observed durations under one metric', async () => {
+    const app = new Hono<{ Variables: Timing.Variables }>()
+    app.use('*', Timing.middleware())
+    app.get('/', async (c) => {
+      Timing.record('db', 12)
+      // Attribution survives awaited work inside the request.
+      await Promise.resolve()
+      Timing.record('db', 8)
+      return c.text('ok')
+    })
+
+    const response = await app.request('/')
+    const timing = response.headers.get('server-timing')
+
+    expect(timing?.match(/db/g)).toHaveLength(1)
+    expect(timing).toContain('db;dur=20.0')
+  })
+
+  test('ignores requests without timing middleware', async () => {
+    const app = new Hono<{ Variables: Timing.Variables }>()
+    app.get('/', (c) => {
+      Timing.record('db', 12)
+      return c.text('ok')
+    })
+
+    const response = await app.request('/')
+
+    expect(response.headers.get('server-timing')).toBeNull()
+  })
+})

package/src/internal/Timing.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
 import type { Context, MiddlewareHandler } from 'hono'
 
 /** Hono variables used to collect Server-Timing metrics. */
@@ -49,6 +50,9 @@ export type Seed = {
 
 const requestSeeds = new WeakMap<Request, Seed>()
 
+/** Metrics of the request whose async continuation is currently running. */
+const scopes = new AsyncLocalStorage<Metric[]>()
+
 /** Seeds timings collected by an outer runtime onto the same request object. */
 export function seed(request: Request, value: Seed): void {
   requestSeeds.set(request, value)
@@ -69,7 +73,9 @@ export function middleware<
     c.set('timingSums', new Map())
 
     const start = performance.now()
-    await next()
+    // Downstream work runs inside the request's async scope so hooks without a
+    // context, such as database query observers, can still attribute to it.
+    await scopes.run(metrics, next)
     metrics.push({ duration: performance.now() - start, name: 'request' })
     for (const timing of outerActive) {
       active.splice(active.indexOf(timing), 1)
@@ -144,6 +150,19 @@ export async function sum<environment extends Environment, value>(
   }
 }
 
+/**
+ * Adds an already-measured duration to the current request's metric,
+ * accumulating repeats. Suits hooks that observe work they cannot wrap and
+ * have no request context of their own; a no-op outside a timed request.
+ */
+export function record(name: string, duration: number): void {
+  const metrics = scopes.getStore()
+  if (!metrics) return
+  const existing = metrics.find((metric) => metric.name === name)
+  if (existing) existing.duration += duration
+  else metrics.push({ duration, name })
+}
+
 function format(metrics: readonly Metric[]) {
   return metrics
     .map((metric) => `${name(metric.name)};dur=${metric.duration.toFixed(1)}`)

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

@@ -0,0 +1,22 @@
+import type { Hex } from 'ox'
+import { describe, expectTypeOf, test } from 'vitest'
+
+import * as Tron from './Tron.js'
+
+describe('createClient', () => {
+  test('exposes typed native Tron actions', () => {
+    const client = Tron.createClient({ urls: ['https://api.trongrid.io'] })
+    expectTypeOf(client.call).returns.toEqualTypeOf<Promise<Hex.Hex>>()
+    expectTypeOf(client.getTransactionReceipt).returns.resolves.toMatchTypeOf<
+      | {
+          blockNumber: number
+          id: string
+          receipt: { result?: string | undefined }
+        }
+      | undefined
+    >()
+    expectTypeOf(client.getBlock).returns.resolves.toMatchTypeOf<{
+      block_header: { raw_data: { number: number; timestamp: number } }
+    }>()
+  })
+})

package/src/internal/Tron.test.ts

@@ -0,0 +1,94 @@
+import { Base58, Hash, Hex } from 'ox'
+import { describe, expect, test } from 'vitest'
+
+import * as Tron from './Tron.js'
+
+const usdt = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'
+const address = '0xa614f803b6fd780986a42c78ec9c7f77e6ded13c'
+
+describe('toEvmAddress', () => {
+  test('decodes the Tron USDT address without its network prefix', () => {
+    expect(Tron.toEvmAddress(usdt)).toMatchInlineSnapshot(
+      '"0xa614f803b6fd780986a42c78ec9c7f77e6ded13c"',
+    )
+  })
+
+  test('rejects a changed checksum and ambiguous characters', () => {
+    expect(() => Tron.toEvmAddress(`${usdt.slice(0, -1)}k`)).toThrowErrorMatchingInlineSnapshot(
+      '[Tron.InvalidAddressError: Invalid Tron address.]',
+    )
+    expect(() =>
+      Tron.toEvmAddress('T0LAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj'),
+    ).toThrowErrorMatchingInlineSnapshot('[Tron.InvalidAddressError: Invalid Tron address.]')
+  })
+
+  test('rejects a valid checksum for another network', () => {
+    const payload = Hex.concat('0x00', address)
+    const value = Base58.fromHex(
+      Hex.concat(payload, Hex.slice(Hash.sha256(Hash.sha256(payload)), 0, 4)),
+    )
+    expect(() => Tron.toEvmAddress(value)).toThrowErrorMatchingInlineSnapshot(
+      '[Tron.InvalidAddressError: Invalid Tron address.]',
+    )
+  })
+})
+
+describe('fromEvmAddress', () => {
+  test('encodes the Tron USDT address and zero address', () => {
+    expect(Tron.fromEvmAddress(address)).toMatchInlineSnapshot(
+      '"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"',
+    )
+    expect(Tron.fromEvmAddress(`0x${'00'.repeat(20)}`)).toMatchInlineSnapshot(
+      '"T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb"',
+    )
+  })
+
+  test('rejects an ABI word in place of an address', () => {
+    expect(() => Tron.fromEvmAddress(`0x${'00'.repeat(32)}`)).toThrowErrorMatchingInlineSnapshot(
+      '[Tron.InvalidAddressError: Invalid Tron address.]',
+    )
+  })
+})
+
+describe('schema', () => {
+  test('validates source evidence with native network-prefixed addresses', () => {
+    const result = Tron.schema.Transaction.safeParse({
+      raw_data: {
+        contract: [
+          {
+            parameter: {
+              value: {
+                contract_address: `41${address.slice(2)}`,
+                data: 'a9059cbb',
+                owner_address: `41${'11'.repeat(20)}`,
+              },
+            },
+            type: 'TriggerSmartContract',
+          },
+        ],
+      },
+      ret: [{ contractRet: 'SUCCESS' }],
+      txID: 'aa'.repeat(32),
+    })
+    expect(result.success).toMatchInlineSnapshot('true')
+  })
+
+  test('rejects missing evidence and malformed hexadecimal results', () => {
+    expect([
+      Tron.schema.Transaction.safeParse({}).success,
+      Tron.schema.Receipt.safeParse({}).success,
+      Tron.schema.Call.safeParse({ constant_result: ['xyz'], result: { result: true } }).success,
+      Tron.schema.Block.safeParse({
+        blockID: 'aa'.repeat(32),
+        block_header: { raw_data: { number: -1, timestamp: 100 } },
+      }).success,
+    ]).toMatchInlineSnapshot(`
+      [
+        false,
+        false,
+        false,
+        false,
+      ]
+    `)
+  })
+})