brustjs 0.1.35-alpha → 0.1.36-alpha

package/runtime/index.ts

@@ -49,6 +49,15 @@ export interface ServeOptions {
     /** Max ms a render waits for a free worker before 503 (AllBusy queues
      * instead of failing fast). Default 10000. */
     claimTimeoutMs?: number
+    /** tokio I/O runtime worker-thread count for the hyper server. Runs inside
+     * Bun (which has its own threads + render workers), so this is NOT
+     * one-per-core. Default `min(availableParallelism, 4)` (fallback 2). */
+    workerThreads?: number
+    /** Render slots per Bun worker — concurrent in-flight renders per isolate.
+     * Default 1 (byte-identical to single in-flight render per worker). The
+     * count is propagated to each worker via the `BRUST_RENDER_SLOTS` env var
+     * and scales the per-worker SAB so each slot keeps the single-slot capacity. */
+    renderSlots?: number
   }
 }
 
@@ -56,10 +65,11 @@ export interface ServeOptions {
 // (the worker wrote `[meta_len][meta][body]` into the SAB; Rust reads it
 // directly), `0` → the worker used the chunk channel via
 // `napi.renderChunk(workerId, len)` (React Suspense streaming) or owns the
-// socket independently (SSE/WS). The argument is a JSON envelope
-// `{ route_id, path, params }` produced by Rust's route table — see
+// socket independently (SSE/WS). The argument is the INLINE JSON envelope
+// `{ route_id, path, params }` produced by Rust's route table (the request
+// always crosses as a string — SAB-request is closed) — see
 // runtime/routes.ts::RouteCall.
-export type RenderFn = (envelopeJsonOrLen: number | string) => Promise<number>
+export type RenderFn = (envelopeJson: string, slot: number) => Promise<number>
 
 // Bun Workers run in the same OS process as the main thread; the `env` option
 // only patches the JS-visible process.env, not the native OS environment that
@@ -127,7 +137,16 @@ export const brust = {
       // leaving the prefix at its default — which broke custom-prefix routing.
       actionPrefix: opts.actionPrefix,
     })
-    const baseEnv = { ...process.env }
+    // Render slots per worker. Propagated to each worker via env (Bun Workers
+    // share the OS process, so the worker reads it from process.env at
+    // registerRenderer time). Precedence: explicit `tuning.renderSlots`, else the
+    // `BRUST_RENDER_SLOTS` env (so it's configurable like BRUST_WORKERS without
+    // per-app wiring), else 1 — byte-identical single in-flight render.
+    const renderSlots = Math.max(
+      1,
+      opts.tuning?.renderSlots ?? (Number(process.env.BRUST_RENDER_SLOTS) || 1),
+    )
+    const baseEnv = { ...process.env, BRUST_RENDER_SLOTS: String(renderSlots) }
     const workersArr: Worker[] = []
     for (let i = 0; i < opts.workers; i++) {
       // Bun.Worker requires the JS entry (post-bundling). For the skeleton,
@@ -142,9 +161,25 @@ export const brust = {
       const { registerInitialPool } = await import('./dev/worker-registry.ts')
       registerInitialPool(workersArr, opts.entry, opts.workers, baseEnv as Record<string, string>)
     }
-    // Bun Workers intercept SIGINT before Rust's ctrl_c() handler fires.
-    // Install a JS-level handler so the process actually exits on SIGINT.
-    process.on('SIGINT', () => process.exit(0))
+    // Bun Workers intercept SIGINT before Rust's ctrl_c() handler fires, so a
+    // JS-level handler owns process exit. GRACEFUL DRAIN: stop accepting new
+    // connections, let in-flight renders/streams finish (bounded by the drain
+    // timeout), THEN exit — so a slow stream isn't cut off mid-response (the
+    // teardown that produced spurious `split_meta` errors under load). A second
+    // signal (impatient Ctrl-C) forces an immediate exit. SIGTERM too, for
+    // container orchestrators (Docker/k8s send SIGTERM on stop).
+    let draining = false
+    const drainTimeoutMs = Number(process.env.BRUST_DRAIN_TIMEOUT_MS) || 10_000
+    const gracefulExit = (code: number) => {
+      if (draining) process.exit(code)
+      draining = true
+      ;(native as any)
+        .beginDrain(drainTimeoutMs)
+        .catch(() => {})
+        .finally(() => process.exit(0))
+    }
+    process.on('SIGINT', () => gracefulExit(130))
+    process.on('SIGTERM', () => gracefulExit(143))
     await (native as any).untilReady(opts.bootTimeoutMs ?? 5000)
     await (native as any).untilShutdown()
   },
@@ -247,8 +282,8 @@ export const brust = {
   // (or any ArrayBuffer the worker keeps rooted) — Rust captures the backing-store
   // pointer once here and reuses it for every render call. The buffer is held alive
   // by the worker's module scope; do not let it go out of scope.
-  registerRenderer(buf: Uint8Array, fn: RenderFn): number {
-    return (native as any).registerRenderer(buf, fn)
+  registerRenderer(buf: Uint8Array, slots: number, fn: RenderFn): number {
+    return (native as any).registerRenderer(buf, slots, fn)
   },
 
   /**
@@ -724,7 +759,11 @@ export const brust = {
         }
       }
 
-      const sab = new SharedArrayBuffer(opts.sabBytes ?? 256 * 1024)
+      // Render slots for this worker (set in serve() via the worker env). The
+      // SAB scales with the slot count so each slot's disjoint sub-region keeps
+      // the single-slot capacity; at K=1 this is byte-identical to before.
+      const renderSlots = Math.max(1, Number(process.env.BRUST_RENDER_SLOTS ?? 1) || 1)
+      const sab = new SharedArrayBuffer((opts.sabBytes ?? 256 * 1024) * renderSlots)
       const view = new Uint8Array(sab)
 
       let mcpManifest: import('./mcp/manifest.ts').McpManifest | null
@@ -766,8 +805,9 @@ export const brust = {
         actions: endpoints,
         getWorkerId: () => wid,
         mcp: mcpServer,
+        slots: renderSlots,
       })
-      wid = this.registerRenderer(view, renderer)
+      wid = this.registerRenderer(view, renderSlots, renderer)
     }
   },
 }

package/runtime/islands/island.tsx

@@ -1,4 +1,4 @@
-import { createElement, type ComponentType, type ReactNode } from 'react'
+import { createContext, createElement, useContext, type ComponentType, type ReactNode } from 'react'
 import type { IsrConfig } from './isr-jsx.ts'
 
 /** Triggers that activate hydration of an island marker. */
@@ -44,18 +44,30 @@ export interface IslandProps<P> {
   isr?: IsrConfig
 }
 
-/** Module-scope flag flipped by every `<Island>` render. `makeRenderer`
- * reads + resets it once per render to decide whether to prepend the
- * importmap + bootstrap script. */
-let __used = false
+/** Per-render box tracking whether any `<Island>` rendered. Created fresh per
+ * render and provided through {@link IslandUsedContext}; the renderer reads
+ * `box.used` once at the end to decide whether to prepend the importmap +
+ * bootstrap script.
+ *
+ * This is REQUEST-SCOPED (not a module-scope flag) so concurrent renders in one
+ * isolate (renderSlots>1) never cross-contaminate: React restores each render's
+ * context stack across Suspense resumption, so an interleaved peer setting its
+ * own box never flips ours. A module `let` could not give that guarantee. */
+export interface IslandUsedBox {
+  used: boolean
+}
 
-/** Internal — flipped by Island, read by makeRenderer. */
-export function consumeIslandUsedFlag(): boolean {
-  const v = __used
-  __used = false
-  return v
+/** Fresh per-render box. */
+export function createIslandUsedBox(): IslandUsedBox {
+  return { used: false }
 }
 
+/** Carries the per-render {@link IslandUsedBox} down to every `<Island>`. The
+ * renderer wraps the tree in a Provider with a fresh box; an `<Island>` rendered
+ * with no Provider (e.g. a standalone `renderToString` outside the React render
+ * path) reads `null` and is a no-op. */
+export const IslandUsedContext = createContext<IslandUsedBox | null>(null)
+
 // Constraint is `object`, NOT `Record<string, unknown>`: a TS `interface` has no
 // implicit index signature, so it does NOT satisfy `extends Record<string, unknown>`
 // — that made `P` fall back to the constraint and rejected any component whose
@@ -67,7 +79,10 @@ export function Island<P extends object>({
   props,
   hydrate = 'load',
 }: IslandProps<P>): ReactNode {
-  __used = true
+  // Request-scoped: flip THIS render's box (see IslandUsedContext). No-op if
+  // rendered without a Provider (standalone renderToString).
+  const usedBox = useContext(IslandUsedContext)
+  if (usedBox) usedBox.used = true
   const resolvedId = Component.name
   if (!resolvedId) {
     throw new Error(

package/runtime/render/stream.ts

@@ -4,7 +4,7 @@
 import { renderToPipeableStream, renderToString } from 'react-dom/server.node'
 import { createElement, type ReactNode, type ComponentType } from 'react'
 import { Writable } from 'node:stream'
-import { consumeIslandUsedFlag } from '../islands/island.tsx'
+import { IslandUsedContext, createIslandUsedBox } from '../islands/island.tsx'
 import { ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 import { injectCssLink } from './inject-css-link.ts'
 import { getCssHrefs, getCssHrefsForRoute } from '../css.ts'
@@ -15,11 +15,26 @@ import { getDevClientSnippet } from '../dev/inject.ts'
 
 export interface RenderBranchStreamingArgs {
   element: ReactNode
+  /** The render's SAB sub-view (whole buffer at slots=1). All chunk encodes
+   * write at offset 0 of this view → automatically the slot's base. */
   view: Uint8Array
+  /** The render slot index, passed to every napi.renderChunk* call so Rust
+   * reads/writes the matching SAB sub-region. Default 0 (single-slot path). */
+  slot?: number
   workerId: bigint
   napi: {
-    renderChunk: (workerId: bigint, len: number, sabBytes: Uint8Array) => Promise<void>
-    renderChunkFinal: (workerId: bigint, len: number, sabBytes: Uint8Array) => Promise<void>
+    renderChunk: (
+      workerId: bigint,
+      slot: number,
+      len: number,
+      sabBytes: Uint8Array,
+    ) => Promise<void>
+    renderChunkFinal: (
+      workerId: bigint,
+      slot: number,
+      len: number,
+      sabBytes: Uint8Array,
+    ) => Promise<void>
   }
   errorBoundary: ComponentType<{ error: Error }>
   /** Status for the successful (non-error) render. Default 200. Used by
@@ -97,15 +112,18 @@ function concatBuffers(parts: Uint8Array[], withBootstrap: boolean): Uint8Array
 
 export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<void> {
   const { element, view, workerId, napi, errorBoundary } = args
+  const slot = args.slot ?? 0
   const successStatus = args.status ?? 200
   const extraHeaders = args.headers ?? {}
 
-  // Reset the islands flag at the start of every render — the streaming path
-  // (which doesn't read the flag at the end) would otherwise leak its setting
-  // to the next render. consumeIslandUsedFlag() reads-and-resets so calling
-  // here is safe; the actual read for the buffering path happens at _final
-  // time and sees only flips made during THIS render's React work.
-  consumeIslandUsedFlag()
+  // Request-scoped islands signal: a fresh box per render, provided to every
+  // <Island> through IslandUsedContext. The buffering path reads `box.used` at
+  // _final to decide whether to prepend the importmap + bootstrap. Per-render
+  // (not a module flag) so concurrent renders in one isolate (renderSlots>1)
+  // never cross-contaminate — React restores each render's context across
+  // Suspense resumption. No start-of-render reset needed: the box starts false.
+  const islandUsedBox = createIslandUsedBox()
+  const renderTree = createElement(IslandUsedContext.Provider, { value: islandUsedBox }, element)
 
   return new Promise<void>((resolve, reject) => {
     let finalSent = false
@@ -113,7 +131,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
       if (finalSent) return
       finalSent = true
       try {
-        await napi.renderChunk(workerId, 0, view)
+        await napi.renderChunk(workerId, slot, 0, view)
         resolve()
       } catch (e) {
         reject(e)
@@ -139,7 +157,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             // Wait for the header chunk to be flushed before sending body chunks.
             if (headerSent) await headerSent
             const len = encodeBodyChunk(view, chunk)
-            await napi.renderChunk(workerId, len, view)
+            await napi.renderChunk(workerId, slot, len, view)
           }
           cb()
         } catch (e) {
@@ -149,7 +167,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
       async final(cb: (e?: Error | null) => void) {
         try {
           if (mode === 'buffering') {
-            const islandsUsed = consumeIslandUsedFlag()
+            const islandsUsed = islandUsedBox.used
             let body = concatBuffers(buffer, islandsUsed)
             const perRouteHrefs = args.routePath ? getCssHrefsForRoute(args.routePath) : []
             body = injectCssLink(body, [...getCssHrefs(), ...perRouteHrefs])
@@ -162,7 +180,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               headers: extraHeaders,
             })
             const len = encodeFirstChunk(view, meta, body)
-            await napi.renderChunkFinal(workerId, len, view)
+            await napi.renderChunkFinal(workerId, slot, len, view)
             finalSent = true
             resolve()
             mode = 'done'
@@ -184,7 +202,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
     let allReadyFired = false
     let stream: ReturnType<typeof renderToPipeableStream>
     try {
-      stream = renderToPipeableStream(element, {
+      stream = renderToPipeableStream(renderTree, {
         onShellReady() {
           // React fires onAllReady synchronously AFTER onShellReady in the
           // same microtask queue flush when there is no pending Suspense.
@@ -247,7 +265,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             ;(async () => {
               try {
                 const len = encodeFirstChunk(view, meta, flushed)
-                await napi.renderChunk(workerId, len, view)
+                await napi.renderChunk(workerId, slot, len, view)
                 resolveHeader()
               } catch (e) {
                 rejectHeader(e)
@@ -267,7 +285,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             ;(async () => {
               try {
                 const len = encodeFirstChunk(view, meta, encoder.encode(html))
-                await napi.renderChunkFinal(workerId, len, view)
+                await napi.renderChunkFinal(workerId, slot, len, view)
                 finalSent = true
                 resolve()
               } catch (e) {
@@ -285,7 +303,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             ;(async () => {
               try {
                 const len = encodeFirstChunk(view, meta, encoder.encode('Internal Server Error'))
-                await napi.renderChunkFinal(workerId, len, view)
+                await napi.renderChunkFinal(workerId, slot, len, view)
                 finalSent = true
                 resolve()
               } catch (e) {
@@ -307,7 +325,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
       ;(async () => {
         try {
           const len = encodeFirstChunk(view, meta, encoder.encode('Internal Server Error'))
-          await napi.renderChunkFinal(workerId, len, view)
+          await napi.renderChunkFinal(workerId, slot, len, view)
           finalSent = true
           resolve()
         } catch (ee) {