@abide/abide 0.110.4 → 0.111.0

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/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/Router.ts

@@ -4,6 +4,7 @@ import { ERROR_META } from '#shared/ERROR_META.ts'
 import { firstMatch, type Params, partsOf } from '#shared/matchRoute.ts'
 import { unmounted } from '#shared/mount.ts'
 import { NAVIGATION_HEADER } from '#shared/NAVIGATION_HEADER.ts'
+import { OFFLINE_SAVED } from '#shared/OFFLINE_CACHES.ts'
 import type { ShareScope } from '#shared/reactive/share.ts'
 import { arrive, route } from '#shared/route.ts'
 import { rankRoutes, type Segment } from '#shared/routePattern.ts'
@@ -255,6 +256,20 @@ export class Router {
             // whole reason the ticket is checked here rather than after the mount — and
             // `navigating` stays the newer navigation's to clear.
             if (ticket.signal.aborted) return
+            // 30.32 — OFFLINE, THE DOCUMENT LOAD BELOW CAN ONLY PAINT THE BROWSER'S ERROR PAGE over a
+            // page that works. A history step has already moved the bar, so it is left to the
+            // document.
+            if (
+                answer === undefined &&
+                !navigator.onLine &&
+                step.direction === 'push'
+            ) {
+                // 45.12 — UNLESS THE SERVICE WORKER SAVED THE PAGE, which the document load is
+                // then answered with.
+                if ((await savedOffline(target)) && !ticket.signal.aborted)
+                    location.href = target.href
+                return
+            }
             // 30.18 — A REFUSAL, A RESPONSE MIDDLEWARE ANSWERED ITSELF, or no answer at all: the
             // document asks again and paints whatever the server says. A fetch that failed —
             // offline, or a redirect to another origin that CORS will not let it follow — goes to
@@ -696,6 +711,16 @@ function loadOrMiss(route: Compiled): Promise<PageModule[] | undefined> {
     return load(route).catch(() => undefined)
 }
 
+/** Whether a service worker controls the page and saved `target`'s page (45.12). */
+async function savedOffline(target: URL): Promise<boolean> {
+    if (navigator.serviceWorker?.controller == null) return false
+    const saved = await caches.match(target.href, {
+        cacheName: OFFLINE_SAVED,
+        ignoreVary: true,
+    })
+    return saved !== undefined
+}
+
 /**
  * Asks the server's `middleware` about an address; `undefined` where the fetch failed.
  *

package/src/ui/registerWorker.ts

@@ -0,0 +1,34 @@
+// 45.1 — THE SERVICE WORKER, REGISTERED where the document carries the tag `ABIDE_OFFLINE` has the
+// server write. The route table calls this in every app, so what the server says decides.
+
+import { WORKER_ADDRESS } from '#shared/ADDRESSES.ts'
+import { MOUNT, mounted } from '#shared/mount.ts'
+import { OFFLINE_META } from '#shared/OFFLINE_META.ts'
+import { onPrincipalRotated } from '#shared/principalRotated.ts'
+import { HYDRATE_LOG } from './Mismatch.ts'
+
+/** Registers the app's service worker once the page has loaded, over the mount's whole scope. */
+export function registerWorker(): void {
+    if (document.querySelector(`meta[name="${OFFLINE_META}"]`) === null) return
+    if (!('serviceWorker' in navigator)) return
+    const workers = navigator.serviceWorker
+    const register = (): void => {
+        workers
+            .register(mounted(WORKER_ADDRESS), {
+                scope: `${MOUNT.current()}/`,
+            })
+            // 45.10
+            .catch((error: unknown) =>
+                HYDRATE_LOG.warning(
+                    'the service worker did not register',
+                    error,
+                ),
+            )
+    }
+    // AFTER THE LOAD, so installing it — every file of the bundle fetched — does not compete with
+    // the page it is installing for.
+    if (document.readyState === 'complete') register()
+    else addEventListener('load', register, { once: true })
+    // 45.7 — a sign-in or sign-out in any tab: the pages it saved were another caller's.
+    onPrincipalRotated(() => workers.controller?.postMessage('rotated'), true)
+}

package/src/ui/routing.ts

@@ -15,4 +15,5 @@
 // `ROUTING_SPECIFIER`. An app with no page never resolves this entry.
 
 export { listenForRoutes } from './listenForRoutes.ts'
+export { registerWorker } from './registerWorker.ts'
 export { type PageMount, type Route, Router, startRouter } from './Router.ts'

package/src/ui/socketWire.ts

@@ -133,6 +133,7 @@ class Mux {
     subscriptions: Map<number, Following>
     nextId: number
     retry: number
+    retrying: ReturnType<typeof setTimeout> | undefined
 
     constructor(url: string) {
         this.url = url
@@ -140,7 +141,23 @@ class Mux {
         this.subscriptions = new Map()
         this.nextId = 1
         this.retry = RETRY_FLOOR_MS
+        this.retrying = undefined
         onPrincipalRotated(() => this.reopen(), true)
+        // 18.33 — THE BACKOFF IS FOR A SERVER THAT IS DOWN, not for a network that has just come
+        // back or a tab whose timers the browser was throttling while it was hidden.
+        addEventListener('online', () => this.redial())
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'visible') this.redial()
+        })
+    }
+
+    /** Opens a closed socket now, in place of the retry waiting out its backoff. */
+    redial(): void {
+        if (this.socket !== null || this.subscriptions.size === 0) return
+        clearTimeout(this.retrying)
+        this.retrying = undefined
+        this.retry = RETRY_FLOOR_MS
+        this.connect()
     }
 
     /**
@@ -188,11 +205,25 @@ class Mux {
         socket.onclose = () => {
             this.socket = null
             if (this.subscriptions.size === 0) return
-            setTimeout(() => this.connect(), this.retry)
-            this.retry = Math.min(this.retry * 2, RETRY_CEILING_MS)
+            this.retryLater()
         }
     }
 
+    /**
+     * Arms the next attempt at the backoff standing, and doubles it.
+     *
+     * 18.34 — OFFLINE, AN ATTEMPT CANNOT SUCCEED, so none is armed: the `online` event's `redial`
+     * makes the next one.
+     */
+    retryLater(): void {
+        if (!navigator.onLine) return
+        this.retrying = setTimeout(() => {
+            this.retrying = undefined
+            this.connect()
+        }, this.retry)
+        this.retry = Math.min(this.retry * 2, RETRY_CEILING_MS)
+    }
+
     receive(frame: ServerFrame): void {
         this.subscriptions.get(frame.id)?.receive(frame)
     }