tapimo 0.1.0 → 0.3.0

package/src/internal/Cache.ts

@@ -74,7 +74,7 @@ export function response<environment extends Env>(
   })
   const etag = hono_etag()
 
-  return async (c, next) => {
+  const middleware: MiddlewareHandler<environment> = async (c, next) => {
     const values = response.preservedHeaders.map((name) => [name, c.res.headers.get(name)] as const)
 
     // Honor the standard request `Cache-Control` directives (plus the HTTP/1.0
@@ -155,6 +155,10 @@ export function response<environment extends Env>(
     if (result instanceof Response) return res
     return undefined
   }
+
+  // `markCacheable` lets the edge layer pay its store lookup only on routes
+  // that mount this middleware; everything else skips the read.
+  return EdgeCache.markCacheable(middleware)
 }
 
 export declare namespace response {

package/src/internal/Cursor.test.ts

@@ -90,11 +90,12 @@ describe('Cursor', () => {
   })
 
   test('falls back to an OR expansion for a mixed-direction keyset', () => {
+    const holder = `'0x${'ab'.repeat(20)}'`
     expect(
       Cursor.keyset([
         { literal: '1000', name: 'balance', order: 'desc' },
-        { literal: "'0xabc'", name: 'holder', order: 'asc' },
+        { literal: holder, name: 'holder', order: 'asc' },
       ]),
-    ).toBe("(balance <= 1000 AND ((balance < 1000) OR (balance = 1000 AND holder > '0xabc')))")
+    ).toBe(`(balance <= 1000 AND ((balance < 1000) OR (balance = 1000 AND holder > ${holder})))`)
   })
 })

package/src/internal/EdgeCache.test.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import { createMiddleware } from 'hono/factory'
 import * as EdgeCache from './EdgeCache.js'
 import type * as Store from './Store.js'
 
@@ -128,6 +129,18 @@ describe('middleware', () => {
     expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
+  test('skips the store lookup for routes that did not opt in', async () => {
+    const { app, store } = createApp()
+
+    await app.request('/uncached')
+    await app.request('/missing-route')
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+
+    // Marked routes still pay (and use) the lookup.
+    await app.request('/cached')
+    expect(store.gets).toMatchInlineSnapshot(`1`)
+  })
+
   test('answers conditional requests from a cached ETag with 304', async () => {
     const { app } = createApp()
 
@@ -172,13 +185,18 @@ type Environment = { Variables: EdgeCache.Variables }
 // In-memory `Store.Store` so the edge cache and origin cache share one shape.
 function memoryStore() {
   const map = new Map<string, string>()
+  let gets = 0
   return {
     async delete(key: string) {
       map.delete(key)
     },
     async get(key: string) {
+      gets++
       return map.get(key) ?? null
     },
+    get gets() {
+      return gets
+    },
     async list() {
       return { keys: [...map.keys()].map((name) => ({ name })) }
     },
@@ -189,7 +207,7 @@ function memoryStore() {
       return map.size
     },
     type: 'state',
-  } satisfies Store.Store & { readonly size: number }
+  } satisfies Store.Store & { readonly gets: number; readonly size: number }
 }
 
 function createApp(options: { store?: Store.Store | undefined } = {}) {
@@ -203,7 +221,12 @@ function createApp(options: { store?: Store.Store | undefined } = {}) {
     downstream++
     await next()
   })
-  app.get('/cached', (c) => {
+  // Routes publishing a policy mount a marked middleware, as `Cache.response`
+  // routes do; unmarked routes must skip the lookup entirely.
+  const cacheable = EdgeCache.markCacheable(
+    createMiddleware<Environment>(async (_c, next) => next()),
+  )
+  app.get('/cached', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     c.header('Age', '123')
     c.header('CF-Cache-Status', 'HIT')
@@ -212,11 +235,11 @@ function createApp(options: { store?: Store.Store | undefined } = {}) {
     c.header('RateLimit-Remaining', '9')
     return c.json({ ok: true })
   })
-  app.get('/error', (c) => {
+  app.get('/error', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     return c.json({ ok: false }, 500)
   })
-  app.get('/binary', (c) => {
+  app.get('/binary', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     // Bytes that are not valid UTF-8 (PNG signature) — corrupted if stored via
     // `.text()` instead of base64.

package/src/internal/EdgeCache.ts

@@ -1,4 +1,5 @@
-import type { Env, MiddlewareHandler } from 'hono'
+import type { Context, Env, MiddlewareHandler } from 'hono'
+import { matchedRoutes } from 'hono/route'
 import { Base64 } from 'ox'
 
 import type * as Store from './Store.js'
@@ -53,6 +54,10 @@ const volatileHeaders = [
  * is that cache hits bypass origin metering: they are not counted against
  * rate-limit quotas.
  *
+ * Lookups are equally scoped: only requests whose matched route carries the
+ * {@link markCacheable} marker (applied by `Cache.response`) pay the store
+ * read, so GETs to non-cacheable routes skip the round trip entirely.
+ *
  * The cache is a plain `Store.Store` — the same store the origin read cache uses
  * — holding the response serialized to a string under a URL key. It is a no-op
  * when no store is supplied.
@@ -68,8 +73,14 @@ export function middleware<environment extends Env>(
 ): MiddlewareHandler<environment> {
   return async (c, next) => {
     const { store } = options
+    // Pay the store lookup only when a matched handler is marked cacheable
+    // (mounted `Cache.response`); other GETs (authed platform routes, docs,
+    // 404s) can never hit, so the read would be a wasted round trip.
     const eligible =
-      store !== undefined && c.req.method === 'GET' && !c.req.raw.headers.has('range')
+      store !== undefined &&
+      c.req.method === 'GET' &&
+      !c.req.raw.headers.has('range') &&
+      isCacheableRoute(c)
     const key = eligible ? cacheKey(c.req.url) : undefined
 
     // Honor the standard request `Cache-Control` directives so a caller can
@@ -104,16 +115,41 @@ export function middleware<environment extends Env>(
     if (c.res.headers.get('content-type')?.includes('text/event-stream')) return
 
     // Store a public, sanitized copy; the client still receives the original
-    // (private, metered) response for this miss.
-    const value = await serialize(c.res, policy)
-    const put = store.put(key, value, { ttl: policy.maxAge * 1_000 })
+    // (private, metered) response for this miss. Clone synchronously — the
+    // original body locks once it streams to the client — then serialize and
+    // write behind `waitUntil` so the miss response is not held open on the
+    // body read.
+    const copy = c.res.clone()
+    const persist = serialize(copy, policy).then((value) =>
+      store.put(key, value, { ttl: policy.maxAge * 1_000 }),
+    )
     const waitUntil = getWaitUntil(c)
-    if (waitUntil) waitUntil(put)
-    else await put.catch(() => {})
+    if (waitUntil) waitUntil(persist)
+    else await persist.catch(() => {})
     return
   }
 }
 
+// Marks handlers whose route publishes an edge-cache policy; the middleware
+// pays the store lookup only when a matched handler carries it.
+const cacheableSymbol = Symbol('tempoApi.edgeCacheable')
+
+/**
+ * Marks a route handler/middleware as publishing an edge-cache policy, so
+ * {@link middleware} looks its route up in the edge cache. `Cache.response`
+ * applies it; routes composed any other way never enter the shared cache.
+ */
+export function markCacheable<const handler extends (...args: never[]) => unknown>(
+  handler: handler,
+): handler {
+  return Object.assign(handler, { [cacheableSymbol]: true })
+}
+
+// True when any handler matched for this request is marked cacheable.
+function isCacheableRoute(c: Context): boolean {
+  return matchedRoutes(c).some((route) => cacheableSymbol in route.handler)
+}
+
 export declare namespace middleware {
   /** Options for the edge-cache middleware. */
   type Options = {
@@ -134,6 +170,8 @@ type Stored = {
   status: number
 }
 
+// Consumes `response` (callers pass a dedicated clone; the client streams the
+// original).
 async function serialize(response: Response, policy: Policy): Promise<string> {
   const headers = new Headers(response.headers)
   for (const name of volatileHeaders) headers.delete(name)
@@ -145,8 +183,8 @@ async function serialize(response: Response, policy: Policy): Promise<string> {
   const textual = isTextual(headers.get('content-type'))
   const stored: Stored = {
     body: textual
-      ? await response.clone().text()
-      : Base64.fromBytes(new Uint8Array(await response.clone().arrayBuffer())),
+      ? await response.text()
+      : Base64.fromBytes(new Uint8Array(await response.arrayBuffer())),
     ...(textual ? {} : { encoding: 'base64' as const }),
     headers: [...headers],
     status: response.status,

package/src/internal/Fees.test.ts

@@ -0,0 +1,32 @@
+import * as Fees from './Fees.js'
+
+describe('fromGas', () => {
+  test('behavior: scales attodollar gas math to token units with ceiling division', () => {
+    // 100k gas × 1e6 atto = 1e11 atto rounds up to one token unit.
+    expect(Fees.fromGas(100_000n, 1_000_000n)).toBe(1n)
+    // 1M gas × 5e11 atto = 5e17 atto = $0.50 exactly.
+    expect(Fees.fromGas(1_000_000n, 500_000_000_000n)).toBe(500_000n)
+    // Any remainder rounds up, mirroring `calc_gas_balance_spending`.
+    expect(Fees.fromGas(1n, 1_000_000_000_001n)).toBe(2n)
+    expect(Fees.fromGas(0n, 0n)).toBe(0n)
+  })
+})
+
+describe('maxOf', () => {
+  test('behavior: computes the signed cap from bigint or hex quantity fields', () => {
+    expect(Fees.maxOf({ gas: 1_000_000n, maxFeePerGas: 500_000_000_000n })).toBe(500_000n)
+    // Fills carry hex quantities: 0xf4240 = 1M gas, 0x746a528800 = 5e11 atto.
+    expect(Fees.maxOf({ gas: '0xf4240', maxFeePerGas: '0x746a528800' })).toBe(500_000n)
+    // Zero fields are computable (a zero cap), not absent.
+    expect(Fees.maxOf({ gas: 0n, maxFeePerGas: 0n })).toBe(0n)
+  })
+
+  test('behavior: yields undefined when either fee field is missing or unparseable', () => {
+    expect(Fees.maxOf({})).toBeUndefined()
+    expect(Fees.maxOf({ gas: 21_000n })).toBeUndefined()
+    expect(Fees.maxOf({ maxFeePerGas: 1_000_000n })).toBeUndefined()
+    // Decimal strings are not hex quantities; callers fail closed.
+    expect(Fees.maxOf({ gas: '21000', maxFeePerGas: 1_000_000n })).toBeUndefined()
+    expect(Fees.maxOf({ gas: null, maxFeePerGas: 1_000_000n })).toBeUndefined()
+  })
+})

package/src/internal/Fees.ts

@@ -0,0 +1,51 @@
+import { Hex } from 'ox'
+
+// Tempo gas prices (`maxFeePerGas`, `effectiveGasPrice`, block base fee) are
+// denominated in attodollars (10^-18 USD) per gas, while fee-token balances
+// use 6 decimals (microdollars, 10^-6 USD). The charged fee is
+// `ceil(gas × gasPrice / 10^12)`, mirroring `calc_gas_balance_spending` in
+// tempoxyz/tempo.
+
+/** Attodollar exponent gas prices use (10^-18 USD per gas), fixed by the fee spec. */
+const attoDecimals = 18
+
+/** Fee-token decimals: TIP-20 fixes 6 (1 token unit = 1 microdollar). */
+export const tokenDecimals = 6
+
+/** Scaling between attodollar gas math and fee-token units, derived from the exponents. */
+export const scalingFactor = 10n ** BigInt(attoDecimals - tokenDecimals)
+
+/**
+ * Fee in fee-token base units for a gas amount priced in attodollars per gas
+ * (ceiling division). Works for actual fees (`gasUsed × effectiveGasPrice`)
+ * and signed caps (`gas × maxFeePerGas`) alike.
+ *
+ * @param gas - Gas amount.
+ * @param gasPrice - Price in attodollars per gas.
+ * @returns The fee in fee-token base units.
+ */
+export function fromGas(gas: bigint, gasPrice: bigint): bigint {
+  return (gas * gasPrice + scalingFactor - 1n) / scalingFactor
+}
+
+/**
+ * Signed fee cap of a candidate transaction in fee-token base units:
+ * `gas × maxFeePerGas` (attodollars) scaled through {@link fromGas}. Undefined
+ * when either field is missing or unparseable, so callers can fail closed.
+ *
+ * @param request - Transaction-shaped fee fields.
+ * @returns The cap in base units, or undefined.
+ */
+export function maxOf(request: { gas?: unknown; maxFeePerGas?: unknown }): bigint | undefined {
+  const gas = toBigInt(request.gas)
+  const maxFeePerGas = toBigInt(request.maxFeePerGas)
+  if (gas === undefined || maxFeePerGas === undefined) return undefined
+  return fromGas(gas, maxFeePerGas)
+}
+
+/** Fee fields arrive as bigints (raw envelopes) or hex quantities (fills). */
+function toBigInt(value: unknown): bigint | undefined {
+  if (typeof value === 'bigint') return value
+  if (typeof value === 'string' && Hex.validate(value)) return Hex.toBigInt(value)
+  return undefined
+}