@fluidframework/container-runtime 2.60.0 → 2.61.0-355516

package/src/blobManager/blobManagerSnapSum.ts

@@ -3,11 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
-	AttachState,
-	type IContainerContext,
-} from "@fluidframework/container-definitions/internal";
-import { assert } from "@fluidframework/core-utils/internal";
+import type { IContainerContext } from "@fluidframework/container-definitions/internal";
 import { readAndParse } from "@fluidframework/driver-utils/internal";
 import type { ISummaryTreeWithStats } from "@fluidframework/runtime-definitions/internal";
 import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
@@ -60,72 +56,54 @@ const loadV1 = async (
 export const toRedirectTable = (
 	blobManagerLoadInfo: IBlobManagerLoadInfo,
 	logger: ITelemetryLoggerExt,
-	attachState: AttachState,
-): Map<string, string | undefined> => {
+): Map<string, string> => {
 	logger.sendTelemetryEvent({
 		eventName: "AttachmentBlobsLoaded",
 		count: blobManagerLoadInfo.ids?.length ?? 0,
 		redirectTable: blobManagerLoadInfo.redirectTable?.length,
 	});
-	const redirectTable = new Map<string, string | undefined>(blobManagerLoadInfo.redirectTable);
-	const detached = attachState !== AttachState.Attached;
-	if (blobManagerLoadInfo.ids) {
-		// If we are detached, we don't have storage IDs yet, so set to undefined
-		// Otherwise, set identity (id -> id) entries.
-		for (const entry of blobManagerLoadInfo.ids) {
-			redirectTable.set(entry, detached ? undefined : entry);
+	const redirectTable = new Map<string, string>(blobManagerLoadInfo.redirectTable);
+	if (blobManagerLoadInfo.ids !== undefined) {
+		for (const storageId of blobManagerLoadInfo.ids) {
+			// Older versions of the runtime used the storage ID directly in the handle,
+			// rather than routing through the redirectTable. To support old handles that
+			// were created in this way but unify handling through the redirectTable, we
+			// add identity mappings to the redirect table at load. These identity entries
+			// will be excluded during summarization.
+			redirectTable.set(storageId, storageId);
 		}
 	}
 	return redirectTable;
 };
 
 export const summarizeBlobManagerState = (
-	redirectTable: Map<string, string | undefined>,
-	attachState: AttachState,
-): ISummaryTreeWithStats => summarizeV1(redirectTable, attachState);
+	redirectTable: Map<string, string>,
+): ISummaryTreeWithStats => summarizeV1(redirectTable);
 
-const summarizeV1 = (
-	redirectTable: Map<string, string | undefined>,
-	attachState: AttachState,
-): ISummaryTreeWithStats => {
-	const storageIds = getStorageIds(redirectTable, attachState);
-
-	// if storageIds is empty, it means we are detached and have only local IDs, or that there are no blobs attached
-	const blobIds = storageIds.size > 0 ? [...storageIds] : [...redirectTable.keys()];
+const summarizeV1 = (redirectTable: Map<string, string>): ISummaryTreeWithStats => {
 	const builder = new SummaryTreeBuilder();
-	for (const blobId of blobIds) {
-		builder.addAttachment(blobId);
+	const storageIds = getStorageIds(redirectTable);
+	for (const storageId of storageIds) {
+		// The Attachment is inspectable by storage, which lets it detect that the blob is referenced
+		// and therefore should not be GC'd.
+		builder.addAttachment(storageId);
 	}
 
-	// Any non-identity entries in the table need to be saved in the summary
-	if (redirectTable.size > blobIds.length) {
-		builder.addBlob(
-			redirectTableBlobName,
-			// filter out identity entries
-			JSON.stringify(
-				[...redirectTable.entries()].filter(([localId, storageId]) => localId !== storageId),
-			),
-		);
+	// Exclude identity mappings from the redirectTable summary. Note that
+	// the storageIds of the identity mappings are still included in the Attachments
+	// above, so we expect these identity mappings will be recreated at load
+	// time in toRedirectTable even if there is no non-identity mapping in
+	// the redirectTable.
+	const nonIdentityRedirectTableEntries = [...redirectTable.entries()].filter(
+		([localId, storageId]) => localId !== storageId,
+	);
+	if (nonIdentityRedirectTableEntries.length > 0) {
+		builder.addBlob(redirectTableBlobName, JSON.stringify(nonIdentityRedirectTableEntries));
 	}
 
 	return builder.getSummaryTree();
 };
 
-export const getStorageIds = (
-	redirectTable: Map<string, string | undefined>,
-	attachState: AttachState,
-): Set<string> => {
-	const ids = new Set<string | undefined>(redirectTable.values());
-
-	// If we are detached, we will not have storage IDs, only undefined
-	const undefinedValueInTable = ids.delete(undefined);
-
-	// For a detached container, entries are inserted into the redirect table with an undefined storage ID.
-	// For an attached container, entries are inserted w/storage ID after the BlobAttach op round-trips.
-	assert(
-		!undefinedValueInTable || (attachState === AttachState.Detached && ids.size === 0),
-		0x382 /* 'redirectTable' must contain only undefined while detached / defined values while attached */,
-	);
-
-	return ids as Set<string>;
+export const getStorageIds = (redirectTable: Map<string, string>): Set<string> => {
+	return new Set<string>(redirectTable.values());
 };

package/src/channelCollection.ts

@@ -46,6 +46,7 @@ import {
 	type IRuntimeMessagesContent,
 	type InboundAttachMessage,
 	type IRuntimeMessageCollection,
+	type MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
 import {
 	GCDataBuilder,
@@ -127,8 +128,14 @@ interface FluidDataStoreMessage {
  * being staged on IFluidParentContext can be added here as well, likely with optionality removed,
  * to ease interactions within this package.
  */
-export interface IFluidParentContextPrivate extends Omit<IFluidParentContext, "isReadOnly"> {
+export interface IFluidParentContextPrivate
+	extends Omit<IFluidParentContext, "isReadOnly" | "minVersionForCollab"> {
 	readonly isReadOnly: () => boolean;
+
+	/**
+	 * {@inheritdoc IFluidParentContext.minVersionForCollab}
+	 */
+	readonly minVersionForCollab: MinimumVersionForCollab;
 }
 
 /**
@@ -198,6 +205,7 @@ export function wrapContext(context: IFluidParentContextPrivate): IFluidParentCo
 		setChannelDirty: (address: string) => {
 			return context.setChannelDirty(address);
 		},
+		minVersionForCollab: context.minVersionForCollab,
 	};
 }
 

package/src/containerCompatibility.ts

@@ -45,6 +45,49 @@ export type RuntimeOptionsAffectingDocSchema = Omit<
 	| "summaryOptions"
 >;
 
+/**
+ * Subset of {@link RuntimeOptionsAffectingDocSchema} which existed prior to the introduction of explicitSchemaControl.
+ *
+ * @remarks
+ * Runtime options that affect document schema should generally require explicitSchemaControl to be enabled.
+ * However, to prevent disruption to existing customers, options that existed prior to explicitSchemaControl
+ * do not explicity require explicitSchemaControl to be enabled. Do not add new options to this list.
+ */
+type RuntimeOptionKeysPredatingExplicitSchemaControl = keyof Pick<
+	RuntimeOptionsAffectingDocSchema,
+	| "explicitSchemaControl"
+	| "compressionOptions"
+	| "enableRuntimeIdCompressor"
+	| "flushMode"
+	| "gcOptions"
+	| "enableGroupedBatching"
+>;
+
+/**
+ * List of keys of {@link RuntimeOptionsAffectingDocSchema} which existed prior to the introduction of explicitSchemaControl.
+ *
+ * @remarks
+ * Runtime options that affect document schema should generally require explicitSchemaControl to be enabled.
+ * However, to prevent disruption to existing customers, options that existed prior to explicitSchemaControl
+ * do not explicity require explicitSchemaControl to be enabled. Do not add new keys to this list.
+ */
+const keysOfOptionsPredatingExplicitSchemaControl = new Set([
+	"explicitSchemaControl",
+	"compressionOptions",
+	"enableRuntimeIdCompressor",
+	"flushMode",
+	"gcOptions",
+	"enableGroupedBatching",
+]) satisfies Set<RuntimeOptionKeysPredatingExplicitSchemaControl>;
+
+/**
+ * Subset of {@link RuntimeOptionsAffectingDocSchema} which require explicitSchemaControl to be enabled.
+ */
+export type RuntimeOptionKeysThatRequireExplicitSchemaControl = keyof Omit<
+	RuntimeOptionsAffectingDocSchema,
+	RuntimeOptionKeysPredatingExplicitSchemaControl
+>;
+
 /**
  * Mapping of RuntimeOptionsAffectingDocSchema to their compatibility related configs.
  *
@@ -113,6 +156,19 @@ const runtimeOptionsAffectingDocSchemaConfigMap = {
 	},
 } as const satisfies ConfigMap<RuntimeOptionsAffectingDocSchema>;
 
+/**
+ * Keys of {@link ContainerRuntimeOptionsInternal} that require explicitSchemaControl to be enabled.
+ */
+export const runtimeOptionKeysThatRequireExplicitSchemaControl = (
+	Object.keys(
+		runtimeOptionsAffectingDocSchemaConfigMap,
+	) as (keyof RuntimeOptionsAffectingDocSchema)[]
+).filter((key) => {
+	return !keysOfOptionsPredatingExplicitSchemaControl.has(
+		key as RuntimeOptionKeysPredatingExplicitSchemaControl,
+	);
+}) as RuntimeOptionKeysThatRequireExplicitSchemaControl[];
+
 const runtimeOptionsAffectingDocSchemaConfigValidationMap = {
 	enableGroupedBatching: configValueToMinVersionForCollab([
 		[false, "1.0.0"],

package/src/containerRuntime.ts

@@ -130,7 +130,6 @@ import type {
 import {
 	defaultMinVersionForCollab,
 	isValidMinVersionForCollab,
-	type SemanticVersion,
 } from "@fluidframework/runtime-utils/internal";
 import {
 	GCDataBuilder,
@@ -144,6 +143,7 @@ import {
 	exceptionToResponse,
 	seqFromTree,
 } from "@fluidframework/runtime-utils/internal";
+import { semanticVersionToMinimumVersionForCollab } from "@fluidframework/runtime-utils/internal";
 import type {
 	IEventSampler,
 	IFluidErrorBase,
@@ -195,6 +195,8 @@ import {
 	getMinVersionForCollabDefaults,
 	type RuntimeOptionsAffectingDocSchema,
 	validateRuntimeOptions,
+	runtimeOptionKeysThatRequireExplicitSchemaControl,
+	type RuntimeOptionKeysThatRequireExplicitSchemaControl,
 } from "./containerCompatibility.js";
 import { ContainerFluidHandleContext } from "./containerHandleContext.js";
 import { channelToDataStore } from "./dataStore.js";
@@ -947,6 +949,19 @@ export class ContainerRuntime
 			createBlobPayloadPending = defaultConfigs.createBlobPayloadPending,
 		}: IContainerRuntimeOptionsInternal = runtimeOptions;
 
+		// If explicitSchemaControl is off, ensure that options which require explicitSchemaControl are not enabled.
+		if (!explicitSchemaControl) {
+			const disallowedKeys = Object.keys(runtimeOptions).filter(
+				(key) =>
+					runtimeOptionKeysThatRequireExplicitSchemaControl.includes(
+						key as RuntimeOptionKeysThatRequireExplicitSchemaControl,
+					) && runtimeOptions[key] !== undefined,
+			);
+			if (disallowedKeys.length > 0) {
+				throw new UsageError(`explicitSchemaControl must be enabled to use ${disallowedKeys}`);
+			}
+		}
+
 		// The logic for enableRuntimeIdCompressor is a bit different. Since `undefined` represents a logical state (off)
 		// we need to check it's explicitly set in runtimeOptions. If so, we should use that value even if it's undefined.
 		const enableRuntimeIdCompressor =
@@ -1181,7 +1196,7 @@ export class ContainerRuntime
 			documentSchemaController,
 			featureGatesForTelemetry,
 			provideEntryPoint,
-			updatedMinVersionForCollab,
+			semanticVersionToMinimumVersionForCollab(updatedMinVersionForCollab),
 			requestHandler,
 			undefined, // summaryConfiguration
 			recentBatchInfo,
@@ -1503,7 +1518,7 @@ export class ContainerRuntime
 		private readonly documentsSchemaController: DocumentsSchemaController,
 		featureGatesForTelemetry: Record<string, boolean | number | undefined>,
 		provideEntryPoint: (containerRuntime: IContainerRuntime) => Promise<FluidObject>,
-		private readonly minVersionForCollab: SemanticVersion,
+		public readonly minVersionForCollab: MinimumVersionForCollab,
 		private readonly requestHandler?: (
 			request: IRequest,
 			runtime: IContainerRuntime,
@@ -3708,7 +3723,7 @@ export class ContainerRuntime
 		telemetryContext?: ITelemetryContext,
 	): ISummaryTree {
 		if (blobRedirectTable) {
-			this.blobManager.setRedirectTable(blobRedirectTable);
+			this.blobManager.patchRedirectTable(blobRedirectTable);
 		}
 
 		// We can finalize any allocated IDs since we're the only client
@@ -4520,6 +4535,22 @@ export class ContainerRuntime
 		return this.blobManager.createBlob(blob, signal);
 	}
 
+	/**
+	 * Lookup the blob storage ID for a given local blob id.
+	 * @param localId - The local blob id. Likely coming from a handle.
+	 * @returns The storage ID if found and the blob is not pending, undefined otherwise.
+	 * @remarks
+	 * This method provides access to the BlobManager's storage ID lookup functionality.
+	 * For blobs with pending payloads (localId exists but upload hasn't finished), this returns undefined.
+	 * Consumers should use the observability APIs on the handle to understand/wait for storage ID availability.
+	 *
+	 * Warning: the returned blob URL may expire and does not support permalinks.
+	 * This API is intended for temporary integration scenarios only.
+	 */
+	public lookupTemporaryBlobStorageId(localId: string): string | undefined {
+		return this.blobManager.lookupTemporaryBlobStorageId(localId);
+	}
+
 	private submitIdAllocationOpIfNeeded({
 		resubmitOutstandingRanges = false,
 		staged,

package/src/dataStoreContext.ts

@@ -67,6 +67,7 @@ import {
 	type IFluidDataStoreFactory,
 	type PackagePath,
 	type IRuntimeStorageService,
+	type MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
 import {
 	addBlobToSummary,
@@ -351,6 +352,11 @@ export abstract class FluidDataStoreContext
 		return runtimeCompatDetailsForDataStore;
 	}
 
+	/**
+	 * {@inheritdoc IFluidDataStoreContext.minVersionForCollab}
+	 */
+	public readonly minVersionForCollab: MinimumVersionForCollab;
+
 	private baseSnapshotSequenceNumber: number | undefined;
 
 	/**
@@ -460,6 +466,7 @@ export abstract class FluidDataStoreContext
 
 		this._containerRuntime = props.parentContext.containerRuntime;
 		this.parentContext = props.parentContext;
+		this.minVersionForCollab = props.parentContext.minVersionForCollab;
 		this.id = props.id;
 		this.storage = props.storage;
 		this.scope = props.scope;

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.60.0";
+export const pkgVersion = "2.61.0-355516";