@brust/core 2.0.0-alpha.34 → 2.0.0-alpha.36

package/src/dev/proxy.ts

@@ -61,13 +61,15 @@ export const WS_PATH = '/_brust/dev/ws'
 export const DEVTOOLS_PATH = '/_brust/dev/devtools.js'
 export const TRACES_PATH = '/_brust/dev/traces'
 export const META_PATH = '/_brust/dev/meta'
-const scriptTag = (gen: number) => `<script type="module" src="${CLIENT_PATH}?g=${gen}"></script><script type="module" src="${DEVTOOLS_PATH}"></script>`
+/** F495: the dev channel's URLs for an app mounted under `base` (`''` = the root): the page's scripts and the WebSocket connect under it. */
+export const devPaths = (base = '') => ({ client: `${base}${CLIENT_PATH}`, ws: `${base}${WS_PATH}`, devtools: `${base}${DEVTOOLS_PATH}`, traces: `${base}${TRACES_PATH}`, meta: `${base}${META_PATH}` })
+const scriptTag = (gen: number, base = '') => `<script type="module" src="${devPaths(base).client}?g=${gen}"></script><script type="module" src="${devPaths(base).devtools}"></script>`
 
 const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string)
 
 /** `html` with the dev client script before `</head>` (else at the end). */
-export function inject(html: string, gen: number, trace: unknown | null = null): string {
-  const tag = scriptTag(gen) + (trace ? traceTag(trace) : '')
+export function inject(html: string, gen: number, trace: unknown | null = null, base = ''): string {
+  const tag = scriptTag(gen, base) + (trace ? traceTag(trace) : '')
   const i = html.search(/<\/head\s*>/i)
   return i >= 0 ? html.slice(0, i) + tag + html.slice(i) : html + tag
 }
@@ -93,8 +95,8 @@ export function decodeTrace(h: string | null): unknown | null {
 }
 
 /** A small HTML page (so even a plain-text 5xx or "no child yet" carries the client script). */
-function htmlPage(status: number, title: string, body: string, gen: number, trace: unknown | null = null): Response {
-  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>${scriptTag(gen)}${trace ? traceTag(trace) : ''}</head><body style="font:14px ui-monospace,monospace;padding:24px"><h1>${esc(title)}</h1><pre style="white-space:pre-wrap">${esc(body)}</pre></body></html>`
+function htmlPage(status: number, title: string, body: string, gen: number, trace: unknown | null = null, base = ''): Response {
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>${scriptTag(gen, base)}${trace ? traceTag(trace) : ''}</head><body style="font:14px ui-monospace,monospace;padding:24px"><h1>${esc(title)}</h1><pre style="white-space:pre-wrap">${esc(body)}</pre></body></html>`
   return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } })
 }
 
@@ -136,7 +138,9 @@ function devtoolsBundle(): Promise<string> {
 /** The trace a proxied response carried (read by `onRequest`; the header itself never reaches the browser). */
 const traceOf = new WeakMap<Response, unknown>()
 
-export function startProxy(o: { hostname: string; port: number; allowedHosts?: string; token: string }, view: DevView): DevProxy {
+export function startProxy(o: { hostname: string; port: number; allowedHosts?: string; token: string; basePath?: string }, view: DevView): DevProxy {
+  const base = o.basePath ?? ''
+  const P = devPaths(base)
   const traces: TraceEntry[] = []
   let seq = 0
   const allowed = allowedHosts(o.hostname, o.allowedHosts ?? process.env.BRUST_DEV_ALLOWED_HOSTS)
@@ -155,7 +159,7 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
     const port = view.upstream()
     if (port === null) {
       const d = view.diag()
-      return htmlPage(503, d ? `brust dev: ${d.rule}` : 'brust dev: building…', d?.raw ?? 'The first build is running. This page reloads when it is ready.', gen)
+      return htmlPage(503, d ? `brust dev: ${d.rule}` : 'brust dev: building…', d?.raw ?? 'The first build is running. This page reloads when it is ready.', gen, null, base)
     }
     const headers = new Headers(req.headers)
     // The token only this proxy knows: whatever a browser sent under that name is overwritten.
@@ -174,13 +178,13 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
         // biome-ignore lint/suspicious/noExplicitAny: Bun's fetch option
       } as any)
     } catch (e) {
-      return htmlPage(502, 'brust dev: the server is not reachable', String((e as Error).message ?? e), gen)
+      return htmlPage(502, 'brust dev: the server is not reachable', String((e as Error).message ?? e), gen, null, base)
     }
     const out = new Headers(res.headers)
     // The trace never reaches the browser as a header: it travels in the page (`#__brust_trace`) and `/_brust/dev/traces`.
     const trace = decodeTrace(res.headers.get('x-brust-dev'))
     out.delete('x-brust-dev')
-    const isAction = req.method !== 'GET' && req.method !== 'HEAD' ? true : url.pathname.startsWith('/_brust/action')
+    const isAction = req.method !== 'GET' && req.method !== 'HEAD' ? true : url.pathname.startsWith(`${base}/_brust/action`)
     if (trace || isAction) {
       traces.push({ id: ++seq, at: Date.now(), kind: trace ? 'page' : 'action', method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), trace })
       if (traces.length > MAX_TRACES) traces.shift()
@@ -195,9 +199,9 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
     if (req.method === 'HEAD' || res.status === 204 || res.status === 304) return new Response(null, { status: res.status, headers: out })
     if (/text\/html/i.test(type)) {
       out.set('content-type', type)
-      return tag(new Response(inject(await res.text(), gen, trace), { status: res.status, headers: out }))
+      return tag(new Response(inject(await res.text(), gen, trace, base), { status: res.status, headers: out }))
     }
-    if (doc && res.status >= 500) return tag(htmlPage(res.status, `${res.status} ${res.statusText || 'server error'}`, await res.text(), gen, trace))
+    if (doc && res.status >= 500) return tag(htmlPage(res.status, `${res.status} ${res.statusText || 'server error'}`, await res.text(), gen, trace, base))
     return tag(new Response(res.body, { status: res.status, headers: out }))
   }
 
@@ -216,17 +220,17 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
       // DNS rebinding: a page on evil.example whose name resolves to 127.0.0.1 would otherwise read the app and the
       // source paths in build errors. Only the dev server's own names are answered.
       if (!allowed.has(hostName(req.headers.get('host') ?? ''))) return new Response('brust dev: unexpected Host header (set BRUST_DEV_ALLOWED_HOSTS to allow it)', { status: 421 })
-      if (url.pathname === WS_PATH && !sameOriginOrNone(req.headers.get('origin'), req.headers.get('host'))) return new Response('brust dev: cross-origin WebSocket refused', { status: 403 })
-      if (url.pathname === WS_PATH) return srv.upgrade(req, { data: undefined }) ? undefined : new Response('websocket expected', { status: 426 })
-      if (url.pathname === TRACES_PATH) return Response.json({ traces }, { headers: { 'cache-control': 'no-store' } })
-      if (url.pathname === META_PATH) return Response.json(view.meta() ?? {}, { headers: { 'cache-control': 'no-store' } })
-      if (url.pathname === DEVTOOLS_PATH) {
+      if (url.pathname === P.ws && !sameOriginOrNone(req.headers.get('origin'), req.headers.get('host'))) return new Response('brust dev: cross-origin WebSocket refused', { status: 403 })
+      if (url.pathname === P.ws) return srv.upgrade(req, { data: undefined }) ? undefined : new Response('websocket expected', { status: 426 })
+      if (url.pathname === P.traces) return Response.json({ traces }, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === P.meta) return Response.json(view.meta() ?? {}, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === P.devtools) {
         return devtoolsBundle().then(
           (js) => new Response(js, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } }),
           (e: Error) => new Response(e.message, { status: 500 }),
         )
       }
-      if (url.pathname === CLIENT_PATH) return new Response(DEV_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } })
+      if (url.pathname === P.client) return new Response(DEV_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } })
       const t0 = performance.now()
       const res = await forward(req)
       view.onRequest({ method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), cache: res.headers.get('x-brust-cache'), trace: traceOf.get(res) ?? null })

package/src/index.ts

@@ -2,6 +2,11 @@
 /// <reference path="./assets.d.ts" />
 // `@brust/core`: the app-facing API.
 export { buildTime } from './build-time'
+
+/** F495 `[server] base_path`: the path the app is mounted under (`/portal`), `''` at the root. Read-only: build URLs with it
+ * (`${basePath}/_brust/…` is brust's own; every URL you write is already the real one). Set from the manifest (`brust start`) or the
+ * config (`brust build`) before the app's modules load. */
+export const basePath: string = process.env.BRUST_BASE_PATH ?? ''
 export { clearNavigationCache, navigate } from './navigate'
 export type { NavErrorDetail, NavLoadDetail, NavigateOptions, NavSuccessDetail, NavTrigger } from './navigate'
 export { cache } from './cache'

package/src/launcher-watch.ts

@@ -15,12 +15,63 @@ export function pidAlive(pid: number): boolean {
   }
 }
 
+/** F492 (PID reuse): the identity of a process that outlives a PID: its creation time (a FILETIME, 100 ns ticks since 1601), read once
+ * through kernel32 `GetProcessTimes` (`OpenProcess` with the query-limited right: no elevation, no process table, no PowerShell). A PID
+ * that is reused by another process has another creation time. `undefined` when it cannot be read (not Windows, the process is gone, no
+ * access, `bun:ffi` missing): the watch then keeps its pid-only behaviour. Synchronous, a few microseconds, nothing awaited. */
+export function processIdentity(pid: number): string | undefined {
+  if (process.platform !== 'win32') return undefined
+  const k = kernel32()
+  if (!k) return undefined
+  try {
+    const h = k.OpenProcess(0x1000 /* PROCESS_QUERY_LIMITED_INFORMATION */, 0, pid)
+    if (!h) return undefined
+    try {
+      const t = new BigUint64Array(4) // creation, exit, kernel, user
+      const base = k.ptr(t)
+      if (!k.GetProcessTimes(h, base, k.ptr(t, 8), k.ptr(t, 16), k.ptr(t, 24))) return undefined
+      return t[0]!.toString()
+    } finally {
+      k.CloseHandle(h)
+    }
+  } catch {
+    return undefined
+  }
+}
+
+type Kernel32 = {
+  OpenProcess(access: number, inherit: number, pid: number): unknown
+  GetProcessTimes(h: unknown, a: unknown, b: unknown, c: unknown, d: unknown): number
+  CloseHandle(h: unknown): number
+  ptr: (view: ArrayBufferView, offset?: number) => never
+}
+let k32: Kernel32 | null | undefined
+/** The three kernel32 bindings, opened ONCE for the life of the process: `dlopen` compiles a binding per symbol and holds it until
+ * the library is closed, and the watch reads the identity every tick of a long-running server. `null` = unavailable (kept). */
+function kernel32(): Kernel32 | null {
+  if (k32 !== undefined) return k32
+  try {
+    const { dlopen, FFIType, ptr } = require('bun:ffi') as typeof import('bun:ffi')
+    const s = dlopen('kernel32.dll', {
+      OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.ptr },
+      GetProcessTimes: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+      CloseHandle: { args: [FFIType.ptr], returns: FFIType.i32 },
+    }).symbols
+    k32 = { ...(s as unknown as Omit<Kernel32, 'ptr'>), ptr: ptr as Kernel32['ptr'] }
+  } catch {
+    k32 = null
+  }
+  return k32
+}
+
 export interface LauncherWatchOptions {
   /** Runs once, when the parent is gone. */
   onGone: (pid: number) => void
   platform?: NodeJS.Platform
   ppid?: number
   alive?: (pid: number) => boolean
+  /** The parent's identity (default: its creation time, win32). Read once at boot and again on each tick while the pid answers alive: a different value means the pid was reused, so the launcher is gone. */
+  identity?: (pid: number) => string | undefined
   intervalMs?: number
   log?: (line: string) => void
 }
@@ -35,8 +86,10 @@ export function watchLauncher(opts: LauncherWatchOptions): { pid: number | undef
     ;(opts.log ?? console.error)(`[brust] launcher (pid ${ppid}) is already gone at boot: not watching it`)
     return none
   }
+  const identity = opts.identity ?? processIdentity
+  const born = identity(ppid)
   const timer = setInterval(() => {
-    if (alive(ppid)) return
+    if (alive(ppid) && (born === undefined || identity(ppid) === born)) return
     clearInterval(timer)
     opts.onGone(ppid)
   }, opts.intervalMs ?? 1000)

package/src/native.ts

@@ -10,6 +10,13 @@ export interface InvalidateArgs {
   tags?: string[]
   path?: string
   method?: string
+  /**
+   * F493: narrow the page invalidation to entries whose evaluated route-cache `prefix` equals this
+   * string exactly (`''` = routes with no prefix). With `path`: that path of that prefix; with
+   * `tags`: that prefix's tagged pages (the job cache is not touched); alone: every page of that
+   * prefix. Not with `key`.
+   */
+  prefix?: string
 }
 export interface InvalidateResult {
   l1Removed: number
@@ -39,6 +46,10 @@ export interface StartOptions {
   l2?: L2Options
   /** `brust dev` only (L14): a request carrying this token (`x-brust-dev-token`) is traced; absent in production. */
   devToken?: string
+  /** F507: who may read `/_brust/cache/stats`; absent = `off` (404). Boot error `stats: …` for a mode and token that do not go together. */
+  stats?: 'off' | 'public' | 'token'
+  /** F507: the secret `stats: 'token'` compares `Authorization: Bearer` with, resolved from its env reference; never logged. */
+  statsToken?: string
 }
 /** napi `NapiL2Options`; defaults 50 ms, 1048576 bytes. */
 export interface L2Options {

package/src/routes.ts

@@ -166,6 +166,19 @@ export function checkCatchAlls(leaves: FlatRoute[]): void {
     throw new BrustRouteError(`more than one '*' route (${all.map((l) => l.id).join(', ')}): M2 allows one root catch-all`, 'duplicate-catch-all')
 }
 
+/** F495: with `[server] base_path` every route is a real URL path under it (`/portal`, `/portal/orders/{id}`): a pattern
+ * outside the base would never be reached, because the server answers 404 for any path outside it. The root `'*'` stays
+ * (it becomes "anything under the base no route matched"). Named error `route-outside-base-path`, listing the ids. */
+export function checkBasePath(leaves: FlatRoute[], basePath: string): void {
+  if (basePath === '') return
+  const outside = leaves.filter((l) => !l.catchAll && l.pattern !== basePath && !l.pattern.startsWith(`${basePath}/`))
+  if (outside.length > 0)
+    throw new BrustRouteError(
+      `routes outside server.base_path ${JSON.stringify(basePath)}: ${outside.map((l) => `${l.id} (${l.pattern})`).join(', ')}; write every route with the base (nest them under { path: ${JSON.stringify(basePath)}, children })`,
+      'route-outside-base-path',
+    )
+}
+
 /** Placeholder for the child route slot inside a layout. The compiler replaces `<Outlet/>`
  * imported from `@brust/core/routes`; rendered by React directly it is empty. */
 export function Outlet(): null {

package/src/run.ts

@@ -35,6 +35,10 @@ export interface RunManifest {
   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
+  /** F495: the `[server] base_path` the build baked in; absent = the app is at the root. */
+  base_path?: string
+  /** F506: the `[server] trailing_slash` the build baked in; absent = `strict`. */
+  trailing_slash?: string
   /** F165: `false` = no route can call a worker; absent (older manifests) = the pool is needed. */
   needs_workers?: boolean
 }
@@ -55,7 +59,9 @@ export function workerCount(cfg: BrustConfig, m: RunManifest): number {
 }
 
 /** Pure: the napi `StartOptions`. No actions/cors/cache → exactly the pre-actions keys. */
-export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string, devToken?: string): StartOptions {
+export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string, devToken?: string, env: Record<string, string | undefined> = process.env): StartOptions {
+  // F507: `/_brust/cache/stats` is off unless set; `brust dev` (its server carries a dev token) defaults to public.
+  const stats = cfg.stats ?? (devToken ? 'public' : 'off')
   return {
     host: cfg.host,
     port: cfg.port,
@@ -69,10 +75,19 @@ export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest,
     ...(actionsClient(cfg, m) ? { actionsClient: actionsClient(cfg, m) } : {}),
     ...(cfg.cors ? { cors: cfg.cors } : {}),
     ...(devToken ? { devToken } : {}),
+    ...(stats !== 'off' ? { stats, ...(stats === 'token' ? { statsToken: statsTokenOf(cfg.statsToken, env) } : {}) } : {}),
     ...(m.cache ? { l2: { adapter: m.cache.adapter, getTimeoutMs: m.cache.getTimeoutMs, maxBodyBytes: m.cache.maxBodyBytes, namespace: m.cache.namespace, buildId: m.cache.buildId } } : {}),
   }
 }
 
+/** F507: the bearer token `[server] stats_token = "env:NAME"` names; a boot error naming the variable (never a value) when it is unset or empty. */
+function statsTokenOf(ref: string | undefined, env: Record<string, string | undefined>): string {
+  const name = (ref ?? '').replace(/^env:/, '')
+  const v = name ? env[name] : undefined
+  if (!v) throw new Error(`stats: [server] stats_token is "env:${name}" but ${name} is not set (or empty)`)
+  return v
+}
+
 /** 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
@@ -81,6 +96,23 @@ function actionsClient(cfg: BrustConfig, m: RunManifest): NonNullable<StartOptio
   return { ...(prefix ? { prefix } : {}), ...(cfg.actionsBaseUrl !== undefined ? { baseUrl: cfg.actionsBaseUrl } : {}), ...(credentials ? { credentials } : {}) }
 }
 
+/** F495: the message when the config names a base path that is not the one the manifest was built for (`base-path-mismatch`), else
+ * null. A config that sets none is fine: the manifest's own is what the server answers under. */
+export function basePathMismatch(cfg: Pick<BrustConfig, 'basePath'>, m: Pick<RunManifest, 'base_path'>): string | null {
+  const built = m.base_path ?? ''
+  if (cfg.basePath === undefined || cfg.basePath === built) return null
+  const show = (p: string) => (p === '' ? 'the root' : JSON.stringify(p))
+  return `base-path-mismatch: server.base_path is ${show(cfg.basePath)} but this build is for ${show(built)}; the base path is baked in at build time, so rebuild (brust build)`
+}
+
+/** F506: the message when the config names a trailing-slash policy other than the one the manifest was built with
+ * (`trailing-slash-mismatch`), else null. A config that sets none serves the manifest's. */
+export function trailingSlashMismatch(cfg: Pick<BrustConfig, 'trailingSlash'>, m: Pick<RunManifest, 'trailing_slash'>): string | null {
+  const built = m.trailing_slash ?? 'strict'
+  if (cfg.trailingSlash === undefined || cfg.trailingSlash === built) return null
+  return `trailing-slash-mismatch: server.trailing_slash is ${JSON.stringify(cfg.trailingSlash)} but this build is for ${JSON.stringify(built)}; it is baked in at build time, so rebuild (brust build)`
+}
+
 /** Every worker's response buffer, kept reachable until the process exits (see run()). */
 const workerBuffers: SharedArrayBuffer[] = []
 
@@ -111,6 +143,10 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail((e as Error).message)
   }
 
+  const mismatch = basePathMismatch(cfg, m) ?? trailingSlashMismatch(cfg, m)
+  if (mismatch) fail(mismatch)
+  // `basePath` of `@brust/core` in the app's modules (the workers inherit the env).
+  process.env.BRUST_BASE_PATH = m.base_path ?? ''
   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
@@ -195,6 +231,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
   // F485 P12: on Windows Ctrl+C (SIGINT) drains; SIGTERM handlers rarely fire and a kill ends the process without a drain (POSIX-only).
   process.on('SIGINT', () => onSignal(130))
   process.on('SIGTERM', () => onSignal(143))
+  // F492: a console Ctrl+Break (and closing the console) reaches Bun as SIGBREAK on Windows: drain like Ctrl+C.
+  if (process.platform === 'win32') process.on('SIGBREAK', () => onSignal(149))
 
   // F488 (Windows only): a killed `bun run start` wrapper takes the shim (our parent) down but leaves this process running; drain when the
   // parent is gone (same path as Ctrl+C). Synchronous, nothing awaited. Not for a one-shot (`opts.onReady`: a static render that exits itself).