@owlmeans/client-socket 0.1.18-rc.5 → 0.1.18-rc.50

package/src/helper.ts

@@ -1,68 +1,110 @@
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { type ClientEntrypoint, clientRequestHelper } 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 { type Connection, SocketConnectionError } from '@owlmeans/socket'
 import { makeConnection } from './utils/connection.js'
 import { assertContext } from '@owlmeans/context'
-import type { Config, Context } 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 type { Config, Context, ConnectOptions, ReconnectPolicy, SocketStatusServiceAppend, WsOptions } from './types.js'
+import type { SocketClientHelper } from './helper/types.js'
+import { makeApiCallHelper } from '@owlmeans/client-entrypoint/utils'
+import { createIdOfLength } from '@owlmeans/basic-ids'
+import { DEFAULT_RECONNECT_POLICY, SOCKET_STATUS } from './consts.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)
+export const createSocketClientHelper = (): SocketClientHelper => {
+  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)
+    })
   }
-  const socket = new WebSocket(url)
 
-  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
 
-      resolve(makeConnection(socket, ctx))
+    const baseClose = connection.close
+    connection.close = async () => {
+      await baseClose()
+      status?.release(statusId)
     }
-  })
-}
 
-export const useWs = (module: string | ClientEntrypoint<any>, request?: Partial<AbstractRequest<any>>): Connection | null => {
-  const ctx = useContext()
-  const mod = useMemo(
-    () => typeof module === 'string' ? ctx.entrypoint<ClientEntrypoint>(module) : module,
-    [module]
-  )
-  const connection = useValue<Connection>(async () => {
-    const _request = provideRequest(mod.getAlias(), mod.getPath())
-    Object.assign(_request, request)
-    return await ws(mod, _request)
-  }, [
-    mod.getAlias(),
-    request?.query?.[AUTH_QUERY],
-    request?.params ? JSON.stringify(request.params) : undefined
-  ])
-
-  useEffect(() => {
-    if (connection != null) {
-      return () => {
-        void connection.close()
+    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)
     }
-  }, [connection])
 
-  return connection
+    // 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
+  }
+
+  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()))
+  }
+
+  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 ?? clientRequestHelper.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 makeApiCallHelper({ ref: module }).entrypointUrl(request)
+      return await openRawSocket(url)
+    })
+  }
+
+  return { connect, ws }
 }
+
+export const socketClientHelper = createSocketClientHelper()
+
+/** @deprecated compat:factory-refactor — use `socketClientHelper.ws(…)` */
+export const ws = (
+  module: ClientEntrypoint<string>, request?: AbstractRequest<{ token?: string }>, options?: WsOptions
+): Promise<Connection> => socketClientHelper.ws(module, request, options)

package/src/hooks.ts

@@ -0,0 +1,75 @@
+import { type ClientEntrypoint, clientRequestHelper } from '@owlmeans/client-entrypoint'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { Connection } from '@owlmeans/socket'
+import type { EntrypointReference } from '@owlmeans/context'
+import type { SocketStatusServiceAppend, WsOptions } from './types.js'
+import { useContext, useValue } from '@owlmeans/client'
+import { AUTH_QUERY } from '@owlmeans/auth'
+import { useEffect, useMemo, useState } from 'react'
+import { SOCKET_STATUS } from './consts.js'
+import { socketClientHelper } from './helper.js'
+
+/**
+ * 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(
+    () => ctx.entrypoint<ClientEntrypoint>(module),
+    [module]
+  )
+  const [failed, setFailed] = useState(false)
+  const [dial, setDial] = useState(0)
+  const connection = useValue<Connection | null>(async (cancel) => {
+    const _request = clientRequestHelper.provideRequest(mod.alias, mod.path())
+    Object.assign(_request, request)
+    try {
+      const conn = await socketClientHelper.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.alias,
+    request?.query?.[AUTH_QUERY],
+    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 () => {
+        void connection.close()
+      }
+    }
+  }, [connection])
+
+  return connection
+}

package/src/index.ts

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

package/src/status.ts

@@ -0,0 +1,162 @@
+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'
+import { RANK } from './consts.local.js'
+import { SOCKET_STATUS } from './consts.js'
+
+/**
+ * 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
+}