redweb-client 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# redweb-client
+
+Browser-first WebSocket client for [Redweb](https://redweb.magnisolution.com/). It adds connection lifecycle, typed message subscriptions, request correlation, bounded queuing, opt-in reconnection, and exact Redweb 0.9 protocol envelopes without adding runtime dependencies.
+
+## Install
+
+```bash
+npm install redweb-client
+```
+
+The package ships ESM, CommonJS, and TypeScript declarations. It targets modern browsers with `WebSocket`, `URL`, `AbortController`, and `Blob`; Node 18+ is supported when a WebSocket implementation is supplied through `webSocketFactory`.
+
+## Quick start
+
+Redweb server:
+
+```js
+const { BaseHandler, HttpServer, SocketRoute, SocketServer } = require('redweb')
+
+class ChatHandler extends BaseHandler {
+  constructor() { super('chat') }
+
+  onMessage(socket, message) {
+    socket.broadcast({ type: 'chat:message', text: message.text })
+  }
+}
+
+class ChatRoute extends SocketRoute {
+  constructor() {
+    super({
+      path: '/chat',
+      handlers: [ChatHandler],
+      allowDuplicateConnections: true,
+      websocketOptions: { maxPayload: 64 * 1024 },
+    })
+  }
+}
+
+const http = new HttpServer({ listen: false, publicPaths: ['./public'] })
+const sockets = new SocketServer({ server: http.server, routes: [ChatRoute] })
+http.server.listen(3030)
+```
+
+Browser:
+
+```ts
+import { RedwebClient } from 'redweb-client'
+
+const client = new RedwebClient('/chat', {
+  baseUrl: window.location.href,
+})
+
+client.on('chat:message', message => {
+  console.log(message.text)
+})
+
+client.onError(error => console.error(error))
+
+await client.connect()
+client.send('chat', { text: 'Hello' })
+```
+
+Relative paths use `window.location` automatically in browsers. `http:` and `https:` bases are converted to `ws:` and `wss:`.
+
+## Versioned Redweb protocol
+
+Enable the same finite version on the Redweb route and client:
+
+```js
+// Server route
+super({
+  path: '/match',
+  handlers: [MoveHandler],
+  protocol: { versions: ['2', '1'] },
+})
+```
+
+```ts
+// Browser client
+const client = new RedwebClient('wss://game.example/match', { version: '2' })
+await client.connect()
+
+const response = await client.request(
+  'move',
+  { x: 4, y: 2 },
+  { requestId: crypto.randomUUID(), sequence: 17 },
+)
+```
+
+The client adds `?redwebVersion=2` when needed. If the URL already contains `redwebVersion`, the client infers that version when `version` is omitted and rejects a conflicting configured value. Browsers cannot provide Redweb's alternative `x-redweb-version` handshake header or inspect the `426` response headers; unsupported versions therefore appear as an ordinary WebSocket connection failure.
+
+Protocol sends use the exact shape:
+
+```ts
+{ v, type, payload, requestId?, sequence? }
+```
+
+Framework error responses reject a correlated `request()` with `RedwebProtocolError`, while still being delivered to `on('error', ...)` and `onAny(...)` subscribers.
+
+```ts
+import { ERROR_CODES, RedwebProtocolError } from 'redweb-client'
+
+try {
+  await client.request('move', { x: 4, y: 2 })
+} catch (error) {
+  if (error instanceof RedwebProtocolError && error.code === ERROR_CODES.RATE_LIMITED) {
+    // Back off; do not automatically replay application commands.
+  }
+}
+```
+
+## Legacy routes
+
+Without `version`, object payload properties stay at the top level because legacy Redweb handlers commonly read `message.text`, `message.action`, and similar fields:
+
+```ts
+client.send('chat', { text: 'Hello' })
+// { type: 'chat', text: 'Hello' }
+```
+
+Scalar and array payloads use `{ type, payload }`. Legacy framework failures such as `{ error: 'Handler failed' }` are observable with `on('error', ...)`; they generally cannot be correlated because Redweb's legacy error shape does not carry `requestId`.
+
+## Typed event maps
+
+```ts
+interface Incoming {
+  'player:moved': { playerId: string; x: number; y: number }
+}
+
+interface Outgoing {
+  move: { x: number; y: number }
+}
+
+const client = new RedwebClient<Incoming, Outgoing>('/match')
+client.send('move', { x: 4, y: 2 })
+client.on('player:moved', message => console.log(message))
+```
+
+TypeScript improves application ergonomics; it does not validate arbitrary application payloads at runtime. Validate untrusted payloads in your application.
+
+## Lifecycle and sending
+
+- `connect()` is idempotent while connecting or open and resolves after the socket opens.
+- `close(code?, reason?)` suppresses reconnection, rejects pending requests, and discards unsent queued data.
+- `dispose()` closes once, clears subscriptions and queued messages, and permanently prevents reuse.
+- `send(type, payload, metadata?)` builds a legacy or protocol message.
+- `sendRaw(data)` sends text or binary data without encoding it.
+- Sends while disconnected throw by default. Set a finite `maxQueueSize` to queue a bounded number of messages until the next open. A queued request is removed if it times out, is aborted, or is rejected by `close()`; a command cannot execute later after its caller has been told it was cancelled.
+- `request()` correlates a response by `requestId`; `waitFor()` waits for a message type. Both support deadlines and `AbortSignal`.
+
+Queued messages are never replayed after they have been sent. Redweb does not provide exactly-once delivery, durable state, or automatic application acknowledgements; `requestId` is correlation and `sequence` is application ordering only.
+
+## Reconnection
+
+Reconnection is disabled by default:
+
+```ts
+const client = new RedwebClient('/match', {
+  reconnect: {
+    enabled: true,
+    maxAttempts: 8,
+    initialDelayMs: 250,
+    maxDelayMs: 10_000,
+    factor: 2,
+    jitter: 0.2,
+    shouldReconnect: event => event.code !== 1000 && event.code !== 1008,
+  },
+})
+```
+
+The default retry policy avoids normal closure (`1000`) and policy violations (`1008`). Manual `close()` and `dispose()` always cancel retries. Customize `shouldReconnect` for deployment shutdown (`1001`), handler failure (`1011`), capacity/backpressure (`1013`), or network-loss behavior. Reconnection never automatically resends application messages or resumes Redweb sessions; session IDs and resume commands belong to the application protocol.
+
+## Binary messages and heartbeat
+
+The client requests `arraybuffer` delivery and passes incoming `ArrayBuffer`, typed-array, or `Blob` values to `onBinary()`. Redweb's protocol binary codec is application-defined, so this package does not guess how to decode it. Use `sendRaw()` and your codec around `onBinary()`.
+
+Browser ping/pong handling is automatic and inaccessible to JavaScript. Redweb's route-level heartbeat operates at the WebSocket protocol layer; no application heartbeat is required here.
+
+## Authentication and security
+
+Browser WebSockets cannot set arbitrary request headers. Use secure, same-site cookies or a short-lived query credential accepted by your Redweb admission hook. Avoid persistent credentials and never put long-lived tokens in URLs, logs, or reconnect configuration. Origin validation, authentication, placement, capacity, and authorization remain server responsibilities.
+
+## Development and verification
+
+```bash
+npm run check
+```
+
+The clean-worktree gate builds first, resolves the public declarations through the package export map, then runs unit tests plus mock-free integration tests against a real local Redweb HTTP/WebSocket server. Coverage is enforced at 100% for statements, branches, functions, and lines.