Write support for blob handles with pending payload

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

@@ -273,6 +273,18 @@ export interface IFluidHandleInternal<out T = unknown> extends IFluidHandle<T>,
     bind(handle: IFluidHandleInternal): void;
 }
 
+// @alpha @legacy
+export interface IFluidHandlePayloadPending<T> extends IFluidHandle<T> {
+    readonly events: IEventProvider<IFluidHandlePayloadPendingEvents>;
+    readonly payloadState: PayloadState;
+}
+
+// @alpha @legacy
+export interface IFluidHandlePayloadPendingEvents extends IEvent {
+    (event: "shared", listener: () => void): any;
+    (event: "failed", listener: (error: unknown) => void): any;
+}
+
 // @public (undocumented)
 export const IFluidLoadable: keyof IProvideFluidLoadable;
 
@@ -388,6 +400,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 // @public
 export type Off = () => void;
 
+// @alpha @legacy
+export type PayloadState = "local" | "shared" | "pending" | "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";
 
 /**
@@ -117,6 +118,52 @@ export interface IFluidHandleInternalPayloadPending<
 	readonly payloadPending: 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
+ * - "pending" - 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" | "pending" | "failed";
+
+/**
+ * Events which fire as the handle's payload state transitions.
+ * @legacy
+ * @alpha
+ */
+export interface IFluidHandlePayloadPendingEvents 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 IFluidHandlePayloadPending<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<IFluidHandlePayloadPendingEvents>;
+}
+
 /**
  * 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

@@ -32,7 +32,10 @@ export type {
 	IProvideFluidHandle,
 	IFluidHandleInternal,
 	IFluidHandleInternalPayloadPending,
+	IFluidHandlePayloadPending,
+	IFluidHandlePayloadPendingEvents,
 	IFluidHandleErased,
+	PayloadState,
 } from "./handles.js";
 export { IFluidHandleContext, IFluidHandle, fluidHandleSymbol } from "./handles.js";