prool 0.0.0 → 0.0.2

package/pool.ts

@@ -0,0 +1,183 @@
+import getPort from 'get-port'
+
+import type { Instance } from './instance.js'
+
+type Instance_ = Omit<Instance, 'create'>
+
+export type Pool<key = number> = Pick<
+  Map<key, Instance_>,
+  'entries' | 'keys' | 'forEach' | 'get' | 'has' | 'size' | 'values'
+> & {
+  _internal: {
+    instance: Instance_
+  }
+  destroy(key: key): Promise<void>
+  destroyAll(): Promise<void>
+  start(key: key, options?: { port?: number }): Promise<Instance_>
+  stop(key: key): Promise<void>
+  stopAll(): Promise<void>
+}
+
+export type DefinePoolParameters = {
+  /** Instance for the pool. */
+  instance: Instance
+  /** The maximum number of instances that can be started. */
+  limit?: number | number
+}
+
+export type DefinePoolReturnType<key = number> = Pool<key>
+
+/**
+ * Defines an instance pool. Instances can be started, cached, and stopped against an identifier.
+ *
+ * @example
+ * ```
+ * const pool = definePool({
+ *  instance: anvil(),
+ * })
+ *
+ * const instance_1 = await pool.start(1)
+ * const instance_2 = await pool.start(2)
+ * const instance_3 = await pool.start(3)
+ * ```
+ */
+export function definePool<key = number>(
+  parameters: DefinePoolParameters,
+): DefinePoolReturnType<key> {
+  const { instance, limit } = parameters
+
+  type Instance_ = Omit<Instance, 'create'>
+  const instances = new Map<key, Instance_>()
+
+  // Define promise instances for mutators to avoid race conditions, and return
+  // identical instances of the promises (instead of duplicating them).
+  // We utilize `Promise.withResolvers` instead of `new Promise((resolve, reject) => ...)`
+  // to avoid async Promise executor functions (https://biomejs.dev/linter/rules/no-async-promise-executor/).
+  const promises = {
+    destroy: new Map<key, Promise<void>>(),
+    destroyAll: undefined as Promise<void> | undefined,
+    start: new Map<key, Promise<Instance_>>(),
+    stop: new Map<key, Promise<void>>(),
+    stopAll: undefined as Promise<void> | undefined,
+  }
+
+  return {
+    _internal: {
+      instance,
+    },
+    async destroy(key) {
+      const destroyPromise = promises.destroy.get(key)
+      if (destroyPromise) return destroyPromise
+
+      const resolver = Promise.withResolvers<void>()
+
+      try {
+        promises.destroy.set(key, resolver.promise)
+
+        await this.stop(key)
+        instances.delete(key)
+
+        resolver.resolve()
+      } catch (error) {
+        resolver.reject(error)
+      }
+
+      return resolver.promise
+    },
+    async destroyAll() {
+      if (promises.destroyAll) return promises.destroyAll
+
+      const resolver = Promise.withResolvers<void>()
+
+      try {
+        promises.destroyAll = resolver.promise
+
+        await Promise.all([...instances.keys()].map((key) => this.destroy(key)))
+
+        promises.destroyAll = undefined
+
+        resolver.resolve()
+      } catch (error) {
+        resolver.reject(error)
+      }
+    },
+    async start(key, options = {}) {
+      const startPromise = promises.start.get(key)
+      if (startPromise) return startPromise
+
+      const resolver = Promise.withResolvers<Instance_>()
+
+      try {
+        promises.start.set(key, resolver.promise)
+
+        if (limit && instances.size >= limit)
+          throw new Error(`Instance limit of ${limit} reached.`)
+
+        const { port = await getPort() } = options
+
+        const instance_ = instances.get(key) || instance.create({ port })
+        await instance_.start()
+
+        instances.set(key, instance_)
+        resolver.resolve(instance_)
+      } catch (error) {
+        resolver.reject(error)
+      } finally {
+        promises.start.delete(key)
+      }
+
+      return resolver.promise
+    },
+    async stop(key) {
+      const stopPromise = promises.stop.get(key)
+      if (stopPromise) return stopPromise
+
+      const resolver = Promise.withResolvers<void>()
+
+      try {
+        promises.stop.set(key, resolver.promise)
+
+        const instance_ = instances.get(key)
+        if (!instance_) {
+          resolver.resolve()
+          return
+        }
+
+        await instance_.stop()
+
+        resolver.resolve()
+      } catch (error) {
+        resolver.reject(error)
+      } finally {
+        promises.stop.delete(key)
+      }
+    },
+    async stopAll() {
+      if (promises.stopAll) return promises.stopAll
+
+      const resolver = Promise.withResolvers<void>()
+
+      try {
+        promises.stopAll = resolver.promise
+
+        await Promise.all([...instances.keys()].map((key) => this.stop(key)))
+
+        promises.stopAll = undefined
+
+        resolver.resolve()
+      } catch (error) {
+        resolver.reject(error)
+      }
+    },
+
+    get size() {
+      return instances.size
+    },
+    entries: instances.entries.bind(instances),
+    keys: instances.keys.bind(instances),
+    forEach: instances.forEach.bind(instances),
+    get: instances.get.bind(instances).bind(instances),
+    has: instances.has.bind(instances),
+    values: instances.values.bind(instances),
+  }
+}

package/server.test.ts

@@ -0,0 +1,294 @@
+import { describe, expect, test } from 'vitest'
+import { type MessageEvent, WebSocket } from 'ws'
+import { anvil } from './instances/anvil.js'
+import { createServer } from './server.js'
+
+describe.each([{ instance: anvil() }])(
+  'instance: $instance.name',
+  ({ instance }) => {
+    test('default', async () => {
+      const pool = createServer({
+        instance,
+      })
+      expect(pool).toBeDefined()
+
+      await pool.start()
+      expect(pool.address()).toBeDefined()
+
+      // Stop via instance method.
+      await pool.stop()
+      expect(pool.address()).toBeNull()
+
+      const stop = await pool.start()
+      expect(pool.address()).toBeDefined()
+
+      // Stop via return value.
+      await stop()
+      expect(pool.address()).toBeNull()
+    })
+
+    test('args: port', async () => {
+      const pool = createServer({
+        instance,
+        port: 3000,
+      })
+      expect(pool).toBeDefined()
+
+      const stop = await pool.start()
+      expect(pool.address()?.port).toBe(3000)
+      await stop()
+    })
+
+    test('args: host', async () => {
+      const pool = createServer({
+        instance,
+        host: 'localhost',
+        port: 3000,
+      })
+      expect(pool).toBeDefined()
+
+      const stop = await pool.start()
+      expect(pool.address()?.address).toBe('::1')
+      expect(pool.address()?.port).toBe(3000)
+      await stop()
+    })
+
+    test('request: /healthcheck', async () => {
+      const server = createServer({
+        instance,
+      })
+
+      const stop = await server.start()
+      const { port } = server.address()!
+      const response = await fetch(`http://localhost:${port}/healthcheck`)
+      expect(response.status).toBe(200)
+
+      await stop()
+    })
+
+    test('request: /start + /stop', async () => {
+      const server = createServer({
+        instance,
+      })
+
+      const stop = await server.start()
+      const { port } = server.address()!
+      const response = await fetch(`http://localhost:${port}/1/start`)
+      expect(response.status).toBe(200)
+
+      const json = (await response.json()) as any
+      expect(json.host).toBeDefined()
+      expect(json.port).toBeDefined()
+
+      const response_err = await fetch(`http://localhost:${port}/1/start`)
+      expect(response_err.status).toBe(400)
+      expect(await response_err.json()).toEqual({
+        message: `Instance "${instance.name}" is not in an idle or stopped state. Status: started`,
+      })
+
+      const response_stop = await fetch(`http://localhost:${port}/1/stop`)
+      expect(response_stop.status).toBe(200)
+
+      const response_2 = await fetch(`http://localhost:${port}/1/start`)
+      expect(response_2.status).toBe(200)
+
+      await stop()
+    })
+
+    test('ws', async () => {
+      const server = createServer({
+        instance,
+      })
+
+      const stop = await server.start()
+      const { port } = server.address()!
+      const ws = new WebSocket(`ws://localhost:${port}/1`)
+      await new Promise((resolve) => ws.addEventListener('open', resolve))
+      ws.send('test')
+      await new Promise((resolve) => ws.addEventListener('message', resolve))
+
+      await stop()
+    })
+  },
+)
+
+describe("instance: 'anvil'", () => {
+  test('request: /{id}', async () => {
+    const server = createServer({
+      instance: anvil(),
+    })
+
+    const stop = await server.start()
+    const { port } = server.address()!
+    const response = await fetch(`http://localhost:${port}/1`)
+    // Standard Anvil HTTP response for invalid request.
+    expect(response.status).toBe(400)
+    expect(await response.text()).toBe(
+      "Connection header did not include 'upgrade'",
+    )
+
+    // Check block numbers
+    expect(
+      await fetch(`http://localhost:${port}/1`, {
+        body: JSON.stringify({
+          method: 'eth_blockNumber',
+          id: 0,
+          jsonrpc: '2.0',
+        }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+      }).then((x) => x.json()),
+    ).toMatchInlineSnapshot(`
+      {
+        "id": 0,
+        "jsonrpc": "2.0",
+        "result": "0x0",
+      }
+    `)
+    expect(
+      await fetch(`http://localhost:${port}/2`, {
+        body: JSON.stringify({
+          method: 'eth_blockNumber',
+          id: 0,
+          jsonrpc: '2.0',
+        }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+      }).then((x) => x.json()),
+    ).toMatchInlineSnapshot(`
+      {
+        "id": 0,
+        "jsonrpc": "2.0",
+        "result": "0x0",
+      }
+    `)
+
+    // Mine block number
+    await fetch(`http://localhost:${port}/1`, {
+      body: JSON.stringify({
+        method: 'anvil_mine',
+        params: ['0x69', '0x0'],
+        id: 0,
+        jsonrpc: '2.0',
+      }),
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      method: 'POST',
+    })
+
+    // Check block numbers
+    expect(
+      await fetch(`http://localhost:${port}/1`, {
+        body: JSON.stringify({
+          method: 'eth_blockNumber',
+          id: 0,
+          jsonrpc: '2.0',
+        }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+      }).then((x) => x.json()),
+    ).toMatchInlineSnapshot(`
+      {
+        "id": 0,
+        "jsonrpc": "2.0",
+        "result": "0x69",
+      }
+    `)
+    expect(
+      await fetch(`http://localhost:${port}/2`, {
+        body: JSON.stringify({
+          method: 'eth_blockNumber',
+          id: 0,
+          jsonrpc: '2.0',
+        }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+      }).then((x) => x.json()),
+    ).toMatchInlineSnapshot(`
+      {
+        "id": 0,
+        "jsonrpc": "2.0",
+        "result": "0x0",
+      }
+    `)
+
+    await stop()
+  })
+
+  test('request: /messages', async () => {
+    const server = createServer({
+      instance: anvil(),
+    })
+
+    const stop = await server.start()
+    const { port } = server.address()!
+
+    await fetch(`http://localhost:${port}/1`)
+
+    expect(
+      (
+        (await fetch(`http://localhost:${port}/1/messages`, {
+          body: JSON.stringify({
+            method: 'eth_blockNumber',
+            id: 0,
+            jsonrpc: '2.0',
+          }),
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          method: 'POST',
+        }).then((x) => x.json())) as any
+      ).length > 0,
+    ).toBeTruthy()
+
+    await stop()
+  })
+
+  test('ws', async () => {
+    const server = createServer({
+      instance: anvil(),
+    })
+
+    const stop = await server.start()
+    const { port } = server.address()!
+    const ws = new WebSocket(`ws://localhost:${port}/1`)
+    await new Promise((resolve) => ws.addEventListener('open', resolve))
+    ws.send(
+      JSON.stringify({
+        method: 'eth_blockNumber',
+        id: 0,
+        jsonrpc: '2.0',
+      }),
+    )
+    const { data } = await new Promise<MessageEvent>((resolve) =>
+      ws.addEventListener('message', resolve),
+    )
+    expect(data).toMatchInlineSnapshot(
+      `"{"jsonrpc":"2.0","id":0,"result":"0x0"}"`,
+    )
+
+    await stop()
+  })
+})
+
+test('404', async () => {
+  const server = createServer({
+    instance: anvil(),
+  })
+
+  const stop = await server.start()
+  const { port } = server.address()!
+  const response = await fetch(`http://localhost:${port}/wat`)
+  expect(response.status).toBe(404)
+
+  await stop()
+})

package/server.ts

@@ -0,0 +1,135 @@
+import {
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+  createServer as createServer_,
+} from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { createProxyServer } from 'http-proxy'
+
+import { type DefinePoolParameters, definePool } from './pool.js'
+import { extractPath } from './utils.js'
+
+export type createServerParameters = DefinePoolParameters &
+  (
+    | {
+        /** Host to run the server on. */
+        host?: string | undefined
+        /** Port to run the server on. */
+        port: number
+      }
+    | {
+        host?: undefined
+        port?: undefined
+      }
+  )
+
+export type createServerReturnType = Omit<
+  Server<typeof IncomingMessage, typeof ServerResponse>,
+  'address'
+> & {
+  address(): AddressInfo | null
+  start(): Promise<() => Promise<void>>
+  stop(): Promise<void>
+}
+
+export function createServer(
+  parameters: createServerParameters,
+): createServerReturnType {
+  const { host = '::', instance, limit, port } = parameters
+
+  const pool = definePool({ instance, limit })
+  const proxy = createProxyServer({
+    ignorePath: true,
+    ws: true,
+  })
+
+  const server = createServer_(async (request, response) => {
+    try {
+      const url = request.url
+      if (!url) {
+        response.end()
+        return
+      }
+
+      const { id, path } = extractPath(url)
+
+      if (typeof id === 'number' && path === '/') {
+        const { host, port } = pool.get(id) || (await pool.start(id))
+        return proxy.web(request, response, {
+          target: `http://${host}:${port}`,
+        })
+      }
+      if (typeof id === 'number' && path === '/start') {
+        const { host, port } = await pool.start(id)
+        response
+          .writeHead(200, { 'Content-Type': 'application/json' })
+          .end(JSON.stringify({ host, port }))
+        return
+      }
+      if (typeof id === 'number' && path === '/stop') {
+        await pool.stop(id)
+        response.writeHead(200, { 'Content-Type': 'application/json' }).end()
+        return
+      }
+      if (typeof id === 'number' && path === '/messages') {
+        const messages = pool.get(id)?.messages.get() || []
+        response
+          .writeHead(200, { 'Content-Type': 'application/json' })
+          .end(JSON.stringify(messages))
+        return
+      }
+
+      if (path === '/healthcheck') {
+        response.writeHead(200, { 'Content-Type': 'application/json' }).end()
+        return
+      }
+
+      response.writeHead(404, { 'Content-Type': 'application/json' }).end()
+      return
+    } catch (error) {
+      response
+        .writeHead(400, { 'Content-Type': 'application/json' })
+        .end(JSON.stringify({ message: (error as Error).message }))
+      return
+    }
+  })
+
+  server.on('upgrade', async (request, socket, head) => {
+    const url = request.url
+    if (!url) {
+      socket.destroy(new Error('Unsupported request'))
+      return
+    }
+
+    const { id, path } = extractPath(url)
+
+    if (typeof id === 'number' && path === '/') {
+      const { host, port } = pool.get(id) || (await pool.start(id))
+      proxy.ws(request, socket, head, {
+        target: `ws://${host}:${port}`,
+      })
+      return
+    }
+
+    socket.destroy(new Error('Unsupported request'))
+    return
+  })
+
+  return Object.assign(server as any, {
+    start() {
+      return new Promise<() => Promise<void>>((resolve) => {
+        if (port) server.listen(port, host, () => resolve(this.stop))
+        else server.listen(() => resolve(this.stop))
+      })
+    },
+    async stop() {
+      await Promise.allSettled([
+        new Promise<void>((resolve, reject) =>
+          server.close((error) => (error ? reject(error) : resolve())),
+        ),
+        pool.destroyAll(),
+      ])
+    },
+  })
+}