@owlmeans/socket 0.1.18-rc.17 → 0.1.18-rc.19

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@^0.1.18-rc.8
+bun add @owlmeans/socket@^0.1.18-rc.18
 ```
 
 ## 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@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.22
 ```
 
 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.17",
-  "generatedAt": "2026-09-12T14:21:25.465Z",
+  "version": "0.1.18-rc.19",
+  "generatedAt": "2026-09-15T12:38:52.490Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/socket
 
 **Layer:** Core
-**Install:** `"@owlmeans/socket": "^0.1.18-rc.17"` in `dependencies`
+**Install:** `"@owlmeans/socket": "^0.1.18-rc.19"` 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
@@ -26,6 +26,8 @@ that make it concrete. Both halves of an application therefore speak the same fr
 | `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 |
 
@@ -77,8 +79,24 @@ connection.listen(async message => {
 ```
 
 Both carriers emit exactly that frame — `MessageType.System`, `event: 'close'`, payload
-`{ code }` — when the socket closes. Nothing else reports a disconnect, so any subscription a
-handler opened is released there.
+`{ 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
 

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.17",
+  "version": "0.1.18-rc.19",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,9 +21,9 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.17",
-    "@owlmeans/basic-ids": "^0.1.18-rc.17",
-    "@owlmeans/error": "^0.1.18-rc.16"
+    "@owlmeans/auth": "^0.1.18-rc.19",
+    "@owlmeans/basic-ids": "^0.1.18-rc.19",
+    "@owlmeans/error": "^0.1.18-rc.18"
   },
   "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