@atproto/lex-server 0.0.1

package/src/nodejs.test.ts

@@ -0,0 +1,107 @@
+import { AddressInfo } from 'node:net'
+import { scheduler } from 'node:timers/promises'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { Server, serve } from './nodejs.js'
+
+describe('Node.js RequestListener', () => {
+  let server: Server
+  let address: string
+
+  beforeAll(async () => {
+    server = await serve(async (request) => {
+      const { pathname } = new URL(request.url)
+      if (pathname === '/hello') {
+        return new Response('Hello, world!', {
+          status: 200,
+          headers: { 'Content-Type': 'text/plain' },
+        })
+      } else if (pathname === '/throw') {
+        throw new Error('Test error')
+      } else if (pathname === '/echo') {
+        return new Response(request.body, {
+          status: 200,
+          headers: { 'Content-Type': 'application/octet-stream' },
+        })
+      }
+      return new Response('Not Found', { status: 404 })
+    })
+    const { port } = server.address() as AddressInfo
+    address = `http://localhost:${port}`
+  })
+
+  afterAll(async () => {
+    await server.terminate()
+  })
+
+  it('should respond with Hello, world! on /hello', async () => {
+    const res = await fetch(new URL(`/hello`, address))
+    const text = await res.text()
+    expect(res.status).toBe(200)
+    expect(text).toBe('Hello, world!')
+  })
+
+  it('should respond with Not Found on unknown path', async () => {
+    const res = await fetch(new URL(`/unknown`, address))
+    const text = await res.text()
+    expect(res.status).toBe(404)
+    expect(text).toBe('Not Found')
+  })
+
+  it('should handle thrown errors and respond with 500', async () => {
+    const res = await fetch(new URL(`/throw`, address))
+    const text = await res.text()
+    expect(res.status).toBe(500)
+    expect(text).toBe('Internal Server Error')
+  })
+
+  it('should handle streaming bodies', async () => {
+    const totalSize = 1024 * 1024
+    const consumerSize = 42 * 1024
+
+    let sentBytes = 0
+    let receivedBytes = 0
+
+    const res = await fetch(new URL(`/echo`, address), {
+      method: 'POST',
+      // @ts-expect-error
+      duplex: 'half',
+      body: new ReadableStream({
+        async pull(controller) {
+          const chunkSize = Math.min(1024, totalSize - sentBytes)
+          controller.enqueue('A'.repeat(chunkSize))
+          sentBytes += chunkSize
+          await scheduler.wait(0) // Yield to event loop
+          if (sentBytes === totalSize) controller.close()
+        },
+      }),
+    })
+
+    const reader = res.body!.getReader()
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const result = await reader.read()
+      if (result.done) break
+      receivedBytes += Buffer.byteLength(result.value)
+      if (receivedBytes >= consumerSize) {
+        await reader.cancel()
+        break
+      }
+    }
+
+    expect(receivedBytes).toBeGreaterThanOrEqual(consumerSize)
+    expect(sentBytes).toBeGreaterThanOrEqual(consumerSize)
+    expect(sentBytes).toBeLessThan(totalSize)
+  })
+
+  it('should echo back request body on /echo', async () => {
+    const body = `Echo this back`
+    const res = await fetch(new URL(`/echo`, address), {
+      method: 'POST',
+      body,
+    })
+    const text = await res.text()
+    expect(res.status).toBe(200)
+    expect(text).toBe(body)
+  })
+})

package/src/nodejs.ts

@@ -0,0 +1,367 @@
+import { once } from 'node:events'
+import {
+  IncomingHttpHeaders,
+  IncomingMessage,
+  RequestListener,
+  Server as HttpServer,
+  ServerOptions,
+  ServerResponse,
+  createServer as createHttpServer,
+} from 'node:http'
+import { ListenOptions } from 'node:net'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { createHttpTerminator } from 'http-terminator'
+import { WebSocket as WebSocketPonyfill, WebSocketServer } from 'ws'
+
+// @ts-expect-error
+Symbol.asyncDispose ??= Symbol.for('Symbol.asyncDispose')
+
+const kResponseWs = Symbol.for('@atproto/lex-server:WebSocket')
+
+function isUpgradeRequest(request: Request, upgrade: string): boolean {
+  return (
+    request.method === 'GET' &&
+    request.headers.get('connection')?.toLowerCase() === 'upgrade' &&
+    request.headers.get('upgrade')?.toLowerCase() === upgrade
+  )
+}
+
+export function upgradeWebSocket(request: Request): {
+  response: Response
+  socket: WebSocket
+} {
+  if (!isUpgradeRequest(request, 'websocket')) {
+    throw new TypeError('upgradeWebSocket() expects a WebSocket upgrade')
+  }
+
+  // Placeholder response for WebSocket upgrade. The actual handling will happen
+  // through the handleWebSocketUpgrade function. Headers set on the response
+  // will be applied during the upgrade.
+  const response = new Response(null, { status: 200 })
+
+  // The Response constructor does not allow setting status 101, so we
+  // define it directly. The purpose of this response is just to signal
+  // that an upgrade is needed, and to carry any headers.
+  Object.defineProperty(response, 'status', {
+    value: 101,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+
+  // @ts-expect-error
+  const socket: WebSocket = new WebSocketPonyfill(null, undefined, {
+    autoPong: true,
+  })
+
+  // Attach the WebSocket to the response for later retrieval
+  Object.defineProperty(response, kResponseWs, {
+    value: socket,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+
+  return { response, socket }
+}
+
+function handleWebSocketUpgrade(
+  req: IncomingMessage,
+  response: Response,
+): void {
+  const ws = (response as { [kResponseWs]?: WebSocketPonyfill })[kResponseWs]
+  if (!ws) throw new TypeError('Response not created by upgradeWebSocket()')
+
+  // Create a one time use WebSocketServer to handle the upgrade
+  const wss = new WebSocketServer({
+    autoPong: true,
+    noServer: true,
+    clientTracking: false,
+    perMessageDeflate: true,
+    // @ts-expect-error
+    WebSocket: function () {
+      // Return the websocket that was created earlier instead of a new instance
+      return ws
+    },
+  })
+
+  // Apply headers that might have been set on the response object during
+  // handling. This will be called during wss.handleUpgrade().
+  wss.on('headers', (headers) => {
+    for (const [name, value] of response.headers) {
+      headers.push(`${name}: ${value}`)
+    }
+  })
+
+  wss.handleUpgrade(req, req.socket, Buffer.alloc(0), (_socket) => {
+    // @TODO find a way to properly "close" the _socket when the server is
+    // shutting down (might require replacing http-terminator with a local
+    // implementation)
+  })
+}
+
+async function sendResponse(
+  req: IncomingMessage,
+  res: ServerResponse,
+  response: Response,
+): Promise<void> {
+  // Invalid usage
+  if (res.headersSent) {
+    throw new TypeError('Response has already been sent')
+  }
+
+  if (response.status === 101) {
+    return handleWebSocketUpgrade(req, response)
+  }
+
+  res.statusCode = response.status
+  res.statusMessage = response.statusText
+
+  for (const [key, value] of response.headers) {
+    res.appendHeader(key, value)
+  }
+
+  if (response.body != null && req.method !== 'HEAD') {
+    const stream = Readable.fromWeb(response.body as any)
+    await pipeline(stream, res)
+  } else {
+    await response.body?.cancel()
+    res.end()
+  }
+}
+
+function toRequest(req: IncomingMessage): Request {
+  const host = req.headers.host ?? req.socket?.localAddress ?? 'localhost'
+  const isEncrypted = (req.socket as any).encrypted === true
+  const protocol = isEncrypted ? 'https' : 'http'
+  const url = new URL(req.url ?? '/', `${protocol}://${host}`)
+  const headers = toHeaders(req.headers)
+  const body = toBody(req)
+
+  const abortController = new AbortController()
+  const abort = (err?: Error) => abortController.abort(err)
+
+  req.on('close', abort)
+  req.on('error', abort)
+  req.on('end', abort)
+
+  abortController.signal.addEventListener(
+    'abort',
+    () => {
+      req.off('close', abort)
+      req.off('error', abort)
+      req.off('end', abort)
+    },
+    { once: true },
+  )
+
+  return new Request(url, {
+    signal: abortController.signal,
+    method: req.method,
+    headers,
+    body,
+    referrer: headers.get('referrer') ?? headers.get('referer') ?? undefined,
+    redirect: 'manual',
+    // @ts-expect-error
+    duplex: body ? 'half' : undefined,
+  })
+}
+
+function toHeaders(headers: IncomingHttpHeaders): Headers {
+  const result = new Headers()
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const v of value) result.append(key, v)
+    } else {
+      result.set(key, value)
+    }
+  }
+  return result
+}
+
+function toBody(req: IncomingMessage): null | ReadableStream<Uint8Array> {
+  if (
+    req.method === 'GET' ||
+    req.method === 'HEAD' ||
+    req.method === 'OPTIONS'
+  ) {
+    return null
+  }
+
+  if (
+    req.headers['content-type'] == null &&
+    req.headers['transfer-encoding'] == null &&
+    req.headers['content-length'] == null
+  ) {
+    return null
+  }
+
+  return Readable.toWeb(req) as ReadableStream<Uint8Array>
+}
+
+export type NetAddr = {
+  hostname: string
+  port: number
+  transport: 'tcp'
+}
+
+export type NodeConnectionInfo = {
+  localAddr?: NetAddr
+  remoteAddr?: NetAddr
+}
+
+export interface HandlerFunction {
+  (req: Request, info: NodeConnectionInfo): Response | Promise<Response>
+}
+
+export interface HandlerObject {
+  handle: HandlerFunction
+}
+
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  handlerFn: HandlerFunction,
+) {
+  const request = toRequest(req)
+  const info = toConnectionInfo(req)
+  const response = await handlerFn(request, info)
+  await sendResponse(req, res, response)
+}
+
+function toConnectionInfo(req: IncomingMessage): NodeConnectionInfo {
+  const { socket } = req
+  return {
+    localAddr:
+      socket.localAddress != null
+        ? {
+            hostname: socket.localAddress,
+            port: socket.localPort!,
+            transport: 'tcp',
+          }
+        : undefined,
+    remoteAddr:
+      socket.remoteAddress != null
+        ? {
+            hostname: socket.remoteAddress,
+            port: socket.remotePort!,
+            transport: 'tcp',
+          }
+        : undefined,
+  }
+}
+
+export function toRequestListener<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+>(handlerFn: HandlerFunction) {
+  return ((
+    req: InstanceType<Request>,
+    res: InstanceType<Response> & { req: InstanceType<Request> },
+    next?: (err?: unknown) => void,
+  ): void => {
+    handleRequest(req, res, handlerFn).catch((err) => {
+      if (next) next(err)
+      else {
+        if (!res.headersSent) {
+          res.statusCode = 500
+          res.setHeader('content-type', 'text/plain; charset=utf-8')
+          res.end('Internal Server Error')
+        } else if (!res.writableEnded) {
+          res.destroy()
+        }
+      }
+    })
+  }) satisfies RequestListener<Request, Response>
+}
+
+export type CreateServerOptions<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+> = ServerOptions<Request, Response> & {
+  gracefulTerminationTimeout?: number
+}
+
+export interface Server<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+> extends HttpServer<Request, Response>,
+    AsyncDisposable {
+  terminate(): Promise<void>
+  [Symbol.asyncDispose](): Promise<void>
+}
+
+export function createServer<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+>(
+  handler: HandlerFunction | HandlerObject,
+  options: CreateServerOptions<Request, Response> = {},
+): Server<Request, Response> {
+  const handlerFn =
+    typeof handler === 'function' ? handler : handler.handle.bind(handler)
+
+  const listener = toRequestListener(handlerFn)
+  const server = createHttpServer(options, listener)
+
+  const terminator = createHttpTerminator({
+    server: server as HttpServer,
+    gracefulTerminationTimeout: options?.gracefulTerminationTimeout,
+  })
+
+  const terminate = async function terminate(this: Server<Request, Response>) {
+    if (this !== server) {
+      throw new TypeError('Server.terminate called with incorrect context')
+    }
+    // @TODO properly close all active WebSocket connections
+    return terminator.terminate()
+  }
+
+  Object.defineProperty(server, 'terminate', {
+    value: terminate,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+
+  Object.defineProperty(server, Symbol.asyncDispose, {
+    value: terminate,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+
+  return server as Server<Request, Response>
+}
+
+export type StartServerOptions<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+> = ListenOptions & CreateServerOptions<Request, Response>
+
+export async function serve<
+  Request extends typeof IncomingMessage = typeof IncomingMessage,
+  Response extends typeof ServerResponse<
+    InstanceType<Request>
+  > = typeof ServerResponse,
+>(
+  handler: HandlerFunction | HandlerObject,
+  options?: StartServerOptions<Request, Response>,
+): Promise<Server<Request, Response>> {
+  const server = createServer(handler, options)
+  server.listen(options)
+  await once(server, 'listening')
+  return server
+}

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": ["../../../tsconfig/isomorphic.json"],
+  "include": ["./src"],
+  "exclude": ["**/*.test.ts"],
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "importHelpers": true,
+    "target": "ES2023",
+    "rootDir": "./src",
+    "outDir": "./dist"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "include": [],
+  "references": [
+    { "path": "./tsconfig.build.json" },
+    { "path": "./tsconfig.examples.json" },
+    { "path": "./tsconfig.tests.json" }
+  ]
+}

package/tsconfig.tests.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig/vitest.json",
+  "include": ["./tests", "./src/**/*.test.ts"],
+  "compilerOptions": {
+    "noImplicitAny": true,
+    "rootDir": "./",
+    "baseUrl": "./"
+  }
+}