@owlmeans/client-socket 0.1.18-rc.47 → 0.1.18-rc.49

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,5 +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

@@ -4,10 +4,8 @@ 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 }
+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

package/src/utils/connection.ts

@@ -1,51 +1,11 @@
-import type { Connection, EventMessage as EMessage } from '@owlmeans/socket'
-import {
-  createBasicConnection, MessageType, SocketConnectionError, SocketSystemEvent,
-  SOCKET_HEARTBEAT_TIMEOUT_CODE
-} from '@owlmeans/socket'
+import { type EventMessage as EMessage, createBasicConnection, MessageType, SocketConnectionError, SocketSystemEvent, SOCKET_HEARTBEAT_TIMEOUT_CODE } from '@owlmeans/socket'
 import { AuthenticationStage } from '@owlmeans/auth'
-import type { ReconnectPolicy, SocketConnectionState } from '../types.js'
 import { logger } from '@owlmeans/log'
+import { TERMINAL_CLOSE_CODES } from './consts.local.js'
+import type { ManagedConnection, ManagedConnectionOptions } from './types.js'
 
 const log = logger('client-socket')
 
-/** 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>
-  /** Restart retrying a connection that gave up after its budget: one attempt at once, then the
-   *  usual backoff within `policy.reviveBudget`. On a connection still waiting out a backoff
-   *  delay: attempt at once, and leave it at least `reviveBudget`. A no-op otherwise — a terminal
-   *  close (client close, 1000/1008, `retry: false`) is never revived. */
-  revive: () => void
-}
-
 /**
  * Build a `Connection` whose transport survives a dropped WebSocket.
  *

package/src/utils/consts.local.ts

@@ -0,0 +1,5 @@
+/** 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`. */
+export const TERMINAL_CLOSE_CODES: ReadonlySet<number> = new Set([1000, 1008])

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 
 export * from './connection.js'
+export type * from './types.js'

package/src/utils/types.ts

@@ -0,0 +1,33 @@
+import type { ReconnectPolicy, SocketConnectionState } from '../types.js'
+import type { Connection } from '@owlmeans/socket'
+
+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>
+  /** Restart retrying a connection that gave up after its budget: one attempt at once, then the
+   *  usual backoff within `policy.reviveBudget`. On a connection still waiting out a backoff
+   *  delay: attempt at once, and leave it at least `reviveBudget`. A no-op otherwise — a terminal
+   *  close (client close, 1000/1008, `retry: false`) is never revived. */
+  revive: () => void
+}

package/tests/reconnect.spec.ts

@@ -1,10 +1,10 @@
 import { afterEach, describe, expect, test } from 'bun:test'
 import type { Server } from 'bun'
-import { connect } from '../src/helper.js'
+import { socketClientHelper } from '../src/helper.js'
 import { makeConnection } from '../src/utils/connection.js'
 import { appendSocketStatus } from '../src/status.js'
 import { SocketSystemEvent } from '@owlmeans/socket'
-import type { EventMessage } from '@owlmeans/socket'
+import type { Connection, EventMessage } from '@owlmeans/socket'
 import { makeTestContext } from './context.js'
 
 /**
@@ -64,7 +64,7 @@ const waitFor = async (check: () => boolean, timeout: number, step = 20): Promis
   }
 }
 
-const systemEvents = (connection: Awaited<ReturnType<typeof connect>>): string[] => {
+const systemEvents = (connection: Connection): string[] => {
   const seen: string[] = []
   connection.listen(async message => {
     if (typeof message === 'object' && (message as EventMessage<unknown>).type === 'system') {
@@ -80,7 +80,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     const port = initial.port
 
     const ctx = makeTestContext({ reconnect: { minDelay: 50, maxDelay: 150, stableAfter: 200, budget: 30_000 } })
-    const connection = await connect(() => `ws://localhost:${port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${port}`, ctx)
     const events = systemEvents(connection)
 
     // Register an observer BEFORE the drop — it must still be the one that fires after the
@@ -143,7 +143,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     const port = initial.port
 
     const ctx = makeTestContext({ reconnect: { minDelay: 50, maxDelay: 150 } })
-    const connection = await connect(() => `ws://localhost:${port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${port}`, ctx)
     const events = systemEvents(connection)
 
     await connection.close()
@@ -160,7 +160,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     const ctx = makeTestContext({
       reconnect: { heartbeat: 60, pongTimeout: 30, minDelay: 20, maxDelay: 40, budget: 10_000 }
     })
-    const connection = await connect(() => `ws://localhost:${silent.port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${silent.port}`, ctx)
     const events = systemEvents(connection)
 
     await waitFor(() => events.includes(SocketSystemEvent.Disconnected), 3_000)
@@ -176,7 +176,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     const ctx = makeTestContext({
       reconnect: { heartbeat: 100, pongTimeout: 50, minDelay: 20, maxDelay: 40, budget: 10_000 }
     })
-    const connection = await connect(() => `ws://localhost:${port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${port}`, ctx)
     const events = systemEvents(connection)
     let observed = 0
     connection.observe('probe', async () => { observed += 1 })
@@ -213,7 +213,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     ctx.configure()
     await ctx.init()
 
-    await expect(connect(() => 'ws://127.0.0.1:1', ctx)).rejects.toBeTruthy()
+    await expect(socketClientHelper.connect(() => 'ws://127.0.0.1:1', ctx)).rejects.toBeTruthy()
 
     expect(ctx.socketStatus().state()).toBe('lost')
   }, 5_000)
@@ -229,7 +229,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     ctx.configure()
     await ctx.init()
 
-    const connection = await connect(() => `ws://localhost:${port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${port}`, ctx)
     const events = systemEvents(connection)
     let observed = 0
     connection.observe('probe', async () => { observed += 1 })
@@ -271,7 +271,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     ctx.configure()
     await ctx.init()
 
-    const connection = await connect(() => `ws://localhost:${port}`, ctx)
+    const connection = await socketClientHelper.connect(() => `ws://localhost:${port}`, ctx)
     const events = systemEvents(connection)
 
     stopServer()
@@ -358,7 +358,7 @@ describe('@owlmeans/client-socket — reconnect', () => {
     ctx.configure()
     await ctx.init()
 
-    await expect(connect(() => 'ws://127.0.0.1:1', ctx)).rejects.toBeTruthy()
+    await expect(socketClientHelper.connect(() => 'ws://127.0.0.1:1', ctx)).rejects.toBeTruthy()
     expect(ctx.socketStatus().state()).toBe('lost')
 
     let retried = 0