@super-line/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -55,6 +55,71 @@ interface Adapter {
     onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
     /** Optional teardown (e.g. close Redis connections). */
     close?(): void | Promise<void>;
+    /**
+     * Optional cluster-wide presence directory. Powers `srv.cluster.*` and
+     * `srv.isOnline`. The in-memory and Redis adapters implement it; cluster
+     * queries throw a clear error on an adapter that doesn't.
+     */
+    presence?: PresenceStore;
+}
+/** A serializable snapshot of a connection, shared cluster-wide via the {@link PresenceStore}. */
+interface ConnDescriptor {
+    /** The connection's server-assigned id. */
+    id: string;
+    /** The connection's role. */
+    role: string;
+    /** The node that holds this connection. */
+    nodeId: string;
+    /** When the connection was accepted (`Date.now()`). */
+    connectedAt: number;
+    /** The stable user key from the server's `identify` hook, if any. */
+    userId?: string;
+    /** Room memberships (topics and node-local `lastPongAt` are not included). */
+    rooms: string[];
+    /** Extra fields contributed by the server's `describeConn` hook. */
+    [extra: string]: unknown;
+}
+/** Per-node aggregate, returned by {@link PresenceStore.topology}. */
+interface NodeStat {
+    /** The node's id. */
+    nodeId: string;
+    /** Number of connections on the node. */
+    connections: number;
+    /** Number of distinct rooms with members on the node. */
+    rooms: number;
+    /** Whether the node is currently live (heartbeat fresh). */
+    alive: boolean;
+}
+/**
+ * Cluster-wide presence directory: a query/addressbook layer kept in the shared
+ * substrate (in-memory bus or Redis). Live message delivery does NOT read this —
+ * it exists only to answer `srv.cluster.*` / `srv.isOnline`.
+ */
+interface PresenceStore {
+    /** Record (or replace) a connection's descriptor. */
+    set(descriptor: ConnDescriptor): void | Promise<void>;
+    /** Remove a connection's descriptor. */
+    del(connId: string): void | Promise<void>;
+    /** Refresh this node's liveness (heartbeat). */
+    beat(nodeId: string): void | Promise<void>;
+    /** Remove all of a node's connections + liveness (graceful shutdown cleanup). */
+    clearNode(nodeId: string): void | Promise<void>;
+    /** Add a room to a connection's membership. */
+    addRoom(connId: string, room: string): void | Promise<void>;
+    /** Remove a room from a connection's membership. */
+    removeRoom(connId: string, room: string): void | Promise<void>;
+    /** All live connection descriptors across the cluster. */
+    list(): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** One connection's descriptor, if present. */
+    get(connId: string): (ConnDescriptor | undefined) | Promise<ConnDescriptor | undefined>;
+    /** Descriptors for a given user key. */
+    byUser(userId: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Descriptors that are members of `room`. */
+    roomMembers(room: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): number | Promise<number>;
+    /** Per-node aggregates. */
+    topology(): NodeStat[] | Promise<NodeStat[]>;
 }
 
 /** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
@@ -80,12 +145,30 @@ interface ServerMessageDef {
     /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
     subscribe?: boolean;
 }
+/**
+ * A server→client request (request/response). The server sends `input`; the
+ * client's `implement` handler returns `output`. Lives in `serverToClient`
+ * alongside events and topics, distinguished by having `input`.
+ */
+interface ServerRequestDef {
+    /** Schema for the request payload the server sends. */
+    input: Schema;
+    /** Schema for the reply the client returns. */
+    output: Schema;
+}
+/** A `serverToClient` entry: a push event, a subscribable topic, or a server→client request. */
+type ServerEntry = ServerMessageDef | ServerRequestDef;
 /** The two directions within a `shared` or role block. */
 interface Directional {
     /** Requests this side may call (client→server). */
     clientToServer?: Record<string, RequestDef>;
-    /** Events/topics this side may receive (server→client). */
-    serverToClient?: Record<string, ServerMessageDef>;
+    /** Events, topics, and server→client requests this side may receive. */
+    serverToClient?: Record<string, ServerEntry>;
+}
+/** A role block: its directions plus an optional `data` schema typing `conn.data`. */
+interface RoleBlock extends Directional {
+    /** Schema for this role's mutable per-connection `conn.data` (server-side scratch state). */
+    data?: Schema;
 }
 /**
  * The single source of truth, imported by both server and client. Split by
@@ -96,7 +179,7 @@ interface Contract {
     /** Surface common to every role (merged into each role's effective surface). */
     shared?: Directional;
     /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
-    roles: Record<string, Directional>;
+    roles: Record<string, RoleBlock>;
     /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
     serverToServer?: Record<string, Schema>;
 }
@@ -129,10 +212,12 @@ type CtsOf<D> = D extends {
     clientToServer: infer M extends Record<string, RequestDef>;
 } ? M : {};
 type StcOf<D> = D extends {
-    serverToClient: infer M extends Record<string, ServerMessageDef>;
+    serverToClient: infer M extends Record<string, ServerEntry>;
 } ? M : {};
 type EventsOf<M> = {
     [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? never : M[K] extends {
         subscribe: true;
     } ? never : K]: M[K];
 };
@@ -141,6 +226,11 @@ type TopicsOf<M> = {
         subscribe: true;
     } ? K : never]: M[K];
 };
+type ServerReqOf<M> = {
+    [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? K : never]: M[K];
+};
 /** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
 type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
 /** A role's effective server→client map (events and topics combined). */
@@ -159,6 +249,16 @@ type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
 type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
 /** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
 type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
+/** A role's effective server→client requests (`shared` ∪ `roles[R]`), answered by `client.implement`. */
+type ServerRequests<C extends Contract, R extends RoleOf<C>> = ServerReqOf<ServerMessages<C, R>>;
+/** Server→client requests in the `shared` block (the surface `srv.toConn(id).request` can call). */
+type SharedServerRequests<C extends Contract> = ServerReqOf<StcOf<C['shared']>>;
+/** The typed shape of `conn.data` for role `R` (its `data` schema, or an empty object). */
+type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
+    data: infer S extends Schema;
+} ? InferOut<S> : Record<string, never>;
+/** Union of every role's `conn.data` shape (used where the role isn't narrowed, e.g. shared handlers). */
+type AnyData<C extends Contract> = DataOf<C, RoleOf<C>>;
 /** The `serverToServer` map, or `{}` if the contract has none. */
 type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
 /** The input type a client passes for a request (pre-validation). */
@@ -219,7 +319,19 @@ interface UnsubFrame {
     t: 'unsub';
     c: string;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface SResFrame {
+    t: 'sres';
+    i: number;
+    d: unknown;
+}
+interface SErrFrame {
+    t: 'serr';
+    i: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -242,7 +354,13 @@ interface PubFrame {
     c: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+interface SReqFrame {
+    t: 'sreq';
+    i: number;
+    m: string;
+    d: unknown;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };
+export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type NodeStat, type Output, PROTOCOL, type PresenceStore, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEntry, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.d.ts

@@ -55,6 +55,71 @@ interface Adapter {
     onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
     /** Optional teardown (e.g. close Redis connections). */
     close?(): void | Promise<void>;
+    /**
+     * Optional cluster-wide presence directory. Powers `srv.cluster.*` and
+     * `srv.isOnline`. The in-memory and Redis adapters implement it; cluster
+     * queries throw a clear error on an adapter that doesn't.
+     */
+    presence?: PresenceStore;
+}
+/** A serializable snapshot of a connection, shared cluster-wide via the {@link PresenceStore}. */
+interface ConnDescriptor {
+    /** The connection's server-assigned id. */
+    id: string;
+    /** The connection's role. */
+    role: string;
+    /** The node that holds this connection. */
+    nodeId: string;
+    /** When the connection was accepted (`Date.now()`). */
+    connectedAt: number;
+    /** The stable user key from the server's `identify` hook, if any. */
+    userId?: string;
+    /** Room memberships (topics and node-local `lastPongAt` are not included). */
+    rooms: string[];
+    /** Extra fields contributed by the server's `describeConn` hook. */
+    [extra: string]: unknown;
+}
+/** Per-node aggregate, returned by {@link PresenceStore.topology}. */
+interface NodeStat {
+    /** The node's id. */
+    nodeId: string;
+    /** Number of connections on the node. */
+    connections: number;
+    /** Number of distinct rooms with members on the node. */
+    rooms: number;
+    /** Whether the node is currently live (heartbeat fresh). */
+    alive: boolean;
+}
+/**
+ * Cluster-wide presence directory: a query/addressbook layer kept in the shared
+ * substrate (in-memory bus or Redis). Live message delivery does NOT read this —
+ * it exists only to answer `srv.cluster.*` / `srv.isOnline`.
+ */
+interface PresenceStore {
+    /** Record (or replace) a connection's descriptor. */
+    set(descriptor: ConnDescriptor): void | Promise<void>;
+    /** Remove a connection's descriptor. */
+    del(connId: string): void | Promise<void>;
+    /** Refresh this node's liveness (heartbeat). */
+    beat(nodeId: string): void | Promise<void>;
+    /** Remove all of a node's connections + liveness (graceful shutdown cleanup). */
+    clearNode(nodeId: string): void | Promise<void>;
+    /** Add a room to a connection's membership. */
+    addRoom(connId: string, room: string): void | Promise<void>;
+    /** Remove a room from a connection's membership. */
+    removeRoom(connId: string, room: string): void | Promise<void>;
+    /** All live connection descriptors across the cluster. */
+    list(): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** One connection's descriptor, if present. */
+    get(connId: string): (ConnDescriptor | undefined) | Promise<ConnDescriptor | undefined>;
+    /** Descriptors for a given user key. */
+    byUser(userId: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Descriptors that are members of `room`. */
+    roomMembers(room: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): number | Promise<number>;
+    /** Per-node aggregates. */
+    topology(): NodeStat[] | Promise<NodeStat[]>;
 }
 
 /** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
@@ -80,12 +145,30 @@ interface ServerMessageDef {
     /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
     subscribe?: boolean;
 }
+/**
+ * A server→client request (request/response). The server sends `input`; the
+ * client's `implement` handler returns `output`. Lives in `serverToClient`
+ * alongside events and topics, distinguished by having `input`.
+ */
+interface ServerRequestDef {
+    /** Schema for the request payload the server sends. */
+    input: Schema;
+    /** Schema for the reply the client returns. */
+    output: Schema;
+}
+/** A `serverToClient` entry: a push event, a subscribable topic, or a server→client request. */
+type ServerEntry = ServerMessageDef | ServerRequestDef;
 /** The two directions within a `shared` or role block. */
 interface Directional {
     /** Requests this side may call (client→server). */
     clientToServer?: Record<string, RequestDef>;
-    /** Events/topics this side may receive (server→client). */
-    serverToClient?: Record<string, ServerMessageDef>;
+    /** Events, topics, and server→client requests this side may receive. */
+    serverToClient?: Record<string, ServerEntry>;
+}
+/** A role block: its directions plus an optional `data` schema typing `conn.data`. */
+interface RoleBlock extends Directional {
+    /** Schema for this role's mutable per-connection `conn.data` (server-side scratch state). */
+    data?: Schema;
 }
 /**
  * The single source of truth, imported by both server and client. Split by
@@ -96,7 +179,7 @@ interface Contract {
     /** Surface common to every role (merged into each role's effective surface). */
     shared?: Directional;
     /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
-    roles: Record<string, Directional>;
+    roles: Record<string, RoleBlock>;
     /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
     serverToServer?: Record<string, Schema>;
 }
@@ -129,10 +212,12 @@ type CtsOf<D> = D extends {
     clientToServer: infer M extends Record<string, RequestDef>;
 } ? M : {};
 type StcOf<D> = D extends {
-    serverToClient: infer M extends Record<string, ServerMessageDef>;
+    serverToClient: infer M extends Record<string, ServerEntry>;
 } ? M : {};
 type EventsOf<M> = {
     [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? never : M[K] extends {
         subscribe: true;
     } ? never : K]: M[K];
 };
@@ -141,6 +226,11 @@ type TopicsOf<M> = {
         subscribe: true;
     } ? K : never]: M[K];
 };
+type ServerReqOf<M> = {
+    [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? K : never]: M[K];
+};
 /** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
 type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
 /** A role's effective server→client map (events and topics combined). */
@@ -159,6 +249,16 @@ type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
 type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
 /** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
 type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
+/** A role's effective server→client requests (`shared` ∪ `roles[R]`), answered by `client.implement`. */
+type ServerRequests<C extends Contract, R extends RoleOf<C>> = ServerReqOf<ServerMessages<C, R>>;
+/** Server→client requests in the `shared` block (the surface `srv.toConn(id).request` can call). */
+type SharedServerRequests<C extends Contract> = ServerReqOf<StcOf<C['shared']>>;
+/** The typed shape of `conn.data` for role `R` (its `data` schema, or an empty object). */
+type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
+    data: infer S extends Schema;
+} ? InferOut<S> : Record<string, never>;
+/** Union of every role's `conn.data` shape (used where the role isn't narrowed, e.g. shared handlers). */
+type AnyData<C extends Contract> = DataOf<C, RoleOf<C>>;
 /** The `serverToServer` map, or `{}` if the contract has none. */
 type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
 /** The input type a client passes for a request (pre-validation). */
@@ -219,7 +319,19 @@ interface UnsubFrame {
     t: 'unsub';
     c: string;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface SResFrame {
+    t: 'sres';
+    i: number;
+    d: unknown;
+}
+interface SErrFrame {
+    t: 'serr';
+    i: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -242,7 +354,13 @@ interface PubFrame {
     c: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+interface SReqFrame {
+    t: 'sreq';
+    i: number;
+    m: string;
+    d: unknown;
+}
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };
+export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type NodeStat, type Output, PROTOCOL, type PresenceStore, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEntry, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Shared contract, validation, wire protocol and errors for super-line.",
   "license": "MIT",