Skip to content

feat(odsp-client): Expose container serialize and rehydrate functionality #25802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

feat(odsp-client): Expose container serialize and rehydrate functionality #25802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
723252a
Expose container.serialize
znewton Oct 21, 2025
f2b6007
Merge branch 'main' into odsp-dedupe-serialize
znewton Nov 3, 2025
d031791
expose only via odsp fluid container
znewton Nov 3, 2025
38afd85
fix build issues
znewton Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions packages/framework/fluid-static/src/fluidContainer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 a detached container to a string representation. This can be saved for later rehydration.
*/
serialize(): string;
Copy link
Contributor

@ChumpChief ChumpChief Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couple thoughts:

  1. IMO it's a flaw in the underlying API that we have diverging paths for detached containers (serialize/rehydrate) as compared to attached containers (getPendingLocalState and load props). Probably not reasonable to fix on your timeline, but just to set context.
  2. The API naming has always been awful too, but at least that's easier to paper over. So I'd suggest renaming at this layer to both:
    1. More clearly indicate that this is for detached containers only (such that throwing for non-detached containers isn't a surprise)
    2. More clearly pair it with its partner API, rehydrate.

Brainstorming some options:

  1. dehydrateDetachedContainer/rehydrateDetachedContainer
  2. saveDetachedContainer/loadDetachedContainer
  3. serializeDetachedContainer/loadFromSerialized

Copy link
Contributor Author

@znewton znewton Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, thank you for the naming context. I'm liking the direction of serializeDetachedContainer/loadFromSerialized. Maybe serializeDetachedContainer/createFromSerializedContainer?

}

/**
Expand Down Expand Up @@ -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();
Copy link
Contributor

@ChumpChief ChumpChief Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Serialization implies a compatibility contract against the outputted serialized form, e.g. if the customer serializes to a string, saves that somewhere, updates to a newer version of Fluid, then tries to use that serialized form to load -- probably needs to work within some support window.

  1. I don't know if we've discussed what that support window/contract is today for its current legacy/beta tagging on IContainer
  2. I suspect that since this PR exposes it on a public API, it might increase that window/contract.

We should at least document the lifespan/expectation of compat that we're giving as we expose this API, if not include more programmatic safeguards like timebomb/version checks.

This might merit some discussion, definitely also get @anthony-murphy 's opinion as it also includes the serialized form from getPendingLocalState.

Copy link
Contributor Author

@znewton znewton Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this PR is exposing it only through ODSP's FluidContainer, so it's Beta, but let me know if I missed something.

I agree the timing window is tricky. For the current usecase, they are basically serializing a "guest" user, logging in, then pretty immediately loading from that serialized state via localStorage.

I would think we could, for now, possibly say "only compatible with current version and tree schema" then improve that compatibility over time, rather than spending a lot of effort right now to meet some arbitrary goal.

}
}
5 changes: 5 additions & 0 deletions packages/service-clients/odsp-client/api-report/odsp-client.alpha.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ export type IOdspAudience = IServiceAudience<OdspMember>;
// @beta
export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
serialize(): string;
}

// @beta
Expand All @@ -31,6 +32,10 @@ export class OdspClient {
container: IOdspFluidContainer<T>;
services: OdspContainerServices;
}>;
rehydrateContainer<T extends ContainerSchema>(serializedContainer: string, containerSchema: T): Promise<{
container: IOdspFluidContainer<T>;
services: OdspContainerServices;
}>;
}

// @beta (undocumented)
Expand Down
5 changes: 5 additions & 0 deletions packages/service-clients/odsp-client/api-report/odsp-client.beta.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ export type IOdspAudience = IServiceAudience<OdspMember>;
// @beta
export interface IOdspFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IFluidContainer<TContainerSchema> {
attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;
serialize(): string;
}

// @beta
Expand All @@ -31,6 +32,10 @@ export class OdspClient {
container: IOdspFluidContainer<T>;
services: OdspContainerServices;
}>;
rehydrateContainer<T extends ContainerSchema>(serializedContainer: string, containerSchema: T): Promise<{
container: IOdspFluidContainer<T>;
services: OdspContainerServices;
}>;
}

// @beta (undocumented)
Expand Down
5 changes: 5 additions & 0 deletions packages/service-clients/odsp-client/src/interfaces.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,11 @@ export interface IOdspFluidContainer<
* @returns A promise which resolves when the attach is complete, with the string identifier of the container.
*/
attach(props?: ContainerAttachProps<OdspContainerAttachProps>): Promise<string>;

/**
* Serialize the container to a string representation. This can be saved for later rehydration.
*/
serialize(): string;
Copy link
Contributor

@ChumpChief ChumpChief Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Serializing isn't service specific, so I'd expect to find it on IFluidContainer (even if AzureClient doesn't have a method to rehydrate).

Copy link
Contributor Author

@znewton znewton Nov 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is on IFluidContainer (internal version), but this is a way to expose some functionality of IFluidContainer with beta rather than public exposure.

}

/**
Expand Down
49 changes: 48 additions & 1 deletion packages/service-clients/odsp-client/src/odspClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import type {
import {
createDetachedContainer,
loadExistingContainer,
rehydrateDetachedContainer,
type ILoaderProps,
} from "@fluidframework/container-loader/internal";
import type {
Expand All @@ -24,6 +25,7 @@ import type { ContainerAttachProps, ContainerSchema } from "@fluidframework/flui
import {
createDOProviderContainerRuntimeFactory,
createFluidContainer,
isInternalFluidContainer,
} from "@fluidframework/fluid-static/internal";
import {
OdspDocumentServiceFactory,
Expand Down Expand Up @@ -136,6 +138,40 @@ export class OdspClient {
return { container: fluidContainer, services };
}

/**
* Create a new container from the serialized state of a detached container.
*
* @param serializedContainer - Serialized string representation of the container.
* @param containerSchema - The schema of the container to rehydrate.
*/
public async rehydrateContainer<T extends ContainerSchema>(
serializedContainer: string,
containerSchema: T,
): Promise<{
container: IOdspFluidContainer<T>;
services: IOdspContainerServices;
}> {
const loaderProps = this.getLoaderProps(containerSchema);

const container = await rehydrateDetachedContainer({
...loaderProps,
serializedState: serializedContainer,
});

const fluidContainer = await this.createFluidContainer<T>(
container,
this.connectionConfig,
);
// Perform type guard to access internal APIs exposed by OdspFluidContainer.
if (!isInternalFluidContainer(fluidContainer)) {
throw new Error("Fluid container is not internal");
}

const services = await this.getContainerServices(container);

return { container: fluidContainer, services };
}

public async getContainer<T extends ContainerSchema>(
id: string,
containerSchema: T,
Expand All @@ -155,6 +191,10 @@ export class OdspClient {
const fluidContainer = await createFluidContainer<T>({
container,
});
// Perform type guard to access internal APIs exposed by OdspFluidContainer.
if (!isInternalFluidContainer(fluidContainer)) {
throw new Error("Fluid container is not internal");
}
const services = await this.getContainerServices(container);
return { container: fluidContainer, services };
}
Expand Down Expand Up @@ -226,7 +266,14 @@ export class OdspClient {
*/
return resolvedUrl.itemId;
};
const fluidContainer = await createFluidContainer<T>({ container });
const fluidContainer = await createFluidContainer<T>({
container,
});
// Perform type guard to access internal APIs exposed by OdspFluidContainer.
if (!isInternalFluidContainer(fluidContainer)) {
throw new Error("Fluid container is not internal");
}
// Assign custom attach method
fluidContainer.attach = attach;
return fluidContainer;
}
Expand Down
Loading