@fluidframework/container-definitions 0.42.0 → 0.44.0

package/src/fluidPackage.ts

@@ -0,0 +1,132 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+ /**
+  * Specifies an environment on Fluid property of a IFluidPackage
+  */
+export interface IFluidPackageEnvironment {
+
+    /**
+     * The name of the target. For a browser environment, this could be umd for scripts
+     * or css for styles.
+     */
+    [target: string]: undefined | {
+        /**
+         * List of files for the target. These can be relative or absolute.
+         * The code loader should resolve relative paths, and validate all
+         * full urls.
+         */
+        files: string[];
+
+        /**
+         * General access for extended fields as specific usages will
+         * likely have additional infornamation like a definition
+         * of Library, the entrypoint for umd packages
+         */
+        [key: string]: unknown;
+    }
+}
+
+/**
+ * Fluid-specific properties expected on a package to be loaded by the code loader.
+ * While compatible with the npm package format it is not necessary that that package is an
+ * npm package:
+ * {@link https://stackoverflow.com/questions/10065564/add-custom-metadata-or-config-to-package-json-is-it-valid}
+ */
+export interface IFluidPackage {
+    /**
+     * The name of the package that this code represnets
+     */
+    name: string;
+    /**
+     * This object represents the Fluid specific properties of the package
+     */
+    fluid: {
+        /**
+         * The name of the of the environment. This should be something like browser, or node
+         * and contain the necessary targets for loading this code in that environment.
+         */
+        [environment: string]:  undefined | IFluidPackageEnvironment;
+    };
+    /**
+     * General access for extended fields as specific usages will
+     * likely have additional infornamation like a definition of
+     * compatible versions, or deployment information like rings or rollouts.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * 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";
+
+/**
+ * Package manager configuration. Provides a key value mapping of config values
+ */
+export interface IFluidCodeDetailsConfig {
+    readonly [key: string]: string;
+}
+
+/**
+ * Data structure used to describe the code to load on the Fluid document
+ */
+export interface IFluidCodeDetails {
+    /**
+     * The code package to be used on the Fluid document. This is either the package name which will be loaded
+     * from a package manager. Or the expanded Fluid package.
+     */
+    readonly package: string | Readonly<IFluidPackage>;
+
+    /**
+     * Configuration details. This includes links to the package manager and base CDNs.
+     */
+    readonly config?: IFluidCodeDetailsConfig;
+}
+
+export const isFluidCodeDetails = (details: unknown): details is Readonly<IFluidCodeDetails> =>{
+    const maybeCodeDetails = details as Partial<IFluidCodeDetails> | undefined;
+    return typeof maybeCodeDetails === "object"
+        && (typeof maybeCodeDetails?.package === "string" || isFluidPackage(maybeCodeDetails?.package))
+        && (maybeCodeDetails?.config === undefined || typeof maybeCodeDetails?.config === "object");
+};
+
+export const IFluidCodeDetailsComparer: keyof IProvideFluidCodeDetailsComparer = "IFluidCodeDetailsComparer";
+
+export interface IProvideFluidCodeDetailsComparer {
+    readonly IFluidCodeDetailsComparer: IFluidCodeDetailsComparer ;
+}
+
+/**
+ * Provides capability to compare Fluid code details.
+ */
+export interface IFluidCodeDetailsComparer extends IProvideFluidCodeDetailsComparer {
+
+    /**
+     * Determines if the `candidate` code details satisfy the constraints specified in `constraint` code details.
+     *
+     * Similar semantics to:
+     * {@link https://github.com/npm/node-semver#usage}
+     */
+    satisfies(candidate: IFluidCodeDetails, constraint: IFluidCodeDetails): Promise<boolean>;
+
+/* eslint-disable max-len */
+    /**
+     * Return a number representing the ascending sort order of the `a` and `b` code details;
+     *      `< 0` if `a < b`.
+     *      `= 0` if `a === b`.
+     *      `> 0` if `a > b`.
+     *      `undefined` if `a` is not comparable to `b`.
+     *
+     * Similar semantics to:
+     * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description | Array.sort}
+     */
+    compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined>;
+/* eslint-enable max-len */
+}

package/src/index.ts

@@ -10,5 +10,6 @@ export * from "./deltas";
 export * from "./error";
 export * from "./loader";
 export * from "./fluidModule";
+export * from "./fluidPackage";
 export * from "./proxyLoader";
 export * from "./runtime";

package/src/loader.ts

@@ -20,7 +20,8 @@ import {
 } from "@fluidframework/protocol-definitions";
 import { IResolvedUrl } from "@fluidframework/driver-definitions";
 import { IEvent, IEventProvider } from "@fluidframework/common-definitions";
-import { IDeltaManager } from "./deltas";
+import { IAudience } from "./audience";
+import { IDeltaManager, ReadOnlyInfo } from "./deltas";
 import { ICriticalContainerError, ContainerWarning } from "./error";
 import { IFluidModule } from "./fluidModule";
 import { AttachState } from "./runtime";
@@ -37,6 +38,35 @@ export interface ICodeLoader extends Partial<IProvideFluidCodeDetailsComparer> {
     load(source: IFluidCodeDetails): Promise<IFluidModule>;
 }
 
+/**
+ * Encapsulates a module entry point with corresponding code details.
+ */
+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;
+}
+
+/**
+ * Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
+ * a package name and package version range.
+ */
+export 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>;
+}
+
 /**
 * The interface returned from a IFluidCodeResolver which represents IFluidCodeDetails
  * that have been resolved and are ready to load
@@ -93,6 +123,31 @@ export interface IContainerEvents extends IEvent {
     (event: "dirty" | "saved", listener: (dirty: boolean) => void);
 }
 
+/**
+ * Namespace for the different connection states a container can be in
+ */
+export namespace ConnectionState {
+    /**
+     * The document is no longer connected to the delta server
+     */
+    export type Disconnected = 0;
+
+    /**
+     * The document has an inbound connection but is still pending for outbound deltas
+     */
+    export type Connecting = 1;
+
+    /**
+     * The document is fully connected
+     */
+     export type Connected = 2;
+}
+
+/**
+ * Type defining the different states of connectivity a container can be in
+ */
+export type ConnectionState = ConnectionState.Disconnected | ConnectionState.Connecting | ConnectionState.Connected;
+
 /**
  * The Host's view of the Container and its connection to storage
  */
@@ -119,14 +174,6 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
      */
     readonly attachState: AttachState;
 
-    /**
-     * The current code details for the container's runtime
-     * @deprecated use getSpecifiedCodeDetails for the code details currently specified for this container, or
-     * getLoadedCodeDetails for the code details that the container's context was loaded with.
-     * To be removed after getSpecifiedCodeDetails and getLoadedCodeDetails become ubiquitous.
-     */
-    readonly codeDetails: IFluidCodeDetails | undefined;
-
     /**
      * Get the code details that are currently specified for the container.
      * @returns The current code details if any are specified, undefined if none are specified.
@@ -197,6 +244,63 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
      * @param request - The request to be issued against the container
      */
     request(request: IRequest): Promise<IResponse>;
+
+    /**
+     * Provides the current connected state of the container
+     */
+    readonly connectionState: ConnectionState;
+
+    /**
+     * Boolean indicating whether the container is currently connected or not
+     */
+    readonly connected: boolean;
+
+    /**
+     * Dictates whether or not the current container will automatically attempt to reconnect to the delta stream
+     * after receiving a disconnect event
+     * @param reconnect - Boolean indicating if reconnect should automatically occur
+     * @alpha
+     */
+    setAutoReconnect?(reconnect: boolean): void;
+
+    /**
+     * Have the container attempt to resume processing ops
+     * @alpha
+     */
+    resume?(): void;
+
+    /**
+     * The audience information for all clients currently associated with the document in the current session
+     */
+    readonly audience: IAudience;
+
+    /**
+     * The server provided ID of the client.
+     * Set once this.connected is true, otherwise undefined
+     * @alpha
+     */
+    readonly clientId?: string | undefined;
+
+    /**
+     * Tells if container is in read-only mode.
+     * Data stores should listen for "readonly" notifications and disallow user making changes to data stores.
+     * Readonly state can be because of no storage write permission,
+     * or due to host forcing readonly mode for container.
+     *
+     * We do not differentiate here between no write access to storage vs. host disallowing changes to container -
+     * in all cases container runtime and data stores should respect readonly state and not allow local changes.
+     *
+     * It is undefined if we have not yet established websocket connection
+     * and do not know if user has write access to a file.
+     */
+    readonly readOnlyInfo: ReadOnlyInfo;
+
+    /**
+     * Allows the host to have the container force to be in read-only mode
+     * @param readonly - Boolean that toggles if read-only policies will be enforced
+     * @alpha
+     */
+    forceReadonly?(readonly: boolean);
 }
 
 /**

package/src/runtime.ts

@@ -5,11 +5,12 @@
 
 import { ITelemetryBaseLogger, IDisposable } from "@fluidframework/common-definitions";
 import {
-    IFluidObject,
+    FluidObject,
+    IFluidCodeDetails,
     IFluidConfiguration,
+    IFluidObject,
     IRequest,
     IResponse,
-    FluidObject,
 } from "@fluidframework/core-interfaces";
 import { IDocumentStorageService } from "@fluidframework/driver-definitions";
 import {
@@ -120,6 +121,9 @@ export interface IRuntime extends IDisposable {
  * and the Container has created a new ContainerContext.
  */
 export interface IContainerContext extends IDisposable {
+    /**
+    * @deprecated This will be removed in a later release. Deprecated in 0.44 of container-definitions
+    */
     readonly id: string;
     readonly existing: boolean | undefined;
     readonly options: ILoaderOptions;
@@ -134,6 +138,14 @@ export interface IContainerContext extends IDisposable {
     readonly closeFn: (error?: ICriticalContainerError) => void;
     readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
     readonly quorum: IQuorum;
+    /**
+     * @deprecated This method is provided as a migration tool for customers currently reading the code details
+     * from within the Container by directly accessing the Quorum proposals.  The code details should not be accessed
+     * from within the Container as this requires coupling between the container contents and the code loader.
+     * Direct access to Quorum proposals will be removed in an upcoming release, and in a further future release this
+     * migration tool will be removed.
+     */
+    getSpecifiedCodeDetails?(): IFluidCodeDetails | undefined;
     readonly audience: IAudience | undefined;
     readonly loader: ILoader;
     /** @deprecated - Use `taggedLogger` if present. Otherwise, be sure to handle tagged data