prool 0.2.5 → 0.2.7

package/src/testcontainers/Instance.test.ts

@@ -1,6 +1,6 @@
 import getPort from 'get-port'
 import { Instance } from 'prool/testcontainers'
-import { afterEach, expect, test } from 'vitest'
+import { afterEach, describe, expect, test } from 'vitest'
 
 const instances: Instance.Instance[] = []
 const slowTestTimeout = 30_000
@@ -125,3 +125,67 @@ test('behavior: faucet funds address', { timeout: 120_000 }, async () => {
   }
   expect(balance).toBeGreaterThan(0n)
 })
+
+// Requires a `tempo-zone` image with the `dev` command and GHCR access
+// (the package is private), e.g. `VITE_TEMPO_ZONE_IMAGE=ghcr.io/tempoxyz/tempo-zone:latest`.
+const tempoZoneImage = process.env['VITE_TEMPO_ZONE_IMAGE']
+const zonePort = await getPort()
+
+describe.runIf(tempoZoneImage)('tempoZone', () => {
+  const defineZoneInstance = (
+    parameters: Instance.tempoZone.Parameters = {},
+  ) => {
+    const instance = Instance.tempoZone({
+      image: tempoZoneImage,
+      port: zonePort,
+      startupTimeout: 120_000,
+      ...parameters,
+    })
+    instances.push(instance)
+    return instance
+  }
+
+  test('default', { timeout: 300_000 }, async () => {
+    const instance = defineZoneInstance()
+
+    await instance.start()
+    expect(instance.status).toEqual('started')
+
+    const rpc = async (method: string, params: unknown[]) => {
+      const response = await fetch(`http://${instance.host}:${instance.port}`, {
+        body: JSON.stringify({ id: 0, jsonrpc: '2.0', method, params }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'POST',
+      })
+      return await response.json()
+    }
+
+    // Zone chain IDs are derived: ZONE_CHAIN_ID_BASE + (zone_id % range).
+    const { result: chainId } = await rpc('eth_chainId', [])
+    expect(BigInt(chainId)).toBeGreaterThanOrEqual(421_700_000n)
+
+    const { result: blockNumber } = await rpc('eth_blockNumber', [])
+    expect(blockNumber).toBeDefined()
+
+    // Private RPC (auth-gated `eth_*` + `zone_*`) is exposed; reachability only (no token).
+    const { privateRpc } = instance._internal
+    expect(privateRpc).toBeDefined()
+    const response = await fetch(
+      `http://${privateRpc!.host}:${privateRpc!.port}`,
+      {
+        body: JSON.stringify({
+          id: 0,
+          jsonrpc: '2.0',
+          method: 'zone_getZoneInfo',
+          params: [],
+        }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'POST',
+      },
+    )
+    expect(response.status).toBeDefined()
+
+    await instance.stop()
+    expect(instance.status).toEqual('stopped')
+  })
+})

package/src/testcontainers/Instance.ts

@@ -1,11 +1,17 @@
 import {
   GenericContainer,
+  Network,
   PullPolicy,
+  type StartedNetwork,
   type StartedTestContainer,
   Wait,
 } from 'testcontainers'
 import * as Instance from '../Instance.js'
 import { command, type tempo as core_tempo } from '../instances/tempo.js'
+import {
+  type tempoZone as core_tempoZone,
+  command as zoneCommand,
+} from '../instances/tempoZone.js'
 import * as ContainerOptions from './containerOptions.js'
 
 export type { Instance, InstanceOptions } from '../Instance.js'
@@ -131,3 +137,239 @@ export declare namespace tempo {
       port?: number | undefined
     }
 }
+
+/**
+ * Defines a Tempo Zone instance.
+ *
+ * Starts a Tempo dev L1 container and a zone container (`tempo-zone dev`) on a
+ * shared network, provisioning a fresh zone against the L1. Pass `l1.rpcUrl`
+ * to attach to an existing L1 instead (the URL must be reachable from inside
+ * the container, e.g. `ws://host.docker.internal:8546`).
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.tempoZone({ port: 9545 })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const tempoZone = Instance.define(
+  (parameters?: tempoZone.Parameters) => {
+    const {
+      containerName = `tempo-zone.${crypto.randomUUID()}`,
+      image = 'ghcr.io/tempoxyz/tempo-zone:latest',
+      l1: l1Parameters,
+      log: log_,
+      startupTimeout,
+      ...args
+    } = parameters || {}
+
+    const log = (() => {
+      try {
+        return JSON.parse(log_ as string)
+      } catch {
+        return log_
+      }
+    })()
+    const RUST_LOG = log && typeof log !== 'boolean' ? log : ''
+
+    // L1 ports inside the container (only reachable over the shared network).
+    const l1HttpPort = 8545
+    const l1WsPort = 8546
+
+    const name = 'tempo-zone'
+    let container: StartedTestContainer | undefined
+    let l1Container: StartedTestContainer | undefined
+    let network: StartedNetwork | undefined
+    let privateRpcPort: number | undefined
+
+    async function teardown() {
+      if (container) await container.stop().catch(() => {})
+      if (l1Container) await l1Container.stop().catch(() => {})
+      if (network) await network.stop().catch(() => {})
+      container = undefined
+      l1Container = undefined
+      network = undefined
+      privateRpcPort = undefined
+    }
+
+    return {
+      _internal: {
+        args,
+        get l1() {
+          if (!l1Container) return undefined
+          return {
+            host: l1Container.getHost(),
+            port: l1Container.getMappedPort(l1HttpPort),
+            wsPort: l1Container.getMappedPort(l1WsPort),
+          }
+        },
+        get privateRpc() {
+          if (!container || !privateRpcPort) return undefined
+          return {
+            host: container.getHost(),
+            port: container.getMappedPort(privateRpcPort),
+          }
+        },
+      },
+      host: args.host ?? 'localhost',
+      name,
+      port: args.port ?? 9545,
+      async start({ port = args.port }, { emitter, setEndpoint }) {
+        const containerPort = port ?? 9545
+        // Mirrors the `zoneCommand` default; serves authenticated `eth_*` + `zone_*`.
+        privateRpcPort =
+          (args['privateRpc'] as { port?: number } | undefined)?.port ??
+          containerPort + 3
+        const timeout = ContainerOptions.resolveStartupTimeout(startupTimeout)
+
+        const logConsumer =
+          (reject: (error: Error) => void) =>
+          (stream: NodeJS.ReadableStream) => {
+            stream.on('data', (data) => {
+              const message = data.toString()
+              emitter.emit('message', message)
+              emitter.emit('stdout', message)
+              if (log) console.log(message)
+              if (message.includes('shutting down'))
+                reject(new Error(`Failed to start: ${message}`))
+            })
+            stream.on('error', (error) => {
+              if (log) console.error(error.message)
+              emitter.emit('message', error.message)
+              emitter.emit('stderr', error.message)
+              reject(new Error(`Failed to start: ${error.message}`))
+            })
+          }
+
+        try {
+          // Start a dev L1 on a shared network unless attaching to an existing one.
+          let l1RpcUrl = l1Parameters?.rpcUrl
+          if (!l1RpcUrl) {
+            network = await new Network().start()
+            l1Container = await new GenericContainer(
+              l1Parameters?.image ?? 'ghcr.io/tempoxyz/tempo:latest',
+            )
+              .withPullPolicy(PullPolicy.alwaysPull())
+              .withPlatform('linux/x86_64')
+              .withNetwork(network)
+              .withNetworkAliases('l1')
+              .withExposedPorts(l1HttpPort, l1WsPort)
+              .withName(`${containerName}.l1`)
+              .withEnvironment({ RUST_LOG })
+              .withCommand(
+                command({
+                  port: l1HttpPort,
+                  // The zone anchors to the L1 over WebSocket.
+                  ws: [true, { addr: '0.0.0.0', api: 'all', port: l1WsPort }],
+                }),
+              )
+              .withWaitStrategy(
+                Wait.forLogMessage(
+                  /Received (block|new payload) from consensus engine/,
+                ),
+              )
+              .withLogConsumer(
+                logConsumer(() => {
+                  // L1 shutdown surfaces via the zone container failing to start.
+                }),
+              )
+              .withStartupTimeout(timeout)
+              .start()
+            l1RpcUrl = `ws://l1:${l1WsPort}`
+          }
+
+          const promise = Promise.withResolvers<void>()
+
+          let c = new GenericContainer(image)
+            .withPullPolicy(PullPolicy.alwaysPull())
+            .withPlatform('linux/x86_64')
+            .withExposedPorts(containerPort, privateRpcPort)
+            .withExtraHosts([
+              { host: 'host.docker.internal', ipAddress: 'host-gateway' },
+            ])
+            .withName(containerName)
+            .withEnvironment({ RUST_LOG })
+            .withCommand(
+              zoneCommand({
+                ...args,
+                l1: {
+                  ...(l1Parameters?.factoryAddress
+                    ? { factoryAddress: l1Parameters.factoryAddress }
+                    : {}),
+                  rpcUrl: l1RpcUrl,
+                },
+                port: containerPort,
+              }),
+            )
+            // Fires after the public RPC; last server to start.
+            .withWaitStrategy(
+              Wait.forLogMessage('Private zone RPC server started'),
+            )
+            .withLogConsumer(logConsumer(promise.reject))
+            .withStartupTimeout(timeout)
+          if (network) c = c.withNetwork(network)
+
+          c.start()
+            .then((started) => {
+              container = started
+              setEndpoint?.({
+                host: started.getHost(),
+                port: started.getMappedPort(containerPort),
+              })
+              promise.resolve()
+            })
+            .catch(promise.reject)
+
+          await promise.promise
+        } catch (error) {
+          await teardown()
+          throw error
+        }
+      },
+      async stop() {
+        await teardown()
+      },
+    }
+  },
+)
+
+export declare namespace tempoZone {
+  export type Parameters = Omit<core_tempoZone.Parameters, 'binary' | 'l1'> &
+    ContainerOptions.Parameters & {
+      /**
+       * Name of the container.
+       */
+      containerName?: string | undefined
+      /**
+       * Docker image to use for the zone node.
+       */
+      image?: string | undefined
+      /**
+       * Host the server will listen on.
+       */
+      host?: string | undefined
+      /**
+       * Tempo L1 options.
+       */
+      l1?:
+        | (NonNullable<core_tempoZone.Parameters['l1']> & {
+            /**
+             * Docker image to use for the L1 node (when no `rpcUrl` is provided).
+             */
+            image?: string | undefined
+            /**
+             * Existing Tempo L1 WebSocket RPC URL, reachable from inside the
+             * container (e.g. `ws://host.docker.internal:8546`). Starts a
+             * dev L1 container when omitted.
+             */
+            rpcUrl?: string | undefined
+          })
+        | undefined
+      /**
+       * Port the server will listen on.
+       */
+      port?: number | undefined
+    }
+}