or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcontainer-lifecycle.mdindex.mdprotocol-quorum.mdutilities.md
tile.json

tessl/npm-fluidframework--container-loader

Fluid container loader providing core container loading functionality for the Fluid Framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@fluidframework/container-loader@2.60.x

To install, run

npx @tessl/cli install tessl/npm-fluidframework--container-loader@2.60.0

index.mddocs/

Fluid Container Loader

The Fluid Framework container loader provides the core container loading functionality for the Fluid Framework, serving as the minimal kernel of the Fluid runtime responsible for providing access to Fluid storage and consensus over a quorum of clients. It manages container lifecycle including loading, connectivity states, audience tracking, error handling, and readonly states.

Package Information

  • Package Name: @fluidframework/container-loader
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @fluidframework/container-loader

Core Imports

import { 
  Loader, 
  ConnectionState,
  createDetachedContainer,
  loadExistingContainer,
  rehydrateDetachedContainer,
  waitContainerToCatchUp,
  isLocationRedirectionError,
  resolveWithLocationRedirectionHandling,
  tryParseCompatibleResolvedUrl
} from "@fluidframework/container-loader";

For CommonJS:

const { 
  Loader, 
  ConnectionState,
  createDetachedContainer,
  loadExistingContainer,
  rehydrateDetachedContainer,
  waitContainerToCatchUp,
  isLocationRedirectionError,
  resolveWithLocationRedirectionHandling,
  tryParseCompatibleResolvedUrl
} = require("@fluidframework/container-loader");

Basic Usage

import { 
  Loader, 
  createDetachedContainer,
  loadExistingContainer,
  ConnectionState 
} from "@fluidframework/container-loader";
import type { 
  ILoaderProps,
  ICreateDetachedContainerProps,
  ILoadExistingContainerProps 
} from "@fluidframework/container-loader";

// Create a loader with required services
const loader = new Loader({
  codeLoader: myCodeLoader,
  documentServiceFactory: myDocServiceFactory,
  urlResolver: myUrlResolver,
  // Optional configuration
  configProvider: myConfigProvider,
  logger: myLogger,
  options: myLoaderOptions
});

// Load an existing container
const container = await loader.resolve(request);

// Or create a detached container
const detachedContainer = await loader.createDetachedContainer(codeDetails);

// Wait for container to catch up
const success = await waitContainerToCatchUp(container);

// Monitor connection state
container.on("connected", () => {
  console.log("Container connected");
});

container.on("disconnected", () => {
  console.log("Container disconnected");
});

Architecture

The Fluid Container Loader is built around several key components:

  • Loader: Central class managing container creation, loading, and lifecycle
  • Container Lifecycle Management: Functions for creating, loading, and managing container states
  • Connection Management: Handling connectivity, reconnection logic, and state transitions
  • Protocol Handling: Managing Fluid protocol operations, quorum consensus, and client synchronization
  • Configuration System: Flexible configuration for document services, code loading, and runtime options
  • Utility Functions: Helper functions for URL parsing, location redirection, and compatibility checks

Capabilities

Container Lifecycle Management

Core functionality for creating, loading, and managing Fluid containers throughout their lifecycle.

class Loader implements IHostLoader {
  constructor(loaderProps: ILoaderProps);
  createDetachedContainer(codeDetails: IFluidCodeDetails, createDetachedProps?: {
    canReconnect?: boolean;
    clientDetailsOverride?: IClientDetails;
  }): Promise<IContainer>;
  resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer>;
  readonly services: ILoaderServices;
}

function createDetachedContainer(props: ICreateDetachedContainerProps): Promise<IContainer>;
function loadExistingContainer(props: ILoadExistingContainerProps): Promise<IContainer>;
function rehydrateDetachedContainer(props: IRehydrateDetachedContainerProps): Promise<IContainer>;

Container Lifecycle

Configuration and Services

Configuration interfaces and service management for customizing loader behavior and integrating with various Fluid Framework services.

interface ILoaderProps {
  readonly codeLoader: ICodeDetailsLoader;
  readonly documentServiceFactory: IDocumentServiceFactory;
  readonly urlResolver: IUrlResolver;
  readonly configProvider?: IConfigProviderBase;
  readonly logger?: ITelemetryBaseLogger;
  readonly options?: ILoaderOptions;
  readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
  readonly scope?: FluidObject;
}

interface ILoaderServices {
  readonly codeLoader: ICodeDetailsLoader;
  readonly documentServiceFactory: IDocumentServiceFactory;
  readonly options: ILoaderOptions;
  readonly scope: FluidObject;
  readonly subLogger: ITelemetryLoggerExt;
  readonly urlResolver: IUrlResolver;
  readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
}

Configuration

Protocol and Quorum Management

Protocol handling interfaces for managing Fluid protocol operations, quorum consensus, and client synchronization.

interface IProtocolHandler extends IBaseProtocolHandler {
  readonly audience: IAudienceOwner;
  processSignal(message: ISignalMessage): any;
}

interface IBaseProtocolHandler {
  readonly attributes: IDocumentAttributes;
  readonly quorum: IQuorum;
  close(): void;
  processMessage(message: ISequencedDocumentMessage, local: boolean): IProcessMessageResult;
  setConnectionState(connected: boolean, clientId: string | undefined): any;
}

type ProtocolHandlerBuilder = (
  attributes: IDocumentAttributes, 
  snapshot: IQuorumSnapshot, 
  sendProposal: (key: string, value: any) => number
) => IProtocolHandler;

Protocol and Quorum

Utilities and Helpers

Utility functions for container management, URL handling, location redirection, and compatibility checks.

function waitContainerToCatchUp(container: IContainer): Promise<boolean>;
function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined;
function resolveWithLocationRedirectionHandling<T>(
  api: (request: IRequest) => Promise<T>, 
  request: IRequest, 
  urlResolver: IUrlResolver, 
  logger?: ITelemetryBaseLogger
): Promise<T>;
function isLocationRedirectionError(error: any): boolean;

Utilities

Connection States

enum ConnectionState {
  Disconnected = 0,
  EstablishingConnection = 3,
  CatchingUp = 1,
  Connected = 2
}

Core Types

interface IParsedUrl {
  id: string;
  path: string;
  query: string;
  version: string | undefined;
}

interface IContainerExperimental extends IContainer {
  /**
   * Get pending state from container. WARNING: misuse of this API can result in duplicate op
   * submission and potential document corruption. The blob returned MUST be deleted if and when this
   * container emits a "connected" event.
   * @returns serialized blob that can be passed to Loader.resolve()
   */
  getPendingLocalState?(): Promise<string>;
}