@metamask/ocap-kernel/dist/Kernel.d.mts

OCap kernel core components

import type { CapData } from "@endo/marshal";
import type { KernelDatabase } from "@metamask/kernel-store";
import type { JsonRpcCall } from "@metamask/kernel-utils";
import { Logger } from "@metamask/logger";
import type { DuplexStream } from "@metamask/streams";
import type { JsonRpcResponse } from "@metamask/utils";
import type { PingVatResult } from "./rpc/index.mjs";
import type { VatId, KRef, VatWorkerService, ClusterConfig, VatConfig, KernelStatus, Subcluster } from "./types.mjs";
import { VatHandle } from "./VatHandle.mjs";
export declare class Kernel {
    #private;
    /**
     * Construct a new kernel instance.
     *
     * @param commandStream - Command channel from whatever external software is driving the kernel.
     * @param vatWorkerService - Service to create a worker in which a new vat can run.
     * @param kernelDatabase - Database holding the kernel's persistent state.
     * @param options - Options for the kernel constructor.
     * @param options.resetStorage - If true, the storage will be cleared.
     * @param options.logger - Optional logger for error and diagnostic output.
     */
    private constructor();
    /**
     * Create a new kernel instance.
     *
     * @param commandStream - Command channel from whatever external software is driving the kernel.
     * @param vatWorkerService - Service to create a worker in which a new vat can run.
     * @param kernelDatabase - Database holding the kernel's persistent state.
     * @param options - Options for the kernel constructor.
     * @param options.resetStorage - If true, the storage will be cleared.
     * @param options.logger - Optional logger for error and diagnostic output.
     * @returns A promise for the new kernel instance.
     */
    static make(commandStream: DuplexStream<JsonRpcCall, JsonRpcResponse>, vatWorkerService: VatWorkerService, kernelDatabase: KernelDatabase, options?: {
        resetStorage?: boolean;
        logger?: Logger;
    }): Promise<Kernel>;
    /**
     * Send a message from the kernel to an object in a vat.
     *
     * @param target - The object to which the message is directed.
     * @param method - The method to be invoked.
     * @param args - Message arguments.
     *
     * @returns a promise for the (CapData encoded) result of the message invocation.
     */
    queueMessage(target: KRef, method: string, args: unknown[]): Promise<CapData<KRef>>;
    /**
     * Launches a sub-cluster of vats.
     *
     * @param config - Configuration object for sub-cluster.
     * @returns a promise for the (CapData encoded) result of the bootstrap message.
     */
    launchSubcluster(config: ClusterConfig): Promise<CapData<KRef> | undefined>;
    /**
     * Terminates a named sub-cluster of vats.
     *
     * @param subclusterId - The id of the subcluster to terminate.
     * @returns A promise that resolves when termination is complete.
     */
    terminateSubcluster(subclusterId: string): Promise<void>;
    /**
     * Reloads a named subcluster by restarting all its vats.
     * This terminates and restarts all vats in the subcluster.
     *
     * @param subclusterId - The id of the subcluster to reload.
     * @returns A promise for an object containing the subcluster.
     * @throws If the subcluster is not found.
     */
    reloadSubcluster(subclusterId: string): Promise<Subcluster>;
    /**
     * Retrieves a subcluster by its ID.
     *
     * @param subclusterId - The id of the subcluster.
     * @returns The subcluster, or undefined if not found.
     */
    getSubcluster(subclusterId: string): Subcluster | undefined;
    /**
     * Gets all subclusters.
     *
     * @returns An array of subcluster information records.
     */
    getSubclusters(): Subcluster[];
    /**
     * Checks if a vat belongs to a specific subcluster.
     *
     * @param vatId - The ID of the vat to check.
     * @param subclusterId - The ID of the subcluster to check against.
     * @returns True if the vat belongs to the specified subcluster, false otherwise.
     */
    isVatInSubcluster(vatId: VatId, subclusterId: string): boolean;
    /**
     * Gets all vat IDs that belong to a specific subcluster.
     *
     * @param subclusterId - The ID of the subcluster to get vats for.
     * @returns An array of vat IDs that belong to the specified subcluster.
     */
    getSubclusterVats(subclusterId: string): VatId[];
    /**
     * Restarts a vat.
     *
     * @param vatId - The ID of the vat.
     * @returns A promise for the restarted vat.
     */
    restartVat(vatId: VatId): Promise<VatHandle>;
    /**
     * Terminate a vat with extreme prejudice.
     *
     * @param vatId - The ID of the vat.
     * @param reason - If the vat is being terminated, the reason for the termination.
     */
    terminateVat(vatId: VatId, reason?: CapData<KRef>): Promise<void>;
    /**
     * Clear the database.
     */
    clearStorage(): Promise<void>;
    /**
     * Gets a list of the IDs of all running vats.
     *
     * @returns An array of vat IDs.
     */
    getVatIds(): VatId[];
    /**
     * Gets a list of information about all running vats.
     *
     * @returns An array of vat information records.
     */
    getVats(): {
        id: VatId;
        config: VatConfig;
        subclusterId: string;
    }[];
    /**
     * Revoke an exported object. Idempotent. Revoking promises is not supported.
     *
     * @param kref - The KRef of the object to revoke.
     * @throws If the object is a promise.
     */
    revoke(kref: KRef): void;
    /**
     * Check if an object is revoked.
     *
     * @param kref - The KRef of the object to check.
     * @returns True if the object is revoked, false otherwise.
     */
    isRevoked(kref: KRef): boolean;
    /**
     * Get the current kernel status, defined as the current cluster configuration
     * and a list of all running vats.
     *
     * @returns The current kernel status containing vats and subclusters information.
     */
    getStatus(): KernelStatus;
    /**
     * Reap vats that match the filter.
     *
     * @param filter - A function that returns true if the vat should be reaped.
     */
    reapVats(filter?: (vatId: VatId) => boolean): void;
    /**
     * Pin a vat root.
     *
     * @param vatId - The ID of the vat.
     * @returns The KRef of the vat root.
     */
    pinVatRoot(vatId: VatId): KRef;
    /**
     * Unpin a vat root.
     *
     * @param vatId - The ID of the vat.
     */
    unpinVatRoot(vatId: VatId): void;
    /**
     * Ping a vat.
     *
     * @param vatId - The ID of the vat.
     * @returns A promise that resolves to the result of the ping.
     */
    pingVat(vatId: VatId): Promise<PingVatResult>;
    /**
     * Stop all running vats and reset the kernel state.
     * This is for debugging purposes only.
     */
    reset(): Promise<void>;
    /**
     * Terminate all vats and collect garbage.
     * This is for debugging purposes only.
     */
    terminateAllVats(): Promise<void>;
    /**
     * Terminate all running vats and reload them.
     * This is for debugging purposes only.
     */
    reload(): Promise<void>;
    /**
     * Collect garbage.
     * This is for debugging purposes only.
     */
    collectGarbage(): void;
}
//# sourceMappingURL=Kernel.d.mts.map