@fluidframework/container-runtime 2.0.0-dev.3.1.0.125672 → 2.0.0-dev.4.2.0.153917

package/lib/summary/summarizerNode/summarizerNode.d.ts

@@ -0,0 +1,149 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ISummarizerNode, ISummarizerNodeConfig, ISummarizeResult, CreateChildSummarizerNodeParam, SummarizeInternalFn, ITelemetryContext } from "@fluidframework/runtime-definitions";
+import { ISequencedDocumentMessage, ISnapshotTree } from "@fluidframework/protocol-definitions";
+import { ITelemetryErrorEvent, ITelemetryLogger } from "@fluidframework/common-definitions";
+import { ReadAndParseBlob } from "@fluidframework/runtime-utils";
+import { EscapedPath, ICreateChildDetails, IFetchSnapshotResult, IInitialSummary, ISummarizerNodeRootContract, RefreshSummaryResult, SummaryNode } from "./summarizerNodeUtils";
+export interface IRootSummarizerNode extends ISummarizerNode, ISummarizerNodeRootContract {
+}
+/**
+ * Encapsulates the summarizing work and state of an individual tree node in the
+ * summary tree. It tracks changes and allows for optimizations when unchanged, or
+ * can allow for fallback summaries to be generated when an error is encountered.
+ * Usage is for the root node to call startSummary first to begin tracking a WIP
+ * (work in progress) summary. Then all nodes will call summarize to summaries their
+ * individual parts. Once completed and uploaded to storage, the root node will call
+ * completeSummary or clearSummary to clear the WIP summary tracking state if something
+ * went wrong. The SummarizerNodes will track all pending summaries that have been
+ * recorded by the completeSummary call. When one of them is acked, the root node should
+ * call refreshLatestSummary to inform the tree of SummarizerNodes of the new baseline
+ * latest successful summary.
+ */
+export declare class SummarizerNode implements IRootSummarizerNode {
+    private readonly summarizeInternalFn;
+    private _changeSequenceNumber;
+    /** Undefined means created without summary */
+    private _latestSummary?;
+    private readonly initialSummary?;
+    protected wipSummaryLogger?: ITelemetryLogger | undefined;
+    /** A unique id of this node to be logged when sending telemetry. */
+    protected telemetryNodeId?: string | undefined;
+    /**
+     * The reference sequence number of the most recent acked summary.
+     * Returns 0 if there is not yet an acked summary.
+     */
+    get referenceSequenceNumber(): number;
+    protected readonly children: Map<string, SummarizerNode>;
+    protected readonly pendingSummaries: Map<string, SummaryNode>;
+    protected wipReferenceSequenceNumber: number | undefined;
+    private wipLocalPaths;
+    private wipSkipRecursion;
+    protected readonly logger: ITelemetryLogger;
+    /**
+     * Do not call constructor directly.
+     * Use createRootSummarizerNode to create root node, or createChild to create child nodes.
+     */
+    constructor(baseLogger: ITelemetryLogger, summarizeInternalFn: SummarizeInternalFn, config: ISummarizerNodeConfig, _changeSequenceNumber: number, 
+    /** Undefined means created without summary */
+    _latestSummary?: SummaryNode | undefined, initialSummary?: IInitialSummary | undefined, wipSummaryLogger?: ITelemetryLogger | undefined, 
+    /** A unique id of this node to be logged when sending telemetry. */
+    telemetryNodeId?: string | undefined);
+    startSummary(referenceSequenceNumber: number, summaryLogger: ITelemetryLogger): void;
+    summarize(fullTree: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummarizeResult>;
+    /**
+     * Complete the WIP summary for the given proposalHandle
+     */
+    completeSummary(proposalHandle: string): void;
+    /**
+     * Recursive implementation for completeSummary, with additional internal-only parameters
+     */
+    protected completeSummaryCore(proposalHandle: string, parentPath: EscapedPath | undefined, parentSkipRecursion: boolean): void;
+    clearSummary(): void;
+    /**
+     * Refreshes the latest summary tracked by this node. If we have a pending summary for the given proposal handle,
+     * it becomes the latest summary. If the current summary is already ahead (e.g., loaded from a service summary),
+     * we skip the update. Otherwise, we fetch the latest snapshot and update latest summary based off of that.
+     *
+     * @returns A RefreshSummaryResult type which returns information based on the following three scenarios:
+     *
+     * 1. The latest summary was not updated.
+     *
+     * 2. The latest summary was updated and the summary corresponding to the params was being tracked.
+     *
+     * 3. The latest summary was updated but the summary corresponding to the params was not tracked. In this
+     * case, the latest summary is updated based on the downloaded snapshot which is also returned.
+     */
+    refreshLatestSummary(proposalHandle: string | undefined, summaryRefSeq: number, fetchLatestSnapshot: () => Promise<IFetchSnapshotResult>, readAndParseBlob: ReadAndParseBlob, correlatedSummaryLogger: ITelemetryLogger): Promise<RefreshSummaryResult>;
+    /**
+     * Called when we get an ack from the server for a summary we've just sent. Updates the reference state of this node
+     * from the state in the pending summary queue.
+     * @param proposalHandle - Handle for the current proposal.
+     * @param referenceSequenceNumber -  reference sequence number of sent summary.
+     */
+    protected refreshLatestSummaryFromPending(proposalHandle: string, referenceSequenceNumber: number): void;
+    protected refreshLatestSummaryFromSnapshot(referenceSequenceNumber: number, snapshotTree: ISnapshotTree, basePath: EscapedPath | undefined, localPath: EscapedPath, correlatedSummaryLogger: ITelemetryLogger, readAndParseBlob: ReadAndParseBlob): Promise<void>;
+    private refreshLatestSummaryCore;
+    updateBaseSummaryState(snapshot: ISnapshotTree): void;
+    recordChange(op: ISequencedDocumentMessage): void;
+    invalidate(sequenceNumber: number): void;
+    /**
+     * True if a change has been recorded with sequence number exceeding
+     * the latest successfully acked summary reference sequence number.
+     * False implies that the previous summary can be reused.
+     */
+    protected hasChanged(): boolean;
+    get latestSummary(): Readonly<SummaryNode> | undefined;
+    protected readonly canReuseHandle: boolean;
+    createChild(
+    /** Summarize function */
+    summarizeInternalFn: SummarizeInternalFn, 
+    /** Initial id or path part of this node */
+    id: string, 
+    /**
+     * Information needed to create the node.
+     * If it is from a base summary, it will assert that a summary has been seen.
+     * Attach information if it is created from an attach op.
+     */
+    createParam: CreateChildSummarizerNodeParam, config?: ISummarizerNodeConfig): ISummarizerNode;
+    getChild(id: string): ISummarizerNode | undefined;
+    /**
+     * Returns the details needed to create a child node.
+     * @param id - Initial id or path part of the child node.
+     * @param createParam - Information needed to create the node.
+     * @returns the details needed to create the child node.
+     */
+    protected getCreateDetailsForChild(id: string, createParam: CreateChildSummarizerNodeParam): ICreateChildDetails;
+    /**
+     * Updates the state of the child if required. For example, if a summary is currently being  tracked, the child's
+     * summary tracking state needs to be updated too.
+     * Also, in case a child node gets realized in between Summary Op and Summary Ack, let's initialize the child's
+     * pending summary as well.
+     * @param child - The child node whose state is to be updated.
+     * @param id - Initial id or path part of this node
+     *
+     */
+    protected maybeUpdateChildState(child: SummarizerNode, id: string): void;
+    protected addPendingSummary(key: string, summary: SummaryNode): void;
+    /**
+     * Tells whether summary tracking is in progress. True if "startSummary" API is called before summarize.
+     */
+    isSummaryInProgress(): boolean;
+    /**
+     * Creates and throws an error due to unexpected conditions.
+     */
+    protected throwUnexpectedError(eventProps: ITelemetryErrorEvent): never;
+}
+/**
+ * Creates a root summarizer node.
+ * @param logger - Logger to use within SummarizerNode
+ * @param summarizeInternalFn - Function to generate summary
+ * @param changeSequenceNumber - Sequence number of latest change to new node/subtree
+ * @param referenceSequenceNumber - Reference sequence number of last acked summary,
+ * or undefined if not loaded from summary
+ * @param config - Configure behavior of summarizer node
+ */
+export declare const createRootSummarizerNode: (logger: ITelemetryLogger, summarizeInternalFn: SummarizeInternalFn, changeSequenceNumber: number, referenceSequenceNumber: number | undefined, config?: ISummarizerNodeConfig) => IRootSummarizerNode;
+//# sourceMappingURL=summarizerNode.d.ts.map

package/lib/summary/summarizerNode/summarizerNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizerNode.d.ts","sourceRoot":"","sources":["../../../src/summary/summarizerNode/summarizerNode.ts"],"names":[],"mappings":"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"}