@fluidframework/container-runtime 2.13.0 → 2.21.0

package/lib/summary/summarizerTypes.d.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 import { IDeltaManager, ContainerWarning } from "@fluidframework/container-definitions/internal";
-import type { ISummarizerEvents as NewISummarizerEvents, SummarizerStopReason as NewSummarizerStopReason } from "@fluidframework/container-runtime-definitions/internal";
-import { IEvent, IEventProvider, ITelemetryBaseProperties, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import type { ISummarizerEvents, SummarizerStopReason } from "@fluidframework/container-runtime-definitions/internal";
+import { IEventProvider, ITelemetryBaseProperties, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { ISummaryTree } from "@fluidframework/driver-definitions";
 import { IDocumentMessage, ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 import { ISummaryStats } from "@fluidframework/runtime-definitions/internal";
@@ -17,9 +17,12 @@ import { SummarizeReason } from "./summaryGenerator.js";
  * @param T - cancellation reason type
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface ICancellationToken<T> {
-    /** Tells if this cancellable token is cancelled */
+    /**
+     * Tells if this cancellable token is cancelled
+     */
     readonly cancelled: boolean;
     /**
      * Promise that gets fulfilled when this cancellable token is cancelled
@@ -31,31 +34,46 @@ export interface ICancellationToken<T> {
  * Similar to AbortSignal, but using promise instead of events
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
-export type ISummaryCancellationToken = ICancellationToken<NewSummarizerStopReason>;
+export type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
 /**
  * Data required to update internal tracking state after receiving a Summary Ack.
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface IRefreshSummaryAckOptions {
-    /** Handle from the ack's summary op. */
+    /**
+     * Handle from the ack's summary op.
+     */
     readonly proposalHandle: string | undefined;
-    /** Handle from the summary ack just received */
+    /**
+     * Handle from the summary ack just received
+     */
     readonly ackHandle: string;
-    /** Reference sequence number from the ack's summary op */
+    /**
+     * Reference sequence number from the ack's summary op
+     */
     readonly summaryRefSeq: number;
-    /** Telemetry logger to which telemetry events will be forwarded. */
+    /**
+     * Telemetry logger to which telemetry events will be forwarded.
+     */
     readonly summaryLogger: ITelemetryLoggerExt;
 }
 /**
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface ISummarizerInternalsProvider {
-    /** Encapsulates the work to walk the internals of the running container to generate a summary */
+    /**
+     * Encapsulates the work to walk the internals of the running container to generate a summary
+     */
     submitSummary(options: ISubmitSummaryOptions): Promise<SubmitSummaryResult>;
-    /** Callback whenever a new SummaryAck is received, to update internal tracking state */
+    /**
+     * Callback whenever a new SummaryAck is received, to update internal tracking state
+     */
     refreshLatestSummaryAck(options: IRefreshSummaryAckOptions): Promise<void>;
 }
 /**
@@ -68,6 +86,7 @@ export interface ISummarizingWarning extends ContainerWarning {
 /**
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface IConnectableRuntime {
     readonly disposed: boolean;
@@ -78,10 +97,13 @@ export interface IConnectableRuntime {
 /**
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface ISummarizerRuntime extends IConnectableRuntime {
     readonly baseLogger: ITelemetryBaseLogger;
-    /** clientId of parent (non-summarizing) container that owns summarizer container */
+    /**
+     * clientId of parent (non-summarizing) container that owns summarizer container
+     */
     readonly summarizerClientId: string | undefined;
     readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
     disposeFn(): void;
@@ -95,21 +117,32 @@ export interface ISummarizerRuntime extends IConnectableRuntime {
  * @alpha
  */
 export interface ISummarizeOptions {
-    /** True to generate the full tree with no handle reuse optimizations; defaults to false */
+    /**
+     * True to generate the full tree with no handle reuse optimizations; defaults to false
+     */
     readonly fullTree?: boolean;
 }
 /**
  * @legacy
  * @alpha
+ * @deprecated This type will be moved to internal in 2.30. External usage is not necessary or supported.
  */
 export interface ISubmitSummaryOptions extends ISummarizeOptions {
-    /** Logger to use for correlated summary events */
+    /**
+     * Logger to use for correlated summary events
+     */
     readonly summaryLogger: ITelemetryLoggerExt;
-    /** Tells when summary process should be cancelled */
+    /**
+     * Tells when summary process should be cancelled
+     */
     readonly cancellationToken: ISummaryCancellationToken;
-    /** Summarization may be attempted multiple times. This tells whether this is the final summarization attempt. */
+    /**
+     * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt.
+     */
     readonly finalAttempt?: boolean;
-    /** The sequence number of the latest summary used to validate if summary state is correct before summarizing */
+    /**
+     * The sequence number of the latest summary used to validate if summary state is correct before summarizing
+     */
     readonly latestSummaryRefSeqNum: number;
 }
 /**
@@ -117,9 +150,13 @@ export interface ISubmitSummaryOptions extends ISummarizeOptions {
  * @alpha
  */
 export interface IOnDemandSummarizeOptions extends ISummarizeOptions {
-    /** Reason for generating summary. */
+    /**
+     * Reason for generating summary.
+     */
     readonly reason: string;
-    /** In case of a failure, will attempt to retry based on if the failure is retriable. */
+    /**
+     * In case of a failure, will attempt to retry based on if the failure is retriable.
+     */
     readonly retryOnFailure?: boolean;
 }
 /**
@@ -128,7 +165,9 @@ export interface IOnDemandSummarizeOptions extends ISummarizeOptions {
  * @alpha
  */
 export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
-    /** If specified, The summarize attempt will not occur until after this sequence number. */
+    /**
+     * If specified, The summarize attempt will not occur until after this sequence number.
+     */
     readonly afterSequenceNumber?: number;
     /**
      * True to override the existing enqueued summarize attempt if there is one.
@@ -145,17 +184,29 @@ export interface IEnqueueSummarizeOptions extends IOnDemandSummarizeOptions {
  * @alpha
  */
 export interface IGeneratedSummaryStats extends ISummaryStats {
-    /** The total number of data stores in the container. */
+    /**
+     * The total number of data stores in the container.
+     */
     readonly dataStoreCount: number;
-    /** The number of data stores that were summarized in this summary. */
+    /**
+     * The number of data stores that were summarized in this summary.
+     */
     readonly summarizedDataStoreCount: number;
-    /** The number of data stores whose GC reference state was updated in this summary. */
+    /**
+     * The number of data stores whose GC reference state was updated in this summary.
+     */
     readonly gcStateUpdatedDataStoreCount?: number;
-    /** The size of the gc blobs in this summary. */
+    /**
+     * The size of the gc blobs in this summary.
+     */
     readonly gcTotalBlobsSize?: number;
-    /** The number of gc blobs in this summary. */
+    /**
+     * The number of gc blobs in this summary.
+     */
     readonly gcBlobNodeCount?: number;
-    /** The summary number for a container's summary. Incremented on summaries throughout its lifetime. */
+    /**
+     * The summary number for a container's summary. Incremented on summaries throughout its lifetime.
+     */
     readonly summaryNumber: number;
 }
 /**
@@ -173,9 +224,13 @@ export interface IRetriableFailureError extends Error {
  */
 export interface IBaseSummarizeResult {
     readonly stage: "base";
-    /** Retriable error object related to failed summarize attempt. */
+    /**
+     * Retriable error object related to failed summarize attempt.
+     */
     readonly error: IRetriableFailureError | undefined;
-    /** Reference sequence number as of the generate summary attempt. */
+    /**
+     * Reference sequence number as of the generate summary attempt.
+     */
     readonly referenceSequenceNumber: number;
     readonly minimumSequenceNumber: number;
 }
@@ -186,11 +241,17 @@ export interface IBaseSummarizeResult {
  */
 export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "stage"> {
     readonly stage: "generate";
-    /** Generated summary tree. */
+    /**
+     * Generated summary tree.
+     */
     readonly summaryTree: ISummaryTree;
-    /** Stats for generated summary tree. */
+    /**
+     * Stats for generated summary tree.
+     */
     readonly summaryStats: IGeneratedSummaryStats;
-    /** Time it took to generate the summary tree and stats. */
+    /**
+     * Time it took to generate the summary tree and stats.
+     */
     readonly generateDuration: number;
 }
 /**
@@ -200,9 +261,13 @@ export interface IGenerateSummaryTreeResult extends Omit<IBaseSummarizeResult, "
  */
 export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "stage"> {
     readonly stage: "upload";
-    /** The handle returned by storage pointing to the uploaded summary tree. */
+    /**
+     * The handle returned by storage pointing to the uploaded summary tree.
+     */
     readonly handle: string;
-    /** Time it took to upload the summary tree to storage. */
+    /**
+     * Time it took to upload the summary tree to storage.
+     */
     readonly uploadDuration: number;
 }
 /**
@@ -212,9 +277,13 @@ export interface IUploadSummaryResult extends Omit<IGenerateSummaryTreeResult, "
  */
 export interface ISubmitSummaryOpResult extends Omit<IUploadSummaryResult, "stage" | "error"> {
     readonly stage: "submit";
-    /** The client sequence number of the summarize op submitted for the summary. */
+    /**
+     * The client sequence number of the summarize op submitted for the summary.
+     */
     readonly clientSequenceNumber: number;
-    /** Time it took to submit the summarize op to the broadcasting service. */
+    /**
+     * Time it took to submit the summarize op to the broadcasting service.
+     */
     readonly submitOpDuration: number;
 }
 /**
@@ -292,11 +361,17 @@ export type SummarizeResultPart<TSuccess, TFailure = undefined> = {
  * @alpha
  */
 export interface ISummarizeResults {
-    /** Resolves when we generate, upload, and submit the summary. */
+    /**
+     * Resolves when we generate, upload, and submit the summary.
+     */
     readonly summarySubmitted: Promise<SummarizeResultPart<SubmitSummaryResult, SubmitSummaryFailureData>>;
-    /** Resolves when we observe our summarize op broadcast. */
+    /**
+     * Resolves when we observe our summarize op broadcast.
+     */
     readonly summaryOpBroadcasted: Promise<SummarizeResultPart<IBroadcastSummaryResult>>;
-    /** Resolves when we receive a summaryAck or summaryNack. */
+    /**
+     * Resolves when we receive a summaryAck or summaryNack.
+     */
     readonly receivedSummaryAckOrNack: Promise<SummarizeResultPart<IAckSummaryResult, INackSummaryResult>>;
 }
 /**
@@ -310,7 +385,9 @@ export type EnqueueSummarizeResult = (ISummarizeResults & {
      */
     readonly alreadyEnqueued?: undefined;
 }) | (ISummarizeResults & {
-    /** Indicates that another summarize attempt was already enqueued. */
+    /**
+     * Indicates that another summarize attempt was already enqueued.
+     */
     readonly alreadyEnqueued: true;
     /**
      * Indicates that the other enqueued summarize attempt was abandoned,
@@ -318,7 +395,9 @@ export type EnqueueSummarizeResult = (ISummarizeResults & {
      */
     readonly overridden: true;
 }) | {
-    /** Indicates that another summarize attempt was already enqueued. */
+    /**
+     * Indicates that another summarize attempt was already enqueued.
+     */
     readonly alreadyEnqueued: true;
     /**
      * Indicates that the other enqueued summarize attempt remains enqueued,
@@ -326,67 +405,18 @@ export type EnqueueSummarizeResult = (ISummarizeResults & {
      */
     readonly overridden?: undefined;
 };
-/**
- * @legacy
- * @alpha
- * @deprecated Use SummarizerStopReason from the "\@fluidframework/container-runtime-definitions" package
- */
-export type SummarizerStopReason = 
-/** Summarizer client failed to summarize in all attempts. */
-"failToSummarize"
-/** Parent client reported that it is no longer connected. */
- | "parentNotConnected"
-/**
- * Parent client reported that it is no longer elected the summarizer.
- * This is the normal flow; a disconnect will always trigger the parent
- * client to no longer be elected as responsible for summaries. Then it
- * tries to stop its spawned summarizer client.
- */
- | "notElectedParent"
-/**
- * We are not already running the summarizer and we are not the current elected client id.
- */
- | "notElectedClient"
-/** Summarizer client was disconnected */
- | "summarizerClientDisconnected"
-/** running summarizer threw an exception */
- | "summarizerException"
-/**
- * The previous summary state on the summarizer is not the most recently acked summary. this also happens when the
- * first submitSummary attempt fails for any reason and there's a 2nd summary attempt without an ack
- */
- | "latestSummaryStateStale";
-/**
- * @legacy
- * @alpha
- * @deprecated Use ISummarizeEventProps from the "\@fluidframework/container-runtime-definitions" package
- */
-export interface ISummarizeEventProps {
-    result: "success" | "failure" | "canceled";
-    currentAttempt: number;
-    maxAttempts: number;
-    error?: any;
-}
-/**
- * @legacy
- * @alpha
- * @deprecated Use ISummarizerEvents from the "\@fluidframework/container-runtime-definitions" package
- */
-export interface ISummarizerEvents extends IEvent {
-    (event: "summarize", listener: (props: ISummarizeEventProps) => void): any;
-}
 /**
  * @legacy
  * @alpha
  */
-export interface ISummarizer extends IEventProvider<NewISummarizerEvents> {
+export interface ISummarizer extends IEventProvider<ISummarizerEvents> {
     /**
      * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.
      */
     readonly ISummarizer?: ISummarizer;
-    stop(reason: NewSummarizerStopReason): void;
+    stop(reason: SummarizerStopReason): void;
     close(): void;
-    run(onBehalfOf: string): Promise<NewSummarizerStopReason>;
+    run(onBehalfOf: string): Promise<SummarizerStopReason>;
     /**
      * Attempts to generate a summary on demand. If already running, takes no action.
      * @param options - options controlling the summarize attempt
@@ -411,30 +441,54 @@ export interface ISummarizer extends IEventProvider<NewISummarizerEvents> {
      */
     enqueueSummarize(options: IEnqueueSummarizeOptions): EnqueueSummarizeResult;
 }
-/** Data about an attempt to summarize used for heuristics. */
+/**
+ * Data about an attempt to summarize used for heuristics.
+ */
 export interface ISummarizeAttempt {
-    /** Reference sequence number when summary was generated or attempted */
+    /**
+     * Reference sequence number when summary was generated or attempted
+     */
     readonly refSequenceNumber: number;
-    /** Time of summary attempt after it was sent or attempted */
+    /**
+     * Time of summary attempt after it was sent or attempted
+     */
     readonly summaryTime: number;
-    /** Sequence number of summary op */
+    /**
+     * Sequence number of summary op
+     */
     summarySequenceNumber?: number;
 }
-/** Data relevant for summary heuristics. */
+/**
+ * Data relevant for summary heuristics.
+ */
 export interface ISummarizeHeuristicData {
-    /** Latest received op sequence number */
+    /**
+     * Latest received op sequence number
+     */
     lastOpSequenceNumber: number;
-    /** Most recent summary attempt from this client */
+    /**
+     * Most recent summary attempt from this client
+     */
     readonly lastAttempt: ISummarizeAttempt;
-    /** Most recent summary that received an ack */
+    /**
+     * Most recent summary that received an ack
+     */
     readonly lastSuccessfulSummary: Readonly<ISummarizeAttempt>;
-    /** Number of runtime ops since last summary */
+    /**
+     * Number of runtime ops since last summary
+     */
     numRuntimeOps: number;
-    /** Number of non-runtime ops since last summary */
+    /**
+     * Number of non-runtime ops since last summary
+     */
     numNonRuntimeOps: number;
-    /** Cumulative size in bytes of all the ops since the last summary */
+    /**
+     * Cumulative size in bytes of all the ops since the last summary
+     */
     totalOpsSize: number;
-    /** Wether or not this instance contains adjusted metrics due to missing op data */
+    /**
+     * Wether or not this instance contains adjusted metrics due to missing op data
+     */
     hasMissingOpData: boolean;
     /**
      * Updates lastAttempt and lastSuccessfulAttempt based on the last summary.
@@ -448,33 +502,55 @@ export interface ISummarizeHeuristicData {
      * @param referenceSequenceNumber - reference sequence number of sent summary
      */
     recordAttempt(referenceSequenceNumber?: number): void;
-    /** Mark that the last sent summary attempt has received an ack */
+    /**
+     * Mark that the last sent summary attempt has received an ack
+     */
     markLastAttemptAsSuccessful(): void;
     opsSinceLastSummary: number;
 }
-/** Responsible for running heuristics determining when to summarize. */
+/**
+ * Responsible for running heuristics determining when to summarize.
+ */
 export interface ISummarizeHeuristicRunner {
-    /** Start specific heuristic trackers (ex: idle timer) */
+    /**
+     * Start specific heuristic trackers (ex: idle timer)
+     */
     start(): void;
-    /** Runs the heuristics to determine if it should try to summarize */
+    /**
+     * Runs the heuristics to determine if it should try to summarize
+     */
     run(): void;
-    /** Runs a different heuristic to check if it should summarize before closing */
+    /**
+     * Runs a different heuristic to check if it should summarize before closing
+     */
     shouldRunLastSummary(): boolean;
-    /** Disposes of resources */
+    /**
+     * Disposes of resources
+     */
     dispose(): void;
 }
 type ISummarizeTelemetryRequiredProperties = 
-/** Reason code for attempting to summarize */
+/**
+ * Reason code for attempting to summarize
+ */
 "summarizeReason";
 type ISummarizeTelemetryOptionalProperties = 
-/** Number of attempts within the last time window, used for calculating the throttle delay. */
+/**
+ * Number of attempts within the last time window, used for calculating the throttle delay.
+ */
 "summaryAttempts"
-/** Summarization may be attempted multiple times. This tells whether this is the final summarization attempt */
+/**
+ * Summarization may be attempted multiple times. This tells whether this is the final summarization attempt
+ */
  | "finalAttempt" | keyof ISummarizeOptions;
 export type ISummarizeTelemetryProperties = Pick<ITelemetryBaseProperties, ISummarizeTelemetryRequiredProperties> & Partial<Pick<ITelemetryBaseProperties, ISummarizeTelemetryOptionalProperties>>;
-/** Strategy used to heuristically determine when we should run a summary */
+/**
+ * Strategy used to heuristically determine when we should run a summary
+ */
 export interface ISummaryHeuristicStrategy {
-    /** Summarize reason for this summarize heuristic strategy (ex: "maxTime") */
+    /**
+     * Summarize reason for this summarize heuristic strategy (ex: "maxTime")
+     */
     summarizeReason: Readonly<SummarizeReason>;
     /**
      * Determines if this strategy's summarize criteria been met
@@ -484,55 +560,97 @@ export interface ISummaryHeuristicStrategy {
     shouldRunSummary(configuration: ISummaryConfigurationHeuristics, heuristicData: ISummarizeHeuristicData): boolean;
 }
 type SummaryGeneratorRequiredTelemetryProperties = 
-/** True to generate the full tree with no handle reuse optimizations */
+/**
+ * True to generate the full tree with no handle reuse optimizations
+ */
 "fullTree"
-/** Time since we last attempted to generate a summary */
+/**
+ * Time since we last attempted to generate a summary
+ */
  | "timeSinceLastAttempt"
-/** Time since we last successfully generated a summary */
+/**
+ * Time since we last successfully generated a summary
+ */
  | "timeSinceLastSummary";
 type SummaryGeneratorOptionalTelemetryProperties = 
-/** Reference sequence number as of the generate summary attempt. */
+/**
+ * Reference sequence number as of the generate summary attempt.
+ */
 "referenceSequenceNumber"
-/** minimum sequence number (at the reference sequence number) */
+/**
+ * minimum sequence number (at the reference sequence number)
+ */
  | "minimumSequenceNumber"
-/** Delta between the current reference sequence number and the reference sequence number of the last attempt */
+/**
+ * Delta between the current reference sequence number and the reference sequence number of the last attempt
+ */
  | "opsSinceLastAttempt"
-/** Delta between the current reference sequence number and the reference sequence number of the last summary */
+/**
+ * Delta between the current reference sequence number and the reference sequence number of the last summary
+ */
  | "opsSinceLastSummary"
 /**
  * Delta in sum of op sizes between the current reference sequence number and the reference
  * sequence number of the last summary
  */
  | "opsSizesSinceLastSummary"
-/** Delta between the number of non-runtime ops since the last summary */
+/**
+ * Delta between the number of non-runtime ops since the last summary
+ */
  | "nonRuntimeOpsSinceLastSummary"
-/** Delta between the number of runtime ops since the last summary */
+/**
+ * Delta between the number of runtime ops since the last summary
+ */
  | "runtimeOpsSinceLastSummary"
-/** Wether or not this instance contains adjusted metrics due to missing op data */
+/**
+ * Wether or not this instance contains adjusted metrics due to missing op data
+ */
  | "hasMissingOpData"
-/** Time it took to generate the summary tree and stats. */
+/**
+ * Time it took to generate the summary tree and stats.
+ */
  | "generateDuration"
-/** The handle returned by storage pointing to the uploaded summary tree. */
+/**
+ * The handle returned by storage pointing to the uploaded summary tree.
+ */
  | "handle"
-/** Time it took to upload the summary tree to storage. */
+/**
+ * Time it took to upload the summary tree to storage.
+ */
  | "uploadDuration"
-/** The client sequence number of the summarize op submitted for the summary. */
+/**
+ * The client sequence number of the summarize op submitted for the summary.
+ */
  | "clientSequenceNumber"
-/** Time it took for this summary to be acked after it was generated */
+/**
+ * Time it took for this summary to be acked after it was generated
+ */
  | "ackWaitDuration"
-/** Reference sequence number of the ack/nack message */
+/**
+ * Reference sequence number of the ack/nack message
+ */
  | "ackNackSequenceNumber"
-/** Actual sequence number of the summary op proposal. */
+/**
+ * Actual sequence number of the summary op proposal.
+ */
  | "summarySequenceNumber"
-/** Optional Retry-After time in seconds. If specified, the client should wait this many seconds before retrying. */
+/**
+ * Optional Retry-After time in seconds. If specified, the client should wait this many seconds before retrying.
+ */
  | "nackRetryAfter"
-/** The stage at which the submit summary method failed at. This can help determine what type of failure we have */
+/**
+ * The stage at which the submit summary method failed at. This can help determine what type of failure we have
+ */
  | "stage";
 export type SummaryGeneratorTelemetry = Pick<ITelemetryBaseProperties, SummaryGeneratorRequiredTelemetryProperties> & Partial<Pick<ITelemetryBaseProperties, SummaryGeneratorOptionalTelemetryProperties>>;
 export interface ISummarizeRunnerTelemetry extends ITelemetryLoggerPropertyBag {
-    /** Number of times the summarizer run. */
+    /**
+     * Number of times the summarizer run.
+     */
     summarizeCount: () => number;
-    /** Number of successful attempts to summarize. */
+    /**
+     * Number of successful attempts to summarize.
+     */
     summarizerSuccessfulAttempts: () => number;
 }
 export {};