@quadnix/octo 0.1.0 → 0.2.0

package/dist/utilities/http/http.utility.js

@@ -0,0 +1,98 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { TransactionError } from '../../errors/index.js';
+/**
+ * The one place octo speaks HTTP.
+ *
+ * A response is handed back whatever its status, so the caller decides what a refusal means instead
+ * of catching one. Only a request that never reached a server throws.
+ *
+ * @internal
+ */
+export class HttpUtility {
+    /**
+     * Downloads `url` into `filePath`, streaming it so its size is not bounded by memory. False when the
+     * server refused it or the download was cut short, which can leave part of the file behind.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all.
+     */
+    static async downloadToFile(url, filePath) {
+        const response = await this.send(url);
+        if (!response.ok || !response.body) {
+            return false;
+        }
+        try {
+            await pipeline(Readable.fromWeb(response.body), createWriteStream(filePath));
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * What a refused request said went wrong, as one line. A service that answers a list - a failed
+     * validation usually does - is read as a sentence, and a body that is not JSON as its status.
+     *
+     * @internal
+     */
+    static async readErrorMessage(response) {
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (error) {
+            return `${response.status} ${response.statusText}`;
+        }
+        const message = Array.isArray(body.message) ? body.message.join(', ') : body.message;
+        return message || `${response.status} ${response.statusText}`;
+    }
+    /**
+     * A body may be a stream, which is sent as it is read rather than held in memory. A stream's length
+     * is unknown to fetch, so a server that needs one is given `Content-Length` in `headers`.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all, which is a different
+     * thing from being refused by it and is the caller's to report differently.
+     */
+    static async send(url, { body, headers = {}, method = 'GET' } = {}) {
+        try {
+            // `duplex` is what lets the body be a stream; Node's fetch refuses one without it.
+            return await fetch(url, { body, duplex: 'half', headers, method });
+        }
+        catch (error) {
+            throw new TransactionError(`Cannot reach "${new URL(url).origin}"!`);
+        }
+    }
+    /**
+     * {@link HttpUtility.send} with a JSON body, which is every request octo makes that carries one
+     * other than an upload.
+     *
+     * @internal
+     */
+    static async sendJson(url, { body, headers = {}, method = 'GET' } = {}) {
+        return this.send(url, {
+            body: body === undefined ? undefined : JSON.stringify(body),
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            method,
+        });
+    }
+    /**
+     * PUTs the file at `filePath` to `url`, streaming it so its size is not bounded by memory, with its
+     * `Content-Length`, which a presigned URL is usually signed with.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all.
+     */
+    static async uploadFile(url, filePath, headers = {}) {
+        const { size } = await stat(filePath);
+        return this.send(url, {
+            body: Readable.toWeb(createReadStream(filePath)),
+            headers: { ...headers, 'Content-Length': String(size) },
+            method: 'PUT',
+        });
+    }
+}
+//# sourceMappingURL=http.utility.js.map

package/dist/utilities/http/http.utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.utility.js","sourceRoot":"","sources":["../../../src/utilities/http/http.utility.ts"],"names":[],"mappings":"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"}

package/dist/utilities/string/string.utility.d.ts

@@ -1,10 +1,30 @@
 /**
- * @internal
+ * String helpers for module and resource authors: hashing values into stable ids, fitting names into
+ * a provider's length limit, and making names safe for terraform.
+ *
+ * @group Utilities/String
  */
 export declare class StringUtility {
     /**
-     * Produces a short deterministic hash of a value, with object keys sorted recursively,
-     * so the hash does not change when key insertion order does.
+     * Shortens a name to at most `maxLength` characters, replacing what is cut with a digest of the whole
+     * name. Two names that differ anywhere still differ after shortening, and the same name always
+     * shortens the same way. A name already within the limit is returned as it is.
+     *
+     * Use it where a provider limits a name that is built by joining others, e.g. a distribution name and
+     * an origin id, so that cutting the tail alone could make two names collide.
+     *
+     * @example
+     * ```ts
+     * StringUtility.boundedName('my-distribution-with-a-very-long-origin-id', 20);
+     * // The first 11 characters, a dash and 8 hex characters: 20 in all.
+     * ```
+     */
+    static boundedName(name: string, maxLength: number): string;
+    /**
+     * Produces a 16-character hex hash of any value, with object keys sorted recursively, so the hash
+     * does not change when key insertion order does. Hash several parts as an array,
+     * `deterministicHash([bucketName, accessPrefix])`, which keeps `['ab', 'c']` and `['a', 'bc']` apart.
+     * Take a prefix of it where a shorter id is enough.
      */
     static deterministicHash(value: unknown): string;
     /**

package/dist/utilities/string/string.utility.js

@@ -1,11 +1,37 @@
 import { createHash } from 'node:crypto';
 /**
- * @internal
+ * String helpers for module and resource authors: hashing values into stable ids, fitting names into
+ * a provider's length limit, and making names safe for terraform.
+ *
+ * @group Utilities/String
  */
 export class StringUtility {
     /**
-     * Produces a short deterministic hash of a value, with object keys sorted recursively,
-     * so the hash does not change when key insertion order does.
+     * Shortens a name to at most `maxLength` characters, replacing what is cut with a digest of the whole
+     * name. Two names that differ anywhere still differ after shortening, and the same name always
+     * shortens the same way. A name already within the limit is returned as it is.
+     *
+     * Use it where a provider limits a name that is built by joining others, e.g. a distribution name and
+     * an origin id, so that cutting the tail alone could make two names collide.
+     *
+     * @example
+     * ```ts
+     * StringUtility.boundedName('my-distribution-with-a-very-long-origin-id', 20);
+     * // The first 11 characters, a dash and 8 hex characters: 20 in all.
+     * ```
+     */
+    static boundedName(name, maxLength) {
+        if (name.length <= maxLength) {
+            return name;
+        }
+        const digest = StringUtility.deterministicHash(name).substring(0, 8);
+        return `${name.substring(0, maxLength - digest.length - 1)}-${digest}`;
+    }
+    /**
+     * Produces a 16-character hex hash of any value, with object keys sorted recursively, so the hash
+     * does not change when key insertion order does. Hash several parts as an array,
+     * `deterministicHash([bucketName, accessPrefix])`, which keeps `['ab', 'c']` and `['a', 'bc']` apart.
+     * Take a prefix of it where a shorter id is enough.
      */
     static deterministicHash(value) {
         const stableStringify = (v) => {

package/dist/utilities/string/string.utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"string.utility.js","sourceRoot":"","sources":["../../../src/utilities/string/string.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACrC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAU,EAAE;YAC7C,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC3B,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YACjD,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9D,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAE,CAA6B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACxH,CAAC,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,8BAA8B,CAAC,KAAa;QACjD,OAAO,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,OAAO,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;CACF"}
+{"version":3,"file":"string.utility.js","sourceRoot":"","sources":["../../../src/utilities/string/string.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,WAAW,CAAC,IAAY,EAAE,SAAiB;QAChD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACrC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAU,EAAE;YAC7C,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC3B,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YACjD,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9D,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAE,CAA6B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACxH,CAAC,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,8BAA8B,CAAC,KAAa;QACjD,OAAO,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,OAAO,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/utilities/terraform/terraform.utility.d.ts

@@ -1,11 +1,8 @@
-import { type ExecFileOptionsWithStringEncoding } from 'node:child_process';
 import type { TerraformOutputs } from '../../modes/commit.mode.js';
 import type { TerraformPlan } from '../../modes/validate.mode.js';
 interface TerraformRawResult {
     readonly args: string[];
     readonly exitCode: number;
-    readonly stderr: string;
-    readonly stdout: string;
 }
 /**
  * The result of planning every module folder under a terragrunt directory.
@@ -39,6 +36,10 @@ interface TerraformPlanResult {
  * @group Utilities/Terraform
  */
 export declare class TerraformUtility {
+    /**
+     * The id of the last process any instance started, so ids never repeat within one octo process.
+     */
+    private static lastProcessId;
     private onceArgs;
     private readonly options;
     /**
@@ -47,35 +48,35 @@ export declare class TerraformUtility {
      */
     private readonly requestedTimeoutInMs;
     /**
-     * @param options Overrides for the binaries invoked and the per-command timeout. `terragruntBinary`
-     * defaults to `terragrunt`.
+     * @param options Overrides for the binaries invoked, the per-command timeout, and the state
+     * check-in interval. `terragruntBinary` defaults to `terragrunt`.
      *
      * `timeoutInMs` defaults to 60 minutes for the commands that only read - `plan`, `output`, `show`.
      * `apply` and `destroy` run unbounded unless it is given: a timeout there turns a slow apply into
      * one killed part way through a mutation, and how long a stack legitimately takes is a fact about
      * that stack rather than something a default can know. What bounds them instead is the caller -
      * a CI job's own timeout, or a person at a terminal.
+     *
+     * `stateCheckInIntervalInMs` is how often terraform state is checked into the state provider while
+     * a command runs, 10 seconds by default. Terraform rewrites it as each resource completes.
      */
     constructor(options?: {
+        stateCheckInIntervalInMs?: number;
         terraformBinary?: string;
         terragruntBinary?: string;
         timeoutInMs?: number;
     });
     /**
-     * Runs `terragrunt run-all apply` over every generated module folder.
+     * Runs `terragrunt run --all -- apply` over every generated module folder.
      *
      * **This changes real infrastructure**, and runs with `-auto-approve`. Use
      * {@link TerraformUtility.findPlannedDestroys} beforehand if a destroy needs confirming.
      *
-     * @param onOutput Called with each chunk terragrunt writes, as it writes it. An apply can run for
-     * tens of minutes, and the buffered result only arrives at the end - without this the caller has
-     * nothing to show for the whole run. The chunks are also still accumulated into the result.
+     * @param terragruntDir The directory octo generated the module folders into.
      */
-    apply(terragruntDir: string, { onOutput }?: {
-        onOutput?: (chunk: string, stream: 'stderr' | 'stdout') => void;
-    }): Promise<TerraformRawResult>;
+    apply(terragruntDir: string): Promise<TerraformRawResult>;
     /**
-     * Runs `terragrunt run-all destroy` over every generated module folder.
+     * Runs `terragrunt run --all -- destroy` over every generated module folder.
      *
      * **This tears down real infrastructure**, and runs with `-auto-approve`.
      */
@@ -100,8 +101,9 @@ export declare class TerraformUtility {
     /**
      * Reads the outputs of every generated module folder.
      *
+     * @param terragruntDir The directory octo generated the module folders into.
      * @param options Pass `{ json: true }` to get the outputs parsed and keyed by `moduleId`, which is
-     * the shape {@link Octo.commit} takes. Without it, terragrunt's raw output is returned.
+     * the shape {@link Octo.commit} takes. Without it, terragrunt's output goes out only as events.
      */
     output(terragruntDir: string, options: {
         json: true;
@@ -115,9 +117,10 @@ export declare class TerraformUtility {
     /**
      * Plans every generated module folder.
      *
+     * @param terragruntDir The directory octo generated the module folders into.
      * @param options Pass `{ json: true }` to get the plans parsed and keyed by `moduleId`, which is
      * the shape {@link Octo.validate} takes - along with the `errors` of any folder that could not be
-     * planned. Without it, terragrunt's raw output is returned.
+     * planned. Without it, terragrunt's output goes out only as events.
      */
     plan(terragruntDir: string, options: {
         json: true;
@@ -133,15 +136,21 @@ export declare class TerraformUtility {
      */
     setArgsOnce(args: string[]): this;
     /**
-     * Runs `terragrunt run-all validate` over every generated module folder, checking the generated
+     * Runs `terragrunt run --all -- validate` over every generated module folder, checking the generated
      * HCL is well-formed. Unrelated to {@link Octo.validate}, which compares plans against intent.
      */
     validate(terragruntDir: string): Promise<TerraformRawResult>;
     /**
-     * @param onOutput Receives each chunk as the child writes it. `execFile` keeps accumulating into
-     * its own buffers regardless, so the resolved result is unchanged whether or not this is passed.
+     * Runs `file` with `args`, handing each chunk it writes to `onChunk` as it arrives. Keeps its whole
+     * stdout only when `keepStdout` asks for it, and the last {@link STDERR_TAIL_LENGTH} characters of its
+     * stderr, so a process writing for an hour holds no more memory than one writing for a second.
      */
-    protected execFileAsync(file: string, args: string[], options: ExecFileOptionsWithStringEncoding, onOutput?: (chunk: string, stream: 'stderr' | 'stdout') => void): Promise<{
+    protected spawnAsync(file: string, args: string[], options: {
+        cwd?: string;
+        env: NodeJS.ProcessEnv;
+        keepStdout: boolean;
+        timeout?: number;
+    }, onChunk: (text: string, stream: 'stderr' | 'stdout') => void): Promise<{
         stderr: string;
         stdout: string;
     }>;
@@ -173,6 +182,15 @@ export declare class TerraformUtility {
      * The `terragrunt run --all` invocation itself, wrapped in its started/finished pair.
      */
     private invokeRunAll;
+    /**
+     * Moves the terraform state of every move the last generate recorded out of its old module folder
+     * into its new one, with `terraform state mv`, and copies the moved resources' outputs along, since
+     * folders depending on the new one read them there. An address the old folder's state does not hold,
+     * or the new one's already holds, is skipped, which is what a move already made leaves behind.
+     * Records in `originalStates` what each state file held before its first move, `undefined` where none
+     * existed.
+     */
+    private moveStates;
     /**
      * Runs `terragrunt output -json` in one module folder.
      *
@@ -191,6 +209,17 @@ export declare class TerraformUtility {
      * abort every other folder's result. The failure is carried so `validate` can report it verbatim.
      */
     private readPlan;
+    /**
+     * The directory with every symbolic link on its path resolved, or the directory as given when it does
+     * not exist. Terragrunt drops `dependency` blocks when its working directory is reached through a
+     * symbolic link, as macOS's temporary directory is.
+     */
+    private resolveRealPath;
+    /**
+     * Writes back what each state file held before {@link TerraformUtility.moveStates}, deleting one that
+     * did not exist.
+     */
+    private restoreStates;
     /**
      * Runs one terragrunt command in a single module folder (`cwd` = that folder).
      */
@@ -200,17 +229,37 @@ export declare class TerraformUtility {
      * the terraform state of every folder checked out around it.
      */
     private runAll;
+    /**
+     * Runs `binary` with `args` in `dir`. Its stdout is returned only when it is asked for JSON, which is
+     * the output octo reads; every other process's output goes out only as events.
+     */
+    private runIn;
+    /**
+     * Runs one process. Every terraform and terragrunt process octo starts goes through here, and goes out
+     * as events: a {@link TerraformProcessStartedEvent}, a {@link TerraformProcessOutputEvent} for each
+     * chunk it writes, and a {@link TerraformProcessExitedEvent}, all named after `command`.
+     *
+     * @throws {@link TerraformCommandError} When the process cannot start or exits non-zero.
+     */
+    private runProcess;
     /**
      * Wraps whatever a failed spawn threw into a {@link TerraformCommandError}.
      */
     private toTerraformCommandError;
     /**
-     * Checks every module folder's terraform state out of Octo's state provider, runs `body`, and
-     * checks it back in.
+     * Checks every module folder's terraform state out of Octo's state provider, moves the state of every
+     * resource generate moved between folders, runs `body`, and checks the state back in.
+     *
+     * Only a command that changes infrastructure (`keepMoves`) checks the moves in. Any other runs on them
+     * and puts back what the state files held before, so a move nobody applied never reaches the provider.
      *
      * The check-in runs on the way out of a failure as much as a success, because what terraform has
      * already built is real whether or not the command that built it returned cleanly. A timer checks
      * in through the command as well, bounding what a killed runner loses.
+     *
+     * A failed command keeps its own error when the check-in after it fails too; the check-in's error
+     * is printed on stderr. The folder's state is ahead of the provider's then, and the next run keeps
+     * it and checks it in.
      */
     private withTerraformState;
 }