@fluidframework/container-loader 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.1

package/dist/container-loader-untrimmed.d.ts

@@ -0,0 +1,351 @@
+import { FluidObject } from '@fluidframework/core-interfaces';
+import { IAudienceOwner } from '@fluidframework/container-definitions';
+import { IClientDetails } from '@fluidframework/protocol-definitions';
+import { IConfigProviderBase } from '@fluidframework/core-interfaces';
+import { IContainer } from '@fluidframework/container-definitions';
+import { IDocumentAttributes } from '@fluidframework/protocol-definitions';
+import { IDocumentServiceFactory } from '@fluidframework/driver-definitions';
+import { IDocumentStorageService } from '@fluidframework/driver-definitions';
+import { IFluidCodeDetails } from '@fluidframework/container-definitions';
+import { IFluidModule } from '@fluidframework/container-definitions';
+import { IFluidRouter } from '@fluidframework/core-interfaces';
+import { IHostLoader } from '@fluidframework/container-definitions';
+import { ILoaderOptions as ILoaderOptions_2 } from '@fluidframework/container-definitions';
+import { ILocationRedirectionError } from '@fluidframework/driver-definitions';
+import { IProtocolHandler as IProtocolHandler_2 } from '@fluidframework/protocol-base';
+import { IProvideFluidCodeDetailsComparer } from '@fluidframework/container-definitions';
+import { IQuorumSnapshot } from '@fluidframework/protocol-base';
+import { IRequest } from '@fluidframework/core-interfaces';
+import { IRequestHeader } from '@fluidframework/core-interfaces';
+import { IResponse } from '@fluidframework/core-interfaces';
+import { ISignalMessage } from '@fluidframework/protocol-definitions';
+import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
+import { IUrlResolver } from '@fluidframework/driver-definitions';
+
+/**
+ * @internal
+ */
+export declare enum ConnectionState {
+    /**
+     * The container is not connected to the ordering service
+     * Note - When in this state the container may be about to reconnect,
+     * or may remain disconnected until explicitly told to connect.
+     */
+    Disconnected = 0,
+    /**
+     * The container is disconnected but actively trying to establish a new connection
+     * PLEASE NOTE that this numerical value falls out of the order you may expect for this state
+     */
+    EstablishingConnection = 3,
+    /**
+     * The container has an inbound connection only, and is catching up to the latest known state from the service.
+     */
+    CatchingUp = 1,
+    /**
+     * The container is fully connected and syncing
+     */
+    Connected = 2
+}
+
+/**
+ * @deprecated ICodeDetailsLoader interface is moved to {@link @fluidframework/container-definition#ICodeDetailsLoader}
+ * to have code loading modules in one package. #8193
+ * Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
+ * a package name and package version range.
+ * @alpha
+ */
+export declare interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
+    /**
+     * Load the code module (package) that is capable to interact with the document.
+     *
+     * @param source - Code proposal that articulates the current schema the document is written in.
+     * @returns Code module entry point along with the code details associated with it.
+     */
+    load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
+}
+
+/**
+ * IContainer interface that includes experimental features still under development.
+ * @internal
+ */
+export declare interface IContainerExperimental extends IContainer {
+    /**
+     * Get pending state from container. WARNING: misuse of this API can result in duplicate op
+     * submission and potential document corruption. The blob returned MUST be deleted if and when this
+     * container emits a "connected" event.
+     * @returns serialized blob that can be passed to Loader.resolve()
+     */
+    getPendingLocalState?(): Promise<string>;
+    /**
+     * Closes the container and returns serialized local state intended to be
+     * given to a newly loaded container.
+     */
+    closeAndGetPendingLocalState?(stopBlobAttachingSignal?: AbortSignal): Promise<string>;
+}
+
+/**
+ * Subset of IDocumentStorageService which only supports createBlob() and readBlob(). This is used to support
+ * blobs in detached containers.
+ * @alpha
+ */
+export declare type IDetachedBlobStorage = Pick<IDocumentStorageService, "createBlob" | "readBlob"> & {
+    size: number;
+    /**
+     * Return an array of all blob IDs present in storage
+     */
+    getBlobIds(): string[];
+};
+
+/**
+ * @deprecated IFluidModuleWithDetails interface is moved to
+ * {@link @fluidframework/container-definitions#IFluidModuleWithDetails}
+ * to have all the code loading modules in one package. #8193
+ * Encapsulates a module entry point with corresponding code details.
+ * @alpha
+ */
+export declare interface IFluidModuleWithDetails {
+    /** Fluid code module that implements the runtime factory needed to instantiate the container runtime. */
+    module: IFluidModule;
+    /**
+     * Code details associated with the module. Represents a document schema this module supports.
+     * If the code loader implements the {@link @fluidframework/core-interfaces#IFluidCodeDetailsComparer} interface,
+     * it'll be called to determine whether the module code details satisfy the new code proposal in the quorum.
+     */
+    details: IFluidCodeDetails;
+}
+
+/**
+ * @alpha
+ */
+export declare interface ILoaderOptions extends ILoaderOptions_2 {
+    summarizeProtocolTree?: boolean;
+}
+
+/**
+ * Services and properties necessary for creating a loader
+ * @alpha
+ */
+export declare interface ILoaderProps {
+    /**
+     * The url resolver used by the loader for resolving external urls
+     * into Fluid urls such that the container specified by the
+     * external url can be loaded.
+     */
+    readonly urlResolver: IUrlResolver;
+    /**
+     * The document service factory take the Fluid url provided
+     * by the resolved url and constructs all the necessary services
+     * for communication with the container's server.
+     */
+    readonly documentServiceFactory: IDocumentServiceFactory;
+    /**
+     * The code loader handles loading the necessary code
+     * for running a container once it is loaded.
+     */
+    readonly codeLoader: ICodeDetailsLoader;
+    /**
+     * A property bag of options used by various layers
+     * to control features
+     */
+    readonly options?: ILoaderOptions;
+    /**
+     * Scope is provided to all container and is a set of shared
+     * services for container's to integrate with their host environment.
+     */
+    readonly scope?: FluidObject;
+    /**
+     * The logger that all telemetry should be pushed to.
+     */
+    readonly logger?: ITelemetryBaseLogger;
+    /**
+     * Blobs storage for detached containers.
+     */
+    readonly detachedBlobStorage?: IDetachedBlobStorage;
+    /**
+     * The configuration provider which may be used to control features.
+     */
+    readonly configProvider?: IConfigProviderBase;
+    /**
+     * Optional property for allowing the container to use a custom
+     * protocol implementation for handling the quorum and/or the audience.
+     */
+    readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
+}
+
+/**
+ * Services and properties used by and exposed by the loader
+ * @alpha
+ */
+export declare interface ILoaderServices {
+    /**
+     * The url resolver used by the loader for resolving external urls
+     * into Fluid urls such that the container specified by the
+     * external url can be loaded.
+     */
+    readonly urlResolver: IUrlResolver;
+    /**
+     * The document service factory take the Fluid url provided
+     * by the resolved url and constructs all the necessary services
+     * for communication with the container's server.
+     */
+    readonly documentServiceFactory: IDocumentServiceFactory;
+    /**
+     * The code loader handles loading the necessary code
+     * for running a container once it is loaded.
+     */
+    readonly codeLoader: ICodeDetailsLoader;
+    /**
+     * A property bag of options used by various layers
+     * to control features
+     */
+    readonly options: ILoaderOptions;
+    /**
+     * Scope is provided to all container and is a set of shared
+     * services for container's to integrate with their host environment.
+     */
+    readonly scope: FluidObject;
+    /**
+     * The logger downstream consumers should construct their loggers from
+     */
+    readonly subLogger: ITelemetryLoggerExt;
+    /**
+     * Blobs storage for detached containers.
+     */
+    readonly detachedBlobStorage?: IDetachedBlobStorage;
+    /**
+     * Optional property for allowing the container to use a custom
+     * protocol implementation for handling the quorum and/or the audience.
+     */
+    readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
+}
+
+/**
+ * Interface to represent the parsed parts of IResolvedUrl.url to help
+ * in getting info about different parts of the url.
+ * May not be compatible or relevant for any Url Resolver
+ * @internal
+ */
+export declare interface IParsedUrl {
+    /**
+     * It is combination of tenantid/docId part of the url.
+     */
+    id: string;
+    /**
+     * It is the deep link path in the url.
+     */
+    path: string;
+    /**
+     * Query string part of the url.
+     */
+    query: string;
+    /**
+     * Null means do not use snapshots, undefined means load latest snapshot
+     * otherwise it's version ID passed to IDocumentStorageService.getVersions() to figure out what snapshot to use.
+     * If needed, can add undefined which is treated by Container.load() as load latest snapshot.
+     */
+    version: string | null | undefined;
+}
+
+/**
+ * @alpha
+ */
+export declare interface IProtocolHandler extends IProtocolHandler_2 {
+    readonly audience: IAudienceOwner;
+    processSignal(message: ISignalMessage): any;
+}
+
+/**
+ * Checks if the error is location redirection error.
+ * @param error - error whose type is to be determined.
+ * @returns `true` is the error is location redirection error, otherwise `false`.
+ * @internal
+ */
+export declare function isLocationRedirectionError(error: any): error is ILocationRedirectionError;
+
+/**
+ * Manages Fluid resource loading
+ * @alpha
+ */
+export declare class Loader implements IHostLoader {
+    readonly services: ILoaderServices;
+    private readonly mc;
+    constructor(loaderProps: ILoaderProps);
+    /**
+     * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+     */
+    get IFluidRouter(): IFluidRouter;
+    createDetachedContainer(codeDetails: IFluidCodeDetails, createDetachedProps?: {
+        canReconnect?: boolean;
+        clientDetailsOverride?: IClientDetails;
+    }): Promise<IContainer>;
+    rehydrateDetachedContainerFromSnapshot(snapshot: string, createDetachedProps?: {
+        canReconnect?: boolean;
+        clientDetailsOverride?: IClientDetails;
+    }): Promise<IContainer>;
+    resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer>;
+    /**
+     * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+     */
+    request(request: IRequest): Promise<IResponse>;
+    private resolveCore;
+    private loadContainer;
+}
+
+/**
+ * Function to be used for creating a protocol handler.
+ * @alpha
+ */
+export declare type ProtocolHandlerBuilder = (attributes: IDocumentAttributes, snapshot: IQuorumSnapshot, sendProposal: (key: string, value: any) => number) => IProtocolHandler;
+
+/**
+ * With an already-resolved container, we can request a component directly, without loading the container again
+ * @param container - a resolved container
+ * @returns component on the container
+ * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @internal
+ */
+export declare function requestResolvedObjectFromContainer(container: IContainer, headers?: IRequestHeader): Promise<IResponse>;
+
+/**
+ * Handles location redirection while fulfilling the loader request.
+ * @param api - Callback in which user can wrap the loader.resolve or loader.request call.
+ * @param request - request to be resolved.
+ * @param urlResolver - resolver used to resolve the url.
+ * @param logger - logger to send events.
+ * @returns Response from the API call.
+ * @internal
+ */
+export declare function resolveWithLocationRedirectionHandling<T>(api: (request: IRequest) => Promise<T>, request: IRequest, urlResolver: IUrlResolver, logger?: ITelemetryBaseLogger): Promise<T>;
+
+/**
+ * Utility api to parse the IResolvedUrl.url into specific parts like querystring, path to get
+ * deep link info etc.
+ * Warning - This function may not be compatible with any Url Resolver's resolved url. It works
+ * with urls of type: protocol://<string>/.../..?<querystring>
+ * @param url - This is the IResolvedUrl.url part of the resolved url.
+ * @returns The IParsedUrl representing the input URL, or undefined if the format was not supported
+ * @internal
+ */
+export declare function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined;
+
+/**
+ * Waits until container connects to delta storage and gets up-to-date.
+ *
+ * Useful when resolving URIs and hitting 404, due to container being loaded from (stale) snapshot and not being
+ * up to date. Host may chose to wait in such case and retry resolving URI.
+ *
+ * Warning: Will wait infinitely for connection to establish if there is no connection.
+ * May result in deadlock if Container.disconnect() is called and never followed by a call to Container.connect().
+ *
+ * @returns `true`: container is up to date, it processed all the ops that were know at the time of first connection.
+ *
+ * `false`: storage does not provide indication of how far the client is. Container processed all the ops known to it,
+ * but it maybe still behind.
+ *
+ * @throws an error beginning with `"Container closed"` if the container is closed before it catches up.
+ * @internal
+ */
+export declare function waitContainerToCatchUp(container: IContainer): Promise<boolean>;
+
+export { }

package/dist/container.cjs

@@ -47,6 +47,7 @@ const hasBlobsSummaryTree = ".hasAttachmentBlobs";
  * but it maybe still behind.
  *
  * @throws an error beginning with `"Container closed"` if the container is closed before it catches up.
+ * @internal
  */
 async function waitContainerToCatchUp(container) {
     // Make sure we stop waiting if container is closed.
@@ -417,11 +418,12 @@ class Container extends telemetry_utils_1.EventEmitterWithErrorHandling {
                 ...createParamOverrides,
             });
         };
+        this._containerId = (0, uuid_1.v4)();
+        this.client = Container.setupClient(this._containerId, this.options, this.clientDetailsOverride);
         // Create logger for data stores to use
         const type = this.client.details.type;
         const interactive = this.client.details.capabilities.interactive;
         const clientType = `${interactive ? "interactive" : "noninteractive"}${type !== undefined && type !== "" ? `/${type}` : ""}`;
-        this._containerId = (0, uuid_1.v4)();
         // Need to use the property getter for docId because for detached flow we don't have the docId initially.
         // We assign the id later so property getter is used.
         this.subLogger = (0, telemetry_utils_1.createChildLogger)({
@@ -646,7 +648,6 @@ class Container extends telemetry_utils_1.EventEmitterWithErrorHandling {
         // runtime matches pending ops to successful ones by clientId and client seq num, so we need to close the
         // container at the same time we get pending state, otherwise this container could reconnect and resubmit with
         // a new clientId and a future container using stale pending state without the new clientId would resubmit them
-        this.disconnectInternal({ text: "closeAndGetPendingLocalState" }); // TODO https://dev.azure.com/fluidframework/internal/_workitems/edit/5127
         const pendingState = await this.getPendingLocalStateCore({
             notifyImminentClosure: true,
             stopBlobAttachingSignal,
@@ -1254,9 +1255,10 @@ class Container extends telemetry_utils_1.EventEmitterWithErrorHandling {
         const pkg = getCodeProposal(quorum);
         return pkg;
     }
-    get client() {
-        const client = this.options?.client !== undefined
-            ? this.options.client
+    static setupClient(containerId, options, clientDetailsOverride) {
+        const loaderOptionsClient = structuredClone(options?.client);
+        const client = loaderOptionsClient !== undefined
+            ? loaderOptionsClient
             : {
                 details: {
                     capabilities: { interactive: true },
@@ -1266,20 +1268,20 @@ class Container extends telemetry_utils_1.EventEmitterWithErrorHandling {
                 scopes: [],
                 user: { id: "" },
             };
-        if (this.clientDetailsOverride !== undefined) {
+        if (clientDetailsOverride !== undefined) {
             client.details = {
                 ...client.details,
-                ...this.clientDetailsOverride,
+                ...clientDetailsOverride,
                 capabilities: {
                     ...client.details.capabilities,
-                    ...this.clientDetailsOverride.capabilities,
+                    ...clientDetailsOverride?.capabilities,
                 },
             };
         }
         client.details.environment = [
             client.details.environment,
             ` loaderVersion:${packageVersion_1.pkgVersion}`,
-            ` containerId:${this._containerId}`,
+            ` containerId:${containerId}`,
         ].join(";");
         return client;
     }