ODSP Client new exposed functionality (DO NOT MERGE)

PACKAGES.md

@@ -183,7 +183,7 @@ The dependencies between layers are enforced by the layer-check command._
 
 | Packages | Layer Dependencies |
 | --- | --- |
-| - [@fluidframework/azure-client](/packages/service-clients/azure-client)</br>- [@fluidframework/odsp-client](/packages/service-clients/odsp-client)</br>- [@fluidframework/tinylicious-client](/packages/service-clients/tinylicious-client)</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp; | - [Core-Interfaces](#Core-Interfaces)</br>- [Driver-Definitions](#Driver-Definitions)</br>- [Container-Definitions](#Container-Definitions)</br>- [Core-Utils](#Core-Utils)</br>- [Telemetry-Utils](#Telemetry-Utils)</br>- [Driver-Utils](#Driver-Utils)</br>- [Other-Utils](#Other-Utils)</br>- [Driver](#Driver)</br>- [Loader](#Loader)</br>- [Runtime](#Runtime)</br>- [Framework](#Framework)</br>- [Routerlicious-Driver](#Routerlicious-Driver) |
+| - [@fluidframework/azure-client](/packages/service-clients/azure-client)</br>- [@fluidframework/odsp-client](/packages/service-clients/odsp-client)</br>- [@fluidframework/tinylicious-client](/packages/service-clients/tinylicious-client)</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp;</br>&nbsp; | - [Core-Interfaces](#Core-Interfaces)</br>- [Driver-Definitions](#Driver-Definitions)</br>- [Container-Definitions](#Container-Definitions)</br>- [Core-Utils](#Core-Utils)</br>- [Client-Utils](#Client-Utils)</br>- [Telemetry-Utils](#Telemetry-Utils)</br>- [Driver-Utils](#Driver-Utils)</br>- [Other-Utils](#Other-Utils)</br>- [Driver](#Driver)</br>- [Loader](#Loader)</br>- [Runtime](#Runtime)</br>- [Framework](#Framework)</br>- [Routerlicious-Driver](#Routerlicious-Driver) |
 
 ### Examples
 

packages/framework/fluid-static/src/fluidContainer.ts

@@ -265,6 +265,11 @@ export interface IFluidContainerInternal extends ContainerExtensionStore {
 	 * @remarks This method is used to expose uploadBlob to the IFluidContainer level. UploadBlob will upload data to server side (as of now, ODSP only). There is no downloadBlob provided as it is not needed(blob lifetime managed by server).
 	 */
 	uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
+
+	/**
+	 * Serialize the container to a string representation. This can be saved for later rehydration.
+	 */
+	serialize(): string;
 }
 
 /**
@@ -401,4 +406,13 @@ class FluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema>
 	public async uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>> {
 		return this.rootDataObject.uploadBlob(blob);
 	}
+
+	public serialize(): string {
+		if (this.container.closed || this.container.attachState !== AttachState.Detached) {
+			throw new Error(
+				"Cannot serialize container. Container must be in detached state and not closed.",
+			);
+		}
+		return this.container.serialize();
+	}
 }

packages/service-clients/odsp-client/api-report/odsp-client.alpha.api.md

@@ -7,6 +7,21 @@
 // @beta
 export type IOdspAudience = IServiceAudience<OdspMember>;
 
+// @beta
+export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
+    attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+    serialize(): string;
+    uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
+}
+
+// @beta
+export interface IOdspFluidContainerEvents extends IEvent {
+    // (undocumented)
+    (event: "readOnlyStateChanged", listener: (readonly: boolean) => void): void;
+    // (undocumented)
+    (event: "sensitivityLabelChanged", listener: (sensitivityLabelsInfo: string) => void): void;
+}
+
 // @beta
 export interface IOdspTokenProvider {
     fetchStorageToken(siteUrl: string, refresh: boolean): Promise<TokenResponse>;
@@ -26,6 +41,10 @@ export class OdspClient {
         container: IFluidContainer<T>;
         services: OdspContainerServices;
     }>;
+    rehydrateContainer<T extends ContainerSchema>(serializedContainer: string, containerSchema: T): Promise<{
+        container: IFluidContainer<T>;
+        services: OdspContainerServices;
+    }>;
 }
 
 // @beta (undocumented)
@@ -43,9 +62,20 @@ export interface OdspConnectionConfig {
     tokenProvider: IOdspTokenProvider;
 }
 
+// @beta (undocumented)
+export interface OdspContainerAttachProps {
+    eTag?: string;
+    fileName: string | undefined;
+    filePath: string | undefined;
+    itemId?: string;
+}
+
 // @beta
-export interface OdspContainerServices {
+export interface OdspContainerServices extends IEventProvider<IOdspFluidContainerEvents> {
     audience: IOdspAudience;
+    dispose(): void;
+    getReadOnlyState(): boolean | undefined;
+    lookupTemporaryBlobURL<T>(handle: IFluidHandle<T>): string | undefined;
 }
 
 // @beta

packages/service-clients/odsp-client/api-report/odsp-client.beta.api.md

@@ -7,6 +7,21 @@
 // @beta
 export type IOdspAudience = IServiceAudience<OdspMember>;
 
+// @beta
+export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
+    attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+    serialize(): string;
+    uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
+}
+
+// @beta
+export interface IOdspFluidContainerEvents extends IEvent {
+    // (undocumented)
+    (event: "readOnlyStateChanged", listener: (readonly: boolean) => void): void;
+    // (undocumented)
+    (event: "sensitivityLabelChanged", listener: (sensitivityLabelsInfo: string) => void): void;
+}
+
 // @beta
 export interface IOdspTokenProvider {
     fetchStorageToken(siteUrl: string, refresh: boolean): Promise<TokenResponse>;
@@ -26,6 +41,10 @@ export class OdspClient {
         container: IFluidContainer<T>;
         services: OdspContainerServices;
     }>;
+    rehydrateContainer<T extends ContainerSchema>(serializedContainer: string, containerSchema: T): Promise<{
+        container: IFluidContainer<T>;
+        services: OdspContainerServices;
+    }>;
 }
 
 // @beta (undocumented)
@@ -43,9 +62,20 @@ export interface OdspConnectionConfig {
     tokenProvider: IOdspTokenProvider;
 }
 
+// @beta (undocumented)
+export interface OdspContainerAttachProps {
+    eTag?: string;
+    fileName: string | undefined;
+    filePath: string | undefined;
+    itemId?: string;
+}
+
 // @beta
-export interface OdspContainerServices {
+export interface OdspContainerServices extends IEventProvider<IOdspFluidContainerEvents> {
     audience: IOdspAudience;
+    dispose(): void;
+    getReadOnlyState(): boolean | undefined;
+    lookupTemporaryBlobURL<T>(handle: IFluidHandle<T>): string | undefined;
 }
 
 // @beta

packages/service-clients/odsp-client/package.json

@@ -104,8 +104,10 @@
 		"temp-directory": "nyc/.nyc_output"
 	},
 	"dependencies": {
+		"@fluid-internal/client-utils": "workspace:~",
 		"@fluidframework/container-definitions": "workspace:~",
 		"@fluidframework/container-loader": "workspace:~",
+		"@fluidframework/container-runtime-definitions": "workspace:~",
 		"@fluidframework/core-interfaces": "workspace:~",
 		"@fluidframework/core-utils": "workspace:~",
 		"@fluidframework/driver-definitions": "workspace:~",
@@ -114,6 +116,7 @@
 		"@fluidframework/odsp-doclib-utils": "workspace:~",
 		"@fluidframework/odsp-driver": "workspace:~",
 		"@fluidframework/odsp-driver-definitions": "workspace:~",
+		"@fluidframework/runtime-utils": "workspace:~",
 		"@fluidframework/telemetry-utils": "workspace:~",
 		"uuid": "^11.1.0"
 	},

packages/service-clients/odsp-client/src/index.ts

@@ -14,10 +14,13 @@
  */
 
 export type {
-	OdspConnectionConfig,
+	IOdspAudience,
+	IOdspFluidContainerEvents,
+	IOdspFluidContainer,
 	OdspClientProps,
+	OdspConnectionConfig,
+	OdspContainerAttachProps,
 	OdspContainerServices,
-	IOdspAudience,
 	OdspMember,
 	TokenResponse,
 } from "./interfaces.js";

packages/service-clients/odsp-client/src/interfaces.ts

@@ -5,9 +5,18 @@
 
 import type {
 	IConfigProviderBase,
+	IEvent,
+	IEventProvider,
+	IFluidHandle,
 	ITelemetryBaseLogger,
 } from "@fluidframework/core-interfaces";
-import type { IMember, IServiceAudience } from "@fluidframework/fluid-static";
+import type {
+	ContainerAttachProps,
+	ContainerSchema,
+	IFluidContainer,
+	IMember,
+	IServiceAudience,
+} from "@fluidframework/fluid-static";
 
 import type { IOdspTokenProvider } from "./token.js";
 
@@ -59,7 +68,6 @@ export interface OdspClientProps {
 }
 
 /**
- * @legacy
  * @beta
  */
 export interface OdspContainerAttachProps {
@@ -72,6 +80,58 @@ export interface OdspContainerAttachProps {
 	 * The file name of the Fluid file. If undefined, the file is named with a GUID.
 	 */
 	fileName: string | undefined;
+
+	/**
+	 * The ID of the item (file) to which the container is being attached.
+	 * When combined with eTag, this will trigger a conversion of an existing file to a Fluid file.
+	 */
+	itemId?: string;
+
+	/**
+	 * Optional eTag to use when attaching the container.
+	 * If provided, the container will
+	 */
+	eTag?: string;
+}
+
+/**
+ * Interface for the events emitted by the ODSP Fluid container services.
+ * @beta
+ */
+export interface IOdspFluidContainerEvents extends IEvent {
+	(event: "readOnlyStateChanged", listener: (readonly: boolean) => void): void;
+	(event: "sensitivityLabelChanged", listener: (sensitivityLabelsInfo: string) => void): void;
+}
+
+/**
+ * ODSP version of the IFluidContainer interface.
+ * @beta
+ */
+export interface IOdspFluidContainer<
+	TContainerSchema extends ContainerSchema = ContainerSchema,
+> extends IFluidContainer<TContainerSchema> {
+	/**
+	 * A newly created container starts detached from the collaborative service.
+	 * Calling `attach()` uploads the new container to the service and connects to the collaborative service.
+	 *
+	 * This function is same as the IFluidContainer.attach function, but has ODSP specific function signatures.
+	 *
+	 * @param props - Optional properties to pass to the attach function.
+	 *
+	 * @returns A promise which resolves when the attach is complete, with the string identifier of the container.
+	 */
+	attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
+
+	/**
+	 * Upload a blob of data.
+	 * @param blob - The blob to upload to the ODSP service.
+	 */
+	uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
+
+	/**
+	 * Serialize the container to a string representation. This can be saved for later rehydration.
+	 */
+	serialize(): string;
 }
 
 /**
@@ -82,11 +142,42 @@ export interface OdspContainerAttachProps {
  * use, will not be included here but rather on the FluidContainer class itself.
  * @beta
  */
-export interface OdspContainerServices {
+export interface OdspContainerServices extends IEventProvider<IOdspFluidContainerEvents> {
 	/**
 	 * Provides an object that facilitates obtaining information about users present in the Fluid session, as well as listeners for roster changes triggered by users joining or leaving the session.
 	 */
 	audience: IOdspAudience;
+
+	/**
+	 * Get the read-only information about the container.
+	 *
+	 * @remarks
+	 *
+	 * This is used to determine if the container is read-only or not.
+	 * Read-only is undefined on disconnected containers.
+	 */
+	getReadOnlyState(): boolean | undefined;
+
+	/**
+	 * Disposes the container services.
+	 */
+	dispose(): void;
+
+	/**
+	 * Lookup the blob URL for a blob handle.
+	 * @param handle - The blob handle to lookup the URL for
+	 * @returns The blob URL if found and the blob is not pending, undefined otherwise
+	 * @remarks
+	 * This function provides access to blob URLs for handles.
+	 * The URL may expire and does not support permalinks.
+	 * For blobs with pending payloads, this returns undefined. Consumers should use
+	 * the observability APIs on the handle (handle.payloadState, payloadShared event)
+	 * to understand/wait for URL availability.
+	 *
+	 * **WARNING**: This API comes with strong warnings that the URL may expire
+	 * and does not support permalinks.
+	 */
+	lookupTemporaryBlobURL<T>(handle: IFluidHandle<T>): string | undefined;
 }
 
 /**