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: Listenable<IFluidHandlePayloadPendingEvents>;
+    readonly payloadState: PayloadState;
+}
+
+// @alpha @legacy
+export interface IFluidHandlePayloadPendingEvents {
+    failed: (error: unknown) => void;
+    shared: () => void;
+}
+
 // @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

@@ -5,6 +5,7 @@
 
 import type { ErasedType } from "./erasedType.js";
 import type { IRequest, IResponse } from "./fluidRouter.js";
+import type { Listenable } from "./internal.js";
 
 /**
  * @legacy
@@ -117,6 +118,58 @@ 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 available 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
+ *
+ * @remarks
+ * The client generating the payload will observe the handle start with "local" state and see a transition
+ * of "local" to "shared" in the case of successful sharing, or "local" to "failed" in the case of failed sharing.
+ *
+ * Receiving clients will see a transition of "pending" to "shared" when the payload has been shared.
+ * @legacy
+ * @alpha
+ */
+export type PayloadState = "local" | "shared" | "pending" | "failed";
+
+/**
+ * Events which fire as the handle's payload state transitions.
+ * @legacy
+ * @alpha
+ */
+export interface IFluidHandlePayloadPendingEvents {
+	/**
+	 * Emitted when the payload becomes available to all clients.
+	 */
+	shared: () => void;
+	/**
+	 * Emitted for locally created handles when the payload fails sharing to remote collaborators.
+	 */
+	failed: (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 emitter, with events that emit as the payload state transitions.
+	 */
+	readonly events: Listenable<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";