lecodes-sdk 2.6.0 → 2.8.1

package/src/runtime/rpc.ts

@@ -5,6 +5,7 @@
  *
  *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
  *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
+ *   export const roomView  = __computed("<serverUrl>", "game.server.ts#roomView")
  *   export const db        = __serverOnly("schema.server.ts#db")
  *
  * Wire (implemented by the runner):
@@ -18,14 +19,20 @@
  * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
  * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
  * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
+ *
+ * `online` (the app's global) is what this transport last learned of its backends: both the calls and
+ * the socket go through here, so it is kept here (docs/plans/multiplayer-plan.md D5a).
  */
 
 import { fetch, File, FormData } from "./fetch"
+import { signal, type Computed } from "../core/signals"
 import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
 import type { ChannelSubscription } from "../server/channel"
+import type { ComputedOptions } from "../server/computed"
 import { _pushRuntime } from "./pushSeam"
+import { firstCallGate, type FirstCallGate } from "./firstCall"
 
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
@@ -38,6 +45,32 @@ export class RpcError extends Error {
   }
 }
 
+// ───────────────────────────── online ─────────────────────────────
+
+/** The backends the transport did not reach the last time it tried — a call that never got there, a
+ *  socket that dropped and is trying again — by server URL. */
+const unreachable = new Set<string>()
+const reachable = signal(true)
+/** What a call or the socket just learned of one backend: it answered (an error answer is an answer),
+ *  or it could not be reached. */
+const heard = (serverUrl: string, answered: boolean) => {
+  if (answered) unreachable.delete(serverUrl)
+  else unreachable.add(serverUrl)
+  reachable.value = unreachable.size === 0
+}
+
+/**
+ * Does the app reach its backend: `true` until a call fails without reaching it (`RpcError` status 0)
+ * or the channel socket drops and starts reconnecting; `true` again once the socket opens, a message
+ * comes over it, or a call is answered — with an error too. With several backends, all of them. Read
+ * `.value` in a binding, a `computed` or an `effect`; it is not the device's network (`device.online`)
+ * and says nothing of whether what a screen shows is old: a computed re-delivers by itself.
+ */
+export const online: Computed<boolean> = reachable
+
+/** @internal forget what was learned of every backend (a test's teardown: `online` is module state). */
+export const _resetOnline = () => { unreachable.clear(); reachable.value = true }
+
 // ───────────────────────────── session token ─────────────────────────────
 
 const sessionKey = (serverUrl: string) => `lecodes.session:${serverUrl}`
@@ -61,6 +94,15 @@ const setSession = (serverUrl: string, token: string | null) => {
 
 const noServer = (id: string) => new RpcError(0, `Endpoint ${id}: the project has no deployed server (compile with serverUrl)`)
 
+/** A device with no token yet: its first call to a backend goes alone and the calls behind it wait
+ *  (./firstCall.ts — the rule a host that calls as a device follows too). One gate per backend per run. */
+const firstCall = new Map<string, FirstCallGate>()
+const gateOf = (serverUrl: string) => {
+  let gate = firstCall.get(serverUrl)
+  if (!gate) { gate = firstCallGate(); firstCall.set(serverUrl, gate) }
+  return gate
+}
+
 /** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
 export const __rpc = (serverUrl: string, id: string) => {
   const call = async (...args: unknown[]): Promise<any> => {
@@ -68,6 +110,22 @@ export const __rpc = (serverUrl: string, id: string) => {
     // an optional argument left out is `undefined` in its place — JSON has no such value (it would
     // travel as null and fail the parameter's type), and it is the last ones
     while (args.length && args[args.length - 1] === undefined) args.pop()
+    return gateOf(serverUrl)(() => !!getSession(serverUrl), () => send(args))
+  }
+  // what the call tells of the backend goes to `online`: an RpcError of status 0 never reached it, any
+  // other end of the call (an error answer too) did — an error thrown before sending (an argument JSON
+  // cannot carry) says nothing of it
+  const send = async (args: unknown[]): Promise<any> => {
+    try {
+      const result = await post(args)
+      heard(serverUrl, true)
+      return result
+    } catch (e) {
+      if (e instanceof RpcError) heard(serverUrl, e.status !== 0)
+      throw e
+    }
+  }
+  const post = async (args: unknown[]): Promise<any> => {
     const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
@@ -118,10 +176,21 @@ type Options = {
   error?: (e: RpcError) => void
 }
 /** `group` is the server's answer (the `ok` frame): undefined until it came. `refused` = the server
- *  said no under that session: the subscription is kept and asked again under another one. */
+ *  said no under that session: the subscription is kept and asked again under another one. `computed`
+ *  = a computed's (`__computed`): the `ok` carries a value, and `last` is the JSON of the one handed on. */
 type Sub = {
   id: number, ch: string, args: unknown[], handler: (message: any) => void, options: Options,
   group: ChannelGroup | null | undefined, refused: { session: string | null } | null,
+  computed: boolean, last: string | undefined,
+}
+const subFrame = (s: Sub): ClientFrame => s.computed ? { t: "sub", id: s.id, ch: s.ch, args: s.args, computed: true } : { t: "sub", id: s.id, ch: s.ch, args: s.args }
+/** A computed's value goes on only when it differs from the last one (a new socket, a new worker, a
+ *  new session answer what the app may already have). */
+const handOn = (s: Sub, value: unknown) => {
+  const json = JSON.stringify(value === undefined ? null : value)
+  if (json === s.last) return
+  s.last = json
+  s.handler(value === undefined ? null : value)
 }
 
 const BACKOFF_MS = [1000, 2000, 5000, 10000, 30000]
@@ -140,15 +209,18 @@ class ChannelSocket {
   private linger: ReturnType<typeof setTimeout> | null = null
   private closedByUs = false
   private everOpened = false
+  /** The token this socket's last `hello` said: a `session` frame answers that hello, and is taken
+   *  only while the storage still holds it — a call may have stored a newer one meanwhile. */
+  private hello: string | null = null
   private serverUrl: string
 
   constructor(serverUrl: string) { this.serverUrl = serverUrl }
 
-  subscribe(ch: string, args: unknown[], handler: (message: any) => void, options: Options): ChannelSubscription {
-    const sub: Sub = { id: this.nextId++, ch, args, handler, options, group: undefined, refused: null }
+  subscribe(ch: string, args: unknown[], handler: (message: any) => void, options: Options, computed = false): ChannelSubscription {
+    const sub: Sub = { id: this.nextId++, ch, args, handler, options, group: undefined, refused: null, computed, last: undefined }
     this.subs.set(sub.id, sub)
     if (this.linger !== null) { clearTimeout(this.linger); this.linger = null }
-    if (this.open) this.send({ t: "sub", id: sub.id, ch, args })
+    if (this.open) this.send(subFrame(sub))
     else this.connect()
     return {
       close: () => {
@@ -166,6 +238,7 @@ class ChannelSocket {
    *  ones are sent too: the new user may be let in. */
   onSessionChanged(token: string | null) {
     if (!this.open) return
+    this.hello = token
     this.send({ t: "hello", session: token })
     const subs = [...this.subs.values()]
     this.subs.clear()
@@ -174,7 +247,7 @@ class ChannelSocket {
       sub.group = undefined
       sub.refused = null
       this.subs.set(sub.id, sub)
-      this.send({ t: "sub", id: sub.id, ch: sub.ch, args: sub.args })
+      this.send(subFrame(sub))
     }
   }
 
@@ -187,7 +260,9 @@ class ChannelSocket {
     ws.addEventListener("open", () => {
       this.open = true
       this.attempts = 0
+      heard(this.serverUrl, true)
       const session = getSession(this.serverUrl)
+      this.hello = session
       this.send({ t: "hello", session })
       const reconnected = this.everOpened
       this.everOpened = true
@@ -196,11 +271,14 @@ class ChannelSocket {
         if (sub.refused && sub.refused.session === session) continue
         sub.group = undefined
         sub.refused = null
-        this.send({ t: "sub", id: sub.id, ch: sub.ch, args: sub.args })
-        if (reconnected) sub.options.reconnect?.()
+        this.send(subFrame(sub))
+        // a computed's `ok` brings the value again: nothing was missed
+        if (reconnected && !sub.computed) sub.options.reconnect?.()
       }
     })
     ws.addEventListener("message", (data) => {
+      // the backend spoke (a socket the app has let go says nothing)
+      if (this.ws === ws) heard(this.serverUrl, true)
       if (typeof data !== "string") return
       let msg: ServerFrame
       try { msg = JSON.parse(data) } catch { return }
@@ -212,6 +290,9 @@ class ChannelSocket {
       this.open = false
       if (this.closedByUs) return
       if (this.subs.size === 0) { this.shutdown(); return }
+      // down while the app listens: it is trying again, and until then the backend is out of reach. A
+      // close the app asked for (the last subscription gone, a teardown) says nothing of it
+      heard(this.serverUrl, false)
       const delay = BACKOFF_MS[Math.min(this.attempts++, BACKOFF_MS.length - 1)]
       this.timer = setTimeout(() => { this.timer = null; this.connect() }, delay)
     }
@@ -221,24 +302,46 @@ class ChannelSocket {
 
   private onFrame(msg: ServerFrame) {
     switch (msg?.t) {
-      // the server already serves this socket under the token it sends: stored, nothing re-sent
-      case "session": storeSession(this.serverUrl, msg.session ?? null); break
-      case "ok": { const s = this.subs.get(msg.id); if (s) s.group = msg.group ?? null; break }
+      // the server already serves this socket under the token it sends: stored, nothing re-sent — unless a
+      // call stored another token since the hello this answers: then the socket follows the storage (a
+      // device has one identity, the one its calls write rows under)
+      case "session": {
+        const token = msg.session ?? null
+        if (getSession(this.serverUrl) === this.hello) { storeSession(this.serverUrl, token); this.hello = token }
+        else this.onSessionChanged(getSession(this.serverUrl))
+        break
+      }
+      case "ok": {
+        const s = this.subs.get(msg.id)
+        if (!s) break
+        s.group = msg.group ?? null
+        if (s.computed) handOn(s, msg.data)
+        break
+      }
       case "err": {
         const s = this.subs.get(msg.id)
         if (!s) break
+        // a computed's later run failed: the subscription stands, the last value too
+        if (s.computed && s.group !== undefined) {
+          const e = new RpcError(msg.status ?? 0, msg.message ?? "the computed failed")
+          if (s.options.error) s.options.error(e)
+          else console.error(`Computed ${s.ch}: a run failed (${e.status}) — ${e.message}`)
+          break
+        }
         // kept until close(): another session may be let in (onSessionChanged)
         s.group = undefined
         s.refused = { session: getSession(this.serverUrl) }
         const e = new RpcError(msg.status ?? 0, msg.message ?? "subscription refused")
         if (s.options.error) s.options.error(e)
-        else console.error(`Channel ${s.ch}: the subscription was refused (${e.status}) — ${e.message}`)
+        else console.error(`${s.computed ? "Computed" : "Channel"} ${s.ch}: the subscription was refused (${e.status}) — ${e.message}`)
         break
       }
       case "ev": {
         const group = msg.group ?? null
         for (const s of [...this.subs.values()]) {
-          if (s.ch === msg.ch && s.group === group) s.handler(msg.data)
+          if (s.ch !== msg.ch || s.group !== group) continue
+          if (s.computed) handOn(s, msg.data)
+          else s.handler(msg.data)
         }
         break
       }
@@ -293,6 +396,32 @@ export const __channel = (serverUrl: string, id: string) => ({
   publish(): never {
     throw new RpcError(0, `Channel ${id}: the server publishes, the app subscribes — call a server function that publishes`)
   },
+  members(): never {
+    throw new RpcError(0, `Channel ${id}: members() is read on the server — call a server function that reads it`)
+  },
+})
+
+// ───────────────────────────── computeds ─────────────────────────────
+
+/**
+ * Build the client proxy of computed `id` — what a `computed()` export of a `*.server.ts` file is in the
+ * app (its type is the server's: src/server/computed.ts). Called, it is an endpoint call;
+ * `subscribe([...args,] handler, { error? })` hears its value now (the `ok`) and on every change (an `ev`
+ * to the subscription's own group), over the channel socket.
+ */
+export const __computed = (serverUrl: string, id: string) => Object.assign(__rpc(serverUrl, id), {
+  subscribe(...all: unknown[]): ChannelSubscription {
+    if (!serverUrl) throw noServer(id)
+    const at = all.findIndex(a => typeof a === "function")
+    if (at < 0) throw new RpcError(0, `Computed ${id}: subscribe([...args,] handler) — no handler given`)
+    const args = all.slice(0, at)
+    while (args.length && args[args.length - 1] === undefined) args.pop()
+    const options = (all[at + 1] as ComputedOptions | undefined) ?? {}
+    return socketFor(serverUrl).subscribe(id, args, all[at] as (value: any) => void, { error: options.error as Options["error"] }, true)
+  },
+  watchers(): never {
+    throw new RpcError(0, `Computed ${id}: watchers() is read on the server — call a server function that reads it`)
+  },
 })
 
 // ───────────────────────────── push channels ─────────────────────────────

package/src/runtime/wire.ts

@@ -7,15 +7,20 @@
  *             then DROPS the socket's subscriptions (they were granted to someone else) and the
  *             client sends them again, under new ids.
  *   → sub     subscribe to channel `ch`; `args` are what the app passed to `subscribe` before the
- *             handler — the channel's `groupBy` reads them.
+ *             handler — the channel's `groupBy` reads them. With `computed: true`, to the computed
+ *             `ch` (../server/computed.ts): `args` are its arguments.
  *   → unsub
  *   ← session a token minted while the socket was served (the first contact of a guest): the client
  *             stores it; nothing is dropped, the server already has it.
  *   ← ok      the subscription stands; `group` is where the server put it (null = a channel without
- *             groups). The client learns its group only here — it never names one.
- *   ← err     refused (a hook threw) — the subscription is gone.
+ *             groups). The client learns its group only here — it never names one. A computed's
+ *             group is a number the server made for that one subscription, and `data` its value.
+ *   ← err     refused (a hook threw) — the subscription is gone. For a computed: refused when it comes
+ *             before the `ok` (the first run threw); after it, a later run failed and the
+ *             subscription stands.
  *   ← ev      one published message, addressed by channel + group so the server sends one frame to
- *             every socket of a group; the client hands it to each of its subscriptions there.
+ *             every socket of a group; the client hands it to each of its subscriptions there. For a
+ *             computed: its next value, sent only when it differs from the last one.
  *
  * A group's value is not a secret: its subscriber is told it.
  */
@@ -25,11 +30,11 @@ export type ChannelGroup = string | number
 
 export type ClientFrame =
   | { t: "hello", session: string | null }
-  | { t: "sub", id: number, ch: string, args: unknown[] }
+  | { t: "sub", id: number, ch: string, args: unknown[], computed?: true }
   | { t: "unsub", id: number }
 
 export type ServerFrame =
   | { t: "session", session: string }
-  | { t: "ok", id: number, group: ChannelGroup | null }
+  | { t: "ok", id: number, group: ChannelGroup | null, data?: unknown }
   | { t: "err", id: number, status: number, message: string }
   | { t: "ev", ch: string, group: ChannelGroup | null, data: unknown }

package/src/server/channel.ts

@@ -22,6 +22,11 @@
  * `globalThis.__lecodesPublish` seam the host installs (same reason as ./context.ts: the bundle
  * carries its own SDK copy). In the app the export is another object altogether — the proxy
  * `__channel` of src/runtime/rpc.ts — which is why `subscribe` here only throws.
+ *
+ * Presence: `roomChannel.members(code)` (and a computed's `watchers(...args)`, ./computed.ts) — the
+ * sessions subscribed to a group now. The hub (./channelHub.ts) holds that table; the read goes to it
+ * through the `globalThis.__lecodesPresence` seam the host installs (./computedHost.ts
+ * `setPresenceProvider`), keyed by the export and the subscription's key as JSON (`presenceKey`).
  */
 
 import type { ChannelGroup } from "../runtime/wire"
@@ -49,6 +54,9 @@ export interface Channel<M> {
   groupBy<K extends ChannelGroup, A extends unknown[] = []>(group: (...args: A) => K | Promise<K>): GroupedChannel<M, K, A>
   /** Server: send `message` to every subscriber (at most once — nothing is kept for a socket that is away). */
   publish(message: M): void
+  /** Server: the sessions (`request.session`) subscribed now, each once. Inside a `computed`, a join or a
+   *  leave runs it again. */
+  members(): Promise<number[]>
   /** App: listen until `close()`. */
   subscribe(handler: (message: M) => void, options?: SubscribeOptions): ChannelSubscription
 }
@@ -57,6 +65,9 @@ export interface Channel<M> {
 export interface GroupedChannel<M, K extends ChannelGroup, A extends unknown[]> {
   /** Server: send `message` to the subscribers of `group`. */
   publish(group: K, message: M): void
+  /** Server: the sessions (`request.session`) subscribed to `group` now, each once. Inside a `computed`,
+   *  a join or a leave runs it again. */
+  members(group: K): Promise<number[]>
   /** App: listen until `close()`; the arguments before the handler go to the channel's `groupBy`. */
   subscribe(...args: [...args: A, handler: (message: M) => void, options?: SubscribeOptions]): ChannelSubscription
 }
@@ -81,6 +92,22 @@ export const setChannelPublisher = (publisher: Publisher | null) => {
   else delete seam.__lecodesPublish
 }
 
+/** What a presence read asks the host: the sessions subscribed to export `id` under `key` (`presenceKey`). */
+export type PresenceAsk = (id: string, key: string) => Promise<number[]>
+const presenceSeam = globalThis as unknown as { __lecodesPresence?: PresenceAsk }
+
+/** The key a subscription is present under, the hub's and the reads' alike: a computed's arguments, a
+ *  channel's group (null without groups) — as JSON. */
+export const presenceKey = (what: unknown): string => JSON.stringify(what === undefined ? null : what)
+
+/** @internal `members` / `watchers` of export `id` (null = not registered): the host's answer. */
+export const askPresence = async (what: string, id: string | null, key: unknown): Promise<number[]> => {
+  if (!id) throw new Error(`${what}: not registered — export it from a *.server.ts file`)
+  const ask = presenceSeam.__lecodesPresence
+  if (!ask) throw new Error(`${what}: no host presence installed`)
+  return ask(id, presenceKey(key))
+}
+
 export const isChannelGroup = (v: unknown): v is ChannelGroup =>
   typeof v === "string" || (typeof v === "number" && Number.isFinite(v))
 
@@ -113,6 +140,11 @@ export const channel = <M = unknown>(): Channel<M> => {
       if (!isChannelGroup(args[0])) throw new Error(`channel.publish: a group is a string or a number, got ${args[0] === null ? "null" : typeof args[0]}`)
       deliver(args[0], args[1])
     },
+    async members(...args: unknown[]) {
+      if (!ch.__groupBy) return askPresence("channel.members", ch.__id, null)
+      if (!isChannelGroup(args[0])) throw new Error(`channel.members: this channel has groups — members(group), a string or a number, got ${args[0] === null ? "null" : typeof args[0]}`)
+      return askPresence("channel.members", ch.__id, args[0])
+    },
     subscribe() {
       throw new Error("channel.subscribe: the app subscribes, the server publishes")
     },