@holochain/tryorama/lib/conductor.d.ts

Toolset to manage Holochain conductors and facilitate running test scenarios

import { AdminWebsocket, AppAuthenticationToken, AppWebsocket, AttachAppInterfaceRequest } from "@holochain/client";
import { URL } from "node:url";
import { AppWithOptions } from "./scenario.js";
import { AgentsAppsOptions } from "./types.js";
/**
 * @public
 */
export declare const CONDUCTOR_CONFIG = "conductor-config.yaml";
/**
 * @public
 */
export interface ConductorOptions {
    /**
     * Start up conductor after creation.
     *
     * @defaultValue true
     */
    startup?: boolean;
    /**
     * A bootstrap server URL for peers to discover each other.
     */
    bootstrapServerUrl?: URL;
    /**
     * Timeout for requests to Admin and App API.
     */
    timeout?: number;
}
/**
 * @public
 */
export interface NetworkConfig {
    /**
     * The interval in seconds between initiating gossip rounds.
     *
     * This controls how often gossip will attempt to find a peer to gossip with.
     * This can be set as low as you'd like, but you will still be limited by
     * minInitiateIntervalMs. So a low value for this will result in gossip
     * doing its initiation in a burst. Then, when it has run out of peers, it will idle
     * for a while.
     *
     * Default: 100
     */
    initiateIntervalMs?: number;
    /**
     * The minimum amount of time that must be allowed to pass before a gossip round can be
     * initiated by a given peer.
     *
     * This is a rate-limiting mechanism to be enforced against incoming gossip and therefore must
     * be respected when initiating too.
     *
     * Default: 100
     */
    minInitiateIntervalMs?: number;
    /**
     * A jitter value to add to the `initiateIntervalMs`.
     *
     * This is used to avoid peers always being the gossip initiator or acceptor. It can be
     * set to `0` to disable jitter, but it is recommended to leave this at the default value.
     *
     * Default: 30
     */
    initiateJitterMs?: number;
    /**
     * The timeout for a round of gossip.
     *
     * This is the maximum amount of time that a gossip round is allowed to take.
     *
     * Default: 10,000
     */
    roundTimeoutMs?: number;
    /**
     * The network timeout for transport operations.
     *
     * This controls how long Holochain will spend waiting for connections to be established and
     * other low-level network operations.
     *
     * If you are writing tests that start and stop conductors, you may want to set this to a lower
     * value to avoid waiting for connections to conductors that are no longer running.
     *
     * Default: 15
     */
    transportTimeoutS?: number;
    /**
     * The target arc factor for gossip.
     *
     * This controls the range of DHT locations that the peer will aim to store and serve during gossip.
     *
     * For leacher nodes that do not contribute to gossip, set to 0.
     *
     * Values other than 1 or 0 will be rejected.
     *
     * Default: 1
     */
    targetArcFactor?: number;
}
/**
 * Options for using the conductor factory.
 *
 * @public
 */
export type CreateConductorOptions = Pick<ConductorOptions, "bootstrapServerUrl" | "timeout">;
/**
 * The function to create a conductor. It starts a sandbox conductor via the
 * Holochain CLI.
 *
 * @returns A conductor instance.
 *
 * @public
 */
export declare const createConductor: (signalingServerUrl: URL, options?: ConductorOptions & NetworkConfig) => Promise<Conductor>;
/**
 * A class to manage a conductor running on localhost.
 *
 * @public
 */
export declare class Conductor {
    private conductorProcess;
    private conductorDir;
    private adminApiUrl;
    private _adminWs;
    private _appWs;
    private readonly timeout;
    private constructor();
    /**
     * Factory to create a conductor.
     *
     * @returns A configured instance of a conductor, not yet running.
     */
    static create(signalingServerUrl: URL, options?: CreateConductorOptions): Promise<Conductor>;
    setNetworkConfig(createConductorOptions: NetworkConfig): void;
    /**
     * Start the conductor and establish a web socket connection to the Admin
     * API.
     */
    startUp(): Promise<void>;
    /**
     * Close Admin and App API connections and kill the conductor process.
     */
    shutDown(): Promise<number | null>;
    private connectAdminWs;
    /**
     * Attach a web socket to the App API.
     *
     * @param request - Specify a port for the web socket (optional).
     * @returns The app interface port.
     */
    attachAppInterface(request?: AttachAppInterfaceRequest): Promise<number>;
    /**
     * Connect a web socket to the App API,
     *
     * @param token - A token to authenticate the connection.
     * @param port - The websocket port to connect to.
     * @returns An app websocket.
     */
    connectAppWs(token: AppAuthenticationToken, port: number): Promise<AppWebsocket>;
    /**
     * Get the path of the directory that contains all files and folders of the
     * conductor.
     *
     * @returns The conductor's temporary directory.
     */
    getTmpDirectory(): string;
    /**
     * Get all Admin API methods.
     *
     * @returns The Admin API web socket.
     */
    adminWs(): AdminWebsocket;
    /**
     * Install an application into the conductor.
     *
     * @param appBundleSource - The bundle or path to the bundle.
     * @param options - {@link AppOptions} for the hApp bundle (optional).
     * @returns An agent app with cells and conductor handle.
     */
    installApp(appWithOptions: AppWithOptions): Promise<import("@holochain/client").AppInfo>;
    /**
     * Install an app for multiple agents into the conductor.
     */
    installAgentsApps(options: AgentsAppsOptions): Promise<import("@holochain/client").AppInfo[]>;
}
/**
 * Run the `hc` command to delete all conductor data.
 *
 * @returns A promise that resolves when the command is complete.
 *
 * @public
 */
export declare const cleanAllConductors: () => Promise<void>;