@highstate/backend 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,508 @@
+import { Stack } from '@pulumi/pulumi/automation';
+import { z } from 'zod';
+import { ComponentModel, Entity, UnitRegistration, UnitSource } from '@highstate/contract';
+
+declare class LocalPulumiProjectHost {
+    private lock;
+    private password;
+    hasPassword(): boolean;
+    setPassword(password: string): void;
+    runInline<T>(projectName: string, stackName: string, program: () => Promise<void> | Promise<Record<string, unknown>>, fn: (stack: Stack) => Promise<T>): Promise<T>;
+    runLocal<T>(projectName: string, stackName: string, programPathResolver: () => Promise<string> | string, fn: (stack: Stack) => Promise<T>): Promise<T>;
+}
+
+declare const instanceStatusSchema: z.ZodEnum<["not_created", "updating", "destroying", "refreshing", "created", "error"]>;
+declare const instanceStateSchema: z.ZodObject<{
+    key: z.ZodString;
+    parentKey: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["not_created", "updating", "destroying", "refreshing", "created", "error"]>;
+    resources: z.ZodNumber;
+    totalResources: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+    resources: number;
+    totalResources: number;
+    error?: string | undefined;
+    parentKey?: string | undefined;
+    message?: string | undefined;
+}, {
+    key: string;
+    status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+    resources: number;
+    totalResources: number;
+    error?: string | undefined;
+    parentKey?: string | undefined;
+    message?: string | undefined;
+}>;
+declare const operationType: z.ZodEnum<["update", "destroy", "recreate", "refresh"]>;
+declare const projectOperation: z.ZodObject<{
+    type: z.ZodEnum<["update", "destroy", "recreate", "refresh"]>;
+    instanceIds: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "update" | "destroy" | "recreate" | "refresh";
+    instanceIds: string[];
+}, {
+    type: "update" | "destroy" | "recreate" | "refresh";
+    instanceIds: string[];
+}>;
+declare const projectStateSchema: z.ZodObject<{
+    currentOperation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<["update", "destroy", "recreate", "refresh"]>;
+        instanceIds: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "update" | "destroy" | "recreate" | "refresh";
+        instanceIds: string[];
+    }, {
+        type: "update" | "destroy" | "recreate" | "refresh";
+        instanceIds: string[];
+    }>>;
+    instances: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        parentKey: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["not_created", "updating", "destroying", "refreshing", "created", "error"]>;
+        resources: z.ZodNumber;
+        totalResources: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+        resources: number;
+        totalResources: number;
+        error?: string | undefined;
+        parentKey?: string | undefined;
+        message?: string | undefined;
+    }, {
+        key: string;
+        status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+        resources: number;
+        totalResources: number;
+        error?: string | undefined;
+        parentKey?: string | undefined;
+        message?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    instances: Record<string, {
+        key: string;
+        status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+        resources: number;
+        totalResources: number;
+        error?: string | undefined;
+        parentKey?: string | undefined;
+        message?: string | undefined;
+    } | undefined>;
+    currentOperation?: {
+        type: "update" | "destroy" | "recreate" | "refresh";
+        instanceIds: string[];
+    } | undefined;
+}, {
+    instances: Record<string, {
+        key: string;
+        status: "not_created" | "updating" | "destroying" | "refreshing" | "created" | "error";
+        resources: number;
+        totalResources: number;
+        error?: string | undefined;
+        parentKey?: string | undefined;
+        message?: string | undefined;
+    } | undefined>;
+    currentOperation?: {
+        type: "update" | "destroy" | "recreate" | "refresh";
+        instanceIds: string[];
+    } | undefined;
+}>;
+declare const positionSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    x: number;
+    y: number;
+}, {
+    x: number;
+    y: number;
+}>;
+declare const outputRefSchema: z.ZodObject<{
+    instanceId: z.ZodString;
+    output: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    instanceId: string;
+    output: string;
+}, {
+    instanceId: string;
+    output: string;
+}>;
+declare const instanceModelSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    name: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>;
+    args: z.ZodRecord<z.ZodString, z.ZodAny>;
+    inputs: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        instanceId: z.ZodString;
+        output: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        instanceId: string;
+        output: string;
+    }, {
+        instanceId: string;
+        output: string;
+    }>, z.ZodArray<z.ZodObject<{
+        instanceId: z.ZodString;
+        output: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        instanceId: string;
+        output: string;
+    }, {
+        instanceId: string;
+        output: string;
+    }>, "many">]>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: string;
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    args: Record<string, any>;
+    inputs: Record<string, {
+        instanceId: string;
+        output: string;
+    } | {
+        instanceId: string;
+        output: string;
+    }[]>;
+}, {
+    name: string;
+    type: string;
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    args: Record<string, any>;
+    inputs: Record<string, {
+        instanceId: string;
+        output: string;
+    } | {
+        instanceId: string;
+        output: string;
+    }[]>;
+}>;
+type OperationType = z.infer<typeof operationType>;
+type ProjectOperation = z.infer<typeof projectOperation>;
+type InstanceStatus = z.infer<typeof instanceStatusSchema>;
+type InstanceState = z.infer<typeof instanceStateSchema>;
+type ProjectState = z.infer<typeof projectStateSchema>;
+type Position = z.infer<typeof positionSchema>;
+type OutputRef = z.infer<typeof outputRefSchema>;
+type InstanceModel = z.infer<typeof instanceModelSchema>;
+
+declare const stringArrayType: z.ZodEffects<z.ZodString, string[], string>;
+
+declare function resolveMainLocalProject(projectPath: string | undefined, projectName: string | undefined): Promise<[projecPath: string, projectName: string]>;
+
+declare class SecretAccessDeniedError extends Error {
+    constructor(projectId: string, key: string);
+}
+interface SecretBackend {
+    /**
+     * Get the secrets of the component.
+     *
+     * @param projectId The ID of the project.
+     * @param instanceKey The key of the component instance.
+     *
+     * @returns A record of secret key-value pairs or `null` if the secrets are not found.
+     * @throws {SecretAccessDeniedError} If access to the secrets is denied.
+     */
+    get(projectId: string, instanceKey: string): Promise<Record<string, string>>;
+    /**
+     * Set the secrets of the component.
+     *
+     * @param projectId The ID of the project.
+     * @param instanceKey The key of the component instance.
+     * @param values The record of secret key-value pairs.
+     *
+     * @throws {SecretAccessDeniedError} If access to the secrets is denied.
+     */
+    set(projectId: string, instanceKey: string, values: Record<string, string>): Promise<void>;
+}
+
+declare const secretBackendConfig: z.ZodObject<{
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_SECRET_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+}, "strip", z.ZodTypeAny, {
+    HIGHSTATE_BACKEND_SECRET_TYPE: "local";
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME?: string | undefined;
+}, {
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_TYPE?: "local" | undefined;
+}>;
+declare function createSecretBackend(config: z.infer<typeof secretBackendConfig>, pulumiProjectHost: LocalPulumiProjectHost): Promise<SecretBackend>;
+
+type LibraryModel = Readonly<{
+    components: Readonly<Record<string, ComponentModel>>;
+    entities: Readonly<Record<string, Entity>>;
+}>;
+type EvaluationInput = {
+    instanceId: string;
+    output: string;
+};
+type EvaluationInstance = {
+    type: string;
+    name: string;
+    args: Record<string, unknown>;
+    inputs: Record<string, EvaluationInput | EvaluationInput[]>;
+};
+interface LibraryBackend {
+    /**
+     * Loads the library.
+     */
+    loadLibrary(): Promise<LibraryModel>;
+    /**
+     * Watches the library for changes.
+     * Returns an async iterable that emits the library whenever it changes.
+     */
+    watchLibrary?(signal?: AbortSignal): AsyncIterable<LibraryModel>;
+    /**
+     * Evaluates the instances and returns the stack registrations.
+     *
+     * @param allInstances The all instances defined in the project.
+     * @param instanceIds The instance IDs to evaluate. If not provided, all instances are evaluated.
+     */
+    evaluateInstances(allInstances: Record<string, EvaluationInstance>, instanceIds?: string[]): Promise<Record<string, UnitRegistration>>;
+}
+
+declare const libraryBackendConfig: z.ZodObject<{
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES: z.ZodDefault<z.ZodEffects<z.ZodString, string[], string>>;
+    HIGHSTATE_BACKEND_LIBRARY_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+}, "strip", z.ZodTypeAny, {
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES: string[];
+    HIGHSTATE_BACKEND_LIBRARY_TYPE: "local";
+}, {
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES?: string | undefined;
+    HIGHSTATE_BACKEND_LIBRARY_TYPE?: "local" | undefined;
+}>;
+declare function createLibraryBackend(config: z.infer<typeof libraryBackendConfig>): Promise<LibraryBackend>;
+
+declare const configSchema: z.ZodObject<{
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_STATE_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_SECRET_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+    HIGHSTATE_BACKEND_PROJECT_BLUEPRINTS_DIR: z.ZodDefault<z.ZodString>;
+    HIGHSTATE_BACKEND_PROJECT_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES: z.ZodDefault<z.ZodEffects<z.ZodString, string[], string>>;
+    HIGHSTATE_BACKEND_LIBRARY_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+}, "strip", z.ZodTypeAny, {
+    HIGHSTATE_BACKEND_SECRET_TYPE: "local";
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES: string[];
+    HIGHSTATE_BACKEND_LIBRARY_TYPE: "local";
+    HIGHSTATE_BACKEND_PROJECT_BLUEPRINTS_DIR: string;
+    HIGHSTATE_BACKEND_PROJECT_TYPE: "local";
+    HIGHSTATE_BACKEND_STATE_TYPE: "local";
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME?: string | undefined;
+}, {
+    HIGHSTATE_BACKEND_SECRET_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_PROJECT_NAME?: string | undefined;
+    HIGHSTATE_BACKEND_SECRET_TYPE?: "local" | undefined;
+    HIGHSTATE_BACKEND_LIBRARY_LOCAL_MODULES?: string | undefined;
+    HIGHSTATE_BACKEND_LIBRARY_TYPE?: "local" | undefined;
+    HIGHSTATE_BACKEND_PROJECT_BLUEPRINTS_DIR?: string | undefined;
+    HIGHSTATE_BACKEND_PROJECT_TYPE?: "local" | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_TYPE?: "local" | undefined;
+}>;
+type Config = z.infer<typeof configSchema>;
+declare function loadConfig(env?: NodeJS.ProcessEnv, useDotenv?: boolean): Promise<Config>;
+
+interface ProjectBackend {
+    getInstances(projectId: string): Promise<Record<string, InstanceModel>>;
+    updateInstance(projectId: string, instance: InstanceModel): Promise<void>;
+    deleteInstance(projectId: string, instanceId: string): Promise<void>;
+}
+
+type UnitBaseOptions = {
+    /**
+     * The name of the project to run.
+     */
+    projectName: string;
+    /**
+     * The name of the stack to run.
+     */
+    stackName: string;
+    /**
+     * The signal to abort the operation.
+     */
+    signal?: AbortSignal;
+};
+type UnitRunOptions = UnitBaseOptions & {
+    /**
+     * The source of the unit.
+     */
+    source: UnitSource;
+};
+type UnitUpdateOptions = UnitRunOptions & {
+    /**
+     * The configuration of the stack.
+     */
+    config: Record<string, string>;
+};
+type UnitWatchOptions = UnitBaseOptions & {
+    /**
+     * The final statuses to watch.
+     * If the unit reaches one of these statuses, it should return the current state and exit.
+     */
+    finalStatuses: InstanceStatus[];
+};
+interface RunnerBackend {
+    /**
+     * Watches the unit state.
+     */
+    watch(options: UnitWatchOptions): AsyncIterable<InstanceState>;
+    /**
+     * Updates the unit.
+     *
+     * The operation must only be aborted by the signal, not even when the connection is closed.
+     * If the unit is already updating, it should exit immediately.
+     * If the unit is running another operation, it should throw an error.
+     */
+    update(options: UnitUpdateOptions): Promise<void>;
+    /**
+     * Destroys the unit.
+     *
+     * The operation must only be aborted by the signal, not even when the connection is closed.
+     * If the unit is not created, it should exit immediately.
+     * If the unit is running another operation, it should throw an error.
+     */
+    destroy(options: UnitRunOptions): Promise<void>;
+    /**
+     * Refreshes the unit.
+     *
+     * The operation must only be aborted by the signal, not even when the connection is closed.
+     * If the unit is not created, it should exit immediately.
+     * If the unit is running another operation, it should throw an error.
+     * If the unit is not running, it should exit immediately.
+     */
+    refresh(options: UnitRunOptions): Promise<void>;
+}
+
+interface StateBackend {
+    /**
+     * Gets all the component states for a project.
+     *
+     * @param projectId The ID of the project.
+     */
+    get(projectId: string): Promise<ProjectState>;
+    /**
+     * Watch the component states for a project.
+     * Returns an async iterable that emits the component states.
+     *
+     * @param projectId The ID of the project.
+     */
+    watch?(projectId: string): AsyncIterable<InstanceState>;
+    /**
+     * Updates the component states for a project.
+     * Use `null` to delete a component state.
+     *
+     * @param projectId The ID of the project.
+     * @param state The new project state.
+     */
+    set(projectId: string, state: ProjectState): Promise<void>;
+}
+
+declare const stateBackendConfig: z.ZodObject<{
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME: z.ZodOptional<z.ZodString>;
+    HIGHSTATE_BACKEND_STATE_TYPE: z.ZodDefault<z.ZodEnum<["local"]>>;
+}, "strip", z.ZodTypeAny, {
+    HIGHSTATE_BACKEND_STATE_TYPE: "local";
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME?: string | undefined;
+}, {
+    HIGHSTATE_BACKEND_STATE_PROJECT_PATH?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_PROJECT_NAME?: string | undefined;
+    HIGHSTATE_BACKEND_STATE_TYPE?: "local" | undefined;
+}>;
+declare function createStateBackend(config: z.infer<typeof stateBackendConfig>, pulumiProjectHost: LocalPulumiProjectHost): Promise<StateBackend>;
+
+declare class ProjectOperator {
+    private readonly projectId;
+    readonly state: ProjectState;
+    private readonly runnerBackend;
+    private readonly stateBackend;
+    private readonly libraryBackend;
+    private readonly projectBackend;
+    private readonly secretBackend;
+    constructor(projectId: string, state: ProjectState, runnerBackend: RunnerBackend, stateBackend: StateBackend, libraryBackend: LibraryBackend, projectBackend: ProjectBackend, secretBackend: SecretBackend);
+    private readonly unitPromises;
+    private readonly eventEmitter;
+    private debouncedUpdateState;
+    private abortController;
+    watchInstanceStates(signal?: AbortSignal): AsyncIterable<InstanceState>;
+    watchCurrentOperation(signal?: AbortSignal): AsyncIterable<ProjectOperation | undefined>;
+    /**
+     * Launches the project operation.
+     * Throws an error if the operation is already running.
+     *
+     * @param operation The operation to launch.
+     */
+    launch(operation: ProjectOperation): void;
+    /**
+     * Cancels the current operation.
+     * Does nothing if no operation is running.
+     */
+    cancel(): void;
+    private operate;
+    private upUnit;
+    private getUnitConfig;
+    private watchStateStream;
+    private updateCurrentOperation;
+    private updateInstanceState;
+    private getOrCreateUnitPromise;
+    static create(projectId: string, runnerBackend: RunnerBackend, stateBackend: StateBackend, libraryBackend: LibraryBackend, projectBackend: ProjectBackend, secretBackend: SecretBackend): Promise<ProjectOperator>;
+}
+
+declare class OperatorManager {
+    private readonly runnerBackend;
+    private readonly stateBackend;
+    private readonly libraryBackend;
+    private readonly projectBackend;
+    private readonly secretBackend;
+    private readonly operators;
+    private readonly lock;
+    constructor(runnerBackend: RunnerBackend, stateBackend: StateBackend, libraryBackend: LibraryBackend, projectBackend: ProjectBackend, secretBackend: SecretBackend);
+    get(projectId: string): Promise<ProjectOperator>;
+}
+
+type Services = {
+    readonly libraryBackend: LibraryBackend;
+    readonly secretBackend: SecretBackend;
+    readonly runnerBackend: RunnerBackend;
+    readonly projectBackend: ProjectBackend;
+    readonly stateBackend: StateBackend;
+    readonly operatorManager: OperatorManager;
+};
+declare function createServices(config?: Config): Promise<Services>;
+
+export { type Config, type EvaluationInput, type EvaluationInstance, type InstanceModel, type InstanceState, type InstanceStatus, type LibraryBackend, type LibraryModel, LocalPulumiProjectHost, type OperationType, OperatorManager, type OutputRef, type Position, type ProjectOperation, ProjectOperator, type ProjectState, SecretAccessDeniedError, type SecretBackend, type Services, type StateBackend, createLibraryBackend, createSecretBackend, createServices, createStateBackend, instanceModelSchema, instanceStateSchema, instanceStatusSchema, libraryBackendConfig, loadConfig, operationType, outputRefSchema, positionSchema, projectOperation, projectStateSchema, resolveMainLocalProject, secretBackendConfig, stateBackendConfig, stringArrayType };