@clossys/launcher 0.3.0 → 0.4.0

package/dist/apply-store.d.ts

@@ -0,0 +1,93 @@
+import type { ApplyBundle, RepositoryChangeSet } from "./change-set-contract.js";
+/** Where every repository change set this hub has computed is kept, one file per digest, relative to the hub root. */
+export declare const CHANGE_SET_STORE_REL = "clossys/.state/apply/change-sets";
+/** Where every apply bundle this hub has computed is kept, one file per digest, relative to the hub root. */
+export declare const BUNDLE_STORE_REL = "clossys/.state/apply/bundles";
+/**
+ * Stores `set` under `hubDirectory`/CHANGE_SET_STORE_REL, named for its own
+ * `changeSetDigest`. Throws a TypeError, naming no path, id or value, when
+ * the set does not validate against the change-set contract, when its
+ * `changeSetDigest` is not `changeSetDigest(set)`, or when that name is
+ * already taken by different bytes (the store is append-only). Storing the
+ * same set again, byte for byte, is a no-op; so is storing another document
+ * that validates to the same changeSetDigest. Returns the file's path.
+ */
+export declare function storeChangeSet(hubDirectory: string, set: RepositoryChangeSet): string;
+/** Thrown by bindChangeSetBody when the stored set is already bound to another body. Names no path, digest or hash. */
+export declare class BodyBoundError extends TypeError {
+    constructor();
+}
+/**
+ * Records `bodySha256`, the hash of the pull request body rendered for the
+ * change set stored under `digest` (issue #1716), as that set's
+ * `pullRequest.bodySha256` -- the one member it changes. The digest excludes
+ * that member, so the file's name and every digest stay as they were. The set
+ * is read here, from the store, and must verify exactly as readStoredChangeSet
+ * verifies it; a set that is not stored, or does not verify, is a TypeError.
+ * A set already bound to the same hash is a no-op that writes nothing; one
+ * bound to another hash throws BodyBoundError and is left as it was: a bound
+ * body is never rebound, and storeChangeSet never replaces a stored set, so it
+ * cannot unbind one either. The write replaces only that one file, atomically
+ * (a temporary file in the same directory, renamed over the name), and is
+ * refused when the file is not the bytes that were read, a symbolic link or not
+ * a regular file, or when a store directory segment is a symbolic link. Every
+ * error names no path, digest or hash, and no other file is touched. Returns
+ * the file's path.
+ *
+ * Two binds of one set are serialised by a per-digest lock (issue #1738): a
+ * dot-prefixed file in the change-sets directory, created exclusively before
+ * the set is first read and removed once this call is done, only by the call
+ * that created it. A bind that finds the lock already held throws a TypeError
+ * and changes nothing, so of two binds with different hashes exactly one
+ * renames; it never waits and never breaks a lock. A crash mid-bind leaves the
+ * lock, and later binds of that set then refuse (fails closed). A set removed
+ * after this call read it is refused rather than written again already bound.
+ */
+export declare function bindChangeSetBody(hubDirectory: string, digest: string, bodySha256: string): string;
+/**
+ * Stores `bundle` under `hubDirectory`/BUNDLE_STORE_REL, named for its own
+ * `bundleDigest`. Throws a TypeError, naming no path, id or value, when the
+ * bundle does not validate against the apply-bundle contract, when the
+ * digest is malformed, or when a store directory segment or the file name is
+ * a symbolic link; nothing is written or replaced in those cases. The digest
+ * excludes the authorization, the clock, the mode and the verdicts (RFC
+ * 12.3), so a bundle whose digest already names a stored file replaces that
+ * one file atomically with these bytes, the newest computation; the same
+ * bytes again are a no-op. A report bundle never replaces a stored file that
+ * verifies as a planned bundle of this digest (a TypeError, naming no path);
+ * a planned bundle replaces anything. A bundle with any other digest never
+ * touches another file. Superseded computations are not recorded. Returns the
+ * file's path.
+ */
+export declare function storeApplyBundle(hubDirectory: string, bundle: ApplyBundle): string;
+/**
+ * Reads the change set stored for `digest` under `hubDirectory`/CHANGE_SET_STORE_REL.
+ * `digest` must match `sha256:` and 64 lowercase hex digits before any path
+ * is built from it; a malformed digest throws a TypeError naming no value,
+ * before touching the filesystem. Otherwise: a missing file, bytes that are
+ * not strict JSON, a document that does not validate against the change-set
+ * contract, or one whose `changeSetDigest` -- recomputed and read from the
+ * document -- does not equal both `digest` and the document's own
+ * `changeSetDigest`, all read as `null`. A file can therefore never be read
+ * back under a name, or with content, other than its own digest.
+ */
+/**
+ * Every change set stored under `hubDirectory`/CHANGE_SET_STORE_REL whose file
+ * name is 64 lowercase hex digits and `.json`, in directory listing order.
+ * Entries that do not read back as a valid stored set are omitted.
+ */
+export declare function listStoredChangeSets(hubDirectory: string): RepositoryChangeSet[];
+export declare function readStoredChangeSet(hubDirectory: string, digest: string): RepositoryChangeSet | null;
+/**
+ * Reads the apply bundle stored for `digest` under `hubDirectory`/BUNDLE_STORE_REL.
+ * `digest` must match `sha256:` and 64 lowercase hex digits before any path
+ * is built from it; a malformed digest throws a TypeError naming no value,
+ * before touching the filesystem. Otherwise: a missing file, bytes that are
+ * not strict JSON, a document that does not validate against the
+ * apply-bundle contract, or one whose bundle digest -- recomputed from its
+ * `plan.digest` and each repository that carries a change set, in the same
+ * order applyBundleRuleViolations' A2 rule computes it -- does not equal
+ * both `digest` and the document's own `bundleDigest`, all read as `null`.
+ */
+export declare function readStoredApplyBundle(hubDirectory: string, digest: string): ApplyBundle | null;
+//# sourceMappingURL=apply-store.d.ts.map

package/dist/apply-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-store.d.ts","sourceRoot":"","sources":["../src/apply-store.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EAAE,WAAW,EAAyB,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGxG,sHAAsH;AACtH,eAAO,MAAM,oBAAoB,qCAAqC,CAAC;AAEvE,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AA4R/D;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAarF;AAED,uHAAuH;AACvH,qBAAa,cAAe,SAAQ,SAAS;;CAI5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA+BlG;AAwCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAMlF;AAwBD;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAWhF;AAED,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CASpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAK9F"}