@owlmeans/socket 0.1.18-rc.1 → 0.1.18-rc.11

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.8
 ```
 
 ## 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.14
 ```
 
 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.11",
+  "generatedAt": "2026-09-10T23:12:07.511Z",
   "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,108 @@ user-invocable: false
 # @owlmeans/socket
 
 **Layer:** Core
-**Install:** `"@owlmeans/socket": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/socket": "^0.1.18-rc.11"` 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 |
+| `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
 
-## Usage
+Pick by who is expected to answer and how often — they are separate registries, and a handler
+bound to one never sees the others.
+
+| 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. Nothing else reports a disconnect, so any subscription a
+handler opened is released there.
+
+## 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 `handleConnection`

package/package.json

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