tapimo 0.0.0 → 0.0.2

package/src/internal/RateLimit.ts

@@ -0,0 +1,93 @@
+import * as z from 'zod/mini'
+
+import * as Store from './Store.js'
+
+/** Zod schemas owned by the rate-limit module. */
+export namespace schema {
+  /** A rate-limit policy; the source of truth for {@link Limit}. */
+  export const Limit = z.object({
+    perMinute: z
+      .number()
+      .check(z.int(), z.nonnegative(), z.describe('Number of requests allowed per minute.')),
+  })
+}
+
+/** Rate-limit policy. */
+export type Limit = z.output<typeof schema.Limit>
+
+/** Result returned by a rate-limit store. */
+export type Result = {
+  /** Whether the request is within quota. */
+  allowed: boolean
+  /** Limit applied to the request. */
+  limit: number
+  /** Requests remaining in the active window. */
+  remaining: number
+  /** Reset timestamp in Unix seconds. */
+  reset: number
+}
+
+/** Rate-limit store. */
+export type RateLimitStore = {
+  /** Consumes one request from the active quota window. */
+  consume(options: RateLimitStore.ConsumeOptions): Promise<Result>
+}
+
+export namespace RateLimitStore {
+  /** Options for consuming one request from a rate-limit store. */
+  export type ConsumeOptions = {
+    /** Quota key. */
+    key: string
+    /** Rate-limit policy. */
+    limit: Limit
+  }
+}
+
+/**
+ * Creates a fixed-window rate-limit store over a counter {@link Store.Store}.
+ *
+ * Each consume is a single `Store.increment`, so a backend with a native
+ * counter (e.g. a Durable Object) is one atomic round trip; backends without
+ * one fall back to get + put, acceptable for dev/in-process stores only.
+ * The storage key is stable per quota key — the
+ * window lives in the TTL: the counter expires exactly at the end of the
+ * current minute, so the next window's first hit restarts at 1 and idle keys
+ * hold no storage. The sub-minute TTL rules out Cloudflare KV as a backend,
+ * which is unsuitable for enforced counters anyway.
+ */
+export function memory(options: memory.Options = {}): RateLimitStore {
+  const store = options.store ?? Store.memory()
+  const now = options.now ?? (() => new Date())
+
+  return {
+    async consume(options) {
+      const time = now().getTime()
+      const bucket = Math.floor(time / 60_000)
+      // Every increment within a window recomputes the TTL against the same
+      // window end, so the counter's absolute expiry never moves under load.
+      const count = await Store.increment(store, `ratelimit:${options.key}`, {
+        ttl: (bucket + 1) * 60_000 - time,
+      })
+      const limit = options.limit.perMinute
+
+      return {
+        allowed: count <= limit,
+        limit,
+        remaining: Math.max(limit - count, 0),
+        reset: Math.ceil(((bucket + 1) * 60_000) / 1_000),
+      }
+    },
+  }
+}
+
+export declare namespace memory {
+  /** Options for creating an in-memory fixed-window rate-limit store. */
+  type Options = {
+    /** Store used to persist counters. */
+    store?: Store.Store | undefined
+    /** Clock used to calculate fixed windows. */
+    now?: (() => Date) | undefined
+  }
+}
+
+export { type RateLimitStore as Store }

package/src/internal/Response.ts

@@ -0,0 +1,131 @@
+import type { Context } from 'hono'
+import type * as z from 'zod/mini'
+
+/** Creates a JSON error response. */
+export function error<const status extends error.Status, const code extends string>(
+  c: Context,
+  options: error.Options<status, code>,
+) {
+  const { code, details, message, status } = options
+  // Error envelopes embed `requestId` and other per-request state, so they
+  // must never be cached by clients, proxies, or CDNs.
+  c.header('Cache-Control', 'no-store')
+  // Record the stable code so the canonical request log line (`Log.middleware`)
+  // can include it without re-parsing the response body.
+  c.set('errorCode', code)
+  const body: error.Body<code> = {
+    error: {
+      code,
+      ...(details === undefined ? {} : { details }),
+      message,
+    },
+    requestId: c.get('requestId'),
+  }
+  return c.json(body, status)
+}
+
+/**
+ * Rejects a well-formed but unsupported chain id with a clear 400, listing the
+ * chain ids this deployment serves. Used to short-circuit before an unknown
+ * chain reaches an upstream (which would surface as an opaque `upstream_error`).
+ */
+export function unsupportedChainId(c: Context, chainId: number, supported: Iterable<number>) {
+  const ids = [...supported].sort((a, b) => a - b).join(', ')
+  return error(c, {
+    code: 'chain_id_unsupported',
+    message: `Unsupported chain id: ${chainId}. Supported chain ids: ${ids}.`,
+    status: 400,
+  })
+}
+
+/**
+ * Maps an unexpected upstream failure to a 502 JSON error envelope. Rethrows
+ * non-`Error` causes so the global handler can convert them.
+ */
+export function upstream(c: Context, cause: unknown) {
+  if (cause instanceof Error)
+    return error(c, { code: 'upstream_error', message: cause.message, status: 502 })
+  throw cause
+}
+
+/**
+ * Validates `value` against `schema`. Returns the parsed value on success or
+ * throws a generic upstream error so the public response body never leaks Zod
+ * internals.
+ */
+export function validated<schema extends z.ZodMiniType>(
+  schema: schema,
+  value: unknown,
+): z.output<schema> {
+  const result = schema.safeParse(value)
+  if (result.success) return result.data
+  throw new Error('Upstream returned invalid response data')
+}
+
+/** Converts standard validation issues into API error details. */
+export function validationDetails(issues: readonly validationDetails.Issue[]): error.Detail[] {
+  return issues.map((issue) => {
+    const path = issue.path?.map(pathSegment).filter((segment) => segment !== undefined)
+    if (!path?.length) return { message: issue.message }
+    return { message: issue.message, path }
+  })
+}
+
+export declare namespace error {
+  /** Public API error response body. */
+  type Body<code extends string = string> = {
+    /** Public error envelope. */
+    error: {
+      /** Stable machine-readable error code. */
+      code: code
+      /** Detailed validation or upstream error information. */
+      details?: readonly Detail[] | undefined
+      /** Human-readable error message. */
+      message: string
+    }
+    /** Request id for support/debugging. */
+    requestId: string
+  }
+
+  /** One public API error detail. */
+  type Detail = {
+    /** Human-readable detail message. */
+    message: string
+    /** Path to the invalid value. */
+    path?: readonly (number | string)[] | undefined
+  }
+
+  /** HTTP status code accepted by the public error helper. */
+  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 502 | 503
+
+  /** Options for creating a JSON error response. */
+  type Options<status extends Status = Status, code extends string = string> = {
+    /** Stable machine-readable error code. */
+    code: code
+    /** Detailed validation or upstream error information. */
+    details?: readonly Detail[] | undefined
+    /** Human-readable error message. */
+    message: string
+    /** HTTP status code. */
+    status: status
+  }
+}
+
+export declare namespace validationDetails {
+  /** Standard-schema validation issue shape used by Hono validators. */
+  type Issue = {
+    /** Human-readable validation message. */
+    message: string
+    /** Path to the invalid value. */
+    path?: readonly unknown[] | undefined
+  }
+}
+
+function pathSegment(segment: unknown) {
+  if (typeof segment === 'string' || typeof segment === 'number') return segment
+  if (!segment || typeof segment !== 'object' || !('key' in segment)) return undefined
+
+  const { key } = segment
+  if (typeof key === 'string' || typeof key === 'number') return key
+  return undefined
+}

package/src/internal/Schema.test.ts

@@ -0,0 +1,34 @@
+import * as Schema from './Schema.js'
+
+describe('ChainId', () => {
+  test('resolves aliases to their chain id', () => {
+    expect(Schema.ChainId.parse('mainnet')).toMatchInlineSnapshot(`4217`)
+    expect(Schema.ChainId.parse('testnet')).toMatchInlineSnapshot(`42431`)
+  })
+
+  test('accepts numeric chain ids as numbers or strings', () => {
+    expect(Schema.ChainId.parse(4217)).toMatchInlineSnapshot(`4217`)
+    expect(Schema.ChainId.parse('4217')).toMatchInlineSnapshot(`4217`)
+    expect(Schema.ChainId.parse('42431')).toMatchInlineSnapshot(`42431`)
+  })
+
+  test('accepts any positive integer chain id (e.g. a localnet)', () => {
+    expect(Schema.ChainId.parse('31337')).toMatchInlineSnapshot(`31337`)
+    expect(Schema.ChainId.parse(1)).toMatchInlineSnapshot(`1`)
+  })
+
+  test('rejects non-positive, non-integer, and unknown-alias values', () => {
+    expect(Schema.ChainId.safeParse('0').success).toMatchInlineSnapshot(`false`)
+    expect(Schema.ChainId.safeParse('-1').success).toMatchInlineSnapshot(`false`)
+    expect(Schema.ChainId.safeParse('1.5').success).toMatchInlineSnapshot(`false`)
+    expect(Schema.ChainId.safeParse('bogus').success).toMatchInlineSnapshot(`false`)
+  })
+})
+
+describe('ChainIdQuery', () => {
+  test('is optional and accepts aliases or numbers', () => {
+    expect(Schema.ChainIdQuery.parse(undefined)).toMatchInlineSnapshot(`undefined`)
+    expect(Schema.ChainIdQuery.parse('mainnet')).toMatchInlineSnapshot(`4217`)
+    expect(Schema.ChainIdQuery.parse('42431')).toMatchInlineSnapshot(`42431`)
+  })
+})