@owlmeans/client-socket 0.1.18-rc.4 → 0.1.18-rc.40

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/client-socket",
-  "version": "0.1.18-rc.4",
+  "version": "0.1.18-rc.40",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 132 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -25,19 +26,21 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
     "@types/react": "^19.2.17",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.4",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.4",
-    "@owlmeans/client": "^0.1.18-rc.4",
-    "@owlmeans/client-context": "^0.1.18-rc.4",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.4",
-    "@owlmeans/context": "^0.1.18-rc.4",
-    "@owlmeans/entrypoint": "^0.1.18-rc.4",
-    "@owlmeans/socket": "^0.1.18-rc.4"
+    "@owlmeans/auth": "^0.1.18-rc.36",
+    "@owlmeans/basic-envelope": "^0.1.18-rc.37",
+    "@owlmeans/basic-ids": "^0.1.18-rc.33",
+    "@owlmeans/client": "^0.1.18-rc.42",
+    "@owlmeans/client-context": "^0.1.18-rc.39",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.38",
+    "@owlmeans/context": "^0.1.18-rc.32",
+    "@owlmeans/entrypoint": "^0.1.18-rc.37",
+    "@owlmeans/socket": "^0.1.18-rc.34"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.ts

@@ -0,0 +1,18 @@
+
+import type { ReconnectPolicy } from './types.js'
+
+/**
+ * 0.2s → 3s geometric backoff, retried for up to 10 minutes before the carrier gives up and
+ * reports the connection lost. See the client-socket skill's "Disconnects" section.
+ */
+export const DEFAULT_RECONNECT_POLICY: ReconnectPolicy = {
+  minDelay: 200,
+  maxDelay: 3_000,
+  factor: 2,
+  jitter: 0.1,
+  budget: 600_000,
+  reviveBudget: 15_000,
+  stableAfter: 10_000,
+  heartbeat: 30_000,
+  pongTimeout: 10_000,
+}

package/src/helper.ts

@@ -1,61 +1,173 @@
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import { provideRequest } from '@owlmeans/client-entrypoint'
-import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { Connection } from '@owlmeans/socket'
-import { SocketInitializationError } from '@owlmeans/socket'
+import { SocketConnectionError } from '@owlmeans/socket'
 import { makeConnection } from './utils/connection.js'
 import { assertContext } from '@owlmeans/context'
-import type { Config, Context } from './types.js'
+import type { EntrypointReference } from '@owlmeans/context'
+import type { Config, Context, ConnectOptions, ReconnectPolicy, SocketStatusServiceAppend, WsOptions } from './types.js'
 import { useContext, useValue } from '@owlmeans/client'
 import { AUTH_QUERY } from '@owlmeans/auth'
-import { urlCall } from '@owlmeans/client-entrypoint/utils'
-import { useEffect, useMemo } from 'react'
+import { entrypointUrl } from '@owlmeans/client-entrypoint/utils'
+import { useEffect, useMemo, useState } from 'react'
+import { createIdOfLength } from '@owlmeans/basic-ids'
+import { DEFAULT_RECONNECT_POLICY } from './consts.js'
+import { SOCKET_STATUS } from './status.js'
 
-export const ws = async (module: ClientEntrypoint<string>, request?: AbstractRequest<{ token?: string }>): Promise<Connection> => {
-  const ctx = assertContext<Config, Context>(module.ctx as Context, 'client-ws')
-  request = request ?? provideRequest(module.getAlias(), module.getPath())
-  const [url, state] = await urlCall({ ref: module })(request)
+const resolvePolicy = (
+  ctx: Context, options?: ConnectOptions
+): { policy: ReconnectPolicy, retry: boolean } => {
+  const requested = options?.reconnect !== undefined ? options.reconnect : ctx.cfg.socket?.reconnect
+  const retry = requested !== false
+  const overrides = requested === false || requested == null ? {} : requested
+  return { policy: { ...DEFAULT_RECONNECT_POLICY, ...overrides }, retry }
+}
 
-  if (state !== EntrypointOutcome.Ok) {
-    throw new SocketInitializationError
-  }
+const openRawSocket = async (url: string): Promise<WebSocket> => {
   const socket = new WebSocket(url)
+  return await new Promise<WebSocket>((resolve, reject) => {
+    const cleanup = () => {
+      socket.removeEventListener('open', onOpen)
+      socket.removeEventListener('error', onFail)
+      socket.removeEventListener('close', onFail)
+    }
+    const onOpen = () => { cleanup(); resolve(socket) }
+    const onFail = () => { cleanup(); reject(new SocketConnectionError('handshake')) }
+    socket.addEventListener('open', onOpen)
+    socket.addEventListener('error', onFail)
+    socket.addEventListener('close', onFail)
+  })
+}
 
-  return new Promise(resolve => {
-    socket.onopen = () => {
-      const heartbeat = setInterval(() => {
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(JSON.stringify({ type: 'ping' }))
-        }
-      }, 30_000)
+const establish = async (
+  ctx: Context, policy: ReconnectPolicy, retry: boolean, open: () => Promise<WebSocket>
+): Promise<Connection> => {
+  const statusId = createIdOfLength(8)
+  const status = ctx.hasService(SOCKET_STATUS)
+    ? (ctx as unknown as SocketStatusServiceAppend).socketStatus() : null
 
-      socket.addEventListener('close', () => {
-        console.info('WebSocket connection closed, clearing heartbeat interval.')
-        clearInterval(heartbeat)
-      })
+  let opened = false
+  let lost = false
+  const managed = makeConnection({
+    policy, retry, open, onStatus: state => {
+      lost = state === 'lost'
+      status?.report(statusId, state, state === 'online' ? undefined : revive)
+    }
+  })
+  const { connection, ready } = managed
+
+  const baseClose = connection.close
+  connection.close = async () => {
+    await baseClose()
+    status?.release(statusId)
+  }
 
-      resolve(makeConnection(socket, ctx))
+  const revive = () => {
+    if (opened || !lost) {
+      managed.revive()
+      return
     }
+    // Never opened, so `ws()` already rejected and nobody holds this connection to hand a revived
+    // socket to: drop it for good and leave re-dialing to its owner (`useWs` does, on `onRetry`).
+    void baseClose()
+    status?.release(statusId)
+  }
+
+  // A rejection leaves this id reporting `'lost'` rather than releasing it — there is no
+  // `Connection` to hand back for a caller to close, and the aggregate is what puts
+  // `SocketReloadDialog` up. It is released by `revive` above, on the next `retry()`.
+  await ready
+  opened = true
+
+  return connection
+}
+
+/**
+ * Open a socket with no declared entrypoint behind it — the primitive `ws()` builds on, and what
+ * a test drives directly against a bare WebSocket server.
+ */
+export const connect = async (
+  address: () => Promise<string> | string, ctx: Context, options?: ConnectOptions
+): Promise<Connection> => {
+  const { policy, retry } = resolvePolicy(ctx, options)
+  return await establish(ctx, policy, retry, async () => openRawSocket(await address()))
+}
+
+/**
+ * Open a socket through a declared entrypoint protocol, restoring it on its own after a network
+ * failure — see the client-socket skill's "Disconnects" section for the full policy. Resolves
+ * once the first attempt opens; rejects with `SocketConnectionError('lost')` if the retry budget
+ * elapses before that ever happens (or the single attempt fails, with `reconnect: false`).
+ */
+export const ws = async (
+  module: ClientEntrypoint<string>, request?: AbstractRequest<{ token?: string }>, options?: WsOptions
+): Promise<Connection> => {
+  const ctx = assertContext<Config, Context>(module.ctx as Context, 'client-ws')
+  request = request ?? provideRequest(module.alias, module.path())
+  const { policy, retry } = resolvePolicy(ctx, options)
+
+  return await establish(ctx, policy, retry, async () => {
+    await options?.beforeConnect?.(request!)
+    const url = await entrypointUrl({ ref: module }, request)
+    return await openRawSocket(url)
   })
 }
 
-export const useWs = (module: string | ClientEntrypoint<any>, request?: Partial<AbstractRequest<any>>): Connection | null => {
+/**
+ * Open a socket through a declared entrypoint protocol.
+ *
+ * String aliases remain an adapter input for dynamically addressed integrations, while
+ * application callers pass their immutable protocol declaration and receive its bound client
+ * entrypoint here at the transport boundary.
+ *
+ * Re-opens on its own after a network drop (see `ws()`). `null` until the first attempt opens,
+ * and again once the retry budget elapses without one ever opening — dialed afresh on the next
+ * `SocketStatusService.retry()`. A screen that must tell those two apart reads
+ * `useSocketStatus()` (from `./status.js`) alongside this.
+ */
+export const useWs = (
+  module: EntrypointReference | string, request?: Partial<AbstractRequest<any>>, options?: WsOptions
+): Connection | null => {
   const ctx = useContext()
   const mod = useMemo(
-    () => typeof module === 'string' ? ctx.entrypoint<ClientEntrypoint>(module) : module,
+    () => ctx.entrypoint<ClientEntrypoint>(module),
     [module]
   )
-  const connection = useValue<Connection>(async () => {
-    const _request = provideRequest(mod.getAlias(), mod.getPath())
+  const [failed, setFailed] = useState(false)
+  const [dial, setDial] = useState(0)
+  const connection = useValue<Connection | null>(async (cancel) => {
+    const _request = provideRequest(mod.alias, mod.path())
     Object.assign(_request, request)
-    return await ws(mod, _request)
+    try {
+      const conn = await ws(mod, _request, options)
+      if (cancel?.current) {
+        // The component unmounted while the handshake (or its retries) were still in flight —
+        // there is no `useEffect` cleanup coming for this value, so close it here instead of
+        // leaving a live socket and its retry timers attached to nothing.
+        void conn.close()
+        return null
+      }
+      return conn
+    } catch {
+      if (!cancel?.current) setFailed(true)
+      return null
+    }
   }, [
-    mod.getAlias(),
+    mod.alias,
     request?.query?.[AUTH_QUERY],
-    request?.params ? JSON.stringify(request.params) : undefined
+    request?.params ? JSON.stringify(request.params) : undefined,
+    dial
   ])
 
+  useEffect(() => {
+    if (!failed || !ctx.hasService(SOCKET_STATUS)) return
+    return (ctx as unknown as SocketStatusServiceAppend).socketStatus().onRetry(() => {
+      setFailed(false)
+      setDial(n => n + 1)
+    })
+  }, [failed])
+
   useEffect(() => {
     if (connection != null) {
       return () => {

package/src/index.ts

@@ -1,3 +1,5 @@
 
 export type * from './types.js'
+export * from './consts.js'
 export * from './helper.js'
+export * from './status.js'

package/src/status.ts

@@ -0,0 +1,164 @@
+import { createService } from '@owlmeans/context'
+import { useContext } from '@owlmeans/client'
+import { useCallback, useEffect, useState } from 'react'
+import type {
+  Config, Context, SocketConnectionState, SocketStatusService, SocketStatusServiceAppend
+} from './types.js'
+
+export const SOCKET_STATUS = 'socket-status'
+
+const RANK: Record<SocketConnectionState, number> = { online: 0, reconnecting: 1, lost: 2 }
+
+/**
+ * Aggregates the coarse health of every `ws()`/`useWs()` connection an app has open into one
+ * worst-of-all state. A page with several sockets (thinking stream, file watch, notifications…)
+ * still shows one dialog, not one per socket — so the aggregate, not any single connection, is
+ * what a UI like `SocketReloadDialog` reads.
+ */
+export const createSocketStatusService = (alias: string = SOCKET_STATUS): SocketStatusService => {
+  const states = new Map<string, SocketConnectionState>()
+  const revivers = new Map<string, () => void>()
+  const listeners = new Set<(state: SocketConnectionState) => void>()
+  const retryListeners = new Set<() => void>()
+  let current: SocketConnectionState = 'online'
+
+  const recompute = () => {
+    let worst: SocketConnectionState = 'online'
+    for (const state of states.values()) {
+      if (RANK[state] > RANK[worst]) worst = state
+    }
+    if (worst !== current) {
+      current = worst
+      listeners.forEach(listener => listener(current))
+    }
+  }
+
+  // Connections still retrying are nudged too, so one whose older budget is about to run out does
+  // not report `'lost'` right after its lost siblings were revived.
+  const retry = (): boolean => {
+    const pending = [...states].filter(([, state]) => state !== 'online')
+    pending.forEach(([id]) => revivers.get(id)?.())
+    if (!pending.some(([, state]) => state === 'lost')) return false
+    retryListeners.forEach(listener => listener())
+    return true
+  }
+
+  // A backgrounded tab is where sockets die unnoticed (throttled timers, a sleeping machine), so
+  // the moment it is looked at again is the moment to retry — before anyone reaches for a button.
+  const watchActivation = () => {
+    if (typeof document === 'undefined' || typeof window === 'undefined') return
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'visible') retry()
+    })
+    window.addEventListener('focus', () => { retry() })
+    window.addEventListener('online', () => { retry() })
+  }
+
+  return createService<SocketStatusService>(alias, {
+    report: (id, state, revive) => {
+      states.set(id, state)
+      if (revive != null) revivers.set(id, revive)
+      else revivers.delete(id)
+      recompute()
+    },
+    release: (id) => { states.delete(id); revivers.delete(id); recompute() },
+    state: () => current,
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    retry,
+    onRetry: listener => {
+      retryListeners.add(listener)
+      return () => { retryListeners.delete(listener) }
+    },
+  }, service => async () => {
+    watchActivation()
+    service.initialized = true
+  })
+}
+
+/**
+ * Register the shared socket-status aggregator. Idempotent, and cheap enough for a host package
+ * (`@owlmeans/web-panel`) to call unconditionally on every context: every `ws()`/`useWs()`
+ * connection reports itself here if — and only if — the context carries this service, so an app
+ * that never calls this behaves exactly as it did before reconnect support existed.
+ */
+export const appendSocketStatus = <C extends Config = Config, T extends Context<C> = Context<C>>(
+  ctx: T, alias: string = SOCKET_STATUS
+): T & SocketStatusServiceAppend => {
+  const _ctx = ctx as T & SocketStatusServiceAppend
+  if (!ctx.hasService(alias)) {
+    ctx.registerService(createSocketStatusService(alias))
+  }
+  _ctx.socketStatus = () => ctx.service(alias)
+  return _ctx
+}
+
+const readSocketStatusService = (
+  ctx: Context & Partial<SocketStatusServiceAppend>
+): SocketStatusService | null => {
+  try {
+    return typeof ctx.hasService === 'function' && ctx.hasService(SOCKET_STATUS)
+      ? ctx.socketStatus?.() ?? null : null
+  } catch {
+    // Registered but not yet run through the context's OWN `init()` — a component that renders
+    // as a sibling of the router (as `SocketReloadDialog` does) mounts before that finishes,
+    // since `context.configure().init()` runs from the router's effect, not before React's
+    // first commit. Treat it as "not ready yet" rather than crash the render.
+    return null
+  }
+}
+
+/** The status service once the context can hand it out; `null` while it cannot, or never will. */
+const useStatusService = (): SocketStatusService | null => {
+  const ctx = useContext() as unknown as Context & Partial<SocketStatusServiceAppend>
+  const [service, setService] = useState<SocketStatusService | null>(() => readSocketStatusService(ctx))
+
+  useEffect(() => {
+    if (service != null) return
+    let cancelled = false
+    void ctx.waitForInitialized?.().then(() => { if (!cancelled) setService(readSocketStatusService(ctx)) })
+    return () => { cancelled = true }
+  }, [ctx, service])
+
+  return service
+}
+
+/**
+ * The worst state across every live `ws()`/`useWs()` connection, or `'online'` if the app never
+ * registered the status service (`appendSocketStatus`) or has not finished initializing yet.
+ */
+export const useSocketStatus = (): SocketConnectionState => {
+  const service = useStatusService()
+  const [state, setState] = useState<SocketConnectionState>(() => service?.state() ?? 'online')
+
+  useEffect(() => {
+    if (service == null) return
+    setState(service.state())
+    return service.subscribe(setState)
+  }, [service])
+
+  return state
+}
+
+/**
+ * `retry` revives every lost connection now (`SocketStatusService.retry()`); `retrying` is true
+ * from any retry — this one, or the service's own on tab activation — until the aggregate settles
+ * back on `'online'` or `'lost'`.
+ */
+export const useSocketRetry = (): { retry: () => void, retrying: boolean } => {
+  const service = useStatusService()
+  const [retrying, setRetrying] = useState(false)
+
+  useEffect(() => {
+    if (service == null) return
+    const stopRetry = service.onRetry(() => setRetrying(service.state() === 'reconnecting'))
+    const stopState = service.subscribe(state => { if (state !== 'reconnecting') setRetrying(false) })
+    return () => { stopRetry(); stopState() }
+  }, [service])
+
+  const retry = useCallback(() => { service?.retry() }, [service])
+
+  return { retry, retrying }
+}

package/src/types.ts

@@ -1,7 +1,90 @@
 
 import type { ClientConfig } from '@owlmeans/client-context'
 import type { ClientContext } from '@owlmeans/client'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { InitializedService } from '@owlmeans/context'
 
-export interface Config extends ClientConfig { }
+export interface Config extends ClientConfig {
+  socket?: SocketClientSettings
+}
 
 export interface Context<C extends Config = Config> extends ClientContext<C> { }
+
+/**
+ * How aggressively a dropped socket is retried, and when the carrier gives up on it.
+ *
+ * The delay grows geometrically from `minDelay` to `maxDelay` (±`jitter`, a fraction of the
+ * computed delay) and stays there. `budget` is measured from the connection's FIRST failed
+ * attempt in an outage — a socket that opens and drops again right away does not get a fresh
+ * budget — and `stableAfter` is how long a reopened socket must stay up before the attempt
+ * counter and the outage clock reset, so a flapping link is never read as "recovered" between
+ * two drops a second apart.
+ */
+export interface ReconnectPolicy {
+  /** First retry delay, in ms. Default 200. */
+  minDelay: number
+  /** Delay ceiling, in ms — the backoff never grows past this. Default 3000. */
+  maxDelay: number
+  /** Geometric growth factor applied to the delay after every failed attempt. Default 2. */
+  factor: number
+  /** Randomization applied to each computed delay, as a fraction of it. Default 0.1 (±10%). */
+  jitter: number
+  /** Total time, in ms, the carrier keeps retrying before it reports the socket lost. Default
+   *  600000 (10 minutes). */
+  budget: number
+  /** Retry window, in ms, of an outage restarted on a lost socket by `SocketStatusService.retry()`
+   *  (a "Try again" press, the tab coming back) — short, so a retry that cannot succeed reports
+   *  `'lost'` again while someone is still looking. Default 15000. */
+  reviveBudget: number
+  /** How long a reopened socket must stay open before the attempt count and the outage clock
+   *  reset, in ms. Default 10000. */
+  stableAfter: number
+  /** Heartbeat ping interval, in ms. Default 30000. */
+  heartbeat: number
+  /** How long to wait for ANY inbound frame after a ping before treating the socket as dead and
+   *  forcing it closed, in ms. Default 10000. */
+  pongTimeout: number
+}
+
+export interface SocketClientSettings {
+  /** `false` disables reconnection outright — a dropped socket is reported gone and stays gone,
+   *  the pre-reconnect-support behaviour. Anything else merges over the defaults. */
+  reconnect?: false | Partial<ReconnectPolicy>
+}
+
+export interface ConnectOptions {
+  reconnect?: false | Partial<ReconnectPolicy>
+}
+
+export interface WsOptions extends ConnectOptions {
+  /**
+   * Run before every connection attempt, the first one included, given the request that will be
+   * turned into the socket URL — where a caller refreshes a token or other query/param value
+   * that may have changed since the previous attempt.
+   */
+  beforeConnect?: (request: AbstractRequest<any>) => void | Promise<void>
+}
+
+/** The coarse health of a socket connection — the worst of everything a status service tracks. */
+export type SocketConnectionState = 'online' | 'reconnecting' | 'lost'
+
+export interface SocketStatusService extends InitializedService {
+  /** Record this connection's current state under `id` — call again to update it. `revive` is
+   *  how `retry()` brings it back (`'lost'`) or hurries it (`'reconnecting'`); every report
+   *  replaces the previous one. */
+  report: (id: string, state: SocketConnectionState, revive?: () => void) => void
+  /** Stop tracking `id` (the connection closed on purpose). */
+  release: (id: string) => void
+  /** The worst state across every tracked connection; `'online'` when none are tracked. */
+  state: () => SocketConnectionState
+  subscribe: (listener: (state: SocketConnectionState) => void) => () => void
+  /** Revive every `'lost'` connection and hurry every `'reconnecting'` one, then tell `onRetry`
+   *  listeners. `false` (and no listener call) when nothing was lost. Also fires by itself when a
+   *  browser tab becomes visible, its window gains focus, or the network comes back online. */
+  retry: () => boolean
+  onRetry: (listener: () => void) => () => void
+}
+
+export interface SocketStatusServiceAppend {
+  socketStatus: () => SocketStatusService
+}