@fluidframework/fluid-runner 2.0.0-internal.1.0.0

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@fluidframework/fluid-runner",
+  "version": "2.0.0-internal.1.0.0",
+  "description": "Utility for running various functionality inside a Fluid Framework environment",
+  "homepage": "https://fluidframework.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/tools/fluid-runner"
+  },
+  "license": "MIT",
+  "author": "Microsoft and contributors",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fluid-runner": "bin/fluidRunner"
+  },
+  "scripts": {
+    "build": "concurrently npm:build:compile npm:lint",
+    "build:commonjs": "npm run tsc && npm run build:test",
+    "build:compile": "concurrently npm:build:commonjs npm:build:esnext",
+    "build:esnext": "tsc --project ./tsconfig.esnext.json",
+    "build:full": "npm run build",
+    "build:full:compile": "npm run build:compile",
+    "build:test": "tsc --project ./src/test/tsconfig.json",
+    "clean": "rimraf dist lib *.tsbuildinfo *.build.log",
+    "eslint": "eslint --format stylish src",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
+    "lint": "npm run eslint",
+    "lint:fix": "npm run eslint:fix",
+    "test": "npm run test:mocha",
+    "test:coverage": "nyc npm test -- --reporter xunit --reporter-option output=nyc/junit-report.xml",
+    "test:mocha": "mocha --ignore 'dist/test/types/*' --recursive dist/test -r node_modules/@fluidframework/mocha-test-setup --unhandled-rejections=strict",
+    "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
+    "tsc": "tsc",
+    "tsfmt": "tsfmt --verify",
+    "tsfmt:fix": "tsfmt --replace"
+  },
+  "nyc": {
+    "all": true,
+    "cache-dir": "nyc/.cache",
+    "exclude": [
+      "src/test/**/*.ts",
+      "dist/test/**/*.js"
+    ],
+    "exclude-after-remap": false,
+    "include": [
+      "src/**/*.ts",
+      "dist/**/*.js"
+    ],
+    "report-dir": "nyc/report",
+    "reporter": [
+      "cobertura",
+      "html",
+      "text"
+    ],
+    "temp-directory": "nyc/.nyc_output"
+  },
+  "dependencies": {
+    "@fluidframework/aqueduct": "^2.0.0-internal.1.0.0",
+    "@fluidframework/common-definitions": "^0.20.1",
+    "@fluidframework/container-definitions": "^2.0.0-internal.1.0.0",
+    "@fluidframework/container-loader": "^2.0.0-internal.1.0.0",
+    "@fluidframework/core-interfaces": "^2.0.0-internal.1.0.0",
+    "@fluidframework/driver-definitions": "^2.0.0-internal.1.0.0",
+    "@fluidframework/odsp-driver": "^2.0.0-internal.1.0.0",
+    "@fluidframework/odsp-driver-definitions": "^2.0.0-internal.1.0.0",
+    "@fluidframework/telemetry-utils": "^2.0.0-internal.1.0.0",
+    "yargs": "13.2.2"
+  },
+  "devDependencies": {
+    "@fluidframework/build-common": "^0.24.0",
+    "@fluidframework/eslint-config-fluid": "^0.28.2000",
+    "@fluidframework/mocha-test-setup": "^2.0.0-internal.1.0.0",
+    "@rushstack/eslint-config": "^2.5.1",
+    "@types/mocha": "^9.1.1",
+    "@types/node": "^14.18.0",
+    "concurrently": "^6.2.0",
+    "cross-env": "^7.0.2",
+    "eslint": "~8.6.0",
+    "mocha": "^10.0.0",
+    "nyc": "^15.0.0",
+    "rimraf": "^2.6.2",
+    "typescript": "~4.5.5"
+  }
+}

package/src/codeLoaderBundle.ts

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ITelemetryBaseLogger } from "@fluidframework/common-definitions";
+import { ICodeDetailsLoader, IContainer } from "@fluidframework/container-definitions";
+import { FluidObject } from "@fluidframework/core-interfaces";
+
+/**
+ * Contract that defines the necessary exports for the bundle provided at runtime
+ * For an example, see "src/test/sampleCodeLoader.ts"
+ */
+ export interface ICodeLoaderBundle {
+    /**
+     * Fluid export of all the required objects and functions
+     */
+    fluidExport: Promise<IFluidFileConverter>;
+}
+
+/**
+ * Instance that holds all the details for Fluid file conversion
+ */
+export interface IFluidFileConverter {
+    /**
+     * Code loader details to provide at Loader creation
+     */
+    codeLoader: ICodeDetailsLoader;
+
+    /**
+     * Scope object to provide at Loader creation
+     */
+    scope?: FluidObject;
+
+    /**
+     * Execute code and return the results
+     * @param container - container created by this application
+     * @param scenario - scenario this execution is related to
+     * @param logger - passed through logger object
+     * @returns - object containing file names as property keys and file content as values
+     */
+    execute(container: IContainer, scenario: string, logger: ITelemetryBaseLogger): Promise<Record<string, string>>;
+}
+
+/**
+ * Type cast to ensure necessary methods are present in the provided bundle
+ * @param bundle - bundle provided to this application
+ */
+export function isCodeLoaderBundle(bundle: any): bundle is ICodeLoaderBundle {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return bundle?.fluidExport && typeof bundle.fluidExport === "object";
+}

package/src/exportFile.ts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as fs from "fs";
+import path from "path";
+import { ITelemetryLogger } from "@fluidframework/common-definitions";
+import { LoaderHeader } from "@fluidframework/container-definitions";
+import { Loader } from "@fluidframework/container-loader";
+import { createLocalOdspDocumentServiceFactory } from "@fluidframework/odsp-driver";
+import { PerformanceEvent } from "@fluidframework/telemetry-utils";
+import { getArgsValidationError } from "./getArgsValidationError";
+import { IFluidFileConverter, isCodeLoaderBundle } from "./codeLoaderBundle";
+import { FakeUrlResolver } from "./fakeUrlResolver";
+
+export type IExportFileResponse = IExportFileResponseSuccess | IExportFileResponseFailure;
+
+interface IExportFileResponseSuccess {
+    success: true;
+}
+
+interface IExportFileResponseFailure {
+    success: false;
+    eventName: string;
+    errorMessage: string;
+    error?: any;
+}
+
+const clientArgsValidationError = "Client_ArgsValidationError";
+
+export async function exportFile(
+    codeLoader: string,
+    inputFile: string,
+    outputFolder: string,
+    scenario: string,
+    logger: ITelemetryLogger,
+): Promise<IExportFileResponse> {
+    try {
+        return await PerformanceEvent.timedExecAsync(logger, { eventName: "ExportFile" }, async () => {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+            const codeLoaderBundle = require(codeLoader);
+            if (!isCodeLoaderBundle(codeLoaderBundle)) {
+                const eventName = clientArgsValidationError;
+                const message = "Code loader bundle is not of type CodeLoaderBundle";
+                return { success: false, eventName, errorMessage: message };
+            }
+
+            const argsValidationError = getArgsValidationError(inputFile, outputFolder, scenario);
+            if (argsValidationError) {
+                const eventName = clientArgsValidationError;
+                return { success: false, eventName, errorMessage: argsValidationError };
+            }
+
+            // TODO: read file stream
+            const inputFileContent = fs.readFileSync(inputFile, { encoding: "utf-8" });
+
+            const results = await createContainerAndExecute(
+                inputFileContent,
+                await codeLoaderBundle.fluidExport,
+                scenario,
+                logger,
+            );
+            // eslint-disable-next-line guard-for-in, no-restricted-syntax
+            for (const key in results) {
+                fs.appendFileSync(path.join(outputFolder, key), results[key]);
+            }
+            return { success: true };
+        });
+    } catch (error) {
+        const eventName = "Client_UnexpectedError";
+        return { success: false, eventName, errorMessage: "Unexpected error", error };
+    }
+}
+
+export async function createContainerAndExecute(
+    localOdspSnapshot: string,
+    fluidFileConverter: IFluidFileConverter,
+    scenario: string,
+    logger: ITelemetryLogger,
+): Promise<Record<string, string>> {
+    const loader = new Loader({
+        urlResolver: new FakeUrlResolver(),
+        documentServiceFactory: createLocalOdspDocumentServiceFactory(localOdspSnapshot),
+        codeLoader: fluidFileConverter.codeLoader,
+        scope: fluidFileConverter.scope,
+    });
+
+    const container = await loader.resolve({ url: "/fakeUrl/", headers: {
+        [LoaderHeader.loadMode]: { opsBeforeReturn: "cached" } } });
+
+    return PerformanceEvent.timedExecAsync(logger, { eventName: "ExportFile" }, async () =>
+        fluidFileConverter.execute(container, scenario, logger));
+}

package/src/fakeUrlResolver.ts

@@ -0,0 +1,49 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IRequest } from "@fluidframework/core-interfaces";
+import { IContainerPackageInfo, IResolvedUrl, IUrlResolver } from "@fluidframework/driver-definitions";
+import { IOdspResolvedUrl } from "@fluidframework/odsp-driver-definitions";
+
+const fakeId = "FakeUrlResolver";
+const fakeUrl = "/FakeUrlResolver/";
+
+/**
+ * Fake URL resolver that returns hard coded values on every request
+ */
+export class FakeUrlResolver implements IUrlResolver {
+    public async resolve(_request: IRequest): Promise<IResolvedUrl | undefined> {
+        const fakeOdspResolvedUrl: IOdspResolvedUrl = {
+            type: "fluid",
+            odspResolvedUrl: true,
+            id: fakeId,
+            siteUrl: fakeUrl,
+            driveId: fakeId,
+            itemId: fakeId,
+            url: fakeUrl,
+            hashedDocumentId: fakeId,
+            endpoints: {
+                snapshotStorageUrl: fakeUrl,
+                attachmentPOSTStorageUrl: fakeUrl,
+                attachmentGETStorageUrl: fakeUrl,
+                deltaStorageUrl: fakeUrl,
+            },
+            tokens: {},
+            fileName: fakeId,
+            summarizer: false,
+            fileVersion: fakeId,
+        };
+
+        return fakeOdspResolvedUrl;
+    }
+
+    public async getAbsoluteUrl(
+        _resolvedUrl: IResolvedUrl,
+        _relativeUrl: string,
+        _packageInfoSource?: IContainerPackageInfo,
+    ): Promise<string> {
+        return "";
+    }
+}

package/src/fluidRunner.ts

@@ -0,0 +1,83 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as fs from "fs";
+import * as yargs from "yargs";
+import { ChildLogger } from "@fluidframework/telemetry-utils";
+import { exportFile } from "./exportFile";
+// eslint-disable-next-line import/no-internal-modules
+import { FileLogger } from "./logger/FileLogger";
+
+function fluidRunner() {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    yargs
+        .strict()
+        .version(false)
+        .command(
+            "exportFile",
+            "Generate an output for a local snapshot",
+            // eslint-disable-next-line @typescript-eslint/no-shadow
+            (yargs) =>
+                yargs
+                    .option("codeLoader", {
+                        describe: "Name of the code loader bundle",
+                        type: "string",
+                        demandOption: true,
+                    })
+                    .option("inputFile", {
+                        describe: "Name of the file containing local ODSP snapshot",
+                        type: "string",
+                        demandOption: true,
+                    })
+                    .option("outputFolder", {
+                        describe: "Name of the output file",
+                        type: "string",
+                        demandOption: true,
+                    })
+                    .option("scenario", {
+                        describe: "Name of scenario to invoke",
+                        type: "string",
+                        demandOption: true,
+                    })
+                    .option("telemetryFile", {
+                        describe: "Config and session data for telemetry",
+                        type: "string",
+                        demandOption: true,
+                    }),
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            async (argv) => {
+                if (fs.existsSync(argv.telemetryFile)) {
+                    console.error(`Telemetry file already exists [${argv.telemetryFile}]`);
+                    process.exit(1);
+                }
+
+                const fileLogger = new FileLogger(argv.telemetryFile);
+
+                const logger = ChildLogger.create(fileLogger, "LocalSnapshotRunnerApp",
+                    { all: { Event_Time: () => Date.now() } });
+
+                const result = await exportFile(
+                    argv.codeLoader,
+                    argv.inputFile,
+                    argv.outputFolder,
+                    argv.scenario,
+                    logger,
+                );
+
+                if (!result.success) {
+                    console.error(`${result.eventName}: ${result.errorMessage}`);
+                    logger.sendErrorEvent({ eventName: result.eventName, message: result.errorMessage }, result.error);
+                    await fileLogger.flush();
+                    process.exit(1);
+                } else {
+                    await fileLogger.flush();
+                }
+            },
+        )
+        .help()
+        .demandCommand().argv;
+}
+
+fluidRunner();

package/src/getArgsValidationError.ts

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as fs from "fs";
+
+export function getArgsValidationError(
+    inputFile: string,
+    outputFolder: string,
+    scenario: string,
+): string | undefined {
+    // Validate input file
+    if (!inputFile) {
+        // TODO: Do not log file name. It can be customer content
+        return "Input file name is missing.";
+    } else if (!fs.existsSync(inputFile)) {
+        return "Input file does not exist.";
+    }
+
+    // Validate output file
+    if (!outputFolder) {
+        return "Output folder name is missing.";
+    } else if (!fs.existsSync(outputFolder)) {
+        return "Output folder does not exist.";
+    } else if (fs.existsSync(`${outputFolder}/index.html`)) {
+        return "Output file already exists.";
+    }
+
+    // Validate scenario name
+    if (!scenario) {
+        return "Scenario name is missing.";
+    }
+
+    return undefined;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export * from "./codeLoaderBundle";
+export * from "./exportFile";

package/src/logger/FileLogger.ts

@@ -0,0 +1,44 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as fs from "fs";
+import { ITelemetryBaseEvent, ITelemetryBaseLogger } from "@fluidframework/common-definitions";
+
+/**
+ * Logger that writes events into a defined file
+ */
+export class FileLogger implements ITelemetryBaseLogger {
+    public supportsTags?: true | undefined;
+
+    /** Hold events in memory until flushed */
+    private events: string[] = [];
+
+    /**
+     * @param filePath - file path to write logs to
+     * @param eventsPerFlush - number of events per flush
+     */
+    public constructor(
+        private readonly filePath: string,
+        private readonly eventsPerFlush: number = 50,
+    ) { }
+
+    public async flush(): Promise<void> {
+        if (this.events.length > 0) {
+            fs.appendFileSync(this.filePath, this.events.join("\n"));
+            this.events = [];
+        }
+    }
+
+    public send(event: ITelemetryBaseEvent): void {
+        const logEvent = JSON.stringify(event);
+
+        this.events.push(logEvent);
+
+        if (this.events.length >= this.eventsPerFlush || event.category === "error") {
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this.flush();
+        }
+    }
+}

package/src/packageVersion.ts

@@ -0,0 +1,9 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ *
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY
+ */
+
+export const pkgName = "@fluidframework/fluid-runner";
+export const pkgVersion = "1.2.0";

package/tsconfig.esnext.json

@@ -0,0 +1,7 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "./lib",
+        "module": "esnext"
+    },
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "extends": "@fluidframework/build-common/ts-common-config.json",
+    "exclude": [
+        "src/test/**/*"
+    ],
+    "compilerOptions": {
+        "rootDir": "./src",
+        "outDir": "./dist",
+        "composite": true
+    },
+    "include": [
+        "src/**/*"
+    ]
+}