@fluidframework/sequence 0.59.4002 → 1.0.2

package/src/intervalCollection.ts

@@ -7,6 +7,7 @@
 
 import { assert, TypedEventEmitter } from "@fluidframework/common-utils";
 import { IEvent } from "@fluidframework/common-definitions";
+import { UsageError } from "@fluidframework/container-utils";
 import {
     addProperties,
     Client,
@@ -17,12 +18,14 @@ import {
     IntervalConflictResolver,
     IntervalNode,
     IntervalTree,
+    ISegment,
     LocalReference,
     MergeTreeDeltaType,
     PropertiesManager,
     PropertySet,
     RedBlackTree,
     ReferenceType,
+    refTypeIncludesFlag,
     reservedRangeLabelsKey,
     UnassignedSequenceNumber,
 } from "@fluidframework/merge-tree";
@@ -35,7 +38,17 @@ const reservedIntervalIdKey = "intervalId";
 export enum IntervalType {
     Simple = 0x0,
     Nest = 0x1,
-    SlideOnRemove = 0x2,
+    /**
+     * SlideOnRemove indicates that the ends of the interval will slide if the segment
+     * they reference is removed and acked.
+     * See `packages\dds\merge-tree\REFERENCEPOSITIONS.md` for details
+     * SlideOnRemove is the default interval behavior and does not need to be specified.
+     */
+    SlideOnRemove = 0x2, // SlideOnRemove is default behavior - all intervals are SlideOnRemove
+    /**
+     * @internal
+     * A temporary interval, used internally
+     */
     Transient = 0x4,
 }
 
@@ -58,8 +71,26 @@ export interface ISerializableInterval extends IInterval {
 
 export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
     compareEnds(a: TInterval, b: TInterval): number;
-    create(label: string, start: number, end: number,
-        client: Client, intervalType?: IntervalType, op?: ISequencedDocumentMessage): TInterval;
+    /**
+     *
+     * @param label - label of the interval collection this interval is being added to. This parameter is
+     * irrelevant for transient intervals.
+     * @param start - numerical start position of the interval
+     * @param end - numberical end position of the interval
+     * @param client - client creating the interval
+     * @param intervalType - Type of interval to create. Default is SlideOnRemove
+     * @param op - If this create came from a remote client, op that created it. Default is undefined (i.e. local)
+     * @param fromSnapshot - If this create came from loading a snapshot. Default is false.
+     */
+    create(
+        label: string,
+        start: number,
+        end: number,
+        client: Client,
+        intervalType?: IntervalType,
+        op?: ISequencedDocumentMessage,
+        fromSnapshot?: boolean,
+    ): TInterval;
 }
 
 export class Interval implements ISerializableInterval {
@@ -310,20 +341,39 @@ export class SequenceInterval implements ISerializableInterval {
     }
 }
 
-function createPositionReference(
+function createPositionReferenceFromSegoff(
     client: Client,
-    pos: number,
+    segoff: { segment: ISegment | undefined; offset: number | undefined; },
     refType: ReferenceType,
     op?: ISequencedDocumentMessage): LocalReference {
-    const segoff = client.getContainingSegment(pos, op);
-    if (segoff?.segment) {
-        const lref = new LocalReference(client, segoff.segment, segoff.offset, refType);
-        if (refType !== ReferenceType.Transient) {
-            client.addLocalReference(lref);
+    if (segoff.segment) {
+        const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined);
+        return ref as LocalReference;
+    } else {
+        if (!op && !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
+            throw new UsageError("Non-transient references need segment");
         }
-        return lref;
+        return new LocalReference(client, undefined, 0, refType);
+    }
+}
+
+function createPositionReference(
+    client: Client,
+    pos: number,
+    refType: ReferenceType,
+    op?: ISequencedDocumentMessage,
+    fromSnapshot?: boolean): LocalReference {
+    let segoff;
+    if (op) {
+        assert((refType & ReferenceType.SlideOnRemove) !== 0, 0x2f5 /* op create references must be SlideOnRemove */);
+        segoff = client.getContainingSegment(pos, op);
+        segoff = client.getSlideToSegment(segoff);
+    } else {
+        assert((refType & ReferenceType.SlideOnRemove) === 0 || fromSnapshot,
+            0x2f6 /* SlideOnRemove references must be op created */);
+        segoff = client.getContainingSegment(pos);
     }
-    return new LocalReference(client, undefined);
+    return createPositionReferenceFromSegoff(client, segoff, refType, op);
 }
 
 function createSequenceInterval(
@@ -331,38 +381,43 @@ function createSequenceInterval(
     start: number,
     end: number,
     client: Client,
-    intervalType: IntervalType,
-    op?: ISequencedDocumentMessage): SequenceInterval {
+    intervalType?: IntervalType,
+    op?: ISequencedDocumentMessage,
+    fromSnapshot?: boolean): SequenceInterval {
     let beginRefType = ReferenceType.RangeBegin;
     let endRefType = ReferenceType.RangeEnd;
-    if (intervalType === IntervalType.Nest) {
-        beginRefType = ReferenceType.NestBegin;
-        endRefType = ReferenceType.NestEnd;
-    } else if (intervalType === IntervalType.Transient) {
+    if (intervalType === IntervalType.Transient) {
         beginRefType = ReferenceType.Transient;
         endRefType = ReferenceType.Transient;
+    } else {
+        if (intervalType === IntervalType.Nest) {
+            beginRefType = ReferenceType.NestBegin;
+            endRefType = ReferenceType.NestEnd;
+        }
+        // All non-transient interval references must eventually be SlideOnRemove
+        // To ensure eventual consistency, they must start as StayOnRemove when
+        // pending (created locally and creation op is not acked)
+        if (op || fromSnapshot) {
+            beginRefType |= ReferenceType.SlideOnRemove;
+            endRefType |= ReferenceType.SlideOnRemove;
+        } else {
+            beginRefType |= ReferenceType.StayOnRemove;
+            endRefType |= ReferenceType.StayOnRemove;
+        }
     }
 
-    // TODO: Should SlideOnRemove be the default behavior?
-    if (intervalType & IntervalType.SlideOnRemove) {
-        beginRefType |= ReferenceType.SlideOnRemove;
-        endRefType |= ReferenceType.SlideOnRemove;
-    }
-
-    const startLref = createPositionReference(client, start, beginRefType, op);
-    const endLref = createPositionReference(client, end, endRefType, op);
-    if (startLref && endLref) {
-        startLref.pairedRef = endLref;
-        endLref.pairedRef = startLref;
-        const rangeProp = {
-            [reservedRangeLabelsKey]: [label],
-        };
-        startLref.addProperties(rangeProp);
-        endLref.addProperties(rangeProp);
+    const startLref = createPositionReference(client, start, beginRefType, op, fromSnapshot);
+    const endLref = createPositionReference(client, end, endRefType, op, fromSnapshot);
+    startLref.pairedRef = endLref;
+    endLref.pairedRef = startLref;
+    const rangeProp = {
+        [reservedRangeLabelsKey]: [label],
+    };
+    startLref.addProperties(rangeProp);
+    endLref.addProperties(rangeProp);
 
-        const ival = new SequenceInterval(startLref, endLref, intervalType, rangeProp);
-        return ival;
-    }
+    const ival = new SequenceInterval(startLref, endLref, intervalType, rangeProp);
+    return ival;
 }
 
 export function defaultIntervalConflictResolver(a: Interval, b: Interval) {
@@ -520,20 +575,19 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
     }
 
     public findOverlappingIntervals(startPosition: number, endPosition: number) {
-        if (!this.intervalTree.intervals.isEmpty()) {
-            const transientInterval =
-                this.helpers.create(
-                    "transient",
-                    startPosition,
-                    endPosition,
-                    this.client,
-                    IntervalType.Transient);
-
-            const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
-            return overlappingIntervalNodes.map((node) => node.key);
-        } else {
+        if (endPosition < startPosition || this.intervalTree.intervals.isEmpty()) {
             return [];
         }
+        const transientInterval =
+            this.helpers.create(
+                "transient",
+                startPosition,
+                endPosition,
+                this.client,
+                IntervalType.Transient);
+
+        const overlappingIntervalNodes = this.intervalTree.match(transientInterval);
+        return overlappingIntervalNodes.map((node) => node.key);
     }
 
     public previousInterval(pos: number) {
@@ -855,11 +909,18 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         if (this.savedSerializedIntervals) {
             for (const serializedInterval of this.savedSerializedIntervals) {
                 this.localCollection.ensureSerializedId(serializedInterval);
-                this.localCollection.addInterval(
-                    serializedInterval.start,
-                    serializedInterval.end,
-                    serializedInterval.intervalType,
-                    serializedInterval.properties);
+                const { start, end, intervalType, properties } = serializedInterval;
+                const interval = this.helpers.create(
+                    label,
+                    start,
+                    end,
+                    client,
+                    intervalType,
+                    undefined,
+                    true,
+                );
+                interval.addProperties(properties);
+                this.localCollection.add(interval);
             }
         }
         this.savedSerializedIntervals = undefined;
@@ -872,6 +933,14 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         return this.localCollection.getIntervalById(id);
     }
 
+    /**
+     * Create a new interval and add it to the collection
+     * @param start - interval start position
+     * @param end - interval end position
+     * @param intervalType - type of the interval. All intervals are SlideOnRemove. Intervals may not be Transient.
+     * @param props - properties of the interval
+     * @returns - the created interval
+     */
     public add(
         start: number,
         end: number,
@@ -881,6 +950,9 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         if (!this.attached) {
             throw new Error("attach must be called prior to adding intervals");
         }
+        if (intervalType & IntervalType.Transient) {
+            throw new Error("Can not add transient intervals");
+        }
 
         const interval: TInterval = this.localCollection.addInterval(start, end, intervalType, props);
 
@@ -1064,6 +1136,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
             // This is an ack from the server. Remove the pending change.
             this.removePendingChange(serializedInterval);
             const id: string = serializedInterval.properties[reservedIntervalIdKey];
+            // Could store the interval in the localOpMetadata to avoid the getIntervalById call
             interval = this.getIntervalById(id);
             if (interval) {
                 // Let the propertyManager prune its pending change-properties set.
@@ -1072,6 +1145,8 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
                         type: MergeTreeDeltaType.ANNOTATE,
                         props: serializedInterval.properties,
                     });
+
+                this.ackInterval(interval, op);
             }
         } else {
             // If there are pending changes with this ID, don't apply the remote start/end change, as the local ack
@@ -1130,6 +1205,53 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         });
     }
 
+    private getSlideToSegment(lref: LocalReference) {
+        const segoff = { segment: lref.segment, offset: lref.offset };
+        const newSegoff = this.client.getSlideToSegment(segoff);
+        const value: { segment: ISegment | undefined; offset: number | undefined; } | undefined
+            = (segoff === newSegoff) ? undefined : newSegoff;
+        return value;
+    }
+
+    private setSlideOnRemove(lref: LocalReference) {
+        let refType = lref.refType;
+        refType = refType & ~ReferenceType.StayOnRemove;
+        refType = refType | ReferenceType.SlideOnRemove;
+        lref.refType = refType;
+    }
+
+    private ackInterval(interval: TInterval, op: ISequencedDocumentMessage) {
+        // in current usage, interval is always a SequenceInterval
+        if (!(interval instanceof SequenceInterval)) {
+            return;
+        }
+
+        if (!refTypeIncludesFlag(interval.start, ReferenceType.StayOnRemove)) {
+            return;
+        }
+        assert(refTypeIncludesFlag(interval.end, ReferenceType.StayOnRemove),
+            0x2f7 /* start and end must both be StayOnRemove */);
+        const newStart = this.getSlideToSegment(interval.start);
+        const newEnd = this.getSlideToSegment(interval.end);
+        this.setSlideOnRemove(interval.start);
+        this.setSlideOnRemove(interval.end);
+
+        if (newStart || newEnd) {
+            this.localCollection.removeExistingInterval(interval);
+            if (newStart) {
+                const props = interval.start.properties;
+                interval.start = createPositionReferenceFromSegoff(this.client, newStart, interval.start.refType, op);
+                interval.start.addProperties(props);
+            }
+            if (newEnd) {
+                const props = interval.end.properties;
+                interval.end = createPositionReferenceFromSegoff(this.client, newEnd, interval.end.refType, op);
+                interval.end.addProperties(props);
+            }
+            this.localCollection.add(interval);
+        }
+    }
+
     /** @deprecated - use ackAdd */
     public addInternal(
         serializedInterval: ISerializedInterval,
@@ -1144,8 +1266,12 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         local: boolean,
         op: ISequencedDocumentMessage) {
         if (local) {
-            // Local ops were applied when the message was created and there's no "pending add"
-            // state to bookkeep
+            const id: string = serializedInterval.properties[reservedIntervalIdKey];
+            // Could store the interval in the localOpMetadata to avoid the getIntervalById call
+            const localInterval = this.getIntervalById(id);
+            if (localInterval) {
+                this.ackInterval(localInterval, op);
+            }
             return;
         }
 

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "0.59.4002";
+export const pkgVersion = "1.0.2";

package/src/sequence.ts

@@ -48,7 +48,7 @@ import {
     SummarySerializer,
 } from "@fluidframework/shared-object-base";
 import { IEventThisPlaceHolder } from "@fluidframework/common-definitions";
-import { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions";
+import { ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
 
 import {
     IntervalCollection,
@@ -173,7 +173,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         attributes: IChannelAttributes,
         public readonly segmentFromSpec: (spec: IJSONSegment) => ISegment,
     ) {
-        super(id, dataStoreRuntime, attributes);
+        super(id, dataStoreRuntime, attributes, "fluid_sequence_");
 
         this.loadedDeferred.promise.catch((error) => {
             this.logger.sendErrorEvent({ eventName: "SequenceLoadFailed" }, error);
@@ -463,7 +463,10 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         return this.intervalCollections.keys();
     }
 
-    protected summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats {
+    protected summarizeCore(
+        serializer: IFluidSerializer,
+        telemetryContext?: ITelemetryContext,
+    ): ISummaryTreeWithStats {
         const builder = new SummaryTreeBuilder();
 
         // conditionally write the interval collection blob
@@ -519,7 +522,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         this.client.startOrUpdateCollaboration(this.runtime.clientId);
     }
 
-    protected onDisconnect() {}
+    protected onDisconnect() { }
 
     protected reSubmitCore(content: any, localOpMetadata: unknown) {
         if (!this.intervalCollections.trySubmitMessage(content, localOpMetadata as IMapMessageLocalMetadata)) {
@@ -559,18 +562,17 @@ export abstract class SharedSegmentSequence<T extends ISegment>
                             || m.referenceSequenceNumber < collabWindow.minSeq
                             || m.sequenceNumber <= collabWindow.minSeq
                             || m.sequenceNumber <= collabWindow.currentSeq) {
-                            throw new Error(`Invalid catchup operations in snapshot: ${
-                                JSON.stringify({
-                                    op: {
-                                        seq: m.sequenceNumber,
-                                        minSeq: m.minimumSequenceNumber,
-                                        refSeq: m.referenceSequenceNumber,
-                                    },
-                                    collabWindow: {
-                                        seq: collabWindow.currentSeq,
-                                        minSeq: collabWindow.minSeq,
-                                    },
-                                })}`);
+                            throw new Error(`Invalid catchup operations in snapshot: ${JSON.stringify({
+                                op: {
+                                    seq: m.sequenceNumber,
+                                    minSeq: m.minimumSequenceNumber,
+                                    refSeq: m.referenceSequenceNumber,
+                                },
+                                collabWindow: {
+                                    seq: collabWindow.currentSeq,
+                                    minSeq: collabWindow.minSeq,
+                                },
+                            })}`);
                         }
                         this.processMergeTreeMsg(m);
                     });
@@ -666,7 +668,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
                 // shallow clone the message as we only overwrite top level properties,
                 // like referenceSequenceNumber and content only
                 stashMessage = {
-                    ... message,
+                    ...message,
                     referenceSequenceNumber: stashMessage.sequenceNumber - 1,
                     contents: ops.length !== 1 ? createGroupOp(...ops) : ops[0],
                 };

package/src/sharedIntervalCollection.ts

@@ -117,7 +117,7 @@ export class SharedIntervalCollection
         runtime: IFluidDataStoreRuntime,
         attributes: IChannelAttributes,
     ) {
-        super(id, runtime, attributes);
+        super(id, runtime, attributes, "fluid_sharedIntervalCollection_");
         this.intervalCollections = new DefaultMap(
             this.serializer,
             this.handle,