@super-line/core 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -78,6 +78,11 @@ interface ConnDescriptor {
     userId?: string;
     /** Room memberships (topics and node-local `lastPongAt` are not included). */
     rooms: string[];
+    /**
+     * The client↔server transport (wire) this connection was accepted on:
+     * `'websocket' | 'sse' | 'longpoll' | 'libp2p' | 'loopback'`. Absent on conns from older nodes.
+     */
+    transport?: string;
     /** Extra fields contributed by the server's `describeConn` hook. */
     [extra: string]: unknown;
 }
@@ -498,7 +503,13 @@ interface SErrFrame {
     m: string;
     d?: unknown;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
+interface PingFrame {
+    t: 'ping';
+}
+interface PongFrame {
+    t: 'pong';
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | PingFrame | PongFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -528,7 +539,85 @@ interface SReqFrame {
     m: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | PingFrame | PongFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, 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 SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };
+/**
+ * The client↔server transport seam. A transport moves opaque encoded bytes over a
+ * LOGICAL connection and hides all physical churn (reconnects, SSE's dual channel,
+ * libp2p signaling). The serializer and the frame protocol stay in core, above the
+ * transport — a transport never inspects a frame, it only carries bytes.
+ */
+/** A live logical connection, from the core's point of view. Symmetric across server + client. */
+interface RawConn {
+    /** Send already-encoded bytes. A no-op when not {@link RawConn.writable}. */
+    send(bytes: string | Uint8Array): void;
+    /** Whether a send will be accepted now (WS derives this from `readyState` + `bufferedAmount`). */
+    readonly writable: boolean;
+    /** Register the handler for inbound frames. The transport MUST normalize each to a `Uint8Array`. */
+    onMessage(cb: (bytes: Uint8Array) => void): void;
+    /** The logical connection died. `code` is best-effort (1000 graceful / 1006 abnormal when the transport has none). */
+    onClose(cb: (code: number, reason?: string) => void): void;
+    /** The send buffer drained below the limit — safe to resume sending. */
+    onDrain(cb: () => void): void;
+    /** Graceful close (close handshake when the transport has one). */
+    close(code?: number, reason?: string): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
+}
+/**
+ * The normalized handshake handed to `authenticate`, replacing the raw `IncomingMessage`.
+ * Each transport fills what it has: ws/sse populate `headers`/`query`; libp2p/webrtc
+ * populate `peer`. `raw` is the transport-specific escape hatch.
+ */
+interface Handshake {
+    /** Transport id, e.g. `'websocket'` | `'loopback'` | `'sse'` | `'libp2p'`. */
+    transport: string;
+    /** Request headers (ws/sse fill these; peer transports leave them sparse). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Role + params, decoded uniformly (WS reads them from the URL query string). */
+    query: Record<string, string>;
+    /** Peer identity, for transports that authenticate one (libp2p/webrtc). */
+    peer?: {
+        id: string;
+        addr?: string;
+    };
+    /** Escape hatch: the `IncomingMessage` for WS, the signaling payload for libp2p, etc. */
+    raw: unknown;
+}
+/**
+ * What `authenticate` returns. Reject by throwing — the transport then rejects in its native idiom.
+ * `transport` is injected by the server (from {@link Handshake.transport}); user `authenticate`
+ * callbacks return only `role` + `ctx`.
+ */
+type AuthOutcome = {
+    role: string;
+    ctx: unknown;
+    transport?: string;
+};
+/**
+ * Server side: the transport listens, authenticates each inbound connection at its
+ * native moment, and surfaces only the accepted ones — so the core never holds an
+ * unauthenticated connection.
+ */
+interface ServerTransport {
+    start(hooks: {
+        /** Core owns the decision; the transport calls this at its native auth point and rejects natively on throw. */
+        authenticate: (h: Handshake) => Promise<AuthOutcome>;
+        /** Fires ONLY for accepted connections. */
+        onConnection: (raw: RawConn, auth: AuthOutcome) => void;
+    }): void | Promise<void>;
+    /** Stop listening and drop in-flight connections. */
+    stop(): void | Promise<void>;
+}
+/** Client side: dial the server, encoding `handshakeParams` (role + params) in the transport's native form. */
+interface ClientTransport {
+    connect(handshakeParams: Record<string, string>, hooks: {
+        onOpen(): void;
+        onMessage(bytes: Uint8Array): void;
+        onClose(code: number): void;
+        onDrain(): void;
+    }): RawConn;
+}
+
+export { type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PingFrame, type PongFrame, type PresenceStore, type PubFrame, type RawConn, 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 SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.d.ts

@@ -78,6 +78,11 @@ interface ConnDescriptor {
     userId?: string;
     /** Room memberships (topics and node-local `lastPongAt` are not included). */
     rooms: string[];
+    /**
+     * The client↔server transport (wire) this connection was accepted on:
+     * `'websocket' | 'sse' | 'longpoll' | 'libp2p' | 'loopback'`. Absent on conns from older nodes.
+     */
+    transport?: string;
     /** Extra fields contributed by the server's `describeConn` hook. */
     [extra: string]: unknown;
 }
@@ -498,7 +503,13 @@ interface SErrFrame {
     m: string;
     d?: unknown;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
+interface PingFrame {
+    t: 'ping';
+}
+interface PongFrame {
+    t: 'pong';
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame | PingFrame | PongFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -528,7 +539,85 @@ interface SReqFrame {
     m: string;
     d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame | PingFrame | PongFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, 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 SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };
+/**
+ * The client↔server transport seam. A transport moves opaque encoded bytes over a
+ * LOGICAL connection and hides all physical churn (reconnects, SSE's dual channel,
+ * libp2p signaling). The serializer and the frame protocol stay in core, above the
+ * transport — a transport never inspects a frame, it only carries bytes.
+ */
+/** A live logical connection, from the core's point of view. Symmetric across server + client. */
+interface RawConn {
+    /** Send already-encoded bytes. A no-op when not {@link RawConn.writable}. */
+    send(bytes: string | Uint8Array): void;
+    /** Whether a send will be accepted now (WS derives this from `readyState` + `bufferedAmount`). */
+    readonly writable: boolean;
+    /** Register the handler for inbound frames. The transport MUST normalize each to a `Uint8Array`. */
+    onMessage(cb: (bytes: Uint8Array) => void): void;
+    /** The logical connection died. `code` is best-effort (1000 graceful / 1006 abnormal when the transport has none). */
+    onClose(cb: (code: number, reason?: string) => void): void;
+    /** The send buffer drained below the limit — safe to resume sending. */
+    onDrain(cb: () => void): void;
+    /** Graceful close (close handshake when the transport has one). */
+    close(code?: number, reason?: string): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
+}
+/**
+ * The normalized handshake handed to `authenticate`, replacing the raw `IncomingMessage`.
+ * Each transport fills what it has: ws/sse populate `headers`/`query`; libp2p/webrtc
+ * populate `peer`. `raw` is the transport-specific escape hatch.
+ */
+interface Handshake {
+    /** Transport id, e.g. `'websocket'` | `'loopback'` | `'sse'` | `'libp2p'`. */
+    transport: string;
+    /** Request headers (ws/sse fill these; peer transports leave them sparse). */
+    headers: Record<string, string | string[] | undefined>;
+    /** Role + params, decoded uniformly (WS reads them from the URL query string). */
+    query: Record<string, string>;
+    /** Peer identity, for transports that authenticate one (libp2p/webrtc). */
+    peer?: {
+        id: string;
+        addr?: string;
+    };
+    /** Escape hatch: the `IncomingMessage` for WS, the signaling payload for libp2p, etc. */
+    raw: unknown;
+}
+/**
+ * What `authenticate` returns. Reject by throwing — the transport then rejects in its native idiom.
+ * `transport` is injected by the server (from {@link Handshake.transport}); user `authenticate`
+ * callbacks return only `role` + `ctx`.
+ */
+type AuthOutcome = {
+    role: string;
+    ctx: unknown;
+    transport?: string;
+};
+/**
+ * Server side: the transport listens, authenticates each inbound connection at its
+ * native moment, and surfaces only the accepted ones — so the core never holds an
+ * unauthenticated connection.
+ */
+interface ServerTransport {
+    start(hooks: {
+        /** Core owns the decision; the transport calls this at its native auth point and rejects natively on throw. */
+        authenticate: (h: Handshake) => Promise<AuthOutcome>;
+        /** Fires ONLY for accepted connections. */
+        onConnection: (raw: RawConn, auth: AuthOutcome) => void;
+    }): void | Promise<void>;
+    /** Stop listening and drop in-flight connections. */
+    stop(): void | Promise<void>;
+}
+/** Client side: dial the server, encoding `handshakeParams` (role + params) in the transport's native form. */
+interface ClientTransport {
+    connect(handshakeParams: Record<string, string>, hooks: {
+        onOpen(): void;
+        onMessage(bytes: Uint8Array): void;
+        onClose(code: number): void;
+        onDrain(): void;
+    }): RawConn;
+}
+
+export { type Adapter, type AnyData, type AuthOutcome, type ClientFrame, type ClientInput, type ClientTransport, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type Handshake, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PingFrame, type PongFrame, type PresenceStore, type PubFrame, type RawConn, 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 SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type ServerTransport, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/package.json

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