brustjs 0.1.0-alpha

package/runtime/dev/watcher.ts

@@ -0,0 +1,109 @@
+import { watch, type FSWatcher } from 'node:fs'
+import path from 'node:path'
+
+export type ChangeKind = 'ts' | 'css' | 'component-css' | 'html' | 'islands'
+
+const IGNORE_DIR_SEGMENTS = new Set(['node_modules', '.git', '.brust', 'dist'])
+const TS_RE = /\.(tsx?|jsx?)$/
+const TEST_RE = /\.test\.(tsx?|jsx?)$/
+
+/** Classify a changed path. Returns null when the path should be ignored.
+ * `root` is used to compute the relative path for ignore-segment matching. */
+export function classifyPath(absPath: string, root: string): ChangeKind | null {
+  const rel = path.relative(root, absPath)
+  const segs = rel.split(path.sep)
+  for (const s of segs) {
+    if (IGNORE_DIR_SEGMENTS.has(s)) return null
+  }
+  if (TEST_RE.test(absPath)) return null
+
+  const base = path.basename(absPath)
+  if (base === 'app.css') return 'css'
+  // skip generated module type declarations
+  if (absPath.endsWith('.module.css.d.ts')) return null
+  // any other .css (including .module.css) is component CSS
+  if (absPath.endsWith('.css')) return 'component-css'
+  if (absPath.endsWith('.html')) return 'html'
+  if (TS_RE.test(absPath)) return 'ts'
+  return null
+}
+
+interface Coalesce {
+  add(path: string): void
+  flush(): void
+}
+
+/** Internal — exposed for unit tests. */
+export function _testCoalesce(debounceMs: number, flush: (paths: string[]) => void): Coalesce {
+  let pending = new Set<string>()
+  let timer: ReturnType<typeof setTimeout> | null = null
+  return {
+    add(p) {
+      pending.add(p)
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => {
+        const out = Array.from(pending)
+        pending = new Set()
+        timer = null
+        flush(out)
+      }, debounceMs)
+    },
+    flush() {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+      if (pending.size > 0) {
+        const out = Array.from(pending)
+        pending = new Set()
+        flush(out)
+      }
+    },
+  }
+}
+
+export interface CreateWatcherOptions {
+  root: string
+  debounceMs?: number
+  onChange: (ev: { paths: string[]; kind: ChangeKind }) => void
+}
+
+export interface Watcher {
+  close(): void
+}
+
+/** Watch `root` recursively. Emits one `onChange` call per debounce window
+ * with paths classified by the dominant kind. Mixed-kind windows pick
+ * by priority: islands > ts > html > css (islands trigger a full restart
+ * that subsumes the others). */
+export function createWatcher(opts: CreateWatcherOptions): Watcher {
+  const debounceMs = opts.debounceMs ?? 50
+  const kindPriority: ChangeKind[] = ['islands', 'ts', 'html', 'css', 'component-css']
+
+  const coalesce = _testCoalesce(debounceMs, (paths) => {
+    const kinds = new Set<ChangeKind>()
+    const keep: string[] = []
+    for (const p of paths) {
+      const k = classifyPath(p, opts.root)
+      if (k === null) continue
+      kinds.add(k)
+      keep.push(p)
+    }
+    if (keep.length === 0) return
+    const dominant = kindPriority.find((k) => kinds.has(k))!
+    opts.onChange({ paths: keep, kind: dominant })
+  })
+
+  const fsWatcher: FSWatcher = watch(opts.root, { recursive: true }, (_event, filename) => {
+    if (!filename) return
+    const abs = path.resolve(opts.root, filename)
+    coalesce.add(abs)
+  })
+
+  return {
+    close() {
+      fsWatcher.close()
+      coalesce.flush()
+    },
+  }
+}

package/runtime/dev/worker-registry.ts

@@ -0,0 +1,96 @@
+const TERMINATE_TIMEOUT_MS = 2000
+
+interface RegistryState {
+  workers: Worker[]
+  entry: string | null
+  count: number
+  baseEnv: Record<string, string> | null
+}
+
+const state: RegistryState = {
+  workers: [],
+  entry: null,
+  count: 0,
+  baseEnv: null,
+}
+
+/** Called once by brust.serve() in dev mode AFTER it spawns the initial
+ * pool. Hands the references to the registry so the coordinator can
+ * churn them later. */
+export function registerInitialPool(
+  workers: Worker[],
+  entry: string,
+  count: number,
+  baseEnv: Record<string, string>,
+): void {
+  state.workers = workers.slice()
+  state.entry = entry
+  state.count = count
+  state.baseEnv = baseEnv
+}
+
+/** Terminate every Worker with a 2s per-worker grace. If termination
+ * doesn't return in time, abandon the reference and continue. */
+export async function terminateAll(): Promise<void> {
+  const olds = state.workers
+  state.workers = []
+  await Promise.all(
+    olds.map(async (w) => {
+      try {
+        await Promise.race([
+          w.terminate(),
+          new Promise<void>((resolve) => setTimeout(resolve, TERMINATE_TIMEOUT_MS)),
+        ])
+      } catch {
+        // Already-terminated rejections swallowed.
+      }
+    }),
+  )
+}
+
+/** Spawn `count` fresh Workers using the entry + env captured at
+ * registerInitialPool time. Each worker gets BRUST_WORKER_ID=i.
+ * Resolves only after every fresh worker reports `brust-worker-ready`
+ * via postMessage — so the caller (coordinator) doesn't broadcast
+ * `reload` against workers whose message listeners aren't installed
+ * yet. Falls back after a 5s grace if a worker never signals. */
+export async function spawnAll(): Promise<void> {
+  if (state.entry === null || state.baseEnv === null) {
+    throw new Error('worker-registry: spawnAll called before registerInitialPool')
+  }
+  const fresh: Worker[] = []
+  const readies: Promise<void>[] = []
+  for (let i = 0; i < state.count; i++) {
+    const w = new Worker(state.entry, {
+      env: { ...state.baseEnv, BRUST_WORKER_ID: String(i) },
+    })
+    fresh.push(w)
+    readies.push(
+      new Promise<void>((resolve) => {
+        const onMsg = (e: MessageEvent) => {
+          const d: any = (e as any).data
+          if (d && d.type === 'brust-worker-ready') {
+            ;(w as any).removeEventListener?.('message', onMsg)
+            resolve()
+          }
+        }
+        ;(w as any).addEventListener?.('message', onMsg)
+        // Grace: don't hang forever if a worker crashes before reporting.
+        setTimeout(resolve, 5000)
+      }),
+    )
+  }
+  state.workers = fresh
+  await Promise.all(readies)
+}
+
+/** Test helper. */
+export function _workersForTests(): Worker[] {
+  return [...state.workers]
+}
+export function _resetForTests(): void {
+  state.workers = []
+  state.entry = null
+  state.count = 0
+  state.baseEnv = null
+}

package/runtime/dev/ws-channel.ts

@@ -0,0 +1,99 @@
+import type { Route, WsHandlers, WsSocket } from '../routes.ts'
+
+/** Server-to-client protocol. Client never sends after open. */
+export type DevMessage =
+  | { type: 'building' }
+  | { type: 'reload' }
+  | { type: 'css-update'; href: string }
+  | { type: 'error'; message: string; stack?: string }
+  | { type: 'ok' }
+
+// Worker-side state. WS connections to /_brust/dev are dispatched by Rust
+// to a worker isolate, so this Set lives in that worker's module copy.
+// Each worker has its own independent set; only the worker holding a
+// given connection has it in `clients`.
+const clients: Set<WsSocket> = new Set()
+
+export function _clientCountForTests(): number {
+  return clients.size
+}
+export function _resetForTests(): void {
+  clients.clear()
+}
+
+/** Build the synthetic /_brust/dev WS route. brust.run() prepends this
+ * to opts.routes in dev mode (both main + worker route arrays). */
+export function createDevWsRoute(): Route {
+  return {
+    path: '/_brust/dev',
+    websocket: () => Promise.resolve(devHandlers),
+  }
+}
+
+const devHandlers: WsHandlers = {
+  open(socket) {
+    clients.add(socket)
+  },
+  close(socket) {
+    clients.delete(socket)
+  },
+  message() {
+    /* ignore — server→client only */
+  },
+}
+
+/** Worker-side: forward JSON to every client connected to this worker. */
+async function broadcastLocal(json: string): Promise<void> {
+  const sends: Promise<unknown>[] = []
+  for (const s of clients) {
+    sends.push(
+      s.send(json).catch(() => {
+        clients.delete(s)
+      }),
+    )
+  }
+  await Promise.all(sends)
+}
+
+let workerListenerInstalled = false
+
+/** Worker-side: install a message listener that receives `dev-broadcast`
+ * envelopes from the main process and forwards them to this worker's
+ * local clients. Idempotent. After install, posts `brust-worker-ready`
+ * back to the parent so spawnAll() knows the worker is ready to relay
+ * broadcasts (avoids a race where `reload` is dispatched before the
+ * fresh worker's listener is wired). */
+export function installWorkerBroadcastListener(): void {
+  if (workerListenerInstalled) return
+  workerListenerInstalled = true
+  ;(globalThis as any).addEventListener('message', (e: MessageEvent) => {
+    const data: any = (e as any).data
+    if (data && data.type === 'dev-broadcast' && typeof data.json === 'string') {
+      void broadcastLocal(data.json)
+    }
+  })
+  // Signal readiness to parent (main thread). In a Worker context,
+  // postMessage targets the parent.
+  try {
+    ;(globalThis as any).postMessage({ type: 'brust-worker-ready' })
+  } catch {
+    /* not in a worker (unit test); harmless */
+  }
+}
+
+/** Main-side: relay the message to every worker via postMessage. Each
+ * worker's installed message listener forwards to its local clients.
+ * Per-worker postMessage failures are swallowed (worker may be already
+ * terminating). */
+export async function broadcast(msg: DevMessage): Promise<void> {
+  const json = JSON.stringify(msg)
+  const { _workersForTests } = await import('./worker-registry.ts')
+  const workers = _workersForTests()
+  for (const w of workers) {
+    try {
+      w.postMessage({ type: 'dev-broadcast', json })
+    } catch {
+      /* worker already terminated; drop */
+    }
+  }
+}

package/runtime/index.d.ts

@@ -0,0 +1,199 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare function beginServe(opts: ServeOptions): NapiResult<undefined>
+
+export declare function configureCache(maxEntries: number): NapiResult<undefined>
+
+export declare function configureCssDir(path: string): NapiResult<undefined>
+
+export declare function configureIslandsDir(path: string): NapiResult<undefined>
+
+export declare function isWorker(): boolean
+
+/**
+ * Sub-project J — boot-time listing of registered minijinja templates.
+ * JS dispatcher uses this to validate every `native: true` route's
+ * `Component.name` is present (warns on mismatch per Reviewer Fix 1).
+ */
+export declare function napiListNativeTemplates(): Array<string>
+
+/**
+ * Sub-project J — boot-time loader for `.brust/jinja/*.jinja` templates.
+ * Returns the list of template names registered (each `<Name>.jinja` file
+ * stem becomes the lookup key). Lenient on missing/non-directory `dir`.
+ */
+export declare function napiLoadJinjaTemplates(dir: string): Array<string>
+
+/**
+ * Register literal SSE paths. Rust's accept loop will match incoming GET
+ * requests against this set; matched requests enter the SSE dispatch branch
+ * instead of the normal render path. Call once at boot before begin_serve.
+ * Only exact-match (literal) paths are supported — parameterized routes
+ * (e.g. `/sse/{room}`) require a matchit-rs follow-up.
+ */
+export declare function napiRegisterSsePaths(paths: Array<string>): NapiResult<undefined>
+
+/**
+ * Boot-time registry of literal WS paths. Mirror of napi_register_sse_paths.
+ * Call once before begin_serve; exact-match only (parameterized routes are a
+ * follow-up).
+ */
+export declare function napiRegisterWsPaths(paths: Array<string>): NapiResult<undefined>
+
+/**
+ * Worker-driven render chunk delivery. Worker calls this once per chunk
+ * it wants to emit; final call uses `len = 0` to close the channel.
+ *
+ * Contract (spec §5.2):
+ * - `len > 0`: read SAB[0..len], send Bytes through render_slot.chunk_tx,
+ *   await ack. Resolves after Rust writes the chunk to the socket.
+ * - `len == 0`: send Final, await ack. Closes the response.
+ * - Bounds violation (len > buf_len) → NAPI Err.
+ * - Slot empty (no in-flight render for this worker) → NAPI Err.
+ * - Ack receiver dropped (handle_conn torn down mid-stream) → NAPI Err
+ *   (NOT hang — worker's sink propagates via cb(err) to renderer Promise).
+ */
+export declare function napiRenderChunk(workerId: number, len: number): Promise<NapiResult<undefined>>
+
+/**
+ * Buffering-path finalizer: equivalent to `napi_render_chunk(_, len)` followed
+ * by `napi_render_chunk(_, 0)` but in a single tsfn crossing. Cuts JS-side
+ * per-request overhead by one full Promise+await cycle.
+ *
+ * Streaming-path callers MUST NOT use this — they send N body chunks then a
+ * separate `Final`. Calling this with `streaming=true` meta is logged at WARN
+ * on the Rust side and falls back to emitting chunked headers + framed body
+ * + chunked terminator (byte-equivalent to Bytes-then-Final in chunked mode).
+ *
+ * Same error semantics as `napi_render_chunk`.
+ */
+export declare function napiRenderChunkFinal(workerId: number, len: number): Promise<NapiResult<undefined>>
+
+/**
+ * Sub-project J — render via minijinja using SAB-side-channeled loader data.
+ *
+ * SAB convention (spec §6 last paragraph): per-napi-call. `napi_render_jinja`
+ * treats SAB[0..data_len] as INBOUND raw JSON written by the JS worker. It
+ * renders the template Rust-side, assembles a `[meta_len: u16 BE][meta JSON]
+ * [body]` payload, writes it back into the SAB, and returns its byte length —
+ * the FAST LANE. The JS native branch returns this length up to the tsfn, and
+ * the dispatch loop's fast-lane arm reads the framed bytes directly from the
+ * SAB and ships them via `build_single_response_bytes`. No chunk channel, no
+ * per-chunk ack round-trip.
+ *
+ * The render reads the inbound JSON into an owned `Vec` first, so overwriting
+ * the SAB with the assembled response afterward is safe (no aliasing).
+ *
+ * SYNCHRONOUS napi fn (not `async`): the body is pure CPU work (jinja render +
+ * SAB memcpy) with no `.await`, so it's a direct FFI call from the worker
+ * thread — no Promise, no microtask round-trip. This is what lets native
+ * routes reach the same crossing floor as actions: the only Rust↔JS hops left
+ * are the tsfn call and the render-Promise resolution.
+ *
+ * Errors:
+ * - worker id not registered → NAPI Err
+ * - `data_len > buf_len` → NAPI Err (caller should have written ≤ buf_len)
+ * - assembled response > buf_len → writes a small framed 500 that fits and
+ *   returns ITS length, so the client gets a response instead of hanging.
+ * - `jinja::render` failure → writes a framed 500 into the SAB and returns its
+ *   length (the protocol error is converted to an HTTP 500 on the wire).
+ */
+export declare function napiRenderJinja(workerId: number, dataLen: number, templateName: string): NapiResult<number>
+
+/**
+ * Drop the connection's sender, which signals the per-conn task to exit
+ * and close the TCP socket. Idempotent — a missing conn is a no-op.
+ */
+export declare function napiSseClose(connId: bigint): NapiResult<undefined>
+
+/**
+ * JS provides a callback that fires once when Rust detects client disconnect.
+ * Stored as a thread-safe wrapper on the SseConn.
+ */
+export declare function napiSseRegisterAbort(connId: bigint, cb: () => void): NapiResult<undefined>
+
+/**
+ * JS reports the middleware open verdict. Single-shot — a second call is
+ * dropped (open_tx is taken on first use).
+ */
+export declare function napiSseSignalOpen(connId: bigint, status: number, body: Buffer, contentType: string): NapiResult<undefined>
+
+/**
+ * Enqueue one SSE frame for the given connection. Returns a Promise that
+ * resolves when the Rust-side per-conn task has finished the TCP write —
+ * cooperative backpressure for the JS reader loop.
+ */
+export declare function napiSseWrite(connId: bigint, bytes: Buffer): Promise<NapiResult<undefined>>
+
+/**
+ * Initiate close. code defaults applied client-side (default 1000);
+ * reason capped at 123 bytes (RFC 6455) at the JS layer.
+ * Idempotent — missing conn is a silent no-op.
+ */
+export declare function napiWsClose(connId: bigint, code: number, reason: string): Promise<NapiResult<undefined>>
+
+/**
+ * JS registers per-conn callbacks. Each Function arg is converted to a tsfn
+ * then wrapped in a Box<dyn Fn> closure, matching the field shape Task 3
+ * chose to keep cargo test --lib happy without napi linker symbols.
+ *
+ * Uses struct-payload form (WsMessageArg / WsCloseArg) because napi-rs
+ * does not accept tuple type parameters for Function<(A, B), R>.
+ * Task 5 + Task 9 must use matching TS object shapes.
+ *
+ * Single-shot registration; a second call replaces both handlers.
+ */
+export declare function napiWsRegisterHandlers(connId: bigint, onMessage: (arg: WsMessageArg) => void, onClose: (arg: WsCloseArg) => void): NapiResult<undefined>
+
+/**
+ * Send one frame. is_binary=false → Text frame (UTF-8 validated before
+ * enqueue), true → Binary frame. Returns Promise<()> resolving after the
+ * TCP write completes — cooperative backpressure, mirrors napi_sse_write.
+ */
+export declare function napiWsSend(connId: bigint, data: Buffer, isBinary: boolean): Promise<NapiResult<undefined>>
+
+/**
+ * JS reports the middleware verdict + chosen subprotocol. Single-shot;
+ * second call is a no-op (the Option is taken).
+ */
+export declare function napiWsSignalOpen(connId: bigint, status: number, body: Buffer, contentType: string, subprotocol: string): NapiResult<undefined>
+
+/**
+ * Register the set of action ids that Rust will accept on
+ * /_brust/action/<id>. Called once at boot from the main thread.
+ * Validates charset and rejects duplicates. Replaces any previous set
+ * (no incremental registration in MVP — register once at boot).
+ */
+export declare function registerActions(ids: Array<string>): NapiResult<number>
+
+export declare function registerRenderer(buf: Uint8Array, f: (arg: number | string) => Promise<number>): NapiResult<number>
+
+export declare function registerRoutes(configs: Array<string>): NapiResult<number>
+
+export interface ServeOptions {
+  port: number
+  workers: number
+  entry: string
+}
+
+export declare function untilReady(timeoutMs: number): Promise<NapiResult<undefined>>
+
+export declare function untilShutdown(): Promise<NapiResult<undefined>>
+
+export declare function workerId(): number | null
+
+/** Argument struct for the JS on_close callback. */
+export interface WsCloseArg {
+  code: number
+  reason: string
+}
+
+/**
+ * Argument struct for the JS on_message callback. napi-rs does not accept
+ * tuple type parameters for Function<(A, B), R> so we use an object payload
+ * instead. Task 5 + Task 9 must construct a matching TS type.
+ */
+export interface WsMessageArg {
+  data: Buffer
+  isBinary: boolean
+}