tapimo 0.14.0 → 0.15.1

package/src/internal/Viem.test.ts

@@ -1,7 +1,15 @@
 import { ZoneRpcAuthentication } from 'ox/tempo'
-import { defineChain, type Chain } from 'viem'
+import {
+  defineChain,
+  LimitExceededRpcError,
+  publicActions,
+  RpcRequestError,
+  type Chain,
+} from 'viem'
 import { tempoTestnet } from 'viem/tempo/chains'
 
+import * as TestRuntime from '../../test/runtime.js'
+import * as TestViem from '../../test/Viem.js'
 import type * as Auth from './Auth.js'
 import * as Viem from './Viem.js'
 
@@ -69,7 +77,150 @@ describe('configuredChainIds', () => {
   })
 })
 
+describe('requestFailure', () => {
+  test('returns bounded JSON-RPC diagnostics', () => {
+    const apiKey = `tempo:sk:${'ab'.repeat(28)}`
+    expect(
+      Viem.requestFailure(
+        new RpcRequestError({
+          body: { method: 'eth_call' },
+          error: { code: -32_000, message: `${apiKey}${'x'.repeat(500)}` },
+          url: 'https://credential.example.com',
+        }),
+      ),
+    ).toEqual({
+      code: 'RpcRequestError:-32000',
+      failure: 'query',
+      message: `tempo:sk:…${'x'.repeat(490)}`,
+    })
+  })
+
+  test('attributes EVM client failures to their chain', async () => {
+    const client = Viem.createEvmClient({
+      chainId: 8453,
+      fetch: async () =>
+        new Response(
+          JSON.stringify({
+            error: { code: -32_000, message: 'upstream failure' },
+            id: 1,
+            jsonrpc: '2.0',
+          }),
+          { headers: { 'content-type': 'application/json' } },
+        ),
+      urls: ['https://base.rpc.test'],
+    }).extend(publicActions)
+    const cause = await client.getChainId().catch((error: unknown) => error)
+
+    expect(Viem.requestFailure(cause)).toEqual({
+      chainId: 8453,
+      code: 'InvalidInputRpcError:-32000',
+      failure: 'query',
+      message: 'upstream failure',
+    })
+  })
+
+  test.each([
+    {
+      cause: new LimitExceededRpcError(
+        new RpcRequestError({
+          body: { method: 'eth_call' },
+          error: { code: -32_005, message: 'rate limited' },
+          url: 'https://base.rpc.test',
+        }),
+      ),
+      code: 'LimitExceededRpcError:-32005',
+    },
+    {
+      cause: new RpcRequestError({
+        body: { method: 'eth_call' },
+        error: { code: 429, message: 'rate limited' },
+        url: 'https://base.rpc.test',
+      }),
+      code: 'RpcRequestError:429',
+    },
+  ])('classifies JSON-RPC limit errors as rate limits %#', ({ cause, code }) => {
+    expect(Viem.requestFailure(cause)).toEqual({
+      code,
+      failure: 'rate_limit',
+      message: 'rate limited',
+    })
+  })
+})
+
 describe('resolveRpc', () => {
+  test('never infers a public endpoint from Zone metadata', () => {
+    for (const rpc of [undefined, {}, { publicZoneUrl: {} }, () => ({})])
+      expect(Viem.resolveRpc(rpc, { chainId: zone.id, principal: publicPrincipal, zone }))
+        .toMatchInlineSnapshot(`
+          {
+            "basicAuth": undefined,
+            "url": "https://internal.zone.rpc.test",
+          }
+        `)
+  })
+
+  test('rejects public URLs that identify a configured or metadata internal endpoint', () => {
+    for (const publicZoneUrl of [
+      'https://internal.zone.rpc.test',
+      'https://INTERNAL.ZONE.RPC.TEST:443/?public=true#rpc',
+      'https://internal.zone.rpc.test/public',
+      'https://override.zone.rpc.test',
+      'https://override.zone.rpc.test/',
+      'https://user:secret@public.zone.rpc.test',
+      'not a URL',
+      'file:///rpc',
+    ])
+      expect(
+        Viem.resolveRpc(
+          { publicZoneUrl, url: 'https://override.zone.rpc.test' },
+          { chainId: zone.id, principal: publicPrincipal, zone },
+        ).publicZoneUrl,
+      ).toBeUndefined()
+  })
+
+  test('canonicalizes internal hostnames before comparing public endpoints', () => {
+    for (const [url, publicZoneUrl] of [
+      ['https://internal.zone.rpc.test', 'https://internal.zone.rpc.test.'],
+      ['https://internal.zone.rpc.test.', 'https://internal.zone.rpc.test'],
+      ['https://internal.zone.rpc.test:8443', 'https://INTERNAL.ZONE.RPC.TEST.:8443/public'],
+      ['https://internal.zone.rpc.test', 'https://internal.zone.rpc.test.:443'],
+      ['https://override.zone.rpc.test.', 'http://override.zone.rpc.test:443'],
+    ])
+      expect(
+        Viem.resolveRpc(
+          { publicZoneUrl, url },
+          { chainId: zone.id, principal: publicPrincipal, zone },
+        ).publicZoneUrl,
+      ).toBeUndefined()
+
+    expect(
+      Viem.resolveRpc(
+        { publicZoneUrl: 'https://internal.zone.rpc.test.:8443' },
+        { chainId: zone.id, principal: publicPrincipal, zone },
+      ).publicZoneUrl,
+    ).toBe('https://internal.zone.rpc.test.:8443')
+  })
+
+  test('compares effective ports across public and internal RPC schemes', () => {
+    for (const [url, publicZoneUrl, allowed] of [
+      ['http://shared.zone.test', 'https://shared.zone.test', true],
+      ['https://shared.zone.test', 'http://shared.zone.test', true],
+      ['http://shared.zone.test:80', 'https://shared.zone.test:443', true],
+      ['http://shared.zone.test', 'https://shared.zone.test:80', false],
+      ['https://shared.zone.test:80', 'http://shared.zone.test', false],
+      ['https://shared.zone.test', 'http://shared.zone.test:443', false],
+      ['http://shared.zone.test:443', 'https://shared.zone.test', false],
+      ['http://shared.zone.test.', 'http://shared.zone.test:80', false],
+      ['https://shared.zone.test.', 'https://shared.zone.test:443', false],
+    ] as const)
+      expect(
+        Viem.resolveRpc(
+          { publicZoneUrl, url },
+          { chainId: zone.id, principal: publicPrincipal, zone },
+        ).publicZoneUrl,
+      ).toBe(allowed ? publicZoneUrl : undefined)
+  })
+
   test('defaults to the per-chain RPC URL', () => {
     expect(Viem.resolveRpc(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
       {
@@ -212,7 +363,6 @@ describe('resolveRpc', () => {
       .toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
-        "publicZoneUrl": "https://zone.rpc.test",
         "url": "https://internal.zone.rpc.test",
       }
     `)
@@ -220,6 +370,19 @@ describe('resolveRpc', () => {
 })
 
 describe('getClient', () => {
+  test('rejects a caller token without a public endpoint before constructing a transport', () => {
+    expect(() =>
+      Viem.getClient({
+        chainId: zone.id,
+        rpc: { auth: 'internal:secret' },
+        zone,
+        zoneToken: 'unvalidated-token',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Viem.PublicZoneRpcUnavailableError: Public Zone RPC is unavailable.]`,
+    )
+  })
+
   test('disables CCIP-Read', () => {
     expect(Viem.getClient({ chainId: 4217 }).ccipRead).toBe(false)
   })
@@ -307,6 +470,42 @@ describe('getClient', () => {
   })
 })
 
+describe('createBatchClient', () => {
+  test('preserves caller cancellation without cancelling unrelated requests', async () => {
+    const client = Viem.createBatchClient({
+      chainId: TestRuntime.get().chainId,
+      rpc: TestViem.rpc,
+    })
+    const controller = new AbortController()
+    controller.abort()
+    const [cancelled, active] = await Promise.allSettled([
+      client.request({ method: 'eth_blockNumber' }, { retryCount: 0, signal: controller.signal }),
+      client.request({ method: 'eth_blockNumber' }),
+    ])
+    expect({ active: active.status, cancelled: cancelled.status }).toMatchInlineSnapshot(`
+      {
+        "active": "fulfilled",
+        "cancelled": "rejected",
+      }
+    `)
+    if (cancelled.status === 'rejected')
+      expect(cancelled.reason).toHaveProperty('name', 'AbortError')
+  })
+
+  test('rejects caller tokens when the public endpoint resolves to the internal node', () => {
+    expect(() =>
+      Viem.createBatchClient({
+        chainId: zone.id,
+        rpc: { publicZoneUrl: 'https://internal.zone.rpc.test' },
+        zone,
+        zoneToken: 'unvalidated-token',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Viem.PublicZoneRpcUnavailableError: Public Zone RPC is unavailable.]`,
+    )
+  })
+})
+
 describe('createGetClient', () => {
   test('memoizes one client per resolved upstream', () => {
     const getClient = Viem.createGetClient({

package/src/internal/Viem.ts

@@ -1,10 +1,23 @@
 import { ZoneRpcAuthentication } from 'ox/tempo'
-import { createClient as core_createClient, fallback, http, publicActions } from 'viem'
+import {
+  BaseError,
+  createClient as core_createClient,
+  fallback,
+  HttpRequestError,
+  http,
+  LimitExceededRpcError,
+  publicActions,
+  RpcError,
+  RpcRequestError,
+  TimeoutError,
+  withTimeout,
+} from 'viem'
 import type {
   Chain as core_Chain,
   Client as core_Client,
   FallbackTransport,
   HttpTransport,
+  HttpTransportConfig,
   PublicActions,
 } from 'viem'
 import { tempoActions } from 'viem/tempo'
@@ -12,12 +25,13 @@ import type { TempoActions } from 'viem/tempo'
 import { tempoMainnet, tempoTestnet } from 'viem/tempo/chains'
 import type * as z from 'zod/mini'
 
+import * as ApiKey from '../ApiKey.js'
 import type * as Auth from './Auth.js'
 import * as Credential from './Credential.js'
 import type * as Schema from './Schema.js'
 
 /** Known Tempo chains keyed by id, for metadata lookups. */
-export const chains = [tempoMainnet, tempoTestnet]
+export const chains: readonly core_Chain[] = [tempoMainnet, tempoTestnet]
 
 /** Tempo chain ids keyed by network. */
 export const chainId = {
@@ -59,22 +73,39 @@ export type ZoneHeaders = Record<string, string>
 
 /** Creates a generic EVM client with ordered RPC endpoint fallback. */
 export function createEvmClient(options: createEvmClient.Options): createEvmClient.ReturnType {
-  return core_createClient({
-    transport: fallback(
-      options.urls.map((url) =>
-        http(url, {
-          fetchFn: options.fetch,
-          ...(options.signal ? { fetchOptions: { signal: options.signal } } : {}),
-          retryCount: 0,
-        }),
-      ),
+  const fallback_transport = fallback(
+    options.urls.map((url) =>
+      http(url, {
+        fetchFn: options.fetch,
+        ...(options.signal ? { fetchOptions: { signal: options.signal } } : {}),
+        retryCount: 0,
+      }),
     ),
-  })
+  )
+  const chainId = options.chainId
+  const transport: FallbackTransport = (parameters) => {
+    const value = fallback_transport(parameters)
+    if (chainId === undefined) return value
+    return {
+      ...value,
+      async request(parameters_request, options_request) {
+        try {
+          return await value.request(parameters_request, options_request)
+        } catch (cause) {
+          if (!(cause instanceof Error)) throw cause
+          throw new EvmClientRequestError(cause, chainId)
+        }
+      },
+    }
+  }
+  return core_createClient({ transport })
 }
 
 export declare namespace createEvmClient {
   /** Generic EVM RPC client configuration. */
   type Options = {
+    /** EIP-155 chain id attached to request failures. */
+    chainId?: number | undefined
     /** Fetch implementation used for RPC requests. */
     fetch: typeof globalThis.fetch
     /** Optional request cancellation signal. */
@@ -87,6 +118,63 @@ export declare namespace createEvmClient {
   type ReturnType = core_Client<FallbackTransport, undefined, undefined>
 }
 
+/** Returns bounded diagnostics for a viem request failure. */
+export function requestFailure(cause: unknown): requestFailure.Result | undefined {
+  if (!(cause instanceof BaseError)) return undefined
+  const root = cause.walk()
+  const request = cause.walk((error) => error instanceof EvmClientRequestError)
+  const http = cause.walk((error) => error instanceof HttpRequestError)
+  const rpc = cause.walk((error) => error instanceof RpcError || error instanceof RpcRequestError)
+  const type = (() => {
+    if (rpc instanceof RpcError || rpc instanceof RpcRequestError) return rpc.name
+    if (http instanceof HttpRequestError) return http.name
+    return root.name
+  })()
+  const code = `${type}${rpc instanceof RpcError || rpc instanceof RpcRequestError ? `:${rpc.code}` : ''}`
+  const failure = (() => {
+    if (
+      root instanceof TimeoutError ||
+      (root instanceof DOMException && root.name === 'AbortError')
+    )
+      return 'timeout'
+    if (
+      rpc instanceof LimitExceededRpcError ||
+      (rpc instanceof RpcRequestError && rpc.code === 429)
+    )
+      return 'rate_limit'
+    if (http instanceof HttpRequestError && http.status === 429) return 'rate_limit'
+    if (http instanceof HttpRequestError && http.status !== undefined) return 'http'
+    if (rpc instanceof RpcError || rpc instanceof RpcRequestError) return 'query'
+    if (root instanceof TypeError || http instanceof HttpRequestError) return 'network'
+    return 'unknown'
+  })()
+  return {
+    ...(request instanceof EvmClientRequestError ? { chainId: request.chainId } : {}),
+    code: /^[A-Za-z0-9_.:-]{1,64}$/.test(code) ? code : 'UnknownError',
+    failure,
+    message: ApiKey.redact(root.message).slice(0, 500),
+    ...(http instanceof HttpRequestError && http.status !== undefined
+      ? { status: http.status }
+      : {}),
+  }
+}
+
+export declare namespace requestFailure {
+  /** Bounded viem request failure details. */
+  type Result = {
+    /** EIP-155 chain whose RPC request failed. */
+    chainId?: number | undefined
+    /** Stable error class and JSON-RPC code. */
+    code: string
+    /** Failure boundary inferred from the viem cause chain. */
+    failure: 'http' | 'network' | 'query' | 'rate_limit' | 'timeout' | 'unknown'
+    /** Root-cause error message. */
+    message: string
+    /** Upstream HTTP status, when a response was received. */
+    status?: number | undefined
+  }
+}
+
 /** Returns chain ids declared by a static chain-id-to-URL map. */
 export function configuredChainIds(value: UrlResolver | undefined): number[] {
   const urls = parseUrls(value)
@@ -117,18 +205,46 @@ export function resolveRpc(
 ): resolveRpc.Resolved {
   const config = typeof rpc === 'function' ? rpc(context) : rpc
   const auth = Credential.resolveCredential({ chainId: context.chainId, value: config?.auth })
-  const publicZoneUrl = context.zone
-    ? (resolveUrl(config?.publicZoneUrl, context.chainId) ?? context.zone.rpcUrls.default.http[0])
-    : undefined
+  const resolvedUrl =
+    resolveUrl(config?.url, context.chainId) ??
+    context.zone?.rpcUrls['internal']?.http[0] ??
+    context.zone?.rpcUrls.default.http[0] ??
+    url[context.chainId]
+  const publicZoneUrl = (() => {
+    if (!context.zone) return undefined
+    const value = resolveUrl(config?.publicZoneUrl, context.chainId)
+    if (!value) return undefined
+    try {
+      const publicUrl = new URL(value)
+      if (
+        !['http:', 'https:'].includes(publicUrl.protocol) ||
+        publicUrl.username ||
+        publicUrl.password
+      )
+        return undefined
+      const port_public = publicUrl.port || (publicUrl.protocol === 'https:' ? '443' : '80')
+      // Internal nodes may ignore URL paths, and trailing DNS dots identify the same host.
+      const internalUrls = context.zone.rpcUrls['internal'] ?? context.zone.rpcUrls.default
+      for (const value of [resolvedUrl, ...internalUrls.http]) {
+        if (!value) continue
+        const internalUrl = new URL(value)
+        const port_internal = internalUrl.port || (internalUrl.protocol === 'https:' ? '443' : '80')
+        if (
+          publicUrl.hostname.replace(/\.$/, '') === internalUrl.hostname.replace(/\.$/, '') &&
+          port_public === port_internal
+        )
+          return undefined
+      }
+      return value
+    } catch {
+      return undefined
+    }
+  })()
   return {
     ...auth,
     ...(publicZoneUrl ? { publicZoneUrl } : {}),
     ...(context.zone && config?.zoneHeaders ? { zoneHeaders: config.zoneHeaders } : {}),
-    url:
-      resolveUrl(config?.url, context.chainId) ??
-      context.zone?.rpcUrls['internal']?.http[0] ??
-      context.zone?.rpcUrls.default.http[0] ??
-      url[context.chainId],
+    url: resolvedUrl,
   }
 }
 
@@ -153,7 +269,7 @@ export declare namespace resolveRpc {
     basicAuth?: string | undefined
     /** Bearer auth credential, or undefined to send no Bearer auth. */
     bearerAuth?: string | undefined
-    /** Public Zone RPC URL that accepts a caller-provided authorization token. */
+    /** Explicit public Zone RPC URL, absent when missing, invalid, or matching the selected Zone's internal endpoints. */
     publicZoneUrl?: string | undefined
     /** Headers sent to Zone RPC upstreams. */
     zoneHeaders?: ZoneHeaders | undefined
@@ -167,13 +283,64 @@ export declare namespace resolveRpc {
 }
 
 export function getClient(options: getClient.Options): getClient.ReturnType {
+  return createTempoClient(options, (url, fetchOptions) =>
+    http(url, fetchOptions ? { fetchOptions } : {}),
+  )
+}
+
+/** Creates a request-local Tempo client that batches JSON-RPC calls over HTTP. */
+export function createBatchClient(options: getClient.Options): getClient.ReturnType {
+  const signal = new AbortController().signal
+  const signals = new WeakMap<AbortSignal, AbortSignal>()
+  return createTempoClient(options, (url, fetchOptions) => (parameters) => {
+    const timeout = parameters.timeout ?? 10_000
+    const value = http(url, {
+      batch: true,
+      // Request signals isolate batches but replace viem's deadline signal, so compose the deadline at fetch time.
+      fetchFn: (input, init) =>
+        withTimeout(
+          ({ signal: signal_timeout }) =>
+            fetch(input, {
+              ...init,
+              signal: AbortSignal.any([signal_timeout!, init?.signal ?? signal]),
+            }),
+          {
+            errorInstance: new TimeoutError({
+              body: JSON.parse(init!.body as string),
+              url: input instanceof Request ? input.url : String(input),
+            }),
+            signal: true,
+            timeout,
+          },
+        ),
+      ...(fetchOptions ? { fetchOptions } : {}),
+      timeout,
+    })(parameters)
+    return {
+      ...value,
+      request(parameters_request, options_request) {
+        // Viem keys HTTP batch queues by URL and signal, so cancellation signals must stay client-local.
+        const signal_request = options_request?.signal
+        if (signal_request && !signals.has(signal_request))
+          signals.set(signal_request, AbortSignal.any([signal, signal_request]))
+        return value.request(parameters_request, {
+          ...options_request,
+          signal: signal_request ? signals.get(signal_request)! : signal,
+        })
+      },
+    }
+  })
+}
+
+function createTempoClient(options: getClient.Options, transport: createTempoClient.Transport) {
   const { chainId = defaultChainId, principal = null, rpc, zone, zoneToken } = options
   const { basicAuth, bearerAuth, publicZoneUrl, url, zoneHeaders } = resolveRpc(rpc, {
     chainId,
     principal,
     zone,
   })
-  const usePublicZoneUrl = Boolean(zoneToken && publicZoneUrl)
+  const usePublicZoneUrl = Boolean(zoneToken)
+  if (usePublicZoneUrl && !publicZoneUrl) throw new PublicZoneRpcUnavailableError()
   const rpcUrl = usePublicZoneUrl ? publicZoneUrl : url
   // Public Zone endpoints authenticate with the caller's token, never internal RPC credentials.
   const authorization = usePublicZoneUrl
@@ -191,6 +358,8 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
             ...(authorization ? { Authorization: authorization } : {}),
             ...(zoneToken ? { [ZoneRpcAuthentication.headerName]: zoneToken } : {}),
           },
+          // Redirects must not forward caller credentials to internal nodes.
+          ...(usePublicZoneUrl ? { redirect: 'manual' as const } : {}),
         }
       : undefined
 
@@ -204,12 +373,19 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
     batch: { multicall: zone ? false : { deployless: true } },
     ccipRead: false,
     chain: { ...tempoMainnet, id: chainId },
-    transport: http(rpcUrl, fetchOptions ? { fetchOptions } : {}),
+    transport: transport(rpcUrl, fetchOptions),
   })
     .extend(publicActions)
     .extend(tempoActions())
 }
 
+declare namespace createTempoClient {
+  type Transport = (
+    url: string | undefined,
+    fetchOptions: HttpTransportConfig['fetchOptions'],
+  ) => HttpTransport
+}
+
 /** Builds a memoized Tempo client resolver. */
 export function createGetClient(options: createGetClient.Options = {}): createGetClient.ReturnType {
   const { defaultChainId: defaultChainId_option = defaultChainId, rpc } = options
@@ -289,7 +465,7 @@ export declare namespace getClient {
     | {
         /** Shared or per-chain RPC credentials. Values containing `:` use Basic auth; others use Bearer auth. */
         auth?: Credential.ChainCredential | undefined
-        /** Resolves the public Zone RPC URL used with caller-provided authorization. */
+        /** Explicit token-validating Zone RPC URL. Must have a distinct host or port from the selected Zone's internal endpoints. */
         publicZoneUrl?: UrlResolver | undefined
         /** Headers sent to Zone RPC upstreams. */
         zoneHeaders?: ZoneHeaders | undefined
@@ -299,7 +475,7 @@ export declare namespace getClient {
     | ((context: resolveRpc.Context) => {
         /** Shared or per-chain RPC credentials, or undefined for none. */
         auth?: Credential.ChainCredential | undefined
-        /** Public Zone RPC URL used with caller-provided authorization. */
+        /** Explicit token-validating Zone RPC URL. Must have a distinct host or port from the selected Zone's internal endpoints. */
         publicZoneUrl?: string | undefined
         /** Headers sent to Zone RPC upstreams. */
         zoneHeaders?: ZoneHeaders | undefined
@@ -343,3 +519,23 @@ function parseUrls(value: UrlResolver | undefined): Record<number, string> | str
     throw new Error('Expected a URL or a chain-id-to-URL JSON object.')
   return urls as Record<number, string>
 }
+
+/** A caller-authorized Zone request has no safe public RPC endpoint. */
+export class PublicZoneRpcUnavailableError extends Error {
+  override name = 'Viem.PublicZoneRpcUnavailableError'
+
+  constructor() {
+    super('Public Zone RPC is unavailable.')
+  }
+}
+
+class EvmClientRequestError extends BaseError {
+  override name = 'Viem.EvmClientRequestError'
+
+  constructor(
+    cause: Error,
+    readonly chainId: number,
+  ) {
+    super('EVM RPC request failed.', { cause })
+  }
+}