@quadnix/octo 0.0.30 → 0.2.0

package/dist/services/state-management/local.state-provider.js

@@ -1,35 +1,42 @@
-import { readFile, writeFile } from 'fs/promises';
-import { join, resolve } from 'path';
-import { TransactionError } from '../../errors/index.js';
+import { randomUUID } from 'crypto';
+import { copyFile, readFile, readdir, rm, writeFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { AppLockError, TransactionError } from '../../errors/index.js';
+import { FileUtility } from '../../utilities/file/file.utility.js';
 /**
+ * Keeps state in a directory on the local filesystem.
+ *
+ * Good for experimenting on your own machine. It is not shared, so a team running Octo against the
+ * same infrastructure needs a provider that persists somewhere they all reach.
+ *
+ * @example
+ * ```ts
+ * await octo.initialize(new LocalStateProvider('./infrastructure'));
+ * ```
+ *
  * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
  */
 export class LocalStateProvider {
+    /**
+     * @param localStateDirectoryPath The directory state files are written into.
+     */
     constructor(localStateDirectoryPath) {
         this.localStateDirectoryPath = resolve(localStateDirectoryPath);
-        this.lockFilePath = resolve(join(localStateDirectoryPath, 'local-state.lock'));
-    }
-    async addOrUpdateAppLock(lockId) {
-        await writeFile(this.lockFilePath, lockId);
+        this.lockFilePath = join(this.localStateDirectoryPath, 'local-state.lock');
     }
+    /**
+     * The id of the lock currently held, or `undefined` when the app is unlocked.
+     */
     async getAppLock() {
-        try {
-            const contents = await readFile(this.lockFilePath, 'utf-8');
-            const appLock = contents.replace(/\s/g, '');
-            if (!appLock) {
-                return undefined;
-            }
-            return appLock;
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return undefined;
-            }
-            else {
-                throw error;
-            }
-        }
+        return (await this.readLock())?.lockId;
     }
+    /**
+     * Reads a state file.
+     *
+     * @throws {@link TransactionError} With the message `No state found!` when the file does not exist.
+     */
     async getState(stateFileName) {
         try {
             return await readFile(join(this.localStateDirectoryPath, stateFileName));
@@ -41,44 +48,164 @@ export class LocalStateProvider {
             throw error;
         }
     }
+    /**
+     * 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) {
         const existingLockId = await this.getAppLock();
         if (!existingLockId) {
             return false;
         }
-        if (lockId !== existingLockId) {
+        if (existingLockId !== lockId) {
             throw new TransactionError('Invalid lock ID!');
         }
-        else {
-            return true;
+        return true;
+    }
+    /**
+     * The names of the state files whose name starts with `prefix`.
+     */
+    async listStates(prefix) {
+        let entries;
+        try {
+            entries = await readdir(this.localStateDirectoryPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
         }
+        return entries.filter((entry) => entry.startsWith(prefix));
     }
-    async lockApp() {
-        const existingLockId = await this.getAppLock();
-        if (existingLockId) {
-            throw new TransactionError('App already locked!');
+    /**
+     * Takes the app lock, writing its id and the time it was taken into `local-state.lock` beside the
+     * state files. With `lockId`, resumes the run already holding it. The lock never expires.
+     *
+     * @throws {@link AppLockError} When a lock is held, naming the id that holds it and how long it has
+     * been held. When `lockId` is given and is not the lock held.
+     */
+    async lockApp(lockId) {
+        await FileUtility.ensureDirectory(this.localStateDirectoryPath);
+        // Resume the run holding the lock, which on one machine holds nothing more to read.
+        if (lockId) {
+            if ((await this.getAppLock()) !== lockId) {
+                throw new AppLockError(`App is not locked with lock ID "${lockId}"!`, { reason: 'not-held' });
+            }
+            return { lockId };
+        }
+        // Take the lock with an exclusive create, so of two runs racing for it exactly one wins.
+        const newLockId = randomUUID();
+        const record = { lockId: newLockId, startedAt: Date.now() };
+        try {
+            await writeFile(this.lockFilePath, JSON.stringify(record), { flag: 'wx' });
         }
-        const lockId = crypto.randomUUID();
-        await this.addOrUpdateAppLock(lockId);
-        return { lockId };
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                const holder = await this.readLock();
+                const heldFor = holder?.startedAt === undefined ? undefined : this.describeAge(holder.startedAt);
+                throw new AppLockError(`App already locked with lock ID "${holder?.lockId}"${heldFor ? `, held for ${heldFor}` : ''}!`, {
+                    holder: holder ? { lockId: holder.lockId, takenAt: holder.startedAt } : undefined,
+                    reason: 'held',
+                });
+            }
+            throw error;
+        }
+        return { lockId: newLockId };
+    }
+    /**
+     * Does nothing: the directory is the only copy of the state, so it is always the newest.
+     */
+    async refreshState() {
+        return { replaced: false };
     }
-    async saveState(stateFileName, data) {
-        await writeFile(join(this.localStateDirectoryPath, stateFileName), data);
+    /**
+     * Writes state files, overwriting whatever was there, copying each one given a `filePath`, and
+     * deleting each one given no `data`. A name holding `/` is written into a directory beneath the state
+     * directory.
+     */
+    async saveStates(stateFiles) {
+        for (const stateFile of stateFiles) {
+            const stateFilePath = join(this.localStateDirectoryPath, stateFile.stateFileName);
+            if ('filePath' in stateFile) {
+                await FileUtility.ensureDirectory(dirname(stateFilePath));
+                await copyFile(stateFile.filePath, stateFilePath);
+            }
+            else if (stateFile.data === undefined) {
+                await rm(stateFilePath, { force: true });
+            }
+            else {
+                await FileUtility.ensureDirectory(dirname(stateFilePath));
+                await writeFile(stateFilePath, stateFile.data);
+            }
+        }
     }
+    /**
+     * Releases the app lock by deleting the lock file.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     */
     async unlockApp(lockId) {
         const existingLockId = await this.getAppLock();
         if (!existingLockId) {
             return;
         }
-        if (lockId !== existingLockId) {
+        if (existingLockId !== lockId) {
             throw new TransactionError('Invalid lock ID!');
         }
-        await this.addOrUpdateAppLock('');
+        await rm(this.lockFilePath, { force: true });
     }
-    async updateAppLockTransaction(lockId) {
-        const isAppLocked = await this.isAppLocked(lockId);
-        if (!isAppLocked) {
-            throw new TransactionError('App is unlocked!');
+    /**
+     * How long the lock has been held, as a short readable span. Undefined when the recorded time
+     * cannot be read as one, so a broken value is left out rather than reported as a negative age.
+     */
+    describeAge(startedAt) {
+        const heldForMs = Date.now() - startedAt;
+        if (!Number.isFinite(heldForMs) || heldForMs < 0) {
+            return undefined;
+        }
+        const seconds = Math.floor(heldForMs / 1000);
+        if (seconds < 60) {
+            return `${seconds}s`;
+        }
+        const minutes = Math.floor(seconds / 60);
+        if (minutes < 60) {
+            return `${minutes}m`;
+        }
+        const hours = Math.floor(minutes / 60);
+        if (hours < 24) {
+            return `${hours}h ${minutes % 60}m`;
+        }
+        return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+    }
+    /**
+     * The lock file's record, or undefined when no lock is held. A file holding an id and nothing else
+     * is a lock taken before the record carried a time, and reads as that id with no age.
+     */
+    async readLock() {
+        let contents;
+        try {
+            contents = (await readFile(this.lockFilePath, 'utf-8')).trim();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        }
+        if (!contents) {
+            return undefined;
+        }
+        if (!contents.startsWith('{')) {
+            return { lockId: contents };
+        }
+        try {
+            const record = JSON.parse(contents);
+            return typeof record.lockId === 'string' ? record : { lockId: contents };
+        }
+        catch (error) {
+            return { lockId: contents };
         }
     }
 }

package/dist/services/state-management/local.state-provider.js.map

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

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

@@ -0,0 +1,216 @@
+import { type IStateProvider } from './state-provider.interface.js';
+/**
+ * Keeps state in Octo's managed backend, so a team shares one store and no machine holds the only copy.
+ *
+ * A run reads and writes a state directory on disk, exactly as {@link LocalStateProvider} does, and
+ * the backend is kept in step with it:
+ *
+ * - {@link RemoteStateProvider.refreshState} brings the directory up to the newest sealed state, and
+ *   is what `octo generate` plans against.
+ * - {@link RemoteStateProvider.lockApp} opens a new record for the run, refusing when the newest
+ *   sealed state has moved since the directory was refreshed.
+ * - Every write under the lock lands in the directory and in the run's record before it returns, so
+ *   a run that dies leaves a record somebody can finish from another machine.
+ * - {@link RemoteStateProvider.unlockApp} seals the record and releases the lock.
+ *
+ * Two files of the provider's own sit beside the state files and are never uploaded:
+ * `remote-state.lock` records the run the directory belongs to and is deleted when the lock is
+ * released, and `remote-state-upload.lock` makes the octo processes of one machine write to the
+ * backend one at a time and is deleted after every write.
+ *
+ * @example
+ * ```ts
+ * await octo.initialize(
+ *   new RemoteStateProvider({
+ *     appId: 'my-app',
+ *     localStateDirectoryPath: './.octo',
+ *     organizationId: 'my-organization',
+ *     sessionId: process.env.OCTO_SESSION!,
+ *     stateManagementServiceUrl: 'http://localhost:3619/state',
+ *   }),
+ * );
+ * ```
+ *
+ * @group Services/State Management
+ *
+ * @see Techniques for [State Providers](/docs/techniques/state-providers).
+ */
+export declare class RemoteStateProvider implements IStateProvider {
+    private readonly appId;
+    private readonly localStateDirectoryPath;
+    private readonly localStateProvider;
+    private readonly lockContext;
+    private readonly organizationId;
+    private readonly sessionId;
+    private readonly stateManagementServiceUrl;
+    /**
+     * @param options `organizationId` and `appId` name the app whose state this is, and `sessionId`
+     * is the session the run acts as. `stateManagementServiceUrl` is the backend service, including
+     * the prefix its routes sit behind. `localStateDirectoryPath` is the directory state files are
+     * written into. `lockContext` is what a blocked run is shown about the holder.
+     */
+    constructor(options: {
+        appId: string;
+        localStateDirectoryPath: string;
+        lockContext?: string;
+        organizationId: string;
+        sessionId: string;
+        stateManagementServiceUrl: string;
+    });
+    /**
+     * 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.
+     */
+    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,
+     * and when `lockId` is held but was neither taken nor resumed in this state directory.
+     */
+    isAppLocked(lockId: string): Promise<boolean>;
+    /**
+     * The names of the state files whose name starts with `prefix`.
+     */
+    listStates(prefix: string): Promise<string[]>;
+    /**
+     * Takes the app lock and opens the run's record with everything the state directory holds.
+     *
+     * With `lockId`, resumes the run already holding that lock instead - from any machine, as the
+     * account that took it or an organization administrator. The state directory is replaced with
+     * what that run wrote so far, its journal included, keeping this machine's journal files, which join
+     * the record, and every write after lands in its record. A run that wrote nothing is resumed from the
+     * newest sealed state, without that state's journal.
+     *
+     * @throws {@link AppLockError} When a lock is held, naming the id that holds it. When the newest
+     * sealed state moved since {@link RemoteStateProvider.refreshState} last ran. When `lockId` is
+     * given and is not held.
+     */
+    lockApp(lockId?: string): ReturnType<IStateProvider['lockApp']>;
+    /**
+     * Brings the state directory up to the newest sealed state, which is what a run plans against.
+     *
+     * A directory an open run is still writing is left alone. A directory the backend holds nothing
+     * for is left alone too: that is a first run, or a project arriving from another provider, and the
+     * files on disk are the only copy there is. Journal files are neither replaced nor taken.
+     */
+    refreshState(): Promise<{
+        commitId?: string;
+        previousCommitId?: string;
+        replaced: boolean;
+    }>;
+    /**
+     * Writes state files, deleting each one given no `data`, and then writes the run's record once for
+     * all of them when a run is open. A name holding `/` is the machine's own: it is written beneath
+     * the state directory and never reaches the record.
+     *
+     * @throws {@link TransactionError} When the backend would refuse a file's name, before anything is
+     * written. When the backend refuses the write, which is where the limits it holds the app to apply.
+     */
+    saveStates(stateFiles: Parameters<IStateProvider['saveStates']>[0]): Promise<void>;
+    /**
+     * Writes the directory into the run's record, seals it, and releases the app lock. Unlocking an app
+     * that is not locked is not an error.
+     *
+     * A write that failed earlier left the directory ahead of the record, so the record is written once
+     * more before it is sealed: a sealed record is what every machine plans against next.
+     *
+     * @throws {@link TransactionError} With the message `Invalid lock ID!` when a different lock is held.
+     * When the directory cannot be written into the record, keeping the lock held.
+     */
+    unlockApp(lockId: string): Promise<void>;
+    /**
+     * The route this app's state and locks are read and written at.
+     */
+    private appStateUrl;
+    /**
+     * The session this run acts as. Every route but the health check is behind it.
+     */
+    private authorizationHeader;
+    /**
+     * Deletes the lock file. Deleting one that is not there is not an error.
+     */
+    private deleteLockFile;
+    /**
+     * How long the lock has been held, as a short readable span. Undefined when the recorded time
+     * cannot be read as one, so a broken value is left out rather than reported as a negative age.
+     */
+    private describeAge;
+    /**
+     * Writes the directory into the run's record, when this directory belongs to an open run.
+     */
+    private pushRun;
+    /**
+     * Every lock the backend holds on this app, oldest first.
+     */
+    private readAppLocks;
+    /**
+     * The lock file. Empty when there is none.
+     */
+    private readLockFile;
+    /**
+     * The newest record the app holds, sealed or not, or `undefined` when it holds none.
+     *
+     * One run holds the whole app at a time, so records are opened in the order they are sealed.
+     */
+    private readNewestState;
+    /**
+     * Releases a lock, sealing the record its commit names. False when the lock is not held.
+     */
+    private releaseAppLock;
+    /**
+     * Replaces every state file in the directory with the ones a state body names, downloading each
+     * from its URL and checking it against its SHA-256, and returns the body. The directory's journal
+     * files are kept; with `takeJournal`, the body's are written beside them.
+     *
+     * Each file is streamed to a temporary file beside it, so a state is not bounded by memory.
+     */
+    private replaceStateFiles;
+    /**
+     * Resumes the run holding `lockId` in this state directory.
+     */
+    private resumeAppLock;
+    /**
+     * Every state file the directory holds, which is every file in it but the provider's two lock
+     * files and a write still in progress, and none of the directories a run writes beside them, such
+     * as a generated terragrunt folder.
+     */
+    private stateFileNames;
+    /**
+     * Runs `body` while holding `remote-state-upload.lock`, so one write to the backend is in flight at
+     * a time across every octo process on this machine. The file is deleted when `body` returns, and
+     * one left by a process that is gone is taken over.
+     */
+    private withUploadLock;
+    /**
+     * Writes the lock file.
+     */
+    private writeLockFile;
+    /**
+     * Writes the directory into the run's record as it stands, and returns the SHA-256 of every file the
+     * record holds afterwards.
+     *
+     * A write is three requests: the upload is asked for naming every file and its digest, the files
+     * the backend does not already hold are PUT to the URLs it answered with, and the upload is
+     * claimed. A file that fails to upload stops the write before the claim, and a claim with a file
+     * missing is refused, so a write lands whole or not at all. An upload left unclaimed is thrown away by
+     * the backend at the next write or when the lock is released. A directory holding nothing writes
+     * nothing, since the backend holds no empty state.
+     *
+     * The files are hard linked into a snapshot directory first and streamed from there, so a state is
+     * not bounded by memory, and a file another process replaces meanwhile is uploaded as it was
+     * hashed: a write replaces a file by renaming over it, which leaves the linked one as it was.
+     */
+    private writeRunState;
+    /**
+     * Writes one file into the state directory whole, from `data` or copied from `filePath`, so a process
+     * reading it never reads half of it. Replacing the file rather than writing into it is also what lets
+     * an upload freeze it with a hard link.
+     */
+    private writeStateFile;
+}