@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Cache.ts

@@ -0,0 +1,119 @@
+/**
+ * An isolate's cache of configuration reads, such as an app's realms. It holds no user data, and a
+ * change that another process writes applies within its TTL.
+ * @module
+ */
+import type * as Timing from './Timing.js'
+
+/** A cache that {@link create} returns. */
+export type Cache = ReturnType<typeof create>
+
+/**
+ * Creates a cache whose entries expire `ttl` milliseconds after their load settles. It stores only
+ * settled values, since another request cannot wait on a load's I/O. Keys can come from requests,
+ * so it holds at most `max` entries, and no key over 256 characters.
+ */
+export function create(options: create.Options) {
+  const { max = 1_000, ttl } = options
+  const entries = new Map<string, Entry>()
+  // Each load takes the next number, so a load that settles late never replaces a newer one's value.
+  let loads = 0
+
+  return {
+    /**
+     * Returns the value of `key`, and loads it with `load` without a live entry. A rejected load, or
+     * a value that `keep` rejects, stores no entry.
+     */
+    async get<value>(
+      load: () => Promise<value>,
+      key: Key,
+      options: read.Options<value> = {},
+    ): Promise<value> {
+      const { keep = () => true } = options
+      const lifetime = Math.min(options.ttl ?? ttl, ttl)
+      // JSON keeps each part apart, whatever characters it holds.
+      const name = JSON.stringify(key)
+      if (lifetime <= 0 || name.length > 256) return await load()
+
+      const cached = entries.get(name)
+      // `Date.now()` advances at I/O, so it reads the time of the request's latest I/O.
+      if (cached && cached.expires > Date.now()) return cached.value as value
+
+      const number = ++loads
+      const value = await load()
+      if (!keep(value)) return value
+      const current = entries.get(name)
+      if (current && current.load > number) return value
+
+      const now = Date.now()
+      entries.delete(name)
+      if (entries.size >= max)
+        for (const [other, entry] of entries)
+          if (entry.expires <= now) entries.delete(other)
+      if (entries.size >= max) {
+        // A `Map` iterates in insertion order, so its first key is the oldest entry.
+        const oldest = entries.keys().next().value
+        if (oldest !== undefined) entries.delete(oldest)
+      }
+      entries.set(name, { expires: now + lifetime, load: number, value })
+      return value
+    },
+  }
+}
+
+export declare namespace create {
+  type Options = {
+    /** The most entries that the cache holds. Defaults to 1,000. */
+    max?: number | undefined
+    /** Milliseconds that each entry lives. 0 turns the cache off. */
+    ttl: number
+  }
+}
+
+/**
+ * Returns the value of `key` from the request's cache, as {@link create}'s `get` does. Without a
+ * cache on `c`, such as in the CLI, it calls `load`.
+ *
+ * ```ts
+ * Cache.read(c, () => Realm.forApp(db, { clientId }), ['realm.forApp', clientId])
+ * ```
+ */
+export async function read<value>(
+  c: read.Context,
+  load: () => Promise<value>,
+  key: Key,
+  options: read.Options<value> = {},
+): Promise<value> {
+  const cache = c.var.cache
+  if (!cache) return await load()
+  return await cache.get(load, key, options)
+}
+
+export declare namespace read {
+  /** A context with the request's timing, and its cache once `IsolateCache.middleware` ran. */
+  type Context = Timing.measure.Context & {
+    /** The request's variables. */
+    var: {
+      /** The isolate's cache. Absent, each read loads. */
+      cache?: Cache | undefined
+    }
+  }
+
+  type Options<value> = {
+    /** Whether to store a loaded value. Defaults to storing every value. */
+    keep?: ((value: value) => boolean) | undefined
+    /** A shorter lifetime for this entry, in milliseconds. Defaults to the cache's own. */
+    ttl?: number | undefined
+  }
+}
+
+/** An entry's key: the read's name, unique across modules, then each input to the read. */
+export type Key = readonly [name: string, ...inputs: readonly string[]]
+
+/** A cached value, and the time in milliseconds when it expires. */
+type Entry = {
+  expires: number
+  /** The number of the load that read the value. */
+  load: number
+  value: unknown
+}

package/src/internal/Chain.ts

@@ -0,0 +1,99 @@
+/**
+ * The Tempo chains whose balances Tempo ID reads, by the name in the `chain` parameter: `mainnet`,
+ * `testnet`, or a name that `RPC_URLS` lists.
+ * @module
+ */
+import {
+  tempo,
+  tempoDevnet,
+  tempoLocalnet,
+  tempoTestnet,
+} from 'viem/tempo/chains'
+import { z } from 'zod'
+import * as ChainList from './ChainList.js'
+import * as ChainName from './ChainName.js'
+import * as Log from './Log.js'
+
+/**
+ * The Tempo chains whose tokens Tempo ID knows. A listed RPC URL serves one of them. The type checks
+ * that `ChainList.known` holds exactly their IDs.
+ */
+export const known = [
+  tempo,
+  tempoTestnet,
+  tempoDevnet,
+  tempoLocalnet,
+] as const satisfies readonly { id: (typeof ChainList.known)[number] }[] & {
+  length: (typeof ChainList.known)['length']
+}
+
+/** A chain's name, as `ChainName.pattern` reads it. */
+export const schema = z.string().regex(ChainName.pattern)
+
+/** A chain's name: `mainnet`, `testnet`, or a listed entry's name. */
+export type Chain = z.output<typeof schema>
+
+/** The Tempo API of the built-in chains, which limits requests without a key. */
+const defaultApiUrl = 'https://api.tempo.xyz'
+
+/**
+ * Returns the Tempo API URL that `TEMPO_API_URLS` lists for `chainId`, else {@link defaultApiUrl}
+ * for a built-in chain. `none` turns the API off. A list that does not parse logs a warning, and
+ * returns `undefined`.
+ */
+export function apiUrl(options: apiUrl.Options) {
+  if (options.apiUrls?.trim() === 'none') return undefined
+  const builtIn = Object.values(ChainList.ids).some(
+    (id) => id === options.chainId,
+  )
+
+  try {
+    const entry = ChainList.list({
+      value: options.apiUrls,
+      variable: 'TEMPO_API_URLS',
+    }).find((candidate) => candidate.chainId === options.chainId)
+    return entry?.url ?? (builtIn ? defaultApiUrl : undefined)
+  } catch (error) {
+    if (!(error instanceof ChainList.InvalidListError)) throw error
+    Log.warn({ error, message: 'TEMPO_API_URLS does not parse.' })
+    return undefined
+  }
+}
+
+export declare namespace apiUrl {
+  type Options = {
+    /** The value of `TEMPO_API_URLS`. */
+    apiUrls: string | undefined
+    /** The chain's ID. */
+    chainId: number
+  }
+}
+
+/**
+ * Returns the name that `GET /v1/chains` lists for `chainId`: `mainnet`, `testnet`, or the first
+ * `RPC_URLS` entry with that ID. Returns `undefined` when none does, or `rpcUrls` does not parse.
+ */
+export function name(options: name.Options) {
+  const builtIn = (
+    Object.keys(ChainList.ids) as (keyof typeof ChainList.ids)[]
+  ).find((key) => ChainList.ids[key] === options.chainId)
+  if (builtIn) return builtIn
+
+  try {
+    return ChainList.list({ value: options.rpcUrls }).find(
+      (entry) => entry.chainId === options.chainId,
+    )?.name
+  } catch (error) {
+    if (!(error instanceof ChainList.InvalidListError)) throw error
+    return undefined
+  }
+}
+
+export declare namespace name {
+  type Options = {
+    /** The chain's ID. */
+    chainId: number
+    /** The value of `RPC_URLS`. */
+    rpcUrls: string | undefined
+  }
+}

package/src/internal/ChainList.ts

@@ -0,0 +1,270 @@
+/**
+ * The chain lists of the deployment's options, `RPC_URLS`, `TEMPO_API_URLS`, and
+ * `CONFIGURABLE_ACCOUNTS`, read without Viem's chain definitions or Zod. `App.create` checks its
+ * options with this module when the Worker starts, so the Worker entry loads no second copy of
+ * either. `Chain` adds the definitions.
+ * @module
+ */
+import type {
+  tempo,
+  tempoDevnet,
+  tempoLocalnet,
+  tempoTestnet,
+} from 'viem/tempo/chains'
+import * as ChainName from './ChainName.js'
+import * as Log from './Log.js'
+
+/**
+ * `RPC_URLS` or `TEMPO_API_URLS` holds an entry that does not parse. The message names the entry by
+ * position only, since a URL can hold a key.
+ */
+export class InvalidListError extends Error {
+  override readonly name = 'ChainList.InvalidListError'
+
+  constructor(options: InvalidListError.Options) {
+    super(
+      `Invalid ${options.variable} entry ${options.index + 1}: ${options.reason}. Write each entry as \`name:chainId=url\`, such as \`local:1337=http://localhost:8545\`, and separate entries with commas.`,
+    )
+  }
+}
+
+export declare namespace InvalidListError {
+  type Options = {
+    /** From 0. */
+    index: number
+    /** What the entry gets wrong. */
+    reason: string
+    /** The variable that holds the entry. */
+    variable: list.Variable
+  }
+}
+
+/** Each built-in chain's ID, by its name. Viem's literal types check each ID. */
+export const ids = { mainnet: 4217, testnet: 42431 } as const satisfies {
+  mainnet: (typeof tempo)['id']
+  testnet: (typeof tempoTestnet)['id']
+}
+
+/**
+ * The IDs of the Tempo chains whose tokens Tempo ID knows, in the order of `Chain.known`, whose
+ * type checks each ID against its definition. A listed RPC URL serves one of them.
+ */
+export const known = [4217, 42431, 31318, 1337] as const satisfies readonly [
+  (typeof tempo)['id'],
+  (typeof tempoTestnet)['id'],
+  (typeof tempoDevnet)['id'],
+  (typeof tempoLocalnet)['id'],
+]
+
+/** The local chain's ID, which errors give as an example. */
+const localnet = known[3]
+
+/** A chain that `RPC_URLS` lists. */
+export type Entry = {
+  /** The Tempo chain that the node serves. */
+  chainId: number
+  /** The name in the `chain` parameter. */
+  name: string
+  /** The node's RPC URL, which can hold a provider's key. */
+  url: string
+}
+
+/**
+ * Returns the chains that a `RPC_URLS` value lists, in order, from comma-separated
+ * `name:chainId=url` entries. An entry named `mainnet` or `testnet` replaces that chain's RPC URL.
+ *
+ * @throws {InvalidListError} When an entry does not parse, repeats a name, gives a built-in name
+ * another chain's ID, or names a chain that is not a Tempo chain.
+ */
+export function list(options: list.Options): readonly Entry[] {
+  const { variable = 'RPC_URLS' } = options
+  const entries: Entry[] = []
+  const parts = (options.value ?? '')
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+
+  for (const [index, part] of parts.entries()) {
+    // The URL can hold `=` and `:` itself, so the first `=` ends the name and the chain ID.
+    const split = part.indexOf('=')
+    const head = split === -1 ? part : part.slice(0, split)
+    const url = split === -1 ? '' : part.slice(split + 1).trim()
+    const [name = '', id = ''] = head.split(':').map((value) => value.trim())
+    const chainId = Number(id)
+
+    if (!ChainName.read(name))
+      throw new InvalidListError({
+        index,
+        reason:
+          'the name needs lowercase letters, digits, and dashes, up to 32 characters',
+        variable,
+      })
+    if (name in ids && chainId !== ids[name as keyof typeof ids])
+      throw new InvalidListError({
+        index,
+        reason: `\`${name}\` is chain ${ids[name as keyof typeof ids]}`,
+        variable,
+      })
+    if (entries.some((entry) => entry.name === name))
+      throw new InvalidListError({
+        index,
+        reason: `\`${name}\` repeats an earlier entry`,
+        variable,
+      })
+    if (!known.some((entry) => entry === chainId))
+      throw new InvalidListError({
+        index,
+        // The segment can hold a URL's key when the entry has no `=`, so only digits are named.
+        reason: /^\d+$/.test(id)
+          ? `\`${id}\` is not a Tempo chain ID, such as ${localnet}`
+          : `the chain ID needs digits, such as ${localnet}`,
+        variable,
+      })
+    if (!URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol))
+      throw new InvalidListError({
+        index,
+        reason: 'the URL needs http or https',
+        variable,
+      })
+
+    entries.push({ chainId, name, url })
+  }
+
+  return entries
+}
+
+export declare namespace list {
+  type Options = {
+    /** The variable's value. */
+    value: string | undefined
+    /** The variable that errors name. Defaults to `RPC_URLS`. */
+    variable?: Variable | undefined
+  }
+
+  /** A variable that lists chains in the `name:chainId=url` format. */
+  type Variable = 'RPC_URLS' | 'TEMPO_API_URLS'
+}
+
+/**
+ * Returns the chain ID and RPC URL of the chain `name`, or `undefined` for an unknown name. A listed
+ * URL applies first, then `rpcUrl` for a built-in chain, then the chain's public RPC URL.
+ *
+ * @throws {InvalidListError} When `rpcUrls` does not parse and `name` is not built in.
+ */
+export function resolve(options: resolve.Options): resolve.ReturnType {
+  const { name } = options
+  if (name === 'mainnet' || name === 'testnet')
+    return {
+      chainId: ids[name],
+      rpcUrl:
+        override({ chainId: ids[name], rpcUrls: options.rpcUrls }) ??
+        options.rpcUrl,
+    }
+
+  const entry = list({ value: options.rpcUrls }).find(
+    (candidate) => candidate.name === name,
+  )
+  if (!entry) return undefined
+  return { chainId: entry.chainId, rpcUrl: entry.url }
+}
+
+export declare namespace resolve {
+  type Options = {
+    /** The chain's name. */
+    name: string
+    /** `TEMPO_RPC_URL`, for each built-in chain that `rpcUrls` does not list. */
+    rpcUrl: string | undefined
+    /** The value of `RPC_URLS`. */
+    rpcUrls: string | undefined
+  }
+
+  type ReturnType =
+    | {
+        /** The chain's ID. */
+        chainId: number
+        /** The RPC URL, or `undefined` for the chain's own. */
+        rpcUrl: string | undefined
+      }
+    | undefined
+}
+
+/**
+ * Returns the URL that a `RPC_URLS` entry gives the built-in chain `chainId`, or `undefined`. A list
+ * that does not parse logs a warning, so built-in chains still read.
+ */
+export function override(options: override.Options) {
+  const name = (Object.keys(ids) as (keyof typeof ids)[]).find(
+    (key) => ids[key] === options.chainId,
+  )
+  if (!name) return undefined
+
+  try {
+    return list({ value: options.rpcUrls }).find((entry) => entry.name === name)
+      ?.url
+  } catch (error) {
+    if (!(error instanceof InvalidListError)) throw error
+    Log.warn({ error, message: 'RPC_URLS does not parse.' })
+    return undefined
+  }
+}
+
+export declare namespace override {
+  type Options = {
+    /** The chain's ID. */
+    chainId: number
+    /** The value of `RPC_URLS`. */
+    rpcUrls: string | undefined
+  }
+}
+
+/**
+ * Returns the chains that `CONFIGURABLE_ACCOUNTS` names, in its order, each with its ID and RPC URL.
+ * A name that is neither built in nor listed is left out, as is a list that does not parse, since
+ * `App.create` refuses both when the Worker starts.
+ */
+export function configurable(
+  options: configurable.Options,
+): readonly configurable.Entry[] {
+  const names = (options.value ?? '')
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+
+  return names.flatMap((name) => {
+    const resolved = (() => {
+      try {
+        return resolve({
+          name,
+          rpcUrl: options.rpcUrl,
+          rpcUrls: options.rpcUrls,
+        })
+      } catch (error) {
+        if (error instanceof InvalidListError) return undefined
+        throw error
+      }
+    })()
+    if (!resolved) return []
+    return [{ chainId: resolved.chainId, name, rpcUrl: resolved.rpcUrl }]
+  })
+}
+
+export declare namespace configurable {
+  type Options = {
+    /** The value of `TEMPO_RPC_URL`. */
+    rpcUrl?: string | undefined
+    /** The value of `RPC_URLS`. */
+    rpcUrls: string | undefined
+    /** The value of `CONFIGURABLE_ACCOUNTS`: chain names, separated with commas. */
+    value: string | undefined
+  }
+
+  /** A chain whose accounts are configurable. */
+  type Entry = {
+    /** The chain's ID, one of {@link known}. */
+    chainId: number
+    /** The chain's name, which the `chain` parameter carries. */
+    name: string
+    /** The RPC URL that serves the chain, or `undefined` for the chain's own. */
+    rpcUrl: string | undefined
+  }
+}

package/src/internal/ChainName.ts

@@ -0,0 +1,14 @@
+/**
+ * The name of a Tempo chain in the `chain` parameter: `mainnet`, `testnet`, or a name that
+ * `RPC_URLS` lists. Pages read the parameter here, since `Chain` holds the chain definitions and the
+ * transaction code that they bring.
+ * @module
+ */
+
+/** A chain's name: up to 32 lowercase letters, digits, and dashes. */
+export const pattern = /^[a-z0-9][a-z0-9-]{0,31}$/
+
+/** Returns `value` if it is a chain's name, else `undefined`. */
+export function read(value: unknown) {
+  return typeof value === 'string' && pattern.test(value) ? value : undefined
+}

package/src/internal/ChainStatus.ts

@@ -0,0 +1,65 @@
+/**
+ * Probes whether a listed chain's node and Tempo API respond, for the dev toolbar.
+ * @module
+ */
+import { createClient, http } from 'viem'
+import { getChainId } from 'viem/actions'
+
+/** Milliseconds that each probe waits. */
+const timeout = 1_000
+
+/**
+ * Returns whether the node at `rpcUrl` serves `chainId`, and whether the Tempo API at `apiUrl`
+ * responds on `/health`. A failed probe reads as `down`, and logs nothing.
+ */
+export async function get(options: get.Options): Promise<get.ReturnType> {
+  const [api, node] = await Promise.all([
+    (async () => {
+      if (!options.apiUrl) return 'none' as const
+
+      // The API can sit under a path, such as behind a gateway, which a root-relative URL would drop.
+      // `/health` needs no key, and a URL that holds one cannot be fetched.
+      const url = new URL(options.apiUrl)
+      url.pathname = `${url.pathname.replace(/\/$/, '')}/health`
+      url.username = ''
+      url.password = ''
+
+      try {
+        const response = await fetch(url, {
+          signal: AbortSignal.timeout(timeout),
+        })
+        await response.body?.cancel()
+        return response.ok ? ('up' as const) : ('down' as const)
+      } catch {
+        return 'down' as const
+      }
+    })(),
+    (async () => {
+      const client = createClient({
+        transport: http(options.rpcUrl, { retryCount: 0, timeout }),
+      })
+      const chainId = await getChainId(client).catch(() => undefined)
+      return chainId === options.chainId ? ('up' as const) : ('down' as const)
+    })(),
+  ])
+
+  return { api, node }
+}
+
+export declare namespace get {
+  type Options = {
+    /** The chain's Tempo API URL, if `TEMPO_API_URLS` lists one. */
+    apiUrl: string | undefined
+    /** The chain that the node serves. */
+    chainId: number
+    /** The node's RPC URL. */
+    rpcUrl: string
+  }
+
+  type ReturnType = {
+    /** `up` when `/health` responds, `down` when it does not, and `none` without an API. */
+    api: 'down' | 'none' | 'up'
+    /** `up` when the node serves the chain, else `down`. */
+    node: 'down' | 'up'
+  }
+}