acrylblends 0.2.0 → 0.4.0

package/plugins/acryl-node-server/src/adapter/utils.ts

@@ -0,0 +1,96 @@
+import type { OutgoingHttpHeaders } from 'node:http'
+import type { Writable } from 'node:stream'
+
+export async function readWithoutBlocking(
+  readPromise: Promise<ReadableStreamReadResult<Uint8Array>>
+): Promise<ReadableStreamReadResult<Uint8Array> | undefined> {
+  return Promise.race([readPromise, Promise.resolve().then(() => Promise.resolve(undefined))])
+}
+
+export function writeFromReadableStreamDefaultReader(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  writable: Writable,
+  currentReadPromise?: Promise<ReadableStreamReadResult<Uint8Array>> | undefined
+) {
+  const cancel = (error?: unknown) => {
+    reader.cancel(error).catch(() => {})
+  }
+
+  writable.on('close', cancel)
+  writable.on('error', cancel)
+  ;(currentReadPromise ?? reader.read()).then(flow, handleStreamError)
+
+  return reader.closed.finally(() => {
+    writable.off('close', cancel)
+    writable.off('error', cancel)
+  })
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function handleStreamError(error: any) {
+    if (error) {
+      writable.destroy(error)
+    }
+  }
+
+  function onDrain() {
+    reader.read().then(flow, handleStreamError)
+  }
+
+  function flow({ done, value }: ReadableStreamReadResult<Uint8Array>): void | Promise<void> {
+    try {
+      if (done) {
+        writable.end()
+      } else if (!writable.write(value)) {
+        writable.once('drain', onDrain)
+      } else {
+        return reader.read().then(flow, handleStreamError)
+      }
+    } catch (e) {
+      handleStreamError(e)
+    }
+  }
+}
+
+export function writeFromReadableStream(stream: ReadableStream<Uint8Array>, writable: Writable) {
+  if (stream.locked) {
+    throw new TypeError('ReadableStream is locked.')
+  } else if (writable.destroyed) {
+    return
+  }
+
+  return writeFromReadableStreamDefaultReader(stream.getReader(), writable)
+}
+
+export const buildOutgoingHttpHeaders = (
+  headers: Headers | HeadersInit | null | undefined,
+  defaultContentType: string | undefined
+): OutgoingHttpHeaders => {
+  const res: OutgoingHttpHeaders = {}
+  if (!(headers instanceof Headers)) {
+    headers = new Headers(headers ?? undefined)
+  }
+
+  if (headers.has('set-cookie')) {
+    const cookies = []
+    for (const [k, v] of headers) {
+      if (k === 'set-cookie') {
+        cookies.push(v)
+      } else {
+        res[k] = v
+      }
+    }
+    if (cookies.length > 0) {
+      res['set-cookie'] = cookies
+    }
+  } else {
+    for (const [k, v] of headers) {
+      res[k] = v
+    }
+  }
+
+  if (defaultContentType) {
+    res['content-type'] ??= defaultContentType
+  }
+
+  return res
+}

package/plugins/acryl-node-server/src/adapter/websocket-types.ts

@@ -0,0 +1,45 @@
+/**
+ * This is the minimal public interface for WebSocket that is compatible with `ws` (`@types/ws`)
+ * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/ws/index.d.ts
+ *
+ * If you need more methods, copy the extra types over from the types file linked above.
+ * Don't import types from `ws` directly, as it will cause issues with users who have `skipLibCheck` enabled.
+ */
+import type { IncomingMessage } from 'node:http'
+import type { Duplex } from 'node:stream'
+
+type WSReadyState = 0 | 1 | 2 | 3
+
+export type WebSocketData = string | ArrayBuffer | Uint8Array | readonly Uint8Array[]
+
+export type WebSocketSendOptions = {
+  compress?: boolean
+}
+
+export interface WebSocketLike {
+  protocol: string
+  readyState: WSReadyState
+  close(code?: number, reason?: string): void
+  send(data: string | ArrayBuffer | ArrayBufferView, options?: WebSocketSendOptions): void
+  on(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this
+  on(event: 'close', listener: (code: number, reason: Uint8Array) => void): this
+  on(event: 'error', listener: (error: unknown) => void): this
+  off(event: 'message', listener: (data: WebSocketData, isBinary: boolean) => void): this
+}
+
+export interface WebSocketServerLike {
+  options: {
+    noServer?: boolean
+  }
+  on(event: 'connection', listener: (ws: WebSocketLike, request: IncomingMessage) => void): this
+  on(event: 'headers', listener: (headers: string[]) => void): this
+  off(event: 'headers', listener: (headers: string[]) => void): this
+  emit(event: 'connection', ws: WebSocketLike, request: IncomingMessage): boolean
+  handleUpgrade(
+    request: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+    callback: (ws: WebSocketLike) => void
+  ): void
+  close(): void
+}

package/plugins/acryl-node-server/src/adapter/websocket.ts

@@ -0,0 +1,375 @@
+import type { UpgradeWebSocket, WSContext } from '../../../acryl-router/src/helpers/index.ts'
+import { defineWebSocketHelper } from '../../../acryl-router/src/helpers/index.ts'
+import type { IncomingMessage } from 'node:http'
+import { STATUS_CODES } from 'node:http'
+import type { Duplex } from 'node:stream'
+import type { FetchCallback, ServerType } from './types.ts'
+import type { WebSocketData, WebSocketLike, WebSocketServerLike } from './websocket-types.ts'
+
+interface CloseEventInit extends EventInit {
+  code?: number
+  reason?: string
+  wasClean?: boolean
+}
+
+/**
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent
+ */
+export const CloseEvent: typeof globalThis.CloseEvent =
+  globalThis.CloseEvent ??
+  class extends Event {
+    #eventInitDict
+
+    constructor(type: string, eventInitDict: CloseEventInit = {}) {
+      super(type, eventInitDict)
+      this.#eventInitDict = eventInitDict
+    }
+
+    get wasClean(): boolean {
+      return this.#eventInitDict.wasClean ?? false
+    }
+
+    get code(): number {
+      return this.#eventInitDict.code ?? 0
+    }
+
+    get reason(): string {
+      return this.#eventInitDict.reason ?? ''
+    }
+  }
+
+interface ErrorEventInit extends EventInit {
+  message?: string
+  filename?: string
+  lineno?: number
+  colno?: number
+  error?: unknown
+}
+
+/**
+ * Node.js has no global `ErrorEvent`, unlike `Event`/`MessageEvent`/`CloseEvent`.
+ * @link https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent
+ */
+export const ErrorEvent: typeof globalThis.ErrorEvent =
+  globalThis.ErrorEvent ??
+  class extends Event {
+    #eventInitDict
+
+    constructor(type: string, eventInitDict: ErrorEventInit = {}) {
+      super(type, eventInitDict)
+      this.#eventInitDict = eventInitDict
+    }
+
+    get message(): string {
+      return this.#eventInitDict.message ?? ''
+    }
+
+    get filename(): string {
+      return this.#eventInitDict.filename ?? ''
+    }
+
+    get lineno(): number {
+      return this.#eventInitDict.lineno ?? 0
+    }
+
+    get colno(): number {
+      return this.#eventInitDict.colno ?? 0
+    }
+
+    get error(): unknown {
+      return this.#eventInitDict.error ?? null
+    }
+  }
+
+const generateConnectionSymbol = () => Symbol('connection')
+
+type WaitForWebSocket = (
+  request: IncomingMessage,
+  connectionSymbol: symbol
+) => Promise<WebSocketLike>
+
+const CONNECTION_SYMBOL_KEY: unique symbol = Symbol('CONNECTION_SYMBOL_KEY')
+const WAIT_FOR_WEBSOCKET_SYMBOL: unique symbol = Symbol('WAIT_FOR_WEBSOCKET_SYMBOL')
+
+export type UpgradeBindings = {
+  incoming: IncomingMessage
+  outgoing: undefined
+  wss: WebSocketServerLike
+  [CONNECTION_SYMBOL_KEY]?: symbol
+  [WAIT_FOR_WEBSOCKET_SYMBOL]?: WaitForWebSocket
+}
+
+type UpgradeWebSocketOptions = {
+  onError: (err: unknown) => void
+}
+
+// Hop-by-hop headers per RFC 9110 Section 7.6.1
+// (https://www.rfc-editor.org/rfc/rfc9110.html#name-connection) plus
+// `keep-alive` (commonly treated as hop-by-hop by HTTP implementations) and
+// WebSocket handshake headers managed by `ws` itself. These must not be
+// forwarded onto the upgrade response or the handshake will be corrupted.
+const responseHeadersToSkip = new Set([
+  'connection',
+  'content-length',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'sec-websocket-accept',
+  'sec-websocket-extensions',
+  'sec-websocket-protocol',
+])
+
+const appendResponseHeaders = (headers: string[], responseHeaders?: Headers) => {
+  if (!responseHeaders) {
+    return
+  }
+  responseHeaders.forEach((value, key) => {
+    if (responseHeadersToSkip.has(key.toLowerCase())) {
+      return
+    }
+    headers.push(`${key}: ${value}`)
+  })
+}
+
+const rejectUpgradeRequest = (socket: Duplex, status: number, responseHeaders?: Headers) => {
+  const responseLines = ['Connection: close', 'Content-Length: 0']
+  appendResponseHeaders(responseLines, responseHeaders)
+
+  socket.end(
+    `HTTP/1.1 ${status.toString()} ${STATUS_CODES[status] ?? ''}\r\n` +
+      `${responseLines.join('\r\n')}\r\n` +
+      '\r\n'
+  )
+}
+
+const createUpgradeRequest = (request: IncomingMessage): Request => {
+  const protocol = (request.socket as { encrypted?: boolean }).encrypted ? 'https' : 'http'
+  const url = new URL(request.url ?? '/', `${protocol}://${request.headers.host ?? 'localhost'}`)
+  const headers = new Headers()
+  for (const key in request.headers) {
+    const value = request.headers[key]
+    if (!value) {
+      continue
+    }
+    headers.append(key, Array.isArray(value) ? value[0] : value)
+  }
+  return new Request(url, {
+    headers,
+  })
+}
+
+export const setupWebSocket = (options: {
+  server: ServerType
+  fetchCallback: FetchCallback
+  wss: WebSocketServerLike
+}): void => {
+  const { server, fetchCallback, wss } = options
+
+  const waiterMap = new Map<
+    IncomingMessage,
+    {
+      resolve: (ws: WebSocketLike) => void
+      reject: (reason: Error) => void
+      connectionSymbol: symbol
+    }
+  >()
+
+  wss.on('connection', (ws, request) => {
+    const waiter = waiterMap.get(request)
+    if (waiter) {
+      waiter.resolve(ws)
+      waiterMap.delete(request)
+    }
+  })
+
+  const rejectWaiter = (request: IncomingMessage) => {
+    const waiter = waiterMap.get(request)
+    if (waiter) {
+      waiterMap.delete(request)
+      waiter.reject(new Error('WebSocket handshake aborted'))
+    }
+  }
+
+  const waitForWebSocket: WaitForWebSocket = (request, connectionSymbol) => {
+    return new Promise<WebSocketLike>((resolve, reject) => {
+      waiterMap.set(request, { resolve, reject, connectionSymbol })
+    })
+  }
+
+  server.on('upgrade', async (request, socket: Duplex, head) => {
+    if (request.headers.upgrade?.toLowerCase() !== 'websocket') {
+      return
+    }
+
+    const env: UpgradeBindings = {
+      incoming: request,
+      outgoing: undefined,
+      wss,
+      [WAIT_FOR_WEBSOCKET_SYMBOL]: waitForWebSocket,
+    }
+
+    let status = 400
+    let responseHeaders: Headers | undefined
+    try {
+      const response = (await fetchCallback(
+        createUpgradeRequest(request),
+        env as unknown as Parameters<FetchCallback>[1]
+      )) as Response
+      if (response instanceof Response) {
+        status = response.status
+        responseHeaders = response.headers
+      }
+    } catch {
+      if (server.listenerCount('upgrade') === 1) {
+        rejectUpgradeRequest(socket, 500)
+      }
+      return
+    }
+
+    const waiter = waiterMap.get(request)
+
+    if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) {
+      rejectWaiter(request)
+      if (server.listenerCount('upgrade') === 1) {
+        rejectUpgradeRequest(socket, status, responseHeaders)
+      }
+      return
+    }
+
+    const addResponseHeaders = (headers: string[]) => {
+      appendResponseHeaders(headers, responseHeaders)
+    }
+
+    const reclaimWaiterOnClose = () => rejectWaiter(request)
+    socket.once('close', reclaimWaiterOnClose)
+
+    wss.on('headers', addResponseHeaders)
+    try {
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        socket.off('close', reclaimWaiterOnClose)
+        wss.emit('connection', ws, request)
+      })
+    } finally {
+      wss.off('headers', addResponseHeaders)
+    }
+  })
+
+  server.on('close', () => {
+    wss.close()
+  })
+}
+
+export const upgradeWebSocket: UpgradeWebSocket<WebSocketLike, UpgradeWebSocketOptions> =
+  defineWebSocketHelper(async (c, events, options) => {
+    if (c.req.header('upgrade')?.toLowerCase() !== 'websocket') {
+      return
+    }
+
+    const env = c.env as UpgradeBindings
+    const waitForWebSocket = env[WAIT_FOR_WEBSOCKET_SYMBOL]
+
+    if (!waitForWebSocket || !env.incoming) {
+      return new Response(null, { status: 500 })
+    }
+
+    const connectionSymbol = generateConnectionSymbol()
+    env[CONNECTION_SYMBOL_KEY] = connectionSymbol
+    ;(async () => {
+      let ws: WebSocketLike
+      try {
+        ws = await waitForWebSocket(env.incoming, connectionSymbol)
+      } catch {
+        return
+      }
+
+      const messagesReceivedInStarting: [data: WebSocketData, isBinary: boolean][] = []
+      const bufferMessage = (data: WebSocketData, isBinary: boolean) => {
+        messagesReceivedInStarting.push([data, isBinary])
+      }
+      ws.on('message', bufferMessage)
+
+      // A plain object with the class's public shape: the class's private field is not part of the shape, so it is asserted once.
+      const shape: Pick<WSContext<WebSocketLike>, keyof WSContext<WebSocketLike>> = {
+        binaryType: 'arraybuffer',
+        close(code, reason) {
+          ws.close(code, reason)
+        },
+        protocol: ws.protocol,
+        raw: ws,
+        get readyState() {
+          return ws.readyState
+        },
+        send(source, opts) {
+          ws.send(source, {
+            compress: opts?.compress,
+          })
+        },
+        url: new URL(c.req.url),
+      }
+      const ctx = shape as WSContext<WebSocketLike>
+
+      try {
+        events?.onOpen?.(new Event('open'), ctx)
+      } catch (e) {
+        ;(options?.onError ?? console.error)(e)
+      }
+
+      const handleMessage = (data: WebSocketData, isBinary: boolean) => {
+        const datas = Array.isArray(data) ? data : [data]
+        for (const data of datas) {
+          try {
+            events?.onMessage?.(
+              new MessageEvent('message', {
+                data: isBinary
+                  ? data instanceof ArrayBuffer
+                    ? data
+                    : data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+                  : typeof data === 'string'
+                    ? data
+                    : Buffer.from(data).toString('utf-8'),
+              }),
+              ctx
+            )
+          } catch (e) {
+            ;(options?.onError ?? console.error)(e)
+          }
+        }
+      }
+
+      ws.off('message', bufferMessage)
+      for (const message of messagesReceivedInStarting) {
+        handleMessage(...message)
+      }
+
+      ws.on('message', (data, isBinary) => {
+        handleMessage(data, isBinary)
+      })
+
+      ws.on('close', (code, reason) => {
+        try {
+          events?.onClose?.(new CloseEvent('close', { code, reason: reason.toString() }), ctx)
+        } catch (e) {
+          ;(options?.onError ?? console.error)(e)
+        }
+      })
+
+      ws.on('error', (error) => {
+        try {
+          events?.onError?.(
+            new ErrorEvent('error', {
+              error,
+            }),
+            ctx
+          )
+        } catch (e) {
+          ;(options?.onError ?? console.error)(e)
+        }
+      })
+    })()
+
+    return new Response()
+  })

package/plugins/acryl-node-server/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * The framework's standalone HTTP adapter (spec 046, ported in spec 047), the standalone counterpart of the Host adapter. It owns one
+ * `node:http` server built by the ported adapter in `src/adapter/` and hands every request to `ctx.router.fetch`, with the socket's peer
+ * address and local port as connection facts.
+ * Use it in an app that runs without the ACRYL Host; inside the Host, `acryl-router-http` mounts prefixes on the Host's own web server.
+ * One adapter per runtime: a plugin keeps asking `ctx.inject(['routerHttp'], ...)` for a mount, which simply never fires here, because this
+ * adapter serves the whole router.
+ *
+ * A configured port that is taken is followed by the next free one, at most `scan` further ports; port 0 lets the system choose. Disposal ends
+ * open streams, closes every connection and returns once the port is free.
+ */
+
+import type { Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '../../acryl-router/src/index.ts'
+import { Request as AdapterRequest } from './adapter/request.ts'
+import { createAdaptorServer } from './adapter/server.ts'
+
+export { serveStatic, type ServeStaticOptions } from './adapter/serve-static.ts'
+export { RequestError } from './adapter/request.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-node-server'
+export const inject = ['router']
+
+export interface Config {
+  hostname: string
+  port: number
+  scan: number
+}
+
+/** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
+export const Config: z<Partial<Config>, Config> = z.object({
+  hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
+  port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
+  scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+})
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    nodeServer: NodeServer
+  }
+}
+
+export class NodeServer extends Service {
+  readonly hostname: string
+  readonly config: Config
+  private readonly server: Server
+  private bound = 0
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'nodeServer')
+    this.config = config
+    this.hostname = config.hostname
+    const router = ctx.router
+    // The handler sees the router's bindings (`c.env.connection`), not the raw `incoming`/`outgoing` pair. The global `Request` and
+    // `Response` stay the platform's, because this adapter shares its process with the rest of the app; so the adapter's lightweight
+    // request is made a real one (its signal still aborts when the client goes away) before the router re-creates it with its own signal.
+    this.server = createAdaptorServer({
+      fetch: (request, { incoming }) => router.fetch(new AdapterRequest(request), { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }),
+      hostname: config.hostname,
+      overrideGlobalObjects: false,
+    }) as Server
+    ctx.effect(() => async () => {
+      this.server.closeAllConnections()
+      if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
+    }, 'acryl-node-server: close listener and open connections')
+  }
+
+  /** The port in use, 0 before the server listens. */
+  get port(): number {
+    return this.bound
+  }
+
+  /** The address clients use. */
+  get url(): string {
+    return `http://${this.hostname.includes(':') ? `[${this.hostname}]` : this.hostname}:${String(this.bound)}`
+  }
+
+  /** Bind, scanning past taken ports. */
+  async listen(): Promise<void> {
+    const { port, scan, hostname } = this.config
+    const last = port === 0 ? 0 : Math.min(65535, port + scan)
+    for (let candidate = port; candidate <= last; candidate += 1) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const onError = (error: Error): void => { reject(error) }
+          this.server.once('error', onError)
+          this.server.listen(candidate, hostname, () => { this.server.off('error', onError); resolve() })
+        })
+        this.bound = (this.server.address() as AddressInfo).port
+        return
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+      }
+    }
+    throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
+  }
+}
+
+/** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
+export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
+  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })
+  await server.listen()
+}

package/plugins/acryl-node-server/tests/adapter/app.ts

@@ -0,0 +1,76 @@
+import { Response as PonyfillResponse } from '@whatwg-node/fetch'
+import { App } from '../../../acryl-router/src/index.ts'
+
+export const app = new App()
+
+app.get('/', (c) => c.text('Hello! Node!'))
+app.get('/url', (c) => c.text(c.req.url))
+
+app.get('/posts', (c) => {
+  return c.text(`Page ${c.req.query('page')}`)
+})
+app.get('/user-agent', (c) => {
+  return c.text(c.req.header('user-agent') as string)
+})
+app.post('/posts', (c) => {
+  return c.redirect('/posts')
+})
+app.post('/body-consumed', async (c) => {
+  return c.text(`Body length: ${(await c.req.text()).length}`)
+})
+app.post('/no-body-consumed', (c) => {
+  if (!c.req.raw.body) {
+    // force create new request object
+    throw new Error('No body consumed')
+  }
+  return c.text('No body consumed')
+})
+app.post('/body-cancelled', (c) => {
+  if (!c.req.raw.body) {
+    // force create new request object
+    throw new Error('No body consumed')
+  }
+  c.req.raw.body.cancel()
+  return c.text('Body cancelled')
+})
+app.post('/partially-consumed', async (c) => {
+  if (!c.req.raw.body) {
+    // force create new request object
+    throw new Error('No body consumed')
+  }
+  const reader = c.req.raw.body.getReader()
+  await reader.read() // read only one chunk
+  return c.text('Partially consumed')
+})
+app.post('/partially-consumed-and-cancelled', async (c) => {
+  if (!c.req.raw.body) {
+    // force create new request object
+    throw new Error('No body consumed')
+  }
+  const reader = c.req.raw.body.getReader()
+  await reader.read() // read only one chunk
+  reader.cancel()
+  return c.text('Partially consumed and cancelled')
+})
+app.post('/early-413', (c) => {
+  if (!c.req.raw.body) {
+    // force create new request object
+    throw new Error('No body consumed')
+  }
+  return c.text('Payload Too Large', 413)
+})
+app.delete('/posts/:id', (c) => {
+  return c.text(`DELETE ${c.req.param('id')}`)
+})
+// @ts-expect-error the response is string
+app.get('/invalid', () => {
+  return '<h1>HTML</h1>'
+})
+app.get('/ponyfill', () => {
+  return new PonyfillResponse('Pony')
+})
+
+app.on('trace', '/', (c) => {
+  const headers = c.req.raw.headers // build new request object
+  return c.text(`headers: ${JSON.stringify(headers)}`)
+})

package/plugins/acryl-node-server/tests/adapter/assets/.static/plain.txt

@@ -0,0 +1 @@
+This is plain.txt