@brust/core 0.0.0-stage → 2.0.0-alpha.10

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @brust/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rust serves the pages; N Bun workers answer only `loader` and `jobs` calls. One napi addon
+(`crates/brust-napi`, loader generated into `native/` by `napi build`) binds `brust-server` and
+`brust-compiler`. Workspace-private (0.0.0) until m2e publishes it; peers `react`/`react-dom` 19.
+
+## Routes (`routes.tsx`)
+
+```tsx
+import { defineRoutes, notFound } from '@brust/core/routes'
+export const routes = defineRoutes([
+  { Component: AppLayout, children: [                     // layout renders <Outlet />
+    { path: '/', Component: HomePage },                   // static: never calls Bun
+    { path: '/items/{id}', Component: ItemPage,
+      loader: async ({ params }) => (params.id === 'x' ? notFound({}) : { item: await load(params.id) }),
+      cache: { ttl_seconds: 60, tags: ['items'] } },      // a HIT never calls Bun
+  ] },
+])
+```
+
+Route fields are exactly `path`, `Component`, `loader`, `cache`, `ssg`, `children` (`ssg` only matters
+to `--target static`, see [docs/static.md](../../docs/static.md)); anything else fails the
+build with `<field> is not supported in M2 (M3)`. Loaders run root → leaf, results merge flat
+(later keys win); return `notFound(data)` / `redirect(location, status)` or throw
+`httpError(status, body)` for a verdict. `cache(Comp, opts)` and `cache.invalidate(…)` ship too.
+
+## `brust build [entry=routes.tsx] [--out-dir dist]`
+
+`--target static [--strict]` also renders every page to `dist/static/` for Cloudflare Pages or Workers
+Static Assets: see [docs/static.md](../../docs/static.md).
+
+Compiles every route component through lowering, then writes (always from scratch):
+
+```
+dist/manifest.json        the only build → server contract (spec S6)
+dist/jinja/<id>.jinja     templates          dist/jobs.js + jobs/*.server.ts   worker jobs
+dist/client/*-<hex>.js    runtime, native chunks, react-<id> island chunks (served immutable)
+dist/client/*-<hex>.css   one minified stylesheet per imported .css / .module.css (see docs/css.md)
+dist/public/              copied from ./public          dist/index.js   `bun dist/index.js` = start
+```
+
+Every route component's `children[]` also gets one static entry per native descendant (at any depth) that has a client chunk, so its `<script>` is linked once per page.
+
+A diagnostic (`nested-instance`, `outlet-in-react`, `outlet-outside-layout`, unsupported route
+field, unresolvable Component) prints `error <rule> <message>` and exits 1. The route tree is
+validated whether or not the entry used `defineRoutes` (`route-config`, `duplicate-route` for two
+patterns the router cannot hold together, e.g. `/a` and `/a/`).
+
+Server-only code never reaches a browser bundle (`error server-only-in-client <importer> imports
+<spec>`, at any import depth, react islands included): `node:*` / `bun:*` / bare Node builtins
+(unless an npm package of that name is installed), `@brust/core/server|native`, any
+`*.server.*` file, and the paths/prefixes listed in `brust.toml`:
+
+```toml
+[build]
+server_only = ["lib/server", "@acme/db"]   # import prefixes, or paths relative to the app root
+```
+
+The `server-only` marker package is honoured the same way: a browser build that reaches `import 'server-only'` (any depth, islands included) fails with `server-only-in-client` whether or not the package throws, and on the server side (route scan, jobs, actions, the Worker) it resolves to an empty module, so a loader may import a module guarded by it.
+
+Loaders and precompute jobs may use all of it (they run in Bun). In the browser `@brust/core`
+resolves to a side-effect-free entry (`cache`, route helpers, verdicts; `cache.invalidate` throws).
+
+The out dir is rebuilt in a sibling temp dir and swapped in only on success (a failed build leaves
+the previous one untouched); an out dir that is the filesystem root, the home dir, the app root or
+an ancestor of it, or that holds the entry / a route Component / `public/`, is refused
+(`out-dir-unsafe`). Relative imports of
+generated files resolve against the component's source dir, bare imports against the app root, so
+`--out-dir` may point anywhere; at run time `dist/` must still resolve `react` and `@brust/core`
+(keep it inside the app, or next to a `node_modules` that has them).
+
+## `brust dev [entry=routes.tsx] [--port N] [--workers N]`
+
+The Bun-target dev server. A long-lived parent owns your port and proxies to the newest build; every
+successful build is booted as a new child (`brust start` on a loopback port, `--workers 1` unless you pass
+`--workers`), the proxy switches over, browsers are told to `reload`, and the old child is stopped. A failed
+build **or a failed boot** keeps the old child serving and shows the error as an overlay above the stale page
+(a page opened while builds fail shows it too); the next good build clears it and reloads.
+
+- Source changes do a full reload (debounced ~150 ms; an edit made during a rebuild is not dropped).
+- A change to `public/*.css` skips the build: the file is copied into the running dist and the `<link>` is
+  swapped (`?v=`), the page keeps its state. Other `public/` files reload.
+- Every `text/html` response, including error pages, gets `/_brust/dev/client.js` (a WebSocket at
+  `/_brust/dev/ws`); responses are `cache-control: no-store`. `Host` and `Origin` reach the child unchanged,
+  so the actions cross-site guard behaves as in production.
+- Dev builds use React in development mode (`NODE_ENV=development`); `brust build` / `brust start` are unchanged.
+- The terminal shows request lines (`method path status ms cache`) and a status block of at most 6 lines at the
+  bottom (state, URL, generation, build time, last request, warnings, hotkeys `r` reload, `o` open, `w` warnings,
+  `c` clear, `q` quit). It never uses the alternate screen. Not a TTY, `CI` or `NO_COLOR`: plain lines only.
+- **Trace for dev tools (L14).** The dev proxy generates a token per session and gives it to each child (`BRUST_DEV_TOKEN`,
+  napi `devToken`) and to every upstream request (`x-brust-dev-token`). Only then the core answers `x-brust-dev: base64(json)`
+  (route, pattern, chain, params, cache outcome, loader and render ms, jobs with kind/key/tags/hit, bun calls, the components the
+  page is made of). It is added after the L1 store, so it is never cached; a core without a token (production) never makes it.
+  The proxy strips the header, puts the trace in the page as `<script type=application/json id=__brust_trace>` and keeps the
+  last 50 (actions included) at `/_brust/dev/traces`. `brust build --dev` (used by `brust dev`) also writes `dev.json`
+  (component id → source file, tier, the react reason, diagnostics with rule/line/col/remediation; served at `/_brust/dev/meta`);
+  a production build writes none. In dev only, every chain level is wrapped in `<!--brust:<id>-->…<!--/brust-->` (never inside a
+  `<brust-island>`), and the runtime exposes its live instances on `globalThis.__brustDev.instances` (`__BRUST_DEV__` is a
+  build define that is `false`, and removed by the minifier, in every other build).
+- **`<brust-devtools>` (L15).** The dev proxy serves `/_brust/dev/devtools.js` (bundled from `src/dev/devtools.ts` on first request) and
+  injects it into every HTML response, so `brust start` and production builds contain none of it. A corner indicator shows the build state
+  and the page's tier counts (`ready · 2s 1n 1r`); `Alt+Shift+B` toggles the panel (real buttons and tabs, arrow keys, `Esc` closes and
+  restores focus, contrast ≥ 4.5:1 in light and dark). Panels, each from the trace, `dev.json`, the DOM or `__brustDev` only: **Page**
+  (route, params, cache, timings), **Components** (tree with tier badges; a react component shows its reason and diagnostic location;
+  hover highlights it), **Jobs**, **Store** (seed from `data-brust-store`, live values of mounted native stores), **Islands**
+  (hydrated or not), **Build** (diagnostics with `file:line:col`, the current build error), **Requests** (the last 50). The terminal
+  status block shows the same tier counts for the last page.
+- Not hot module replacement: component state does not survive an edit. `brust dev --target cloudflare` keeps
+  its wrangler loop (now on the same watch loop).
+
+## `brust start [--port N] [--workers N] [--dist-dir dist] [--entry routes.tsx]`
+
+Prints `[brust] listening on <addr>` then `[brust] ready (N workers)`. `--port 0` picks a free port.
+SIGINT/SIGTERM drains gracefully (`BRUST_DRAIN_TIMEOUT_MS`); a second signal exits at once.
+Config precedence: env (`BRUST_ADDR`, `BRUST_PORT`, `BRUST_WORKERS`, `BRUST_RENDER_SLOTS`,
+`BRUST_DRAIN_TIMEOUT_MS`, `BRUST_BOOT_TIMEOUT_MS`, `BRUST_CALL_TIMEOUT_MS`, `BRUST_SLOT_BYTES`,
+`BRUST_MAX_LOADER_RESPONSE_BYTES`, `BRUST_DIST_DIR`, `BRUST_APP_ENTRY`) > flags
+(`--port`, `--workers`, `--dist-dir`, `--entry`) and `run({ config })` > `brust.toml` (`[server] address/port/max_loader_response_bytes`,
+`[workers] count/slot_bytes`, `[cors]`) > defaults (`localhost:1337`, one worker per CPU, `min(cores, 16)` slots per worker (each slot is a `slotBytes` shared response buffer, 256 KiB by default, so 10 slots = 2.5 MiB per worker), 10 s drain, 30 s
+worker boot timeout, 30 s call timeout, 8 MiB loader response limit).
+`slotBytes` (`[workers] slot_bytes`, env `BRUST_SLOT_BYTES`, `run({ config: { slotBytes } })`) is 64 KiB..16 MiB.
+A loader, jobs or planned reply that does not fit its slot is not an error: the worker hands it to the server
+over the heap, up to `maxLoaderResponseBytes` (`[server] max_loader_response_bytes`, env
+`BRUST_MAX_LOADER_RESPONSE_BYTES`, `run({ config: { maxLoaderResponseBytes } })`; 256 KiB..64 MiB, default 8 MiB).
+A bigger reply answers `{"error":"response too large: <n> > <limit> (maxLoaderResponseBytes)"}` (a 500). This
+limit applies to loader and jobs replies; `[actions]` has its own `max_response_bytes`.
+`[cors]` can also be given as `run({ config: { cors: { origins, methods, headers, exposeHeaders, credentials,
+maxAgeSeconds } } })` (camelCase, an unknown key is rejected). It replaces a `brust.toml` `[cors]` as a whole,
+never merging with it; `cors: null` turns the toml table off.
+A loader or job call that has not settled within `BRUST_CALL_TIMEOUT_MS` answers **504**; its worker
+slot stays claimed until the call settles (the late result is discarded), so a stuck call costs one
+slot, never a frozen worker. Waiting for a free slot is the separate 503 "all workers busy".
+`GET /_brust/cache/stats` reports L1/job cache counters plus `loader_calls` / `job_calls` /
+`timed_out_calls`.
+
+## Worker wire (contract 7, `crates/brust-server/src/protocol.rs`)
+
+Requests arrive as inline JSON; responses go into the worker's SharedArrayBuffer slot (never
+past `floor(len / slots)` bytes). A `loader`/`jobs` reply that does not fit crosses by heap: the worker
+puts the bytes with `putFetchReply` and writes the 5-byte marker `[0x00][u32 LE n]` into the slot (JSON
+never starts with 0x00); the server reads the `n` bytes it was handed. A loader context too large for the
+slot is planned from the bytes (`planJobsBuf`). Over `maxLoaderResponseBytes` the reply becomes
+`{"error":…}`. A handler never rejects.
+
+`loader` `{routeId, params, path, req}` → `{ok:true, data}` | `{verdict, …}` | `{error}`;
+`jobs` `{jobs:[{id, componentId, kind, inputs, target?, row?}]}` → `{results:[{id, value}|{id, error}]}`
+(an `ssr` job renders `jobs[target]` with the manifest job's `literals` merged over `inputs`).
+
+**M2 limits:** the route fields above only; per-row child instances one level deep (a nested
+instance is a build error); a react child's props must be props paths or literals; no worker respawn.
+**Gates:** `bun run build:debug && bun run typecheck && bun test` (CI runs each server-starting
+file alone; e2e: `bun test --timeout 120000 test/e2e.test.ts`).

package/bin/brust

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from '../src/cli.ts'
+
+await main(process.argv.slice(2))

package/native/index.d.ts

@@ -0,0 +1,226 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+/**
+ * Graceful drain of the current server: stop accepting, wait for in-flight
+ * connections up to `timeout_ms`.
+ */
+export declare function beginDrain(timeoutMs: number): Promise<void>
+
+/** Drop both tier-1 caches (a broadcast gap, R10); `stats.l2.resets`++. The L1 entries removed. */
+export declare function cacheClear(): number
+
+/**
+ * Static output (gaps round R9.4): the request reads of one `cache.prefix` / `cache.bypass`
+ * expression (`header(x)`, `cookie(x)`, `query(x)`, `request(host)`), parsed by the server's own
+ * grammar. Errors when the expression does not parse. Needs no running server.
+ */
+export declare function cacheExprReads(src: string): Array<string>
+
+/** `cache.invalidate({ key?, tags?, path?, method? })` (spec §5). */
+export declare function cacheInvalidate(args: NapiInvalidateArgs): NapiInvalidateResult
+
+/**
+ * Bump the `stats.l2` counter `name` (the JS side's counts, R9). `false` = unknown name, no
+ * adapter, or no server. Never throws.
+ */
+export declare function cacheL2Count(name: string): boolean
+
+/**
+ * A broadcast invalidation another process published (worker 0's subscriber, cache-adapter R10):
+ * tier 1 + the floor at `seq`. Never re-published (L3). Same args/result as `cache_invalidate`.
+ */
+export declare function cacheReplay(args: NapiInvalidateArgs, seq?: number | undefined | null): NapiInvalidateResult
+
+/** `/_brust/cache/stats` JSON (snake_case keys, as the server serialises it). */
+export declare function cacheStats(): string
+
+export interface CompiledComponent {
+  id: string
+  source: string
+  /** `ComponentIR` as JSON (snake_case keys, as the compiler serialises it). */
+  ir: string
+  jinja: string
+  serverTs?: string
+  /** Build-time evaluation module (L2): one thunk per `ir.build_eval` slot. */
+  evalTs?: string
+  clientJs?: string
+  diagnostics: Array<NapiDiagnostic>
+}
+
+export interface CompiledTree {
+  components: Array<CompiledComponent>
+  error?: NapiDiagnostic
+}
+
+/**
+ * Compiles `path` (relative to `root`) and every child it reaches through lowering. `css_modules` (L20): the class
+ * map of each `*.module.css`, keyed by its path relative to `root`; `styles.x` folds to the literal class.
+ * `packages` (F153c): the JSON resolution map of the package sources the build wrote (`pkg-src.ts`).
+ */
+export declare function compileTree(path: string, root: string, runtimeImport: string, serverOnly: Array<string>, slotValues?: string | undefined | null, cssModules?: Record<string, Record<string, string>> | undefined | null, iconSvgs?: string | undefined | null, routeRoots?: Array<string> | undefined | null, pathAliases?: string | undefined | null, packages?: string | undefined | null): CompiledTree
+
+/** The bound address as `host:port` (port 0 resolves here). */
+export declare function localAddr(): string
+
+/** L16: what the page tells the browser client. `credentials`: `"same-origin"` (default), `"include"` or `"omit"`. */
+export interface NapiActionsClient {
+  prefix?: string
+  baseUrl?: string
+  credentials?: string
+}
+
+/** M3-F A3 consumer `{ prefix?, maxBodyBytes?, maxResponseBytes? }` (defaults `/_brust/action`, 1 MiB, 8 MiB). Present = actions on. */
+export interface NapiActionsOptions {
+  prefix?: string
+  maxBodyBytes?: number
+  /** F82: cap on an action response body (default 8388608). */
+  maxResponseBytes?: number
+  /** `"reject"` (default) or `"allow"` (F87): cross-site mutating action requests. */
+  crossSite?: string
+}
+
+/**
+ * Global CORS (0.1.x `NapiCorsOptions`, brust/src/lib.rs:79-98); napi camelCases the keys:
+ * `origins, methods, headers, exposeHeaders, credentials, maxAgeSeconds`. Validated by `start` (`cors: …`).
+ */
+export interface NapiCorsOptions {
+  origins: Array<string>
+  methods?: Array<string>
+  headers?: Array<string>
+  exposeHeaders?: Array<string>
+  credentials?: boolean
+  maxAgeSeconds?: number
+}
+
+export interface NapiDiagnostic {
+  class: string
+  rule: string
+  message: string
+  line: number
+  col: number
+  remediation: string
+}
+
+export interface NapiInvalidateArgs {
+  key?: string
+  tags?: Array<string>
+  path?: string
+  method?: string
+}
+
+export interface NapiInvalidateResult {
+  l1Removed: number
+  jobRemoved: number
+}
+
+/** The cache adapter (`[cache]`, cache-adapter lane A); built by `brust start` from `manifest.cache`. */
+export interface NapiL2Options {
+  adapter: string
+  /** The `store.get` budget; absent = 50. */
+  getTimeoutMs?: number
+  /** A bigger rendered body is not written; absent = 1 048 576. */
+  maxBodyBytes?: number
+  namespace: string
+  buildId: string
+}
+
+/**
+ * M3-P P6: plan the calling worker's in-flight loader call for `slot` from the `len` bytes it
+ * just wrote there. Returns the misses' `JobsRequest` JSON, `""` when every job hit, or `"!"`
+ * (declined: answer with the loader response already in the slot). Sync, on the worker's JS
+ * thread; never throws (a napi Error return is unreliable under Bun).
+ */
+export declare function planJobs(slot: number, len: number): string
+
+/**
+ * L10: [`plan_jobs`] for a loader response too large for the slot: the worker hands the bytes
+ * over in `buf` instead of writing them to the slot. Same answers (`""`, the misses' JSON, or
+ * `"!"`); a declined plan leaves the response for the worker to hand over with `putFetchReply`.
+ */
+export declare function planJobsBuf(slot: number, buf: Uint8Array): string
+
+/**
+ * F82: hand Rust the response body of the calling worker's in-flight `fetch` call for `slot`
+ * (too large for the SAB slot). `false` = declined (over `max_response_bytes`, not in a `fetch`
+ * call, already put, nothing bound). Sync, on the worker's JS thread; never throws.
+ */
+export declare function putFetchReply(slot: number, body: Uint8Array): boolean
+
+/**
+ * Register the calling worker with the current server. `buf` is a view of
+ * the worker's SharedArrayBuffer, which must outlive the process's use of
+ * this worker (`brust start` allocates it on the main thread and keeps it for
+ * the process lifetime: `dispatch.rs` BufPtr); it is split into
+ * `slots` disjoint sub-regions of `floor(buf.byteLength / slots)` bytes.
+ * `f(kind, requestJson, slot)` writes the response JSON at offset
+ * `slot * sub` and resolves with its byte length (> 0, ≤ sub). Returns the
+ * worker id.
+ */
+export declare function registerWorker(buf: Uint8Array, slots: number, f: (arg0: string, arg1: string, arg2: number) => Promise<number>): number
+
+export interface StartOptions {
+  host: string
+  port: number
+  distDir: string
+  /** Workers to wait for before accepting; `0` = serve at once. */
+  workers: number
+  claimTimeoutMs?: number
+  /**
+   * A claimed worker call that has not settled after this long answers
+   * 504 (the slot stays claimed until JS settles). Absent = 30 000.
+   */
+  callTimeoutMs?: number
+  /**
+   * L10: the biggest loader/jobs reply that may cross the heap when it does not fit the slot
+   * (256 KiB..=64 MiB; boot error otherwise). Absent = 8 MiB.
+   */
+  maxLoaderResponseBytes?: number
+  /**
+   * tokio threads of the HTTP runtime (every page renders there); absent =
+   * one per core (`Tuning::default`).
+   */
+  workerThreads?: number
+  l1Capacity?: number
+  jobCacheCapacity?: number
+  /** `X-Powered-By` value; absent = header not stamped. */
+  generator?: string
+  /** Global CORS policy; absent = CORS off. */
+  cors?: NapiCorsOptions
+  /** The actions subtree (M3-F); absent = no actions (byte-identical server). */
+  actions?: NapiActionsOptions
+  /** L16: base URL / credentials / prefix injected for the browser `client()`; absent = from `actions` alone. */
+  actionsClient?: NapiActionsClient
+  /** The cache adapter; absent = none (byte-identical server). */
+  l2?: NapiL2Options
+  /** `brust dev` only (L14): a request carrying this token in `x-brust-dev-token` is traced. Absent in production. */
+  devToken?: string
+}
+
+/**
+ * Boot the server (manifest, routes, templates, bind). Throws on any boot
+ * error (`manifest: …`, `routes: …`, `render: …`, `cors: …`, `actions: …`,
+ * `bind failed on …`).
+ */
+export declare function startServer(opts: StartOptions): void
+
+/**
+ * F82: the heap request body of the calling worker's in-flight `fetch` call for `slot`, once.
+ * `None` when there is none, nothing is bound, or the binding is ambiguous. Sync, on the
+ * worker's JS thread; never throws.
+ */
+export declare function takeFetchBody(slot: number): Uint8Array | null
+
+/**
+ * Resolves once `workers` workers registered with the current server and the server has printed its
+ * `[brust] listening on` line (so a caller's `ready` always follows it, F128); rejects after `timeout_ms` (the caller decides the exit policy).
+ */
+export declare function untilReady(timeoutMs: number): Promise<void>