Blob placeholders prototype

examples/apps/blobs/src/container/runtimeFactory.ts

@@ -44,6 +44,11 @@ export class BlobCollectionContainerRuntimeFactory implements IRuntimeFactory {
 				[blobCollectionRegistryKey, Promise.resolve(blobCollectionFactory)],
 			]),
 			provideEntryPoint,
+			runtimeOptions: {
+				// To use the new experimental blob placeholders features, we need to set these flags.
+				explicitSchemaControl: true,
+				createBlobPlaceholders: true,
+			},
 			existing,
 		});
 

packages/common/core-interfaces/api-report/core-interfaces.legacy.alpha.api.md

@@ -282,6 +282,18 @@ export interface IFluidLoadable extends IProvideFluidLoadable {
     readonly handle: IFluidHandle;
 }
 
+// @alpha
+export interface IFluidPlaceholderHandle<T> extends IFluidHandle<T> {
+    readonly events: IEventProvider<IFluidPlaceholderHandleEvents>;
+    readonly payloadState: PayloadState;
+}
+
+// @alpha
+export interface IFluidPlaceholderHandleEvents extends IEvent {
+    (event: "shared", listener: () => void): any;
+    (event: "failed", listener: (error: unknown) => void): any;
+}
+
 // @alpha
 export interface ILoggingError extends Error {
     getTelemetryProperties(): ITelemetryBaseProperties;
@@ -388,6 +400,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 // @public
 export type Off = () => void;
 
+// @alpha
+export type PayloadState = "local" | "shared" | "placeholder" | "failed";
+
 // @public
 export type ReplaceIEventThisPlaceHolder<L extends any[], TThis> = L extends any[] ? {
     [K in keyof L]: L[K] extends IEventThisPlaceHolder ? TThis : L[K];

packages/common/core-interfaces/src/handles.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ErasedType } from "./erasedType.js";
+import type { IEvent, IEventProvider } from "./events.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
 
 /**
@@ -101,6 +102,69 @@ export interface IFluidHandleInternal<
 	bind(handle: IFluidHandleInternal): void;
 }
 
+/**
+ * Information on whether the handle is a placeholder or not.
+ * @privateRemarks
+ * Contents to be merged with IFluidHandleInternal, and then this separate interface should be removed.
+ * @internal
+ */
+export interface IFluidPlaceholderHandleInternal<
+	// REVIEW: Constrain `T` to something? How do we support dds and datastores safely?
+	out T = unknown, // FluidObject & IFluidLoadable,
+> extends IFluidHandleInternal<T> {
+	/**
+	 * Whether the handle is a placeholder, meaning that it may exist before its payload is retrievable.
+	 * For instance, the BlobManager can generate handles before completing the blob upload/attach.
+	 */
+	readonly placeholder: boolean;
+}
+
+/**
+ * The state of the handle's payload.
+ * - "local" - The payload is only available to the local client, and not to remote collaborators
+ * - "shared" - The payload is availabe to both the local client and remote collaborators
+ * - "placeholder" - The payload is not yet available to the local client
+ * - "failed" - The payload is available to the local client but has failed in sharing to remote collaborators
+ * @legacy
+ * @alpha
+ */
+export type PayloadState = "local" | "shared" | "placeholder" | "failed";
+
+/**
+ * Events which fire as the handle's payload state transitions.
+ * @legacy
+ * @alpha
+ */
+export interface IFluidPlaceholderHandleEvents extends IEvent {
+	/**
+	 * Emitted when the payload becomes available to all clients.
+	 */
+	(event: "shared", listener: () => void);
+	/**
+	 * Emitted for locally created handles when the payload fails sharing to remote collaborators.
+	 */
+	(event: "failed", listener: (error: unknown) => void);
+}
+
+/**
+ * Observable state on the handle regarding its payload sharing state.
+ *
+ * @privateRemarks
+ * Contents to be merged to IFluidHandle, and then this separate interface should be removed.
+ * @legacy
+ * @alpha
+ */
+export interface IFluidPlaceholderHandle<T> extends IFluidHandle<T> {
+	/**
+	 * The current state of the handle's payload.
+	 */
+	readonly payloadState: PayloadState;
+	/**
+	 * Event provider, with events that emit as the payload state transitions.
+	 */
+	readonly events: IEventProvider<IFluidPlaceholderHandleEvents>;
+}
+
 /**
  * Symbol which must only be used on an {@link (IFluidHandle:interface)}, and is used to identify such objects.
  *

packages/common/core-interfaces/src/index.ts

@@ -31,7 +31,11 @@ export type {
 	IProvideFluidHandleContext,
 	IProvideFluidHandle,
 	IFluidHandleInternal,
+	IFluidPlaceholderHandle,
+	IFluidPlaceholderHandleEvents,
+	IFluidPlaceholderHandleInternal,
 	IFluidHandleErased,
+	PayloadState,
 } from "./handles.js";
 export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";
 

packages/dds/shared-object-base/src/serializer.ts

@@ -153,7 +153,7 @@ export class FluidSerializer implements IFluidSerializer {
 				? value.url
 				: generateHandleContextPath(value.url, this.context);
 
-			return new RemoteFluidObjectHandle(absolutePath, this.root);
+			return new RemoteFluidObjectHandle(absolutePath, this.root, value.placeholder === true);
 		} else {
 			return value;
 		}

packages/dds/shared-object-base/src/test/serializer.spec.ts

@@ -41,7 +41,11 @@ describe("FluidSerializer", () => {
 	describe("vanilla JSON", () => {
 		const context = new MockHandleContext();
 		const serializer = new FluidSerializer(context);
-		const handle = new RemoteFluidObjectHandle("/root", context);
+		const handle = new RemoteFluidObjectHandle(
+			"/root",
+			context,
+			false, // placeholder
+		);
 
 		// Start with the various JSON-serializable types.  A mix of "truthy" and "falsy" values
 		// are of particular interest.
@@ -167,7 +171,11 @@ describe("FluidSerializer", () => {
 	describe("JSON w/embedded handles", () => {
 		const context = new MockHandleContext();
 		const serializer = new FluidSerializer(context);
-		const handle = new RemoteFluidObjectHandle("/root", context);
+		const handle = new RemoteFluidObjectHandle(
+			"/root",
+			context,
+			false, // placeholder
+		);
 		const serializedHandle = {
 			type: "__fluid_handle__",
 			url: "/root",
@@ -329,8 +337,16 @@ describe("FluidSerializer", () => {
 	describe("Utils", () => {
 		const serializer = new FluidSerializer(new MockHandleContext());
 		it("makeSerializable is idempotent", () => {
-			const bind = new RemoteFluidObjectHandle("/", new MockHandleContext());
-			const handle = new RemoteFluidObjectHandle("/okay", new MockHandleContext());
+			const bind = new RemoteFluidObjectHandle(
+				"/",
+				new MockHandleContext(),
+				false, // placeholder
+			);
+			const handle = new RemoteFluidObjectHandle(
+				"/okay",
+				new MockHandleContext(),
+				false, // placeholder
+			);
 			const input = { x: handle, y: 123 };
 			const serializedOnce = makeHandlesSerializable(input, serializer, bind) as {
 				x: { type: "__fluid_handle__" };

packages/runtime/container-runtime/api-report/container-runtime.legacy.alpha.api.md

@@ -101,6 +101,7 @@ export interface ICompressionRuntimeOptions {
 export interface IContainerRuntimeOptions {
     readonly chunkSizeInBytes?: number;
     readonly compressionOptions?: ICompressionRuntimeOptions;
+    readonly createBlobPlaceholders?: boolean;
     // @deprecated
     readonly enableGroupedBatching?: boolean;
     readonly enableRuntimeIdCompressor?: IdCompressorMode;