Replace ICodeLoader with ICodeDetailsLoader (microsoft#9697)

The usage of ICodeLoader is replaced with ICodeDetailsLoader in the entire repo. The old interface is not yet removed.

BREAKING.md

@@ -17,12 +17,17 @@ There are a few steps you can take to write a good change note and avoid needing
 # 0.59
 
 ## 0.59 Upcoming changes
+- [Remove ICodeLoader interface](#Remove-ICodeLoader-interface)
+
+### Remove ICodeLoader interface
+ICodeLoader interface was deprecated a while ago and will be removed in the next release. Please refer to [replace ICodeLoader with ICodeDetailsLoader interface](#Replace-ICodeLoader-with-ICodeDetailsLoader-interface) for more details.
 
 ## 0.59 Breaking changes
 - [Removing Commit from TreeEntry and commits from SnapShotTree](#Removing-Commit-from-TreeEntry-and-commits-from-SnapShotTree)
 - [raiseContainerWarning removed from IContainerContext](#raiseContainerWarning-removed-from-IContainerContext)
 - [Remove `@fluidframework/core-interface#fluidPackage.ts`](#Remove-fluidframeworkcore-interfacefluidPackagets)
 - [getAbsoluteUrl() argument type changed](#getAbsoluteUrl-argument-type-changed)
+- [Replace ICodeLoader with ICodeDetailsLoader interface](#Replace-ICodeLoader-with-ICodeDetailsLoader-interface)
 
 ### Removing Commit from TreeEntry and commits from SnapShotTree
 Cleaning up properties that are not being used in the codebase: `TreeEntry.Commit` and `ISnapshotTree.commits`.
@@ -67,6 +72,27 @@ The `packageInfoSource` argument in `getAbsoluteUrl()` on `@fluidframework/odsp-
 + ): Promise<string>;
 ```
 
+### Replace ICodeLoader with ICodeDetailsLoader interface
+The interface `ICodeLoader` was deprecated a while ago in previous releases. The alternative for `ICodeLoader` interface is the `ICodeDetailsLoader` interface which can be imported from `@fluidframework/container-definitions`. `ICodeLoader` interface will be removed in the next release.
+
+In particular, note the `ILoaderService` and `ILoaderProps` interfaces used with the `Loader` class now only support `ICodeDetailsLoader`. If you were using an `ICodeLoader` with these previously, you'll need to update to an `ICodeDetailsLoader`.
+
+```ts
+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>;
+}
+```
+All codeloaders are now expected to return the object including both the runtime factory and code details of the package that was actually loaded. These code details may be used later then to check whether the currently loaded package `.satisfies()` a constraint.
+
+You can start by returning default code details that were passed into the code loader which used to be our implementation on your behalf if code details were not passed in. Later on, this gives an opportunity to implement more sophisticated code loading where the code loader now can inform about the actual loaded module via the returned details.
+
 # 0.58
 
 ## 0.58 Upcoming changes

api-report/container-loader.api.md

@@ -10,7 +10,6 @@ import { FluidObject } from '@fluidframework/core-interfaces';
 import { IAudience } from '@fluidframework/container-definitions';
 import { IClientConfiguration } from '@fluidframework/protocol-definitions';
 import { IClientDetails } from '@fluidframework/protocol-definitions';
-import { ICodeLoader } from '@fluidframework/container-definitions';
 import { IConfigProviderBase } from '@fluidframework/telemetry-utils';
 import { IContainer } from '@fluidframework/container-definitions';
 import { IContainerEvents } from '@fluidframework/container-definitions';
@@ -155,7 +154,7 @@ export interface ILoaderOptions extends ILoaderOptions_2 {
 
 // @public
 export interface ILoaderProps {
-    readonly codeLoader: ICodeDetailsLoader | ICodeLoader;
+    readonly codeLoader: ICodeDetailsLoader;
     readonly configProvider?: IConfigProviderBase;
     readonly detachedBlobStorage?: IDetachedBlobStorage;
     readonly documentServiceFactory: IDocumentServiceFactory;
@@ -168,7 +167,7 @@ export interface ILoaderProps {
 
 // @public
 export interface ILoaderServices {
-    readonly codeLoader: ICodeDetailsLoader | ICodeLoader;
+    readonly codeLoader: ICodeDetailsLoader;
     readonly detachedBlobStorage?: IDetachedBlobStorage;
     readonly documentServiceFactory: IDocumentServiceFactory;
     readonly options: ILoaderOptions;

api-report/test-utils.api.md

@@ -7,7 +7,7 @@
 import { ContainerRuntime } from '@fluidframework/container-runtime';
 import { FluidDataStoreRuntime } from '@fluidframework/datastore';
 import { IChannelFactory } from '@fluidframework/datastore-definitions';
-import { ICodeLoader } from '@fluidframework/container-definitions';
+import { ICodeDetailsLoader } from '@fluidframework/container-definitions';
 import { IContainer } from '@fluidframework/container-definitions';
 import { IContainerContext } from '@fluidframework/container-definitions';
 import { IContainerRuntime } from '@fluidframework/container-runtime-definitions';
@@ -21,6 +21,7 @@ import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
 import { IFluidHandle } from '@fluidframework/core-interfaces';
 import { IFluidLoadable } from '@fluidframework/core-interfaces';
 import { IFluidModule } from '@fluidframework/container-definitions';
+import { IFluidModuleWithDetails } from '@fluidframework/container-definitions';
 import { IHostLoader } from '@fluidframework/container-definitions';
 import { ILoaderOptions } from '@fluidframework/container-definitions';
 import { ILoaderProps } from '@fluidframework/container-loader';
@@ -194,9 +195,9 @@ export class LoaderContainerTracker implements IOpProcessingController {
     }
 
 // @public
-export class LocalCodeLoader implements ICodeLoader {
+export class LocalCodeLoader implements ICodeDetailsLoader {
     constructor(packageEntries: Iterable<[IFluidCodeDetails, fluidEntryPoint]>, runtimeOptions?: IContainerRuntimeOptions);
-    load(source: IFluidCodeDetails): Promise<IFluidModule>;
+    load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
 }
 
 // @public

api-report/web-code-loader.api.md

@@ -5,10 +5,10 @@
 ```ts
 
 import { ICodeAllowList } from '@fluidframework/container-definitions';
-import { ICodeLoader } from '@fluidframework/container-definitions';
+import { ICodeDetailsLoader } from '@fluidframework/container-definitions';
 import { IFluidCodeDetails } from '@fluidframework/container-definitions';
 import { IFluidCodeResolver } from '@fluidframework/container-definitions';
-import { IFluidModule } from '@fluidframework/container-definitions';
+import { IFluidModuleWithDetails } from '@fluidframework/container-definitions';
 import { IFluidPackage } from '@fluidframework/container-definitions';
 import { IFluidPackageEnvironment } from '@fluidframework/container-definitions';
 import { IResolvedFluidCodeDetails } from '@fluidframework/container-definitions';
@@ -47,14 +47,14 @@ export class SemVerCdnCodeResolver implements IFluidCodeResolver {
 }
 
 // @public (undocumented)
-export class WebCodeLoader implements ICodeLoader {
+export class WebCodeLoader implements ICodeDetailsLoader {
     constructor(codeResolver: IFluidCodeResolver, allowList?: ICodeAllowList | undefined);
     // (undocumented)
-    load(source: IFluidCodeDetails): Promise<IFluidModule>;
+    load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
     // (undocumented)
     preCache(source: IFluidCodeDetails): Promise<void>;
     // (undocumented)
-    seedModule(source: IFluidCodeDetails, maybeFluidModule?: Promise<IFluidModule> | IFluidModule): Promise<void>;
+    seedModule(source: IFluidCodeDetails, maybeFluidModule?: Promise<IFluidModuleWithDetails> | IFluidModuleWithDetails): Promise<void>;
 }
 
 

examples/hosts/iframe-host/src/inframehost.ts

@@ -6,12 +6,13 @@
 import * as Comlink from "comlink";
 import {
     AttachState,
-    ICodeLoader,
     IContainerContext,
     IRuntime,
     IProxyLoaderFactory,
     ILoaderOptions,
     IContainer,
+    ICodeDetailsLoader,
+    IFluidCodeDetails,
 } from "@fluidframework/container-definitions";
 import { Loader } from "@fluidframework/container-loader";
 import { IRequest, IResponse, FluidObject } from "@fluidframework/core-interfaces";
@@ -104,9 +105,14 @@ class ProxyChaincode extends RuntimeFactoryHelper {
     }
 }
 
-class ProxyCodeLoader implements ICodeLoader {
-    async load() {
-        return Promise.resolve({ fluidExport: new ProxyChaincode() });
+class ProxyCodeLoader implements ICodeDetailsLoader {
+    async load(source: IFluidCodeDetails) {
+        return {
+            module: {
+                fluidExport: new ProxyChaincode(),
+            },
+            details: source,
+        };
     }
 }
 

examples/hosts/iframe-host/src/inner.ts

@@ -5,7 +5,7 @@
 
 import * as Comlink from "comlink";
 import { fluidExport as TodoContainer } from "@fluid-example/todo";
-import { IContainer } from "@fluidframework/container-definitions";
+import { IContainer, IFluidModuleWithDetails } from "@fluidframework/container-definitions";
 import { Loader } from "@fluidframework/container-loader";
 import { IFluidResolvedUrl } from "@fluidframework/driver-definitions";
 import { FluidObject, IRequest } from "@fluidframework/core-interfaces";
@@ -51,8 +51,14 @@ async function loadContainer(
     const documentServiceFactory = await InnerDocumentServiceFactory.create(innerPort);
     const urlResolver = await InnerUrlResolver.create(innerPort);
 
-    const module = { fluidExport: TodoContainer };
-    const codeLoader = { load: async () => module };
+    const load = async (): Promise<IFluidModuleWithDetails> => {
+        return {
+            module: { fluidExport: TodoContainer },
+            details: { package: "no-dynamic-package", config: {} },
+        };
+    };
+
+    const codeLoader = { load };
 
     const loader = new Loader({
         urlResolver,

experimental/framework/get-container/src/getContainer.ts

@@ -5,6 +5,7 @@
 
 import {
     IContainer,
+    IFluidModuleWithDetails,
     IRuntimeFactory,
 } from "@fluidframework/container-definitions";
 import { Loader } from "@fluidframework/container-loader";
@@ -24,9 +25,14 @@ export interface IGetContainerParams {
 export async function createContainer(
     params: IGetContainerParams,
 ): Promise<IContainer> {
-    const module = { fluidExport: params.containerRuntimeFactory };
-    const codeLoader = { load: async () => module };
+    const load = async (): Promise<IFluidModuleWithDetails> => {
+        return {
+            module: { fluidExport: params.containerRuntimeFactory },
+            details: { package: "no-dynamic-package", config: {} },
+        };
+    };
 
+    const codeLoader = { load };
     const loader = new Loader({
         urlResolver: params.urlResolver,
         documentServiceFactory: params.documentServiceFactory,
@@ -45,9 +51,14 @@ export async function createContainer(
 export async function getContainer(
     params: IGetContainerParams,
 ): Promise<IContainer> {
-    const module = { fluidExport: params.containerRuntimeFactory };
-    const codeLoader = { load: async () => module };
+    const load = async (): Promise<IFluidModuleWithDetails> => {
+        return {
+            module: { fluidExport: params.containerRuntimeFactory },
+            details: { package: "no-dynamic-package", config: {} },
+        };
+    };
 
+    const codeLoader = { load };
     const loader = new Loader({
         urlResolver: params.urlResolver,
         documentServiceFactory: params.documentServiceFactory,

experimental/framework/get-container/src/getSessionStorageContainer.ts

@@ -5,6 +5,7 @@
 
 import {
     IContainer,
+    IFluidModuleWithDetails,
     IRuntimeFactory,
 } from "@fluidframework/container-definitions";
 import { Loader } from "@fluidframework/container-loader";
@@ -37,8 +38,14 @@ export async function getSessionStorageContainer(
 
     // To bypass proposal-based loading, we need a codeLoader that will return our already-in-memory container factory.
     // The expected format of that response is an IFluidModule with a fluidExport.
-    const module = { fluidExport: containerRuntimeFactory };
-    const codeLoader = { load: async () => module };
+    const load = async (): Promise<IFluidModuleWithDetails> => {
+        return {
+            module: { fluidExport: containerRuntimeFactory },
+            details: { package: "no-dynamic-package", config: {} },
+        };
+    };
+
+    const codeLoader = { load };
 
     const loader = new Loader({
         urlResolver,

packages/framework/azure-client/src/AzureClient.ts

@@ -7,7 +7,11 @@ import {
     IDocumentServiceFactory,
     IUrlResolver,
 } from "@fluidframework/driver-definitions";
-import { AttachState, IContainer } from "@fluidframework/container-definitions";
+import {
+    AttachState,
+    IContainer,
+    IFluidModuleWithDetails,
+} from "@fluidframework/container-definitions";
 import { RouterliciousDocumentServiceFactory } from "@fluidframework/routerlicious-driver";
 import { requestFluidObject } from "@fluidframework/runtime-utils";
 import { ensureFluidResolvedUrl } from "@fluidframework/driver-utils";
@@ -138,8 +142,14 @@ export class AzureClient {
         const runtimeFactory = new DOProviderContainerRuntimeFactory(
             containerSchema,
         );
-        const module = { fluidExport: runtimeFactory };
-        const codeLoader = { load: async () => module };
+        const load = async (): Promise<IFluidModuleWithDetails> => {
+            return {
+                module: { fluidExport: runtimeFactory },
+                details: { package: "no-dynamic-package", config: {} },
+            };
+        };
+
+        const codeLoader = { load };
         return new Loader({
             urlResolver: this.urlResolver,
             documentServiceFactory: this.documentServiceFactory,

packages/framework/tinylicious-client/src/TinyliciousClient.ts

@@ -7,7 +7,11 @@ import {
     IDocumentServiceFactory,
     IUrlResolver,
 } from "@fluidframework/driver-definitions";
-import { AttachState, IContainer } from "@fluidframework/container-definitions";
+import {
+    AttachState,
+    IContainer,
+    IFluidModuleWithDetails,
+} from "@fluidframework/container-definitions";
 import { RouterliciousDocumentServiceFactory } from "@fluidframework/routerlicious-driver";
 import {
     createTinyliciousCreateNewRequest,
@@ -119,8 +123,14 @@ export class TinyliciousClient {
         const containerRuntimeFactory = new DOProviderContainerRuntimeFactory(
             containerSchema,
         );
-        const module = { fluidExport: containerRuntimeFactory };
-        const codeLoader = { load: async () => module };
+        const load = async (): Promise<IFluidModuleWithDetails> => {
+            return {
+                module: { fluidExport: containerRuntimeFactory },
+                details: { package: "no-dynamic-package", config: {} },
+            };
+        };
+
+        const codeLoader = { load };
         const loader = new Loader({
             urlResolver: this.urlResolver,
             documentServiceFactory: this.documentServiceFactory,

packages/loader/container-loader/src/containerContext.ts

@@ -15,11 +15,12 @@ import {
     AttachState,
     ILoaderOptions,
     IRuntimeFactory,
-    ICodeLoader,
     IProvideRuntimeFactory,
     IFluidCodeDetails,
     IFluidCodeDetailsComparer,
     IProvideFluidCodeDetailsComparer,
+    ICodeDetailsLoader,
+    IFluidModuleWithDetails,
 } from "@fluidframework/container-definitions";
 import {
     IFluidObject,
@@ -44,15 +45,14 @@ import {
 } from "@fluidframework/protocol-definitions";
 import { PerformanceEvent } from "@fluidframework/telemetry-utils";
 import { Container } from "./container";
-import { ICodeDetailsLoader, IFluidModuleWithDetails } from "./loader";
 
 const PackageNotFactoryError = "Code package does not implement IRuntimeFactory";
 
 export class ContainerContext implements IContainerContext {
     public static async createOrLoad(
         container: Container,
         scope: FluidObject,
-        codeLoader: ICodeDetailsLoader | ICodeLoader,
+        codeLoader: ICodeDetailsLoader,
         codeDetails: IFluidCodeDetails,
         baseSnapshot: ISnapshotTree | undefined,
         deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>,
@@ -157,7 +157,7 @@ export class ContainerContext implements IContainerContext {
     constructor(
         private readonly container: Container,
         public readonly scope: IFluidObject & FluidObject,
-        private readonly codeLoader: ICodeDetailsLoader | ICodeLoader,
+        private readonly codeLoader: ICodeDetailsLoader,
         private readonly _codeDetails: IFluidCodeDetails,
         private readonly _baseSnapshot: ISnapshotTree | undefined,
         public readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>,
@@ -329,6 +329,9 @@ export class ContainerContext implements IContainerContext {
                 details: details ?? codeDetails,
             };
         } else {
+            // If "module" is not in the result, we are using a legacy ICodeLoader.  Fix the result up with details.
+            // Once usage drops to 0 we can remove this compat path.
+            this.taggedLogger.sendTelemetryEvent({ eventName: "LegacyCodeLoader" });
             return { module: loadCodeResult, details: codeDetails };
         }
     }

packages/loader/container-loader/src/loader.ts

@@ -13,7 +13,6 @@ import {
     IResponse,
 } from "@fluidframework/core-interfaces";
 import {
-    ICodeLoader,
     IContainer,
     IFluidModule,
     IHostLoader,
@@ -187,7 +186,7 @@ export interface ILoaderProps {
      * The code loader handles loading the necessary code
      * for running a container once it is loaded.
      */
-    readonly codeLoader: ICodeDetailsLoader | ICodeLoader;
+    readonly codeLoader: ICodeDetailsLoader;
 
     /**
      * A property bag of options used by various layers
@@ -243,7 +242,7 @@ export interface ILoaderServices {
      * The code loader handles loading the necessary code
      * for running a container once it is loaded.
      */
-    readonly codeLoader: ICodeDetailsLoader | ICodeLoader;
+    readonly codeLoader: ICodeDetailsLoader;
 
     /**
      * A property bag of options used by various layers