@hydranium/protocol 1.0.0-next.24 → 1.0.0-next.242

package/lib/client/data-port.d.ts

@@ -7,14 +7,20 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import type { Event, MessageConnection } from 'vscode-jsonrpc';
+import type { Logger } from '../logger';
+import type { ResolvedMessage } from '../messages/primitives';
+import type { RpcConnectionLifecycle } from './rpc-connection';
 /**
  * The one thing a host has to supply for the data head: a live JSON-RPC
- * connection to the data server, plus the identity and failure sink that go
- * with it.
+ * connection to the data server, plus the failure sink that goes with it.
  *
- * "Port" in the hexagonal sense — the host implements it, `DataSession`
+ * "Port" in the hexagonal sense — the host implements it, `DataConnection`
  * consumes it, and nothing on either side of the boundary imports the other.
  *
+ * Carries no identity. A `clientId` names a participant, and one transport
+ * serves as many as the host has; binding an identity here is what makes two
+ * of them share one, so it lives on `DataSession` instead.
+ *
  * **This deliberately does NOT wrap the protocol methods.** `createRpcProxy`
  * already takes a promise of a connection and produces the whole typed
  * `DataServerProtocol` surface, so wrapping it would re-derive the framework's
@@ -22,7 +28,7 @@ import type { Event, MessageConnection } from 'vscode-jsonrpc';
  * method allowlists, which cannot drift. Everything a form or a tree actually
  * does — the wire contract, the open/watch/update/close sequence, `baseVersion`
  * conflict handling, echo filtering by `sourceClientId` — is host-invariant and
- * lives above this interface. What varies between hosts is exactly the four
+ * lives above this interface. What varies between hosts is exactly the
  * members below.
  *
  * **Why the transport hop and not merely the protocol.** In a Theia frontend
@@ -43,28 +49,25 @@ import type { Event, MessageConnection } from 'vscode-jsonrpc';
  *   calls on the promise but never calls `listen` itself.
  */
 export interface DataPort {
-    /**
-     * Stable identity of this client on the data server, passed as `clientId`
-     * on every document request.
-     *
-     * It has to be stable for the session because it is the echo key: an
-     * inbound `onDocumentUpdated` carries the originating mutation's
-     * `clientId` as `sourceClientId`, and a client that cannot recognise its
-     * own echo treats its own write as a concurrent third-party one. It also
-     * has to be distinct per client, since it keys the server's per-
-     * `(uri, clientId)` watch bucket.
-     *
-     * Avoid the three values the framework itself uses as sentinels —
-     * `'language-client'`, `'unknown'` and `'revert-on-close'`.
-     */
-    readonly clientId: string;
     /**
      * Open the transport and hand back a listening `MessageConnection`.
      *
-     * Called at most once per connection generation. A rejection is a
-     * transport-construction failure and is reported through
-     * {@link reportError} by the consumer; it must leave the port reusable, so
-     * that a later generation can retry.
+     * Called at most once per connection generation. A rejection before the
+     * port is disposed is a transport-construction failure and is reported
+     * through {@link reportError} by the consumer; it must leave the port
+     * reusable, so that a later generation can retry.
+     *
+     * The consumer disposes a connection only when it drops the generation on
+     * {@link onDispose} or is disposed itself, so the connection of a generation
+     * that failed its readiness check stays with the port. A port whose
+     * connections reach one far end hands back the same connection until it is
+     * disposed: a second live one would take answers meant for the first, or end
+     * that far end when disposed. A port that opens an independent transport per
+     * call disposes the one it opened before at the next call. Either releases
+     * its connection at its own dispose and refuses to connect after it, since
+     * the consumer reconnects when told. Either serves one consumer: one
+     * consumer's dispose, or its next call to a port of the second kind,
+     * disposes the connection another still uses.
      */
     connect(): Promise<MessageConnection>;
     /**
@@ -73,17 +76,25 @@ export interface DataPort {
      *
      * It exists because the alternative is worse in both directions: this tier
      * cannot import a host's UI, and swallowing the error makes a dead
-     * connection look like an empty model. `context` names what was being
-     * attempted, not where in the code it happened.
+     * connection look like an empty model.
+     *
+     * `reported` is a complete sentence plus the identity needed to render it in
+     * another language. It carries a value rather than using a protocol field
+     * because this tier does not know whether a process hop intervenes — in a
+     * webview host the render happens across one — and a `ResolvedMessage` is
+     * structured-clone safe either way. Render it with `renderFrameworkMessage`;
+     * passing no translation map yields the English.
      */
-    reportError(error: unknown, context: string): void;
+    reportError(error: unknown, reported: ResolvedMessage): void;
+    /** Where a connection over this port logs what it does on its own. Without one it logs nothing. */
+    readonly logger?: Logger;
     /**
      * Fires when the host tears the transport down and the current connection
      * is no longer usable — a language-server restart being the case that
      * forces this to exist, since a restarted server binds new ephemeral ports
      * and nothing re-discovers them.
      *
-     * `DataSession` drops its connection generation on this event and
+     * `DataConnection` drops its connection generation on this event and
      * builds a fresh one on the next request.
      *
      * A local `Event`, deliberately: nothing here crosses a structured-clone
@@ -91,5 +102,11 @@ export interface DataPort {
      * `Disposable` on the *wire* would not be.
      */
     readonly onDispose: Event<void>;
+    /**
+     * Called for each connection generation, beside the lifecycle the
+     * connection's options pass, so a host reporting its connections itself
+     * does so without every connection built over it passing this on.
+     */
+    readonly connectionLifecycle?: RpcConnectionLifecycle;
 }
 //# sourceMappingURL=data-port.d.ts.map

package/lib/client/data-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-port.d.ts","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,QAAQ;IACtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtC;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CAClC"}
+{"version":3,"file":"data-port.d.ts","sourceRoot":"","sources":["../../src/client/data-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,QAAQ;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IAE7D,mGAAmG;IACnG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,sBAAsB,CAAC;CACxD"}