@hydranium/protocol 1.0.0-next.117 → 1.0.0-next.123

package/src/data/data-protocol-methods.ts

@@ -20,6 +20,10 @@ import type {
 
 /** Request-method names on {@link DocumentServerProtocol}. */
 export const DOCUMENT_SERVER_PROTOCOL_METHODS = [
+   'createSession',
+   'closeSession',
+   'createModelDocument',
+   'updateModelDocuments',
    'openModelDocument',
    'closeModelDocument',
    'getModelDocument',

package/src/data/data-server-protocol.ts

@@ -21,11 +21,15 @@ import type {
    TransferDocumentUpdatedEvent
 } from './events';
 import type {
+   CloseSessionArgs,
+   CreateModelDocumentArgs,
+   CreateSessionArgs,
    GetModelDocumentArgs,
    GetProjectForUriArgs,
    TransferSaveDocumentArgs,
    WatchModelDocumentArgs,
-   TransferUpdateDocumentArgs
+   TransferUpdateDocumentArgs,
+   TransferUpdateDocumentsArgs
 } from './requests';
 
 /**
@@ -46,35 +50,74 @@ import type {
  */
 export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
    /**
-    * Open a document for an editor session and return its current state.
-    * Registers `(uri, clientId)` with the multi-client document manager
-    * (so concurrent editors share one built document) and returns the
-    * document at the server's configured target phase — the same shape
-    * {@link getModelDocument} returns, except that `version` is taken from
-    * the text-document store so the caller's first `basedOn` write
-    * cannot self-conflict. Idempotent in registration terms: opening an
-    * already-open document refreshes the client registration. Note it does
-    * NOT avoid a rebuild — a second client attaching triggers
-    * `refreshContent`, which fires a change event, so mounting a form on a
-    * document already open in a text editor rebuilds it.
+    * Register `args.clientId` as a client session owned by this connection.
+    * Rejects with a `DuplicateClientIdError` code when the id is live anywhere
+    * in the server process or reserved by the framework.
     *
-    * The default `DataServer` impl delegates to `ModelService.open` then
-    * reads the built state. Pair with {@link watchModelDocument} to receive
-    * subsequent build-phase events (open returns a one-shot snapshot;
-    * later validation diagnostics arrive on the watch channel).
+    * A request carrying a registered id acts as that session: it writes only
+    * what the session has open, failing with a `DocumentNotOpenError` code
+    * otherwise, and opens nothing implicitly; its open reads the file and takes
+    * no `languageId`, `version` or `text` seed. The session ends with
+    * {@link closeSession} or when the connection closes, and either closes
+    * every document it has open.
+    *
+    * A registration carrying the `resumeToken` an earlier registration of the
+    * same id carried ends that session first, from any connection, so a client
+    * whose connection dropped can register again before the server notices.
+    */
+   createSession(args: CreateSessionArgs): Promise<void>;
+
+   /**
+    * End a session this connection registered: close every document it has
+    * open, drop its watches, and free its id. A no-op for an id this
+    * connection did not register.
+    */
+   closeSession(args: CloseSessionArgs): Promise<void>;
+
+   /**
+    * Create a document with `args.text`, open for the session, and return it
+    * as {@link openModelDocument} does. It reaches disk with the first save.
+    * Fails when the file exists or any client has the URI open, and with a
+    * `SessionClosedError` code when `args.clientId` is not a session
+    * registered on this connection.
+    */
+   createModelDocument(args: CreateModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+
+   /**
+    * Write several documents the session has open, all or none: a conflict or
+    * a document not open fails the whole set before any text applies.
+    * Resolves to the documents in the order given. Only for a session
+    * registered on this connection.
+    */
+   updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+
+   /**
+    * Open a document for the client session `clientId` and return its current
+    * state. `clientId` must be a session this connection registered with
+    * {@link createSession}; any other id fails with the closed-session code,
+    * as every document request here does. The document is read from disk
+    * unless a client has it open already, so the request carries no
+    * `languageId`, `version` or `text` seed. Returns the document at
+    * the server's configured target phase — the same shape
+    * {@link getModelDocument} returns, except that `version` is taken from the
+    * text-document store so the caller's first `basedOn` write cannot
+    * self-conflict. A repeat open changes nothing.
+    *
+    * Pair with {@link watchModelDocument} to receive subsequent build-phase
+    * events (open returns a one-shot snapshot; later validation diagnostics
+    * arrive on the watch channel).
     */
-   openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+   openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Close an editor session for `(uri, clientId)`. Counterpart to
-    * {@link openModelDocument}; the underlying document stays built until
-    * every registered client has closed. The default `DataServer` impl
-    * delegates to `ModelService.close` and ALSO releases any watch for the
-    * same `(uri, clientId)` (closing a session frees its own watch — a
-    * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
-    * the implicit unwatch is idempotent). `watchModelDocument` is NOT
-    * coupled the other way: opening does not force a watch, so a snapshot
-    * reader can open without streaming.
+    * Close the session's open of `uri`. Counterpart to
+    * {@link openModelDocument}; the document stays open until every client
+    * has closed it, and the last close reverts it to disk. The default
+    * `DataServer` impl ALSO releases any watch for the same
+    * `(uri, clientId)` (a forgotten {@link unwatchModelDocument} would
+    * otherwise leak dispatch; the implicit unwatch is idempotent).
+    * `watchModelDocument` is NOT coupled the other way: opening does not force
+    * a watch, so a snapshot reader can open without streaming.
     */
    closeModelDocument(args: CloseModelArgs): Promise<void>;
 
@@ -87,14 +130,15 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
    getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Update a document's content. The response carries the latest built
-    * state including diagnostics; callers observe convergence via that
-    * response.
+    * Update a document's content as the session `clientId`, which must have
+    * it open. The response carries the latest built state including
+    * diagnostics; callers observe convergence via that response.
     */
    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
 
    /**
-    * Persist a document to disk. The response is the post-save document
+    * Write a document as the session `clientId`, which must have it open, and
+    * persist it to disk. The response is the post-save document
     * state (matches the file on disk). Save semantics depend on the
     * filesystem-provider wiring; rejection paths surface as awaited
     * promise rejections.

package/src/data/requests.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+import type { BasedOn } from '../model-service/based-on';
 
 /** Get the current state of a single document. The server returns the latest built version. */
 export interface GetModelDocumentArgs {
@@ -41,24 +41,84 @@ export interface GetProjectForUriArgs {
 }
 
 /**
- * Update a document's content. Wire-side projection of the facade's
- * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
- * handler can forward straight to the in-process `ModelService.update`
- * without an args mapping.
+ * Update a document the session `clientId` has open. Generic over `TTransfer`
+ * so adopters parameterise the structured shape against their grammar's
+ * transfer-model overlay; passing a string is always allowed.
  */
-export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
+export interface TransferUpdateDocumentArgs<TTransfer> {
+   /** Document URI. */
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The whole structured model root, or its serialised textual form. */
+   model: TTransfer | string;
+   /**
+    * What this write was authored against. A `SnapshotVersion` is compared
+    * against the server's current text-document version for `uri` and throws
+    * `ConflictError` on mismatch; `'anything'` writes unconditionally.
+    *
+    * **Required so that an ungated write is a decision rather than an
+    * omission.** An optional gate is indistinguishable from a forgotten one at
+    * the call site, and a file of twenty writes hides the one that lost the
+    * field. Nothing else here can see that, since the defect is an absence.
+    */
+   basedOn: BasedOn;
+}
+
+/** Update a document the session `clientId` has open, then persist it to disk. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TransferSaveDocumentArgs<TTransfer> extends TransferUpdateDocumentArgs<TTransfer> {}
+
+/** Register a client session on the connection. */
+export interface CreateSessionArgs {
+   /** The session's id, minted by the client; unique in the server process while the session is live. */
+   clientId: string;
+   /** What the participant is; kept as the server session's `label`. */
+   label?: string;
+   /**
+    * A token the client keeps for the session's lifetime. It is no secret: the
+    * wire carries no authentication. A later `createSession` for the same id
+    * carrying the same token, from any connection, ends the session it names
+    * and registers the id afresh, so a client whose connection dropped before
+    * the server noticed can register again. Without it the id stays refused
+    * until the server notices.
+    */
+   resumeToken?: string;
+}
+
+/** End a client session registered on the connection. */
+export interface CloseSessionArgs {
+   clientId: string;
+}
+
+/** Create a document that exists nowhere yet, open for the session creating it. */
+export interface CreateModelDocumentArgs {
+   uri: string;
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   /** The document's initial content; it reaches disk with the first save. */
+   text: string;
+}
 
-/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
-export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+/**
+ * Write several documents a session has open, all or none. `clientId` is on
+ * the set rather than on each update: an id per update would allow a set
+ * mixing clients, which the server would have to refuse.
+ */
+export interface TransferUpdateDocumentsArgs<TTransfer> {
+   /** The id of a live session registered on this connection. */
+   clientId: string;
+   updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
+}
 
 /**
  * Identifies a per-document watch on the data server. Shared by both
  * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
  * pair is the watch key, so unwatching names the same watch that was
  * started. The `clientId` identifies the originator the same way it does
- * on facade-side mutations (`TransferUpdateArgs.clientId`,
- * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
- * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * on the document writes (`TransferUpdateDocumentArgs.clientId`,
+ * `TransferSaveDocumentArgs.clientId`): it keys the per-`(uri, clientId)`
+ * watch bucket so multiple watchers on the same wire stay distinct, AND it lets
  * each watcher recognise its own echo on inbound `onDocumentUpdated` events
  * (the wire shape's `sourceClientId` carries the originating mutation's
  * `clientId`).

package/src/errors.ts

@@ -47,7 +47,7 @@ export interface ConflictErrorData extends HydraniumMessageData {
 }
 
 /**
- * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * Thrown by a client session's `update` / `save` when the caller-
  * supplied based-on version no longer matches the server's current text-
  * document version for the same URI — i.e. the snapshot the caller
  * authored against has been superseded by an intervening edit.
@@ -60,9 +60,9 @@ export interface ConflictErrorData extends HydraniumMessageData {
  * `err.data` (the instance is reconstructed as a generic
  * `ResponseError`, so subclass getters / fields do not survive).
  *
- * Detection is driven by the required `basedOn` field on
- * `TransferUpdateArgs` / `TransferSaveArgs`; a caller with no meaningful
- * based-on version passes `'anything'` and gets no gating.
+ * Detection is driven by the required `basedOn` field of every write
+ * request; a caller with no meaningful based-on version passes
+ * `'anything'` and gets no gating.
  *
  * Three reasonable adopter recovery strategies:
  *
@@ -114,6 +114,103 @@ export class ConflictError extends ResponseError<ConflictErrorData> {
    }
 }
 
+/**
+ * JSON-RPC code for {@link SessionClosedError}, beside {@link CONFLICT_ERROR_CODE}
+ * and for the same reason: the code survives reconstruction, the class does not.
+ */
+export const SESSION_CLOSED_ERROR_CODE = 1004;
+/** JSON-RPC code for {@link DocumentNotOpenError}. */
+export const DOCUMENT_NOT_OPEN_ERROR_CODE = 1005;
+/** JSON-RPC code for {@link DuplicateClientIdError}. */
+export const DUPLICATE_CLIENT_ID_ERROR_CODE = 1006;
+
+/**
+ * Thrown by every call on a client session after it ended, and by an open that
+ * was still in flight when its session ended.
+ *
+ * The message names the client id, so it is addressed to whoever composes the
+ * system rather than to an end user, and carries no message identity. A client
+ * recognises it after an RPC with {@link isSessionClosedError}.
+ */
+export class SessionClosedError extends ResponseError<{ readonly clientId: string }> {
+   /** `message` replaces the default sentence, for a caller that knows more than that the session is gone. */
+   constructor(clientId: string, message = `Client session ${clientId} is closed`) {
+      super(SESSION_CLOSED_ERROR_CODE, message, { clientId });
+      this.name = 'SessionClosedError';
+      // `ResponseError` resets the prototype to its own; see `ConflictError`.
+      Object.setPrototypeOf(this, SessionClosedError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Thrown when a client session writes a document it does not have open.
+ *
+ * A session writes only what it has open, so this is the answer both to a write
+ * that never opened and to one whose open was closed underneath it — by the
+ * session itself, or by the document being deleted.
+ */
+export class DocumentNotOpenError extends ResponseError<{ readonly uri: string; readonly clientId: string }> {
+   constructor(uri: string, clientId: string) {
+      super(DOCUMENT_NOT_OPEN_ERROR_CODE, `Document ${uri} is not open in client session ${clientId}`, { uri, clientId });
+      this.name = 'DocumentNotOpenError';
+      Object.setPrototypeOf(this, DocumentNotOpenError.prototype);
+   }
+
+   get uri(): string {
+      return this.data!.uri;
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Thrown when a client session is started under an id that is already live in
+ * the process, or that the framework reserves for itself.
+ *
+ * Ids are unique process-wide because the id is also the author label on every
+ * version and the key a client recognises its own echoes by; two participants
+ * sharing one would each take the other's writes for their own.
+ */
+export class DuplicateClientIdError extends ResponseError<{ readonly clientId: string }> {
+   constructor(clientId: string) {
+      super(DUPLICATE_CLIENT_ID_ERROR_CODE, `Client id ${clientId} is already in use`, { clientId });
+      this.name = 'DuplicateClientIdError';
+      Object.setPrototypeOf(this, DuplicateClientIdError.prototype);
+   }
+
+   get clientId(): string {
+      return this.data!.clientId;
+   }
+}
+
+/**
+ * Whether `error` is a {@link SessionClosedError}: by name in-process, by code
+ * after an RPC, where it arrives as a plain `ResponseError`.
+ */
+export function isSessionClosedError(error: unknown): error is SessionClosedError {
+   return hasErrorIdentity(error, 'SessionClosedError', SESSION_CLOSED_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DocumentNotOpenError}; see {@link isSessionClosedError}. */
+export function isDocumentNotOpenError(error: unknown): error is DocumentNotOpenError {
+   return hasErrorIdentity(error, 'DocumentNotOpenError', DOCUMENT_NOT_OPEN_ERROR_CODE);
+}
+
+/** Whether `error` is a {@link DuplicateClientIdError}; see {@link isSessionClosedError}. */
+export function isDuplicateClientIdError(error: unknown): error is DuplicateClientIdError {
+   return hasErrorIdentity(error, 'DuplicateClientIdError', DUPLICATE_CLIENT_ID_ERROR_CODE);
+}
+
+function hasErrorIdentity(error: unknown, name: string, code: number): boolean {
+   return error instanceof Error && (error.name === name || (error as Partial<ResponseError<unknown>>).code === code);
+}
+
 /** Marker substring present in every {@link ConflictError} message, used by
  *  {@link isConflictError} as a fallback when a transport re-wraps the error
  *  and drops the JSON-RPC code. */

package/src/messages/index.ts

@@ -27,6 +27,7 @@ export * from './primitives';
 
 export { STALE_BASED_UPDATE } from '../errors';
 export { DATA_SERVER_CONNECT_FAILED, DATA_SERVER_NOT_READY } from '../client/rpc-connection';
+export { DATA_SESSION_RESTORE_FAILED, DATA_SESSION_UNSAVED_LOST } from '../client/data-session';
 export {
    RELAY_REPLAY_FAILED,
    RELAY_TRANSPORT_OPEN_FAILED,

package/src/model-server.ts

@@ -14,17 +14,19 @@
  * over `TRoot`.
  */
 
-import type { TransferClientArgs } from './model-service/args';
 import type { ReferenceCandidate } from './model-service/reference-candidate';
 
 // ---------------------------------------------------------------------------
 // Client / server arguments
 // ---------------------------------------------------------------------------
 
-// `TransferClientArgs` / `TransferUpdateArgs` / `TransferSaveArgs` live in
-// `./model-service/args.ts` and are re-exported by the main barrel via
-// `./model-service`. The legacy LSP-style protocol (Open / Close / events)
-// defined here only consumes them as a supertype.
+/** Identifies a client-document binding. */
+export interface TransferClientArgs {
+   /** Document URI. */
+   uri: string;
+   /** Stable identifier for the client invoking the operation. */
+   clientId: string;
+}
 
 /** Open a document on behalf of a client. */
 export interface OpenModelArgs extends TransferClientArgs {
@@ -53,6 +55,12 @@ export interface OpenModelArgs extends TransferClientArgs {
     * `didOpen` attach may separately refresh the build.
     */
    text?: string;
+   /**
+    * Kept on the server for this client's open until it closes, for the
+    * server's own open path to read. Only a client session's open keeps them,
+    * and a repeat open keeps the first open's.
+    */
+   options?: object;
 }
 
 /** Close a previously-opened document for the client. */

package/src/model-service/based-on.ts

@@ -58,3 +58,6 @@ export function isSnapshotVersion(basedOn: BasedOn): basedOn is SnapshotVersion
 export function asSnapshotVersion(version: number): SnapshotVersion {
    return version as SnapshotVersion;
 }
+
+/** A snapshot version no write can match, so a write based on it conflicts. */
+export const NO_MATCHING_VERSION: SnapshotVersion = asSnapshotVersion(-1);

package/src/model-service/index.ts

@@ -7,11 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-// Subpath barrel for the in-process `ModelService` facade contract. The
-// implementation lives in `@hydranium/core`; this package owns the
-// argument types so both the framework facade and the data-server wire
-// protocol can structurally agree on the lifecycle shape.
+// Generic payload types the data protocol shares with core: the based-on
+// version, which the server's model service checks writes against, and the
+// reference candidates, which core's scope and completion code produce.
 
-export * from './args';
 export * from './based-on';
 export * from './reference-candidate';