@quadnix/octo 0.1.0 → 0.2.0

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;
+}