@super-line/server 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, AccessRules, Resource, Perms, SharedTopics, EventData, ServerTransport, Handshake, ServerStore } from '@super-line/core';
 
-/** Backpressure policy: what to do when a connection's send buffer grows too large. */
-interface Backpressure {
-    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
-    maxBufferedBytes: number;
-    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
-    onExceed?: 'close' | 'drop';
-}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
 declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,14 +18,17 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
-    private readonly backpressure?;
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     private readonly onEmit?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
     /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
     data: Data;
-    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** ACL identity for stores: `identify(conn) ?? conn.id`, set by the server at accept (always defined there). */
+    principal?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -43,26 +37,33 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** Pings sent since the last pong; drives reaping (managed by the server). */
     missedPongs: number;
     constructor(
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    ws: WebSocket, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined, 
+    ctx: Ctx, serializer: Serializer, 
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     onEmit?: ((event: string, data: unknown) => void) | undefined);
-    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
+/**
+ * The ACL principal for a connection: the stable `identify` key when configured, else the
+ * (random, per-connection) `conn.id`. Always returns a string — store access rules never key
+ * on `undefined`. Distinct from `identify`'s raw output (which may be undefined, used for presence).
+ */
+declare function resolvePrincipal(conn: Conn, identify?: (conn: Conn) => string | undefined): string;
 
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
@@ -217,23 +218,42 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
+/**
+ * Server-side handle for one configured Store, reached via `srv.store.<name>`. The server is
+ * authoritative: it creates Resources, grants/revokes access, and may co-write. `data` is untyped
+ * (stores are off-contract — see ADR-0003); callers assert the shape.
+ */
+interface ServerStoreHandle {
+    /** Create a Resource with initial data + access rules (deny-by-default for everyone unlisted). */
+    create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
+    /** Read a Resource (data + accessRules), or undefined if absent. */
+    read(id: string): Promise<Resource | undefined>;
+    /** Server co-write: replace the Resource's value (LWW), fanned out to subscribers with a `server` origin. */
+    write(id: string, data: unknown): Promise<void>;
+    /** Grant a principal read/write on a Resource. */
+    grant(id: string, principal: string, perms: Perms): Promise<void>;
+    /** Revoke a principal's access to a Resource entirely. */
+    revoke(id: string, principal: string): Promise<void>;
+    /** Delete a Resource. */
+    delete(id: string): Promise<void>;
+    /** All Resource ids in this store. */
+    list(): Promise<string[]>;
+}
 /** Options for {@link createSuperLineServer}. */
 interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
     /**
      * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
      * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
      */
     nodeName?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => Awaitable<A>;
     /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
     identify?: (conn: Conn) => string | undefined;
     /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
@@ -252,16 +272,20 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
     /**
-     * Read-only Control Center inspector channel, reached via the WS subprotocol
-     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
-     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
      */
     inspector?: boolean | {
         redact?: string[];
     };
+    /**
+     * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
+     * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
+     * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
+     */
+    stores?: Record<string, ServerStore>;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -300,6 +324,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
+    /** Server-authoritative handle for a configured Store (`srv.store('scene').create(...)`). Throws `NOT_FOUND` if the name isn't configured. */
+    store(name: string): ServerStoreHandle;
     close(): Promise<void>;
 }
 /**
@@ -315,8 +341,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * @example
  * ```ts
  * const srv = createSuperLineServer(api, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -326,4 +352,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerStoreHandle, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };

package/dist/index.d.ts

@@ -1,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, AccessRules, Resource, Perms, SharedTopics, EventData, ServerTransport, Handshake, ServerStore } from '@super-line/core';
 
-/** Backpressure policy: what to do when a connection's send buffer grows too large. */
-interface Backpressure {
-    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
-    maxBufferedBytes: number;
-    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
-    onExceed?: 'close' | 'drop';
-}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
 declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,14 +18,17 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
-    private readonly backpressure?;
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     private readonly onEmit?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
     /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
     data: Data;
-    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** ACL identity for stores: `identify(conn) ?? conn.id`, set by the server at accept (always defined there). */
+    principal?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -43,26 +37,33 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** Pings sent since the last pong; drives reaping (managed by the server). */
     missedPongs: number;
     constructor(
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    ws: WebSocket, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined, 
+    ctx: Ctx, serializer: Serializer, 
     /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
     onEmit?: ((event: string, data: unknown) => void) | undefined);
-    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
+/**
+ * The ACL principal for a connection: the stable `identify` key when configured, else the
+ * (random, per-connection) `conn.id`. Always returns a string — store access rules never key
+ * on `undefined`. Distinct from `identify`'s raw output (which may be undefined, used for presence).
+ */
+declare function resolvePrincipal(conn: Conn, identify?: (conn: Conn) => string | undefined): string;
 
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
@@ -217,23 +218,42 @@ interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
+/**
+ * Server-side handle for one configured Store, reached via `srv.store.<name>`. The server is
+ * authoritative: it creates Resources, grants/revokes access, and may co-write. `data` is untyped
+ * (stores are off-contract — see ADR-0003); callers assert the shape.
+ */
+interface ServerStoreHandle {
+    /** Create a Resource with initial data + access rules (deny-by-default for everyone unlisted). */
+    create(id: string, data: unknown, accessRules: AccessRules): Promise<void>;
+    /** Read a Resource (data + accessRules), or undefined if absent. */
+    read(id: string): Promise<Resource | undefined>;
+    /** Server co-write: replace the Resource's value (LWW), fanned out to subscribers with a `server` origin. */
+    write(id: string, data: unknown): Promise<void>;
+    /** Grant a principal read/write on a Resource. */
+    grant(id: string, principal: string, perms: Perms): Promise<void>;
+    /** Revoke a principal's access to a Resource entirely. */
+    revoke(id: string, principal: string): Promise<void>;
+    /** Delete a Resource. */
+    delete(id: string): Promise<void>;
+    /** All Resource ids in this store. */
+    list(): Promise<string[]>;
+}
 /** Options for {@link createSuperLineServer}. */
 interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
     /**
      * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
      * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
      */
     nodeName?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => Awaitable<A>;
     /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
     identify?: (conn: Conn) => string | undefined;
     /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
@@ -252,16 +272,20 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
     /**
-     * Read-only Control Center inspector channel, reached via the WS subprotocol
-     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
-     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
      */
     inspector?: boolean | {
         redact?: string[];
     };
+    /**
+     * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
+     * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
+     * `srv.store.<name>` and `client.store.<name>`. Stores are off-contract and untyped (ADR-0003).
+     */
+    stores?: Record<string, ServerStore>;
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -300,6 +324,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
+    /** Server-authoritative handle for a configured Store (`srv.store('scene').create(...)`). Throws `NOT_FOUND` if the name isn't configured. */
+    store(name: string): ServerStoreHandle;
     close(): Promise<void>;
 }
 /**
@@ -315,8 +341,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * @example
  * ```ts
  * const srv = createSuperLineServer(api, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -326,4 +352,4 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  */
 declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerStoreHandle, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };