@abide/abide 0.110.4 → 0.112.0

package/src/server/responseRelay.ts

@@ -25,7 +25,7 @@ export type ToRelay =
     | { kind: 'pull'; id: number }
     | { kind: 'cancel'; id: number }
 
-/** What the worker's half sends: a request's idle timeout raised, and its head, each chunk, and its end. */
+/** What the worker's half sends: a request's idle timeout set, and its head, each chunk, and its end. */
 export type FromRelay =
     | { kind: 'timeout'; id: number; seconds: number }
     | {
@@ -56,8 +56,8 @@ export function describe(thrown: unknown): string {
 
 /**
  * The worker's half: answers each request the listener sends with `fetch`, and its body a chunk per
- * pull. `take` is handed every `ToRelay` message; `timeout` raises a request's idle timeout where the
- * listener holds its connection (16.22); `hangUpAll` aborts every request still being answered.
+ * pull. `take` is handed every `ToRelay` message; `timeout` sets a request's idle timeout where the
+ * listener holds its connection (16.23); `hangUpAll` aborts every request still being answered.
  */
 export function serveOver(
     channel: Channel<FromRelay>,
@@ -80,7 +80,7 @@ export function serveOver(
         number,
         { reader: ReadableStreamDefaultReader<Uint8Array>; html: boolean }
     >()
-    // 16.22 — each request built here, known by the ask it was built from.
+    // 16.23 — each request built here, known by the ask it was built from.
     const asks = new WeakMap<Request, number>()
 
     const ended = (id: number): void => {
@@ -203,7 +203,7 @@ export function serveOver(
 // and, once its head has come back, the stream the body is fed into and the pull waiting on the
 // worker's next chunk (38.35).
 type InFlight = {
-    // 16.22 — the request bun handed the listener, which is the one its idle timeout is raised on.
+    // 16.23 — the request bun handed the listener, which is the one its idle timeout is set on.
     request: Request
     headers: [string, string][]
     body: ArrayBuffer | null
@@ -223,7 +223,7 @@ type InFlight = {
  * compiles; `endAll` ends what the worker that is gone was answering.
  */
 export function askOver(
-    raiseTimeout: (request: Request, seconds: number) => void,
+    setIdleTimeout: (request: Request, seconds: number) => void,
 ) {
     let channel: Channel<ToRelay> | undefined
     const inFlight = new Map<number, InFlight>()
@@ -334,7 +334,7 @@ export function askOver(
             const waiting = inFlight.get(message.id)
             if (waiting === undefined) return
             if (message.kind === 'timeout') {
-                raiseTimeout(waiting.request, message.seconds)
+                setIdleTimeout(waiting.request, message.seconds)
                 return
             }
             if (message.kind === 'head') {

package/src/server/serveBuild.ts

@@ -24,6 +24,7 @@ import {
     PUBLIC_DIRECTORY,
 } from './CLIENT_BUILD.ts'
 import { bundleServer, type ServedFile } from './clientBundle.ts'
+import { settingOn } from './config.ts'
 import type { Manifest } from './manifestOf.ts'
 import { namesUnder } from './namesUnder.ts'
 import { ENCODINGS } from './negotiateEncoding.ts'
@@ -137,6 +138,7 @@ export function builtSources(parts: BuildParts): Promise<AppSources> {
                 files,
                 'public, max-age=31536000, immutable',
             ),
+            offline: settingOn('ABIDE_OFFLINE', true),
         },
     })
 }

package/src/server/serveDev.ts

@@ -31,6 +31,7 @@ import { DEV_ADDRESS } from '#shared/ADDRESSES.ts'
 import type { Compilation } from './abideModules.ts'
 import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
 import type { FromWorker, ToWorker } from './devWorker.ts'
+import { IDLE_TIMEOUT_SECONDS } from './IDLE_TIMEOUT_SECONDS.ts'
 import { muxSocketOptions, sendOrClose, upgraded } from './muxUpgrade.ts'
 import { placeOf } from './placement.ts'
 import { plainAnswer } from './plainAnswer.ts'
@@ -77,7 +78,7 @@ export async function serveDev(
     options: DevOptions,
 ): Promise<Bun.Server<undefined>> {
     // 38.24, 38.35 — every request, asked of the worker there is and streamed back a chunk per read.
-    // 16.22 — a call's idle timeout raised on the request bun handed this listener.
+    // 16.23 — a request's idle timeout set on the request bun handed this listener.
     const relay = askOver((request, seconds) =>
         served?.timeout(request, seconds),
     )
@@ -302,6 +303,8 @@ export async function serveDev(
         ...(port === undefined ? {} : { port }),
         // 16.54, as `App.listen` lifts it: the worker behind this is where the ceiling is read.
         maxRequestBodySize: Number.MAX_SAFE_INTEGER,
+        // 16.56 — the bound a request received whole lifts and its answer puts back (16.23).
+        idleTimeout: IDLE_TIMEOUT_SECONDS,
         async fetch(request, listening) {
             const asked = new URL(request.url).pathname
             // THE MUX STANDS UNDER THE MOUNT, which is the app's configuration and so the worker's to

package/src/server/streamEvent.ts

@@ -5,9 +5,68 @@
 import type { Problem } from '#shared/Failed.ts'
 import type { Framed } from '#shared/framing.ts'
 import { REFUSAL_KEY } from '#shared/REFUSAL_KEY.ts'
+import { HEARTBEAT_MILLISECONDS } from './HEARTBEAT_MILLISECONDS.ts'
 
 /** AN EVENT STREAM OPENS ON A COMMENT, so a proxy has bytes to pass before the first event. */
-export const EVENT_STREAM_OPENER = ':\n\n'
+export const EVENT_STREAM_OPENER = new TextEncoder().encode(':\n\n')
+
+/**
+ * `body`, read one chunk a pull; `release` runs once it closes, errors or its reader hangs up.
+ *
+ * 16.57 — `beats`: a comment wherever a read has waited a heartbeat for its next chunk. A COMMENT
+ * RATHER THAN AN EVENT: every reader skips one (18.27), and it gives a proxy in front bytes to
+ * pass, so neither it nor the reader takes a quiet stream for a dead one. A bridge's reader goes by
+ * it too (44.27), where a frame would sit in the pairing's inbox through a drop.
+ *
+ * BEATS ONLY WHILE A READ WAITS, at a high-water mark of 0: a reader that stalled or never started
+ * pulls nothing, so no comment queues behind it and no timer outlives it, and `body` is pulled no
+ * further ahead than it was. A read the beat won is kept for the next pull.
+ */
+export function heldBody(
+    body: ReadableStream<Uint8Array>,
+    release: () => void,
+    beats: boolean,
+): ReadableStream<Uint8Array> {
+    const reader = body.getReader()
+    let pending: ReturnType<typeof reader.read> | undefined
+    return new ReadableStream<Uint8Array>(
+        {
+            async pull(controller) {
+                pending ??= reader.read()
+                let beat: ReturnType<typeof setTimeout> | undefined
+                try {
+                    const next = beats
+                        ? await Promise.race([
+                              pending,
+                              new Promise<undefined>((quiet) => {
+                                  beat = setTimeout(
+                                      () => quiet(undefined),
+                                      HEARTBEAT_MILLISECONDS,
+                                  )
+                              }),
+                          ])
+                        : await pending
+                    if (next === undefined)
+                        return controller.enqueue(EVENT_STREAM_OPENER)
+                    pending = undefined
+                    if (!next.done) return controller.enqueue(next.value)
+                    controller.close()
+                    release()
+                } catch (thrown) {
+                    controller.error(thrown)
+                    release()
+                } finally {
+                    clearTimeout(beat)
+                }
+            },
+            cancel(reason) {
+                release()
+                return reader.cancel(reason)
+            },
+        },
+        { highWaterMark: 0 },
+    )
+}
 
 /**
  * One event: its `event` name and `id` where it has them, and `data` — one line, which JSON is as

package/src/shared/ADDRESSES.ts

@@ -59,3 +59,14 @@ export const SOCKET_ADDRESS = `${ABIDE_ADDRESS}/socket`
  * 26.2.
  */
 export const PRINCIPAL_ADDRESS = `${ABIDE_ADDRESS}/principal`
+
+/**
+ * Where an app with `ABIDE_OFFLINE` on serves its service worker, and where every other app serves
+ * the one that removes it.
+ *
+ * 45.1, 45.9.
+ */
+export const WORKER_ADDRESS = `${ABIDE_ADDRESS}/worker.js`
+
+/** The web app manifest an app answers where it keeps its pages offline and has an icon (45.15). */
+export const APP_MANIFEST_ADDRESS = `${ABIDE_ADDRESS}/manifest.webmanifest`

package/src/shared/ASCII_WHITESPACE.ts

@@ -0,0 +1,6 @@
+/**
+ * A run of ASCII whitespace, which is what a `class` value is split into tokens on — read by the
+ * compiler finding the classes a static `class` holds and by the runtime writing a `class={expr}`'s
+ * tokens (32.71), so both split one way.
+ */
+export const ASCII_WHITESPACE = /[\t\n\f\r ]+/

package/src/shared/LONGEST_DELAY.ts

@@ -0,0 +1,2 @@
+/** The longest delay `setTimeout` holds, in milliseconds: it reads anything past a signed 32-bit count as 1 ms. */
+export const LONGEST_DELAY = 2 ** 31 - 1

package/src/shared/OFFLINE_CACHES.ts

@@ -0,0 +1,12 @@
+// 45.3, 45.5 — THE CACHES THE SERVICE WORKER KEEPS, named once for the worker the server writes and
+// the router that asks whether a page was saved (45.12). A leaf, for the reason every constant
+// crossing a seam is one.
+
+/** What every cache the worker keeps is named under, so a cache an earlier worker named is found. */
+export const OFFLINE_CACHE_PREFIX = 'abide:'
+
+/** The pages, the handlers' answers and the public files the worker saved, by address. */
+export const OFFLINE_SAVED = `${OFFLINE_CACHE_PREFIX}saved`
+
+/** The build's bundle, saved as the worker installs. */
+export const OFFLINE_BUNDLE = `${OFFLINE_CACHE_PREFIX}bundle`

package/src/shared/OFFLINE_META.ts

@@ -0,0 +1,7 @@
+/**
+ * The `<meta>` the server writes unless `ABIDE_OFFLINE` is off, and a browser registers the service
+ * worker by.
+ *
+ * 45.1.
+ */
+export const OFFLINE_META = 'abide-offline'

package/src/shared/answerOf.ts

@@ -81,15 +81,40 @@ async function fetched(
     streams: boolean,
     signal: AbortSignal | undefined,
 ): Promise<Answer> {
-    const response = await fetch(
-        request.url,
-        signal === undefined ? request.init : { ...request.init, signal },
-    )
+    let response: Response
+    try {
+        response = await fetch(
+            request.url,
+            signal === undefined ? request.init : { ...request.init, signal },
+        )
+    } catch (error) {
+        // An abort is the load's own ending (16.49), which the value has already answered.
+        if (signal?.aborted === true) throw error
+        // 16.79 — NO ANSWER AT ALL, as a status the app can narrow on rather than the browser's
+        // own `TypeError`, whose message differs in each.
+        return unanswered()
+    }
     // THE HANDLER SIGNED THIS CALLER IN OR OUT, and the cookie is already the browser's.
     principalRotated(response)
     return answerFrom(response, undefined, streams)
 }
 
+/** The answer a call that reached no server stands in for: an empty 503, which `answered` refuses. */
+function unanswered(): Answer {
+    return {
+        status: 503,
+        statusText: '',
+        ok: false,
+        framing: null,
+        followable: false,
+        version: undefined,
+        life: undefined,
+        text: '',
+        bytes: undefined,
+        body: undefined,
+    }
+}
+
 /**
  * `response`, classified: a body `read` to its end already (an early call the server painted)
  * decoded as what it carried, and one unread read as bytes where it is a binary (16.34), as text

package/src/shared/attributeText.ts

@@ -31,7 +31,7 @@ export function attributeText(name: string, value: unknown): string | null {
     const safe = safeUrl(text)
     if (safe !== text)
         RENDER_LOG.warning(
-            `abide: \`${name}\` was handed a URL whose scheme is not http:, https:, mailto: or tel:, and is written empty. RULEBOOK 32.20.`,
+            `abide: \`${name}\` was handed a URL whose scheme is not http:, https:, mailto:, tel:, blob: or data:, and is written empty. RULEBOOK 32.20.`,
         )
     return safe
 }

package/src/shared/reactive/Expiry.ts

@@ -38,6 +38,8 @@
 // nothing is dropped early, and the read-driven backstop in `Reactive.ts` catches up the
 // moment the clock does.
 
+import { LONGEST_DELAY } from '../LONGEST_DELAY.ts'
+
 export type Expiry = {
     /** The life of one production, in milliseconds. */
     ms: number
@@ -90,13 +92,23 @@ export function expiryFor(
  * number and has no process to hold open, so the clause is satisfied there by there being nothing
  * to satisfy. CLAUDE.md's uniformity bias is exactly this shape — one mechanism, inert on the side
  * that cannot need it.
+ *
+ * PAST WHAT `setTimeout` HOLDS — 2^31 - 1 ms, near 25 days — a delay is run after 1 ms, and a
+ * deadline that fires early finds nothing expired and re-arms: a timer a millisecond for the life of
+ * the value. So `Infinity` arms nothing, and a longer finite delay arms at the cap — early, which a
+ * deadline re-checks and re-arms from, and which a debounce or throttle window that long takes as
+ * its end.
  */
 export function armTimer(
     expiry: { timer: ReturnType<typeof setTimeout> | null },
     delay: number,
     fire: () => void,
 ): void {
-    const timer = setTimeout(fire, delay > 0 ? delay : 0)
+    if (delay === Number.POSITIVE_INFINITY) return
+    const timer = setTimeout(
+        fire,
+        delay > 0 ? Math.min(delay, LONGEST_DELAY) : 0,
+    )
     const unref = (timer as { unref?: () => void }).unref
     if (typeof unref === 'function') unref.call(timer)
     expiry.timer = timer

package/src/shared/reactive/Reactive.ts

@@ -1998,7 +1998,16 @@ function refused(cell: Cell, failure: unknown): unknown {
     // had set it true, and `error` went from nothing to this. A guard that asked about
     // either is woken here or never.
     probesMoved(cell)
-    if (!cell.servable) cascade(cell)
+    if (cell.servable) return failure
+    // 7.19 — A SERVER THAT COULD NOT BE REACHED (16.79) says nothing about the value held, so the
+    // invalidated value is served again rather than lost to a read that throws, as 4.12 serves one.
+    if (
+        cell.landed &&
+        isFailedNamed(failure, 'HttpError') &&
+        (failure as Failed<string, unknown>).status === 503
+    )
+        serveAgain(cell)
+    else cascade(cell)
     return failure
 }
 
@@ -3253,7 +3262,9 @@ function settled(cell: Cell, untilStreaming = false): Promise<unknown> {
     if (untilStreaming && cell.stream !== null)
         return Promise.resolve(STREAMING)
     if (cell.servable && !busyNow(cell)) return Promise.resolve(heldValue(cell))
-    if (!cell.landed && !busyNow(cell)) {
+    // 2.8 — UNSERVED, NOT UNLANDED: an invalidated value has landed (7.8), and a reload that failed
+    // over it leaves the failure as the answer, or the await waits on a load that has ended.
+    if (!busyNow(cell)) {
         const failure = failureOf(cell)
         if (failure !== undefined) return Promise.reject(failure)
     }
@@ -3280,7 +3291,6 @@ function settled(cell: Cell, untilStreaming = false): Promise<unknown> {
                 settle(heldValue(cell))
                 return
             }
-            if (cell.landed) return
             const failure = failureOf(cell)
             if (failure !== undefined) {
                 waiter.alive = false

package/src/shared/safeUrl.ts

@@ -8,7 +8,14 @@
 // attribute's name.
 import { textOf } from './Raw.ts'
 
-const SAFE_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+const SAFE_SCHEMES = new Set([
+    'http:',
+    'https:',
+    'mailto:',
+    'tel:',
+    'blob:',
+    'data:',
+])
 
 /** A URL attribute's text, or `''` where its scheme is outside the safe set. */
 export function safeUrl(value: unknown): string {

package/src/ui/Level.ts

@@ -6,7 +6,7 @@ import {
 } from '#shared/reactive/share.ts'
 import { untracked } from '#shared/reactive/tracking.ts'
 import { type Disposer, watchTracked } from '#shared/reactive/watch.ts'
-import { applyHead, withdrawHead } from './applyHead.ts'
+import { reconciled, reconcileHead } from './reconcileHead.ts'
 import { isEmptyRegion, type Region } from './regions.ts'
 import type { Scope } from './Scope.ts'
 
@@ -43,10 +43,10 @@ export class Level {
      */
     share: ShareScope | null = null
     /**
-     * The head the components built on the client contributed while this level mounts, applied
-     * once its `mount` returns; `undefined` outside one, where a contribution applies at once.
+     * Whether a component built on the client contributed a head while this level mounts, which is
+     * reconciled once its `mount` returns; `undefined` outside one, where it is reconciled at once.
      */
-    unapplied: string | undefined = undefined
+    unapplied: boolean | undefined = undefined
     /**
      * This level's own head markup as it reads now; `undefined` for a level with no `<head>`.
      *
@@ -82,11 +82,31 @@ export class Level {
         this.share = share
     }
 
-    /** The level's head as it reads now: its own, then every component's, deepest last (39.4). */
-    headMarkup(): string {
-        let markup = this.head?.() ?? ''
-        for (const one of this.contributed) markup += one.head()
-        return markup
+    /** Reconciles the document head from the chain this level stands in (`reconcileHead`). */
+    reconcile(): void {
+        Level.reconcile(this.levels)
+    }
+
+    /**
+     * Reconciles the document head from `levels`: each level's own head, then every component's in
+     * the order they mounted, outermost first — so the deepest wins by key (39.4). Read untracked:
+     * a head read here is followed by its own watch, not by whatever wrote.
+     */
+    static reconcile(levels: Level[]): void {
+        reconcileHead(untracked(Level.chain, levels, undefined))
+    }
+
+    /** Every contributor in `levels` and the head it reads now, outermost first. */
+    static chain(
+        levels: Level[],
+        _?: undefined,
+    ): [who: object, text: string][] {
+        const chain: [object, string][] = []
+        for (const level of levels) {
+            if (level.head !== undefined) chain.push([level, level.head()])
+            for (const one of level.contributed) chain.push([one, one.head()])
+        }
+        return chain
     }
 
     /**
@@ -100,78 +120,18 @@ export class Level {
         const contribution = new HeadContribution(this, head)
         this.contributed.add(contribution)
         contribution.dispose = watchTracked(() => contribution.follow())
-        // Batched while this level mounts; applied at once by an arm or a row mounted after it,
-        // under whatever is deeper (39.4) — only the levels below, since it was added last here.
-        const text = contribution.last ?? ''
+        // Batched while this level mounts; reconciled at once for an arm or a row mounted after it.
         if (isEmptyRegion(region))
-            if (this.unapplied !== undefined) this.unapplied += text
-            else
-                applyHead(
-                    text,
-                    untracked(Level.headsOf, this.levels, this.at + 1),
-                )
+            if (this.unapplied !== undefined) this.unapplied = true
+            else this.reconcile()
         return contribution
     }
 
-    /**
-     * Writes `text` over the `last` that `contributor` in this level wrote.
-     *
-     * 39.4 — IT YIELDS TO EVERY CONTRIBUTOR DEEPER, read as they stand at the write and untracked:
-     * the components that contributed after it, then every level below, so a layout's
-     * `<title>{site}</title>` moving does not write over the page's `<title>`, and the page's head
-     * moving wakes only the page's own watch. 39.15 — its keyless nodes replace the ones it wrote.
-     */
-    reapply(text: string, last: string, contributor: HeadContribution): void {
-        applyHead(
-            text,
-            untracked(Level.headsAfter, this, contributor),
-            last,
-            // Read only where a key `last` held is withdrawn.
-            () => untracked(Level.headsBefore, this, contributor),
-        )
-    }
-
-    /**
-     * The heads either side of `contribution` in `level` (`headsBefore`, `headsAfter`). One `level`
-     * does not hold is the level's own head (`followHead`), which stands before every component's.
-     */
-    static headsAround(
-        level: Level,
-        contribution: HeadContribution,
-    ): [string, string] {
-        return [
-            Level.headsBefore(level, contribution),
-            Level.headsAfter(level, contribution),
-        ]
-    }
-
-    /** Every level above `level`, then what stands before `contribution` in it. */
-    static headsBefore(level: Level, contribution: HeadContribution): string {
-        let outer = Level.headsOf(level.levels, 0, level.at)
-        if (!level.contributed.has(contribution)) return outer
-        outer += level.head?.() ?? ''
-        for (const one of level.contributed) {
-            if (one === contribution) break
-            outer += one.head()
-        }
-        return outer
-    }
-
-    /** What stands after `contribution` in `level`, then every level below it. */
-    static headsAfter(level: Level, contribution: HeadContribution): string {
-        let inner = ''
-        let past = !level.contributed.has(contribution)
-        for (const one of level.contributed)
-            if (past) inner += one.head()
-            else if (one === contribution) past = true
-        return inner + Level.headsOf(level.levels, level.at + 1)
-    }
-
     /**
      * 39.13 — A HEAD THAT READS A VALUE FOLLOWS IT for as long as the level is mounted, which is
      * `scope`'s life. The first run only subscribes: the head it would write is already there,
      * written by the server or applied by the level's mount ahead of its fill (39.6). Followed as a
-     * component's is, by a contribution the level does not hold (`headsAround`).
+     * component's is, by a contribution the level does not hold.
      */
     followHead(scope: Scope): void {
         const own = new HeadContribution(this, this.head as () => string)
@@ -190,8 +150,8 @@ export class Level {
             values: new Map(),
             level: this,
         })
-        this.unapplied = ''
-        let unapplied: string
+        this.unapplied = false
+        let unapplied: boolean
         let result: Result
         try {
             result = run()
@@ -200,20 +160,9 @@ export class Level {
             this.unapplied = undefined
             leaveShare(back)
         }
-        // 39.4 — under whatever a level below wrote while this one was mounting: the page in a
-        // layout's `<slot/>` applied its own head ahead of the components that layout holds.
-        if (unapplied !== '')
-            applyHead(unapplied, Level.headsOf(this.levels, this.at + 1))
+        if (unapplied) this.reconcile()
         return result
     }
-
-    /** The heads of `levels` from `from` to `to`, outermost first. */
-    static headsOf(levels: Level[], from: number, to = levels.length): string {
-        let markup = ''
-        for (let at = from; at < to; at += 1)
-            markup += (levels[at] as Level).headMarkup()
-        return markup
-    }
 }
 
 /**
@@ -236,24 +185,23 @@ export class HeadContribution {
     follow(): void {
         const text = this.head()
         const last = this.last
-        if (last !== undefined && text !== last)
-            this.level.reapply(text, last, this)
         this.last = text
+        if (last !== undefined && text !== last) this.level.reconcile()
     }
 
     /**
-     * 39.14 — WITHDRAWN AS A LEAVING LEVEL'S IS, its keys going back to what stands outside it and
-     * staying where something deeper holds them. Nothing where the level is leaving too: the router
-     * withdraws the whole level once, and cleared its contributions before stopping it.
+     * 39.14 — WITHDRAWN AS A LEAVING LEVEL'S IS: the chain is reconciled without it. Adopted first
+     * where the server painted it and nothing has reconciled since, so what it painted is known to
+     * be its own. Nothing where the level is leaving too: the router reconciles the whole chain
+     * once, and cleared its contributions before stopping it.
      */
     stop(): void {
         this.dispose?.()
         const level = this.level
         if (!level.contributed.has(this)) return
-        withdrawHead(this.last ?? '', () =>
-            untracked(Level.headsAround, level, this),
-        )
+        if (!reconciled(this)) level.reconcile()
         level.contributed.delete(this)
+        level.reconcile()
     }
 }