lecodes-sdk 2.5.1 → 2.8.0

package/src/server/channelHub.ts

@@ -19,12 +19,43 @@
  * for the new one. A socket's frames are served ONE AT A TIME, in the order they came: a `hello`
  * never overtakes the subscription sent before it, and two subscriptions of a guest do not mint two
  * sessions.
+ *
+ * A computed subscription (a `sub` frame with `computed: true`, ./computed.ts) goes the same way, with
+ * a number the hub mints for it alone: `subscribe(scope, id, args, ctx, sub)` runs it where the bundle
+ * lives and answers its value (the `ok` carries it), the bundle's side keeps it fresh and publishes each
+ * new value as an envelope to (`id`, `sub`) — the host's `hub.publish`, as a channel's — and
+ * `unsubscribe(scope, sub)` tells it the subscription is over (an unsub, a closed socket, another
+ * session). The hub sends a value only when it differs from the last one sent (JSON), and a host whose
+ * bundle starts in a new process (a deploy, a cold start) calls `hub.rerun(scope)`: every live computed
+ * subscription of it runs there again, in its socket's turn. A first run that fails is a refusal (`err`,
+ * the subscription is gone); a later one that fails is an `err` too, and the subscription stands.
+ *
+ * Presence: a subscription is presence. The hub keeps who is subscribed where — (scope, export id, key)
+ * → sessions, the key a computed's arguments or a channel's group as JSON (./channel.ts `presenceKey`) —
+ * and answers `presence(scope, id, key)`: what `watchers` / `members` read in the bundle, asked over the
+ * host's IPC. A subscription's session is its subscriber's `request.session`, which the bundle's side
+ * decides: the envelope of its guard / first run names it (`subscriber`); one without a session is not
+ * listed. A session is listed once however many subscriptions it has there (two screens, two sockets).
+ * A leave is not at once: a session whose last subscription of a key ended (an unsub, a closed socket,
+ * a `hello` with another session) stays listed for PRESENCE_GRACE_MS, and is gone only if none of its
+ * subscriptions of that key came back meanwhile — a socket that drops on a Wi-Fi → LTE switch and
+ * comes back does not flicker. When the sessions of a key change (a join at once, a leave after its
+ * grace), `presenceChanged(scope, id, key)` tells the bundle's side, which runs the computeds that read
+ * them again. The table is the hub's, in the host's main process: a new worker loses nothing of it.
+ *
+ * A session opens at most RATE_LIMITS.subscribe subscriptions (./rateLimit.ts) — a `sub` past it is refused
+ * with an `err` of status 429, on every host alike.
  */
 
+import { presenceKey } from "./channel"
+import { callerKey, createRateLimiter, RATE_LIMITS, TOO_MANY_CALLS, type RateLimiter } from "./rateLimit"
 import type { RequestContext } from "./context"
 import type { InvokeResult } from "./runtime"
 import type { ChannelGroup, ServerFrame } from "../runtime/wire"
 
+/** How long a session that left a key stays listed (ms): a socket that comes back within it is no leave. */
+export const PRESENCE_GRACE_MS = 5_000
+
 type Ctx = Omit<RequestContext, "id">
 
 /** Where a group's frames go. The default keeps the sockets of a key in a set; a host whose
@@ -38,8 +69,20 @@ export type HubFanout<S> = {
 
 export type ChannelHubOptions<S> = {
   send: (socket: S, frame: string) => void
-  /** Run the hooks of channel `ch` (createSubscribeGuard, wherever the bundle lives): `result` = the group. */
-  subscribe: (scope: string, ch: string, args: unknown[], ctx: Ctx) => Promise<InvokeResult>
+  /** Run the hooks of channel `ch` (createSubscribeGuard, wherever the bundle lives): `result` = the group.
+   *  With `sub`: start computed `ch` for that subscription (createComputedHost's `start`): `result` = its value. */
+  subscribe: (scope: string, ch: string, args: unknown[], ctx: Ctx, sub?: number) => Promise<InvokeResult>
+  /** A computed subscription is over: the bundle's side lets it go (createComputedHost's `end`). Without
+   *  it the hub serves channels only, and a computed subscription is refused. */
+  unsubscribe?: (scope: string, sub: number) => void
+  /** The sessions subscribed to (`id`, `key`) changed — a join (at once) or a leave (after its grace): the
+   *  bundle's side runs the computeds that read them again (createComputedHost's `presenceChanged`). */
+  presenceChanged?: (scope: string, id: string, key: string) => void
+  /** How long a leave waits (default PRESENCE_GRACE_MS; a test's knob). */
+  graceMs?: number
+  /** How often a session may subscribe (default RATE_LIMITS.subscribe, per scope and session — ./rateLimit.ts;
+   *  `null`: no limit). A test's knob. */
+  subscribeLimiter?: RateLimiter | null
   fanout?: HubFanout<S>
 }
 
@@ -49,11 +92,19 @@ export type HubConnection = {
 }
 
 export type ChannelHub<S> = {
-  connect(socket: S, info: { scope?: string, ip?: string, session?: string | null }): HubConnection
+  /** `filesBase`: what a stored file's url starts with for this socket (RequestContext's). */
+  connect(socket: S, info: { scope?: string, ip?: string, session?: string | null, filesBase?: string }): HubConnection
+  /** A channel's message to a group — or, for a computed subscription's (`ch`, `sub`), its next envelope. */
   publish(scope: string, ch: string, group: ChannelGroup | null, message: unknown): void
+  /** The bundle of `scope` runs in a new process: its live computed subscriptions run there again. */
+  rerun(scope: string): Promise<void>
+  /** Who is subscribed to export `id` under `key` (`presenceKey`) in `scope` now: their sessions, each once,
+   *  in the order they came — one that left counts until its grace is over. */
+  presence(scope: string, id: string, key: string): number[]
 }
 
 const keyOf = (scope: string, ch: string, group: ChannelGroup | null) => `${scope}|${ch}|${JSON.stringify(group)}`
+const tableKey = (scope: string, id: string, key: string) => `${scope}|${id}|${key}`
 
 const setFanout = <S>(send: (socket: S, frame: string) => void): HubFanout<S> => {
   const sockets = new Map<string, Set<S>>()
@@ -73,25 +124,143 @@ const setFanout = <S>(send: (socket: S, frame: string) => void): HubFanout<S> =>
   }
 }
 
+/** One socket, as the computed subscriptions on it need it after its frames are served. */
+type Conn<S> = {
+  scope: string
+  socket: S
+  ip?: string
+  filesBase?: string
+  session: string | null
+  closed: boolean
+  /** Run `task` in this socket's turn (after the frames before it). */
+  enqueue(task: () => Promise<void>): Promise<void>
+}
+type Computed<S> = {
+  conn: Conn<S>
+  ch: string
+  args: unknown[]
+  /** the client's id of the subscription */
+  id: number
+  /** the hub's: its group */
+  sub: number
+  /** the JSON of the last value sent */
+  last: string | undefined
+  /** a run of it is on its way (the first, a rerun): what is published meanwhile is newer, and waits */
+  starting: boolean
+  queued: InvokeResult | null
+  /** the session it is present as (its runs say so), once its first run is answered */
+  here: number | undefined
+}
+/** A session under one key: how many of its subscriptions are there; with none, the timer of its leave. */
+type Holder = { n: number, leaving: ReturnType<typeof setTimeout> | null }
+
+const ctxOf = <S>(conn: Conn<S>): Ctx => ({
+  headers: conn.session ? { authorization: `Bearer ${conn.session}` } : {},
+  ip: conn.ip,
+  sessionToken: conn.session ?? undefined,
+  ...(conn.filesBase !== undefined ? { filesBase: conn.filesBase } : {}),
+})
+
 export const createChannelHub = <S>(opts: ChannelHubOptions<S>): ChannelHub<S> => {
   const fanout = opts.fanout ?? setFanout(opts.send)
   const frame = (f: ServerFrame) => JSON.stringify(f)
+  /** live computed subscriptions, by the hub's number */
+  const computeds = new Map<number, Computed<S>>()
+  const conns = new Set<Conn<S>>()
+  let seq = 0
+  const grace = opts.graceMs ?? PRESENCE_GRACE_MS
+  const subscribeLimiter = opts.subscribeLimiter === undefined ? createRateLimiter(RATE_LIMITS.subscribe) : opts.subscribeLimiter
+  /** presence: tableKey → session → its holder, in the order the sessions came */
+  const table = new Map<string, Map<number, Holder>>()
+
+  const join = (scope: string, id: string, key: string, session: number) => {
+    const k = tableKey(scope, id, key)
+    let here = table.get(k)
+    if (!here) table.set(k, here = new Map())
+    const h = here.get(session)
+    if (h) {
+      // back within the grace (a new socket, a re-subscription): it never left
+      h.n++
+      if (h.leaving) { clearTimeout(h.leaving); h.leaving = null }
+      return
+    }
+    here.set(session, { n: 1, leaving: null })
+    opts.presenceChanged?.(scope, id, key)
+  }
+  const leave = (scope: string, id: string, key: string, session: number) => {
+    const k = tableKey(scope, id, key)
+    const here = table.get(k)
+    const h = here?.get(session)
+    if (!here || !h || --h.n > 0) return
+    h.leaving = setTimeout(() => {
+      if (here.get(session) !== h || h.n > 0) return
+      here.delete(session)
+      if (here.size === 0 && table.get(k) === here) table.delete(k)
+      opts.presenceChanged?.(scope, id, key)
+    }, grace)
+    ;(h.leaving as { unref?: () => void }).unref?.()
+  }
+  /** a computed subscription is present as `session` from now on (a run said so) */
+  const presentAs = (c: Computed<S>, session: number | undefined) => {
+    if (session === undefined || session === c.here) return
+    const key = presenceKey(c.args)
+    join(c.conn.scope, c.ch, key, session)
+    if (c.here !== undefined) leave(c.conn.scope, c.ch, key, c.here)
+    c.here = session
+  }
+
+  // a token minted by a run (the first contact of a guest): the socket is that session from now on
+  const adopt = (conn: Conn<S>, token: string) => {
+    conn.session = token
+    opts.send(conn.socket, frame({ t: "session", session: token }))
+  }
+  const deliver = (c: Computed<S>, r: InvokeResult) => {
+    if (c.starting) { c.queued = r; return }
+    if (!r.ok) { opts.send(c.conn.socket, frame({ t: "err", id: c.id, status: r.status, message: r.message })); return }
+    const data = r.result === undefined ? null : r.result
+    const json = JSON.stringify(data)
+    if (json === c.last) return
+    c.last = json
+    opts.send(c.conn.socket, frame({ t: "ev", ch: c.ch, group: c.sub, data }))
+  }
+  /** a run of `c` is back: its answer, then what was published while it ran */
+  const settle = (c: Computed<S>, r: InvokeResult) => {
+    c.starting = false
+    deliver(c, r)
+    const q = c.queued
+    c.queued = null
+    if (q) deliver(c, q)
+  }
 
   return {
     connect(socket, info) {
       const scope = info.scope ?? ""
-      let session = info.session ?? null
-      let closed = false
       let queue: Promise<void> = Promise.resolve()
-      /** client sub id → key */
-      const subs = new Map<number, string>()
+      const conn: Conn<S> = {
+        scope, socket, ip: info.ip, filesBase: info.filesBase, session: info.session ?? null, closed: false,
+        enqueue: (task) => (queue = queue.then(() => conn.closed ? undefined : task()).catch(() => {})),
+      }
+      conns.add(conn)
+      /** client sub id → fan-out key, or the hub's number of a computed subscription */
+      const subs = new Map<number, string | number>()
       /** key → how many of this socket's subs are on it (the fan-out hears of the first and the last) */
       const counts = new Map<string, number>()
+      /** client sub id of a channel subscription → where it is present, and as whom */
+      const held = new Map<number, { ch: string, key: string, session: number }>()
 
       const drop = (id: number) => {
         const key = subs.get(id)
         if (key === undefined) return
         subs.delete(id)
+        if (typeof key === "number") {
+          const c = computeds.get(key)
+          computeds.delete(key)
+          if (c?.here !== undefined) leave(scope, c.ch, presenceKey(c.args), c.here)
+          opts.unsubscribe?.(scope, key)
+          return
+        }
+        const p = held.get(id)
+        if (p) { held.delete(id); leave(scope, p.ch, p.key, p.session) }
         const n = (counts.get(key) ?? 1) - 1
         if (n > 0) { counts.set(key, n); return }
         counts.delete(key)
@@ -99,24 +268,53 @@ export const createChannelHub = <S>(opts: ChannelHubOptions<S>): ChannelHub<S> =
       }
       const dropAll = () => { for (const id of [...subs.keys()]) drop(id) }
 
+      /** A computed subscription: its first run where the bundle lives; the `ok` carries the value. */
+      const compute = async (id: number, ch: string, args: unknown[]) => {
+        if (!opts.unsubscribe) { opts.send(socket, frame({ t: "err", id, status: 404, message: `${ch}: this server keeps no computed values` })); return }
+        const c: Computed<S> = { conn, ch, args, id, sub: ++seq, last: undefined, starting: true, queued: null, here: undefined }
+        computeds.set(c.sub, c)
+        const r = await opts.subscribe(scope, ch, args, ctxOf(conn), c.sub)
+        if (conn.closed) { computeds.delete(c.sub); opts.unsubscribe(scope, c.sub); return }
+        if (r.session) adopt(conn, r.session)
+        if (!r.ok) {
+          // a first run that fails is a refusal: nothing is kept
+          computeds.delete(c.sub)
+          opts.unsubscribe(scope, c.sub)
+          opts.send(socket, frame({ t: "err", id, status: r.status, message: r.message }))
+          return
+        }
+        drop(id)
+        const data = r.result === undefined ? null : r.result
+        c.last = JSON.stringify(data)
+        opts.send(socket, frame({ t: "ok", id, group: c.sub, data }))
+        subs.set(id, c.sub)
+        presentAs(c, r.subscriber)
+        settle(c, { ok: true, result: data })
+      }
+
       const serve = async (msg: any) => {
         switch (msg?.t) {
           case "hello": {
             const next = typeof msg.session === "string" && msg.session ? msg.session : null
-            if (next === session) return
-            session = next
+            if (next === conn.session) return
+            conn.session = next
             dropAll()
             return
           }
           case "sub": {
             const id = Number(msg.id), ch = String(msg.ch ?? "")
             if (!Number.isFinite(id) || !ch) return
+            // a session subscribing too often is refused, the subscription with it (the client hears an RpcError(429))
+            if (subscribeLimiter && !subscribeLimiter.take(`${scope}|${callerKey(conn.session, conn.ip)}`)) {
+              opts.send(socket, frame({ t: "err", id, status: TOO_MANY_CALLS.status, message: TOO_MANY_CALLS.message }))
+              return
+            }
             const args = Array.isArray(msg.args) ? msg.args : []
-            const ctx: Ctx = { headers: session ? { authorization: `Bearer ${session}` } : {}, ip: info.ip, sessionToken: session ?? undefined }
-            const r = await opts.subscribe(scope, ch, args, ctx)
-            if (closed) return
+            if (msg.computed === true) return compute(id, ch, args)
+            const r = await opts.subscribe(scope, ch, args, ctxOf(conn))
+            if (conn.closed) return
             // a token minted by the hooks (the first contact of a guest) → the client stores it
-            if (r.session) { session = r.session; opts.send(socket, frame({ t: "session", session: r.session })) }
+            if (r.session) adopt(conn, r.session)
             if (!r.ok) { opts.send(socket, frame({ t: "err", id, status: r.status, message: r.message })); return }
             const group = (r.result ?? null) as ChannelGroup | null
             const key = keyOf(scope, ch, group)
@@ -125,6 +323,11 @@ export const createChannelHub = <S>(opts: ChannelHubOptions<S>): ChannelHub<S> =
             subs.set(id, key)
             counts.set(key, (counts.get(key) ?? 0) + 1)
             if (counts.get(key) === 1) fanout.subscribe(socket, key)
+            if (r.subscriber !== undefined) {
+              const p = { ch, key: presenceKey(group), session: r.subscriber }
+              held.set(id, p)
+              join(scope, ch, p.key, p.session)
+            }
             return
           }
           case "unsub":
@@ -137,17 +340,44 @@ export const createChannelHub = <S>(opts: ChannelHubOptions<S>): ChannelHub<S> =
         message(raw) {
           let msg: unknown
           try { msg = JSON.parse(raw) } catch { return queue }
-          queue = queue.then(() => closed ? undefined : serve(msg)).catch(() => {})
-          return queue
+          return conn.enqueue(() => serve(msg))
         },
         close() {
-          closed = true
+          conn.closed = true
+          conns.delete(conn)
           dropAll()
         },
       }
     },
     publish(scope, ch, group, message) {
+      const c = typeof group === "number" ? computeds.get(group) : undefined
+      if (c && c.conn.scope === scope && c.ch === ch) { deliver(c, message as InvokeResult); return }
       fanout.publish(keyOf(scope, ch, group), frame({ t: "ev", ch, group, data: message === undefined ? null : message }))
     },
+    async rerun(scope) {
+      const runs: Promise<void>[] = []
+      for (const conn of conns) {
+        if (conn.scope !== scope) continue
+        runs.push(conn.enqueue(async () => {
+          // one after another on a socket, in its turn: a first run still ahead in the queue is done by
+          // now (and runs again here — it may have run in the old process), and a token the first one
+          // mints is the next ones' session
+          for (const c of [...computeds.values()]) {
+            if (c.conn !== conn || c.starting) continue
+            c.starting = true
+            let r: InvokeResult
+            try { r = await opts.subscribe(scope, c.ch, c.args, ctxOf(conn), c.sub) } catch (e) { r = { ok: false, status: 500, message: (e as Error)?.message ?? "Internal error" } }
+            if (conn.closed || computeds.get(c.sub) !== c) continue
+            if (r.session) adopt(conn, r.session)
+            if (r.ok) presentAs(c, r.subscriber)
+            settle(c, r)
+          }
+        }))
+      }
+      await Promise.all(runs)
+    },
+    presence(scope, id, key) {
+      return [...table.get(tableKey(scope, id, key))?.keys() ?? []]
+    },
   }
 }

package/src/server/clock.ts

@@ -0,0 +1,50 @@
+/**
+ * The server's clock under a test: `setServerClock(offsetMs)` moves `Date.now()`, `new Date()` (no
+ * arguments), `Date()` and `performance.now()` of this process that many ms ahead of the machine's clock
+ * — the backend worker of `lecodes test`, where a case has one clock: a flow's `wait` and `clock` steps
+ * move the apps' virtual clocks and this one together (tools/cli/src/dev/backendWorker.ts, set over the
+ * dev backend's IPC). The clock keeps running in real time; only its reading is shifted, and the offset
+ * only grows (the test runner never moves it back), so the server's time never goes backwards.
+ *
+ * Host-side, process-wide on purpose: the server bundle is evaluated in this process and reads the
+ * global `Date` at call time, so one swap covers the bundle, the SDK's host code (sessions, codes) and
+ * every module alike. Installed on the first call; an offset of 0 reads the machine's clock as before.
+ * Timers are not touched: a deadline is data, and a `setTimeout` on the server is not a scheduler.
+ */
+
+let offset = 0
+let installed = false
+
+const install = () => {
+  if (installed) return
+  installed = true
+  const g = globalThis as unknown as { Date: DateConstructor, performance?: { now(): number } }
+  const Real = g.Date
+  // whole ms, as the real one reads: a date field takes an integer
+  const now = () => Math.floor(Real.now() + offset)
+  // A function, not a class: `Date()` called without `new` answers a string, as the real one does.
+  function ShiftedDate(this: unknown, ...args: unknown[]) {
+    if (!new.target) return new Real(now()).toString()
+    return Reflect.construct(Real, args.length === 0 ? [now()] : args, new.target)
+  }
+  Object.setPrototypeOf(ShiftedDate, Real)        // Date.UTC, Date.parse, … are the real ones
+  ShiftedDate.prototype = Real.prototype           // `instanceof Date` holds both ways
+  Object.defineProperty(ShiftedDate, "now", { value: now, writable: true, configurable: true })
+  Object.defineProperty(ShiftedDate, "name", { value: "Date" })
+  g.Date = ShiftedDate as unknown as DateConstructor
+  const perf = g.performance
+  if (perf && typeof perf.now === "function") {
+    const realNow = perf.now.bind(perf)
+    try { Object.defineProperty(perf, "now", { value: () => realNow() + offset, writable: true, configurable: true }) } catch { /* a frozen performance: Date is enough */ }
+  }
+}
+
+/** Read the clock this many ms ahead of the machine's from now on (a test's case clock). */
+export const setServerClock = (offsetMs: number): void => {
+  if (!Number.isFinite(offsetMs)) throw new Error(`setServerClock: ${offsetMs} is not a number of ms`)
+  if (offsetMs !== 0) install()
+  offset = offsetMs
+}
+
+/** The offset the clock reads with now (ms). */
+export const serverClockOffset = (): number => offset

package/src/server/computed.ts

@@ -0,0 +1,84 @@
+/**
+ * `computed(fn)` — a server function the runtime keeps fresh (server global). The app calls it once,
+ * like an endpoint, or subscribes to it: the value now, and again whenever the data it read changes.
+ *
+ *   export const roomView = computed(async (code: string) => {           // game.server.ts
+ *     const room = await db.room.where({ code }).first()
+ *     const players = await db.player.where({ room: code }).select({ name: true, device: true })
+ *     return { room, players, me: request.session }
+ *   })
+ *
+ *   const sub = roomView.subscribe(code, (view) => { room.value = view })   // app: now, then on every change
+ *   sub.close()
+ *   const view = await roomView(code)                                        // app: one call
+ *
+ * The app's `computed` (src/core/signals.ts) is the same idea: a value derived from its inputs, made
+ * again when they change. The app's inputs are signals; the server's are the database's rows. Hence its
+ * two rules: it only READS (a write inside is an error), and its value follows from its data and its
+ * arguments alone (`Math.random()` inside = a value that is new at every run).
+ *
+ * How it stays fresh (./computedHost.ts): a subscription runs `fn` in the subscriber's request scope
+ * (`request.session`, `db.auth`), and every read the db client sends meanwhile becomes a WATCH of the
+ * database (./db/watch.ts). When the database says a watched result may have changed, `fn` runs again —
+ * once for any number of signals during a run — and the subscriber hears the value only when it differs
+ * from the last one (JSON equality). The subscription rides the channel socket (a `sub` frame with
+ * `computed: true`, ../runtime/wire.ts); the hub (./channelHub.ts) holds it across a new worker (a deploy,
+ * an eviction) and runs it there again.
+ *
+ * Identity, as a channel's: the export (`<path>#<name>`), set by the runtime when the bundle is loaded
+ * (`loadServerModules`). In the bundle the export is callable — another server function may
+ * `await roomView(code)`, its reads are then that function's own — and `subscribe` only throws; in the
+ * app it is the proxy `__computed` of src/runtime/rpc.ts.
+ *
+ * Who is here: `roomView.watchers(code)` — the sessions subscribed to it with these arguments now (the
+ * hub's table, read as a channel's `members` is: ./channel.ts `askPresence`). A read, not a hook: inside
+ * a computed it is one more input, and a join or a leave there runs that computed again (./computedHost.ts).
+ */
+
+import { askPresence, type ChannelSubscription } from "./channel"
+
+export type ComputedOptions = {
+  /** The server refused the subscription (its first run threw), or a later run failed: an `RpcError`,
+   *  its `status` the thrown one. Without it the failure is logged. A refused subscription is asked
+   *  again when the session changes; after a failed later run the last value stands and the next change
+   *  runs it again. */
+  error?: (e: Error & { readonly status: number }) => void
+}
+
+/** A server function the runtime keeps fresh: `computed(async (…args) => value)`. */
+export interface ServerComputed<A extends unknown[], R> {
+  /** One call, as an endpoint's. */
+  (...args: A): Promise<R>
+  /** App: `handler` gets the value now, and again each time it changes, until `close()`; the arguments
+   *  before it are the function's. */
+  subscribe(...args: [...args: A, handler: (value: R) => void, options?: ComputedOptions]): ChannelSubscription
+  /** Server: the sessions (`request.session`) subscribed to it with these arguments now, each once — the
+   *  arguments as the app passed them, matched as JSON. Inside a `computed`, a join or a leave runs it again. */
+  watchers(...args: A): Promise<number[]>
+}
+
+/** @internal what the host reads of a computed (./runtime.ts, ./computedHost.ts) */
+export type ComputedRecord = ((...args: unknown[]) => Promise<unknown>) & {
+  /** set by the runtime: `<path>#<export>` */
+  __id: string | null
+  readonly __computed: true
+  readonly __fn: (...args: unknown[]) => Promise<unknown>
+}
+
+export const computed = <A extends unknown[], R>(fn: (...args: A) => Promise<R>): ServerComputed<A, R> => {
+  if (typeof fn !== "function") throw new Error("computed(fn): fn is the async function that reads the value")
+  const c = ((...args: A) => fn(...args)) as unknown as Record<string, unknown>
+  c.__id = null
+  c.__computed = true
+  c.__fn = fn
+  c.subscribe = () => { throw new Error("computed.subscribe: the app subscribes — in server code, call it: await view(...args)") }
+  c.watchers = async (...args: unknown[]) => {
+    // the app's transport leaves out the trailing arguments that are undefined: so does the key
+    while (args.length && args[args.length - 1] === undefined) args.pop()
+    return askPresence("computed.watchers", c.__id as string | null, args)
+  }
+  return c as unknown as ServerComputed<A, R>
+}
+
+export const isComputed = (v: unknown): v is ComputedRecord =>
+  typeof v === "function" && (v as Partial<ComputedRecord>).__computed === true