@brust/core 2.0.0-alpha.3 → 2.0.0-alpha.31

package/src/navigate.ts

@@ -0,0 +1,19 @@
+// `navigate()` (SPA navigation, design §5.3): the types shared by the browser and server entries, and the server stub.
+export interface NavigateOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean
+}
+export type NavTrigger = 'link' | 'navigate' | 'popstate'
+/** `detail` of `brust:nav:load`. */
+export interface NavLoadDetail { id: number; url: string; from: string; trigger: NavTrigger }
+/** `detail` of `brust:nav:success`. */
+export interface NavSuccessDetail extends NavLoadDetail { status: number }
+/** `detail` of `brust:nav:error`: `swapped` tells whether a page (a 404, an error page) was swapped in anyway. */
+export interface NavErrorDetail extends NavLoadDetail { status?: number; error?: unknown; swapped: boolean }
+
+export function navigate(_url: string, _opts?: NavigateOptions): Promise<void> {
+  throw new Error('navigate is browser-only (call it from a component or island running in the browser)')
+}
+
+/** The page cache lives in the browser: nothing to clear on the server. */
+export function clearNavigationCache(): void {}

package/src/navigation.ts

@@ -0,0 +1,91 @@
+// The built-in `navigation` store (SPA navigation design §11): the `brust:nav:*` events as
+// signals, so a component reads navigation state through `useStore(navigation)` like any other store. Browser-safe and
+// React-free, like `@brust/core/store`. The name is reserved (the compiler refuses a user `defineStore('navigation')`).
+//
+// Server: the factory paints `idle` and the loader seeds `url` with the request's path + search (handlers.ts), so the first
+// paint is right and hydration matches. Browser: this module listens to the four events once and `batch`-sets the signals.
+import { batch, defineStore, signal } from '@brust/runtime-dom/store'
+
+export type NavigationTrigger = 'link' | 'navigate' | 'popstate'
+
+const at = (): string => (typeof location === 'undefined' ? '/' : location.pathname + location.search)
+
+/** `new URL(href).pathname + search`, the way the store spells a page; `href` itself when it does not parse. */
+const path = (href: unknown): string => {
+  try {
+    const u = new URL(String(href), typeof location === 'undefined' ? 'http://x' : location.href)
+    return u.pathname + u.search
+  } catch {
+    return String(href)
+  }
+}
+
+declare const __BRUST_DEV__: boolean | undefined
+
+// Instances this module's factory made: a record under the name that is not one belongs to someone else's defineStore.
+const made = new WeakSet<object>()
+
+export const navigation = defineStore('navigation', () => {
+  const store = {
+    /** `'loading'` from `brust:nav:load` until `success` / `error`. */
+    state: signal<'idle' | 'loading'>('idle'),
+    /** Path + search of the page on screen: updated at `success`, and at `error` when the page was swapped in. */
+    url: signal<string>(at()),
+    /** Path + search being loaded, else `null`. */
+    to: signal<string | null>(null),
+    /** Of the current or last navigation. */
+    trigger: signal<NavigationTrigger | null>(null),
+    /** HTTP status of the last navigation. */
+    status: signal<number | null>(null),
+    /** Message of the last failed navigation; cleared at the next `load`. */
+    error: signal<string | null>(null),
+    /** The last navigation id (0 before any). */
+    id: signal<number>(0),
+  }
+  made.add(store)
+  return store
+})
+
+// One subscription per tab, whichever chunk evaluates this module first (the store registry is shared the same way).
+const BOUND = Symbol.for('brust.navigation')
+if (typeof document !== 'undefined' && !(globalThis as { [BOUND]?: true })[BOUND]) {
+  ;(globalThis as { [BOUND]?: true })[BOUND] = true
+  // A user `defineStore('navigation', …)` outside a component is not seen by the compiler (`store-name-reserved`); it
+  // would share this record by name, so say so in dev.
+  if (typeof __BRUST_DEV__ !== 'undefined' && __BRUST_DEV__ && !made.has(navigation()))
+    console.warn("[brust] the store name 'navigation' is reserved for @brust/core/navigation, but another defineStore('navigation') made the record in use; rename yours")
+  const on = (name: string, apply: (d: Record<string, unknown>) => void) =>
+    document.addEventListener(`brust:nav:${name}`, (e) => apply((e as CustomEvent).detail ?? {}))
+  on('load', (d) =>
+    batch(() => {
+      navigation.state.set('loading')
+      navigation.to.set(path(d.url))
+      navigation.trigger.set(d.trigger as NavigationTrigger)
+      navigation.error.set(null)
+      navigation.id.set(d.id as number)
+    }),
+  )
+  on('success', (d) =>
+    batch(() => {
+      navigation.state.set('idle')
+      navigation.url.set(path(d.url))
+      navigation.to.set(null)
+      navigation.trigger.set(d.trigger as NavigationTrigger)
+      navigation.status.set(d.status as number)
+      navigation.error.set(null)
+      navigation.id.set(d.id as number)
+    }),
+  )
+  on('error', (d) =>
+    batch(() => {
+      navigation.state.set('idle')
+      // A swapped error page (404, 500) is on screen; a failed swap leaves the old page where it was.
+      if (d.swapped) navigation.url.set(path(d.url))
+      navigation.to.set(null)
+      navigation.trigger.set(d.trigger as NavigationTrigger)
+      navigation.status.set((d.status as number | undefined) || null) // 0: no response
+      navigation.error.set(d.error instanceof Error ? d.error.message : d.error != null ? String(d.error) : `HTTP ${d.status}`)
+      navigation.id.set(d.id as number)
+    }),
+  )
+}

package/src/routes.ts

@@ -1,3 +1,5 @@
+/// <reference path="./css-modules.d.ts" />
+/// <reference path="./assets.d.ts" />
 // Route tree, ids and loader verdicts (spec S4, S7 step 4). M2 routes carry ONLY
 // `path/Component/loader/cache/children`; every other 0.1.x field fails loudly (M3).
 
@@ -23,21 +25,37 @@ export interface LoaderReq {
   search: Record<string, string>
 }
 
+/** The response a loader shapes (F464). One per request, shared by every loader in the chain in chain order:
+ * `set` replaces, `append` adds (repeated `Set-Cookie` survive). The headers go on whatever the chain answers:
+ * the page, `notFound()`, `redirect()` and an `httpError()`. `Content-Type`, `Content-Length`,
+ * `Transfer-Encoding`, `Connection` and `Location` are the server's (a redirect's comes from `redirect()`):
+ * setting one throws in dev and is dropped with a warning in production. */
+export interface LoaderRes {
+  headers: Headers
+}
+
 export interface LoaderCtx<P = Record<string, string>> {
   params: P
   path: string
   req: LoaderReq
+  res: LoaderRes
 }
 
+/** `brust build --target static` (gaps round R9.2): `params` lists the values of a dynamic route's
+ * `{name}` segments, one record per page; `false` leaves the route out of the static output. The
+ * server and Cloudflare targets ignore it. */
+export type RouteSsgConfig<P = Record<string, string>> = { params?: () => P[] | Promise<P[]> } | false
+
 export interface Route<P = Record<string, string>, D = unknown> {
   path?: string
   Component?: ComponentType<any>
   loader?: (ctx: LoaderCtx<P>) => Promise<D> | D
   cache?: RouteCacheConfig
+  ssg?: RouteSsgConfig<P>
   children?: Route<any, any>[]
 }
 
-export const ALLOWED_ROUTE_FIELDS = ['path', 'Component', 'loader', 'cache', 'children'] as const
+export const ALLOWED_ROUTE_FIELDS = ['path', 'Component', 'loader', 'cache', 'ssg', 'children'] as const
 const ALLOWED_CACHE_FIELDS = ['ttl_seconds', 'prefix', 'bypass', 'tags'] as const
 const M3_CACHE_FIELDS = ['key', 'key_ttl_seconds'] as const
 
@@ -61,6 +79,18 @@ function validate(node: Route, where: string): void {
   if (node.path !== undefined && typeof node.path !== 'string') throw new BrustRouteError(`route ${where}: path must be a string`)
   if (node.loader !== undefined && typeof node.loader !== 'function')
     throw new BrustRouteError(`route ${where}: loader must be a function`)
+  if (node.ssg !== undefined) {
+    const ssg = node.ssg as unknown
+    if (ssg !== false && (typeof ssg !== 'object' || ssg === null || Array.isArray(ssg)))
+      throw new BrustRouteError(`route ${where}: ssg must be false or { params }`)
+    if (ssg !== false) {
+      for (const k of Object.keys(ssg as object))
+        if (k !== 'params') throw new BrustRouteError(`route ${where}: unknown ssg field ssg.${k} (allowed: params)`)
+      const params = (ssg as { params?: unknown }).params
+      if (params !== undefined && typeof params !== 'function') throw new BrustRouteError(`route ${where}: ssg.params must be a function`)
+    }
+    if (node.children !== undefined) throw new BrustRouteError(`route ${where}: ssg on a layout route is not supported (put it on each leaf)`)
+  }
   if (node.cache !== undefined) {
     if (typeof node.cache !== 'object' || node.cache === null) throw new BrustRouteError(`route ${where}: cache must be an object`)
     for (const k of Object.keys(node.cache)) {

package/src/run.ts

@@ -4,45 +4,82 @@
 // once (130 / 143); a signal before every worker registered exits 0 at once (nothing is being
 // served yet, and the server's drain only starts once it accepts). A worker that dies (error,
 // process.exit, OOM) → drain → exit 1: M2 does not respawn, the supervisor restarts the process.
+// F165: a build whose manifest says `needs_workers: false` (no loader, job, actions app or cache
+// adapter) spawns none; the server then serves at once and a stray worker call answers 503.
 // Nothing here returns on its own: a started server keeps the process alive and a drained one
 // does not end it, so every exit is an explicit `process.exit`.
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { type BrustConfig, loadConfig } from './config'
-import { beginDrain, type StartOptions, startServer, untilReady } from './native'
-import { SLOT_BYTES } from './worker'
+import { type BrustConfig, type ConfigOverrides, loadConfig } from './config'
+import { beginDrain, localAddr, type StartOptions, type StreamOptions, startServer, untilReady } from './native'
+import { DEFAULT_MAX_LOADER_RESPONSE_BYTES } from './worker'
 
 export interface RunOptions {
   distDir?: string
   /** The routes module the workers import (`export const routes` or default). */
   entry?: string
   /** Overrides below env (CLI flags): see config.ts (incl. `bootTimeoutMs`, default 30000). */
-  config?: Partial<BrustConfig>
+  config?: ConfigOverrides
+  /** Static output (gaps round L9): runs once every worker is ready, with the bound `host:port`;
+   * then the server drains and the process exits with the returned code. */
+  onReady?: (addr: string) => Promise<number>
 }
 
 /** The manifest fields `run` needs (build/manifest.ts owns the full shape). */
 export interface RunManifest {
-  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } & StreamKeys | null
+  /** L16 R16.3: `brust build --actions-only`: no page routes and no routes entry. */
+  actions_only?: boolean
+  /** L16 R16.4b: a page-only build; the actions app is deployed elsewhere (`[actions] base_url`). */
+  actions_remote?: { prefix: string } | null
   /** `[cache]`: the server's L2 settings (the workers load the adapter itself). */
   cache?: { adapter: string; getTimeoutMs: number; maxBodyBytes: number; namespace: string; buildId: string } | null
+  /** F165: `false` = no route can call a worker; absent (older manifests) = the pool is needed. */
+  needs_workers?: boolean
+}
+
+/** F475: the `[actions] stream` keys of `manifest.actions`, passed to napi as they are. */
+type StreamKeys = Pick<StreamOptions, 'stream' | 'maxStreamBytes' | 'streamIdleMs' | 'streamTotalMs' | 'maxStreams'>
+
+/** F475: the stream keys `a` carries; none without a `stream` list, so an app without one starts as before. */
+function streamOptions(a: StreamKeys): StreamKeys {
+  if (!a.stream?.length) return {}
+  const { stream, maxStreamBytes, streamIdleMs, streamTotalMs, maxStreams } = a
+  return { stream, maxStreamBytes, streamIdleMs, streamTotalMs, ...(maxStreams !== undefined ? { maxStreams } : {}) }
+}
+
+/** F165 (R40.1): the pool size `run` spawns: none only when the build said no request needs one. */
+export function workerCount(cfg: BrustConfig, m: RunManifest): number {
+  return m.needs_workers === false ? 0 : cfg.workers
 }
 
 /** Pure: the napi `StartOptions`. No actions/cors/cache → exactly the pre-actions keys. */
-export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string): StartOptions {
+export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string, devToken?: string): StartOptions {
   return {
     host: cfg.host,
     port: cfg.port,
     distDir,
-    workers: cfg.workers,
+    workers: workerCount(cfg, m),
     callTimeoutMs: cfg.callTimeoutMs,
+    ...(cfg.maxLoaderResponseBytes !== undefined && cfg.maxLoaderResponseBytes !== DEFAULT_MAX_LOADER_RESPONSE_BYTES ? { maxLoaderResponseBytes: cfg.maxLoaderResponseBytes } : {}),
     workerThreads: cfg.ioThreads,
     generator: `brust/${version}`,
-    ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes, ...(m.actions.maxResponseBytes !== undefined ? { maxResponseBytes: m.actions.maxResponseBytes } : {}), ...(m.actions.crossSite ? { crossSite: m.actions.crossSite } : {}) } } : {}),
+    ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes, ...(m.actions.maxResponseBytes !== undefined ? { maxResponseBytes: m.actions.maxResponseBytes } : {}), ...(m.actions.crossSite ? { crossSite: m.actions.crossSite } : {}), ...streamOptions(m.actions) } } : {}),
+    ...(actionsClient(cfg, m) ? { actionsClient: actionsClient(cfg, m) } : {}),
     ...(cfg.cors ? { cors: cfg.cors } : {}),
+    ...(devToken ? { devToken } : {}),
     ...(m.cache ? { l2: { adapter: m.cache.adapter, getTimeoutMs: m.cache.getTimeoutMs, maxBodyBytes: m.cache.maxBodyBytes, namespace: m.cache.namespace, buildId: m.cache.buildId } } : {}),
   }
 }
 
+/** L16: what the page tells the browser `client()` (R16.1/R16.2); absent while it would only repeat the prefix script. */
+function actionsClient(cfg: BrustConfig, m: RunManifest): NonNullable<StartOptions['actionsClient']> | undefined {
+  const credentials = cfg.actionsCredentials !== undefined && cfg.actionsCredentials !== 'same-origin' ? cfg.actionsCredentials : undefined
+  if (cfg.actionsBaseUrl === undefined && credentials === undefined && !m.actions_remote) return undefined
+  const prefix = m.actions?.prefix ?? m.actions_remote?.prefix
+  return { ...(prefix ? { prefix } : {}), ...(cfg.actionsBaseUrl !== undefined ? { baseUrl: cfg.actionsBaseUrl } : {}), ...(credentials ? { credentials } : {}) }
+}
+
 /** Every worker's response buffer, kept reachable until the process exits (see run()). */
 const workerBuffers: SharedArrayBuffer[] = []
 
@@ -63,7 +100,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail(`bad manifest ${manifest}: ${(e as Error).message}`)
   }
   const entry = resolve(process.env.BRUST_APP_ENTRY || opts.entry || 'routes.tsx')
-  if (!existsSync(entry)) fail(`routes entry ${entry} not found`)
+  // R16.3: an actions-only dist has no pages, so no routes module either.
+  if (!m.actions_only && !existsSync(entry)) fail(`routes entry ${entry} not found`)
 
   let cfg: BrustConfig
   try {
@@ -72,9 +110,11 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail((e as Error).message)
   }
 
+  if (m.actions_remote && cfg.actionsBaseUrl === undefined)
+    fail('this build has no local actions app: set [actions] base_url (or BRUST_ACTIONS_BASE_URL) to the deployment that serves them')
   const version: string = (await Bun.file(join(import.meta.dir, '../package.json')).json()).version
   try {
-    startServer(startOptions(cfg, distDir, m, version))
+    startServer(startOptions(cfg, distDir, m, version, process.env.BRUST_DEV_TOKEN || undefined))
   } catch (e) {
     fail((e as Error).message)
   }
@@ -87,6 +127,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     ...process.env,
     NODE_ENV: process.env.NODE_ENV,
     BRUST_RENDER_SLOTS: String(cfg.renderSlots),
+    BRUST_SLOT_BYTES: String(cfg.slotBytes),
+    BRUST_MAX_LOADER_RESPONSE_BYTES: String(cfg.maxLoaderResponseBytes),
     BRUST_DIST_DIR: distDir,
     BRUST_APP_ENTRY: entry,
     // One cache-adapter origin per process: its workers' published events are not replayed here.
@@ -111,11 +153,12 @@ export async function run(opts: RunOptions = {}): Promise<void> {
       .finally(() => exit(failed ? 1 : code))
   }
 
+  const workers = workerCount(cfg, m)
   const url = new URL('./worker.ts', import.meta.url)
-  for (let i = 0; i < cfg.workers; i++) {
+  for (let i = 0; i < workers; i++) {
     // The response buffer is owned HERE, for the process lifetime: the Rust dispatcher keeps a raw
     // pointer into it, so it must not be freed with the worker (crates/brust-napi dispatch.rs).
-    const sab = new SharedArrayBuffer(SLOT_BYTES * cfg.renderSlots)
+    const sab = new SharedArrayBuffer(cfg.slotBytes * cfg.renderSlots)
     workerBuffers.push(sab)
     const w = new Worker(url, { env: { ...env, BRUST_WORKER_ID: String(i) }, workerData: { sab } } as WorkerOptions)
     // No respawn in M2: a worker that fails to boot or dies later takes the process down loudly
@@ -157,6 +200,15 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail(`workers not ready: ${String((e as Error).message ?? e)} (BRUST_BOOT_TIMEOUT_MS=${cfg.bootTimeoutMs})`)
   }
   ready = true
-  console.log(`[brust] ready (${cfg.workers} worker${cfg.workers === 1 ? '' : 's'})`)
+  console.log(`[brust] ready (${workers} worker${workers === 1 ? '' : 's'})`)
+  if (opts.onReady) {
+    let code = 1
+    try {
+      code = await opts.onReady(localAddr())
+    } catch (e) {
+      console.error(`[brust] ${(e as Error).stack ?? String(e)}`)
+    }
+    if (!draining) drainThenExit(code)
+  }
   await new Promise<never>(() => {})
 }