@owlmeans/socket 0.1.18-rc.2 → 0.1.18-rc.21

package/README.md

@@ -12,7 +12,7 @@ Shared WebSocket connection types and message protocol for OwlMeans real-time co
 ## Installation
 
 ```bash
-bun add @owlmeans/socket
+bun add @owlmeans/socket@^0.1.18-rc.20
 ```
 
 ## Usage
@@ -91,7 +91,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.24
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/socket",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.508Z",
+  "version": "0.1.18-rc.21",
+  "generatedAt": "2026-09-15T12:59:01.049Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/socket/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: socket
-description: How to use @owlmeans/socket — abstract WebSocket protocol model, message types, and socket errors shared between client-socket and server-socket. Auto-invoked when importing socket types or message constants.
+description: How to use @owlmeans/socket — the transport-agnostic Connection model shared by client-socket and server-socket, its message types (call/request/event/auth/system), the type guards, and the socket error classes. Auto-invoked when importing socket types, message constants or the connection model.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,29 +8,126 @@ user-invocable: false
 # @owlmeans/socket
 
 **Layer:** Core
-**Install:** `"@owlmeans/socket": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/socket": "^0.1.18-rc.21"` in `dependencies`
+
+Contracts and one implementation-free connection model. It knows nothing about WebSockets: the
+browser side is `@owlmeans/client-socket`, the Fastify side `@owlmeans/server-socket`, and each
+supplies the members the model leaves abstract — `send`, `close`, `authenticate` and `prepare` —
+that make it concrete. Both halves of an application therefore speak the same frames.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Message` types | Wire message shape (envelope, payload, headers) |
-| `SocketEvent` types | Socket lifecycle events |
-| Errors | Typed socket errors (Disconnected, AuthFailed, etc.) |
-| Constants | Message types, channel names |
-| Helpers | Encode/decode messages |
+| `createBasicConnection()` | The connection model — everything below the wire. A carrier assigns `send` / `close` / `authenticate` / `prepare` and feeds bytes to `receive` |
+| `Connection` | What a handler is handed: the messaging verbs, `stage`, `getListeners` |
+| `Message<T>` | The frame — `{ type, payload, id?, sender?, recipient?, dt?, rawData? }` |
+| `CallMessage<T>` / `EventMessage<T>` / `AuthMessage<T>` | The three frames that add a field: `method` + `timeout`, `event`, `stage` |
+| `MessageType` | `Call` `Result` `Error` `Request` `Response` `Event` `Message` `Auth` `System` |
+| `isMessage` / `isEventMessage` / `isCallMessage` / `isAuthMessage` | Type guards — `isMessage(msg, true)` excludes system frames, `isEventMessage(msg, true)` keeps only them |
+| `ConnectionListener` / `CallHendler` / `RequestHandler` / `CallResolver` | The callback shapes |
+| `SocketSystemEvent` | The `event` values a `MessageType.System` frame carries — see below |
+| `SOCKET_HEARTBEAT_TIMEOUT_CODE` | `4000` — the close code `client-socket`'s carrier uses when it force-closes a socket that has gone silent |
+| `SocketError` and subclasses | `SocketInitializationError`, `SocketConnectionError`, `SocketUnauthorized`, `SocketUnsupported`, `SocketTimeout`, `SocketMessageError`, `SocketMessageMalformed` — all registered with `ResilientError` |
+| `CALL_TIMEOUT` | 60 000 ms, the fallback when neither the message nor `connection.defaultCallTimeout` says |
+
+## The four ways to say something
+
+Pick by who is expected to answer and how often — they are separate registries, and a handler
+bound to one never sees the others.
 
-## Usage
+| Verb | Answered by | Shape |
+|---|---|---|
+| `notify(event, payload)` | `observe(event, handler)` | Fire-and-forget, fanned out to every observer of that event name |
+| `call(method, ...args)` | `perform(method, handler)` | One RPC, resolved with the handler's return value or rejected with its error |
+| `request(payload, observer?)` | `acknowledge(handler)`, answered with `reply(id, payload)` | An open question — acknowledgers run in turn until one takes it |
+| `enqueue(payload, id?)` | `consume(filter?)` | A mailbox the far side drains on its own schedule; `enqueued()` is its depth |
 
 ```typescript
-import type { Message } from '@owlmeans/socket'
+import { MessageType } from '@owlmeans/socket'
+import type { Connection, EventMessage } from '@owlmeans/socket'
+
+connection.observe<Progress>('job-event', async message => render(message.payload))
+await connection.notify('job-event', { id, progress: 0.5 })
+
+connection.perform<Report, [string]>('report', async id => await build(id))
+const report = await connection.call<Report, [string]>('report', id)
+```
+
+A `call` carries an id and a timeout, and the model arms the timer on both sides: the caller
+rejects with `SocketTimeout` when the answer does not arrive, and the performer stops sending one
+once it has elapsed. `timeout: 0` disables it. A performer that throws is answered with a
+`MessageType.Error` frame carrying the marshalled error, so the caller's `call` rejects with the
+original class rather than with a string.
+
+## Frames a listener sees
 
-const msg: Message = { type: 'subscribe', channel: 'projects', payload: { entityId } }
+`listen(listener)` receives EVERY inbound frame after the model has routed it — the escape hatch
+for what the verbs above do not cover. It also receives the frames a carrier synthesises, which is
+how a handler learns the connection is gone:
+
+```typescript
+connection.listen(async message => {
+  if (typeof message !== 'object') {
+    return
+  }
+  const msg = message as EventMessage<void>
+  if (msg.type === MessageType.System && msg.event === 'close') {
+    await cleanUp()
+  }
+})
 ```
 
-Concrete implementations live in `@owlmeans/client-socket` (browser/native) and `@owlmeans/server-socket` (Fastify integration).
+Both carriers emit exactly that frame — `MessageType.System`, `event: 'close'`, payload
+`{ code }` — when the socket closes for good. Nothing else reports a TERMINAL disconnect, so any
+subscription a handler opened is released there.
+
+**`SocketSystemEvent`** is the full vocabulary a `MessageType.System` frame's `event` can carry —
+`client-socket`'s reconnecting carrier is what emits the other four:
+
+| Event | Meaning |
+|---|---|
+| `close` | The connection is gone for good — see above |
+| `disconnected` | The socket dropped and a retry IS scheduled (client-socket only) — `{ code }` |
+| `reconnecting` | Before each retry attempt (client-socket only) — `{ attempt, delay }` |
+| `reconnected` | A retry succeeded, same `Connection` model (client-socket only) — `{ attempts }` |
+| `lost` | The retry budget elapsed with no success, immediately followed by `close` (client-socket only) |
+
+`close` is the only one of the five a plain carrier with no retry logic (like `server-socket`, or
+`client-socket` itself with `reconnect: false`) will ever emit — a listener written against `close`
+alone, before reconnect support existed, still sees exactly the frame it always did once a
+reconnecting carrier's retries give up.
+
+## What the model expects of a carrier
+
+- `receive(raw)` takes the raw string. It only parses text that starts with `{` or `[`; anything
+  else is dropped without reaching a listener. The carriers' own heartbeat IS JSON
+  (`{ type: 'ping' }`), so it is parsed: it matches no `MessageType` and routes nowhere, yet it
+  still reaches every `listen` listener — a listener has to recognise the frames it wants.
+- A frame with no `type` is read as `MessageType.Message` and a frame with no `payload` is treated
+  as its own payload, so a plain JSON body from a foreign client still arrives as a message.
+- `prepare(message, isRequest?)` is the carrier's hook for stamping a frame — timestamps,
+  `sender` / `recipient`. It runs on every outbound frame and on every inbound one.
+- `send`, `close` and `authenticate` throw `SyntaxError` until a carrier assigns them, so one that
+  forgets a member fails loudly rather than dropping frames. `prepare` is the exception: it is
+  optional on the interface and simply absent until assigned, and the model calls it defensively —
+  a carrier that omits it stamps nothing.
+
+## Authentication
+
+`auth(stage, payload)` sends an `AuthMessage` and waits. The far side's `authenticate` answers with
+the next stage and its payload, or throws — a rejection travels back as an `AuthMessage` with a
+null stage and is rebuilt by the initiator. `connection.stage` holds the current
+`AuthenticationStage` throughout. Only the server carrier implements a real sequence; see the
+`server-socket` skill.
 
 ## Depends On
 
-- `@owlmeans/error`, `@owlmeans/i18n`
-- `@owlmeans/basic-envelope` — message envelopes
+- `@owlmeans/error` — `ResilientError`, which every socket error registers with
+- `@owlmeans/auth` — `AuthenticationStage`, the vocabulary the auth frames carry
+- `@owlmeans/basic-ids` — `uuid` for call and request ids
+
+## Related
+
+- `client-socket` — the browser carrier and `useWs`
+- `server-socket` — the Fastify carrier, guard enforcement and `connection(protocol, callback)`

package/build/consts.d.ts

@@ -10,4 +10,26 @@ export declare enum MessageType {
     System = "system"
 }
 export declare const CALL_TIMEOUT = 60000;
+/**
+ * System frames a carrier synthesises around the lifecycle of the underlying transport.
+ *
+ * `Close` keeps its original meaning: the connection is gone for good — a client-initiated
+ * close, a terminal server code, or a reconnect budget exhausted. A drop the carrier intends to
+ * retry is reported as `Disconnected` instead, so a listener that only knew about `close` before
+ * this carried reconnect support still sees exactly the frame it always did once retries give up.
+ */
+export declare enum SocketSystemEvent {
+    Close = "close",
+    Disconnected = "disconnected",
+    Reconnecting = "reconnecting",
+    Reconnected = "reconnected",
+    Lost = "lost"
+}
+/**
+ * The close code a carrier uses when it drops a socket itself — a missed heartbeat pong within
+ * `pongTimeout`, catching a half-open TCP connection long before the OS would notice one.
+ * Reserved in the 4000–4999 private-use range so it is never confused with a code either
+ * endpoint's own WebSocket stack could produce.
+ */
+export declare const SOCKET_HEARTBEAT_TIMEOUT_CODE = 4000;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,eAAO,MAAM,YAAY,QAAQ,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,eAAO,MAAM,YAAY,QAAQ,CAAA;AAEjC;;;;;;;GAOG;AACH,oBAAY,iBAAiB;IAC3B,KAAK,UAAU;IACf,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,WAAW,gBAAgB;IAC3B,IAAI,SAAS;CACd;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAA"}

package/build/consts.js

@@ -11,4 +11,27 @@ export var MessageType;
     MessageType["System"] = "system";
 })(MessageType || (MessageType = {}));
 export const CALL_TIMEOUT = 60000;
+/**
+ * System frames a carrier synthesises around the lifecycle of the underlying transport.
+ *
+ * `Close` keeps its original meaning: the connection is gone for good — a client-initiated
+ * close, a terminal server code, or a reconnect budget exhausted. A drop the carrier intends to
+ * retry is reported as `Disconnected` instead, so a listener that only knew about `close` before
+ * this carried reconnect support still sees exactly the frame it always did once retries give up.
+ */
+export var SocketSystemEvent;
+(function (SocketSystemEvent) {
+    SocketSystemEvent["Close"] = "close";
+    SocketSystemEvent["Disconnected"] = "disconnected";
+    SocketSystemEvent["Reconnecting"] = "reconnecting";
+    SocketSystemEvent["Reconnected"] = "reconnected";
+    SocketSystemEvent["Lost"] = "lost";
+})(SocketSystemEvent || (SocketSystemEvent = {}));
+/**
+ * The close code a carrier uses when it drops a socket itself — a missed heartbeat pong within
+ * `pongTimeout`, catching a half-open TCP connection long before the OS would notice one.
+ * Reserved in the 4000–4999 private-use range so it is never confused with a code either
+ * endpoint's own WebSocket stack could produce.
+ */
+export const SOCKET_HEARTBEAT_TIMEOUT_CODE = 4000;
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,WAUX;AAVD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,gCAAiB,CAAA;IACjB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,oCAAqB,CAAA;IACrB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,gCAAiB,CAAA;AACnB,CAAC,EAVW,WAAW,KAAX,WAAW,QAUtB;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAN,IAAY,WAUX;AAVD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,gCAAiB,CAAA;IACjB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,oCAAqB,CAAA;IACrB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,gCAAiB,CAAA;AACnB,CAAC,EAVW,WAAW,KAAX,WAAW,QAUtB;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,iBAMX;AAND,WAAY,iBAAiB;IAC3B,oCAAe,CAAA;IACf,kDAA6B,CAAA;IAC7B,kDAA6B,CAAA;IAC7B,gDAA2B,CAAA;IAC3B,kCAAa,CAAA;AACf,CAAC,EANW,iBAAiB,KAAjB,iBAAiB,QAM5B;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/socket",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.21",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,9 +21,9 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.2",
-    "@owlmeans/basic-ids": "^0.1.18-rc.2",
-    "@owlmeans/error": "^0.1.18-rc.2"
+    "@owlmeans/auth": "^0.1.18-rc.21",
+    "@owlmeans/basic-ids": "^0.1.18-rc.21",
+    "@owlmeans/error": "^0.1.18-rc.20"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/consts.ts

@@ -12,3 +12,27 @@ export enum MessageType {
 }
 
 export const CALL_TIMEOUT = 60000
+
+/**
+ * System frames a carrier synthesises around the lifecycle of the underlying transport.
+ *
+ * `Close` keeps its original meaning: the connection is gone for good — a client-initiated
+ * close, a terminal server code, or a reconnect budget exhausted. A drop the carrier intends to
+ * retry is reported as `Disconnected` instead, so a listener that only knew about `close` before
+ * this carried reconnect support still sees exactly the frame it always did once retries give up.
+ */
+export enum SocketSystemEvent {
+  Close = 'close',
+  Disconnected = 'disconnected',
+  Reconnecting = 'reconnecting',
+  Reconnected = 'reconnected',
+  Lost = 'lost'
+}
+
+/**
+ * The close code a carrier uses when it drops a socket itself — a missed heartbeat pong within
+ * `pongTimeout`, catching a half-open TCP connection long before the OS would notice one.
+ * Reserved in the 4000–4999 private-use range so it is never confused with a code either
+ * endpoint's own WebSocket stack could produce.
+ */
+export const SOCKET_HEARTBEAT_TIMEOUT_CODE = 4000