@owlmeans/server-socket 0.1.18-rc.55 → 0.1.18-rc.56

package/README.md

@@ -11,7 +11,7 @@ in a queue (`@owlmeans/server-job`).
 ## Installation
 
 ```bash
-bun add @owlmeans/server-socket@^0.1.18-rc.55
+bun add @owlmeans/server-socket@^0.1.18-rc.56
 ```
 
 ## Concepts
@@ -210,7 +210,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.51
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 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/server-socket",
-  "version": "0.1.18-rc.55",
-  "generatedAt": "2026-10-06T11:45:57.676Z",
+  "version": "0.1.18-rc.56",
+  "generatedAt": "2026-10-08T21:27:54.312Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -6,7 +6,7 @@ description: Bind OwlMeans socket protocol declarations to Fastify WebSocket han
 
 # Socket protocol handlers
 
-**Install:** `bun add @owlmeans/server-socket@^0.1.18-rc.55`
+**Install:** `bun add @owlmeans/server-socket@^0.1.18-rc.56`
 
 Declare a socket route and its contract in the shared protocol package. Bind it on the server with
 `connection()` and `bind()`.
@@ -25,5 +25,41 @@ export const serverBindings = [
 ```
 
 The handler receives a typed connection, context, request and response boundary. Guards and gates
-are inherited from the protocol tree and enforced before the WebSocket handler runs. Do not expose
+are inherited from the protocol tree and enforced before the WebSocket handler runs: a refused
+guard or a closed gate answers the upgrade with an HTTP error and the handler is never reached. A
+guard that admits the upgrade authenticates the connection, so frames flow without an in-band
+`authenticate`; an unguarded route accepts only authentication frames until its handler's
+`authenticate` succeeds, and any other frame before that closes the socket with 1008. Do not expose
 Fastify request objects through a shared contract.
+
+## What the route does with the handler's answer
+
+| The handler | The socket |
+|---|---|
+| returns after wiring listeners (what every `connection()` handler does) | stays open; **a connection handler that resolves nothing sends nothing** — no frame, empty or otherwise |
+| resolves a value with `EntrypointOutcome.Ok` (`handleConnection`'s `res`) | receives that value once (a string as is, anything else as JSON), then is closed |
+| throws | is closed with 1011; the reason is the refusal marshalled WITHOUT its stack (`type|||message`), clipped to the 123-byte close-reason limit |
+
+`connection()` resolves `undefined` after its callback returns and rejects with whatever it threw.
+Sending that `undefined` used to put an empty frame on the wire: Bun refuses it ("send requires a
+non-empty message"), the throw became a rejection and every real socket closed with 1011 before it
+could authenticate. A server stack never travels in a close reason.
+
+The connection's own `listen` listeners receive the system `close` frame when either side closes,
+which is where a handler releases what it subscribed to. Closing the API server closes every open
+socket with 1001.
+
+## Tests
+
+`bun test ./tests` (category A, offline). `tests/context.ts` boots a real server context the way
+`@owlmeans/server-app` does — `appendApiServer`, `appendSocketService`, `createSocketMiddleware()` —
+on `port: 0`, reading the bound port back; a test guard and gate stand in for real ones. Its client
+is a plain `WebSocket` under `createBasicConnection()`, the shape of viable's agent→publisher link.
+
+| Spec | Covers |
+|---|---|
+| `socket.spec.ts` | the idle handler staying open (the empty-frame regression); the publisher file watch (authenticate → `authenticated` → `{ event, path }` notifications; a refused authentication; a pre-auth frame → 1008); a throwing handler → 1011 and its stackless, clipped reason; a value with Ok → one frame and close; the thinking relay's unsubscribe on client close; guards and gates refusing before the handler; server shutdown → 1001 |
+| `connection.spec.ts` | `connection()` against the real transport response: resolve with `undefined`, reject with the thrown error, a request without a socket, a binding without a context |
+
+A change to the route's resolve/reject handling is verified by reverting it and watching the
+regression spec fail.

package/build/consts.local.d.ts

@@ -0,0 +1,3 @@
+/** The longest close reason a WebSocket close frame carries, in UTF-8 bytes (RFC 6455). */
+export declare const CLOSE_REASON_LIMIT = 123;
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AACA,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,MAAM,CAAA"}

package/build/consts.local.js

@@ -0,0 +1,3 @@
+/** The longest close reason a WebSocket close frame carries, in UTF-8 bytes (RFC 6455). */
+export const CLOSE_REASON_LIMIT = 123;
+//# sourceMappingURL=consts.local.js.map

package/build/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AACA,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA"}

package/build/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAW,MAAM,sBAAsB,CAAA;AAgBpE,eAAO,MAAM,mBAAmB,WAAW,MAAM,KAAmB,aA+GnE,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,OACnE,CAAC,UAAS,MAAM,KACpB,CAOF,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAW,MAAM,sBAAsB,CAAA;AA+BpE,eAAO,MAAM,mBAAmB,WAAW,MAAM,KAAmB,aAoHnE,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,OACnE,CAAC,UAAS,MAAM,KACpB,CAOF,CAAA"}

package/build/service.js

@@ -1,5 +1,6 @@
 import { assertContext, createService } from '@owlmeans/context';
 import { DEFAULT_ALIAS } from './consts.js';
+import { CLOSE_REASON_LIMIT } from './consts.local.js';
 import { canServerModule } from './utils/server.js';
 import { fastifyWebsocket } from '@fastify/websocket';
 import { authorize, httpErrorHelper, makeRequestContextHelper, payloadHelper } from '@owlmeans/server-api/utils';
@@ -7,6 +8,18 @@ import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint';
 import { ResilientError } from '@owlmeans/error';
 import { logger, logThrottle } from '@owlmeans/log';
 const log = logger('server-socket');
+/**
+ * A close reason is at most 123 UTF-8 bytes (RFC 6455): longer is cut by one transport and thrown
+ * on by another, so the marshalled refusal is clipped on a character boundary to fit.
+ */
+const closeReason = (reason) => {
+    const encoder = new TextEncoder();
+    let clipped = reason;
+    while (encoder.encode(clipped).length > CLOSE_REASON_LIMIT) {
+        clipped = clipped.slice(0, -1);
+    }
+    return clipped;
+};
 export const createSocketService = (alias = DEFAULT_ALIAS) => {
     const service = createService(alias, {
         update: async (api) => {
@@ -73,7 +86,12 @@ export const createSocketService = (alias = DEFAULT_ALIAS) => {
                         conn.on('error', (error) => log.error('WebSocket error', { route: module.alias, error }));
                         void module.handle(request, {
                             resolve: (value, outcome) => {
-                                conn.send(typeof value === 'string' ? value : JSON.stringify(value));
+                                // A connection handler that only wires listeners resolves with nothing. There is no
+                                // message to send then, and an empty frame is not one: the transport refuses it, and
+                                // the refusal would close a socket that is just getting started.
+                                if (value !== undefined && value !== null) {
+                                    conn.send(typeof value === 'string' ? value : JSON.stringify(value));
+                                }
                                 if (outcome === EntrypointOutcome.Ok) {
                                     conn.close();
                                 }
@@ -85,7 +103,7 @@ export const createSocketService = (alias = DEFAULT_ALIAS) => {
                                 if (logThrottle(`socket.refused:${module.alias}:${refusal.type}`, 60_000)) {
                                     log.warn('Connection rejected', details, { event: 'socket.refused' });
                                 }
-                                conn.close(1011, refusal.marshal().message);
+                                conn.close(1011, closeReason(refusal.marshal({ includeStack: false }).message));
                             }
                         });
                         const close = () => conn.close(1001);

package/build/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/server-socket",
-  "version": "0.1.18-rc.55",
+  "version": "0.1.18-rc.56",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 324 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -22,6 +23,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.2",
     "@types/connect": "^3.4.38",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
@@ -31,16 +33,18 @@
   },
   "dependencies": {
     "@fastify/websocket": "^11.3.3",
-    "@owlmeans/auth": "^0.1.18-rc.40",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.47",
+    "@owlmeans/auth": "^0.1.18-rc.41",
+    "@owlmeans/basic-envelope": "^0.1.18-rc.48",
     "@owlmeans/context": "^0.1.18-rc.34",
     "@owlmeans/entrypoint": "^0.1.18-rc.41",
-    "@owlmeans/log": "^0.1.18-rc.2",
-    "@owlmeans/server-api": "^0.1.18-rc.52",
-    "@owlmeans/server-auth": "^0.1.18-rc.55",
-    "@owlmeans/server-context": "^0.1.18-rc.43",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/log": "^0.1.18-rc.3",
+    "@owlmeans/route": "^0.1.18-rc.35",
+    "@owlmeans/server-api": "^0.1.18-rc.53",
+    "@owlmeans/server-auth": "^0.1.18-rc.56",
+    "@owlmeans/server-context": "^0.1.18-rc.44",
     "@owlmeans/server-entrypoint": "^0.1.18-rc.40",
-    "@owlmeans/socket": "^0.1.18-rc.41"
+    "@owlmeans/socket": "^0.1.18-rc.42"
   },
   "publishConfig": {
     "access": "public"

package/src/consts.local.ts

@@ -0,0 +1,3 @@
+
+/** The longest close reason a WebSocket close frame carries, in UTF-8 bytes (RFC 6455). */
+export const CLOSE_REASON_LIMIT = 123

package/src/service.ts

@@ -2,6 +2,7 @@ import { assertContext, createService } from '@owlmeans/context'
 import type { SocketService } from './types.js'
 import type { Config, Context, Request } from '@owlmeans/server-api'
 import { DEFAULT_ALIAS } from './consts.js'
+import { CLOSE_REASON_LIMIT } from './consts.local.js'
 import type { FixerService, ServerEntrypoint } from '@owlmeans/server-entrypoint'
 import { canServerModule } from './utils/server.js'
 import { fastifyWebsocket } from '@fastify/websocket'
@@ -16,6 +17,20 @@ import { logger, logThrottle } from '@owlmeans/log'
 
 const log = logger('server-socket')
 
+/**
+ * A close reason is at most 123 UTF-8 bytes (RFC 6455): longer is cut by one transport and thrown
+ * on by another, so the marshalled refusal is clipped on a character boundary to fit.
+ */
+const closeReason = (reason: string): string => {
+  const encoder = new TextEncoder()
+  let clipped = reason
+  while (encoder.encode(clipped).length > CLOSE_REASON_LIMIT) {
+    clipped = clipped.slice(0, -1)
+  }
+
+  return clipped
+}
+
 export const createSocketService = (alias: string = DEFAULT_ALIAS): SocketService => {
   const service: SocketService = createService<SocketService>(alias, {
     update: async api => {
@@ -94,7 +109,12 @@ export const createSocketService = (alias: string = DEFAULT_ALIAS): SocketServic
 
             void module.handle<AbstractRequest<WebSocket>>(request, {
               resolve: (value, outcome) => {
-                conn.send(typeof value === 'string' ? value : JSON.stringify(value))
+                // A connection handler that only wires listeners resolves with nothing. There is no
+                // message to send then, and an empty frame is not one: the transport refuses it, and
+                // the refusal would close a socket that is just getting started.
+                if (value !== undefined && value !== null) {
+                  conn.send(typeof value === 'string' ? value : JSON.stringify(value))
+                }
                 if (outcome === EntrypointOutcome.Ok) {
                   conn.close()
                 }
@@ -106,7 +126,7 @@ export const createSocketService = (alias: string = DEFAULT_ALIAS): SocketServic
                 if (logThrottle(`socket.refused:${module.alias}:${refusal.type}`, 60_000)) {
                   log.warn('Connection rejected', details, { event: 'socket.refused' })
                 }
-                conn.close(1011, refusal.marshal().message)
+                conn.close(1011, closeReason(refusal.marshal({ includeStack: false }).message))
               }
             })
 

package/tests/connection.spec.ts

@@ -0,0 +1,99 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AuthorizationError } from '@owlmeans/auth'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import { bind } from '@owlmeans/server-entrypoint'
+import type { BoundEntrypointHandler, RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
+import { SocketInitializationError } from '@owlmeans/socket'
+import type { Connection } from '@owlmeans/socket'
+import { connection } from '../src/helper.js'
+import { connectClient, protocols, roundTrip, startSocketServer, until } from './context.js'
+import type { SocketServer } from './context.js'
+
+type Call = ['resolve', unknown, unknown] | ['reject', Error]
+
+/**
+ * Runs a `connection()` binding with the transport's own response and records what the binding
+ * told it — the response is the real one, so the socket behaves exactly as it does in production.
+ */
+const recorded = (binding: BoundEntrypointHandler<any>, calls: Call[]): RefedEntrypointHandler => ref => {
+  const handle = binding.bind(ref)
+
+  return async (request, response) => await handle(request, {
+    resolve: (value: unknown, outcome?: unknown) => {
+      calls.push(['resolve', value, outcome])
+      response.resolve(value, outcome as any)
+    },
+    reject: (error: Error) => {
+      calls.push(['reject', error])
+      response.reject(error)
+    },
+  } as AbstractResponse<any>)
+}
+
+const watchCalls: Call[] = []
+const failingCalls: Call[] = []
+const wired: Connection[] = []
+const refusal = new AuthorizationError('slot')
+
+const files = connection(protocols.files, async conn => {
+  conn.listen(async () => undefined)
+  wired.push(conn)
+})
+const failing = connection(protocols.failing, async () => { throw refusal })
+
+describe('@owlmeans/server-socket — connection()', () => {
+  let server: SocketServer
+
+  beforeAll(async () => {
+    server = await startSocketServer([
+      bind(protocols.files, recorded(files, watchCalls)),
+      bind(protocols.failing, recorded(failing, failingCalls)),
+    ])
+  })
+  afterAll(async () => { await server?.close() })
+
+  test('publisher file watch: the handler only wires listeners, and is resolved with undefined once it returns', async () => {
+    const client = connectClient(server.url('/update/files'))
+
+    expect(await client.opened).toBe(true)
+    expect(await roundTrip(client)).toBe(true)
+    expect(wired).toHaveLength(1)
+    expect(watchCalls).toEqual([['resolve', undefined, undefined]])
+    client.socket.close()
+    await client.closed
+  })
+
+  test('a handler that throws is answered through reject with its own error, never resolve', async () => {
+    const client = connectClient(server.url('/failing'))
+
+    await client.closed
+    await until(() => failingCalls.length > 0)
+    expect(failingCalls).toEqual([['reject', refusal]])
+  })
+
+  test('a request that carries no socket is rejected with SocketInitializationError before the handler', async () => {
+    let reached = false
+    const calls: Call[] = []
+    const binding = connection(protocols.idle, async () => { reached = true })
+
+    await recorded(binding, calls)({ ref: { ctx: server.context } } as any)(
+      { alias: protocols.idle.alias, params: {}, query: {}, headers: {} } as any,
+      { resolve: () => undefined, reject: () => undefined } as any,
+    )
+
+    expect(reached).toBe(false)
+    expect(calls).toHaveLength(1)
+    expect(calls[0]?.[0]).toBe('reject')
+    expect(calls[0]?.[1]).toBeInstanceOf(SocketInitializationError)
+  })
+
+  test('a binding reached without a context throws, naming the protocol, and never runs the handler', async () => {
+    let reached = false
+    const binding = connection(protocols.idle, async () => { reached = true })
+
+    expect(binding.protocol).toBe(protocols.idle)
+    await expect(binding.bind({ ref: {} } as any)({ alias: protocols.idle.alias } as any, {} as any))
+      .rejects.toThrow(protocols.idle.alias)
+    expect(reached).toBe(false)
+  })
+})

package/tests/context.ts

@@ -0,0 +1,248 @@
+import { EventEmitter } from 'node:events'
+import { AppType, createLazyService, createService } from '@owlmeans/context'
+import type { AbstractRequest, GateService, GuardService } from '@owlmeans/entrypoint'
+import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
+import { openProtocol } from '@owlmeans/entrypoint'
+import { AuthorizationError, AuthenticationStage } from '@owlmeans/auth'
+import type { Auth } from '@owlmeans/auth'
+import { route, socket } from '@owlmeans/route'
+import { appendApiServer } from '@owlmeans/server-api'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig } from '@owlmeans/server-context'
+import { createBasicConnection, MessageType } from '@owlmeans/socket'
+import type { AuthenticateMethod, Connection, EventMessage } from '@owlmeans/socket'
+import { appendSocketService } from '../src/service.js'
+import { createSocketMiddleware } from '../src/middleware.js'
+import type { Context } from '../src/types.js'
+
+export const TEST_SERVICE = 'server-socket-tests'
+export const TEST_GUARD = 'server-socket-test-guard'
+export const TEST_GATE = 'server-socket-test-gate'
+
+/** What the agent signs with and the publisher accepts — the in-band credential of every case. */
+export const AGENT_TOKEN = 'signed-by-the-agent'
+/** The query token the HTTP guard of a guarded socket route accepts. */
+export const GUARD_TOKEN = 'guard-accepts-this'
+
+/** The publisher's `API_PUBLISHER_WATCH` event: one `{ event, path }` per file-system change. */
+export const WATCH_EVENT = 'server-socket-test:watch'
+/** The manager-api's `agent:thinking` relay event. */
+export const THINKING_EVENT = 'server-socket-test:thinking'
+
+export interface WatchChange { event: string, path: string }
+
+/**
+ * Socket routes declared the way a shared protocol package declares them — `socket()` routes in
+ * immutable protocol declarations — one per case the specs depict.
+ */
+export const protocols = {
+  /** The publisher's file watch (`publisherProtocols.update.files`). */
+  files: openProtocol(route('server-socket-test:update:files', '/update/files', socket())),
+  /** The manager-api's thinking relay (`back.update.project`). */
+  thinking: openProtocol(route('server-socket-test:update:thinking', '/update/thinking', socket())),
+  /** A handler that only wires listeners and resolves nothing. */
+  idle: openProtocol(route('server-socket-test:idle', '/idle', socket())),
+  /** A handler that throws before it is done. */
+  failing: openProtocol(route('server-socket-test:failing', '/failing', socket())),
+  /** A handler that answers once with a value and the Ok outcome. */
+  once: openProtocol(route('server-socket-test:once', '/once', socket())),
+  /** A route behind an HTTP guard. */
+  guarded: openProtocol(route('server-socket-test:guarded', '/guarded', socket()), { guards: TEST_GUARD }),
+  /** A route behind a gate. */
+  gated: openProtocol(route('server-socket-test:gated', '/gated', socket()), {
+    gate: { alias: TEST_GATE, params: ['watch'] },
+  }),
+} as const
+
+const queryOf = (request: AbstractRequest): Record<string, unknown> =>
+  (request.query ?? {}) as Record<string, unknown>
+
+/** A guard that admits the upgrade carrying `GUARD_TOKEN` in its query, the way a bearer guard would. */
+const createTestGuard = (): GuardService => createService<GuardService>(TEST_GUARD, {
+  authenticated: async () => null,
+  match: async request => queryOf(request).token != null,
+  handle: async (request, response) => {
+    if (queryOf(request).token !== GUARD_TOKEN) {
+      return false as any
+    }
+    response.resolve({ token: GUARD_TOKEN, userId: 'agent' } as Auth)
+
+    return true as any
+  },
+}, service => async () => { service.initialized = true })
+
+/** A gate that opens only for an upgrade asking for it, and records every assertion it made. */
+export interface TestGate extends GateService {
+  asserted: string[][]
+}
+
+const createTestGate = (): TestGate => {
+  const asserted: string[][] = []
+
+  return createLazyService<TestGate>(TEST_GATE, {
+    asserted,
+    assert: async (request, _response, params) => {
+      asserted.push(params)
+      if (queryOf(request).gate !== 'open') {
+        throw new AuthorizationError('gate')
+      }
+    },
+  })
+}
+
+export interface SocketServer {
+  context: Context
+  gate: TestGate
+  /** The `ws://` address of a route path on the bound ephemeral port. */
+  url: (path: string, query?: Record<string, string>) => string
+  close: () => Promise<void>
+}
+
+/**
+ * A real server context wired the way `@owlmeans/server-app` wires one — the API server, the
+ * socket service and its middleware — listening on an ephemeral port (`port: 0`).
+ */
+export const startSocketServer = async (entrypoints: ServerEntrypoint<any>[]): Promise<SocketServer> => {
+  const context = makeServerContext(config<ServerConfig>(TEST_SERVICE, {
+    services: { [TEST_SERVICE]: { service: TEST_SERVICE, type: AppType.Backend, host: '127.0.0.1', port: 0 } },
+  } as Partial<ServerConfig>)) as unknown as Context
+  appendApiServer(context)
+  appendSocketService(context)
+  context.registerMiddleware(createSocketMiddleware())
+  context.registerService(createTestGuard())
+  const gate = createTestGate()
+  context.registerService(gate)
+  context.registerEntrypoints(entrypoints)
+
+  context.configure()
+  await context.init()
+  await context.getApiServer().listen()
+
+  const address = context.getApiServer().server.server.address()
+  const port = typeof address === 'object' && address != null ? address.port : 0
+
+  return {
+    context,
+    gate,
+    url: (path, query) => `ws://127.0.0.1:${port}${path}${query != null ? `?${new URLSearchParams(query)}` : ''}`,
+    close: async () => { await context.getApiServer().server.close() },
+  }
+}
+
+export interface Closed { code: number, reason: string }
+
+export interface TestClient {
+  connection: Connection
+  socket: WebSocket
+  /** Every raw frame the server sent, in order. */
+  frames: string[]
+  /** True once the socket opened; false when it closed (or failed) before opening. */
+  opened: Promise<boolean>
+  closed: Promise<Closed>
+}
+
+/**
+ * The agent's side of the agent→publisher link (`connectWsWithSignedAuth` in viable's
+ * `sources/backend/src/lib/ws.ts`): a plain WebSocket under the shared connection model, whose
+ * close is reported to listeners as the system `close` frame.
+ */
+export const connectClient = (url: string): TestClient => {
+  const ws = new WebSocket(url)
+  const frames: string[] = []
+  const model = createBasicConnection()
+
+  model.send = async message => {
+    if (typeof message !== 'string') {
+      model.prepare?.(message)
+    }
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(typeof message === 'string' ? message : JSON.stringify(message))
+    }
+  }
+  model.close = async () => {
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close()
+    }
+  }
+  // The agent never answers a server-initiated exchange, exactly like the platform's client.
+  model.authenticate = (async () => []) as unknown as AuthenticateMethod
+  model.prepare = message => {
+    message.dt = message.dt ?? Date.now()
+    return message
+  }
+
+  ws.addEventListener('message', event => {
+    const data = typeof event.data === 'string' ? event.data : String(event.data)
+    frames.push(data)
+    void model.receive(data).catch(() => undefined)
+  })
+
+  const opened = new Promise<boolean>(resolve => {
+    ws.addEventListener('open', () => resolve(true))
+    ws.addEventListener('close', () => resolve(false))
+  })
+  const closed = new Promise<Closed>(resolve => {
+    ws.addEventListener('close', event => {
+      const msg: EventMessage<{ code: number }> = {
+        type: MessageType.System, event: 'close', payload: { code: event.code },
+      }
+      void Promise.all(model.getListeners().map(async listener => await listener(msg)))
+      resolve({ code: event.code, reason: event.reason })
+    })
+  })
+
+  return { connection: model, socket: ws, frames, opened, closed }
+}
+
+/** Send a heartbeat and wait for the server's `pong` — proof the socket is alive end to end. */
+export const roundTrip = async (client: TestClient): Promise<boolean> => {
+  const before = client.frames.length
+  client.socket.send(JSON.stringify({ type: 'ping' }))
+
+  return await Promise.race([
+    new Promise<boolean>(resolve => {
+      const check = (): void => {
+        if (client.frames.slice(before).includes(JSON.stringify({ type: 'pong' }))) {
+          resolve(true)
+        } else {
+          setTimeout(check, 5)
+        }
+      }
+      check()
+    }),
+    client.closed.then(() => false),
+  ])
+}
+
+/** Wait until `predicate` holds, or fail after `timeout` ms. */
+export const until = async (predicate: () => boolean, timeout: number = 2_000): Promise<void> => {
+  const started = Date.now()
+  while (!predicate()) {
+    if (Date.now() - started > timeout) {
+      throw new Error('Condition not reached in time')
+    }
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+}
+
+/**
+ * The publisher's in-band authentication (`createWsAuthentication` in viable's
+ * `sources/publisher/src/helpers/ws-auth.ts`): a valid credential announces the system
+ * `authenticated` frame to the connection's own listeners; a refused one closes the socket.
+ */
+export const makeAgentAuthentication = (conn: Connection): AuthenticateMethod => (async (
+  stage: AuthenticationStage, payload: { token?: string },
+) => {
+  if (stage !== AuthenticationStage.Authenticate || payload?.token !== AGENT_TOKEN) {
+    await conn.close()
+
+    return [AuthenticationStage.Error, null]
+  }
+  const msg: EventMessage<void> = { type: MessageType.System, event: 'authenticated', payload: undefined }
+  conn.getListeners().map(listener => listener(msg))
+
+  return [AuthenticationStage.Authenticated, true]
+}) as AuthenticateMethod
+
+/** A slot's change feed and a pub/sub topic: the in-process sources the real handlers subscribe to. */
+export const makeFeed = (): EventEmitter => new EventEmitter()

package/tests/socket.spec.ts

@@ -0,0 +1,247 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AuthenticationStage, AuthorizationError } from '@owlmeans/auth'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import { bind } from '@owlmeans/server-entrypoint'
+import { MessageType } from '@owlmeans/socket'
+import type { EventMessage } from '@owlmeans/socket'
+import { connection, handleConnection } from '../src/helper.js'
+import {
+  AGENT_TOKEN, GUARD_TOKEN, THINKING_EVENT, WATCH_EVENT, connectClient, makeAgentAuthentication, makeFeed,
+  protocols, roundTrip, startSocketServer, until,
+} from './context.js'
+import type { SocketServer, WatchChange } from './context.js'
+
+const isSystem = (raw: unknown, event: string): boolean => typeof raw === 'object' && raw != null
+  && (raw as EventMessage<void>).type === MessageType.System && (raw as EventMessage<void>).event === event
+
+/** The slot's change feed the publisher's file watch subscribes to once the agent authenticated. */
+const slot = makeFeed()
+/** The pub/sub topic the manager-api's thinking relay subscribes to. */
+const topic = makeFeed()
+/** Close codes the thinking relay's server-side close listener observed. */
+const relayClosed: number[] = []
+/** How many times each handler was reached. */
+const reached: Record<string, number> = { guarded: 0, gated: 0 }
+/** Frames the guarded handler observed. */
+const guardedEvents: unknown[] = []
+
+const refusal = new AuthorizationError('slot')
+/** A refusal whose marshalled form outgrows a close frame's 123-byte reason. */
+const longRefusal = new AuthorizationError(`slot:${'ü'.repeat(80)}`)
+const bytes = (text: string): number => new TextEncoder().encode(text).length
+
+const entrypoints = [
+  // Every real Viable socket: a `connection()` handler that wires listeners and resolves nothing.
+  bind(protocols.idle, connection(protocols.idle, async conn => {
+    conn.listen(async () => undefined)
+  })),
+
+  // The publisher's file watch (viable `sources/publisher/src/app/update/files.ts`).
+  bind(protocols.files, connection(protocols.files, async conn => {
+    conn.listen(async raw => {
+      if (!isSystem(raw, 'authenticated')) {
+        return
+      }
+      const onChange = (change: WatchChange): void => { void conn.notify(WATCH_EVENT, change) }
+      slot.on('change', onChange)
+      conn.listen(async msg => {
+        if (isSystem(msg, 'close')) {
+          slot.off('change', onChange)
+        }
+      })
+    })
+    conn.authenticate = makeAgentAuthentication(conn)
+  })),
+
+  // The manager-api's thinking relay (viable `sources/manager-api/src/app/project/thinking.ts`).
+  bind(protocols.thinking, handleConnection(async conn => {
+    conn.authenticate = makeAgentAuthentication(conn)
+    let unsubscribe: (() => void) | undefined
+    conn.listen(async raw => {
+      if (isSystem(raw, 'authenticated')) {
+        const push = (entry: unknown): void => { void conn.notify(THINKING_EVENT, entry) }
+        topic.on('thinking', push)
+        unsubscribe = () => topic.off('thinking', push)
+      } else if (isSystem(raw, 'close')) {
+        relayClosed.push((raw as EventMessage<{ code: number }>).payload.code)
+        unsubscribe?.()
+        unsubscribe = undefined
+      }
+    })
+  })),
+
+  bind(protocols.failing, connection(protocols.failing, async (_conn, _ctx, request) => {
+    throw (request.query as Record<string, string> | undefined)?.long != null ? longRefusal : refusal
+  })),
+
+  bind(protocols.once, handleConnection(async (_conn, _ctx, _req, res) => {
+    res.resolve({ ready: true }, EntrypointOutcome.Ok)
+  })),
+
+  bind(protocols.guarded, connection(protocols.guarded, async conn => {
+    reached.guarded++
+    conn.observe(WATCH_EVENT, async msg => { guardedEvents.push(msg.payload) })
+  })),
+
+  bind(protocols.gated, connection(protocols.gated, async conn => {
+    reached.gated++
+    conn.listen(async () => undefined)
+  })),
+]
+
+describe('@owlmeans/server-socket — a socket route served end to end', () => {
+  let server: SocketServer
+  const clients: WebSocket[] = []
+  const open = (path: string, query?: Record<string, string>) => {
+    const client = connectClient(server.url(path, query))
+    clients.push(client.socket)
+    return client
+  }
+
+  beforeAll(async () => { server = await startSocketServer(entrypoints) })
+  afterAll(async () => {
+    clients.forEach(socket => socket.close())
+    await server?.close()
+  })
+
+  test('a connection handler that only wires listeners keeps the socket open and sends no frame', async () => {
+    const client = open('/idle')
+
+    expect(await client.opened).toBe(true)
+    // The ping is answered only by a live server-side socket; a 1011 close would end the race first.
+    expect(await roundTrip(client)).toBe(true)
+    expect(client.socket.readyState).toBe(WebSocket.OPEN)
+    expect(client.frames).toEqual([JSON.stringify({ type: 'pong' })])
+  })
+
+  test('publisher file watch: the agent authenticates, then observes { event, path } changes', async () => {
+    const client = open('/update/files')
+    const changes: WatchChange[] = []
+    client.connection.observe<WatchChange>(WATCH_EVENT, async msg => { changes.push(msg.payload) })
+
+    expect(await client.opened).toBe(true)
+    expect(await client.connection.auth<{ token: string }, boolean>(AuthenticationStage.Authenticate, { token: AGENT_TOKEN }))
+      .toBe(true)
+    expect(client.connection.stage).toBe(AuthenticationStage.Authenticated)
+    await until(() => slot.listenerCount('change') === 1)
+
+    slot.emit('change', { event: 'change', path: 'src/index.ts' })
+    await until(() => changes.length === 1)
+    expect(changes).toEqual([{ event: 'change', path: 'src/index.ts' }])
+
+    client.socket.close()
+    await client.closed
+    await until(() => slot.listenerCount('change') === 0)
+  })
+
+  test('publisher file watch: a refused authentication is closed by the server, nothing is watched', async () => {
+    const client = open('/update/files')
+
+    expect(await client.opened).toBe(true)
+    void client.connection.auth(AuthenticationStage.Authenticate, { token: 'forged' }).catch(() => undefined)
+
+    await client.closed
+    expect(slot.listenerCount('change')).toBe(0)
+  })
+
+  test('publisher file watch: a frame other than authentication before it closes the socket with 1008', async () => {
+    const client = open('/update/files')
+
+    expect(await client.opened).toBe(true)
+    client.socket.send(JSON.stringify({ type: MessageType.Event, event: WATCH_EVENT, payload: {} }))
+
+    expect((await client.closed).code).toBe(1008)
+    expect(slot.listenerCount('change')).toBe(0)
+  })
+
+  test('a handler that throws is rejected: closed with 1011 and the marshalled refusal as reason', async () => {
+    const client = open('/failing')
+
+    const closed = await client.closed
+    expect(closed.code).toBe(1011)
+    // Type and message only: a server stack never reaches the client.
+    expect(closed.reason).toBe(ResilientError.ensure(refusal).marshal({ includeStack: false }).message)
+    expect(ResilientError.ensure(new Error(closed.reason))).toBeInstanceOf(AuthorizationError)
+    expect(client.frames).toEqual([])
+  })
+
+  test('a refusal longer than a close frame allows is clipped to 123 bytes on a character boundary', async () => {
+    const client = open('/failing', { long: '1' })
+
+    const closed = await client.closed
+    const full = ResilientError.ensure(longRefusal).marshal({ includeStack: false }).message
+    expect(closed.code).toBe(1011)
+    expect(bytes(full)).toBeGreaterThan(123)
+    expect(bytes(closed.reason)).toBeLessThanOrEqual(123)
+    expect(full.startsWith(closed.reason)).toBe(true)
+  })
+
+  test('a handler resolving a value with the Ok outcome sends it once and closes', async () => {
+    const client = open('/once')
+
+    await client.closed
+    expect(client.frames).toEqual([JSON.stringify({ ready: true })])
+  })
+
+  test('thinking relay: a client close runs the server-side close listener, which unsubscribes', async () => {
+    const client = open('/update/thinking')
+    const entries: unknown[] = []
+    client.connection.observe(THINKING_EVENT, async msg => { entries.push(msg.payload) })
+
+    expect(await client.opened).toBe(true)
+    await client.connection.auth(AuthenticationStage.Authenticate, { token: AGENT_TOKEN })
+    await until(() => topic.listenerCount('thinking') === 1)
+    topic.emit('thinking', { step: 'plan' })
+    await until(() => entries.length === 1)
+    expect(entries).toEqual([{ step: 'plan' }])
+
+    await client.connection.close()
+    await until(() => topic.listenerCount('thinking') === 0)
+    expect(relayClosed).toHaveLength(1)
+  })
+
+  test('a guard refusing the upgrade never reaches the handler', async () => {
+    const client = open('/guarded')
+
+    expect(await client.opened).toBe(false)
+    const forged = open('/guarded', { token: 'forged' })
+    expect(await forged.opened).toBe(false)
+    expect(reached.guarded).toBe(0)
+  })
+
+  test('a guard admitting the upgrade authenticates the connection: frames flow without in-band auth', async () => {
+    const client = open('/guarded', { token: GUARD_TOKEN })
+
+    expect(await client.opened).toBe(true)
+    await until(() => reached.guarded === 1)
+    await client.connection.notify(WATCH_EVENT, { event: 'add', path: 'README.md' })
+    await until(() => guardedEvents.length === 1)
+    expect(guardedEvents).toEqual([{ event: 'add', path: 'README.md' }])
+  })
+
+  test('a closed gate refuses the upgrade before the handler; an open one lets it through', async () => {
+    const refused = open('/gated')
+    expect(await refused.opened).toBe(false)
+    expect(reached.gated).toBe(0)
+
+    const admitted = open('/gated', { gate: 'open' })
+    expect(await admitted.opened).toBe(true)
+    await until(() => reached.gated === 1)
+    expect(server.gate.asserted).toEqual([['watch'], ['watch']])
+  })
+})
+
+describe('@owlmeans/server-socket — server shutdown', () => {
+  test('closing the server closes every open socket with 1001', async () => {
+    const server = await startSocketServer([
+      bind(protocols.idle, connection(protocols.idle, async conn => { conn.listen(async () => undefined) })),
+    ])
+    const client = connectClient(server.url('/idle'))
+    expect(await client.opened).toBe(true)
+    expect(await roundTrip(client)).toBe(true)
+
+    await server.close()
+    expect((await client.closed).code).toBe(1001)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -7,5 +7,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }