brustjs 0.1.0-alpha

package/runtime/scan-actions.ts

@@ -0,0 +1,172 @@
+import { relative } from 'node:path'
+import type { ActionDef, ActionFn } from './actions.ts'
+import { isValidActionId, getActionMiddleware } from './actions.ts'
+
+const DIRECTIVE_HEAD_BYTES = 512
+
+/** Remove leading whitespace, line comments (`//`), and block comments
+ * from `src` and return the rest. Stops at the first non-trivial character.
+ * Does NOT understand string literals — fine because we only run this on a
+ * directive prologue, which by spec contains comments and the directive only.
+ * If a block comment never terminates, returns '' so the caller treats the
+ * file as non-server. */
+export function stripLeadingTrivia(src: string): string {
+  let i = 0
+  while (i < src.length) {
+    const ch = src[i]
+    if (ch === ' ' || ch === '\t' || ch === '\r' || ch === '\n') {
+      i++
+      continue
+    }
+    if (ch === '/' && src[i + 1] === '/') {
+      const nl = src.indexOf('\n', i)
+      if (nl === -1) return ''
+      i = nl + 1
+      continue
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2)
+      if (end === -1) return ''
+      i = end + 2
+      continue
+    }
+    break
+  }
+  return src.slice(i)
+}
+
+const USE_SERVER_PATTERN = /^(?:'use server'|"use server")\s*;?\s*(?:\r?\n|$)/
+
+/** Read the first 512 bytes of `filePath` and return true iff a file-level
+ * `'use server'` directive sits at the prologue position (before any import
+ * or other statement). Comments and whitespace ahead of the directive are
+ * skipped. Mirrors the TC39 directive-prologue rule. */
+export async function hasUseServerDirective(filePath: string): Promise<boolean> {
+  const f = Bun.file(filePath)
+  const head = await f.slice(0, DIRECTIVE_HEAD_BYTES).text()
+  const stripped = stripLeadingTrivia(head)
+  return USE_SERVER_PATTERN.test(stripped)
+}
+
+/** Dynamically import `filePath` and collect every named function export as
+ * an ActionDef. Skips non-function exports silently. Throws on:
+ *   - default export (must be named)
+ *   - class export (calling a class without `new` would 500 at dispatch)
+ *   - invalid id charset
+ *   - zero function exports (likely a bug — file marked 'use server' but
+ *     publishes nothing).
+ * Middleware metadata installed by withMiddleware is preserved. */
+export async function collectExports(filePath: string): Promise<ActionDef[]> {
+  const mod = (await import(filePath)) as Record<string, unknown>
+  const defs: ActionDef[] = []
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value !== 'function') continue
+    // typeof class{} is 'function' in JS; reject explicitly so an accidental
+    // `export class Foo {}` in a 'use server' file fails loudly at scan,
+    // not with a confusing 500 at dispatch.
+    if (Function.prototype.toString.call(value).startsWith('class ')) {
+      throw new Error(
+        `${filePath}: export "${name}" is a class. Actions must be plain async functions, not class constructors.`,
+      )
+    }
+    if (name === 'default') {
+      throw new Error(`${filePath}: default exports are not action-eligible. Use named export.`)
+    }
+    if (!isValidActionId(name)) {
+      throw new Error(
+        `${filePath}: export "${name}" has invalid id (must match [A-Za-z0-9_-]+, 1-128 chars).`,
+      )
+    }
+    defs.push({
+      id: name,
+      fn: value as ActionFn,
+      middleware: getActionMiddleware(value),
+    })
+  }
+  if (defs.length === 0) {
+    throw new Error(`${filePath}: marked 'use server' but exports no functions.`)
+  }
+  return defs
+}
+
+export interface ScanOptions {
+  /** Glob roots to scan from. Default: ['./']. Pass an explicit root (e.g.
+   * `import.meta.dirname`) when the project layout includes sibling subtrees
+   * you don't want scanned — typical for example apps inside a larger repo. */
+  roots?: string[]
+  /** Ignore globs (matched against the path relative to each root). Override
+   * the default array if you need a different policy — there's no merge.
+   * Default covers build outputs and test patterns. */
+  ignore?: string[]
+}
+
+const DEFAULT_IGNORE = Object.freeze([
+  'node_modules/**',
+  '.brust/**',
+  'dist/**',
+  'build/**',
+  'tests/**',
+  '__tests__/**',
+  '*.test.ts',
+  '*.test.tsx',
+  '*.spec.ts',
+  '*.spec.tsx',
+])
+
+const FILE_PATTERN = '**/*.{ts,tsx,js,jsx,mjs,cjs}'
+
+async function findCandidateFiles(opts: ScanOptions): Promise<string[]> {
+  const roots = opts.roots ?? ['./']
+  const ignore = opts.ignore ?? [...DEFAULT_IGNORE]
+  const ignoreGlobs = ignore.map((p) => new Bun.Glob(p))
+  const out: string[] = []
+  for (const root of roots) {
+    const glob = new Bun.Glob(FILE_PATTERN)
+    for await (const f of glob.scan({ cwd: root, dot: false, absolute: true })) {
+      const rel = relative(root, f)
+      if (ignoreGlobs.some((g) => g.match(rel))) continue
+      out.push(f)
+    }
+  }
+  return out
+}
+
+export interface ScanActionsResult {
+  actions: ActionDef[]
+  /** Absolute paths of files that had a `'use server'` directive — needed by
+   * `brust.buildMcpManifest` to feed the TypeScript compiler API extractor. */
+  sourceFiles: string[]
+}
+
+/** Walk the project, find files whose first statement is `'use server'`,
+ * import each, and return all named function exports as ActionDef[] plus the
+ * list of server source files.
+ * Throws on duplicate ids across files. Always returns actions sorted by id
+ * for deterministic logging. */
+export async function scanActions(opts: ScanOptions = {}): Promise<ScanActionsResult> {
+  const candidates = await findCandidateFiles(opts)
+  // Run directive checks in parallel — file IO scales well there.
+  const directiveChecks = await Promise.all(
+    candidates.map(async (p) => ({ path: p, isServer: await hasUseServerDirective(p) })),
+  )
+  const serverFiles = directiveChecks.filter((c) => c.isServer).map((c) => c.path)
+
+  // Serial imports — heavy module side effects shouldn't all fire at once.
+  const byId = new Map<string, string>()
+  const all: ActionDef[] = []
+  for (const file of serverFiles) {
+    const defs = await collectExports(file)
+    for (const def of defs) {
+      const prior = byId.get(def.id)
+      if (prior) {
+        throw new Error(
+          `Duplicate action "${def.id}" — defined in both ${prior} and ${file}. Rename one.`,
+        )
+      }
+      byId.set(def.id, file)
+      all.push(def)
+    }
+  }
+  all.sort((a, b) => a.id.localeCompare(b.id))
+  return { actions: all, sourceFiles: serverFiles }
+}

package/runtime/sse/handler.ts

@@ -0,0 +1,85 @@
+import type { Route, BrustRequest, RouteCall } from '../routes.ts'
+
+export type SseCall = Extract<RouteCall, { kind: 'sse' }>
+
+/** NAPI surface — Rust provides these. In tests, a mock satisfies the shape. */
+export interface SseNapi {
+  write(conn_id: bigint, bytes: Uint8Array): Promise<void>
+  close(conn_id: bigint): void
+  registerAbort(conn_id: bigint, cb: () => void): void
+  signalOpen(conn_id: bigint, status: number, body: string, contentType: string): void
+}
+
+const encoder = new TextEncoder()
+const PING_FRAME = encoder.encode(': ping\n\n')
+
+/**
+ * Per-connection JS driver for SSE routes. Called once per client connection.
+ *
+ * Contract with the Rust napi shim:
+ *   - napi.registerAbort(conn_id, cb)  — Rust calls cb when client disconnects
+ *   - napi.signalOpen(conn_id, status, body, contentType)
+ *                                      — JS reports verdict; Rust waits before writing headers
+ *   - napi.write(conn_id, bytes)       — write a chunk; Promise resolves when TCP write completes (backpressure)
+ *   - napi.close(conn_id)             — JS tells Rust to tear down the per-conn task
+ */
+export async function handleSseStream(call: SseCall, route: Route, napi: SseNapi): Promise<void> {
+  // 1. Create per-conn AbortController + a fresh request object whose signal
+  //    points at it. We spread call.req rather than mutating in place so the
+  //    underlying envelope object (potentially reused by makeRenderer in the
+  //    future) is never modified — the SSE-specific signal lives on a copy.
+  const controller = new AbortController()
+  const req: BrustRequest = { ...call.req, signal: controller.signal }
+
+  // 2. Wire Rust→JS abort.
+  napi.registerAbort(call.conn_id, () => controller.abort())
+
+  // 3. Open the user's stream. Throw → signal 500 and close.
+  let stream: ReadableStream<Uint8Array | string>
+  try {
+    stream = await route.sse!(req)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    napi.signalOpen(call.conn_id, 500, `sse handler threw: ${msg}`, 'text/plain; charset=utf-8')
+    napi.close(call.conn_id)
+    return
+  }
+
+  // 4. Signal open OK — Rust writes SSE response headers.
+  napi.signalOpen(call.conn_id, 200, '', 'text/event-stream')
+
+  // 5. Heartbeat + reader loop.
+  const reader = stream.getReader()
+  const heartbeatMs = route.sseOptions?.heartbeatMs ?? 15_000
+  const heartbeatId =
+    heartbeatMs > 0
+      ? setInterval(() => {
+          void napi.write(call.conn_id, PING_FRAME)
+        }, heartbeatMs)
+      : null
+
+  // Force-cancel reader on abort so a stuck `await reader.read()` unwinds
+  // even if the author didn't listen to req.signal.
+  controller.signal.addEventListener('abort', () => {
+    void reader.cancel()
+  })
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      const bytes = typeof value === 'string' ? encoder.encode(value) : value
+      await napi.write(call.conn_id, bytes)
+    }
+  } catch (err) {
+    if (!controller.signal.aborted) {
+      console.error(`[brust] sse stream error conn=${call.conn_id}:`, err)
+    }
+  } finally {
+    if (heartbeatId !== null) clearInterval(heartbeatId)
+    napi.close(call.conn_id)
+    try {
+      reader.releaseLock()
+    } catch {}
+  }
+}

package/runtime/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/runtime/ws/handler.ts

@@ -0,0 +1,151 @@
+import type { Route, RouteCall, WsHandlers, WsSocket } from '../routes.ts'
+
+export type WsCall = Extract<RouteCall, { kind: 'ws' }>
+
+/** NAPI surface — Rust provides these. Tests use a mock. */
+export interface WsNapi {
+  send(conn_id: bigint, data: Uint8Array, isBinary: boolean): Promise<void>
+  close(conn_id: bigint, code: number, reason: string): void
+  signalOpen(
+    conn_id: bigint,
+    status: number,
+    body: string,
+    contentType: string,
+    subprotocol: string,
+  ): void
+  registerHandlers(
+    conn_id: bigint,
+    onMessage: (data: Uint8Array, isBinary: boolean) => void,
+    onClose: (code: number, reason: string) => void,
+  ): void
+}
+
+/** Pick the first subprotocol from `routeList` that the client also requested.
+ * Returns null when there's no overlap or routeList is empty/undefined. */
+export function pickSubprotocol(
+  clientList: string[],
+  routeList: string[] | undefined,
+): string | null {
+  if (!routeList || routeList.length === 0) return null
+  for (const candidate of routeList) {
+    if (clientList.includes(candidate)) return candidate
+  }
+  return null
+}
+
+class WsSocketImpl implements WsSocket {
+  constructor(
+    public readonly id: bigint,
+    private napi: WsNapi,
+    private closed: { v: boolean },
+  ) {}
+
+  async send(data: string | Uint8Array): Promise<void> {
+    if (this.closed.v) throw new Error(`ws conn ${this.id}: already closed`)
+    const bytes = typeof data === 'string' ? encoder.encode(data) : data
+    const isBinary = typeof data !== 'string'
+    await this.napi.send(this.id, bytes, isBinary)
+  }
+
+  close(code: number = 1000, reason: string = ''): void {
+    if (this.closed.v) return
+    this.closed.v = true
+    this.napi.close(this.id, code, reason.slice(0, 123))
+  }
+}
+
+const decoder = new TextDecoder('utf-8')
+const encoder = new TextEncoder()
+
+/**
+ * Per-connection JS driver for WebSocket routes. Caller (wsBranch) is
+ * responsible for running middleware FIRST and only invoking this on a 101
+ * verdict — the signalOpen call here is always 101.
+ *
+ * Ordering note: handlers.open is *called* before any message can fire,
+ * but if open is async it is NOT guaranteed to *complete* before the first
+ * message arrives. Handlers that initialise per-connection state in open
+ * and read it in message should await any setup synchronously inside open,
+ * or guard reads in message against missing state.
+ */
+export async function handleWsConn(call: WsCall, route: Route, napi: WsNapi): Promise<void> {
+  // Load the handler module. Failure here → 500 signalOpen (Rust writes
+  // regular HTTP error response since 101 hasn't been sent yet).
+  //
+  // Accept either a direct WsHandlers object OR a module wrapper exposing
+  // the handlers via `default`. The latter is what `() => import('./x.ts')`
+  // produces, which is the most common author pattern — refusing it would
+  // silently no-op the handler (no method on the module-namespace object
+  // matches WsHandlers' method names).
+  let handlers: WsHandlers
+  try {
+    const loaded = await route.websocket!()
+    const maybeDefault = (loaded as { default?: WsHandlers }).default
+    handlers =
+      maybeDefault && typeof maybeDefault === 'object' ? maybeDefault : (loaded as WsHandlers)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    napi.signalOpen(
+      call.conn_id,
+      500,
+      `ws handler import failed: ${msg}`,
+      'text/plain; charset=utf-8',
+      '',
+    )
+    return
+  }
+
+  // Pick subprotocol (route declares; client requests; first match wins).
+  const chosen = pickSubprotocol(call.client_subprotocols, route.wsOptions?.subprotocols)
+
+  // CRITICAL ORDERING: register handlers BEFORE signalOpen(101). Once
+  // signalOpen fires, Rust writes the 101 response, the client sees
+  // OPEN immediately, and may send frames that hit ws_conn_task's
+  // on_message lookup. If on_message is still None at that point the
+  // frame is silently dropped. Build the socket + install handlers
+  // first; only then unblock Rust by signalling 101.
+  const closed = { v: false }
+  const socket = new WsSocketImpl(call.conn_id, napi, closed)
+
+  napi.registerHandlers(
+    call.conn_id,
+    (data, isBinary) => {
+      const payload = isBinary ? data : decoder.decode(data)
+      try {
+        const r = handlers.message?.(socket, payload)
+        if (r instanceof Promise)
+          r.catch((err) => {
+            console.error(`[brust] ws conn=${call.conn_id} message handler rejected:`, err)
+          })
+      } catch (err) {
+        console.error(`[brust] ws conn=${call.conn_id} message handler threw:`, err)
+      }
+    },
+    (code, reason) => {
+      closed.v = true
+      try {
+        handlers.close?.(socket, code, reason)
+      } catch (err) {
+        console.error(`[brust] ws conn=${call.conn_id} close handler threw:`, err)
+      }
+    },
+  )
+
+  napi.signalOpen(call.conn_id, 101, '', '', chosen ?? '')
+
+  // Fire author's open hook. Throws here close the conn 1011.
+  if (handlers.open) {
+    try {
+      const r = handlers.open(socket, { req: call.req, subprotocol: chosen })
+      if (r instanceof Promise) {
+        r.catch((err) => {
+          console.error(`[brust] ws conn=${call.conn_id} open handler rejected:`, err)
+          if (!closed.v) socket.close(1011, 'internal error')
+        })
+      }
+    } catch (err) {
+      console.error(`[brust] ws conn=${call.conn_id} open handler threw:`, err)
+      if (!closed.v) socket.close(1011, 'internal error')
+    }
+  }
+}