@hydranium/data-client-vscode 1.0.0-next.322 → 1.0.0-next.323

package/README.md

@@ -16,6 +16,8 @@ to it over a `vscode-messenger` hop, and the webview's data port reads it.
 - The webview's `DataPort`, for the connection and sessions from
   `@hydranium/protocol`, which rejects pending requests when the extension host
   reports the relay lost.
+- A `DataPort` over a socket for code in the extension host itself, such as a
+  command, which looks the port up again for every connection.
 
 ## Install
 
@@ -78,6 +80,22 @@ messenger.start();
 const connection = new DataConnectionWithEvents(port);
 ```
 
+For code in the extension host itself, give the connection a `SocketDataPort`
+instead, which opens the socket there; nothing connects until the first
+request:
+
+<!-- snippet-preamble
+declare function findDataServerPort(): Promise<number>;
+-->
+
+```ts
+import { SocketDataPort } from '@hydranium/data-client-vscode/node';
+import { DataConnectionWithEvents } from '@hydranium/protocol';
+
+const port = new SocketDataPort({ findPort: findDataServerPort });
+const connection = new DataConnectionWithEvents(port);
+```
+
 To test a webview's data path in Node, `makeMessengerHarness` from `./testing`
 joins the real extension-side and webview-side messengers through a fake
 panel and a fake `window`, so the test runs their real routing.
@@ -90,7 +108,7 @@ For the whole setup, see *Host in VS Code* in
 | Subpath     | Use it for                                    | Runs in                    |
 | ----------- | --------------------------------------------- | -------------------------- |
 | `.`         | The messenger channel both ends build on      | anywhere                   |
-| `./node`    | The relay from the data-server's socket       | the VS Code extension host |
+| `./node`    | The relay, and the extension host's own port  | the VS Code extension host |
 | `./browser` | The webview's data port                       | a webview                  |
 | `./testing` | The real messenger pair joined in a Node test | a test                     |
 

package/lib/node/index.d.ts

@@ -7,4 +7,5 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 export * from './data-server-connection';
+export * from './socket-data-port';
 //# sourceMappingURL=index.d.ts.map

package/lib/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}

package/lib/node/index.js

@@ -23,4 +23,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./data-server-connection"), exports);
+__exportStar(require("./socket-data-port"), exports);
 //# sourceMappingURL=index.js.map

package/lib/node/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,2DAAyC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,2DAAyC;AACzC,qDAAmC"}

package/lib/node/socket-data-port.d.ts

@@ -0,0 +1,54 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type DataPort, type Logger, type ResolvedMessage } from '@hydranium/protocol';
+import { Emitter } from 'vscode-jsonrpc';
+import { type MessageConnection } from 'vscode-jsonrpc/node';
+/** What {@link SocketDataPort} needs from the host. */
+export interface SocketDataPortOptions {
+    /**
+     * Resolve the data-server's listening port. Called once per connection
+     * generation, so a restarted server is re-discovered rather than cached.
+     */
+    readonly findPort: () => Promise<number>;
+    /** The data-server's host. Defaults to the loopback address. */
+    readonly host?: string;
+    /** Where the connection logs its protocol faults, and what it does on its own. */
+    readonly logger?: Logger;
+    /** Surface a failure to the user. Defaults to the logger, else the console. */
+    readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
+}
+/**
+ * A {@link DataPort} over a socket to the data-server, for code in the
+ * extension host itself, such as a command. A webview has no `net`; it takes
+ * `WebviewDataPort` over `connectDataServer` instead.
+ *
+ * Each generation opens its own socket and closes the one before, without
+ * firing {@link onDispose} for it; of two overlapping calls, the one that
+ * settles last keeps its socket. A socket the server ends under the current
+ * generation fires it, so `DataConnection` reconnects to the port
+ * {@link SocketDataPortOptions.findPort} finds next.
+ */
+export declare class SocketDataPort implements DataPort {
+    protected readonly options: SocketDataPortOptions;
+    protected readonly disposeEmitter: Emitter<void>;
+    readonly onDispose: import("vscode-jsonrpc").Event<void>;
+    readonly logger?: Logger;
+    protected disposed: boolean;
+    protected current?: {
+        readonly connection: MessageConnection;
+        readonly dispose: () => void;
+    };
+    constructor(options: SocketDataPortOptions);
+    connect(): Promise<MessageConnection>;
+    reportError(error: unknown, reported: ResolvedMessage): void;
+    /** The consumer hears it first; then the current socket closes. */
+    dispose(): void;
+    protected closeCurrent(): void;
+}
+//# sourceMappingURL=socket-data-port.d.ts.map

package/lib/node/socket-data-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-data-port.d.ts","sourceRoot":"","sources":["../../src/node/socket-data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA0B,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;CAC7E;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAOhC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,qBAAqB;IAN7D,SAAS,CAAC,QAAQ,CAAC,cAAc,gBAAuB;IACxD,QAAQ,CAAC,SAAS,uCAA6B;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,QAAQ,UAAS;IAC3B,SAAS,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAE7F,YAA+B,OAAO,EAAE,qBAAqB,EAE5D;IAEK,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CA6B1C;IAED,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQ3D;IAED,mEAAmE;IACnE,OAAO,IAAI,IAAI,CAQd;IAED,SAAS,CAAC,YAAY,IAAI,IAAI,CAI7B;CACH"}

package/lib/node/socket-data-port.js

@@ -0,0 +1,96 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketDataPort = void 0;
+const protocol_1 = require("@hydranium/protocol");
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+const node_1 = require("vscode-jsonrpc/node");
+const data_server_connection_1 = require("./data-server-connection");
+/**
+ * A {@link DataPort} over a socket to the data-server, for code in the
+ * extension host itself, such as a command. A webview has no `net`; it takes
+ * `WebviewDataPort` over `connectDataServer` instead.
+ *
+ * Each generation opens its own socket and closes the one before, without
+ * firing {@link onDispose} for it; of two overlapping calls, the one that
+ * settles last keeps its socket. A socket the server ends under the current
+ * generation fires it, so `DataConnection` reconnects to the port
+ * {@link SocketDataPortOptions.findPort} finds next.
+ */
+class SocketDataPort {
+    options;
+    disposeEmitter = new vscode_jsonrpc_1.Emitter();
+    onDispose = this.disposeEmitter.event;
+    logger;
+    disposed = false;
+    current;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger;
+    }
+    async connect() {
+        if (this.disposed) {
+            throw new Error('SocketDataPort: the port is disposed');
+        }
+        const transport = await (0, data_server_connection_1.openSocketTransport)(await this.options.findPort(), this.options.host);
+        // Disposed while the socket opened: nothing would close this one.
+        if (this.disposed) {
+            transport.dispose?.();
+            throw new Error('SocketDataPort: the port is disposed');
+        }
+        // The one before, or an overlapping call's that was installed meanwhile.
+        this.closeCurrent();
+        const connection = (0, node_1.createMessageConnection)(transport.reader, transport.writer, this.logger);
+        const current = {
+            connection,
+            dispose: () => {
+                connection.dispose();
+                transport.dispose?.();
+            }
+        };
+        this.current = current;
+        connection.onClose(() => {
+            if (this.current === current) {
+                this.closeCurrent();
+                this.disposeEmitter.fire();
+            }
+        });
+        connection.listen();
+        return connection;
+    }
+    reportError(error, reported) {
+        if (this.options.reportError) {
+            this.options.reportError(error, reported);
+        }
+        else if (this.logger) {
+            this.logger.error((0, protocol_1.renderFrameworkMessage)(reported), error);
+        }
+        else {
+            console.error(`[data head] ${(0, protocol_1.renderFrameworkMessage)(reported)}`, error);
+        }
+    }
+    /** The consumer hears it first; then the current socket closes. */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.disposeEmitter.fire();
+        this.disposeEmitter.dispose();
+        this.closeCurrent();
+    }
+    closeCurrent() {
+        const current = this.current;
+        this.current = undefined;
+        current?.dispose();
+    }
+}
+exports.SocketDataPort = SocketDataPort;
+//# sourceMappingURL=socket-data-port.js.map

package/lib/node/socket-data-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-data-port.js","sourceRoot":"","sources":["../../src/node/socket-data-port.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/data-client-vscode",
-  "version": "1.0.0-next.322",
+  "version": "1.0.0-next.323",
   "description": "VS Code client primitives for the hydranium data-server protocol head; companion of @hydranium/data-server. The extension host relays the data-server's socket to a webview over a vscode-messenger hop, and the webview's data port reads it, so DataConnection and DataSession run unchanged in a webview.",
   "keywords": [
     "hydranium",
@@ -63,7 +63,7 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/protocol": "1.0.0-next.322",
+    "@hydranium/protocol": "1.0.0-next.323",
     "@types/node": "^22.0.0",
     "@types/vscode": "^1.101.0",
     "rimraf": "^5.0.0",
@@ -74,7 +74,7 @@
     "vscode-messenger-webview": "^0.4.5"
   },
   "peerDependencies": {
-    "@hydranium/protocol": "1.0.0-next.322",
+    "@hydranium/protocol": "1.0.0-next.323",
     "vscode-jsonrpc": "^9.0.0",
     "vscode-messenger": "^0.4.5",
     "vscode-messenger-common": "^0.4.5",

package/src/node/index.ts

@@ -8,3 +8,4 @@
  ********************************************************************************/
 
 export * from './data-server-connection';
+export * from './socket-data-port';

package/src/node/socket-data-port.ts

@@ -0,0 +1,109 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { renderFrameworkMessage, type DataPort, type Logger, type ResolvedMessage } from '@hydranium/protocol';
+import { Emitter } from 'vscode-jsonrpc';
+import { createMessageConnection, type MessageConnection } from 'vscode-jsonrpc/node';
+import { openSocketTransport } from './data-server-connection';
+
+/** What {@link SocketDataPort} needs from the host. */
+export interface SocketDataPortOptions {
+   /**
+    * Resolve the data-server's listening port. Called once per connection
+    * generation, so a restarted server is re-discovered rather than cached.
+    */
+   readonly findPort: () => Promise<number>;
+   /** The data-server's host. Defaults to the loopback address. */
+   readonly host?: string;
+   /** Where the connection logs its protocol faults, and what it does on its own. */
+   readonly logger?: Logger;
+   /** Surface a failure to the user. Defaults to the logger, else the console. */
+   readonly reportError?: (error: unknown, reported: ResolvedMessage) => void;
+}
+
+/**
+ * A {@link DataPort} over a socket to the data-server, for code in the
+ * extension host itself, such as a command. A webview has no `net`; it takes
+ * `WebviewDataPort` over `connectDataServer` instead.
+ *
+ * Each generation opens its own socket and closes the one before, without
+ * firing {@link onDispose} for it; of two overlapping calls, the one that
+ * settles last keeps its socket. A socket the server ends under the current
+ * generation fires it, so `DataConnection` reconnects to the port
+ * {@link SocketDataPortOptions.findPort} finds next.
+ */
+export class SocketDataPort implements DataPort {
+   protected readonly disposeEmitter = new Emitter<void>();
+   readonly onDispose = this.disposeEmitter.event;
+   readonly logger?: Logger;
+   protected disposed = false;
+   protected current?: { readonly connection: MessageConnection; readonly dispose: () => void };
+
+   constructor(protected readonly options: SocketDataPortOptions) {
+      this.logger = options.logger;
+   }
+
+   async connect(): Promise<MessageConnection> {
+      if (this.disposed) {
+         throw new Error('SocketDataPort: the port is disposed');
+      }
+      const transport = await openSocketTransport(await this.options.findPort(), this.options.host);
+      // Disposed while the socket opened: nothing would close this one.
+      if (this.disposed) {
+         transport.dispose?.();
+         throw new Error('SocketDataPort: the port is disposed');
+      }
+      // The one before, or an overlapping call's that was installed meanwhile.
+      this.closeCurrent();
+      const connection = createMessageConnection(transport.reader, transport.writer, this.logger);
+      const current = {
+         connection,
+         dispose: () => {
+            connection.dispose();
+            transport.dispose?.();
+         }
+      };
+      this.current = current;
+      connection.onClose(() => {
+         if (this.current === current) {
+            this.closeCurrent();
+            this.disposeEmitter.fire();
+         }
+      });
+      connection.listen();
+      return connection;
+   }
+
+   reportError(error: unknown, reported: ResolvedMessage): void {
+      if (this.options.reportError) {
+         this.options.reportError(error, reported);
+      } else if (this.logger) {
+         this.logger.error(renderFrameworkMessage(reported), error);
+      } else {
+         console.error(`[data head] ${renderFrameworkMessage(reported)}`, error);
+      }
+   }
+
+   /** The consumer hears it first; then the current socket closes. */
+   dispose(): void {
+      if (this.disposed) {
+         return;
+      }
+      this.disposed = true;
+      this.disposeEmitter.fire();
+      this.disposeEmitter.dispose();
+      this.closeCurrent();
+   }
+
+   protected closeCurrent(): void {
+      const current = this.current;
+      this.current = undefined;
+      current?.dispose();
+   }
+}