/*! * Copyright (c) Microsoft Corporation and contributors. All rights reserved. * Licensed under the MIT License. */ import { type IContainer, type IFluidCodeDetails, type IFluidModule, type IHostLoader, type ILoader, type ILoaderOptions, type IProvideFluidCodeDetailsComparer, LoaderHeader, } from "@fluidframework/container-definitions/internal"; import type { FluidObject, IConfigProviderBase, IRequest, ITelemetryBaseLogger, } from "@fluidframework/core-interfaces"; import type { IClientDetails } from "@fluidframework/driver-definitions"; import type { IDocumentServiceFactory, IResolvedUrl, IUrlResolver, } from "@fluidframework/driver-definitions/internal"; import { type MonitoringContext, PerformanceEvent, createChildMonitoringContext, mixinMonitoringContext, sessionStorageConfigProvider, toITelemetryLoggerExt, } from "@fluidframework/telemetry-utils/internal"; // eslint-disable-next-line import-x/no-internal-modules -- Needed to avoid specialized /internal ITelemetryLoggerExt import type { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils/legacy"; import { v4 as uuid } from "uuid"; import { Container } from "./container.js"; import { mixinDebugLogger } from "./debugLogger.js"; import { pkgVersion } from "./packageVersion.js"; import type { ProtocolHandlerBuilder } from "./protocol.js"; import type { IPendingContainerState } from "./serializedStateManager.js"; import { getAttachedContainerStateFromSerializedContainer, tryParseCompatibleResolvedUrl, } from "./utils.js"; function ensureResolvedUrlDefined( resolved: IResolvedUrl | undefined, ): asserts resolved is IResolvedUrl { if (resolved === undefined) { throw new Error(`Object is not a IResolveUrl.`); } } /** * @internal */ export class RelativeLoader implements ILoader { constructor( private readonly container: Container, private readonly loader: ILoader | undefined, ) {} public async resolve(request: IRequest): Promise { if (request.url.startsWith("/")) { ensureResolvedUrlDefined(this.container.resolvedUrl); const container = await this.container.clone( { resolvedUrl: { ...this.container.resolvedUrl }, // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment version: request.headers?.[LoaderHeader.version] ?? undefined, // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment loadMode: request.headers?.[LoaderHeader.loadMode], }, { // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment canReconnect: request.headers?.[LoaderHeader.reconnect], // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails], }, ); return container; } if (this.loader === undefined) { throw new Error("Cannot resolve external containers"); } return this.loader.resolve(request); } } /** * @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. * @legacy @beta */ export 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; } /** * @deprecated ICodeDetailsLoader interface is moved to {@link @fluidframework/container-definitions#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. * @legacy @beta */ export interface ICodeDetailsLoader extends Partial { /** * 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; } /** * Services and properties necessary for creating a loader * @legacy @beta */ export 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; /** * 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 * @legacy @beta */ export 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; /** * Optional property for allowing the container to use a custom * protocol implementation for handling the quorum and/or the audience. */ readonly protocolHandlerBuilder?: ProtocolHandlerBuilder; } /** * Manages Fluid resource loading * @legacy @beta * * @remarks The Loader class is deprecated and will be removed in a future release. Use the free-form functions instead (See issue #24450 for more details). */ export class Loader implements IHostLoader { public readonly services: ILoaderServices; private readonly mc: MonitoringContext; constructor(loaderProps: ILoaderProps) { const { urlResolver, documentServiceFactory, codeLoader, options, scope, logger, configProvider, protocolHandlerBuilder, } = loaderProps; const telemetryProps = { loaderId: uuid(), loaderVersion: pkgVersion, }; const subMc = mixinMonitoringContext( mixinDebugLogger("fluid:telemetry", logger, { all: telemetryProps, }), sessionStorageConfigProvider.value, configProvider, ); this.services = { urlResolver, documentServiceFactory, codeLoader, options: options ?? {}, scope: options?.provideScopeLoader === false ? { ...scope } : { ...scope, ILoader: this }, protocolHandlerBuilder, subLogger: toITelemetryLoggerExt(subMc.logger), }; this.mc = createChildMonitoringContext({ logger: this.services.subLogger, namespace: "Loader", }); } public async createDetachedContainer( codeDetails: IFluidCodeDetails, createDetachedProps?: { canReconnect?: boolean; clientDetailsOverride?: IClientDetails; }, ): Promise { return Container.createDetached( { ...createDetachedProps, ...this.services, }, codeDetails, ); } public async rehydrateDetachedContainerFromSnapshot( snapshot: string, createDetachedProps?: { canReconnect?: boolean; clientDetailsOverride?: IClientDetails; }, ): Promise { return Container.rehydrateDetachedFromSnapshot( { ...createDetachedProps, ...this.services, }, snapshot, ); } public async resolve(request: IRequest, pendingLocalState?: string): Promise { const eventName = pendingLocalState === undefined ? "Resolve" : "ResolveWithPendingState"; return PerformanceEvent.timedExecAsync(this.mc.logger, { eventName }, async () => { return this.resolveCore( request, getAttachedContainerStateFromSerializedContainer(pendingLocalState), ); }); } private async resolveCore( request: IRequest, pendingLocalState?: IPendingContainerState, ): Promise { const resolvedAsFluid = await this.services.urlResolver.resolve(request); ensureResolvedUrlDefined(resolvedAsFluid); // Parse URL into data stores const parsed = tryParseCompatibleResolvedUrl(resolvedAsFluid.url); if (parsed === undefined) { throw new Error(`Invalid URL ${resolvedAsFluid.url}`); } if (pendingLocalState !== undefined) { const parsedPendingUrl = tryParseCompatibleResolvedUrl(pendingLocalState.url); if ( parsedPendingUrl?.id !== parsed.id || parsedPendingUrl?.path.replace(/\/$/, "") !== parsed.path.replace(/\/$/, "") ) { const message = `URL ${resolvedAsFluid.url} does not match pending state URL ${pendingLocalState.url}`; throw new Error(message); } } request.headers ??= {}; // If set in both query string and headers, use query string. Also write the value from the query string into the header either way. // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment request.headers[LoaderHeader.version] = parsed.version ?? request.headers[LoaderHeader.version]; return this.loadContainer(request, resolvedAsFluid, pendingLocalState); } private async loadContainer( request: IRequest, resolvedUrl: IResolvedUrl, pendingLocalState?: IPendingContainerState, ): Promise { return Container.load( { resolvedUrl, // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment version: request.headers?.[LoaderHeader.version] ?? undefined, // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment loadMode: request.headers?.[LoaderHeader.loadMode], pendingLocalState, }, { // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment canReconnect: request.headers?.[LoaderHeader.reconnect], // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment clientDetailsOverride: request.headers?.[LoaderHeader.clientDetails], ...this.services, }, ); } }