@fluidframework/fluid-runner

This package contains utility for running various functionality inside a Fluid Framework environment.

Using Fluid Framework libraries

For a dependency on a Fluid Framework library's public APIs, we recommend a ^ (caret) version range. For example, use ^1.3.4.

For a dependency on an unstable API, such as a beta API, we recommend a more restrictive version range. For example, use a ~ version range.

Installation

Run this command to install the package:

npm i @fluidframework/fluid-runner

Importing from this package

This package uses package.json exports to separate APIs by support level. For information about the support guarantees, read API Support Levels.

Import the public APIs from @fluidframework/fluid-runner.

Import the legacy APIs from @fluidframework/fluid-runner/legacy.

Export File

Allows some execution to be made on a container given a provided ODSP snapshot.

Sample command

If package is installed globally: node fluid-runner exportFile --codeLoader=compiledBundle.js --inputFile=inputFileName.fluid --outputFile=result.txt --telemetryFile=telemetryFile.txt

If working directly on this package: node bin/fluid-runner exportFile --codeLoader=compiledBundle.js --inputFile=inputFileName.fluid --outputFile=result.txt --telemetryFile=telemetryFile.txt

Code Loader bundle format

The Code Loader bundle should provide defined exports required for this functionality. For more details on what exports are needed, see codeLoaderBundle.ts.

"codeLoader" vs "IFluidFileConverter" argument

You may notice the command line argument codeLoader is optional. If you choose not to provide a value for codeLoader, you must extend this library and provide a IFluidFileConverter implementation to the fluidRunner(...) method.

import { fluidRunner } from "@fluidframework/fluid-runner";

await fluidRunner({
    /* IFluidFileConverter implementation here */
});

Note: Only one of codeLoader or fluidRunner(...) argument is allowed. If both or none are provided, an error will be thrown at the start of execution.

Input file format

The input file is expected to be an ODSP snapshot. For some examples, see the files in the localOdspSnapshots folder.

Telemetry format

There is an optional command line option telemetryFormat that allows you to specify the telemetry output format. The naming provided to this option is strict and must match an option in OutputFormat. The default format is currently JSON

Additional telemetry properties

There is an optional command line option telemetryProp that allows you to specify additional properties that will be added to every telemetry entry. The format follows these rules:

• every key must be a string
• values may be either a string or a number
• keys and values cannot be empty

Example of valid usages:

--telemetryProp prop1 value1 --telemetryProp prop2 10.5
--telemetryProp "  prop1 " "   value1 " prop2 value2
--telemetryProp prop1 "aaa=bbb" prop2 "aaa\"bbb"

No trimming of white-space inside quotes

Example of invalid usages:

--telemetryProp "10" value1
--telemetryProp prop1
--telemetryProp=             // this will be treated as ['']

Consumption

The code around exportFile can be consumed in multiple different layers. It is not necessary to run all this code fully as is, and the following are some interesting code bits involved in this workflow:

• createLogger(...)
  • Creates and wraps an IFileLogger and adds some useful telemetry data to every entry
• createContainerAndExecute(...)
  • This is the core logic for running some action based on a local ODSP snapshot
• getSnapshotFileContent(...)
  • Reads a local ODSP snapshot from both JSON and binary formats for usage in createContainerAndExecute(...)

For an example of a consumption path that differs slightly to exportFile(...), see parseBundleAndExportFile(...). In addition to running the same logic as exportFile method, it implements the logic around parsing a dynamically provided bundle path into an IFluidFileConverter object.

Contribution Guidelines

You can contribute to Fluid Framework in these ways:

• Answer questions in GitHub Discussions.
• Submit bug reports and help verify fixes.
• Review source code changes.
• Contribute bug fixes.

For detailed instructions, read the repo documentation.

This project follows the Microsoft Open Source Code of Conduct. For more information, read the Code of Conduct frequently asked questions. For questions or comments, contact [email protected].

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Help

Read the Fluid Framework documentation for information about Fluid Framework concepts and APIs.

To request information that the documentation does not contain, create an issue.

Trademark

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.

Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.