@quadnix/octo 0.0.30 → 0.1.0

package/dist/services/state-management/state-management.service.d.ts

@@ -1,39 +1,174 @@
-import type { ModelSerializedOutput, ResourceSerializedOutput } from '../../app.type.js';
+import type { ModelSerializedOutput, ResourceSerializedOutput, TerraformFolderOutput, TerraformResourceOutput } from '../../app.type.js';
 import type { IStateProvider } from './state-provider.interface.js';
 /**
+ * The `userData` persisted alongside the model graph in `models.json`.
+ */
+interface ModelStateUserData {
+    terraformFolders?: TerraformFolderOutput[];
+    version?: number;
+}
+/**
+ * The `userData` persisted alongside the resource graph in `resources-actual.json` /
+ * `resources-old.json`.
+ */
+interface ResourceStateUserData {
+    terraformFolders?: TerraformFolderOutput[];
+    terraformResources?: TerraformResourceOutput[];
+    version?: number;
+}
+/**
+ * What an external resource's action made of it, recorded the moment the action succeeded: the
+ * inputs it was given, the properties it was asked for, and the response it produced.
+ *
+ * It exists only between that moment and the `commit` that folds it into the resource graph, and
+ * while it exists it is the truth about that resource - octo state has not caught up yet.
+ */
+interface ExternalResourceState {
+    inputs: Record<string, unknown>;
+    properties: Record<string, unknown>;
+    response: Record<string, string>;
+}
+/**
+ * Reads and writes Octo's state files through the configured {@link IStateProvider}.
+ *
+ * Resolve it from the {@link Container} when you need to inspect what the last run recorded.
+ * Octo manages its own state files, so writing through this service is rarely the right move.
+ *
  * @group Services/State Management
  */
 export declare class StateManagementService {
+    /**
+     * The resource graph as it stands after the last commit.
+     */
+    readonly actualResourceStateFileName: string;
+    /**
+     * The model graph as it stands after the last commit.
+     */
+    readonly modelStateFileName: string;
+    /**
+     * The resource graph as intent described it on the last commit.
+     */
+    readonly oldResourceStateFileName: string;
+    private readonly externalResourceStateFileNamePrefix;
     private readonly stateProvider;
+    /**
+     * @param stateProvider Where state is read from and written to.
+     */
     constructor(stateProvider: IStateProvider);
+    /**
+     * Clears what an external resource's action recorded.
+     *
+     * @internal
+     */
+    deleteExternalResourceState(resourceId: string): Promise<void>;
+    /**
+     * Deletes a state file. Deleting one that is not there is not an error.
+     */
+    deleteState(stateFileName: string): Promise<void>;
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     getAppLock(): Promise<string | undefined>;
+    /**
+     * What an external resource's action made of it, if `commit` has not folded that into the resource
+     * graph yet. Undefined once it has, or before the action has ever run.
+     *
+     * @internal
+     */
+    getExternalResourceState(resourceId: string): Promise<ExternalResourceState | undefined>;
+    /**
+     * Reads the model graph. Returns an empty graph when no state exists yet.
+     */
     getModelState(stateFileName: string, { freeze }?: {
         freeze?: boolean;
     }): Promise<{
         data: ModelSerializedOutput;
-        userData: object;
+        userData: ModelStateUserData;
     }>;
+    /**
+     * The response of one resource: what an external resource's action published and `commit` has not
+     * recorded yet, falling back to what the last commit recorded. Undefined when neither holds it.
+     *
+     * @internal
+     */
+    getResourceResponse(resourceId: string): Promise<Record<string, string> | undefined>;
+    /**
+     * Reads a resource graph. Returns an empty graph when no state exists yet.
+     */
     getResourceState(stateFileName: string, { freeze }?: {
         freeze?: boolean;
     }): Promise<{
         data: ResourceSerializedOutput;
-        userData: object;
+        userData: ResourceStateUserData;
     }>;
+    /**
+     * Reads a state file as-is.
+     *
+     * @param defaultValue Returned instead of throwing when the file does not exist.
+     */
     getState(stateFileName: string, defaultValue?: any): Promise<Buffer>;
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     isAppLocked(lockId: string): Promise<boolean>;
+    /**
+     * The resource id of every external resource record a `commit` has not folded into the resource
+     * graph yet.
+     *
+     * A record is written the moment an action succeeds and cleared by the commit that records it, so
+     * one still here belongs to a run that did not finish.
+     *
+     * @internal
+     */
+    listExternalResourceStateIds(): Promise<string[]>;
+    /**
+     * Takes the app lock and returns its id.
+     *
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it.
+     */
     lockApp(): Promise<{
         lockId: string;
     }>;
-    saveModelState(stateFileName: string, data: ModelSerializedOutput, userData: object): Promise<void>;
-    saveResourceState(stateFileName: string, data: ResourceSerializedOutput, userData: object): Promise<void>;
+    /**
+     * Records what an external resource's action made of it. The next run reads it back rather than
+     * asking the resource graph, which does not learn any of this until `commit`.
+     *
+     * @internal
+     */
+    saveExternalResourceState(resourceId: string, state: ExternalResourceState): Promise<void>;
+    /**
+     * @internal
+     */
+    saveModelState(stateFileName: string, data: ModelSerializedOutput, userData: ModelStateUserData): Promise<void>;
+    /**
+     * @internal
+     */
+    saveResourceState(stateFileName: string, data: ResourceSerializedOutput, userData: ResourceStateUserData): Promise<void>;
+    /**
+     * Writes a state file as-is.
+     */
     saveState(stateFileName: string, data: Buffer): Promise<void>;
+    /**
+     * Releases the app lock. Unlocking an app that is not locked is not an error.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     unlockApp(lockId: string): Promise<void>;
-    updateAppLockTransaction(lockId: string): Promise<void>;
+    /**
+     * @internal
+     */
+    private externalResourceStateFileName;
 }
 /**
  * @internal
  */
 export declare class StateManagementServiceFactory {
     private static instance;
+    /**
+     * @internal
+     */
     static create(stateProvider?: IStateProvider): Promise<StateManagementService>;
 }
+export {};

package/dist/services/state-management/state-management.service.js

@@ -7,15 +7,76 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Factory } from '../../decorators/factory.decorator.js';
 import { TransactionError } from '../../errors/index.js';
 /**
+ * Serializes one state file.
+ *
+ * Formatted rather than written as a single line, because these files are committed: a reviewer
+ * reading the pull request that produced them sees which entries moved, and a merge conflict lands
+ * on the entries that actually collide instead of on the whole file.
+ */
+function serializeState(data, userData) {
+    return Buffer.from(JSON.stringify({ data, userData }, null, 2));
+}
+/**
+ * Reads and writes Octo's state files through the configured {@link IStateProvider}.
+ *
+ * Resolve it from the {@link Container} when you need to inspect what the last run recorded.
+ * Octo manages its own state files, so writing through this service is rarely the right move.
+ *
  * @group Services/State Management
  */
 export class StateManagementService {
+    /**
+     * @param stateProvider Where state is read from and written to.
+     */
     constructor(stateProvider) {
+        /**
+         * The resource graph as it stands after the last commit.
+         */
+        this.actualResourceStateFileName = 'resources-actual.json';
+        /**
+         * The model graph as it stands after the last commit.
+         */
+        this.modelStateFileName = 'models.json';
+        /**
+         * The resource graph as intent described it on the last commit.
+         */
+        this.oldResourceStateFileName = 'resources-old.json';
+        this.externalResourceStateFileNamePrefix = 'resource-state-';
         this.stateProvider = stateProvider;
     }
+    /**
+     * Clears what an external resource's action recorded.
+     *
+     * @internal
+     */
+    async deleteExternalResourceState(resourceId) {
+        await this.deleteState(this.externalResourceStateFileName(resourceId));
+    }
+    /**
+     * Deletes a state file. Deleting one that is not there is not an error.
+     */
+    async deleteState(stateFileName) {
+        return this.stateProvider.deleteState(stateFileName);
+    }
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     async getAppLock() {
         return this.stateProvider.getAppLock();
     }
+    /**
+     * What an external resource's action made of it, if `commit` has not folded that into the resource
+     * graph yet. Undefined once it has, or before the action has ever run.
+     *
+     * @internal
+     */
+    async getExternalResourceState(resourceId) {
+        const recordedState = await this.getState(this.externalResourceStateFileName(resourceId), Buffer.from(''));
+        return recordedState.length > 0 ? JSON.parse(recordedState.toString()) : undefined;
+    }
+    /**
+     * Reads the model graph. Returns an empty graph when no state exists yet.
+     */
     async getModelState(stateFileName, { freeze = true } = {}) {
         const defaultValue = {
             data: {
@@ -39,6 +100,30 @@ export class StateManagementService {
             }
         }
     }
+    /**
+     * The response of one resource: what an external resource's action published and `commit` has not
+     * recorded yet, falling back to what the last commit recorded. Undefined when neither holds it.
+     *
+     * @internal
+     */
+    async getResourceResponse(resourceId) {
+        const recordedState = await this.getExternalResourceState(resourceId);
+        if (recordedState) {
+            return recordedState.response;
+        }
+        const { data } = await this.getResourceState(this.actualResourceStateFileName);
+        const serializedResource = Object.values(data.resources).find((r) => r.resource.resourceId === resourceId);
+        if (!serializedResource) {
+            return undefined;
+        }
+        return Object.entries(serializedResource.resource.response).reduce((accumulator, [key, value]) => {
+            accumulator[key] = String(value);
+            return accumulator;
+        }, {});
+    }
+    /**
+     * Reads a resource graph. Returns an empty graph when no state exists yet.
+     */
     async getResourceState(stateFileName, { freeze = true } = {}) {
         const defaultValue = {
             data: {
@@ -60,6 +145,11 @@ export class StateManagementService {
             }
         }
     }
+    /**
+     * Reads a state file as-is.
+     *
+     * @param defaultValue Returned instead of throwing when the file does not exist.
+     */
     async getState(stateFileName, defaultValue) {
         try {
             return await this.stateProvider.getState(stateFileName);
@@ -73,32 +163,87 @@ export class StateManagementService {
             }
         }
     }
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     async isAppLocked(lockId) {
         return this.stateProvider.isAppLocked(lockId);
     }
+    /**
+     * The resource id of every external resource record a `commit` has not folded into the resource
+     * graph yet.
+     *
+     * A record is written the moment an action succeeds and cleared by the commit that records it, so
+     * one still here belongs to a run that did not finish.
+     *
+     * @internal
+     */
+    async listExternalResourceStateIds() {
+        const stateFileNames = await this.stateProvider.listStates(this.externalResourceStateFileNamePrefix);
+        return stateFileNames
+            .filter((stateFileName) => stateFileName.endsWith('.json'))
+            .map((stateFileName) => decodeURIComponent(stateFileName.slice(this.externalResourceStateFileNamePrefix.length, -'.json'.length)));
+    }
+    /**
+     * Takes the app lock and returns its id.
+     *
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it.
+     */
     async lockApp() {
         return this.stateProvider.lockApp();
     }
+    /**
+     * Records what an external resource's action made of it. The next run reads it back rather than
+     * asking the resource graph, which does not learn any of this until `commit`.
+     *
+     * @internal
+     */
+    async saveExternalResourceState(resourceId, state) {
+        await this.saveState(this.externalResourceStateFileName(resourceId), Buffer.from(JSON.stringify(state)));
+    }
+    /**
+     * @internal
+     */
     async saveModelState(stateFileName, data, userData) {
-        await this.saveState(stateFileName, Buffer.from(JSON.stringify({ data, userData })));
+        await this.saveState(stateFileName, serializeState(data, userData));
     }
+    /**
+     * @internal
+     */
     async saveResourceState(stateFileName, data, userData) {
-        await this.saveState(stateFileName, Buffer.from(JSON.stringify({ data, userData })));
+        await this.saveState(stateFileName, serializeState(data, userData));
     }
+    /**
+     * Writes a state file as-is.
+     */
     async saveState(stateFileName, data) {
         return this.stateProvider.saveState(stateFileName, data);
     }
+    /**
+     * Releases the app lock. Unlocking an app that is not locked is not an error.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     async unlockApp(lockId) {
         return this.stateProvider.unlockApp(lockId);
     }
-    async updateAppLockTransaction(lockId) {
-        return this.stateProvider.updateAppLockTransaction(lockId);
+    /**
+     * @internal
+     */
+    externalResourceStateFileName(resourceId) {
+        // A resource id is not a file name - it carries `/` where a resource is named after a path.
+        return `${this.externalResourceStateFileNamePrefix}${encodeURIComponent(resourceId)}.json`;
     }
 }
 /**
  * @internal
  */
 let StateManagementServiceFactory = class StateManagementServiceFactory {
+    /**
+     * @internal
+     */
     static async create(stateProvider) {
         if (!this.instance) {
             if (!stateProvider) {

package/dist/services/state-management/state-management.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-management.service.js","sourceRoot":"","sources":["../../../src/services/state-management/state-management.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-management.service.js","sourceRoot":"","sources":["../../../src/services/state-management/state-management.service.ts"],"names":[],"mappings":"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"}

package/dist/services/state-management/state-provider.interface.d.ts

@@ -1,14 +1,68 @@
 /**
+ * Where Octo's state files live.
+ *
+ * Octo has no database - it records what it built in state files, and reads them back on the next run
+ * to work out the diff. A state provider is only asked to put a named blob somewhere and hand it back
+ * later, so implementing this interface is all it takes to keep state in S3, a database, or anywhere
+ * else your team already trusts.
+ *
+ * Pass one to {@link Octo.initialize}.
+ *
  * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
  */
 export interface IStateProvider {
+    /**
+     * Deletes a state file. Deleting one that is not there is not an error.
+     */
+    deleteState(stateFileName: string): Promise<void>;
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     getAppLock(): Promise<string | undefined>;
+    /**
+     * Reads a state file.
+     *
+     * @throws {@link TransactionError} With the message `No state found!` when the file does not exist.
+     * Octo treats that as a first run rather than an error.
+     */
     getState(stateFileName: string): Promise<Buffer>;
+    /**
+     * Whether `lockId` is the lock currently held.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a *different* lock is
+     * held, so a caller holding a stale id is told it is stale rather than told the app is free.
+     */
     isAppLocked(lockId: string): Promise<boolean>;
+    /**
+     * The names of the state files whose name starts with `prefix`, named as
+     * {@link IStateProvider.getState} would be given them.
+     *
+     * Octo reads state by name everywhere else, so this is the only way it can discover a file it was
+     * not told about - a record an interrupted run left behind. Returns an empty list when the store
+     * holds nothing matching, including when it does not exist yet.
+     */
+    listStates(prefix: string): Promise<string[]>;
+    /**
+     * Takes the app lock and returns its id, which `apply` and `commit` must then present.
+     *
+     * The lock is taken atomically, so of two callers racing for it exactly one wins.
+     *
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it.
+     */
     lockApp(): Promise<{
         lockId: string;
     }>;
+    /**
+     * Writes a state file, overwriting whatever was there.
+     */
     saveState(stateFileName: string, data: Buffer): Promise<void>;
+    /**
+     * Releases the app lock. Unlocking an app that is not locked is not an error.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is
+     * held, so one run can never release another's.
+     */
     unlockApp(lockId: string): Promise<void>;
-    updateAppLockTransaction(lockId: string): Promise<void>;
 }

package/dist/services/state-management/terraform-state.service.d.ts

@@ -0,0 +1,76 @@
+import { StateManagementService } from './state-management.service.js';
+/**
+ * Moves each module folder's `terraform.tfstate` in and out of Octo's {@link IStateProvider}.
+ *
+ * Terraform's record of what exists is the one thing Octo cannot rebuild, and a local backend leaves
+ * it in the module folder where only the machine that ran the apply can see it. Checking it out
+ * before a terraform command and back in after puts it wherever Octo state already lives, so a team
+ * sharing Octo state shares terraform state with it.
+ *
+ * Check-in is frequent rather than atomic: it runs on every terraform command's return, success or
+ * failure, and on a timer through a long apply. A partial record of what exists beats none.
+ *
+ * {@link TerraformUtility} drives this around every command it runs, so nothing calls it directly.
+ *
+ * @internal
+ */
+export declare class TerraformStateService {
+    private checkInQueue;
+    private periodicCheckIn;
+    private readonly stateManagementService;
+    /**
+     * @param stateManagementService Where terraform state is read from and written to.
+     */
+    constructor(stateManagementService: StateManagementService);
+    /**
+     * Writes every module folder's terraform state to the state provider.
+     *
+     * A folder holding no state file, or one recording no resources, has its state **deleted** rather
+     * than written - that is a module terraform has destroyed, and a file recording nothing is a file
+     * worth nobody's history.
+     *
+     * Check-ins are serialized, so the one on a command's return never races the one on the timer.
+     */
+    checkIn(terragruntDir: string, moduleIds: string[]): Promise<void>;
+    /**
+     * Writes the state provider's terraform state into every module folder.
+     *
+     * A module the provider holds nothing for keeps whatever its folder already has, which is what
+     * adopts the state of a stack that ran with a local backend until now. The check-in that follows
+     * hands that state to the provider, and from then on the provider is the one that answers.
+     */
+    checkOut(terragruntDir: string, moduleIds: string[]): Promise<void>;
+    /**
+     * Starts checking state in on a timer, bounding what a killed runner loses to one interval.
+     */
+    startPeriodicCheckIn(terragruntDir: string, moduleIds: string[]): void;
+    /**
+     * Stops the timer {@link TerraformStateService.startPeriodicCheckIn} started.
+     */
+    stopPeriodicCheckIn(): void;
+    /**
+     * Whether a terraform state file records nothing, which is what a destroyed module is left with.
+     * State that cannot be parsed is treated as holding resources, so an unreadable file is kept.
+     */
+    private holdsNoResources;
+    /**
+     * The name one module's terraform state is stored under, alongside Octo's own state files.
+     */
+    private stateFileName;
+    /**
+     * The body of a check-in, run one at a time through {@link TerraformStateService.checkIn}.
+     */
+    private writeStates;
+}
+/**
+ * @internal
+ */
+export declare class TerraformStateServiceFactory {
+    /**
+     * Never cached: {@link Octo.initialize} builds a new {@link StateManagementService} around the
+     * provider it is given, and a cached instance would go on writing to the previous one.
+     *
+     * @internal
+     */
+    static create(): Promise<TerraformStateService>;
+}