@weft-js/start 0.1.0 → 0.1.2

package/src/rust.ts

@@ -13,13 +13,28 @@
 // `WEFT_RUST_SECRET` for the sidecars they supervise, and a sidecar deployed on its own needs both set by hand.
 // Nothing here imports a Node module, so none of it reaches a bundle that doesn't call it.
 
-import { raise, StartError, type Context, type Fn } from './data'
+import { StartError, type Context, type Fn } from './data'
+import {
+  DEFAULT_TIMEOUT,
+  callContext,
+  defaultClaims,
+  encoder,
+  env,
+  settled,
+  wire,
+} from './rust/common'
+import { createNative } from './rust/native'
 
 /** Whoever `ctx.user` is in this app, once it declares `Context`. */
 type User = Context extends { user: infer U } ? U | null : unknown
 
 /** What a sidecar may know of the user. Sent signed; a sidecar never sees a cookie or a session token. */
-export interface Claims { id: string; roles?: string[]; tenant?: string | null; [key: string]: unknown }
+export interface Claims {
+  id: string
+  roles?: string[]
+  tenant?: string | null
+  [key: string]: unknown
+}
 
 /** `remote()`: the address, the deadline, and how a user becomes claims. */
 export interface RemoteOptions {
@@ -34,9 +49,18 @@ export interface RemoteOptions {
 }
 
 /** One function call on its way to a sidecar. */
-export interface RemoteCall { fn: Fn; input: unknown; ctx: Context; request: Request }
+export interface RemoteCall {
+  fn: Fn
+  input: unknown
+  ctx: Context
+  request: Request
+}
 /** What a sidecar answered: the value, and the tags it says to refresh. */
-export interface RemoteResult { value: unknown; tags: string[]; touched: string[] }
+export interface RemoteResult {
+  value: unknown
+  tags: string[]
+  touched: string[]
+}
 
 /** What `remote()` returns: pass it as a function's `impl`. */
 export interface Remote {
@@ -67,88 +91,43 @@ export interface Native {
 }
 
 const TARGET = /^rust:\/\/([a-z][a-z0-9_-]*)$/
-const NAME = /^[a-z][a-z0-9_-]*$/
-const DEFAULT_TIMEOUT = 10_000
-const encoder = new TextEncoder()
-
-// An app's tsc may have no Node types, so what's read of `process` is named here.
-const nodeHost = globalThis as unknown as { process?: { env: Record<string, string | undefined>; platform: string; arch: string; getBuiltinModule?(name: string): unknown; dlopen(mod: object, file: string): void } }
-const env = (name: string): string | undefined => nodeHost.process?.env?.[name] || undefined
 /** `search-index` → `WEFT_RUST_SEARCH_INDEX_URL`. */
-export const urlVariable = (service: string) => `WEFT_RUST_${service.toUpperCase().replaceAll('-', '_')}_URL`
-
-const hex = (b: ArrayBuffer) => Array.from(new Uint8Array(b), x => x.toString(16).padStart(2, '0')).join('')
-const base64url = (s: string) => btoa(String.fromCharCode(...encoder.encode(s))).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
-const randomHex = (bytes: number) => Array.from(crypto.getRandomValues(new Uint8Array(bytes)), x => x.toString(16).padStart(2, '0')).join('')
-
+export const urlVariable = (service: string) =>
+  `WEFT_RUST_${service.toUpperCase().replaceAll('-', '_')}_URL`
+
+const hex = (b: ArrayBuffer) =>
+  Array.from(new Uint8Array(b), (x) => x.toString(16).padStart(2, '0')).join('')
+const base64url = (s: string) =>
+  btoa(String.fromCharCode(...encoder.encode(s)))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '')
 const keys = new Map<string, Promise<CryptoKey>>()
 const keyOf = (secret: string) => {
   let k = keys.get(secret)
-  if (!k) keys.set(secret, (k = crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])))
+  if (!k)
+    keys.set(
+      secret,
+      (k = crypto.subtle.importKey(
+        'raw',
+        encoder.encode(secret),
+        { name: 'HMAC', hash: 'SHA-256' },
+        false,
+        ['sign'],
+      )),
+    )
   return k
 }
 
 /** `weft-sig`: the crate's `verify` checks the same bytes. It covers the function and the body, not just the claims. */
 export const sign = async (secret: string, id: string, ctx: string, body: string) =>
-  hex(await crypto.subtle.sign('HMAC', await keyOf(secret), encoder.encode(`weft1\n${id}\n${ctx}\n${body}`)))
-
-const defaultClaims = (user: User): Claims | null => {
-  const u = user as { id: unknown; roles?: string[]; role?: string; tenant?: string | null } | null
-  return u && { id: String(u.id), roles: u.roles ?? (u.role ? [u.role] : []), ...(u.tenant != null && { tenant: u.tenant }) }
-}
-
-const TRACEPARENT = /^00-(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}-[0-9a-f]{2}$/
-
-/** The caller's trace with a new span, or a new trace. */
-function traceparent(request: Request): string {
-  const inbound = request.headers.get('traceparent')
-  const trace = inbound && TRACEPARENT.test(inbound) ? inbound.split('-')[1] : randomHex(16)
-  return `00-${trace}-${randomHex(8)}-01`
-}
-
-/** The value as a sidecar reads it: what the schema parsed, encoded back to the wire shape (codecs, defaults filled). */
-function wire(fn: Fn, input: unknown): unknown {
-  const schema = fn.def.input as { encodeAsync?: (value: unknown) => Promise<unknown> } | undefined
-  if (typeof schema?.encodeAsync === 'function') return schema.encodeAsync(input)
-  return input
-}
-
-async function checkedOutput(fn: Fn, value: unknown, validate: boolean): Promise<unknown> {
-  const schema = fn.def.output
-  if (!schema || !validate) return value
-  const r = await schema['~standard'].validate(value)
-  if (!r.issues) return r.value
-  const issues = r.issues.map(i => `${i.path?.map(p => (typeof p === 'object' ? p.key : p)).join('.') ?? ''}: ${i.message}`).join('; ')
-  throw new StartError('R103', `\`${fn.$id}\`'s sidecar returned a value its \`output\` schema rejects: ${issues}`, 'the sidecar was built from another contract, or sets a field the schema refuses: rebuild it, or fix the schema', { status: 502 })
-}
-
-/** A declared error: its data checked like any output, with the status a client can act on. */
-async function declared(fn: Fn, error: { code: string; data?: unknown }): Promise<never> {
-  const schema = fn.def.errors?.[error.code]
-  if (!schema) throw new StartError('R103', `\`${fn.$id}\`'s sidecar answered with the undeclared error \`${error.code}\``, 'declare it in `errors`, or rebuild the sidecar from the current contract', { status: 502 })
-  const r = await schema['~standard'].validate(error.data ?? null)
-  if (r.issues) throw new StartError('R103', `\`${fn.$id}\`'s sidecar sent \`${error.code}\` with data its schema rejects`, 'rebuild the sidecar from the current contract', { status: 502 })
-  raise(error.code, r.value)
-}
-
-/** A shared value goes by no one's claims: the crate's `SharedCtx` has no user to read, and neither has the wire. */
-function callContext(fn: Fn, ctx: Context, request: Request, timeout: number, claims: (user: User) => Claims | null) {
-  const shared = fn.def.cache && fn.def.cache.scope !== 'user'
-  return { user: shared ? null : claims((ctx as { user?: User }).user ?? null) ?? null, requestId: randomHex(8), deadlineMs: timeout, traceparent: traceparent(request) }
-}
-
-/** What a reply comes to: the same for a sidecar's body and an addon's string. */
-async function settled(fn: Fn, reply: Reply | undefined, target: string, timeout: number, validate: boolean): Promise<RemoteResult> {
-  if (reply?.ok === true) return { value: await checkedOutput(fn, reply.value, validate), tags: reply.tags ?? [], touched: reply.touched ?? [] }
-  const error = reply?.error
-  if (error?.code === 'Refused') throw new StartError('R106', `\`${target}\` refused \`${fn.$id}\`'s signature`, '`WEFT_RUST_SECRET` must be the same on both sides, and the clocks within a minute', { status: 503 })
-  if (error?.code === 'Deadline') throw new StartError('R107', `\`${fn.$id}\` ran past its ${timeout} ms`, 'raise `timeout`, or make the Rust answer sooner', { status: 504 })
-  if (error?.code === 'Drift') throw new StartError('R103', `\`${fn.$id}\` doesn't match \`${target}\`: ${error.message}`, 'rebuild it from the current contract', { status: 502 })
-  if (error?.code && error.code !== 'Internal') await declared(fn, { code: error.code, data: error.data })
-  // The detail stays in a log, under this id: a sidecar's own, or this server's for what ran in this process.
-  if (error?.detail) console.error(`[weft] \`${fn.$id}\` failed (request ${error.requestId}): ${error.detail}`)
-  throw new StartError('R108', `\`${fn.$id}\` failed in \`${target}\` (request ${error?.requestId ?? 'unknown'})`, 'find the request id in the server\'s or the sidecar\'s log', { status: 500 })
-}
+  hex(
+    await crypto.subtle.sign(
+      'HMAC',
+      await keyOf(secret),
+      encoder.encode(`weft1\n${id}\n${ctx}\n${body}`),
+    ),
+  )
 
 /**
  * A Rust sidecar implementing the functions that point at it, as `impl: search`. `run` and `impl` are one or the other:
@@ -156,178 +135,73 @@ async function settled(fn: Fn, reply: Reply | undefined, target: string, timeout
  */
 export function remote(target: string, options: RemoteOptions = {}): Remote {
   const service = TARGET.exec(target)?.[1]
-  if (!service) throw new StartError('R106', `\`remote('${target}')\` isn't a sidecar target`, "`remote('rust://search')`, with the address in `WEFT_RUST_SEARCH_URL` or the `url` option")
+  if (!service)
+    throw new StartError(
+      'R106',
+      `\`remote('${target}')\` isn't a sidecar target`,
+      "`remote('rust://search')`, with the address in `WEFT_RUST_SEARCH_URL` or the `url` option",
+    )
   const { timeout = DEFAULT_TIMEOUT, claims = defaultClaims, validate = true } = options
   return {
-    kind: 'remote', target, service,
+    kind: 'remote',
+    target,
+    service,
     async call({ fn, input, ctx, request }) {
       const url = options.url ?? env(urlVariable(service))
-      if (!url) throw new StartError('R106', `\`${fn.$id}\` is implemented by \`${target}\`, and this server has no address for it`, `set \`${urlVariable(service)}\` (\`weft dev\` and \`weft start\` do it for a sidecar they supervise), or pass \`url\` to \`remote()\``, { status: 503 })
+      if (!url)
+        throw new StartError(
+          'R106',
+          `\`${fn.$id}\` is implemented by \`${target}\`, and this server has no address for it`,
+          `set \`${urlVariable(service)}\` (\`weft dev\` and \`weft start\` do it for a sidecar they supervise), or pass \`url\` to \`remote()\``,
+          { status: 503 },
+        )
       const secret = env('WEFT_RUST_SECRET')
-      if (!secret) throw new StartError('R106', `\`${fn.$id}\` can't sign its call: \`WEFT_RUST_SECRET\` isn't set`, 'set the same value on the server and the sidecar', { status: 503 })
-
-      const envelope = base64url(JSON.stringify({ ...callContext(fn, ctx, request, timeout, claims), iat: Date.now() }))
+      if (!secret)
+        throw new StartError(
+          'R106',
+          `\`${fn.$id}\` can't sign its call: \`WEFT_RUST_SECRET\` isn't set`,
+          'set the same value on the server and the sidecar',
+          { status: 503 },
+        )
+
+      const envelope = base64url(
+        JSON.stringify({ ...callContext(fn, ctx, request, timeout, claims), iat: Date.now() }),
+      )
       const body = JSON.stringify({ input: (await wire(fn, input)) ?? null })
 
       let res: Response
       try {
         res = await fetch(`${url.replace(/\/$/, '')}/_weft/fn/${encodeURIComponent(fn.$id)}`, {
           method: 'POST',
-          headers: { 'content-type': 'application/json', 'weft-ctx': envelope, 'weft-sig': await sign(secret, fn.$id, envelope, body) },
+          headers: {
+            'content-type': 'application/json',
+            'weft-ctx': envelope,
+            'weft-sig': await sign(secret, fn.$id, envelope, body),
+          },
           body,
           signal: AbortSignal.any([AbortSignal.timeout(timeout), request.signal]),
         })
       } catch (e) {
-        if ((e as Error | undefined)?.name === 'TimeoutError') throw new StartError('R107', `\`${fn.$id}\` took longer than its ${timeout} ms`, 'raise `timeout` on `remote()`, or make the sidecar answer sooner', { status: 504 })
-        throw new StartError('R107', `\`${fn.$id}\`: \`${target}\` didn't answer`, 'check that the sidecar is running. Nothing else on this server is affected', { status: 503 })
+        if ((e as Error | undefined)?.name === 'TimeoutError')
+          throw new StartError(
+            'R107',
+            `\`${fn.$id}\` took longer than its ${timeout} ms`,
+            'raise `timeout` on `remote()`, or make the sidecar answer sooner',
+            { status: 504 },
+          )
+        throw new StartError(
+          'R107',
+          `\`${fn.$id}\`: \`${target}\` didn't answer`,
+          'check that the sidecar is running. Nothing else on this server is affected',
+          { status: 503 },
+        )
       }
       return settled(fn, await res.json().catch(() => undefined), target, timeout, validate)
     },
   }
 }
 
-// ---- native ---------------------------------------------------------------------------------------------------------
-
-/** The exports a `.wasm` built by the crate has. */
-interface Wasm { memory: WebAssembly.Memory; weft_init: () => void; weft_free: (ptr: number, len: number) => void; weft_alloc: (len: number) => number; weft_contract: () => bigint; weft_call: (i: number, il: number, c: number, cl: number, b: number, bl: number) => bigint }
-interface Reply { ok?: boolean; value?: unknown; tags?: string[]; touched?: string[]; error?: { code?: string; message?: string; detail?: string; requestId?: string; data?: unknown } }
-interface Engine { kind: 'addon' | 'wasm'; call(id: string, ctx: string, body: string): Promise<string> | string }
-interface Entry { kind?: string; hash: string; addon?: string; wasm?: string; failure?: string }
-
-interface ReadFile { (file: string, encoding: 'utf8'): string; (file: string): Uint8Array<ArrayBuffer> }
-interface Builtins { 'node:fs': { existsSync(file: string): boolean; readFileSync: ReadFile }; 'node:path': { dirname(path: string): string; join(...parts: string[]): string }; 'node:url': { fileURLToPath(url: string): string } }
-const builtin = <K extends keyof Builtins>(name: K) => nodeHost.process?.getBuiltinModule?.(name) as Builtins[K] | undefined
-const platform = () => { const p = nodeHost.process; return `${p?.platform}-${p?.arch}` }
-
-/** `.output/server/rust/` from wherever the bundle put this code. `WEFT_NATIVE_DIR` is `weft dev`'s, and `weft build`'s. */
-function nativeDir(): string | undefined {
-  const fs = builtin('node:fs'), path = builtin('node:path')!, url = builtin('node:url')!
-  if (!fs) return undefined
-  const set = env('WEFT_NATIVE_DIR')
-  if (set) return set
-  let dir = path.dirname(url.fileURLToPath(import.meta.url))
-  for (let i = 0; i < 6; i++, dir = path.dirname(dir)) if (fs.existsSync(path.join(dir, 'rust', 'manifest.json'))) return path.join(dir, 'rust')
-  return undefined
-}
-
-function addonEngine(file: string, hash: string, target: string): Engine {
-  const mod = { exports: {} as { contract: () => string; call: Engine['call'] } }
-  nodeHost.process!.dlopen(mod, file)
-  const built = JSON.parse(mod.exports.contract())
-  if (built.hash !== hash) throw new StartError('R103', `\`${target}\`'s library was built from contract ${built.hash}, and this app's is ${hash}`, 'rebuild it: `weft build`', { status: 502 })
-  return { kind: 'addon', call: mod.exports.call }
-}
-
-/**
- * The same functions as a `.wasm`, on this thread. A panic traps, which ends an instance: what it said arrives first,
- * and the next call gets a new one, as a sidecar's crash gets a restart.
- */
-async function wasmEngine(file: string, hash: string, target: string): Promise<Engine> {
-  const module = await WebAssembly.compile(builtin('node:fs')!.readFileSync(file))
-  const decoder = new TextDecoder()
-  let said = ''
-  let x: Wasm | undefined
-  const text = (ptr: number, len: number) => decoder.decode(new Uint8Array(x!.memory.buffer, ptr, len))
-  const fresh = () => {
-    x = new WebAssembly.Instance(module, { weft: { now: () => performance.now(), panicked: (ptr: number, len: number) => { said = text(ptr, len) } } }).exports as unknown as Wasm
-    x.weft_init()
-  }
-  const taken = (packed: bigint) => {
-    const ptr = Number(packed >> 32n), len = Number(packed & 0xffffffffn)
-    const out = text(ptr, len)
-    x!.weft_free(ptr, len)
-    return out
-  }
-  const put = (s: string): [number, number] => {
-    const bytes = encoder.encode(s)
-    const ptr = x!.weft_alloc(bytes.length)
-    new Uint8Array(x!.memory.buffer, ptr, bytes.length).set(bytes)
-    return [ptr, bytes.length]
-  }
-  fresh()
-  const built = JSON.parse(taken(x!.weft_contract()))
-  if (built.hash !== hash) throw new StartError('R103', `\`${target}\`'s library was built from contract ${built.hash}, and this app's is ${hash}`, 'rebuild it: `weft build`', { status: 502 })
-  return {
-    kind: 'wasm',
-    call(id, ctx, body) {
-      if (!x) fresh()
-      const [i, il] = put(id), [c, cl] = put(ctx), [b, bl] = put(body)
-      try {
-        const reply = taken(x!.weft_call(i, il, c, cl, b, bl))
-        x!.weft_free(i, il)
-        x!.weft_free(c, cl)
-        return reply
-      } catch (e) {
-        if (!(e instanceof WebAssembly.RuntimeError)) throw e
-        x = undefined
-        return JSON.stringify({ ok: false, error: { code: 'Internal', requestId: JSON.parse(ctx).requestId, detail: said || e.message } })
-      }
-    },
-  }
-}
-
-/**
- * A Rust library implementing the functions that point at it, in this process, as `impl: media`. An addon runs each call
- * on the worker pool, so the event loop stays free; where one can't load, its `.wasm` runs them on this thread. Either
- * way the declaration, the client and the caches are the same as for `run`.
- */
+/** A Rust library implementing functions in this process. */
 export function native(name: string, options: NativeOptions = {}): Native {
-  if (!NAME.test(name)) throw new StartError('R104', `\`native('${name}')\` isn't a service name`, "`native('media')`, for the crate at `crates/media`")
-  const { timeout = DEFAULT_TIMEOUT, claims = defaultClaims, validate = true } = options
-  const target = `native('${name}')`
-  // Before the pool's first use: its default of 4 is a ceiling on calls at once that an app would never think to raise.
-  const proc = nodeHost.process
-  if (proc?.env && !proc.env.UV_THREADPOOL_SIZE) proc.env.UV_THREADPOOL_SIZE = String(Math.max(4, globalThis.navigator?.hardwareConcurrency ?? 4))
-
-  let loaded: Promise<Engine> | undefined, stamp: string | undefined
-
-  async function load(dir: string, entry: Entry): Promise<Engine> {
-    const fs = builtin('node:fs')!, path = builtin('node:path')!
-    const addon = entry.addon && path.join(dir, entry.addon)
-    if (addon && fs.existsSync(addon)) {
-      try {
-        return addonEngine(addon, entry.hash, target)
-      } catch (e) {
-        if (e instanceof StartError) throw e
-        console.warn(`[weft] ${target}: the addon didn't load here (${String((e as { message?: unknown }).message).split('\n')[0]})${entry.wasm ? ': using its WASM' : ''}`)
-      }
-    }
-    if (entry.wasm) return wasmEngine(path.join(dir, entry.wasm), entry.hash, target)
-    throw new StartError('R104', `\`${target}\` has no addon for ${platform()} and no WASM`, 'build on this platform, drop `wasm: false` from `rust.services`, or use `remote()`', { status: 503 })
-  }
-
-  /** The engine for now. Under `weft dev` a rebuild is a new file: the next call loads it, and calls on the old one finish. */
-  function engine(): Promise<Engine> {
-    const fs = builtin('node:fs')!, path = builtin('node:path')!
-    const dir = nativeDir()
-    if (!dir) throw new StartError('R104', `\`${target}\` has nothing to load here`, 'this runtime has no file system, or the build has no `rust/` folder: use `remote()`, or run `weft build`', { status: 503 })
-    const file = path.join(dir, 'manifest.json')
-    const watching = !!env('WEFT_NATIVE_DIR')
-    // Its text, not its mtime: two writes can land in one tick of a coarse clock.
-    const text: string | undefined = watching && fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : undefined
-    if (loaded && text === stamp) return loaded
-    const entry: Entry | undefined = fs.existsSync(file) ? JSON.parse(text ?? fs.readFileSync(file, 'utf8'))[name] : undefined
-    if (!entry) throw new StartError('R104', `\`${target}\` isn't in this build`, 'run `weft build`, or check `crates/' + name + '`', { status: 503 })
-    if (entry.failure) throw new StartError('R103', `\`${target}\` didn't build: ${entry.failure}`, 'fix the crate: `weft dev` retries on every edit', { status: 503 })
-    stamp = text
-    const held = loaded
-    const next = load(dir, entry)
-    // A bad build keeps what was serving, as a sidecar's does.
-    loaded = next.catch(e => { if (held) { loaded = held; return held } loaded = undefined; throw e })
-    return loaded
-  }
-
-  return {
-    kind: 'native', target: `native://${name}`, service: name,
-    engine: async () => (await engine()).kind,
-    async call({ fn, input, ctx, request }) {
-      const context = JSON.stringify(callContext(fn, ctx, request, timeout, claims))
-      const body = JSON.stringify({ input: (await wire(fn, input)) ?? null })
-      const running = (await engine()).call(fn.$id, context, body)
-      let timer: ReturnType<typeof setTimeout> | undefined
-      const reply = typeof running === 'string' ? running : await Promise.race([running, new Promise<string>(ok => { timer = setTimeout(ok, timeout, '{"ok":false,"error":{"code":"Deadline"}}') })])
-      clearTimeout(timer)
-      return settled(fn, JSON.parse(reply), target, timeout, validate)
-    },
-  }
+  return createNative(name, options, import.meta.url)
 }

package/src/server/card.tsx

@@ -0,0 +1,65 @@
+import { renderToString } from '@weft-js/core/ssr'
+import type { Merged } from '@weft-js/core/ssr'
+import { DefaultCard } from '../og/DefaultCard'
+import { renderCard } from '../og/index.mjs'
+import { settledView } from './payload'
+import type { HandlerOptions, Manifest, Resolved, RouteModule } from './types'
+export function makeCard({
+  resolve,
+  finished,
+  mod,
+  manifest,
+  options,
+  site,
+  CARD,
+}: {
+  resolve: (path: string, request: Request) => Promise<Resolved>
+  finished: (r: Resolved, request: Request) => Promise<Merged>
+  mod: (file?: string) => RouteModule | undefined
+  manifest: Manifest
+  options: HandlerOptions
+  site: NonNullable<HandlerOptions['site']>
+  CARD: { width: number; height: number }
+}) {
+  return async function og(url: URL, request: Request): Promise<Response> {
+    const path =
+      '/' +
+      url.pathname
+        .slice('/_weft/og/'.length)
+        .replace(/\.png$/, '')
+        .replace(/^index$/, '')
+    const r = await resolve(path, request)
+    if (r.status !== 200 || !r.route) return new Response('Not found', { status: 404 }) // only params the route's own load accepts
+    const head = await finished(r, request)
+    const image = head.og.image
+    if (typeof image !== 'object' || !image.url.startsWith('/_weft/og/'))
+      return new Response('Not found', { status: 404 }) // this page has no generated card
+    const want = new URL(image.url, url).searchParams.get('v')
+    const cardMod = mod(r.route.card ?? manifest.defaultCard)
+    const leaf = r.levels.at(-1)!
+    const cardProps = {
+      params: leaf.params,
+      data: settledView(leaf.raw, leaf.d, leaf.id, options),
+      meta: head,
+      site: { ...site, url: r.origin },
+      path: r.path,
+      title: head.og.title ?? head.title,
+      description: head.og.description ?? head.description ?? '',
+    }
+    const Card = (cardMod?.default ?? DefaultCard) as (props: typeof cardProps) => unknown
+    const html = renderToString(() => <Card {...cardProps} />, { hydratable: false })
+    const png = await renderCard(html, cardMod?.size ?? CARD, options.fonts ?? [], {
+      strict: false,
+      onDiagnostic: (d: { code: string; severity: string; message: string }) =>
+        options.onDiagnostic?.({ ...d, route: r.route!.id }),
+    })
+    // A signed-in request can see what a public cache must not keep.
+    const fresh = url.searchParams.get('v') === want && !request.headers.has('cookie')
+    const cache = options.dev
+      ? 'no-store'
+      : fresh
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache'
+    return new Response(png, { headers: { 'content-type': 'image/png', 'cache-control': cache } })
+  }
+}

package/src/server/compression.ts

@@ -0,0 +1,115 @@
+import type * as NodeZlib from 'node:zlib'
+
+/** A complete page's text. Its Response holds no body until `compressed` gives it one: compressed, it's never read. */
+export const whole = new WeakMap<Response, string>()
+
+type Encoding = 'br' | 'gzip'
+type Zlib = typeof NodeZlib
+
+let loaded: Promise<Zlib | undefined> | undefined
+const loadZlib = () => (loaded ??= import('node:zlib').catch(() => undefined))
+const brotli = (zlib: Zlib, sizeHint: number) => ({
+  params: {
+    [zlib.constants.BROTLI_PARAM_QUALITY]: 5,
+    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: sizeHint,
+  },
+})
+
+const PACKED_MAX = 16 * 1024 * 1024 // characters of text held, per encoding
+const PACKED_ENTRY_MAX = 1024 * 1024
+
+/**
+ * Compressed bodies by their whole text, most recently used last. The text is the key, not a hash of it, so a response
+ * is only ever reused for the same bytes: two users can share an entry only if each was already being sent that page.
+ */
+const packed: Record<Encoding, { entries: Map<string, Promise<Uint8Array>>; held: number }> = {
+  br: { entries: new Map(), held: 0 },
+  gzip: { entries: new Map(), held: 0 },
+}
+
+function compressWhole(zlib: Zlib, encoding: Encoding, text: string): Promise<Uint8Array> {
+  const cache = packed[encoding]
+  const hit = cache.entries.get(text)
+  if (hit) {
+    cache.entries.delete(text)
+    cache.entries.set(text, hit)
+    return hit
+  }
+  const out = new Promise<Uint8Array>((ok, no) => {
+    const done = (e: Error | null, b: Buffer) => (e ? no(e) : ok(b))
+    if (encoding === 'br') zlib.brotliCompress(text, brotli(zlib, Buffer.byteLength(text)), done)
+    else zlib.gzip(text, done)
+  })
+  if (text.length > PACKED_ENTRY_MAX) return out
+  cache.entries.set(text, out)
+  cache.held += text.length
+  for (const key of cache.entries.keys()) {
+    if (cache.held <= PACKED_MAX) break
+    cache.entries.delete(key)
+    cache.held -= key.length
+  }
+  return out
+}
+
+/** A stream of chunks, each flushed as it arrives so a Boundary reaches the client when it resolves. */
+function compressStream(
+  zlib: Zlib,
+  encoding: Encoding,
+  source: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const z = encoding === 'br' ? zlib.createBrotliCompress(brotli(zlib, 0)) : zlib.createGzip()
+  const reader = source.getReader()
+  return new ReadableStream<Uint8Array>({
+    start(out) {
+      z.on('data', (d: Buffer) => out.enqueue(new Uint8Array(d)))
+      z.on('end', () => out.close())
+      z.on('error', (e) => out.error(e))
+      ;(async () => {
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) return void z.end()
+          z.write(value)
+          await new Promise((ok) => {
+            z.flush(ok as () => void)
+          })
+        }
+      })().catch((e) => out.error(e))
+    },
+    cancel(reason) {
+      z.destroy()
+      return reader.cancel(reason)
+    },
+  })
+}
+
+/**
+ * HTML and data go out brotli or gzipped when the client takes it. A response that is complete is compressed once and
+ * kept, since most pages come out the same for every visitor; one still streaming is flushed chunk by chunk. A runtime
+ * with no node:zlib sits behind a platform that compresses.
+ */
+export async function compressed(request: Request, response: Response): Promise<Response> {
+  const page = whole.get(response)
+  const plain = () => (page === undefined ? response : new Response(page, response))
+  if (page === undefined && (!response.body || response.headers.has('content-encoding')))
+    return response
+  const type = response.headers.get('content-type') ?? ''
+  if (!/^(text\/html|application\/json)/.test(type)) return plain()
+  const accepts = request.headers.get('accept-encoding') ?? ''
+  const encoding = /\bbr\b/.test(accepts) ? 'br' : /\bgzip\b/.test(accepts) ? 'gzip' : undefined
+  const zlib = encoding && (await loadZlib())
+  if (!zlib) return plain()
+  const text = page ?? (type.startsWith('application/json') ? await response.text() : undefined)
+  const body =
+    text === undefined
+      ? compressStream(zlib, encoding, response.body!)
+      : await compressWhole(zlib, encoding, text)
+  const headers = new Headers(response.headers)
+  headers.set('content-encoding', encoding)
+  headers.append('vary', 'Accept-Encoding')
+  headers.delete('content-length')
+  return new Response(body as BodyInit, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

package/src/server/core.ts

@@ -0,0 +1,70 @@
+import type { AsyncLocalStorage } from 'node:async_hooks'
+import { region } from '@weft-js/core/ssr'
+import { createRouteState, type Component, type RoutePayload } from '../router'
+import { ErrorPage, NotFoundPage } from '../builtin'
+import { deployUrl } from '../derive.mjs'
+import type { Scope } from '../exec'
+import { routeTree } from './routes'
+import type { Head } from './page-types'
+import type { HandlerOptions, Resolved } from './types'
+
+const HEADS_MAX = 512
+
+/** Handler-local routing, component and head-cache state. */
+export function makeCore(options: HandlerOptions, als: AsyncLocalStorage<Scope>) {
+  const { manifest, modules, site = {} } = options
+  const byId = new Map(manifest.routes.map((r) => [r.id, r]))
+  const mod = (file?: string) => (file ? modules[file] : undefined)
+  const comps: Record<string, Component> = { 404: NotFoundPage, error: ErrorPage }
+  for (const l of manifest.layouts) if (mod(l.file)?.default) comps[l.id] = mod(l.file)!.default!
+  for (const r of manifest.routes) if (mod(r.file)?.default) comps[r.id] = mod(r.file)!.default!
+  const statics = new Set(options.statics)
+  /**
+   * What each route's last render needed in its head, by status, Save-Data and levels: the next request sends that head
+   * before it renders. `null`: a route whose render sets headers, so it renders first.
+   */
+  const heads = new Map<string, Head | null>()
+  const remember = (shape: string, head: Head) => {
+    if (heads.size >= HEADS_MAX && !heads.has(shape)) heads.clear()
+    heads.set(shape, head)
+  }
+  const publicUrl = deployUrl(
+    site,
+    (globalThis as unknown as { process?: { env: Record<string, string | undefined> } }).process
+      ?.env,
+  )
+  let warned = false
+  /**
+   * The origin canonical, og:url and og:image are built on. Without a configured one, the request's: right for what
+   * a browser asked, but it's whatever `Host` said, so a production server says so once. A prerender has no public
+   * request at all (it would write `localhost` into a file), so its pages stay relative and H001 reports them.
+   */
+  const originOf = (request: Request) => {
+    if (publicUrl) return publicUrl
+    if (request.headers.has('x-nitro-prerender') || options.requestOrigin === false)
+      return undefined
+    if (!options.dev && !warned) {
+      warned = true
+      options.onDiagnostic?.({
+        code: 'H001',
+        severity: 'warning',
+        message:
+          "H001 `site.url` is not set, so canonical, og:url and og:image use the request's Host header. Set `site.url`, or `WEFT_SITE_URL` in the deploy environment.",
+      })
+    }
+    return new URL(request.url).origin
+  }
+  /** The route state of a server render: where a static level is in it, it marks where each level starts (`region`). */
+  const stateOf = (r: Resolved, payload: RoutePayload) => {
+    const route = createRouteState(
+      { ...payload, m: r.levels.map((lv) => ({ id: lv.id, params: lv.params, data: lv.raw })) },
+      comps,
+    )
+    if (r.levels.some((l) => statics.has(l.id)))
+      route.around = (d, id, body) =>
+        region(statics.has(id), d, statics.has(r.levels[d - 1]?.id ?? ''), body)
+    return route
+  }
+  const tree = routeTree(manifest, modules, als)
+  return { manifest, site, byId, mod, comps, statics, heads, remember, originOf, stateOf, tree }
+}