@owlmeans/client-socket 0.1.18-rc.3 → 0.1.18-rc.30

package/src/helper.ts

@@ -1,57 +1,141 @@
 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 { entrypointUrl } from '@owlmeans/client-entrypoint/utils'
 import { useEffect, useMemo } 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)
-      })
+  const { connection, ready } = makeConnection({
+    policy, retry, open, onStatus: state => status?.report(statusId, state)
+  })
 
-      resolve(makeConnection(socket, ctx))
-    }
+  const baseClose = connection.close
+  connection.close = async () => {
+    await baseClose()
+    status?.release(statusId)
+  }
+
+  // A rejection here means `finish()` already ran and reported this id's terminal state —
+  // `'lost'` in every case, since the budget-exhausted path is the only one that rejects
+  // `ready`. Deliberately NOT released: there is no `Connection` to hand back for a caller to
+  // close, so the aggregate stays `'lost'` — the whole reason `SocketReloadDialog` exists — until
+  // the page reloads. Only a connection this function actually returns can be released, and only
+  // by the caller closing it on purpose.
+  await ready
+
+  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 — 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 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 {
+      return null
+    }
   }, [
-    mod.getAlias(),
+    mod.alias,
     request?.query?.[AUTH_QUERY],
     request?.params ? JSON.stringify(request.params) : undefined
   ])

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,108 @@
+import { createService } from '@owlmeans/context'
+import { useContext } from '@owlmeans/client'
+import { 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 listeners = new Set<(state: SocketConnectionState) => 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))
+    }
+  }
+
+  return createService<SocketStatusService>(alias, {
+    report: (id, state) => { states.set(id, state); recompute() },
+    release: (id) => { states.delete(id); recompute() },
+    state: () => current,
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+  }, service => async () => { 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 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 ctx = useContext() as unknown as Context & Partial<SocketStatusServiceAppend>
+  const [state, setState] = useState<SocketConnectionState>(() => readSocketStatusService(ctx)?.state() ?? 'online')
+
+  useEffect(() => {
+    let cancelled = false
+    let unsubscribe: (() => void) | null = null
+
+    const attach = (): boolean => {
+      const service = readSocketStatusService(ctx)
+      if (service == null) return false
+      setState(service.state())
+      unsubscribe = service.subscribe(next => { if (!cancelled) setState(next) })
+      return true
+    }
+
+    if (!attach()) {
+      void ctx.waitForInitialized?.().then(() => { if (!cancelled) attach() })
+    }
+
+    return () => {
+      cancelled = true
+      unsubscribe?.()
+    }
+  }, [ctx])
+
+  return state
+}

package/src/types.ts

@@ -1,7 +1,79 @@
 
 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
+  /** 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. */
+  report: (id: string, state: SocketConnectionState) => 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
+}
+
+export interface SocketStatusServiceAppend {
+  socketStatus: () => SocketStatusService
+}

package/src/utils/connection.ts

@@ -1,26 +1,226 @@
-import type { Config, Context } from '../types.js'
 import type { Connection, EventMessage as EMessage } from '@owlmeans/socket'
-import { createBasicConnection, MessageType } from '@owlmeans/socket'
+import {
+  createBasicConnection, MessageType, SocketConnectionError, SocketSystemEvent,
+  SOCKET_HEARTBEAT_TIMEOUT_CODE
+} from '@owlmeans/socket'
+import { AuthenticationStage } from '@owlmeans/auth'
+import type { ReconnectPolicy, SocketConnectionState } from '../types.js'
 
-export const makeConnection = <C extends Config = Config, T extends Context<C> = Context<C>>(
-  conn: WebSocket, _context: T
-): Connection => {
+/** Close codes that mean "this connection is finished on purpose" — never worth retrying: a
+ *  normal closure the SERVER initiated (1000, e.g. the protocol's own one-shot completion) and a
+ *  policy violation (1008, e.g. the guard rejected the frame that opened it). A client-initiated
+ *  close is handled separately, through `closedByClient`. */
+const TERMINAL_CLOSE_CODES: ReadonlySet<number> = new Set([1000, 1008])
+
+export interface ConnectionOpener {
+  (): Promise<WebSocket>
+}
+
+export interface ManagedConnectionOptions {
+  policy: ReconnectPolicy
+  /** Whether a drop schedules a retry at all. `false` keeps the pre-reconnect-support
+   *  behaviour — one attempt, report and stop — while the heartbeat/liveness check below still
+   *  runs exactly as it always did. */
+  retry: boolean
+  /** Opens a fresh socket for the first attempt and every retry — already reflecting whatever a
+   *  caller's `beforeConnect` refreshed (a token, most often). Resolves once the socket is OPEN,
+   *  rejects on a handshake failure. */
+  open: ConnectionOpener
+  /** Told this connection's coarse health, if a caller wants to aggregate it — the status
+   *  service `@owlmeans/web-panel`'s reload dialog reads. */
+  onStatus?: (state: SocketConnectionState) => void
+}
+
+export interface ManagedConnection {
+  connection: Connection
+  /** Settles once the first socket opens; rejects with `SocketConnectionError('lost')` once the
+   *  retry budget elapses first (or the single attempt fails, with `retry: false`). */
+  ready: Promise<void>
+}
+
+/**
+ * Build a `Connection` whose transport survives a dropped WebSocket.
+ *
+ * The connection MODEL (`createBasicConnection()`) is created exactly once and never replaced —
+ * every `observe`/`listen` a caller registered keeps firing across a reconnect, because only the
+ * underlying `WebSocket` is swapped underneath it. A server's own subscriptions do NOT survive a
+ * new TCP connection, so a caller whose server sets up state only after an in-band
+ * `authenticated` frame (as this platform's handlers do) must replay that frame itself on
+ * `SocketSystemEvent.Reconnected` — this carrier only re-opens the pipe.
+ */
+export const makeConnection = (opts: ManagedConnectionOptions): ManagedConnection => {
+  const { policy, retry, open, onStatus } = opts
   const model = createBasicConnection()
 
-  model.send = async message => {
-    if (typeof message !== 'string') {
-      model.prepare?.(message)
+  let current: WebSocket | null = null
+  let closedByClient = false
+  let finished = false
+  let attempts = 0
+  let outageStartedAt: number | null = null
+  let stableTimer: ReturnType<typeof setTimeout> | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  let lastFrameAt = Date.now()
+
+  let resolveReady: () => void = () => void 0
+  let rejectReady: (error: Error) => void = () => void 0
+  const ready = new Promise<void>((resolve, reject) => { resolveReady = resolve; rejectReady = reject })
+  let settled = false
+
+  const settle = (error?: Error) => {
+    if (settled) return
+    settled = true
+    if (error != null) rejectReady(error)
+    else resolveReady()
+  }
+
+  const emitSystem = async <T,>(event: SocketSystemEvent, payload: T): Promise<void> => {
+    const msg: EMessage<T> = { type: MessageType.System, event, payload }
+    model.prepare?.(msg)
+    await Promise.all(model.getListeners().map(async listener => listener(msg)))
+  }
+
+  const clearHeartbeat = () => {
+    if (heartbeatTimer != null) { clearInterval(heartbeatTimer); heartbeatTimer = null }
+  }
+
+  const clearTimers = () => {
+    if (retryTimer != null) { clearTimeout(retryTimer); retryTimer = null }
+    if (stableTimer != null) { clearTimeout(stableTimer); stableTimer = null }
+    clearHeartbeat()
+  }
+
+  const startHeartbeat = (socket: WebSocket) => {
+    lastFrameAt = Date.now()
+    heartbeatTimer = setInterval(() => {
+      if (socket.readyState !== WebSocket.OPEN) return
+      if (Date.now() - lastFrameAt > policy.heartbeat + policy.pongTimeout) {
+        // Silent half-open TCP: nothing at all has arrived since well past a heartbeat interval
+        // plus its grace period — force the close this socket's own stack would eventually
+        // notice on its own, minutes later.
+        socket.close(SOCKET_HEARTBEAT_TIMEOUT_CODE)
+        return
+      }
+      socket.send(JSON.stringify({ type: 'ping' }))
+    }, policy.heartbeat)
+  }
+
+  const computeDelay = (attempt: number): number => {
+    const raw = Math.min(policy.maxDelay, policy.minDelay * Math.pow(policy.factor, attempt - 1))
+    const span = raw * policy.jitter
+    const jittered = raw + (Math.random() * 2 - 1) * span
+    return Math.max(policy.minDelay, Math.min(policy.maxDelay, Math.round(jittered)))
+  }
+
+  const finish = async (code: number) => {
+    if (finished) return
+    finished = true
+    closedByClient = true
+    clearTimers()
+    onStatus?.('lost')
+    await emitSystem(SocketSystemEvent.Close, { code })
+    settle(new SocketConnectionError('lost'))
+  }
+
+  const scheduleReconnect = (code: number) => {
+    if (outageStartedAt == null) outageStartedAt = Date.now()
+    if (Date.now() - outageStartedAt >= policy.budget) {
+      void (async () => {
+        onStatus?.('lost')
+        await emitSystem(SocketSystemEvent.Lost, {})
+        await finish(code)
+      })()
+      return
     }
-    if (conn.readyState === WebSocket.OPEN) {
-      conn.send(typeof message === 'string' ? message : JSON.stringify(message))
+    attempts += 1
+    const delay = computeDelay(attempts)
+    onStatus?.('reconnecting')
+    void emitSystem(SocketSystemEvent.Reconnecting, { attempt: attempts, delay })
+    retryTimer = setTimeout(() => { retryTimer = null; void attemptConnect() }, delay)
+  }
+
+  const attemptConnect = async () => {
+    if (closedByClient) return
+    try {
+      const socket = await open()
+      onOpened(socket)
+    } catch {
+      if (retry) scheduleReconnect(1006)
+      else void finish(1006)
+    }
+  }
+
+  const onOpened = (socket: WebSocket) => {
+    current = socket
+    const wasRetry = attempts > 0
+
+    const messageHandler = async (event: MessageEvent) => {
+      lastFrameAt = Date.now()
+      await model.receive(event.data)
+    }
+    const errorHandler = () => {
+      // The close event that always follows carries the code; nothing actionable here beyond
+      // keeping the browser's own unhandled-error reporting quiet for it.
+    }
+    const closeHandler = async (event: CloseEvent) => {
+      if (current !== socket) return
+      socket.removeEventListener('message', messageHandler)
+      socket.removeEventListener('close', closeHandler)
+      socket.removeEventListener('error', errorHandler)
+      clearHeartbeat()
+      current = null
+
+      if (closedByClient) {
+        await emitSystem(SocketSystemEvent.Close, { code: event.code })
+        return
+      }
+      if (!retry || TERMINAL_CLOSE_CODES.has(event.code)) {
+        await finish(event.code)
+        return
+      }
+
+      if (model._authSequence != null) {
+        model._authSequence.reject(new SocketConnectionError('disconnected'))
+        model._authSequence = undefined
+      }
+      model.stage = AuthenticationStage.Init
+      await emitSystem(SocketSystemEvent.Disconnected, { code: event.code })
+      scheduleReconnect(event.code)
+    }
+
+    socket.addEventListener('message', messageHandler)
+    socket.addEventListener('close', closeHandler)
+    socket.addEventListener('error', errorHandler)
+    startHeartbeat(socket)
+
+    if (stableTimer != null) clearTimeout(stableTimer)
+    stableTimer = setTimeout(() => { attempts = 0; outageStartedAt = null }, policy.stableAfter)
+
+    onStatus?.('online')
+    settle()
+    if (wasRetry) void emitSystem(SocketSystemEvent.Reconnected, { attempts })
+  }
+
+  model.send = async message => {
+    if (typeof message !== 'string') model.prepare?.(message)
+    if (current?.readyState === WebSocket.OPEN) {
+      current.send(typeof message === 'string' ? message : JSON.stringify(message))
     }
   }
 
   model.close = async () => {
-    if (conn.readyState === WebSocket.OPEN || conn.readyState === WebSocket.CONNECTING) {
-      conn.close()
+    if (finished) return
+    finished = true
+    closedByClient = true
+    clearTimers()
+    if (current != null && (current.readyState === WebSocket.OPEN || current.readyState === WebSocket.CONNECTING)) {
+      current.close(1000)
+    } else {
+      // No live socket to fire a close event from — mid-retry, or closed before the first open
+      // ever resolved — so report the same frame directly.
+      await emitSystem(SocketSystemEvent.Close, { code: 1000 })
     }
-    // @TODO Make sure it trigger close observers
+    settle(new SocketConnectionError('closed'))
   }
 
   model.authenticate = async (_stage, _payload) => {
@@ -34,24 +234,7 @@ export const makeConnection = <C extends Config = Config, T extends Context<C> =
     return message
   }
 
-  const messageHandler = async (message: MessageEvent) => {
-    await model.receive(message.data)
-  }
-  const closeHandler = async (event: CloseEvent) => {
-    const msg: EMessage<{ code: number }> = {
-      type: MessageType.System,
-      event: 'close',
-      payload: { code: event.code }
-    }
-    if (model.prepare != null) {
-      model.prepare(msg)
-    }
-    await Promise.all(model.getListeners().map(async listener => listener(msg)))
-    conn.removeEventListener('message', messageHandler)
-    conn.removeEventListener('close', closeHandler)
-  }
-  conn.addEventListener('message', messageHandler)
-  conn.addEventListener('close', closeHandler)
+  void attemptConnect()
 
-  return model
+  return { connection: model, ready }
 }

package/tests/context.ts

@@ -0,0 +1,20 @@
+import { config, makeClientContext } from '@owlmeans/client-context'
+import type { Config, Context } from '../src/types.js'
+
+/**
+ * A real, minimal client context — no mocking of the carrier or the transport, just enough
+ * config plumbing (`hasService`/`registerService`/`service`, `cfg.socket`) for `connect()` and
+ * `appendSocketStatus()` to work against.
+ *
+ * Left unconfigured: `hasService`/`registerService` work before `configure()`/`init()`, and
+ * `connect()` never calls `.service()` when nothing is registered — a test that DOES need a
+ * registered service's methods (`appendSocketStatus`'s `ctx.socketStatus()`) must register it
+ * and then run `ctx.configure(); await ctx.init()` itself, since a context only calls a
+ * service's own `init()` once, during that pass.
+ */
+export const makeTestContext = (socket?: Config['socket']): Context => {
+  const cfg = config<Config>('client-socket-tests')
+  cfg.socket = socket
+
+  return makeClientContext<Config, Context>(cfg)
+}