@super-line/server 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 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, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+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';
 
 /** Backpressure policy: what to do when a connection's send buffer grows too large. */
@@ -28,6 +28,8 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     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. */
@@ -48,7 +50,9 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, backpressure?: Backpressure | undefined, 
+    /** 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;
@@ -127,12 +131,17 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request or a topic subscribe. */
-    kind: 'request' | 'subscribe';
-    /** The request/topic name. */
+    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
+    kind: 'request' | 'subscribe' | 'event';
+    /** The request/topic/event name. */
     name: string;
-    /** The connection the operation is on (`conn.role` available). */
-    conn: Conn;
+    /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
+    conn?: Conn;
+}
+/** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
+interface BusMeta {
+    /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
+    from: string;
 }
 /**
  * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
@@ -186,7 +195,7 @@ interface ConnTarget<C extends Contract> {
     emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /**
      * Send a shared server→client request and await the client's typed reply
-     * (cross-node). Rejects with a `TIMEOUT` `SocketError` if no live node owns
+     * (cross-node). Rejects with a `TIMEOUT` `SuperLineError` if no live node owns
      * the connection or the client doesn't answer in time.
      */
     request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
@@ -208,8 +217,8 @@ 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;
 }
-/** Options for {@link createSocketServer}. */
-interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+/** 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;
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -218,6 +227,11 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     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>;
     /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
@@ -240,6 +254,14 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     } | 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.**
+     */
+    inspector?: boolean | {
+        redact?: string[];
+    };
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -247,10 +269,12 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** Called for any error thrown in middleware/handlers (after the client is replied to). */
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
-/** A running super-line server, returned by {@link createSocketServer}. */
-interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+/** A running super-line server, returned by {@link createSuperLineServer}. */
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     /** This node's stable id (unique per server process). */
     readonly nodeId: string;
+    /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
+    readonly nodeName: string;
     /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
     readonly local: LocalView;
     /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
@@ -262,32 +286,35 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
     /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
     toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
     publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /**
+     * Subscribe SERVER-side to a shared topic, cluster-wide. The callback fires for a
+     * publish from any node — including this one (local echo, delivered in-process with
+     * no round-trip). `meta.from` is the publishing node; self-exclude with
+     * `if (meta.from === srv.nodeId) return`. Returns an unsubscribe fn.
+     */
+    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>;
-    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
-    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
-    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
-    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
     close(): Promise<void>;
 }
 /**
  * Create a server bound to a contract. Attach it to an `http.Server`, then call
- * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * {@link SuperLineServer.implement} with your handlers. `authenticate` resolves each
  * connection's `{ role, ctx }` at the upgrade.
  *
  * @param contract - the shared contract.
  * @param opts - server options; `authenticate` is required.
- * @returns the {@link SocketServer}.
- * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ * @returns the {@link SuperLineServer}.
+ * @throws nothing directly; handler throws become a typed `SuperLineError` to the client.
  *
  * @example
  * ```ts
- * const srv = createSocketServer(api, {
+ * const srv = createSuperLineServer(api, {
  *   server,
  *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
@@ -297,6 +324,6 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+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 ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+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';
 
 /** Backpressure policy: what to do when a connection's send buffer grows too large. */
@@ -28,6 +28,8 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     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. */
@@ -48,7 +50,9 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, backpressure?: Backpressure | undefined, 
+    /** 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;
@@ -127,12 +131,17 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request or a topic subscribe. */
-    kind: 'request' | 'subscribe';
-    /** The request/topic name. */
+    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
+    kind: 'request' | 'subscribe' | 'event';
+    /** The request/topic/event name. */
     name: string;
-    /** The connection the operation is on (`conn.role` available). */
-    conn: Conn;
+    /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
+    conn?: Conn;
+}
+/** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
+interface BusMeta {
+    /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
+    from: string;
 }
 /**
  * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
@@ -186,7 +195,7 @@ interface ConnTarget<C extends Contract> {
     emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /**
      * Send a shared server→client request and await the client's typed reply
-     * (cross-node). Rejects with a `TIMEOUT` `SocketError` if no live node owns
+     * (cross-node). Rejects with a `TIMEOUT` `SuperLineError` if no live node owns
      * the connection or the client doesn't answer in time.
      */
     request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
@@ -208,8 +217,8 @@ 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;
 }
-/** Options for {@link createSocketServer}. */
-interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+/** 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;
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -218,6 +227,11 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     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>;
     /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
@@ -240,6 +254,14 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     } | 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.**
+     */
+    inspector?: boolean | {
+        redact?: string[];
+    };
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -247,10 +269,12 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** Called for any error thrown in middleware/handlers (after the client is replied to). */
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
-/** A running super-line server, returned by {@link createSocketServer}. */
-interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+/** A running super-line server, returned by {@link createSuperLineServer}. */
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     /** This node's stable id (unique per server process). */
     readonly nodeId: string;
+    /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
+    readonly nodeName: string;
     /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
     readonly local: LocalView;
     /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
@@ -262,32 +286,35 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
     /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
     toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
     publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /**
+     * Subscribe SERVER-side to a shared topic, cluster-wide. The callback fires for a
+     * publish from any node — including this one (local echo, delivered in-process with
+     * no round-trip). `meta.from` is the publishing node; self-exclude with
+     * `if (meta.from === srv.nodeId) return`. Returns an unsubscribe fn.
+     */
+    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>;
-    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
-    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
-    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
-    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
     close(): Promise<void>;
 }
 /**
  * Create a server bound to a contract. Attach it to an `http.Server`, then call
- * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * {@link SuperLineServer.implement} with your handlers. `authenticate` resolves each
  * connection's `{ role, ctx }` at the upgrade.
  *
  * @param contract - the shared contract.
  * @param opts - server options; `authenticate` is required.
- * @returns the {@link SocketServer}.
- * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ * @returns the {@link SuperLineServer}.
+ * @throws nothing directly; handler throws become a typed `SuperLineError` to the client.
  *
  * @example
  * ```ts
- * const srv = createSocketServer(api, {
+ * const srv = createSuperLineServer(api, {
  *   server,
  *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
@@ -297,6 +324,6 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+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 ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };
+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 };