@abide/abide 0.49.0 → 0.50.1

package/src/lib/shared/createReachable.ts

@@ -1,108 +1,77 @@
-import { createLivenessWatch } from './createLivenessWatch.ts'
-
 /*
-The reachability registry behind `abide/shared/reachable`. A probe transport
-and the timings are injected so the public name wires them from env + a real
-HEAD while tests drive scripted outcomes on tiny intervals.
-
-Per origin, the first read awaits one real probe (the FAITHFUL first answer —
-its latency, including a full timeout when the host is down, is the price of
-not guessing) and then hands the origin to a createLivenessWatch that re-probes
-every `intervalMs` to keep the value warm. Every later read resolves instantly
-off that warm value, fresh within one interval — the faithful cost is paid once.
+The reachability registry behind `abide/shared/reachable`. A probe transport and the
+TTL are injected so the public name wires them from env + a real HEAD while tests drive
+scripted outcomes.
 
-The inaugural probe runs DIRECTLY, not through the watch: the watch's
-failureLimit (anti-flap) is right for the ongoing poll but would make a down
-host take failureLimit× the timeout to answer on the first call. The watch's
-injected probe doubles as the idle reaper — a host nobody has read in `idleMs`
-stops polling (stop() during the probe changes the watched url, so the watch
-discards the result and never reschedules); the next read restarts it cold.
+Per origin, a TTL memoize: the first read — and any read after the cached verdict has
+aged past `ttlMs` — awaits a real probe (the FAITHFUL answer; its latency, a full timeout
+when the host is down, is the price of not guessing) and caches the verdict with its
+timestamp. Every read within the TTL resolves instantly off that cached value. Concurrent
+reads of a cold/stale origin share the one in-flight probe. No background poll: a host that
+goes down (or recovers) is noticed on the next read after its entry ages out, not
+continuously.
 */
 export function createReachable(options: {
     probe: (origin: string) => Promise<boolean>
-    intervalMs: number
-    idleMs: number
+    ttlMs: number
 }): {
     reachable: (host: string | URL) => Promise<boolean>
-    /* Stop every origin's poll — graceful shutdown, and test isolation. */
+    /* Drop every cached verdict — graceful reset and test isolation. */
     stop: () => void
-    /* `using registry = createReachable(...)` — disposal stops every poll. */
+    /* `using registry = createReachable(...)` — disposal clears the cache. */
     [Symbol.dispose]: () => void
 } {
     type Entry = {
         alive: boolean
-        /* The inaugural probe while it is still in flight; concurrent cold reads await the same one. */
+        /* `Date.now()` when `alive` was taken; a read past `ttlMs` re-probes. */
+        probedAt: number
+        /* A probe in flight — concurrent cold/stale reads await the same one. */
         inflight: Promise<boolean> | undefined
-        watch: ReturnType<typeof createLivenessWatch> | undefined
-        lastReadAt: number
-    }
-    const registry = new Map<string, Entry>()
-
-    /* The ongoing poll's probe: reap an idle origin, else run the real probe. */
-    function watchProbe(origin: string): Promise<boolean> {
-        const entry = registry.get(origin)
-        if (entry && Date.now() - entry.lastReadAt > options.idleMs) {
-            entry.watch?.stop()
-            registry.delete(origin)
-            /* Discarded — stop() moved the watched url, so the watch won't reschedule. */
-            return Promise.resolve(false)
-        }
-        return options.probe(origin)
     }
+    const cache = new Map<string, Entry>()
 
-    function startWatch(entry: Entry, origin: string): void {
-        entry.watch = createLivenessWatch({
-            probe: watchProbe,
-            onChange: (alive) => {
-                entry.alive = alive
-            },
-            intervalMs: options.intervalMs,
-        })
-        entry.watch.watch(origin)
-    }
-
-    async function reachable(host: string | URL): Promise<boolean> {
-        /*
-        HEAD the origin root: this answers host connectivity, not endpoint
-        health. A bare host string defaults to https (the external-dependency
-        norm); an explicit http://… is honored.
-        */
-        const url =
-            typeof host === 'string' && !/^https?:\/\//i.test(host) ? `https://${host}` : host
-        const origin = new URL(url).origin
-        const existing = registry.get(origin)
-        if (existing) {
-            existing.lastReadAt = Date.now()
-            return existing.inflight ?? existing.alive
-        }
-        /* Cold: optimistic seed, but the first read awaits a real probe before returning. */
-        const entry: Entry = {
-            alive: true,
-            inflight: undefined,
-            watch: undefined,
-            lastReadAt: Date.now(),
-        }
-        registry.set(origin, entry)
-        /* A rejecting probe reads as unreachable, not a permanent wedge: without
-           the catch a thrown probe leaves inflight set forever (every later read
-           returns the rejected promise) and never starts the watch. */
+    /* Re-probe an origin, folding the verdict + its timestamp back into the entry. A rejecting
+       probe reads as unreachable, not a permanent wedge (without the catch a thrown probe would
+       leave `inflight` set forever). */
+    function refresh(origin: string, entry: Entry): Promise<boolean> {
         entry.inflight = options
             .probe(origin)
             .catch(() => false)
             .then((alive) => {
                 entry.alive = alive
+                entry.probedAt = Date.now()
                 entry.inflight = undefined
-                startWatch(entry, origin)
                 return alive
             })
         return entry.inflight
     }
 
-    function stop(): void {
-        for (const entry of registry.values()) {
-            entry.watch?.stop()
+    function reachable(host: string | URL): Promise<boolean> {
+        /* HEAD the origin root: host connectivity, not endpoint health. A bare host defaults to
+           https (the external-dependency norm); an explicit http://… is honored. */
+        const url =
+            typeof host === 'string' && !/^https?:\/\//i.test(host) ? `https://${host}` : host
+        const origin = new URL(url).origin
+        const existing = cache.get(origin)
+        if (existing !== undefined) {
+            /* A probe already running → share it (dedupes concurrent cold/stale reads). */
+            if (existing.inflight !== undefined) {
+                return existing.inflight
+            }
+            /* Fresh within the TTL → instant warm read. */
+            if (Date.now() - existing.probedAt < options.ttlMs) {
+                return Promise.resolve(existing.alive)
+            }
+            /* Aged out → re-probe on this read. */
+            return refresh(origin, existing)
         }
-        registry.clear()
+        const entry: Entry = { alive: true, probedAt: 0, inflight: undefined }
+        cache.set(origin, entry)
+        return refresh(origin, entry)
+    }
+
+    function stop(): void {
+        cache.clear()
     }
 
     return { reachable, stop, [Symbol.dispose]: stop }

package/src/lib/shared/createRemoteFunction.ts

@@ -4,22 +4,25 @@ import { HttpError } from './HttpError.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { recordRemoteMeta } from './recordRemoteMeta.ts'
+import { reviveWireOutput } from './reviveWireOutput.ts'
 import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { subscribableFromResponse } from './subscribableFromResponse.ts'
-import type { CacheOptions } from './types/CacheOptions.ts'
+import type { CachePolicy } from './types/CachePolicy.ts'
 import type { ClientFlags } from './types/ClientFlags.ts'
 import type { HttpMethod } from './types/HttpMethod.ts'
+import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
+import type { OutputWirePlan } from './types/OutputWirePlan.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
 import type { RpcOptions } from './types/RpcOptions.ts'
-import type { Subscribable } from './types/Subscribable.ts'
+import type { StreamPolicy } from './types/StreamPolicy.ts'
 
 /*
 Assembles the public RemoteFunction shape used identically by the
 server-side defineRpc (in-process handler invocation) and the
 client-side remoteProxy (network fetch). Centralising the wiring here
 keeps the call/raw/stream/fetch semantics — including WeakMap meta
-recording, Content-Type decode, and Subscribable derivation — in one
+recording, Content-Type decode, and NamedAsyncIterable derivation — in one
 place so the two halves can't drift.
 
 - `buildRequest(args)` synthesizes the Request a meta reader (cache()) or
@@ -50,10 +53,19 @@ export function createRemoteFunction<Args, Return>(opts: {
         opts?: RpcOptions,
     ) => Promise<Response>
     parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
-    /* A streaming rpc (handler returns jsonl()/sse()): the bare call returns the Subscribable
+    /* A streaming rpc (handler returns jsonl()/sse()): the bare call returns the NamedAsyncIterable
        directly (the iterable IS the value) rather than decoding one Response body. Emitted by
        the bundler's syntactic scan; false/undefined keeps the decode-a-Response path. */
     streaming?: boolean
+    /* Endpoint cache/stream policy (ADR-0020) — stamped onto both callable variants so
+       readThrough reads it as the bottom policy layer. Declared once on the rpc definition. */
+    cache?: CachePolicy<Args>
+    stream?: StreamPolicy
+    /* Client-only: the output wire codec plan (ADR-0029) the remoteProxy stub carries — the decoded
+       response body's structured fields are revived through it (a `Set`/`Map`/`bigint`/`Date`). The
+       server defineRpc never sets it, so an in-process read is untouched. undefined leaves the body
+       as its honest-JSON form. */
+    outputWirePlan?: OutputWirePlan
 }): RemoteFunction<Args, Return> {
     const {
         method,
@@ -64,6 +76,9 @@ export function createRemoteFunction<Args, Return>(opts: {
         invoke,
         parseArgsForFetch,
         streaming,
+        cache: cachePolicy,
+        stream: streamPolicy,
+        outputWirePlan,
     } = opts
 
     /*
@@ -102,20 +117,21 @@ export function createRemoteFunction<Args, Return>(opts: {
     }
     rawCall.method = method
     rawCall.url = url
+    /* Endpoint policy on both variants so readThrough can read it off whichever the caller
+       passed (`fn` for the decoded read, `fn.raw` for the raw escape hatch). */
+    rawCall.cache = cachePolicy
+    rawCall.stream = streamPolicy
     /* Non-enumerable brand on both variants; see REMOTE_FUNCTION. */
     Object.defineProperty(rawCall, REMOTE_FUNCTION, { value: true })
     const raw = rawCall as RawRemoteFunction<Args>
 
-    function callable(
-        args: Args | FormData,
-        opts?: RpcOptions,
-    ): Promise<Return> | Subscribable<Return> {
-        /* A streaming rpc (jsonl/sse) returns the Subscribable directly — the iterable IS the
+    function callable(args: Args | FormData): Promise<Return> | NamedAsyncIterable<Return> {
+        /* A streaming rpc (jsonl/sse) returns the NamedAsyncIterable directly — the iterable IS the
            value (for await / state(fn(args))). Deferred fetch, keyForRemoteCall-keyed so tail()
            dedupes readers; no decode, so the error-capture path below doesn't apply. */
         if (streaming) {
             return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
-                raw(args as Args, opts),
+                raw(args as Args),
             )
         }
         /* The bare call IS the smart read: route through the cache store's smart-read
@@ -123,34 +139,40 @@ export function createRemoteFunction<Args, Return>(opts: {
            reactive, while a write is coalesce-only — the raw fetch moves to `.raw`.
            `cache.read(callable, …)` brand-reads `callable.raw` for the undecoded variant
            and decodes on the way out, so pass the callable (which carries `.raw`), not
-           `raw`. `opts` supplies cache options (ttl/tags/throttle/debounce); per-call
-           transport options live on `.raw` now. */
+           `raw`. There is no call-site options argument any more — all cache policy is read
+           from the endpoint (`callable.cache`); per-call transport options live on `.raw`. */
         const key = keyForRemoteCall(method, url, args)
-        return cache
-            .read(callable as RemoteFunction<Args, Return>, args as Args, opts as CacheOptions)
-            .then(
-                /* Capture the rejection into the rpc error registry (design Part 4) keyed by call
+        return cache.read(callable as RemoteFunction<Args, Return>, args as Args).then(
+            /* Capture the rejection into the rpc error registry (design Part 4) keyed by call
                identity, and clear it on success — the reactive `fn.error()` probe reads it. */
-                (value) => {
-                    rpcErrorRegistry.clear(key)
-                    return value as Return
-                },
-                (error: unknown) => {
-                    /* A parked durable write throws a `kind: 'queued'` sentinel — it's pending
-                   retry, not a failure. Don't record it, so fn.error() stays undefined for a
-                   merely-parked write (pending() already reflects it via the outbox). */
-                    if (!(error instanceof HttpError && error.kind === 'queued')) {
-                        rpcErrorRegistry.record(key, error)
-                    }
-                    throw error
-                },
-            )
+            (value) => {
+                rpcErrorRegistry.clear(key)
+                /* Revive the decoded body's structured fields per the baked output plan (ADR-0029):
+                   a wire array → `Set`/`Map`, a digit string → `bigint`, an ISO string → `Date`. The
+                   decoded value is call-private (a fresh decode or cloned warm value), so the revive
+                   mutates in place. No plan (undefined — every server-side read, or a client endpoint
+                   with no structured field) returns the value untouched. */
+                return reviveWireOutput(value, outputWirePlan) as Return
+            },
+            (error: unknown) => {
+                rpcErrorRegistry.record(key, error)
+                throw error
+            },
+        )
     }
     callable.method = method
     callable.url = url
     callable.clients = clients
     callable.crossOrigin = crossOrigin
+    callable.cache = cachePolicy
+    callable.stream = streamPolicy
     callable.raw = raw
+    /* Stamp the output wire codec plan (ADR-0029) so the public `cache(fn, args)` and
+       `cache.peek(fn, args)` can revive the decoded body's structured fields (Set/Map/Date/bigint)
+       exactly as the bare `fn(args)` read does above — otherwise those two read APIs return the raw
+       honest-JSON form and disagree with `fn(args)`. A runtime affordance, not on the RemoteFunction
+       surface (read via cast in cache.ts, like `settled`); undefined server-side / plan-less. */
+    ;(callable as { outputWirePlan?: OutputWirePlan }).outputWirePlan = outputWirePlan
     /* Uniform runtime guard for every rpc — the per-rpc data typing lives entirely in the
        RpcErrorGuard<Errors> signature RemoteFunction projects onto it (Errors flows from the
        rpc helper's declared type, not from here). */