@hediet/linkrpc-hub 0.0.1

package/dist/hub/server/node/index.d.ts

@@ -0,0 +1,218 @@
+import { IMessageTransport, JsonRpcMessage } from "@hediet/linkrpc";
+import { ITransportServer, Transport } from "@hediet/linkrpc/hub/common";
+import { TopologyTransportInfo } from "@hediet/linkrpc/inspection";
+import * as net from "node:net";
+import * as http from "node:http";
+import { WebSocket } from "ws";
+//#region src/hub/server/node/socketServer.d.ts
+/**
+ * A {@link Transport} over a Node socket that still exposes the underlying
+ * {@link net.Socket}. Provenance providers (peercred, etc.) read `socket`;
+ * the hub core never does. Framing is newline-delimited JSON, and the
+ * connection has already completed the `hubrpc::initialize` handshake.
+ */
+declare class NodeSocketTransport implements Transport {
+  readonly socket: net.Socket;
+  private readonly _inner;
+  readonly topologyInfo?: TopologyTransportInfo | undefined;
+  private readonly _closeHandlers;
+  private _closed;
+  /**
+   * Token presented by the peer in the `hubrpc::initialize` handshake. When
+   * the server was started with {@link SocketServerOptions.isTokenAccepted}
+   * the token has already been validated (the connection would otherwise have
+   * been dropped); a {@link ConnectionProvenanceProvider} can read it to
+   * further attest the peer (e.g. map a one-shot run token to an identity).
+   * `undefined` when the handshake carried no token.
+   */
+  initializeToken: string | undefined;
+  constructor(socket: net.Socket, _inner: IMessageTransport, topologyInfo?: TopologyTransportInfo | undefined);
+  send(message: JsonRpcMessage): void | Promise<void>;
+  setListener(listener: ((message: JsonRpcMessage) => void) | undefined): void;
+  onDidClose(handler: () => void): void;
+  dispose(): void;
+  private _fireClose;
+}
+interface SocketServerOptions {
+  /**
+   * Named pipe (Windows) / UDS path (Unix) to listen on. Defaults to a
+   * per-instance computed path.
+   */
+  readonly endpoint?: string;
+  /**
+   * Validate the token presented in the client's `hubrpc::initialize`
+   * handshake. Resolve `true` to admit the connection, `false` to reject it
+   * (the socket is dropped before it reaches the connection handler). Called
+   * live on every connection, so a dynamic allow-list (e.g. one-shot run
+   * tokens added for the lifetime of a spawned child) is re-read per connect.
+   *
+   * Omit to accept any token: the handshake is still required and the token
+   * is captured onto {@link NodeSocketTransport.initializeToken} for a
+   * provenance provider, but it is not gated.
+   */
+  readonly isTokenAccepted?: (token: string | undefined) => Promise<boolean>;
+}
+/**
+ * A hub-agnostic {@link ITransportServer} over a named pipe / UDS. It listens,
+ * accepts, runs the `hubrpc::initialize` handshake (authentication + protocol
+ * negotiation), frames each socket as a {@link NodeSocketTransport}, and hands
+ * it to the connection handler — no hub coupling. Compose
+ * attestation/identity on top via `withProvenance` and
+ * {@link HubConnectionAcceptor}.
+ *
+ * The handshake's token is validated via
+ * {@link SocketServerOptions.isTokenAccepted} when provided; otherwise any
+ * token is accepted and merely captured for a provenance provider.
+ */
+declare class SocketServer implements ITransportServer<NodeSocketTransport> {
+  private readonly _server;
+  private readonly _endpoint;
+  private readonly _live;
+  private readonly _isTokenAccepted;
+  private _handler;
+  private _disposed;
+  private constructor();
+  /** Bind + listen (with stale-UDS unlink retry), resolving once ready. */
+  static start(options?: SocketServerOptions): Promise<SocketServer>;
+  /** Allocate a fresh, unused socket path (named pipe on Windows, UDS elsewhere). */
+  static allocSocketPath(): string;
+  get endpoint(): string;
+  setConnectionHandler(handler: (transport: NodeSocketTransport) => void): void;
+  dispose(): void;
+  private _onConnection;
+  /**
+   * Run the `hubrpc::initialize` handshake on the freshly accepted socket,
+   * then frame it as a {@link NodeSocketTransport} and hand it to the
+   * connection handler. A failed handshake (bad/missing token, wrong first
+   * message, or timeout) drops the socket without reaching the handler.
+   */
+  private _acceptConnection;
+  private _listenWithRetry;
+  private _listenOnce;
+}
+//#endregion
+//#region src/hub/server/node/webSocketServer.d.ts
+/**
+ * A {@link Transport} over a server-side `ws` WebSocket. One JSON-RPC message
+ * per text frame; binary frames are decoded as UTF-8 and unparseable frames
+ * are dropped (the same lenient behaviour as {@link NodeSocketTransport}).
+ *
+ * The transport takes ownership of the socket: {@link dispose} closes it, and
+ * a peer close / error fires {@link onDidClose} handlers exactly once.
+ */
+declare class NodeWebSocketTransport implements Transport {
+  readonly socket: WebSocket;
+  readonly topologyInfo?: TopologyTransportInfo | undefined;
+  private _listener;
+  private readonly _buffer;
+  private readonly _closeHandlers;
+  private _closed;
+  /**
+   * Token presented by the peer in the `hubrpc::initialize` handshake, when
+   * the server ran one. A {@link ConnectionProvenanceProvider} can read it to
+   * attest the peer. `undefined` when the handshake carried no token.
+   */
+  initializeToken: string | undefined;
+  constructor(socket: WebSocket, topologyInfo?: TopologyTransportInfo | undefined);
+  send(message: JsonRpcMessage): void;
+  setListener(listener: ((m: JsonRpcMessage) => void) | undefined): void;
+  onDidClose(handler: () => void): void;
+  dispose(): void;
+  private _fireClose;
+  private _deliver;
+}
+type WebSocketServerEvent = {
+  readonly kind: 'accepted';
+  readonly remoteAddress: string | undefined;
+} | {
+  readonly kind: 'rejected';
+  readonly reason: string;
+  readonly remoteAddress: string | undefined;
+} | {
+  readonly kind: 'closed';
+  readonly remoteAddress: string | undefined;
+};
+interface WebSocketServerOptions {
+  /** TCP port to listen on. Defaults to an OS-assigned free port (`0`). */
+  readonly port?: number;
+  /** Host/interface to bind. Defaults to all interfaces. */
+  readonly host?: string;
+  /**
+   * Validate the token presented in the client's `hubrpc::initialize`
+   * handshake. Resolve `true` to admit the connection, `false` to reject it.
+   * Required unless {@link allowAnonymous} is set. Browsers cannot set the
+   * `Authorization` header on the `WebSocket` constructor, so auth happens
+   * over the in-band handshake rather than the HTTP upgrade.
+   */
+  readonly isTokenAccepted?: (token: string | undefined) => Promise<boolean>;
+  /**
+   * Allow connections without validating a token: the `hubrpc::initialize`
+   * handshake still runs (and its token is captured), but any token is
+   * accepted. Use ONLY behind a trusted reverse proxy that performs auth
+   * itself, or on a private interface.
+   */
+  readonly allowAnonymous?: boolean;
+  /**
+   * Optional `Origin` allow-list for browser clients. When set, the upgrade
+   * is rejected if `Origin` is present and not in the list. Non-browser
+   * clients (which send no `Origin`) are unaffected.
+   */
+  readonly allowedOrigins?: readonly string[];
+  /**
+   * URL path the WebSocket endpoint is mounted at. Defaults to `/`. Any
+   * other path gets a `404`, so the same server can host health checks.
+   */
+  readonly path?: string;
+  /** Bytes. Frames larger than this close the connection. Defaults to 16 MiB. */
+  readonly maxPayload?: number;
+  /** Optional logger called on accept / reject / close. */
+  readonly onEvent?: (event: WebSocketServerEvent) => void;
+  /**
+   * Optional handler for ordinary (non-upgrade) HTTP requests on the same
+   * port. An Express app is a valid {@link http.RequestListener}, so this
+   * lets the WebSocket endpoint and e.g. a `/health` route share one port.
+   * Defaults to replying `426 upgrade required` to every request.
+   */
+  readonly requestListener?: http.RequestListener;
+}
+/**
+ * A hub-agnostic {@link ITransportServer} over WebSocket. It owns an
+ * `http.Server`, gates each upgrade by origin, runs the `hubrpc::initialize`
+ * handshake (authentication + protocol negotiation) over each accepted socket,
+ * and frames it as a {@link NodeWebSocketTransport}. Compose identity/claim
+ * policy on top via {@link HubConnectionAcceptor} — this server never couples
+ * to the hub.
+ *
+ * Sibling of {@link SocketServer} (named pipe / UDS) for reaching the hub from
+ * outside the host over `ws://` / `wss://`.
+ */
+declare class WebSocketServer implements ITransportServer<NodeWebSocketTransport> {
+  private readonly _opts;
+  private readonly _httpServer;
+  private readonly _wss;
+  private readonly _path;
+  private readonly _attached;
+  private readonly _sockets;
+  private _handler;
+  private _disposed;
+  private constructor();
+  /** Bind + listen, resolving once the port is open. */
+  static start(options?: WebSocketServerOptions): Promise<WebSocketServer>;
+  /** The bound port (resolved even when started with port `0`). */
+  get port(): number;
+  setConnectionHandler(handler: (transport: NodeWebSocketTransport) => void): void;
+  dispose(): void;
+  private _onUpgrade;
+  private _onConnection;
+  /**
+   * Frame the upgraded socket, run the `hubrpc::initialize` handshake
+   * (authentication + protocol negotiation), then hand the transport to the
+   * connection handler. A failed handshake (bad/missing token, wrong first
+   * message, or timeout) drops the socket without reaching the handler.
+   */
+  private _acceptConnection;
+  private _reject;
+}
+//#endregion
+export { NodeSocketTransport, NodeWebSocketTransport, SocketServer, type SocketServerOptions, WebSocketServer, type WebSocketServerEvent, type WebSocketServerOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/hub/server/node/index.js

@@ -0,0 +1,2 @@
+import { i as SocketServer, n as WebSocketServer, r as NodeSocketTransport, t as NodeWebSocketTransport } from "../../../chunks/node-CTXsQ6oa.js";
+export { NodeSocketTransport, NodeWebSocketTransport, SocketServer, WebSocketServer };

package/dist/hub/server/transit.d.ts

@@ -0,0 +1,2 @@
+import { v as tapTransport } from "../../chunks/nodeTransit-cmtZgdpW.js";
+export { tapTransport };

package/dist/hub/server/transit.js

@@ -0,0 +1,2 @@
+import { a as tapTransport } from "../../chunks/nodeTransit-CWeFnbwt.js";
+export { tapTransport };