@fluidframework/container-definitions 2.0.0-dev.6.4.0.192049 → 2.0.0-dev.7.2.0.204906

package/src/loader.ts

@@ -6,6 +6,7 @@
 import {
 	IRequest,
 	IResponse,
+	// eslint-disable-next-line import/no-deprecated
 	IFluidRouter,
 	FluidObject,
 	IEvent,
@@ -29,6 +30,7 @@ import { IFluidCodeDetails, IFluidPackage, IProvideFluidCodeDetailsComparer } fr
 
 /**
  * Encapsulates a module entry point with corresponding code details.
+ * @public
  */
 export interface IFluidModuleWithDetails {
 	/**
@@ -48,6 +50,7 @@ export interface IFluidModuleWithDetails {
 /**
  * Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
  * a package name and package version range.
+ * @public
  */
 export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
 	/**
@@ -62,6 +65,7 @@ export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComp
 /**
  * The interface returned from a IFluidCodeResolver which represents IFluidCodeDetails
  * that have been resolved and are ready to load
+ * @public
  */
 export interface IResolvedFluidCodeDetails extends IFluidCodeDetails {
 	/**
@@ -80,6 +84,7 @@ export interface IResolvedFluidCodeDetails extends IFluidCodeDetails {
  * The Fluid code resolver is coupled to a specific cdn and knows how to resolve
  * the code detail for loading from that cdn. This include resolving to the most recent
  * version of package that supports the provided code details.
+ * @public
  */
 export interface IFluidCodeResolver {
 	/**
@@ -93,6 +98,7 @@ export interface IFluidCodeResolver {
 
 /**
  * Events emitted by the {@link IContainer} "upwards" to the Loader and Host.
+ * @public
  */
 export interface IContainerEvents extends IEvent {
 	/**
@@ -252,6 +258,7 @@ export interface IContainerEvents extends IEvent {
 /**
  * Namespace for the different connection states a container can be in.
  * PLEASE NOTE: The sequence of the numerical values does no correspond to the typical connection state progression.
+ * @public
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace ConnectionState {
@@ -281,6 +288,7 @@ export namespace ConnectionState {
 
 /**
  * Type defining the different states of connectivity a Container can be in.
+ * @public
  */
 export type ConnectionState =
 	| ConnectionState.Disconnected
@@ -290,7 +298,9 @@ export type ConnectionState =
 
 /**
  * The Host's view of a Container and its connection to storage
+ * @public
  */
+// eslint-disable-next-line import/no-deprecated
 export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRouter {
 	/**
 	 * The Delta Manager supporting the op stream for this Container
@@ -374,7 +384,10 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	 * TODO - in the case of failure options should give a retry policy.
 	 * Or some continuation function that allows attachment to a secondary document.
 	 */
-	attach(request: IRequest): Promise<void>;
+	attach(
+		request: IRequest,
+		attachProps?: { deltaConnection?: "none" | "delayed" },
+	): Promise<void>;
 
 	/**
 	 * Extract a snapshot of the container as long as it is in detached state. Calling this on an attached container
@@ -391,9 +404,13 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
 
 	/**
+	 * @deprecated Requesting 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)
+	 *
 	 * 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.
 	 *
@@ -405,21 +422,19 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	 * 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.
+	 * @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
+	 * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
 	 */
+	// eslint-disable-next-line import/no-deprecated
 	readonly IFluidRouter: IFluidRouter;
 
 	/**
@@ -489,19 +504,13 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
 	/**
 	 * Exposes the entryPoint for the container.
 	 * Use this as the primary way of getting access to the user-defined logic within the container.
-	 * If the method is undefined or the returned promise returns undefined (meaning that exposing the entryPoint
-	 * hasn't been implemented in a particular scenario) fall back to the current approach of requesting the default
-	 * object of the container through the request pattern.
-	 *
-	 * @remarks The plan is that eventually IContainer will no longer implement IFluidRouter (and thus won't have a
-	 * request() method), this method will no longer be optional, and it will become the only way to access
-	 * the entryPoint for the container.
 	 */
-	getEntryPoint?(): Promise<FluidObject | undefined>;
+	getEntryPoint(): Promise<FluidObject | undefined>;
 }
 
 /**
  * The Runtime's view of the Loader, used for loading Containers
+ * @public
  */
 export interface ILoader extends Partial<IProvideLoader> {
 	/**
@@ -516,33 +525,50 @@ export interface ILoader extends Partial<IProvideLoader> {
 	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.
+	 * @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.
+	 * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the Container's IFluidRouter/request.
 	 */
+	// eslint-disable-next-line import/no-deprecated
 	readonly IFluidRouter: IFluidRouter;
 }
 
 /**
  * The Host's view of the Loader, used for loading Containers
+ * @public
  */
 export interface IHostLoader extends ILoader {
 	/**
 	 * Creates a new container using the specified chaincode but in an unattached state. While unattached all
 	 * updates will only be local until the user explicitly attaches the container to a service provider.
 	 */
-	createDetachedContainer(codeDetails: IFluidCodeDetails): Promise<IContainer>;
+	createDetachedContainer(
+		codeDetails: IFluidCodeDetails,
+		createDetachedProps?: {
+			canReconnect?: boolean;
+			clientDetailsOverride?: IClientDetails;
+		},
+	): Promise<IContainer>;
 
 	/**
 	 * Creates a new container using the specified snapshot but in an unattached state. While unattached all
 	 * updates will only be local until the user explicitly attaches the container to a service provider.
 	 */
-	rehydrateDetachedContainerFromSnapshot(snapshot: string): Promise<IContainer>;
+	rehydrateDetachedContainerFromSnapshot(
+		snapshot: string,
+		createDetachedProps?: {
+			canReconnect?: boolean;
+			clientDetailsOverride?: IClientDetails;
+		},
+	): Promise<IContainer>;
 }
 
+/**
+ * @public
+ */
 export type ILoaderOptions = {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	[key in string | number]: any;
@@ -575,6 +601,7 @@ export type ILoaderOptions = {
 
 /**
  * Accepted header keys for requests coming to the Loader
+ * @public
  */
 export enum LoaderHeader {
 	/**
@@ -605,6 +632,9 @@ export enum LoaderHeader {
 	version = "version",
 }
 
+/**
+ * @public
+ */
 export interface IContainerLoadMode {
 	opsBeforeReturn?: /*
 	 * No trailing ops are applied before container is returned.
@@ -658,6 +688,7 @@ export interface IContainerLoadMode {
 
 /**
  * Set of Request Headers that the Loader understands and may inspect or modify
+ * @public
  */
 export interface ILoaderHeader {
 	/**
@@ -675,6 +706,9 @@ export interface ILoaderHeader {
 	[LoaderHeader.version]: string | undefined;
 }
 
+/**
+ * @public
+ */
 export interface IProvideLoader {
 	readonly ILoader: ILoader;
 }
@@ -683,6 +717,7 @@ export interface IProvideLoader {
  * @deprecated 0.48, This API will be removed in 0.50
  * No replacement since it is not expected anyone will depend on this outside container-loader
  * See {@link https://github.com/microsoft/FluidFramework/issues/9711} for context.
+ * @public
  */
 export interface IPendingLocalState {
 	url: string;
@@ -694,6 +729,7 @@ export interface IPendingLocalState {
  * in separate property: {@link ISnapshotTreeWithBlobContents.blobsContents}.
  *
  * @remarks This is used as the `ContainerContext`'s base snapshot when attaching.
+ * @public
  */
 export interface ISnapshotTreeWithBlobContents extends ISnapshotTree {
 	blobsContents: { [path: string]: ArrayBufferLike };

package/src/runtime.ts

@@ -32,6 +32,7 @@ import { IFluidCodeDetails } from "./fluidPackage";
 /**
  * The attachment state of some Fluid data (e.g. a container or data store), denoting whether it is uploaded to the
  * service.  The transition from detached to attached state is a one-way transition.
+ * @public
  */
 export enum AttachState {
 	/**
@@ -55,11 +56,12 @@ export enum AttachState {
 /**
  * The IRuntime represents an instantiation of a code package within a Container.
  * Primarily held by the ContainerContext to be able to interact with the running instance of the Container.
+ * @public
  */
 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
+	 * @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>;
 
@@ -105,7 +107,7 @@ export interface IRuntime extends IDisposable {
 	/**
 	 * Notify runtime that container is moving to "Attaching" state
 	 * @param snapshot - snapshot created at attach time
-	 * @deprecated - not necessary after op replay moved to Container
+	 * @deprecated not necessary after op replay moved to Container
 	 */
 	notifyAttaching(snapshot: ISnapshotTreeWithBlobContents): void;
 
@@ -120,15 +122,13 @@ export interface IRuntime extends IDisposable {
 	 * Use this as the primary way of getting access to the user-defined logic within the container runtime.
 	 *
 	 * @see {@link IContainer.getEntryPoint}
-	 *
-	 * @remarks The plan is that eventually IRuntime will no longer have a request() method, this method will no
-	 * longer be optional, and it will become the only way to access the entryPoint for the runtime.
 	 */
-	getEntryPoint?(): Promise<FluidObject | undefined>;
+	getEntryPoint(): Promise<FluidObject | undefined>;
 }
 
 /**
  * Payload type for IContainerContext.submitBatchFn()
+ * @public
  */
 export interface IBatchMessage {
 	contents?: string;
@@ -141,6 +141,7 @@ export interface IBatchMessage {
  * IContainerContext is fundamentally just the set of things that an IRuntimeFactory (and IRuntime) will consume from the
  * loader layer.  It gets passed into the IRuntimeFactory.instantiateRuntime call.  Only include members on this interface
  * if you intend them to be consumed/called from the runtime layer.
+ * @public
  */
 export interface IContainerContext {
 	readonly options: ILoaderOptions;
@@ -214,13 +215,20 @@ export interface IContainerContext {
 	 * @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.
+	 *
+	 * @privateremarks Tracking in AB#5714
 	 */
 	readonly id: string;
 }
 
+/**
+ * @public
+ */
 export const IRuntimeFactory: keyof IProvideRuntimeFactory = "IRuntimeFactory";
 
+/**
+ * @public
+ */
 export interface IProvideRuntimeFactory {
 	readonly IRuntimeFactory: IRuntimeFactory;
 }
@@ -230,6 +238,7 @@ export interface IProvideRuntimeFactory {
  *
  * Provides the entry point for the ContainerContext to load the proper IRuntime
  * to start up the running instance of the Container.
+ * @public
  */
 export interface IRuntimeFactory extends IProvideRuntimeFactory {
 	/**