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

package/src/config.ts

@@ -89,6 +89,22 @@ export async function loadConfig(cwd: string = process.cwd(), cli: Partial<Brust
   }
 }
 
+/** `[cors]` of brust.toml and nothing else (no env, no cli): what the Cloudflare build ships in CONFIG.
+ * Throws `BrustConfigError` on a bad table, exactly like `loadConfig`. */
+export async function loadCors(cwd: string): Promise<CorsConfig | undefined> {
+  const tomlPath = join(cwd, 'brust.toml')
+  const file = Bun.file(tomlPath)
+  if (!(await file.exists())) return undefined
+  let parsed: unknown
+  try {
+    parsed = Bun.TOML.parse(await file.text())
+  } catch (e) {
+    throw new BrustConfigError(`failed to parse ${tomlPath}: ${(e as Error).message}`, tomlPath)
+  }
+  const root = (parsed ?? {}) as Record<string, unknown>
+  return 'cors' in root ? parseCors(root.cors, tomlPath) : undefined
+}
+
 /** CLI / programmatic overrides get the same bounds as env (a CLI `--port 0` = any free port). */
 function checkCli(cli: Partial<BrustConfig>): void {
   const check = (name: string, v: number | undefined, min: number, max: number) => {

package/src/dev.ts

@@ -0,0 +1,110 @@
+// `brust dev [entry] --target cloudflare [-- <wrangler args>]` (M4-CF R10): build, run `wrangler dev` on the
+// generated project, rebuild + restart wrangler on a source change. No HMR. Each build runs in a child
+// process: a failed build keeps the old wrangler, and module caches never leak between builds.
+import { type FSWatcher, watch } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { BuildError } from './build/errors'
+
+export interface DevOptions {
+  appRoot: string
+  entry: string
+  outDir: string
+  port?: number
+  wranglerArgs: string[]
+  fromSource: boolean
+  log: (s: string) => void
+}
+
+const IGNORED = new Set(['node_modules', '.wrangler', '.git'])
+const DEBOUNCE_MS = 300
+
+function wranglerBin(appRoot: string): string {
+  const fake = process.env.BRUST_WRANGLER
+  if (fake) return fake
+  const found = Bun.which('wrangler', { PATH: `${join(appRoot, 'node_modules', '.bin')}:${process.env.PATH ?? ''}` })
+  if (!found) throw new BuildError('cf-dev', 'wrangler not found (bun add -d wrangler)')
+  return found
+}
+
+/** Resolves with the exit code once the session ends (SIGINT/SIGTERM -> 0, or the child's own exit code). */
+export async function runDev(o: DevOptions): Promise<number> {
+  const appRoot = resolve(o.appRoot)
+  const dist = resolve(appRoot, o.outDir)
+  const bin = wranglerBin(appRoot)
+  const build = (): Promise<number> => {
+    const p = Bun.spawn([process.execPath, join(import.meta.dir, 'cli.ts'), 'build', o.entry, '--target', 'cloudflare', '--out-dir', o.outDir, ...(o.fromSource ? ['--wasm-from-source'] : [])], {
+      cwd: appRoot,
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    return p.exited
+  }
+  if ((await build()) !== 0) return 1
+
+  const args = ['dev', '-c', join(dist, 'cf', 'wrangler.jsonc'), '--persist-to', join(appRoot, '.wrangler', 'state'), ...(o.port !== undefined ? ['--port', String(o.port)] : []), ...o.wranglerArgs]
+  let child: ReturnType<typeof Bun.spawn> | null = null
+  let stopping = false
+  let restarting = false
+  let exitCode: (c: number) => void = () => {}
+  const done = new Promise<number>((r) => {
+    exitCode = r
+  })
+  const spawn = () => {
+    const c = Bun.spawn([bin, ...args], { cwd: appRoot, stdio: ['inherit', 'inherit', 'inherit'] })
+    child = c
+    c.exited.then((code) => {
+      if (child !== c || stopping || restarting) return
+      watcher?.close()
+      exitCode(code)
+    })
+  }
+  const stopChild = async () => {
+    const c = child
+    if (!c) return
+    c.kill('SIGTERM')
+    await c.exited
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let building = false
+  let again = false
+  const rebuild = async () => {
+    if (building) {
+      again = true
+      return
+    }
+    building = true
+    do {
+      again = false
+      o.log('[brust] change detected; rebuilding')
+      if ((await build()) === 0) {
+        restarting = true
+        await stopChild()
+        restarting = false
+        if (!stopping) spawn()
+      } else o.log('[brust] rebuild failed; keeping the running wrangler')
+    } while (again && !stopping)
+    building = false
+  }
+  const ignored = (rel: string) => {
+    const abs = resolve(appRoot, rel)
+    return rel.split(sep).some((s) => IGNORED.has(s)) || abs === dist || abs.startsWith(dist + sep) || abs.startsWith(`${dist}.`) || abs.startsWith(join(dirname(dist), `.${basename(dist)}.brust-`)) || relative(dist, abs) === ''
+  }
+  let watcher: FSWatcher | null = watch(appRoot, { recursive: true }, (_ev, name) => {
+    if (!name || ignored(String(name))) return
+    clearTimeout(timer)
+    timer = setTimeout(() => void rebuild(), DEBOUNCE_MS)
+  })
+
+  spawn()
+  const stop = () => {
+    if (stopping) return
+    stopping = true
+    clearTimeout(timer)
+    watcher?.close()
+    void stopChild().then(() => exitCode(0))
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+  return done
+}

package/src/handlers.ts

@@ -0,0 +1,243 @@
+// The host-agnostic half of the worker (M4-CF lane 4): wire shapes + `makeHandlers`. No Bun, no
+// napi, no `node:*` — the Cloudflare entry imports it through `@brust/core/server-handlers`.
+// `worker.ts` re-exports everything here, so existing importers are unchanged.
+import { installServerResolver, type StoreSnapshot } from './store/core-adapter'
+import { collectSnapshot, getServerInstance, runInStoreContext, touchStores } from './store/server-context'
+import { type FlatRoute, isHttpErrorTrigger, isVerdict, type LoaderReq, type Route, type Verdict } from './routes'
+
+installServerResolver(getServerInstance)
+
+
+// ---- wire shapes (protocol.rs, camelCase) ----
+
+export interface LoaderRequest {
+  routeId: string
+  params: Record<string, string>
+  path: string
+  req: LoaderReq
+  /** M3-P P6: the chain has jobs — plan them in this call (`planJobs`). Optional to honour. */
+  plan?: boolean
+}
+
+export type LoaderResponse =
+  | { ok: true; data: Record<string, unknown>; headers?: Record<string, string>; store?: StoreSnapshot | null }
+  | { verdict: 'notFound'; data: unknown; store?: StoreSnapshot | null }
+  | { verdict: 'redirect'; location: string; status: number }
+  | { verdict: 'httpError'; status: number; body: string }
+  | { error: string }
+
+export type JobKind = 'precompute' | 'ssr'
+
+export interface JobCall {
+  /** Opaque, echoed back: `<componentId>/<jobId>[/<row>]` for a chain job,
+   * `<parentId>/<childId>_<k>/<jobId>[/<row>]` for an inlined child instance (pipeline.rs `plan_one`). */
+  id: string
+  componentId: string
+  kind: JobKind
+  // biome-ignore lint/suspicious/noExplicitAny: job inputs are arbitrary JSON
+  inputs: any
+  /** ssr: the react component to render (D6). */
+  target?: string
+  row?: number
+}
+
+export interface JobsRequest {
+  jobs: JobCall[]
+}
+
+export type JobResult = { id: string; value: unknown } | { id: string; error: string }
+
+export interface JobsResponse {
+  results: JobResult[]
+}
+
+/** The default export of `<dist>/<manifest.jobs_module>` (built by Task 6): component id → job fns. */
+// biome-ignore lint/suspicious/noExplicitAny: props are whatever the component takes
+export type JobsModule = Record<string, { precompute?: (props: any) => unknown; ssr?: (props: any) => string | Promise<string> }>
+
+/** The slice of `manifest.json` the worker reads: ssr job `literals` (S6 amendment). */
+export interface ManifestLike {
+  routes?: { id: string; chain: string[] }[]
+  components: Record<
+    string,
+    {
+      jobs: { id: string; kind?: string; target?: string; literals?: Record<string, unknown> }[]
+      children?: { id: string }[]
+      stores?: string[]
+    }
+  >
+  jobs_module?: string
+  /** `brust build` (M3-F A3): the actions entry, relative to dist. Absent/null = no actions. */
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number } | null
+}
+
+export function toJson(out: unknown): string {
+  try {
+    return JSON.stringify(out)
+  } catch (e) {
+    return JSON.stringify({ error: `response not serialisable: ${String(e)}` })
+  }
+}
+
+// ---- literals (S6 amendment: the worker merges an ssr job's `literals` over `call.inputs`) ----
+
+/** `"<componentId>/<jobId>"` → that job record's `literals` (only records that carry some). */
+export function literalsIndex(manifest: ManifestLike | undefined): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>()
+  for (const [cid, c] of Object.entries(manifest?.components ?? {}))
+    for (const j of c.jobs ?? []) if (j.literals && Object.keys(j.literals).length > 0) out.set(`${cid}/${j.id}`, j.literals)
+  return out
+}
+
+/** The manifest job id of a call: the segment after `componentId` in a chain id
+ * (`<cid>/<jobId>[/<row>]`), else the third segment of a child-instance id
+ * (`<parentId>/<cid>_<k>/<jobId>[/<row>]`). */
+export function jobIdOf(call: Pick<JobCall, 'id' | 'componentId'>): string | undefined {
+  const parts = call.id.split('/')
+  return parts[0] === call.componentId ? parts[1] : parts[2]
+}
+
+// ---- touched stores (M3-F D4) ----
+
+/** route id -> sorted unique union of `stores` over the route's chain, walking each component's
+ * `children[].id` and `jobs[].target` transitively. Routes with an empty union are absent. */
+export function routeStoresIndex(manifest: ManifestLike | undefined): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const comps = manifest?.components ?? {}
+  for (const r of manifest?.routes ?? []) {
+    const acc = new Set<string>()
+    const seen = new Set<string>()
+    const walk = (id: string) => {
+      if (seen.has(id)) return
+      seen.add(id)
+      const c = comps[id]
+      if (!c) return
+      for (const p of c.stores ?? []) acc.add(p)
+      for (const k of c.children ?? []) walk(k.id)
+      for (const j of c.jobs ?? []) if (j.target) walk(j.target)
+    }
+    for (const id of r.chain ?? []) walk(id)
+    if (acc.size > 0) out.set(r.id, [...acc].sort())
+  }
+  return out
+}
+
+/** R1: `store` is assigned only when a store was touched; absent otherwise. */
+function withStore<T extends LoaderResponse>(r: T): T {
+  const s = collectSnapshot()
+  if (s) (r as { store?: StoreSnapshot | null }).store = s
+  return r
+}
+
+// ---- handlers ----
+
+/** `parent`: the data the chain merged before the verdict. A notFound renders the route's
+ * template (layouts included), so the layouts' data stays under the verdict's own keys. */
+function verdictJson(v: Verdict, parent: Record<string, unknown>): LoaderResponse {
+  if (v.status === 404) {
+    const own = v.data ?? {}
+    return { verdict: 'notFound', data: typeof own === 'object' && !Array.isArray(own) ? { ...parent, ...own } : own }
+  }
+  return { verdict: 'redirect', location: v.headers?.Location ?? '/', status: v.status }
+}
+
+export interface Handlers {
+  loader(req: LoaderRequest): Promise<LoaderResponse>
+  jobs(req: JobsRequest): Promise<JobsResponse>
+}
+
+/** `leaves` from `flattenRoutes` (ids must match the manifest's route ids); `jobs` the jobs
+ * module; `manifest` supplies ssr `literals` (omit → no merge). */
+export function makeHandlers(opts: {
+  leaves: FlatRoute[]
+  jobs: JobsModule
+  manifest?: ManifestLike
+  /** `jobs.js` `stores` table (R2): C3 path -> module namespace. */
+  stores?: Record<string, object>
+}): Handlers {
+  const byId = new Map(opts.leaves.map((l) => [l.id, l]))
+  const literals = literalsIndex(opts.manifest)
+  const jobs = opts.jobs
+  const storeIdx = routeStoresIndex(opts.manifest)
+  const storeTable = opts.stores ?? {}
+
+  async function runJob(call: JobCall): Promise<JobResult> {
+    const owner = call.kind === 'ssr' ? (call.target ?? call.componentId) : call.componentId // D6
+    const fn = jobs[owner]?.[call.kind]
+    if (typeof fn !== 'function') return { id: call.id, error: `no ${call.kind} job for component ${owner}` }
+    try {
+      let props = call.inputs
+      if (call.kind === 'ssr') {
+        const jid = jobIdOf(call)
+        const lit = jid === undefined ? undefined : literals.get(`${call.componentId}/${jid}`)
+        if (lit) props = { ...(props ?? {}), ...lit }
+        // Precompute runs outside any scope (D8); ssr runs in a scope seeded from `__store`, which props never see.
+        const seed = (props?.__store ?? null) as StoreSnapshot | null
+        if (props && '__store' in props) {
+          const { __store: _, ...rest } = props
+          props = rest
+        }
+        const p = props
+        return { id: call.id, value: await runInStoreContext(() => fn(p), seed) }
+      }
+      return { id: call.id, value: await fn(props) }
+    } catch (e) {
+      return { id: call.id, error: String(e) }
+    }
+  }
+
+  return {
+    // 0.1.x `runNativeChainLoaders`: root → leaf, flat merge (later keys win), first verdict stops
+    // (a notFound keeps what the chain merged so far: verdictJson).
+    async loader(req) {
+      const leaf = byId.get(req.routeId)
+      if (!leaf) return { error: `unknown routeId ${req.routeId}` }
+      // One object for the whole chain: each level's keys are assigned INTO it (later keys win,
+      // first-seen key order — what `{...merged, ...r}` produced) instead of re-spreading every
+      // key once per level (M3-P P1). `merged` is fresh per call; a loader's own object is never
+      // written to. Null prototype: with no `__proto__` setter to hit, an own "__proto__" key in a
+      // loader's data is assigned as data, as the spread copied it.
+      return runInStoreContext(async () => {
+        const merged: Record<string, unknown> = Object.create(null)
+        try {
+          const touch = storeIdx.get(req.routeId)
+          if (touch) touchStores(touch, storeTable)
+          for (const node of leaf.chain) {
+            if (!node.loader) continue
+            let r: unknown
+            try {
+              r = await node.loader({ params: req.params, path: req.path, req: req.req })
+            } catch (e) {
+              if (isHttpErrorTrigger(e)) return { verdict: 'httpError', status: e.status, body: e.body } as LoaderResponse
+              throw e
+            }
+            if (isVerdict(r)) {
+              const v = verdictJson(r, merged)
+              return 'verdict' in v && v.verdict === 'notFound' ? withStore(v) : v
+            }
+            if (r && typeof r === 'object') Object.assign(merged, r)
+          }
+          return withStore({ ok: true, data: merged } as LoaderResponse)
+        } catch (e) {
+          return { error: String(e) } as LoaderResponse
+        }
+      })
+    },
+    // One request carries every job of the page; a per-job failure keeps the other results.
+    async jobs(req) {
+      return { results: await Promise.all((req.jobs ?? []).map(runJob)) }
+    },
+  }
+}
+
+/** Wraps an async handler for a JSON-string boundary: parses, calls, serialises; NEVER rejects
+ * (a parse error or a throwing handler resolves `{"error":…}`, like `makeDispatch`). */
+export function jsonCall<Q, R>(fn: (q: Q) => Promise<R>): (json: string) => Promise<string> {
+  return async (json) => {
+    try {
+      return toJson(await fn(JSON.parse(json)))
+    } catch (e) {
+      return toJson({ error: String(e) })
+    }
+  }
+}

package/src/native.ts

@@ -31,6 +31,16 @@ export interface StartOptions {
   cors?: CorsOptions
   /** The actions subtree (M3-F A3); absent = no actions. Boot error `actions: …` when invalid. */
   actions?: ActionsOptions
+  /** The cache adapter (`manifest.cache`); absent = none (byte-identical server). */
+  l2?: L2Options
+}
+/** napi `NapiL2Options`; defaults 50 ms, 1048576 bytes. */
+export interface L2Options {
+  adapter: string
+  getTimeoutMs?: number
+  maxBodyBytes?: number
+  namespace: string
+  buildId: string
 }
 /** napi `NapiCorsOptions` (camelCase keys; snake_case keys are silently dropped). */
 export interface CorsOptions {
@@ -41,12 +51,16 @@ export interface CorsOptions {
   credentials?: boolean
   maxAgeSeconds?: number
 }
-/** napi `NapiActionsOptions`; defaults `/_brust/action`, 262144. */
+/** napi `NapiActionsOptions`; defaults `/_brust/action`, 1048576, 8388608. */
 export interface ActionsOptions {
   prefix?: string
   maxBodyBytes?: number
+  /** F82: response body cap (bytes). Default 8388608. */
+  maxResponseBytes?: number
+  /** F87: cross-site mutating requests. Default `reject`. */
+  crossSite?: 'reject' | 'allow'
 }
-export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch', requestJson: string, slot: number) => Promise<number>
+export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch' | 'cache', requestJson: string, slot: number) => Promise<number>
 export interface NativeBinding {
   startServer(opts: StartOptions): void
   registerWorker(buf: Uint8Array, slots: number, f: WorkerFn): number
@@ -57,6 +71,16 @@ export interface NativeBinding {
   localAddr(): string
   /** M3-P P6 — see crates/brust-napi/src/server.rs `plan_jobs`. Never throws. */
   planJobs(slot: number, len: number): string
+  /** F82 — the heap request body of the in-flight `fetch` call, once; null if none. Never throws. */
+  takeFetchBody(slot: number): Uint8Array | null
+  /** F82 — hand Rust a response body too large for the slot; false = declined. Never throws. */
+  putFetchReply(slot: number, body: Uint8Array): boolean
+  /** cache adapter R10 — a foreign broadcast event: tier 1 + the floor at `seq`; never re-published. */
+  cacheReplay(args: InvalidateArgs, seq: number | null): InvalidateResult
+  /** cache adapter R9 — bump `stats.l2[name]`; false = unknown name / no adapter / no server. Never throws. */
+  cacheL2Count(name: string): boolean
+  /** cache adapter R10 — drop both tier-1 caches (a broadcast gap); the L1 entries removed. */
+  cacheClear(): number
 }
 
 let binding: NativeBinding | null = null
@@ -83,3 +107,8 @@ export const cacheInvalidate = (args: InvalidateArgs): InvalidateResult => nativ
 export const cacheStats = (): string => native().cacheStats()
 export const localAddr = (): string => native().localAddr()
 export const planJobs = (slot: number, len: number): string => native().planJobs(slot, len)
+export const takeFetchBody = (slot: number): Uint8Array | null => native().takeFetchBody(slot)
+export const putFetchReply = (slot: number, body: Uint8Array): boolean => native().putFetchReply(slot, body)
+export const cacheReplay = (args: InvalidateArgs, seq: number | null): InvalidateResult => native().cacheReplay(args, seq)
+export const cacheL2Count = (name: string): boolean => native().cacheL2Count(name)
+export const cacheClear = (): number => native().cacheClear()

package/src/run.ts

@@ -22,10 +22,12 @@ export interface RunOptions {
 
 /** The manifest fields `run` needs (build/manifest.ts owns the full shape). */
 export interface RunManifest {
-  actions?: { entry: string; prefix: string; maxBodyBytes: number } | null
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | 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
 }
 
-/** Pure: the napi `StartOptions`. No actions/cors → exactly the pre-actions keys. */
+/** 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 {
   return {
     host: cfg.host,
@@ -35,8 +37,9 @@ export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest,
     callTimeoutMs: cfg.callTimeoutMs,
     workerThreads: cfg.ioThreads,
     generator: `brust/${version}`,
-    ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes } } : {}),
+    ...(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 } : {}) } } : {}),
     ...(cfg.cors ? { cors: cfg.cors } : {}),
+    ...(m.cache ? { l2: { adapter: m.cache.adapter, getTimeoutMs: m.cache.getTimeoutMs, maxBodyBytes: m.cache.maxBodyBytes, namespace: m.cache.namespace, buildId: m.cache.buildId } } : {}),
   }
 }
 
@@ -86,6 +89,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     BRUST_RENDER_SLOTS: String(cfg.renderSlots),
     BRUST_DIST_DIR: distDir,
     BRUST_APP_ENTRY: entry,
+    // One cache-adapter origin per process: its workers' published events are not replayed here.
+    BRUST_CACHE_ORIGIN: crypto.randomUUID(),
   }
 
   let ready = false

package/src/server-handlers.ts

@@ -0,0 +1,32 @@
+// What the generated Cloudflare entry (`brust-app.js`) imports: the host-agnostic handler code and the
+// store-scoped action fetch. No Bun / worker_threads here; `actions-bridge`'s napi import is stubbed by the
+// CF bundle (M4-CF R8).
+import { type CfCacheBridge, type CfInstallExt, installCache } from './cache-adapter/workers'
+import type { InvalidateArgs, InvalidateResult } from './native'
+
+export { fetchInScope, noActions } from './actions-bridge'
+export { jsonCall, makeHandlers } from './handlers'
+export { flattenRoutes } from './routes'
+
+/** What the wasm side hands over at start (`#[event(start]` -> `install({ invalidate, l2Count })`, ruling 19753649). */
+export interface CfRuntime {
+  invalidate(args: InvalidateArgs): InvalidateResult
+  /** Bumps a `stats.l2` counter (cache adapters R9). */
+  l2Count?(name: string): boolean
+}
+export type { CfCacheBridge, CfInstallExt }
+
+let rt: CfRuntime | null = null
+
+/** Called by the wasm glue once at Worker start; the CF bundle's napi stub forwards `cacheInvalidate` to it.
+ * With a cache adapter (`ext`, from the generated entry) it answers the adapter bridge (R11, R14). */
+export function install(runtime: CfRuntime, ext?: CfInstallExt): { cache: CfCacheBridge | null } {
+  rt = runtime
+  return { cache: ext ? installCache(runtime, ext) : null }
+}
+
+/** The installed runtime; throws before `install` (a request cannot arrive earlier). */
+export function installedRuntime(): CfRuntime {
+  if (!rt) throw new Error('brust: the Cloudflare runtime is not installed (install(rt) was not called at start)')
+  return rt
+}