@fluidframework/container-runtime 2.0.0-internal.8.0.1 → 2.0.0-rc.1.0.1

package/dist/container-runtime-alpha.d.ts

@@ -51,7 +51,10 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: AllowInactiveRequestHeaderKey */
 
-/* Excluded from this release type: AllowTombstoneRequestHeaderKey */
+/** True if a tombstoned object should be returned without erroring
+ * @alpha
+ */
+export declare const AllowTombstoneRequestHeaderKey = "allowTombstone";
 
 /* Excluded from this release type: assertIsStableId */
 
@@ -65,7 +68,28 @@ export declare enum CompressionAlgorithms {
     lz4 = "lz4"
 }
 
-/* Excluded from this release type: ContainerMessageType */
+/**
+ * @alpha
+ */
+export declare enum ContainerMessageType {
+    FluidDataStoreOp = "component",
+    Attach = "attach",
+    ChunkedOp = "chunkedOp",
+    BlobAttach = "blobAttach",
+    Rejoin = "rejoin",
+    Alias = "alias",
+    /**
+     * An op containing an IdRange of Ids allocated using the runtime's IdCompressor since
+     * the last allocation op was sent.
+     * See the [IdCompressor README](./id-compressor/README.md) for more details.
+     */
+    IdAllocation = "idAllocation",
+    /**
+     * Garbage collection specific op. This is sent by the summarizer client when GC runs. It's used to synchronize GC
+     * state across all clients.
+     */
+    GC = "GC"
+}
 
 /**
  * Represents the runtime of the container. Contains helper functions/state of the container.
@@ -423,6 +447,10 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
     deleteSweepReadyNodes(sweepReadyRoutes: readonly string[]): readonly string[];
     /**
      * This is called to update objects that are tombstones.
+     *
+     * A Tombstoned object has been unreferenced long enough that GC knows it won't be referenced again.
+     * Tombstoned objects are eventually deleted by GC.
+     *
      * @param tombstonedRoutes - Data store and attachment blob routes that are tombstones in this Container.
      */
     updateTombstonedRoutes(tombstonedRoutes: readonly string[]): void;
@@ -546,7 +574,10 @@ export declare class ContainerRuntime extends TypedEventEmitter<IContainerRuntim
 
 /* Excluded from this release type: ContainerRuntimeMessage */
 
-/* Excluded from this release type: DefaultSummaryConfiguration */
+/**
+ * @alpha
+ */
+export declare const DefaultSummaryConfiguration: ISummaryConfiguration;
 
 /**
  * @alpha
@@ -621,7 +652,14 @@ export declare type GCVersion = number;
 
 /* Excluded from this release type: generateStableId */
 
-/* Excluded from this release type: IAckedSummary */
+/**
+ * A single summary which has already been acked by the server.
+ * @alpha
+ */
+export declare interface IAckedSummary {
+    readonly summaryOp: ISummaryOpMessage;
+    readonly summaryAck: ISummaryAckMessage;
+}
 
 /**
  * @alpha
@@ -661,7 +699,13 @@ export declare interface IBroadcastSummaryResult {
     readonly broadcastDuration: number;
 }
 
-/* Excluded from this release type: ICancellableSummarizerController */
+/**
+ * Similar to AbortController, but using promise instead of events
+ * @alpha
+ */
+export declare interface ICancellableSummarizerController extends ISummaryCancellationToken {
+    stop(reason: SummarizerStopReason): void;
+}
 
 /**
  * Similar to AbortSignal, but using promise instead of events
@@ -680,7 +724,14 @@ export declare interface ICancellationToken<T> {
 
 /* Excluded from this release type: IChunkedOp */
 
-/* Excluded from this release type: IClientSummaryWatcher */
+/**
+ * Watches summaries created by a specific client.
+ * @alpha
+ */
+export declare interface IClientSummaryWatcher extends IDisposable {
+    watchSummary(clientSequenceNumber: number): ISummary;
+    waitFlushed(): Promise<IAckedSummary | undefined>;
+}
 
 /**
  * Options for op compression.
@@ -835,6 +886,8 @@ export declare interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOpti
 }
 
 /**
+ * GC-specific metadata to be written into the summary.
+ *
  * @alpha
  */
 export declare interface IGCMetadata {
@@ -868,8 +921,15 @@ export declare interface IGCMetadata {
     readonly sweepEnabled?: boolean;
     /** If this is present, the session for this container will expire after this time and the container will close */
     readonly sessionExpiryTimeoutMs?: number;
-    /** How long to wait after an object is unreferenced before deleting it via GC Sweep */
-    readonly sweepTimeoutMs?: number;
+    /**
+     * How long to wait after an object is unreferenced before it becomes a Tombstone.
+     *
+     * After this point, there's a grace period before the object is deleted.
+     * @see IGCRuntimeOptions.sweepGracePeriodMs
+     *
+     * So the full sweep timeout in a session is tombstoneTimeoutMs + sweepGracePeriodMs.
+     */
+    readonly tombstoneTimeoutMs?: number;
 }
 
 /**
@@ -1001,7 +1061,11 @@ export declare interface INackSummaryResult extends IRetriableFailureResult {
     readonly ackNackDuration: number;
 }
 
-/* Excluded from this release type: InactiveResponseHeaderKey */
+/**
+ * Inactive error responses will have this header set to true
+ * @alpha
+ */
+export declare const InactiveResponseHeaderKey = "isInactive";
 
 /**
  * @alpha
@@ -1009,6 +1073,8 @@ export declare interface INackSummaryResult extends IRetriableFailureResult {
 export declare interface IOnDemandSummarizeOptions extends ISummarizeOptions {
     /** Reason for generating summary. */
     readonly reason: string;
+    /** In case of a failure, will attempt to retry based on if the failure is retriable. */
+    readonly retryOnFailure?: boolean;
 }
 
 /**
@@ -1108,7 +1174,41 @@ export declare interface ISummarizeOptions {
     readonly refreshLatestAck?: boolean;
 }
 
-/* Excluded from this release type: ISummarizer */
+/**
+ * @alpha
+ */
+export declare interface ISummarizer extends IEventProvider<ISummarizerEvents> {
+    /**
+     * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.
+     */
+    readonly ISummarizer?: ISummarizer;
+    stop(reason: SummarizerStopReason): void;
+    close(): void;
+    run(onBehalfOf: string, disableHeuristics?: boolean): Promise<SummarizerStopReason>;
+    /**
+     * Attempts to generate a summary on demand. If already running, takes no action.
+     * @param options - options controlling the summarize attempt
+     * @returns an alreadyRunning promise if a summarize attempt is already in progress,
+     * which will resolve when the current attempt completes. At that point caller can
+     * decide to try again or not. Otherwise, it will return an object containing promises
+     * that resolve as the summarize attempt progresses. They will resolve with success
+     * false if a failure is encountered.
+     */
+    summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;
+    /**
+     * Enqueue an attempt to summarize after the specified sequence number.
+     * If afterSequenceNumber is provided, the summarize attempt is "enqueued"
+     * to run once an eligible op comes in with sequenceNumber \>= afterSequenceNumber.
+     * @param options - options controlling the summarize attempt
+     * @returns an object containing an alreadyEnqueued flag to indicate if another
+     * summarize attempt has already been enqueued. It also may contain an overridden flag
+     * when alreadyEnqueued is true, that indicates whether this attempt forced the
+     * previous attempt to abort. If this attempt becomes enqueued, it returns an object
+     * containing promises that resolve as the summarize attempt progresses. They will
+     * resolve with success false if a failure is encountered.
+     */
+    enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
+}
 
 /**
  * @alpha
@@ -1155,7 +1255,17 @@ export declare interface ISummarizerRuntime extends IConnectableRuntime {
 
 /* Excluded from this release type: ISummarizingWarning */
 
-/* Excluded from this release type: ISummary */
+/**
+ * A single summary which can be tracked as it goes through its life cycle.
+ * The life cycle is: Local to Broadcast to Acked/Nacked.
+ * @alpha
+ */
+export declare interface ISummary {
+    readonly clientId: string;
+    readonly clientSequenceNumber: number;
+    waitBroadcast(): Promise<ISummaryOpMessage>;
+    waitAckNack(): Promise<ISummaryAckMessage | ISummaryNackMessage>;
+}
 
 /**
  * Interface for summary ack messages with typed contents.
@@ -1193,7 +1303,12 @@ export declare interface ISummaryBaseConfiguration {
  */
 export declare type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
 
-/* Excluded from this release type: ISummaryCollectionOpEvents */
+/**
+ * @alpha
+ */
+export declare interface ISummaryCollectionOpEvents extends IEvent {
+    (event: OpActionEventName, listener: OpActionEventListener): any;
+}
 
 /**
  * @alpha
@@ -1348,9 +1463,15 @@ export declare interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeR
 
 /* Excluded from this release type: neverCancelledSummaryToken */
 
-/* Excluded from this release type: OpActionEventListener */
+/**
+ * @alpha
+ */
+export declare type OpActionEventListener = (op: ISequencedDocumentMessage) => void;
 
-/* Excluded from this release type: OpActionEventName */
+/**
+ * @alpha
+ */
+export declare type OpActionEventName = MessageType.Summarize | MessageType.SummaryAck | MessageType.SummaryNack | "default";
 
 /* Excluded from this release type: RecentlyAddedContainerRuntimeMessageDetails */
 
@@ -1385,7 +1506,78 @@ export declare interface SubmitSummaryFailureData extends IRetriableFailureResul
  */
 export declare type SubmitSummaryResult = IBaseSummarizeResult | IGenerateSummaryTreeResult | IUploadSummaryResult | ISubmitSummaryOpResult;
 
-/* Excluded from this release type: Summarizer */
+/**
+ * Summarizer is responsible for coordinating when to generate and send summaries.
+ * It is the main entry point for summary work.
+ * It is created only by summarizing container (i.e. one with clientType === "summarizer")
+ * @alpha
+ */
+export declare class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements ISummarizer {
+    /** Reference to runtime that created this object.
+     * i.e. runtime with clientType === "summarizer"
+     */
+    private readonly runtime;
+    private readonly configurationGetter;
+    /** Represents an object that can generate summary.
+     * In practical terms, it's same runtime (this.runtime) with clientType === "summarizer".
+     */
+    private readonly internalsProvider;
+    readonly summaryCollection: SummaryCollection;
+    private readonly runCoordinatorCreateFn;
+    get ISummarizer(): this;
+    private readonly logger;
+    private runningSummarizer?;
+    private _disposed;
+    private starting;
+    private readonly stopDeferred;
+    constructor(
+    /** Reference to runtime that created this object.
+     * i.e. runtime with clientType === "summarizer"
+     */
+    runtime: ISummarizerRuntime, configurationGetter: () => ISummaryConfiguration, 
+    /** Represents an object that can generate summary.
+     * In practical terms, it's same runtime (this.runtime) with clientType === "summarizer".
+     */
+    internalsProvider: ISummarizerInternalsProvider, handleContext: IFluidHandleContext, summaryCollection: SummaryCollection, runCoordinatorCreateFn: (runtime: IConnectableRuntime) => Promise<ICancellableSummarizerController>);
+    run(onBehalfOf: string): Promise<SummarizerStopReason>;
+    /**
+     * Stops the summarizer from running.  This will complete
+     * the run promise, and also close the container.
+     * @param reason - reason code for stopping
+     */
+    stop(reason: SummarizerStopReason): void;
+    close(): void;
+    private runCore;
+    /**
+     * Should we try to run a last summary for the given stop reason?
+     * Currently only allows "parentNotConnected"
+     * @param stopReason - SummarizerStopReason
+     * @returns `true` if the stop reason can run a last summary, otherwise `false`.
+     */
+    static stopReasonCanRunLastSummary(stopReason: SummarizerStopReason): boolean;
+    private _heuristicData;
+    /**
+     * Put the summarizer in a started state, including creating and initializing the RunningSummarizer.
+     * The start request can come either from the SummaryManager (in the auto-summarize case) or from the user
+     * (in the on-demand case).
+     * @param onBehalfOf - ID of the client that requested that the summarizer start
+     * @param runCoordinator - cancellation token
+     * @param newConfig - Summary configuration to override the existing config when invoking the RunningSummarizer.
+     * @returns A promise that is fulfilled when the RunningSummarizer is ready.
+     */
+    private start;
+    private readonly handleSummarizeEvent;
+    /**
+     * Disposes of resources after running.  This cleanup will
+     * clear any outstanding timers and reset some of the state
+     * properties.
+     * Called by ContainerRuntime when it is disposed, as well as at the end the run().
+     */
+    dispose(): void;
+    summarizeOnDemand(options: IOnDemandSummarizeOptions): ISummarizeResults;
+    enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
+    recordSummaryAttempt?(summaryRefSeqNum?: number): void;
+}
 
 /**
  * @alpha
@@ -1429,7 +1621,59 @@ export declare type SummarizerStopReason =
 */
 | "latestSummaryStateStale";
 
-/* Excluded from this release type: SummaryCollection */
+/**
+ * Data structure that looks at the op stream to track summaries as they
+ * are broadcast, acked and nacked.
+ * It provides functionality for watching specific summaries.
+ * @alpha
+ */
+export declare class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEvents> {
+    private readonly deltaManager;
+    private readonly logger;
+    private readonly summaryWatchers;
+    private readonly pendingSummaries;
+    private refreshWaitNextAck;
+    private lastSummaryTimestamp;
+    private maxAckWaitTime;
+    private pendingAckTimerTimeoutCallback;
+    private lastAck;
+    get latestAck(): IAckedSummary | undefined;
+    emit(event: OpActionEventName, ...args: Parameters<OpActionEventListener>): boolean;
+    get opsSinceLastAck(): number;
+    addOpListener(listener: () => void): void;
+    removeOpListener(listener: () => void): void;
+    constructor(deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>, logger: ITelemetryLoggerExt);
+    /**
+     * Creates and returns a summary watcher for a specific client.
+     * This will allow for local sent summaries to be better tracked.
+     * @param clientId - client id for watcher
+     */
+    createWatcher(clientId: string): IClientSummaryWatcher;
+    removeWatcher(clientId: string): void;
+    setPendingAckTimerTimeoutCallback(maxAckWaitTime: number, timeoutCallback: () => void): void;
+    unsetPendingAckTimerTimeoutCallback(): void;
+    /**
+     * Returns a promise that resolves once all pending summary ops
+     * have been acked or nacked.
+     */
+    waitFlushed(): Promise<IAckedSummary | undefined>;
+    /**
+     * Returns a promise that resolves once a summary is acked that has a reference
+     * sequence number greater than or equal to the passed in sequence number.
+     * @param referenceSequenceNumber - reference sequence number to wait for
+     * @returns The latest acked summary
+     */
+    waitSummaryAck(referenceSequenceNumber: number): Promise<IAckedSummary>;
+    private parseContent;
+    /**
+     * Handler for ops; only handles ops relating to summaries.
+     * @param op - op message to handle
+     */
+    private handleOp;
+    private handleSummaryOp;
+    private handleSummaryAck;
+    private handleSummaryNack;
+}
 
 /**
  * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.
@@ -1437,7 +1681,11 @@ export declare type SummarizerStopReason =
  */
 export declare type SummaryStage = SubmitSummaryResult["stage"] | "unknown";
 
-/* Excluded from this release type: TombstoneResponseHeaderKey */
+/**
+ * Tombstone error responses will have this header set to true
+ * @alpha
+ */
+export declare const TombstoneResponseHeaderKey = "isTombstoned";
 
 /* Excluded from this release type: unpackRuntimeMessage */
 

package/dist/container-runtime-beta.d.ts

@@ -55,8 +55,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: assertIsStableId */
 
-/* Excluded from this release type: AttachState */
-
 /* Excluded from this release type: CompatModeBehavior */
 
 /* Excluded from this release type: CompressionAlgorithms */
@@ -77,8 +75,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: FluidDataStoreRegistryEntry */
 
-/* Excluded from this release type: FluidObject */
-
 /* Excluded from this release type: FlushMode */
 
 /* Excluded from this release type: GCFeatureMatrix */
@@ -93,8 +89,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IAckSummaryResult */
 
-/* Excluded from this release type: IAudience */
-
 /* Excluded from this release type: IBaseSummarizeResult */
 
 /* Excluded from this release type: IBlobManagerLoadInfo */
@@ -127,32 +121,16 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ICreateContainerMetadata */
 
-/* Excluded from this release type: ICriticalContainerError */
-
 /* Excluded from this release type: IDataStore */
 
-/* Excluded from this release type: IDeltaManager */
-
-/* Excluded from this release type: IDisposable */
-
 /* Excluded from this release type: IDocumentStorageService */
 
 /* Excluded from this release type: IEnqueueSummarizeOptions */
 
-/* Excluded from this release type: IEvent */
-
-/* Excluded from this release type: IEventProvider */
-
 /* Excluded from this release type: IFluidDataStoreContextDetached */
 
 /* Excluded from this release type: IFluidDataStoreRegistry */
 
-/* Excluded from this release type: IFluidHandle */
-
-/* Excluded from this release type: IFluidHandleContext */
-
-/* Excluded from this release type: IGarbageCollectionData */
-
 /* Excluded from this release type: IGCMetadata */
 
 /* Excluded from this release type: IGCRuntimeOptions */
@@ -165,12 +143,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IGetPendingLocalStateProps */
 
-/* Excluded from this release type: IIdCompressor */
-
 /* Excluded from this release type: IIdCompressorCore */
 
-/* Excluded from this release type: ILoaderOptions */
-
 /* Excluded from this release type: IMarkPhaseStats */
 
 /* Excluded from this release type: INackSummaryResult */
@@ -179,14 +153,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IOnDemandSummarizeOptions */
 
-/* Excluded from this release type: IProvideFluidHandleContext */
-
 /* Excluded from this release type: IRefreshSummaryAckOptions */
 
-/* Excluded from this release type: IRequest */
-
-/* Excluded from this release type: IResponse */
-
 /* Excluded from this release type: IRetriableFailureResult */
 
 /* Excluded from this release type: IRuntime */
@@ -243,16 +211,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ISummaryRuntimeOptions */
 
-/* Excluded from this release type: ISummaryStats */
-
-/* Excluded from this release type: ISummaryTreeWithStats */
-
 /* Excluded from this release type: ISweepPhaseStats */
 
-/* Excluded from this release type: ITelemetryContext */
-
-/* Excluded from this release type: ITelemetryLoggerExt */
-
 /* Excluded from this release type: IUploadSummaryResult */
 
 /* Excluded from this release type: NamedFluidDataStoreRegistryEntries */
@@ -285,8 +245,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: TombstoneResponseHeaderKey */
 
-/* Excluded from this release type: TypedEventEmitter */
-
 /* Excluded from this release type: unpackRuntimeMessage */
 
 export { }

package/dist/container-runtime-public.d.ts

@@ -55,8 +55,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: assertIsStableId */
 
-/* Excluded from this release type: AttachState */
-
 /* Excluded from this release type: CompatModeBehavior */
 
 /* Excluded from this release type: CompressionAlgorithms */
@@ -77,8 +75,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: FluidDataStoreRegistryEntry */
 
-/* Excluded from this release type: FluidObject */
-
 /* Excluded from this release type: FlushMode */
 
 /* Excluded from this release type: GCFeatureMatrix */
@@ -93,8 +89,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IAckSummaryResult */
 
-/* Excluded from this release type: IAudience */
-
 /* Excluded from this release type: IBaseSummarizeResult */
 
 /* Excluded from this release type: IBlobManagerLoadInfo */
@@ -127,32 +121,16 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ICreateContainerMetadata */
 
-/* Excluded from this release type: ICriticalContainerError */
-
 /* Excluded from this release type: IDataStore */
 
-/* Excluded from this release type: IDeltaManager */
-
-/* Excluded from this release type: IDisposable */
-
 /* Excluded from this release type: IDocumentStorageService */
 
 /* Excluded from this release type: IEnqueueSummarizeOptions */
 
-/* Excluded from this release type: IEvent */
-
-/* Excluded from this release type: IEventProvider */
-
 /* Excluded from this release type: IFluidDataStoreContextDetached */
 
 /* Excluded from this release type: IFluidDataStoreRegistry */
 
-/* Excluded from this release type: IFluidHandle */
-
-/* Excluded from this release type: IFluidHandleContext */
-
-/* Excluded from this release type: IGarbageCollectionData */
-
 /* Excluded from this release type: IGCMetadata */
 
 /* Excluded from this release type: IGCRuntimeOptions */
@@ -165,12 +143,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IGetPendingLocalStateProps */
 
-/* Excluded from this release type: IIdCompressor */
-
 /* Excluded from this release type: IIdCompressorCore */
 
-/* Excluded from this release type: ILoaderOptions */
-
 /* Excluded from this release type: IMarkPhaseStats */
 
 /* Excluded from this release type: INackSummaryResult */
@@ -179,14 +153,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: IOnDemandSummarizeOptions */
 
-/* Excluded from this release type: IProvideFluidHandleContext */
-
 /* Excluded from this release type: IRefreshSummaryAckOptions */
 
-/* Excluded from this release type: IRequest */
-
-/* Excluded from this release type: IResponse */
-
 /* Excluded from this release type: IRetriableFailureResult */
 
 /* Excluded from this release type: IRuntime */
@@ -243,16 +211,8 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: ISummaryRuntimeOptions */
 
-/* Excluded from this release type: ISummaryStats */
-
-/* Excluded from this release type: ISummaryTreeWithStats */
-
 /* Excluded from this release type: ISweepPhaseStats */
 
-/* Excluded from this release type: ITelemetryContext */
-
-/* Excluded from this release type: ITelemetryLoggerExt */
-
 /* Excluded from this release type: IUploadSummaryResult */
 
 /* Excluded from this release type: NamedFluidDataStoreRegistryEntries */
@@ -285,8 +245,6 @@ import { TypedEventEmitter } from '@fluid-internal/client-utils';
 
 /* Excluded from this release type: TombstoneResponseHeaderKey */
 
-/* Excluded from this release type: TypedEventEmitter */
-
 /* Excluded from this release type: unpackRuntimeMessage */
 
 export { }