@fluidframework/container-definitions 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/error.ts

@@ -3,10 +3,25 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryProperties } from "@fluidframework/core-interfaces";
+import { FluidErrorTypes, IErrorBase } from "@fluidframework/core-interfaces";
 
 /**
- * Different error types the Container may report out to the Host
+ * Different error types the ClientSession may report out to the Host.
+ */
+export const ContainerErrorTypes = {
+	...FluidErrorTypes,
+	/**
+	 * Error indicating an client session has expired. Currently this only happens when GC is allowed on a document and
+	 * aids in safely deleting unused objects.
+	 */
+	clientSessionExpiredError: "clientSessionExpiredError",
+} as const;
+export type ContainerErrorTypes = typeof ContainerErrorTypes[keyof typeof ContainerErrorTypes];
+
+/**
+ * Different error types the Container may report out to the Host.
+ *
+ * @deprecated ContainerErrorType is being deprecated as a public export. Please use {@link ContainerErrorTypes#clientSessionExpiredError} instead.
  */
 export enum ContainerErrorType {
 	/**
@@ -41,35 +56,6 @@ export enum ContainerErrorType {
 	clientSessionExpiredError = "clientSessionExpiredError",
 }
 
-/**
- * Base interface for all errors and warnings at container level
- */
-export interface IErrorBase extends Partial<Error> {
-	/** errorType is a union of error types from
-	 * - container
-	 * - runtime
-	 * - drivers
-	 */
-	readonly errorType: string;
-
-	/**
-	 * See Error.message
-	 * Privacy Note - This is a freeform string that we may not control in all cases (e.g. a dependency throws an error)
-	 * If there are known cases where this contains privacy-sensitive data it will be tagged and included in the result
-	 * of getTelemetryProperties. When logging, consider fetching it that way rather than straight from this field.
-	 */
-	readonly message: string;
-	/** See Error.name */
-	readonly name?: string;
-	/** See Error.stack */
-	readonly stack?: string;
-	/**
-	 * Returns all properties of this error object that are either safe to log
-	 * or explicitly tagged as containing privacy-sensitive data.
-	 */
-	getTelemetryProperties?(): ITelemetryProperties;
-}
-
 /**
  * Represents warnings raised on container.
  */
@@ -89,7 +75,7 @@ export interface ContainerWarning extends IErrorBase {
  *
  * The following are commonly thrown error types, but `errorType` could be any string.
  *
- * - {@link @fluidframework/container-definitions#ContainerErrorType}
+ * - {@link @fluidframework/core-interfaces#ContainerErrorType}
  *
  * - {@link @fluidframework/driver-definitions#DriverErrorType}
  *
@@ -99,26 +85,3 @@ export interface ContainerWarning extends IErrorBase {
  *
  */
 export type ICriticalContainerError = IErrorBase;
-
-/**
- * Generic wrapper for an unrecognized/uncategorized error object
- */
-export interface IGenericError extends IErrorBase {
-	readonly errorType: ContainerErrorType.genericError;
-	error?: any;
-}
-
-/**
- * Error indicating an API is being used improperly resulting in an invalid operation.
- */
-export interface IUsageError extends IErrorBase {
-	readonly errorType: ContainerErrorType.usageError;
-}
-
-/**
- * Warning emitted when requests to storage are being throttled
- */
-export interface IThrottlingWarning extends IErrorBase {
-	readonly errorType: ContainerErrorType.throttlingError;
-	readonly retryAfterSeconds: number;
-}

package/src/fluidPackage.ts

@@ -63,8 +63,10 @@ export interface IFluidPackage {
  * Check if the package.json defines a Fluid package
  * @param pkg - the package json data to check if it is a Fluid package.
  */
-export const isFluidPackage = (pkg: any): pkg is Readonly<IFluidPackage> =>
-	typeof pkg === "object" && typeof pkg?.name === "string" && typeof pkg?.fluid === "object";
+export const isFluidPackage = (pkg: unknown): pkg is Readonly<IFluidPackage> =>
+	typeof pkg === "object" &&
+	typeof (pkg as Partial<IFluidPackage>)?.name === "string" &&
+	typeof (pkg as Partial<IFluidPackage>)?.fluid === "object";
 
 /**
  * Package manager configuration. Provides a key value mapping of config values

package/src/index.ts

@@ -17,27 +17,21 @@ export {
 } from "./browserPackage";
 export {
 	IConnectionDetails,
-	IConnectionDetailsInternal,
-	IDeltaHandlerStrategy,
 	IDeltaManager,
 	IDeltaManagerEvents,
-	IDeltaSender,
 	IDeltaQueue,
 	IDeltaQueueEvents,
+	IDeltaSender,
 	ReadOnlyInfo,
 } from "./deltas";
 export {
+	ContainerErrorTypes,
 	ContainerErrorType,
 	ContainerWarning,
 	ICriticalContainerError,
-	IErrorBase,
-	IGenericError,
-	IUsageError,
-	IThrottlingWarning,
 } from "./error";
 export {
 	ConnectionState,
-	ICodeAllowList,
 	ICodeDetailsLoader,
 	IContainer,
 	IContainerEvents,
@@ -73,3 +67,22 @@ export {
 	IRuntime,
 	IRuntimeFactory,
 } from "./runtime";
+
+export {
+	/**
+	 * @deprecated IErrorBase is being deprecated as a public export is moving to "core-interfaces".
+	 */
+	IErrorBase,
+	/**
+	 * @deprecated IGenericError is being deprecated as a public export is moving to "core-interfaces".
+	 */
+	IGenericError,
+	/**
+	 * @deprecated IThrottlingWarning is being deprecated as a public export is moving to "core-interfaces".
+	 */
+	IThrottlingWarning,
+	/**
+	 * @deprecated IUsageError is being deprecated as a public export is moving to "core-interfaces".
+	 */
+	IUsageError,
+} from "@fluidframework/core-interfaces";

package/src/loader.ts

@@ -3,7 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { IRequest, IResponse, IFluidRouter, FluidObject } from "@fluidframework/core-interfaces";
+import {
+	IRequest,
+	IResponse,
+	IFluidRouter,
+	FluidObject,
+	IEvent,
+	IEventProvider,
+} from "@fluidframework/core-interfaces";
 import {
 	IClientDetails,
 	IDocumentMessage,
@@ -13,7 +20,6 @@ import {
 	ISnapshotTree,
 } from "@fluidframework/protocol-definitions";
 import { IResolvedUrl } from "@fluidframework/driver-definitions";
-import { IEvent, IEventProvider } from "@fluidframework/common-definitions";
 import { IAudience } from "./audience";
 import { IDeltaManager, ReadOnlyInfo } from "./deltas";
 import { ICriticalContainerError, ContainerWarning } from "./error";
@@ -48,7 +54,7 @@ export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComp
 	 * Load the code module (package) that can 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.
+	 * @returns Code module entry point along with the code details associated with it.
 	 */
 	load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
 }
@@ -79,24 +85,12 @@ export interface IFluidCodeResolver {
 	/**
 	 * Resolves a Fluid code details into a form that can be loaded.
 	 * @param details - The Fluid code details to resolve.
-	 * @returns - A IResolvedFluidCodeDetails where the resolvedPackage's Fluid file entries are absolute urls, and
+	 * @returns A IResolvedFluidCodeDetails where the resolvedPackage's Fluid file entries are absolute urls, and
 	 * an optional resolvedPackageCacheId if the loaded package should be cached.
 	 */
 	resolveCodeDetails(details: IFluidCodeDetails): Promise<IResolvedFluidCodeDetails>;
 }
 
-/**
- * Code AllowListing Interface
- *
- * @deprecated 2.0.0-internal.3.2.0 Fluid does not prescribe a particular code validation approach. Will be removed in an upcoming release.
- */
-export interface ICodeAllowList {
-	/**
-	 * @deprecated 2.0.0-internal.3.2.0 Fluid does not prescribe a particular code validation approach. Will be removed in an upcoming release.
-	 */
-	testSource(source: IResolvedFluidCodeDetails): Promise<boolean>;
-}
-
 /**
  * Events emitted by the {@link IContainer} "upwards" to the Loader and Host.
  */
@@ -141,11 +135,6 @@ export interface IContainerEvents extends IEvent {
 		listener: (codeDetails: IFluidCodeDetails, proposal: ISequencedProposal) => void,
 	);
 
-	/**
-	 * @deprecated No replacement API recommended.
-	 */
-	(event: "contextChanged", listener: (codeDetails: IFluidCodeDetails) => void);
-
 	/**
 	 * Emitted when the {@link IContainer} becomes disconnected from the Fluid service.
 	 *
@@ -339,10 +328,15 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	getLoadedCodeDetails(): IFluidCodeDetails | undefined;
 
 	/**
-	 * Returns true if the container has been closed, otherwise false.
+	 * Returns true if the container has been closed and/or disposed, otherwise false.
 	 */
 	readonly closed: boolean;
 
+	/**
+	 * Returns true if the container has been disposed, otherwise false.
+	 */
+	readonly disposed?: boolean;
+
 	/**
 	 * Whether or not there are any local changes that have not been saved.
 	 */
@@ -365,16 +359,6 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	 */
 	close(error?: ICriticalContainerError): void;
 
-	/**
-	 * @deprecated - This is moved to the IContainerExperimental interface. To access you should cast IContainerExperimental before attempting to use
-	 *
-	 * Closes the container and returns serialized local state intended to be
-	 * given to a newly loaded container.
-	 * @experimental
-	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/loader/container-loader/closeAndGetPendingLocalState.md}
-	 */
-	closeAndGetPendingLocalState(): string;
-
 	/**
 	 * Propose new code details that define the code to be loaded for this container's runtime.
 	 *
@@ -406,12 +390,38 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	 */
 	getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
 
+	/**
+	 * IMPORTANT: This overload is provided for back-compat where IContainer.request(\{ url: "/" \}) is already implemented and used.
+	 * The functionality it can provide (if the Container implementation is built for it) is redundant with @see {@link IContainer.getEntryPoint}.
+	 * Once that API is mandatory on IContainer, this overload will be deprecated.
+	 *
+	 * Refer to Removing-IFluidRouter.md for details on migrating from the request pattern to using entryPoint.
+	 *
+	 * @param request - Only requesting \{ url: "/" \} is supported, requesting arbitrary URLs is deprecated.
+	 */
+	request(request: { url: "/"; headers?: undefined }): Promise<IResponse>;
+
 	/**
 	 * Issue a request against the container for a resource.
 	 * @param request - The request to be issued against the container
+	 *
+	 * @deprecated - Requesting an arbitrary URL with headers will not be supported in a future major release.
+	 * Instead, access the objects in a Fluid Container using entryPoint, and then navigate from there using
+	 * app-specific logic (e.g. retrieving handles from the entryPoint's DDSes, or a container's entryPoint object
+	 * could implement a request paradigm itself)
+	 *
+	 * NOTE: IContainer.request(\{url: "/"\}) is not yet deprecated. If and only if the Container implementation supports it,
+	 * that overload may be used as a proxy for getting the entryPoint until {@link IContainer.getEntryPoint} is mandatory.
+	 *
+	 * Refer to Removing-IFluidRouter.md for details on migrating from the request pattern to using entryPoint.
 	 */
 	request(request: IRequest): Promise<IResponse>;
 
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+	 */
+	readonly IFluidRouter: IFluidRouter;
+
 	/**
 	 * Provides the current state of the container's connection to the ordering service.
 	 *
@@ -493,7 +503,7 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 /**
  * The Runtime's view of the Loader, used for loading Containers
  */
-export interface ILoader extends IFluidRouter, Partial<IProvideLoader> {
+export interface ILoader extends Partial<IProvideLoader> {
 	/**
 	 * Resolves the resource specified by the URL + headers contained in the request object
 	 * to the underlying container that will resolve the request.
@@ -504,6 +514,16 @@ export interface ILoader extends IFluidRouter, Partial<IProvideLoader> {
 	 * a request against the server found from the resolve step.
 	 */
 	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>;
+
+	/**
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
+	 */
+	readonly IFluidRouter: IFluidRouter;
 }
 
 /**
@@ -524,15 +544,17 @@ export interface IHostLoader extends ILoader {
 }
 
 export type ILoaderOptions = {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	[key in string | number]: any;
 } & {
 	/**
+	 * @deprecated This option has been deprecated and will be removed in a future release
 	 * Set caching behavior for the loader. If true, we will load a container from cache if one
 	 * with the same id/version exists or create a new container and cache it if it does not. If
 	 * false, always load a new container and don't cache it. If the container has already been
 	 * closed, it will not be cached. A cache option in the LoaderHeader for an individual
 	 * request will override the Loader's value.
-	 * Defaults to true.
+	 * Defaults to false.
 	 */
 	cache?: boolean;
 
@@ -556,7 +578,7 @@ export type ILoaderOptions = {
  */
 export enum LoaderHeader {
 	/**
-	 * @deprecated In next release, all caching functionality will be removed, and this is not useful anymore
+	 * @deprecated This header has been deprecated and will be removed in a future release
 	 * Override the Loader's default caching behavior for this container.
 	 */
 	cache = "fluid-cache",
@@ -568,6 +590,10 @@ export enum LoaderHeader {
 	 */
 	loadMode = "loadMode",
 	reconnect = "fluid-reconnect",
+	/**
+	 * Loads the container to at least the specified sequence number.
+	 * If not defined, behavior will fall back to `IContainerLoadMode.opsBeforeReturn`.
+	 */
 	sequenceNumber = "fluid-sequence-number",
 
 	/**
@@ -585,6 +611,11 @@ export interface IContainerLoadMode {
 	 * Default value.
 	 */
 	| undefined
+		/*
+		 * Only fetch and apply trailing ops up until (and including) the specified sequence number.
+		 * Requires `ILoaderHeader["fluid-sequence-number"]` to also be defined.
+		 */
+		| "sequenceNumber"
 		/*
 		 * Only cached trailing ops are applied before returning container.
 		 * Caching is optional and could be implemented by the driver.
@@ -618,6 +649,11 @@ export interface IContainerLoadMode {
 		 * Default value.
 		 */
 		| undefined;
+
+	/**
+	 * If set to true, will indefinitely pause all incoming and outgoing after the container is loaded.
+	 */
+	pauseAfterLoad?: boolean;
 }
 
 /**
@@ -625,11 +661,15 @@ export interface IContainerLoadMode {
  */
 export interface ILoaderHeader {
 	/**
-	 * @deprecated In next release, all caching functionality will be removed, and this is not useful anymore
+	 * @deprecated This header has been deprecated and will be removed in a future release
 	 */
 	[LoaderHeader.cache]: boolean;
 	[LoaderHeader.clientDetails]: IClientDetails;
 	[LoaderHeader.loadMode]: IContainerLoadMode;
+	/**
+	 * Loads the container to at least the specified sequence number.
+	 * If not defined, behavior will fall back to `IContainerLoadMode.opsBeforeReturn`.
+	 */
 	[LoaderHeader.sequenceNumber]: number;
 	[LoaderHeader.reconnect]: boolean;
 	[LoaderHeader.version]: string | undefined;

package/src/runtime.ts

@@ -13,7 +13,6 @@ import {
 
 import { IDocumentStorageService } from "@fluidframework/driver-definitions";
 import {
-	IClientConfiguration,
 	IClientDetails,
 	ISequencedDocumentMessage,
 	ISnapshotTree,
@@ -60,6 +59,7 @@ export enum AttachState {
 export interface IRuntime extends IDisposable {
 	/**
 	 * Executes a request against the runtime
+	 * @deprecated - Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
 	 */
 	request(request: IRequest): Promise<IResponse>;
 
@@ -76,6 +76,8 @@ export interface IRuntime extends IDisposable {
 	/**
 	 * Processes the given signal
 	 */
+	// TODO: use `unknown` instead (API breaking)
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	processSignal(message: any, local: boolean);
 
 	/**
@@ -98,7 +100,7 @@ export interface IRuntime extends IDisposable {
 	 * @experimental
 	 * {@link https://github.com/microsoft/FluidFramework/packages/tree/main/loader/container-loader/closeAndGetPendingLocalState.md}
 	 */
-	getPendingLocalState(): unknown;
+	getPendingLocalState(props?: { notifyImminentClosure?: boolean }): unknown;
 
 	/**
 	 * Notify runtime that container is moving to "Attaching" state
@@ -141,22 +143,27 @@ export interface IBatchMessage {
  * if you intend them to be consumed/called from the runtime layer.
  */
 export interface IContainerContext {
-	/** @deprecated Please pass in existing directly in instantiateRuntime */
-	readonly existing: boolean | undefined;
 	readonly options: ILoaderOptions;
 	readonly clientId: string | undefined;
 	readonly clientDetails: IClientDetails;
 	readonly storage: IDocumentStorageService;
 	readonly connected: boolean;
 	readonly baseSnapshot: ISnapshotTree | undefined;
-	/** @deprecated Please use submitBatchFn & submitSummaryFn */
+	/**
+	 * @deprecated Please use submitBatchFn & submitSummaryFn
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	readonly submitFn: (type: MessageType, contents: any, batch: boolean, appData?: any) => number;
-	/** @returns clientSequenceNumber of last message in a batch */
+	/**
+	 * @returns clientSequenceNumber of last message in a batch
+	 */
 	readonly submitBatchFn: (batch: IBatchMessage[], referenceSequenceNumber?: number) => number;
 	readonly submitSummaryFn: (
 		summaryOp: ISummaryContent,
 		referenceSequenceNumber?: number,
 	) => number;
+	// TODO: use `unknown` instead (API breaking)
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	readonly submitSignalFn: (contents: any) => void;
 	readonly disposeFn?: (error?: ICriticalContainerError) => void;
 	readonly closeFn: (error?: ICriticalContainerError) => void;
@@ -174,11 +181,6 @@ export interface IContainerContext {
 	readonly loader: ILoader;
 	// The logger implementation, which would support tagged events, should be provided by the loader.
 	readonly taggedLogger: ITelemetryBaseLogger;
-	/**
-	 * @deprecated - 2.0.0-internal.5.2.0 - This property is redundant, and is unused by the runtime. The same information can be found via
-	 * deltaManager.serviceConfiguration on this object if it is necessary.
-	 */
-	readonly serviceConfiguration: IClientConfiguration | undefined;
 	pendingLocalState?: unknown;
 
 	/**
@@ -209,22 +211,12 @@ export interface IContainerContext {
 	 * WARNING: this id is meant for telemetry usages ONLY, not recommended for other consumption
 	 * This id is not supposed to be exposed anywhere else. It is dependant on usage or drivers
 	 * and scenarios which can change in the future.
-	 * @deprecated - 2.0.0-internal.5.2.0 - The docId is already logged by the IContainerContext.taggedLogger for
-	 * telemetry purposes, so this is generally unnecessary for telemetry.  If the id is needed for other purposes
-	 * it should be passed to the consumer explicitly.  This member will be removed in an upcoming release.
+	 * @deprecated 2.0.0-internal.5.2.0 - The docId is already logged by the {@link IContainerContext.taggedLogger} for
+	 * telemetry purposes, so this is generally unnecessary for telemetry.
+	 * If the id is needed for other purposes it should be passed to the consumer explicitly.
+	 * This member will be removed in the 2.0.0-internal.7.0.0 release.
 	 */
 	readonly id: string;
-
-	/**
-	 * @deprecated - 2.0.0-internal.5.2.0 - The disposed state on the IContainerContext is not meaningful to the runtime.
-	 * This member will be removed in an upcoming release.
-	 */
-	readonly disposed: boolean;
-	/**
-	 * @deprecated - 2.0.0-internal.5.2.0 - The runtime is not permitted to dispose the IContainerContext, this results
-	 * in an inconsistent system state.  This member will be removed in an upcoming release.
-	 */
-	dispose(error?: Error): void;
 }
 
 export const IRuntimeFactory: keyof IProvideRuntimeFactory = "IRuntimeFactory";