@fluidframework/container-runtime 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/src/summary/summarizerTypes.ts

@@ -19,6 +19,7 @@ import { SummarizeReason } from "./summaryGenerator";
 /**
  * Similar to AbortSignal, but using promise instead of events
  * @param T - cancellation reason type
+ * @public
  */
 export interface ICancellationToken<T> {
 	/** Tells if this cancellable token is cancelled */
@@ -30,11 +31,15 @@ export interface ICancellationToken<T> {
 	readonly waitCancelled: Promise<T>;
 }
 
-/* Similar to AbortSignal, but using promise instead of events */
+/**
+ * Similar to AbortSignal, but using promise instead of events
+ * @public
+ */
 export type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
 
 /**
  * Data required to update internal tracking state after receiving a Summary Ack.
+ * @public
  */
 export interface IRefreshSummaryAckOptions {
 	/** Handle from the ack's summary op. */
@@ -47,6 +52,9 @@ export interface IRefreshSummaryAckOptions {
 	readonly summaryLogger: ITelemetryLoggerExt;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizerInternalsProvider {
 	/** Encapsulates the work to walk the internals of the running container to generate a summary */
 	submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;
@@ -57,6 +65,7 @@ export interface ISummarizerInternalsProvider {
 
 /**
  * @deprecated Options that control the behavior of a running summarizer.
+ * @public
  * */
 export interface ISummarizerOptions {
 	/**
@@ -68,11 +77,17 @@ export interface ISummarizerOptions {
 	disableHeuristics: boolean;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizingWarning extends ContainerWarning {
 	readonly errorType: "summarizingError";
 	readonly logged: boolean;
 }
 
+/**
+ * @public
+ */
 export interface IConnectableRuntime {
 	readonly disposed: boolean;
 	readonly connected: boolean;
@@ -80,6 +95,9 @@ export interface IConnectableRuntime {
 	once(event: "connected" | "disconnected" | "dispose", listener: () => void): this;
 }
 
+/**
+ * @public
+ */
 export interface ISummarizerRuntime extends IConnectableRuntime {
 	readonly logger: ITelemetryLoggerExt;
 	/** clientId of parent (non-summarizing) container that owns summarizer container */
@@ -97,18 +115,25 @@ export interface ISummarizerRuntime extends IConnectableRuntime {
 	): this;
 }
 
-/** Options affecting summarize behavior. */
+/**
+ * Options affecting summarize behavior.
+ * @public
+ */
 export interface ISummarizeOptions {
 	/** True to generate the full tree with no handle reuse optimizations; defaults to false */
 	readonly fullTree?: boolean;
 	/**
 	 * True to ask the server what the latest summary is first; defaults to false
 	 *
-	 * @deprecated - Summarize will not refresh latest snapshot state anymore.
+	 * @deprecated Summarize will not refresh latest snapshot state anymore. Instead it updates the cache and closes.
+	 * It's expected a new summarizer client will be created, likely by the same parent.
 	 */
 	readonly refreshLatestAck?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface ISubmitSummaryOptions extends ISummarizeOptions {
 	/** Logger to use for correlated summary events */
 	readonly summaryLogger: ITelemetryLoggerExt;
@@ -118,12 +143,18 @@ export interface ISubmitSummaryOptions extends ISummarizeOptions {
 	readonly finalAttempt?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface IOnDemandSummarizeOptions extends ISummarizeOptions {
 	/** Reason for generating summary. */
 	readonly reason: string;
 }
 
-/** Options to use when enqueueing a summarize attempt. */
+/**
+ * Options to use when enqueueing a summarize attempt.
+ * @public
+ */
 export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
 	/** If specified, The summarize attempt will not occur until after this sequence number. */
 	readonly afterSequenceNumber?: number;
@@ -140,6 +171,7 @@ export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
 /**
  * In addition to the normal summary tree + stats, this contains additional stats
  * only relevant at the root of the tree.
+ * @public
  */
 export interface IGeneratedSummaryStats extends ISummaryStats {
 	/** The total number of data stores in the container. */
@@ -156,7 +188,10 @@ export interface IGeneratedSummaryStats extends ISummaryStats {
 	readonly summaryNumber: number;
 }
 
-/** Base results for all submitSummary attempts. */
+/**
+ * Base results for all submitSummary attempts.
+ * @public
+ */
 export interface IBaseSummarizeResult {
 	readonly stage: "base";
 	/** Error object related to failed summarize attempt. */
@@ -166,7 +201,10 @@ export interface IBaseSummarizeResult {
 	readonly minimumSequenceNumber: number;
 }
 
-/** Results of submitSummary after generating the summary tree. */
+/**
+ * Results of submitSummary after generating the summary tree.
+ * @public
+ */
 export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "stage"> {
 	readonly stage: "generate";
 	/** Generated summary tree. */
@@ -179,7 +217,10 @@ export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "
 	readonly forcedFullTree: boolean;
 }
 
-/** Results of submitSummary after uploading the tree to storage. */
+/**
+ * Results of submitSummary after uploading the tree to storage.
+ * @public
+ */
 export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "stage"> {
 	readonly stage: "upload";
 	/** The handle returned by storage pointing to the uploaded summary tree. */
@@ -188,7 +229,10 @@ export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "
 	readonly uploadDuration: number;
 }
 
-/** Results of submitSummary after submitting the summarize op. */
+/**
+ * Results of submitSummary after submitting the summarize op.
+ * @public
+ */
 export interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stage" | "error"> {
 	readonly stage: "submit";
 	/** The client sequence number of the summarize op submitted for the summary. */
@@ -212,6 +256,7 @@ export interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stag
  * 3. "upload" - the summary was uploaded to storage, and the result contains the server-provided handle
  *
  * 4. "submit" - the summarize op was submitted, and the result contains the op client sequence number.
+ * @public
  */
 export type SubmitSummaryResult =
 	| IBaseSummarizeResult
@@ -219,34 +264,55 @@ export type SubmitSummaryResult =
 	| IUploadSummaryResult
 	| ISubmitSummaryOpResult;
 
-/** The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage. */
+/**
+ * The stages of Summarize, used to describe how far progress succeeded in case of a failure at a later stage.
+ * @public
+ */
 export type SummaryStage = SubmitSummaryResult["stage"] | "unknown";
 
-/** Type for summarization failures that are retriable. */
+/**
+ * Type for summarization failures that are retriable.
+ * @public
+ */
 export interface IRetriableFailureResult {
 	readonly retryAfterSeconds?: number;
 }
 
-/** The data in summarizer result when submit summary stage fails. */
+/**
+ * The data in summarizer result when submit summary stage fails.
+ * @public
+ */
 export interface SubmitSummaryFailureData extends IRetriableFailureResult {
 	stage: SummaryStage;
 }
 
+/**
+ * @public
+ */
 export interface IBroadcastSummaryResult {
 	readonly summarizeOp: ISummaryOpMessage;
 	readonly broadcastDuration: number;
 }
 
+/**
+ * @public
+ */
 export interface IAckSummaryResult {
 	readonly summaryAckOp: ISummaryAckMessage;
 	readonly ackNackDuration: number;
 }
 
+/**
+ * @public
+ */
 export interface INackSummaryResult extends IRetriableFailureResult {
 	readonly summaryNackOp: ISummaryNackMessage;
 	readonly ackNackDuration: number;
 }
 
+/**
+ * @public
+ */
 export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 	| {
 			success: true;
@@ -259,6 +325,9 @@ export type SummarizeResultPart<TSuccess, TFailure = undefined> =
 			error: any;
 	  };
 
+/**
+ * @public
+ */
 export interface ISummarizeResults {
 	/** Resolves when we generate, upload, and submit the summary. */
 	readonly summarySubmitted: Promise<
@@ -272,6 +341,9 @@ export interface ISummarizeResults {
 	>;
 }
 
+/**
+ * @public
+ */
 export type EnqueueSummarizeResult =
 	| (ISummarizeResults & {
 			/**
@@ -299,6 +371,9 @@ export type EnqueueSummarizeResult =
 			readonly overridden?: undefined;
 	  };
 
+/**
+ * @public
+ */
 export type SummarizerStopReason =
 	/** Summarizer client failed to summarize in all 3 consecutive attempts. */
 	| "failToSummarize"
@@ -325,16 +400,26 @@ export type SummarizerStopReason =
 	 */
 	| "latestSummaryStateStale";
 
+/**
+ * @public
+ */
 export interface ISummarizeEventProps {
 	result: "success" | "failure" | "canceled";
 	currentAttempt: number;
 	maxAttempts: number;
 	error?: any;
 }
+
+/**
+ * @public
+ */
 export interface ISummarizerEvents extends IEvent {
 	(event: "summarize", listener: (props: ISummarizeEventProps) => void);
 }
 
+/**
+ * @public
+ */
 export interface ISummarizer extends IEventProvider<ISummarizerEvents> {
 	/**
 	 * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.

package/src/summary/summaryCollection.ts

@@ -19,6 +19,7 @@ import {
 
 /**
  * Interface for summary op messages with typed contents.
+ * @public
  */
 export interface ISummaryOpMessage extends ISequencedDocumentMessage {
 	type: MessageType.Summarize;
@@ -27,6 +28,7 @@ export interface ISummaryOpMessage extends ISequencedDocumentMessage {
 
 /**
  * Interface for summary ack messages with typed contents.
+ * @public
  */
 export interface ISummaryAckMessage extends ISequencedDocumentMessage {
 	type: MessageType.SummaryAck;
@@ -35,6 +37,7 @@ export interface ISummaryAckMessage extends ISequencedDocumentMessage {
 
 /**
  * Interface for summary nack messages with typed contents.
+ * @public
  */
 export interface ISummaryNackMessage extends ISequencedDocumentMessage {
 	type: MessageType.SummaryNack;
@@ -44,6 +47,7 @@ export interface ISummaryNackMessage extends ISequencedDocumentMessage {
 /**
  * A single summary which can be tracked as it goes through its life cycle.
  * The life cycle is: Local to Broadcast to Acked/Nacked.
+ * @public
  */
 export interface ISummary {
 	readonly clientId: string;
@@ -54,6 +58,7 @@ export interface ISummary {
 
 /**
  * A single summary which has already been acked by the server.
+ * @public
  */
 export interface IAckedSummary {
 	readonly summaryOp: ISummaryOpMessage;
@@ -140,6 +145,7 @@ class Summary implements ISummary {
 
 /**
  * Watches summaries created by a specific client.
+ * @public
  */
 export interface IClientSummaryWatcher extends IDisposable {
 	watchSummary(clientSequenceNumber: number): ISummary;
@@ -207,13 +213,23 @@ class ClientSummaryWatcher implements IClientSummaryWatcher {
 		this._disposed = true;
 	}
 }
-
+/**
+ * @public
+ */
 export type OpActionEventName =
 	| MessageType.Summarize
 	| MessageType.SummaryAck
 	| MessageType.SummaryNack
 	| "default";
+
+/**
+ * @public
+ */
 export type OpActionEventListener = (op: ISequencedDocumentMessage) => void;
+
+/**
+ * @public
+ */
 export interface ISummaryCollectionOpEvents extends IEvent {
 	(event: OpActionEventName, listener: OpActionEventListener);
 }
@@ -222,6 +238,7 @@ export interface ISummaryCollectionOpEvents extends IEvent {
  * 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.
+ * @public
  */
 export class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEvents> {
 	// key: clientId
@@ -405,6 +422,7 @@ export class SummaryCollection extends TypedEventEmitter<ISummaryCollectionOpEve
 	private handleSummaryAck(op: ISummaryAckMessage) {
 		const seq = op.contents.summaryProposal.summarySequenceNumber;
 		const summary = this.pendingSummaries.get(seq);
+		// eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- optional chain is not logically equivalent
 		if (!summary || summary.summaryOp === undefined) {
 			// Summary ack without an op should be rare. We could fetch the
 			// reference sequence number from the snapshot, but instead we

package/src/summary/summaryFormat.ts

@@ -84,6 +84,10 @@ export function getAttributesFormatVersion(attributes: ReadFluidDataStoreAttribu
 export function hasIsolatedChannels(attributes: ReadFluidDataStoreAttributes): boolean {
 	return !!attributes.summaryFormatVersion && !attributes.disableIsolatedChannels;
 }
+
+/**
+ * @public
+ */
 export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGCMetadata {
 	readonly summaryFormatVersion: 1;
 	/** The last message processed at the time of summary. Only primitive property types are added to the summary. */
@@ -98,6 +102,9 @@ export interface IContainerRuntimeMetadata extends ICreateContainerMetadata, IGC
 	readonly idCompressorEnabled?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface ICreateContainerMetadata {
 	/** Runtime version of the container when it was first created */
 	createContainerRuntimeVersion?: string;
@@ -105,7 +112,10 @@ export interface ICreateContainerMetadata {
 	createContainerTimestamp?: number;
 }
 
-/** The properties of an ISequencedDocumentMessage to be stored in the metadata blob in summary. */
+/**
+ * The properties of an ISequencedDocumentMessage to be stored in the metadata blob in summary.
+ * @public
+ */
 export type ISummaryMetadataMessage = Pick<
 	ISequencedDocumentMessage,
 	| "clientId"

package/src/summary/summaryGenerator.ts

@@ -47,12 +47,12 @@ export async function raceTimer<T>(
 	cancellationToken?: ISummaryCancellationToken,
 ): Promise<raceTimerResult<T>> {
 	const promises: Promise<raceTimerResult<T>>[] = [
-		promise.then((value) => ({ result: "done", value } as const)),
-		timer.then(({ timerResult: result }) => ({ result } as const)),
+		promise.then((value) => ({ result: "done", value }) as const),
+		timer.then(({ timerResult: result }) => ({ result }) as const),
 	];
 	if (cancellationToken !== undefined) {
 		promises.push(
-			cancellationToken.waitCancelled.then(() => ({ result: "cancelled" } as const)),
+			cancellationToken.waitCancelled.then(() => ({ result: "cancelled" }) as const),
 		);
 	}
 	return Promise.race(promises);

package/src/summary/summaryManager.ts

@@ -114,7 +114,7 @@ export class SummaryManager extends TypedEventEmitter<ISummarizerEvents> impleme
 		parentLogger: ITelemetryBaseLogger,
 		/** Creates summarizer by asking interactive container to spawn summarizing container and
 		 * get back its Summarizer instance. */
-		private readonly requestSummarizerFn: () => Promise<ISummarizer>,
+		private readonly createSummarizerFn: () => Promise<ISummarizer>,
 		private readonly startThrottler: IThrottler,
 		{
 			initialDelayMs = defaultInitialDelayMs,
@@ -264,7 +264,7 @@ export class SummaryManager extends TypedEventEmitter<ISummarizerEvents> impleme
 				);
 				this.state = SummaryManagerState.Running;
 
-				const summarizer = await this.requestSummarizerFn();
+				const summarizer = await this.createSummarizerFn();
 				this.summarizer = summarizer;
 				this.summarizer.on("summarize", this.handleSummarizeEvent);
 

package/src/gc/gcEarlyAdoption.md

@@ -1,145 +0,0 @@
-# Garbage Collection: Advanced configuration for early adopters
-
-_For a technical overview of Garbage Collection, start with [GarbageCollection.md](./garbageCollection.md)_
-
-GC Sweep is not yet enabled by default, and until that time early adopters have several configuration options available
-for how to enable GC and monitor for any GC-impacting bugs that would need to be mitigated.
-
-Please refer to the section [Techniques Used for Configuration](./garbageCollection.md#techniques-used-for-configuration)
-before continuing, to ensure you're familiar with using "GC Options" and "Config Settings" for configuring GC.
-
-## What's on by default
-
-GC Mark Phase is enabled by default, which includes marking objects that are ready to be deleted as Tombstones.
-FF will log an informational event if/when a Tombstoned object is loaded - a scenario that would represent data loss if Sweep were enabled.
-The eventName for the Tombstone log ends with `GC_Tombstone_DataStore_Requested`.
-
-There's a similar event logged long before an object is Tombstoned. Ater only 7 days (configurable), an unreferenced object is considered
-"Inactive", and FF will log if an Inactive object is loaded as well.
-The eventName for the Inactive log ends with `InactiveObject_Loaded`.
-
-## Getting earlier signals: Shortening the InactiveObject timeout
-
-The default timeout for an unreferenced object to become "Inactive" is 7 days. This is intended to be long enough such that
-it's very unlikely to hit a legitimate case where an object is revived within the same session it was deleted (e.g. delete then undo).
-Based on your application's user experience, you may choose to shorten this timeout to get an earlier signal (but beware of false positives).
-
-To override the default InactiveObject timeout, use the `inactiveTimeoutMs` GC Option.
-There's also a Config Setting which can be used for testing (if the Config Provider allows overriding via localStorage/sessionStorage):
-`Fluid.GarbageCollection.TestOverride.InactiveTimeoutMs`
-
-## Enabling Tombstone Enforcement
-
-By default, GC is marking objects as Tombstoned, but merely logging if they're used after that point.
-You can enable enforcement of Tombstone objects to simulate real Sweep while having the peace of mind
-that the data is not yet deleted from the user's file, and can be recovered.
-
-The first step is to prevent the Fluid Framework from loading a Tombstoned object (via `handle.get()` as described previously),
-by using this Config Setting:
-
-```ts
-"Fluid.GarbageCollection.ThrowOnTombstoneLoad": true
-```
-
-Now, even with `Fluid.GarbageCollection.ThrowOnTombstoneLoad` set to true, changes to a Tombstoned object will be allowed.
-This is required for the advanced recovery options to work, explained [below](#advanced-back-door-recovering-and-reviving-tombstoned-objects).
-
-To instruct FF to treat Tombstoned objects as if they are truly not present in the document, use this Config Setting:
-
-```ts
-"Fluid.GarbageCollection.ThrowOnTombstoneUsage": true
-```
-
-### In case of emergency: Bumping the gcTombstoneGeneration
-
-GC includes a mechanism for Tombstone by which all new documents may be stamped with a "Generation" number,
-and if set then Tombstone is only enforceable for documents of the latest Generation. This number is specified
-via the `gcTombstoneGeneration` GC Option, and will not change over the lifetime of a given document.
-
-In case a bug is released that is found to cause GC errors, a bump to the gcTombstoneGeneration can be incuded
-with the fix, which will prevent any user pain for those potentially affected documents that were exposed to the bug.
-
-If gcTombstoneGeneration is unset, Tombstone enforcement will be enabled/disabled as otherwise configured.
-In other words, until you start using this, Tombstone enforcement will apply to all documents.
-
-### Advanced "Back door": Recovering and reviving Tombstoned objects
-
-If your application has Tombstone enabled and your users are encountering Tombstones - even at the point where
-Tombstone enforcement is enabled - there is a way to still access these objects to recover them and property
-reference them ("revival"). However, please understand that this is an advanced and unsupported path that may
-be immediately deprecated at any time.
-
-As mentioned above, bumping the gcTombstoneGeneration will free up impacted documents, but that's a permanent
-mitigation - those documents will never be exposed to GC Tombstone or Sweep.
-
-If there's a particular codepath in your application where objects being loaded may be Tombstoned,
-you may use this advanced "back door" to recover them and then properly reference them, thus restoring the document.
-For this to work, you must disable the `Fluid.GarbageCollection.ThrowOnTombstoneUsage` Config Setting.
-
-When a Tombstoned object (via `handle.get()`) fails to load, the 404 response error object has an `underlyingResponseHeaders` with the
-`isTombstoned` flag set to true: i.e. `error.underlyingResponseHeaders?.isTombstoned === true`. In this case,
-you may turn around and use `IContainerRuntime.resolveHandle` with `allowTombstone: true` in `IRequest.headers` to request
-the object again - this time it will succeed.
-
-To be very clear once again - This path uses deprecated APIs (`resolveHandle`) and comes with no guarantees of support.
-
-### Tombstones and the Summarizer Client
-
-Note: The Summarizer client will _never_ throw on usage or load of a Tombstoned object.
-
-## Enabling Sweep
-
-To enable Sweep for the first time, set this GC Option:
-
-```ts
-gcSweepGeneration: 0;
-```
-
-This will enable sweep for all documents moving forward _as well as_ any documents created with `gcTombstoneGeneration: 0`
-(this is a special case in the code).
-
-### A caveat...
-
-If you used `gcTombstoneGeneration` **and ever bumped it**, you should skip 0 here to avoid enabling Sweep for old / at-risk documents:
-
-```ts
-gcSweepGeneration: 1;
-```
-
-Remember, you can always bump `gcSweepGeneration` to disable Sweep for all existing documents and start fresh,
-in case a major bug is discovered and fixed.
-
-### More about gcSweepGeneration and gcTombstoneGeneration
-
-`gcSweepGeneration` is persisted and immutable in the document, just like `gcTombstoneGeneration`.
-However, behavior differs in a few important ways.
-
-For Tombstone, if `gcTombstoneGeneration` is not set, Tombstone enforcement will be **enabled**.
-For Sweep however, if `gcSweepGeneration` is not set, Sweep enforcement will be **disabled**.
-
-This means that until the `gcSweepGeneration` GC Option is set, _no existing document will be eligible for Sweep, ever_.
-So all documents created since the most recent bump to the gcSweepGeneration will have Sweep enabled.
-Note that if `gcSweepGeneration` is set and matches, Tombstone Mode is off for the session and `gcTombstoneGeneration` is ignored.
-
-And as mentioned above, there is a special case when `gcSweepGeneration === 0`: Any document with `gcTombstoneGeneration: 0` will
-be eligible for Sweep as well. This was done for historical reasons due to circumstances during GC's development.
-
-## More Advanced Configurations
-
-There are a handful of other configuration options/settings that can be used to tweak GC's behavior,
-mostly for testing. Please refer to the function [`generateGCConfigs` in gcConfigs.ts](./gcConfigs.ts) and the
-[setting/option names listed in gcDefinitions.ts](./gcDefinitions.ts) for the full story.
-
-Examples of available advanced configuration include:
-
--   Disabling GC permanently for new files
--   Overriding GC Mark/Sweep enablement for this session:
-    -   Disabling running GC Mark and/or Sweep phases for this session
-    -   Forcing GC Mark and/or Sweep to run for this session even if otherwise it would be disabled
-    -   Disabling Tombstone Mode (don't even mark objects as Tombstones)
-    -   Disabling the deletion of either DataStores or AttachmentBlobs independent of one another (when Sweep is enabled)
--   Overriding the default Session Expiry for new files (or disabling it altogether, which will also disable Tombstone/Sweep)
--   Overriding the Sweep Timeout, _independent of Session Expiry_, so use with care (for testing purposes only - data loss could occur)
--   Running in "Test Mode", where objects are deleted as soon as they're unreferenced
--   Force "Full GC" to run, which ignores incremental optimizations based on previously computed GC Data
--   Treat InactiveObjects like Tombstones: throw an error on load (with the same back door to follow-up with a successful request)