@hydranium/protocol 1.0.0-next.25 → 1.0.0-next.250

package/src/client/data-port.ts

@@ -8,15 +8,21 @@
  ********************************************************************************/
 
 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
@@ -24,7 +30,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
@@ -45,29 +51,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>;
 
@@ -77,10 +79,19 @@ 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
@@ -88,7 +99,7 @@ export interface DataPort {
     * 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
@@ -96,4 +107,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;
 }