@fluidframework/fluid-runner 2.102.0 → 2.110.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/fluid-runner",
-  "version": "2.102.0",
+  "version": "2.110.0",
   "description": "Utility for running various functionality inside a Fluid Framework environment",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -71,26 +71,26 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluidframework/aqueduct": "~2.102.0",
-    "@fluidframework/container-definitions": "~2.102.0",
-    "@fluidframework/container-loader": "~2.102.0",
-    "@fluidframework/core-interfaces": "~2.102.0",
-    "@fluidframework/driver-definitions": "~2.102.0",
-    "@fluidframework/odsp-driver": "~2.102.0",
-    "@fluidframework/odsp-driver-definitions": "~2.102.0",
-    "@fluidframework/telemetry-utils": "~2.102.0",
+    "@fluidframework/aqueduct": "~2.110.0",
+    "@fluidframework/container-definitions": "~2.110.0",
+    "@fluidframework/container-loader": "~2.110.0",
+    "@fluidframework/core-interfaces": "~2.110.0",
+    "@fluidframework/driver-definitions": "~2.110.0",
+    "@fluidframework/odsp-driver": "~2.110.0",
+    "@fluidframework/odsp-driver-definitions": "~2.110.0",
+    "@fluidframework/telemetry-utils": "~2.110.0",
     "@json2csv/plainjs": "^7.0.6",
     "yargs": "17.7.2"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~2.102.0",
+    "@fluid-internal/mocha-test-setup": "~2.110.0",
     "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.65.0",
-    "@fluidframework/eslint-config-fluid": "^9.0.0",
-    "@fluidframework/fluid-runner-previous": "npm:@fluidframework/fluid-runner@2.101.0",
+    "@fluidframework/eslint-config-fluid": "^13.0.0",
+    "@fluidframework/fluid-runner-previous": "npm:@fluidframework/fluid-runner@2.103.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/mocha": "^10.0.10",
     "@types/node": "~22.19.17",

package/src/exportFile.ts

@@ -11,17 +11,22 @@ import {
 	waitContainerToCatchUp,
 	type ILoaderProps,
 } from "@fluidframework/container-loader/internal";
+import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { createLocalOdspDocumentServiceFactory } from "@fluidframework/odsp-driver/internal";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	PerformanceEvent,
+	createChildLogger,
 } from "@fluidframework/telemetry-utils/internal";
 
 import type { IFluidFileConverter } from "./codeLoaderBundle.js";
 import { FakeUrlResolver } from "./fakeUrlResolver.js";
 /* eslint-disable import-x/no-internal-modules */
-import type { ITelemetryOptions } from "./logger/fileLogger.js";
-import { createLogger, getTelemetryFileValidationError } from "./logger/loggerUtils.js";
+import type { IFileLoggerTelemetryOptions } from "./logger/fileLogger.js";
+import {
+	createFluidRunnerLogger,
+	getTelemetryFileValidationError,
+} from "./logger/loggerUtils.js";
 import { getArgsValidationError, getSnapshotFileContent, timeoutPromise } from "./utils.js";
 /* eslint-enable import-x/no-internal-modules */
 
@@ -50,7 +55,8 @@ export interface IExportFileResponseFailure {
 const clientArgsValidationError = "Client_ArgsValidationError";
 
 /**
- * Execute code on Container based on ODSP snapshot and write result to file
+ * Execute code on a Fluid {@link @fluidframework/container-definitions#IContainer} loaded from an ODSP snapshot
+ * file and write the resulting string to disk.
  * @internal
  */
 export async function exportFile(
@@ -59,7 +65,7 @@ export async function exportFile(
 	outputFile: string,
 	telemetryFile: string,
 	options?: string,
-	telemetryOptions?: ITelemetryOptions,
+	telemetryOptions?: IFileLoggerTelemetryOptions,
 	timeout?: number,
 	disableNetworkFetch?: boolean,
 ): Promise<IExportFileResponse> {
@@ -68,7 +74,11 @@ export async function exportFile(
 		const eventName = clientArgsValidationError;
 		return { success: false, eventName, errorMessage: telemetryArgError };
 	}
-	const { fileLogger, logger } = createLogger(telemetryFile, telemetryOptions);
+	const { fileLogger, logger: baseLogger } = createFluidRunnerLogger(
+		telemetryFile,
+		telemetryOptions,
+	);
+	const logger = createChildLogger({ logger: baseLogger });
 
 	try {
 		return await PerformanceEvent.timedExecAsync(
@@ -84,10 +94,10 @@ export async function exportFile(
 
 				fs.writeFileSync(
 					outputFile,
-					await createContainerAndExecute(
+					await createFluidRunnerContainerAndExecute(
 						getSnapshotFileContent(inputFile),
 						fluidFileConverter,
-						logger,
+						baseLogger,
 						options,
 						timeout,
 						disableNetworkFetch,
@@ -106,15 +116,59 @@ export async function exportFile(
 	}
 }
 
+/**
+ * Create a Fluid {@link @fluidframework/container-definitions#IContainer} from an ODSP snapshot and run
+ * caller-provided code against it.
+ *
+ * @remarks
+ * The container is loaded with `opsBeforeReturn: "cached"` and {@link @fluidframework/container-loader#waitContainerToCatchUp}
+ * is invoked before {@link IFluidFileConverter.execute} runs. The container is disposed once `execute` resolves
+ * (or rejects).
+ *
+ * @param localOdspSnapshot - The ODSP snapshot to load the container from. May be either the JSON snapshot
+ * as a string or the binary snapshot as a `Uint8Array`.
+ * @param fluidFileConverter - Caller-provided code loader and execution logic. See {@link IFluidFileConverter}.
+ * @param baseLogger - Telemetry logger that will receive events emitted during load and execution. Typically
+ * obtained from {@link createFluidRunnerLogger}.
+ * @param options - Opaque, caller-defined string passed through to {@link IFluidFileConverter.execute}.
+ * @param timeout - Optional timeout in milliseconds. If the operation does not complete within this period
+ * the returned promise rejects. When omitted, no timeout is applied.
+ * @param disableNetworkFetch - When `true`, replaces `global.fetch` with an implementation that throws,
+ * ensuring the container load is fully serviced from the provided snapshot. Defaults to `false`.
+ * @returns The string result returned by {@link IFluidFileConverter.execute}.
+ *
+ * @legacy
+ * @beta
+ */
+export async function createFluidRunnerContainerAndExecute(
+	localOdspSnapshot: string | Uint8Array,
+	fluidFileConverter: IFluidFileConverter,
+	baseLogger: ITelemetryBaseLogger,
+	options?: string,
+	timeout?: number,
+	disableNetworkFetch?: boolean,
+): Promise<string> {
+	const logger = createChildLogger({ logger: baseLogger });
+	return createContainerAndExecute(
+		localOdspSnapshot,
+		fluidFileConverter,
+		logger,
+		options,
+		timeout,
+		disableNetworkFetch,
+	);
+}
+
 /**
  * Create the container based on an ODSP snapshot and execute code on it
  * @returns result of execution
+ * @deprecated Use {@link createFluidRunnerContainerAndExecute}.
  * @internal
  */
 export async function createContainerAndExecute(
 	localOdspSnapshot: string | Uint8Array,
 	fluidFileConverter: IFluidFileConverter,
-	logger: ITelemetryLoggerExt,
+	logger: TelemetryLoggerExt,
 	options?: string,
 	timeout?: number,
 	disableNetworkFetch: boolean = false,

package/src/index.ts

@@ -7,6 +7,7 @@
 export type { ICodeLoaderBundle, IFluidFileConverter } from "./codeLoaderBundle.js";
 export {
 	createContainerAndExecute,
+	createFluidRunnerContainerAndExecute,
 	exportFile,
 	type IExportFileResponse,
 	type IExportFileResponseSuccess,
@@ -15,10 +16,12 @@ export {
 export { fluidRunner } from "./fluidRunner.js";
 export {
 	OutputFormat,
-	type ITelemetryOptions,
+	type IFileLoggerTelemetryOptions,
 	type IFileLogger,
+	type ITelemetryOptions,
 } from "./logger/fileLogger.js";
 export {
+	createFluidRunnerLogger,
 	createLogger,
 	getTelemetryFileValidationError,
 	validateAndParseTelemetryOptions,

package/src/logger/fileLogger.ts

@@ -7,7 +7,8 @@ import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 
 /**
  * Contract for logger that writes telemetry to a file
- * @internal
+ * @legacy
+ * @beta
  */
 export interface IFileLogger extends ITelemetryBaseLogger {
 	/**
@@ -27,9 +28,10 @@ export enum OutputFormat {
 
 /**
  * Options to provide upon creation of IFileLogger
- * @internal
+ * @legacy
+ * @beta
  */
-export interface ITelemetryOptions {
+export interface IFileLoggerTelemetryOptions {
 	/** Desired output format used to create a specific IFileLogger implementation */
 	outputFormat?: OutputFormat;
 
@@ -47,3 +49,10 @@ export interface ITelemetryOptions {
 	/** Number of telemetry events per flush to telemetry file */
 	eventsPerFlush?: number;
 }
+
+/**
+ * Options to provide upon creation of IFileLogger
+ * @deprecated Use {@link IFileLoggerTelemetryOptions}.
+ * @internal
+ */
+export type ITelemetryOptions = IFileLoggerTelemetryOptions;

package/src/logger/loggerUtils.ts

@@ -5,17 +5,50 @@
 
 import * as fs from "fs";
 
+import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import {
-	type ITelemetryLoggerExt,
+	type TelemetryLoggerExt,
 	createChildLogger,
 } from "@fluidframework/telemetry-utils/internal";
 
 import { CSVFileLogger } from "./csvFileLogger.js";
-import { type IFileLogger, type ITelemetryOptions, OutputFormat } from "./fileLogger.js";
+import {
+	type IFileLogger,
+	type IFileLoggerTelemetryOptions,
+	OutputFormat,
+} from "./fileLogger.js";
 import { JSONFileLogger } from "./jsonFileLogger.js";
 
 /**
- * Create an {@link @fluidframework/telemetry-utils#ITelemetryLoggerExt} wrapped around provided {@link IFileLogger}.
+ * Create a telemetry logger wrapped around an {@link IFileLogger} that writes to the given file path.
+ *
+ * @remarks
+ * All telemetry events should be sent through the returned `logger`. The returned `fileLogger` is the
+ * underlying sink — its `close()` method must be called at the end of execution to flush any buffered
+ * events to disk.
+ *
+ * If `options.outputFormat` is not supplied, telemetry is written as JSON. Use {@link OutputFormat.CSV}
+ * to write CSV instead. See {@link IFileLoggerTelemetryOptions} for supported options including default
+ * properties applied to every event and flush batching.
+ *
+ * @param filePath - Path to the file telemetry will be written to. If the file already exists its
+ * contents will be overwritten or corrupted — callers should verify the path is unused before calling.
+ * @param options - Optional telemetry configuration. See {@link IFileLoggerTelemetryOptions}.
+ * @returns The wrapped telemetry logger to send events through, and the underlying `IFileLogger`
+ * which must be closed when telemetry collection is finished.
+ *
+ * @legacy
+ * @beta
+ */
+export function createFluidRunnerLogger(
+	filePath: string,
+	options?: IFileLoggerTelemetryOptions,
+): { logger: ITelemetryBaseLogger; fileLogger: IFileLogger } {
+	return createLogger(filePath, options);
+}
+
+/**
+ * Create an {@link @fluidframework/telemetry-utils#TelemetryLoggerExt} wrapped around provided {@link IFileLogger}.
  *
  * @remarks
  *
@@ -25,13 +58,15 @@ import { JSONFileLogger } from "./jsonFileLogger.js";
  *
  * Note: if an output format is not supplied, default is JSON.
  *
- * @returns Both the `IFileLogger` implementation and `ITelemetryLoggerExt` wrapper to be called.
+ * @returns Both the `IFileLogger` implementation and `TelemetryLoggerExt` wrapper to be called.
+ *
+ * @deprecated Use {@link createFluidRunnerLogger}.
  * @internal
  */
 export function createLogger(
 	filePath: string,
-	options?: ITelemetryOptions,
-): { logger: ITelemetryLoggerExt; fileLogger: IFileLogger } {
+	options?: IFileLoggerTelemetryOptions,
+): { logger: TelemetryLoggerExt; fileLogger: IFileLogger } {
 	const fileLogger =
 		options?.outputFormat === OutputFormat.CSV
 			? new CSVFileLogger(filePath, options?.eventsPerFlush, options?.defaultProps)
@@ -73,7 +108,9 @@ export function validateAndParseTelemetryOptions(
 	format?: string,
 	props?: (string | number)[],
 	eventsPerFlush?: number,
-): { success: false; error: string } | { success: true; telemetryOptions: ITelemetryOptions } {
+):
+	| { success: false; error: string }
+	| { success: true; telemetryOptions: IFileLoggerTelemetryOptions } {
 	let outputFormat: OutputFormat | undefined;
 	const defaultProps: Record<string, string | number> = {};
 

package/src/parseBundleAndExportFile.ts

@@ -6,13 +6,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import { PerformanceEvent } from "@fluidframework/telemetry-utils/internal";
+import { PerformanceEvent, createChildLogger } from "@fluidframework/telemetry-utils/internal";
 
 import { isCodeLoaderBundle, isFluidFileConverter } from "./codeLoaderBundle.js";
-import { type IExportFileResponse, createContainerAndExecute } from "./exportFile.js";
+import {
+	type IExportFileResponse,
+	createFluidRunnerContainerAndExecute,
+} from "./exportFile.js";
 /* eslint-disable import-x/no-internal-modules */
-import type { ITelemetryOptions } from "./logger/fileLogger.js";
-import { createLogger, getTelemetryFileValidationError } from "./logger/loggerUtils.js";
+import type { IFileLoggerTelemetryOptions } from "./logger/fileLogger.js";
+import {
+	createFluidRunnerLogger,
+	getTelemetryFileValidationError,
+} from "./logger/loggerUtils.js";
 /* eslint-enable import-x/no-internal-modules */
 import { getArgsValidationError, getSnapshotFileContent } from "./utils.js";
 
@@ -29,7 +35,7 @@ export async function parseBundleAndExportFile(
 	outputFile: string,
 	telemetryFile: string,
 	options?: string,
-	telemetryOptions?: ITelemetryOptions,
+	telemetryOptions?: IFileLoggerTelemetryOptions,
 	timeout?: number,
 	disableNetworkFetch?: boolean,
 ): Promise<IExportFileResponse> {
@@ -38,7 +44,11 @@ export async function parseBundleAndExportFile(
 		const eventName = clientArgsValidationError;
 		return { success: false, eventName, errorMessage: telemetryArgError };
 	}
-	const { fileLogger, logger } = createLogger(telemetryFile, telemetryOptions);
+	const { fileLogger, logger: baseLogger } = createFluidRunnerLogger(
+		telemetryFile,
+		telemetryOptions,
+	);
+	const logger = createChildLogger({ logger: baseLogger });
 
 	try {
 		return await PerformanceEvent.timedExecAsync(
@@ -76,10 +86,10 @@ export async function parseBundleAndExportFile(
 
 				fs.writeFileSync(
 					outputFile,
-					await createContainerAndExecute(
+					await createFluidRunnerContainerAndExecute(
 						getSnapshotFileContent(inputFile),
 						fluidExport,
-						logger,
+						baseLogger, // Pass baseLogger with ITelemetryBaseLogger type
 						options,
 						timeout,
 						disableNetworkFetch,