@fluidframework/merge-tree 2.31.0 → 2.32.0

package/lib/test/clientTestHelper.d.ts

@@ -0,0 +1,100 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
+import type { IMergeTreeOptions, InteriorSequencePlace } from "../index.js";
+import type { TestClient } from "./testClient.js";
+import { TestClientLogger } from "./testClientLogger.js";
+declare const ClientIds: readonly ["A", "B", "C", "D"];
+type ClientName = (typeof ClientIds)[number];
+/**
+ * Helper for authoring tests which perform operations on a number of clients.
+ * This class essentially serves the role of the server in that it maintains a sequencing order of ops as well as information
+ * about the latest op that each client has applied.
+ *
+ * When using this class, *do not* perform operations which may submit ops on clients directly: it does not currently wire up client events
+ * to the server. Instead, use methods on the helper and pass the client name they should apply to as the first argument.
+ *
+ * It is analogous to MockContainerRuntimeFactory in the test-runtime-utils package, though the APIs are not completely equivalent
+ * (see for example differences noted on disconnect and reconnect).
+ *
+ * This helper is also designed to support advancing only some clients to a given sequence number
+ * (not all clients must be synchronized at the same time).
+ *
+ * This allows testing sequences of operations where clients have varying refSeqs, rather than having all clients advance refSeq
+ * in lockstep.
+ *
+ * @remarks
+ * If we wired the server up to "delta" events on the client, it would be reasonable to rename this to `MockServer` and the API for tests
+ * would be a bit cleaner.
+ */
+export declare class ClientTestHelper {
+    clients: Record<ClientName, TestClient> & {
+        all: TestClient[];
+    };
+    idxFromName(name: ClientName): number;
+    logger: TestClientLogger;
+    ops: ISequencedDocumentMessage[];
+    clientToLastAppliedSeq: Map<"A" | "B" | "C" | "D", number>;
+    perClientOps: ISequencedDocumentMessage[][];
+    private readonly disconnectedClientOps;
+    private seq;
+    constructor(options?: IMergeTreeOptions);
+    private addMessage;
+    insertText(clientName: ClientName, pos: number, text: string): void;
+    removeRange(clientName: ClientName, start: number, end: number): void;
+    obliterateRange(clientName: ClientName, start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;
+    advanceClientToSeq(clientName: ClientName, seq: number): void;
+    /**
+     * Sends all known ops to the procieded client ids.
+     */
+    advanceClients(...clientNames: ClientName[]): void;
+    processAllOps(): void;
+    /**
+     * Causes the provided clients to "disconnect" by isolating their outbound queue from the op stream.
+     * These clients will still receive ops from this helper just like all other clients.
+     * When a client reconnects (see {@link reconnect}), the helper will rebase all of the client's pending ops (that they submitted since
+     * `disconnect` was called) and re-add them to the op stream.
+     *
+     * BEWARE: This is slightly different from what the mocks in test-runtime-utils do in two ways:
+     *
+     * 1. Those mocks actually wipe outstanding ops submitted by the disconnected clients from the op stream and rebases those as well.
+     * 2. Those mocks freeze the inbound queue of the disconnected clients as well as the outbound queue.
+     *
+     * E.g. (pseudocode; syntax is different for those mocks and these):
+     *
+     * ```typescript
+     * B.submitLocalOp1()
+     * B.submitLocalOp2()
+     * disconnect(B)
+     * A.submitLocalOp1()
+     * B.submitLocalOp3()
+     * processAllOps()
+     * ```
+     *
+     * the test-runtime-mocks will...
+     *
+     * - have none of B's local ops be receieved by A in the processAllOps() line
+     * - have B not receive A's local op 1
+     *
+     * whereas this helper will...
+     *
+     * - have B's local ops 1 and 2 be received by A, but not its third local op
+     * - have B receive acks for its first two local ops as well as A's op in the processAllOps() line
+     *
+     * This operation is a no-op if called multiple times on the same client with no intervening reconnects.
+     */
+    disconnect(...clientNames: ClientName[]): void;
+    /**
+     * Reconnects clients which have been disconnected. No-ops on any client which is already connected.
+     * For disconnected clients, any pending ops they have will be resubmitted using the resubmit flow, see {@link disconnect} for details and an example.
+     *
+     * @remarks
+     * If reconnecting multiple clients, the order that their ops will be resubmitted in will match the order in the array
+     */
+    reconnect(...clientNames: ClientName[]): void;
+    private isDisconnected;
+}
+export {};
+//# sourceMappingURL=clientTestHelper.d.ts.map

package/lib/test/clientTestHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientTestHelper.d.ts","sourceRoot":"","sources":["../../src/test/clientTestHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AAExF,OAAO,KAAK,EAAgB,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG1F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAA+B,MAAM,uBAAuB,CAAC;AAEtF,QAAA,MAAM,SAAS,+BAAgC,CAAC;AAChD,KAAK,UAAU,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAY7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG;QAAE,GAAG,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAEhE,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAIrC,MAAM,EAAE,gBAAgB,CAAC;IAEzB,GAAG,EAAE,yBAAyB,EAAE,CAAM;IACtC,sBAAsB,qCAAiC;IAEvD,YAAY,EAAE,yBAAyB,EAAE,EAAE,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAGlC;IAEJ,OAAO,CAAC,GAAG,CAAa;gBAEL,OAAO,GAAE,iBAAsB;IAgBlD,OAAO,CAAC,UAAU;IAmBX,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQnE,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKrE,eAAe,CACrB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,MAAM,GAAG,qBAAqB,EACrC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GACjC,IAAI;IAKA,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAwBpE;;OAEG;IACI,cAAc,CAAC,GAAG,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI;IAOlD,aAAa,IAAI,IAAI;IAO5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,UAAU,CAAC,GAAG,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI;IAUrD;;;;;;OAMG;IACI,SAAS,CAAC,GAAG,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI;IAepD,OAAO,CAAC,cAAc;CAGtB"}

package/lib/test/clientTestHelper.js

@@ -0,0 +1,192 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { strict as assert } from "node:assert";
+import { TestClientLogger, createClientsAtInitialState } from "./testClientLogger.js";
+const ClientIds = ["A", "B", "C", "D"];
+function isClientId(s) {
+    return ClientIds.includes(s);
+}
+function clientNameOf(client) {
+    const { longClientId } = client;
+    assert(isClientId(longClientId), "Client ID is not a valid client name");
+    return longClientId;
+}
+/**
+ * Helper for authoring tests which perform operations on a number of clients.
+ * This class essentially serves the role of the server in that it maintains a sequencing order of ops as well as information
+ * about the latest op that each client has applied.
+ *
+ * When using this class, *do not* perform operations which may submit ops on clients directly: it does not currently wire up client events
+ * to the server. Instead, use methods on the helper and pass the client name they should apply to as the first argument.
+ *
+ * It is analogous to MockContainerRuntimeFactory in the test-runtime-utils package, though the APIs are not completely equivalent
+ * (see for example differences noted on disconnect and reconnect).
+ *
+ * This helper is also designed to support advancing only some clients to a given sequence number
+ * (not all clients must be synchronized at the same time).
+ *
+ * This allows testing sequences of operations where clients have varying refSeqs, rather than having all clients advance refSeq
+ * in lockstep.
+ *
+ * @remarks
+ * If we wired the server up to "delta" events on the client, it would be reasonable to rename this to `MockServer` and the API for tests
+ * would be a bit cleaner.
+ */
+export class ClientTestHelper {
+    idxFromName(name) {
+        return (name.codePointAt(0) ?? 0) - ("A".codePointAt(0) ?? 0);
+    }
+    constructor(options = {}) {
+        this.ops = [];
+        this.clientToLastAppliedSeq = new Map();
+        this.disconnectedClientOps = new Map();
+        this.seq = 0;
+        this.clients = createClientsAtInitialState({
+            initialState: "",
+            options: {
+                mergeTreeEnableObliterate: true,
+                mergeTreeEnableObliterateReconnect: true,
+                ...options,
+            },
+        }, ...ClientIds);
+        this.logger = new TestClientLogger(this.clients.all);
+        this.perClientOps = this.clients.all.map(() => []);
+    }
+    addMessage(client, op) {
+        const disconnectedQueue = this.disconnectedClientOps.get(clientNameOf(client));
+        if (disconnectedQueue === undefined) {
+            const message = client.makeOpMessage(op, ++this.seq);
+            this.ops.push(message);
+            // This implementation (specifically, that of applying ops / synchronizing clients) assumes messages
+            // are pushed sequentially starting with seq 1.
+            assert(message.sequenceNumber === this.ops.length, "Partial sync test helper invariant violated");
+        }
+        else {
+            // Client is not currently connected.
+            const segmentGroup = client.peekPendingSegmentGroups();
+            assert(segmentGroup !== undefined, "Client should have a pending segment group");
+            disconnectedQueue.push({ op, segmentGroup });
+        }
+    }
+    insertText(clientName, pos, text) {
+        const client = this.clients[clientName];
+        const insertOp = client.insertTextLocal(pos, text);
+        if (insertOp) {
+            this.addMessage(client, insertOp);
+        }
+    }
+    removeRange(clientName, start, end) {
+        const client = this.clients[clientName];
+        this.addMessage(client, client.removeRangeLocal(start, end));
+    }
+    obliterateRange(clientName, start, end) {
+        const client = this.clients[clientName];
+        this.addMessage(client, client.obliterateRangeLocal(start, end));
+    }
+    advanceClientToSeq(clientName, seq) {
+        const client = this.clients[clientName];
+        const lastApplied = this.clientToLastAppliedSeq.get(clientName);
+        assert(seq > 0, "Can only advance clients to sequence numbers that exist");
+        assert(this.ops.length >= seq, "Cannot attempt to advance clients to sequence numbers that don't yet exist");
+        let startIndex;
+        if (lastApplied === undefined) {
+            startIndex = 0;
+        }
+        else {
+            if (lastApplied >= seq) {
+                return;
+            }
+            startIndex = lastApplied;
+        }
+        for (let i = startIndex; i < seq; i++) {
+            const nextMessage = this.ops[i];
+            client.applyMsg(nextMessage);
+            this.clientToLastAppliedSeq.set(clientName, nextMessage.sequenceNumber);
+        }
+    }
+    /**
+     * Sends all known ops to the procieded client ids.
+     */
+    advanceClients(...clientNames) {
+        const latestSeq = this.ops[this.ops.length - 1].sequenceNumber;
+        for (const name of clientNames) {
+            this.advanceClientToSeq(name, latestSeq);
+        }
+    }
+    processAllOps() {
+        const latestSeq = this.ops[this.ops.length - 1].sequenceNumber;
+        for (const name of ClientIds) {
+            this.advanceClientToSeq(name, latestSeq);
+        }
+    }
+    /**
+     * Causes the provided clients to "disconnect" by isolating their outbound queue from the op stream.
+     * These clients will still receive ops from this helper just like all other clients.
+     * When a client reconnects (see {@link reconnect}), the helper will rebase all of the client's pending ops (that they submitted since
+     * `disconnect` was called) and re-add them to the op stream.
+     *
+     * BEWARE: This is slightly different from what the mocks in test-runtime-utils do in two ways:
+     *
+     * 1. Those mocks actually wipe outstanding ops submitted by the disconnected clients from the op stream and rebases those as well.
+     * 2. Those mocks freeze the inbound queue of the disconnected clients as well as the outbound queue.
+     *
+     * E.g. (pseudocode; syntax is different for those mocks and these):
+     *
+     * ```typescript
+     * B.submitLocalOp1()
+     * B.submitLocalOp2()
+     * disconnect(B)
+     * A.submitLocalOp1()
+     * B.submitLocalOp3()
+     * processAllOps()
+     * ```
+     *
+     * the test-runtime-mocks will...
+     *
+     * - have none of B's local ops be receieved by A in the processAllOps() line
+     * - have B not receive A's local op 1
+     *
+     * whereas this helper will...
+     *
+     * - have B's local ops 1 and 2 be received by A, but not its third local op
+     * - have B receive acks for its first two local ops as well as A's op in the processAllOps() line
+     *
+     * This operation is a no-op if called multiple times on the same client with no intervening reconnects.
+     */
+    disconnect(...clientNames) {
+        for (const clientName of clientNames) {
+            const client = this.clients[clientName];
+            if (this.isDisconnected(client)) {
+                continue;
+            }
+            this.disconnectedClientOps.set(clientName, []);
+        }
+    }
+    /**
+     * Reconnects clients which have been disconnected. No-ops on any client which is already connected.
+     * For disconnected clients, any pending ops they have will be resubmitted using the resubmit flow, see {@link disconnect} for details and an example.
+     *
+     * @remarks
+     * If reconnecting multiple clients, the order that their ops will be resubmitted in will match the order in the array
+     */
+    reconnect(...clientNames) {
+        for (const clientName of clientNames) {
+            const submittedOps = this.disconnectedClientOps.get(clientName);
+            if (submittedOps === undefined) {
+                continue;
+            }
+            this.disconnectedClientOps.delete(clientName);
+            const client = this.clients[clientName];
+            for (const { op, segmentGroup } of submittedOps) {
+                const rebasedOp = client.regeneratePendingOp(op, segmentGroup);
+                this.addMessage(client, rebasedOp);
+            }
+        }
+    }
+    isDisconnected(client) {
+        return this.disconnectedClientOps.has(clientNameOf(client));
+    }
+}
+//# sourceMappingURL=clientTestHelper.js.map

package/lib/test/clientTestHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientTestHelper.js","sourceRoot":"","sources":["../../src/test/clientTestHelper.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { strict as assert } from \"node:assert\";\n\nimport { ISequencedDocumentMessage } from \"@fluidframework/driver-definitions/internal\";\n\nimport type { IMergeTreeOp, IMergeTreeOptions, InteriorSequencePlace } from \"../index.js\";\nimport type { SegmentGroup } from \"../mergeTreeNodes.js\";\n\nimport type { TestClient } from \"./testClient.js\";\nimport { TestClientLogger, createClientsAtInitialState } from \"./testClientLogger.js\";\n\nconst ClientIds = [\"A\", \"B\", \"C\", \"D\"] as const;\ntype ClientName = (typeof ClientIds)[number];\n\nfunction isClientId(s: unknown): s is ClientName {\n\treturn ClientIds.includes(s as ClientName);\n}\n\nfunction clientNameOf(client: TestClient): ClientName {\n\tconst { longClientId } = client;\n\tassert(isClientId(longClientId), \"Client ID is not a valid client name\");\n\treturn longClientId;\n}\n\n/**\n * Helper for authoring tests which perform operations on a number of clients.\n * This class essentially serves the role of the server in that it maintains a sequencing order of ops as well as information\n * about the latest op that each client has applied.\n *\n * When using this class, *do not* perform operations which may submit ops on clients directly: it does not currently wire up client events\n * to the server. Instead, use methods on the helper and pass the client name they should apply to as the first argument.\n *\n * It is analogous to MockContainerRuntimeFactory in the test-runtime-utils package, though the APIs are not completely equivalent\n * (see for example differences noted on disconnect and reconnect).\n *\n * This helper is also designed to support advancing only some clients to a given sequence number\n * (not all clients must be synchronized at the same time).\n *\n * This allows testing sequences of operations where clients have varying refSeqs, rather than having all clients advance refSeq\n * in lockstep.\n *\n * @remarks\n * If we wired the server up to \"delta\" events on the client, it would be reasonable to rename this to `MockServer` and the API for tests\n * would be a bit cleaner.\n */\nexport class ClientTestHelper {\n\tclients: Record<ClientName, TestClient> & { all: TestClient[] };\n\n\tidxFromName(name: ClientName): number {\n\t\treturn (name.codePointAt(0) ?? 0) - (\"A\".codePointAt(0) ?? 0);\n\t}\n\n\tlogger: TestClientLogger;\n\n\tops: ISequencedDocumentMessage[] = [];\n\tclientToLastAppliedSeq = new Map<ClientName, number>();\n\n\tperClientOps: ISequencedDocumentMessage[][];\n\tprivate readonly disconnectedClientOps = new Map<\n\t\tClientName,\n\t\t{ op: IMergeTreeOp; segmentGroup: SegmentGroup }[]\n\t>();\n\n\tprivate seq: number = 0;\n\n\tpublic constructor(options: IMergeTreeOptions = {}) {\n\t\tthis.clients = createClientsAtInitialState(\n\t\t\t{\n\t\t\t\tinitialState: \"\",\n\t\t\t\toptions: {\n\t\t\t\t\tmergeTreeEnableObliterate: true,\n\t\t\t\t\tmergeTreeEnableObliterateReconnect: true,\n\t\t\t\t\t...options,\n\t\t\t\t},\n\t\t\t},\n\t\t\t...ClientIds,\n\t\t);\n\t\tthis.logger = new TestClientLogger(this.clients.all);\n\t\tthis.perClientOps = this.clients.all.map(() => []);\n\t}\n\n\tprivate addMessage(client: TestClient, op: IMergeTreeOp): void {\n\t\tconst disconnectedQueue = this.disconnectedClientOps.get(clientNameOf(client));\n\t\tif (disconnectedQueue === undefined) {\n\t\t\tconst message = client.makeOpMessage(op, ++this.seq);\n\t\t\tthis.ops.push(message);\n\t\t\t// This implementation (specifically, that of applying ops / synchronizing clients) assumes messages\n\t\t\t// are pushed sequentially starting with seq 1.\n\t\t\tassert(\n\t\t\t\tmessage.sequenceNumber === this.ops.length,\n\t\t\t\t\"Partial sync test helper invariant violated\",\n\t\t\t);\n\t\t} else {\n\t\t\t// Client is not currently connected.\n\t\t\tconst segmentGroup = client.peekPendingSegmentGroups();\n\t\t\tassert(segmentGroup !== undefined, \"Client should have a pending segment group\");\n\t\t\tdisconnectedQueue.push({ op, segmentGroup });\n\t\t}\n\t}\n\n\tpublic insertText(clientName: ClientName, pos: number, text: string): void {\n\t\tconst client = this.clients[clientName];\n\t\tconst insertOp = client.insertTextLocal(pos, text);\n\t\tif (insertOp) {\n\t\t\tthis.addMessage(client, insertOp);\n\t\t}\n\t}\n\n\tpublic removeRange(clientName: ClientName, start: number, end: number): void {\n\t\tconst client = this.clients[clientName];\n\t\tthis.addMessage(client, client.removeRangeLocal(start, end));\n\t}\n\n\tpublic obliterateRange(\n\t\tclientName: ClientName,\n\t\tstart: number | InteriorSequencePlace,\n\t\tend: number | InteriorSequencePlace,\n\t): void {\n\t\tconst client = this.clients[clientName];\n\t\tthis.addMessage(client, client.obliterateRangeLocal(start, end));\n\t}\n\n\tpublic advanceClientToSeq(clientName: ClientName, seq: number): void {\n\t\tconst client = this.clients[clientName];\n\t\tconst lastApplied = this.clientToLastAppliedSeq.get(clientName);\n\t\tassert(seq > 0, \"Can only advance clients to sequence numbers that exist\");\n\t\tassert(\n\t\t\tthis.ops.length >= seq,\n\t\t\t\"Cannot attempt to advance clients to sequence numbers that don't yet exist\",\n\t\t);\n\t\tlet startIndex: number;\n\t\tif (lastApplied === undefined) {\n\t\t\tstartIndex = 0;\n\t\t} else {\n\t\t\tif (lastApplied >= seq) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tstartIndex = lastApplied;\n\t\t}\n\t\tfor (let i = startIndex; i < seq; i++) {\n\t\t\tconst nextMessage = this.ops[i];\n\t\t\tclient.applyMsg(nextMessage);\n\t\t\tthis.clientToLastAppliedSeq.set(clientName, nextMessage.sequenceNumber);\n\t\t}\n\t}\n\n\t/**\n\t * Sends all known ops to the procieded client ids.\n\t */\n\tpublic advanceClients(...clientNames: ClientName[]): void {\n\t\tconst latestSeq = this.ops[this.ops.length - 1].sequenceNumber;\n\t\tfor (const name of clientNames) {\n\t\t\tthis.advanceClientToSeq(name, latestSeq);\n\t\t}\n\t}\n\n\tpublic processAllOps(): void {\n\t\tconst latestSeq = this.ops[this.ops.length - 1].sequenceNumber;\n\t\tfor (const name of ClientIds) {\n\t\t\tthis.advanceClientToSeq(name, latestSeq);\n\t\t}\n\t}\n\n\t/**\n\t * Causes the provided clients to \"disconnect\" by isolating their outbound queue from the op stream.\n\t * These clients will still receive ops from this helper just like all other clients.\n\t * When a client reconnects (see {@link reconnect}), the helper will rebase all of the client's pending ops (that they submitted since\n\t * `disconnect` was called) and re-add them to the op stream.\n\t *\n\t * BEWARE: This is slightly different from what the mocks in test-runtime-utils do in two ways:\n\t *\n\t * 1. Those mocks actually wipe outstanding ops submitted by the disconnected clients from the op stream and rebases those as well.\n\t * 2. Those mocks freeze the inbound queue of the disconnected clients as well as the outbound queue.\n\t *\n\t * E.g. (pseudocode; syntax is different for those mocks and these):\n\t *\n\t * ```typescript\n\t * B.submitLocalOp1()\n\t * B.submitLocalOp2()\n\t * disconnect(B)\n\t * A.submitLocalOp1()\n\t * B.submitLocalOp3()\n\t * processAllOps()\n\t * ```\n\t *\n\t * the test-runtime-mocks will...\n\t *\n\t * - have none of B's local ops be receieved by A in the processAllOps() line\n\t * - have B not receive A's local op 1\n\t *\n\t * whereas this helper will...\n\t *\n\t * - have B's local ops 1 and 2 be received by A, but not its third local op\n\t * - have B receive acks for its first two local ops as well as A's op in the processAllOps() line\n\t *\n\t * This operation is a no-op if called multiple times on the same client with no intervening reconnects.\n\t */\n\tpublic disconnect(...clientNames: ClientName[]): void {\n\t\tfor (const clientName of clientNames) {\n\t\t\tconst client = this.clients[clientName];\n\t\t\tif (this.isDisconnected(client)) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthis.disconnectedClientOps.set(clientName, []);\n\t\t}\n\t}\n\n\t/**\n\t * Reconnects clients which have been disconnected. No-ops on any client which is already connected.\n\t * For disconnected clients, any pending ops they have will be resubmitted using the resubmit flow, see {@link disconnect} for details and an example.\n\t *\n\t * @remarks\n\t * If reconnecting multiple clients, the order that their ops will be resubmitted in will match the order in the array\n\t */\n\tpublic reconnect(...clientNames: ClientName[]): void {\n\t\tfor (const clientName of clientNames) {\n\t\t\tconst submittedOps = this.disconnectedClientOps.get(clientName);\n\t\t\tif (submittedOps === undefined) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthis.disconnectedClientOps.delete(clientName);\n\t\t\tconst client = this.clients[clientName];\n\t\t\tfor (const { op, segmentGroup } of submittedOps) {\n\t\t\t\tconst rebasedOp = client.regeneratePendingOp(op, segmentGroup);\n\t\t\t\tthis.addMessage(client, rebasedOp);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate isDisconnected(client: TestClient): boolean {\n\t\treturn this.disconnectedClientOps.has(clientNameOf(client));\n\t}\n}\n"]}

package/lib/test/mergeTree.annotate.spec.js

@@ -111,7 +111,7 @@ describe("MergeTree", () => {
                     assert.equal(splitSegment.properties?.propertySource, "local");
                     assert.equal(splitSegment.properties?.secondChange, 1);
                     assert.equal(splitSegment.properties?.splitOnly, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -130,7 +130,7 @@ describe("MergeTree", () => {
                     assert.equal(splitSegment.properties?.propertySource, "local");
                     assert.equal(splitSegment.properties?.secondChange, 1);
                     assert.equal(splitSegment.properties?.splitOnly, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -149,7 +149,7 @@ describe("MergeTree", () => {
                     assert.equal(splitSegment.properties?.propertySource, "local");
                     assert.equal(splitSegment.properties?.secondChange, 1);
                     assert.equal(splitSegment.properties?.splitOnly, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: splitPos,
                             pos2: annotateEnd,
@@ -180,7 +180,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.remoteProperty, 1);
                 });
                 it("sequenced local", () => {
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -197,7 +197,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.propertySource, "local");
                 });
                 it("sequenced local before remote", () => {
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -236,7 +236,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.propertySource, "local2");
                     assert.equal(segment.properties?.secondSource, 1);
                     assert.equal(segment.properties?.thirdSource, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -250,7 +250,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.propertySource, "local2");
                     assert.equal(segment.properties?.secondSource, 1);
                     assert.equal(segment.properties?.thirdSource, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -264,7 +264,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.propertySource, "local2");
                     assert.equal(segment.properties?.secondSource, 1);
                     assert.equal(segment.properties?.thirdSource, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -283,7 +283,7 @@ describe("MergeTree", () => {
                     mergeTree.annotateRange(annotateStart, annotateEnd, {
                         props: { secondSource: "local2" },
                     }, mergeTree.localPerspective, mergeTree.collabWindow.mintNextLocalOperationStamp(), undefined);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -344,7 +344,7 @@ describe("MergeTree", () => {
                     assert(segmentInfo.segment?.segmentGroups?.empty !== false);
                     mergeTree.annotateRange(annotateStart, annotateEnd, props, mergeTree.localPerspective, mergeTree.collabWindow.mintNextLocalOperationStamp(), undefined);
                     assert.equal(segmentInfo.segment?.segmentGroups?.size, 1);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -387,7 +387,7 @@ describe("MergeTree", () => {
                     assert.equal(segment.properties?.remoteProperty, 1);
                 });
                 it("sequenced local before remote", () => {
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,
@@ -411,7 +411,7 @@ describe("MergeTree", () => {
                     mergeTree.annotateRange(annotateStart, annotateEnd, {
                         props: { secondSource: "local2" },
                     }, mergeTree.localPerspective, mergeTree.collabWindow.mintNextLocalOperationStamp(), undefined);
-                    mergeTree.ackPendingSegment({
+                    mergeTree.ackOp({
                         op: {
                             pos1: annotateStart,
                             pos2: annotateEnd,