@intentius/chant-lexicon-terraform 0.124.52 → 0.124.54

package/dist/state/gcs.js

@@ -0,0 +1,224 @@
+/**
+ * Google Cloud Storage for a gcs backend's state, over its JSON API with
+ * `fetch` and `node:crypto`: an object's text and generation, a write, a
+ * write only when there is no object (the lock), and a delete.
+ *
+ * The identity, first match wins: a bearer token (`access_token`, or
+ * GOOGLE_OAUTH_ACCESS_TOKEN), else a credentials file or its JSON:
+ *
+ *   external_account  the job's OIDC token, traded at Google's STS, then the
+ *                     service account it impersonates.
+ *   service_account   a key: requests carry a self-signed JWT.
+ *
+ * With `impersonate_service_account`, every request carries that service
+ * account's token, which the identity asks IAM for.
+ *
+ * Lifted from terragucci's `report/gcs.ts` (c493e0e), without signed URLs,
+ * version listing and the re-plan's traded tokens.
+ */
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { defaultFetch, encodeStrict, StoreConflict, StoreError } from "./object-store.js";
+export const GCS_ENDPOINT = "https://storage.googleapis.com";
+/** IAM Credentials, where a token for an impersonated service account comes from. */
+export const IAM_CREDENTIALS = "https://iamcredentials.googleapis.com";
+const CLOUD_PLATFORM = "https://www.googleapis.com/auth/cloud-platform";
+const READ_WRITE = "https://www.googleapis.com/auth/devstorage.read_write";
+const b64url = (b) => Buffer.from(b).toString("base64url");
+/** A JWT the key signs for itself, which Google's APIs take as an access token for the scope it names. */
+export function selfSignedJwt(key, now) {
+    const iat = Math.floor(now.getTime() / 1000);
+    const head = b64url(JSON.stringify({ alg: "RS256", typ: "JWT", ...(key.private_key_id ? { kid: key.private_key_id } : {}) }));
+    const body = b64url(JSON.stringify({ iss: key.client_email, sub: key.client_email, scope: READ_WRITE, iat, exp: iat + 3600 }));
+    return `${head}.${body}.${createSign("RSA-SHA256").update(`${head}.${body}`).sign(key.private_key).toString("base64url")}`;
+}
+/** Google's error message, or the start of the body. */
+const why = (text) => {
+    try {
+        const j = JSON.parse(text);
+        if (typeof j.error === "object" && j.error?.message)
+            return j.error.message;
+        if (typeof j.error === "string")
+            return [j.error, j.error_description].filter(Boolean).join(": ");
+    }
+    catch {
+        // Not JSON.
+    }
+    return text.slice(0, 300);
+};
+export class GcsClient {
+    constructor(target, fetchFn = defaultFetch, readFile = (f) => readFileSync(f, "utf-8")) {
+        this.target = target;
+        this.fetchFn = fetchFn;
+        this.readFile = readFile;
+    }
+    where(key) {
+        return `gs://${this.target.bucket}/${key}`;
+    }
+    credentials() {
+        if (this.creds)
+            return this.creds;
+        const source = this.target.credentialsFile ?? "the backend's credentials";
+        let c;
+        try {
+            c = JSON.parse(this.target.credentialsJson ?? this.readFile(this.target.credentialsFile ?? ""));
+        }
+        catch (e) {
+            throw new StoreError(`cannot read the credentials in ${source}: ${e.message}`);
+        }
+        if (c.type === "external_account" && c.token_url && c.audience && c.credential_source && (c.credential_source.file || c.credential_source.url))
+            return (this.creds = c);
+        if (c.type === "service_account" && c.client_email && c.private_key)
+            return (this.creds = c);
+        throw new StoreError(`${source} is not an external_account file with a credential_source file or url, nor a service_account key`);
+    }
+    async post(url, headers, body, what) {
+        const res = await this.fetchFn(url, { method: "POST", headers, body });
+        const text = await res.text();
+        if (!res.ok)
+            throw new StoreError(`${what}: ${res.status} ${why(text)}`);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new StoreError(`${what}: the answer is not JSON`);
+        }
+    }
+    /** The job's OIDC token, from the file or URL the credentials name. */
+    async subjectToken(c) {
+        const src = c.credential_source;
+        let text;
+        if (src.file) {
+            try {
+                text = this.readFile(src.file);
+            }
+            catch (e) {
+                throw new StoreError(`cannot read the OIDC token in ${src.file}: ${e.message}`);
+            }
+        }
+        else {
+            const res = await this.fetchFn(src.url, { method: "GET", headers: src.headers ?? {} });
+            text = await res.text();
+            if (!res.ok)
+                throw new StoreError(`the OIDC token at ${src.url.split("?")[0]}: ${res.status} ${why(text)}`);
+        }
+        const field = src.format?.type === "json" ? src.format.subject_token_field_name : undefined;
+        let token = text.trim();
+        if (field) {
+            try {
+                token = String(JSON.parse(text)[field] ?? "");
+            }
+            catch {
+                throw new StoreError(`the job's OIDC token is not JSON with ${field}`);
+            }
+        }
+        if (!token)
+            throw new StoreError("the job's OIDC token is empty");
+        return token;
+    }
+    async impersonateWith(url, bearer, sa) {
+        const r = await this.post(url, { "content-type": "application/json", authorization: `Bearer ${bearer}` }, JSON.stringify({ scope: [CLOUD_PLATFORM], lifetime: "3600s" }), `impersonating ${sa}`);
+        if (typeof r.accessToken !== "string")
+            throw new StoreError(`IAM answered the impersonation of ${sa} without a token`);
+        const at = typeof r.expireTime === "string" ? Date.parse(r.expireTime) : NaN;
+        return { token: r.accessToken, expires: Number.isNaN(at) ? Date.now() + 3600000 : at };
+    }
+    /** STS's federated token, then the impersonated service account's, when the credentials name one. */
+    async exchange(c) {
+        const sts = await this.post(c.token_url, { "content-type": "application/x-www-form-urlencoded" }, new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+            audience: c.audience,
+            scope: CLOUD_PLATFORM,
+            requested_token_type: "urn:ietf:params:oauth:token-type:access_token",
+            subject_token: await this.subjectToken(c),
+            subject_token_type: c.subject_token_type,
+        }).toString(), `Google STS refused the OIDC token for ${c.audience}`);
+        if (typeof sts.access_token !== "string")
+            throw new StoreError("Google STS answered without a token");
+        const fed = { token: sts.access_token, expires: Date.now() + Number(sts.expires_in ?? 3600) * 1000 };
+        if (!c.service_account_impersonation_url)
+            return fed;
+        return this.impersonateWith(c.service_account_impersonation_url, fed.token, "the service account");
+    }
+    /** The identity's own token: the one the target gives, a key's self-signed JWT, or STS's for the OIDC token. */
+    async own() {
+        if (this.target.accessToken)
+            return { token: this.target.accessToken, expires: Date.now() + 3600000 };
+        const c = this.credentials();
+        return c.type === "service_account" ? { token: selfSignedJwt(c, new Date()), expires: Date.now() + 3600000 } : this.exchange(c);
+    }
+    /** An access token: once per client, again a minute before it expires. */
+    async bearer() {
+        const sa = this.target.impersonate;
+        const fresh = async () => {
+            if (!sa)
+                return this.own();
+            const base = await this.own();
+            return this.impersonateWith(`${(this.target.iamEndpoint ?? IAM_CREDENTIALS).replace(/\/+$/, "")}/v1/projects/-/serviceAccounts/${encodeURIComponent(sa)}:generateAccessToken`, base.token, sa);
+        };
+        const again = () => (this.token = fresh().catch((e) => {
+            this.token = undefined;
+            throw e;
+        }));
+        let held = await (this.token ?? again());
+        if (held.expires - Date.now() < 60000)
+            held = await again();
+        return held.token;
+    }
+    objectUrl(key) {
+        return `${this.target.endpoint}/storage/v1/b/${encodeURIComponent(this.target.bucket)}/o/${encodeStrict(key)}`;
+    }
+    /** Write an object; with `ifGenerationMatch`, only when the object still has that generation (`0`: there is none), else StoreConflict. */
+    async put(key, body, contentType, ifGenerationMatch) {
+        const t = this.target;
+        const url = `${t.endpoint}/upload/storage/v1/b/${encodeURIComponent(t.bucket)}/o?uploadType=media&name=${encodeStrict(key)}${ifGenerationMatch !== undefined ? `&ifGenerationMatch=${encodeStrict(ifGenerationMatch)}` : ""}`;
+        const res = await this.fetchFn(url, { method: "POST", headers: { "content-type": contentType, authorization: `Bearer ${await this.bearer()}` }, body });
+        if (res.status === 412)
+            throw new StoreConflict(`PUT ${this.where(key)}: 412, it changed since it was read`);
+        if (!res.ok)
+            throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    }
+    async get(key) {
+        const res = await this.fetchFn(`${this.objectUrl(key)}?alt=media`, { method: "GET", headers: { authorization: `Bearer ${await this.bearer()}` } });
+        if (res.status === 404)
+            return undefined;
+        if (!res.ok)
+            throw new StoreError(`GET ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+        return res.text();
+    }
+    /** An object's metadata and never its body: whether it is there, and its generation. */
+    async head(key) {
+        const res = await this.fetchFn(this.objectUrl(key), { method: "GET", headers: { authorization: `Bearer ${await this.bearer()}` } });
+        const text = await res.text();
+        if (res.status === 404)
+            return { exists: false };
+        if (!res.ok)
+            throw new StoreError(`GET ${this.where(key)} metadata: ${res.status} ${why(text)}`);
+        let g;
+        try {
+            g = JSON.parse(text).generation;
+        }
+        catch {
+            // Metadata that is not JSON: no generation.
+        }
+        return { exists: true, ...(g !== undefined && g !== null && g !== "" ? { generation: String(g) } : {}) };
+    }
+    /** Write an object only when there is none (ifGenerationMatch=0): true when this write made it, false when one was there. */
+    async putIfAbsent(key, body, contentType) {
+        try {
+            await this.put(key, body, contentType, "0");
+            return true;
+        }
+        catch (e) {
+            if (e instanceof StoreConflict)
+                return false;
+            throw e;
+        }
+    }
+    /** Delete an object's live generation. One that is not there is deleted already. */
+    async remove(key) {
+        const res = await this.fetchFn(this.objectUrl(key), { method: "DELETE", headers: { authorization: `Bearer ${await this.bearer()}` } });
+        if (!res.ok && res.status !== 404)
+            throw new StoreError(`DELETE ${this.where(key)}: ${res.status} ${why(await res.text())}`);
+    }
+}

package/dist/state/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A root's state for a composed run (#4437): where it is, its lock, its pull
+ * and its write, and the unwritten keep. Plain lexicon code, lifted from
+ * terragucci at c493e0e.
+ */
+export * from "./object-store.js";
+export * from "./backend.js";
+export * from "./store.js";
+export * from "./exec.js";
+export * from "./locks.js";
+export * from "./root-states.js";
+export { S3Client, s3FromEnv, type S3Target } from "./s3.js";
+export { GcsClient, type GcsTarget } from "./gcs.js";
+export { AzureBlobClient, type AzureTarget } from "./azure-blob.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,14 @@
+/**
+ * A root's state for a composed run (#4437): where it is, its lock, its pull
+ * and its write, and the unwritten keep. Plain lexicon code, lifted from
+ * terragucci at c493e0e.
+ */
+export * from "./object-store.js";
+export * from "./backend.js";
+export * from "./store.js";
+export * from "./exec.js";
+export * from "./locks.js";
+export * from "./root-states.js";
+export { S3Client, s3FromEnv } from "./s3.js";
+export { GcsClient } from "./gcs.js";
+export { AzureBlobClient } from "./azure-blob.js";

package/dist/state/locks.d.ts

@@ -0,0 +1,105 @@
+import type { LockHolder, StateStore } from "./store.js";
+/** What a lock says holds it: the operation and a line of info, as the binary prints them when it finds the lock held. */
+export interface LockOperation {
+    operation: string;
+    info: string;
+}
+/** The lock info a run writes, in the shape the binary writes and prints when it finds a lock held. */
+export declare function lockInfo(path: string, now: string, op: LockOperation, who?: string): string;
+/** Who holds a lock, from the lock info it left: what is there of it. */
+export interface LockHolderInfo {
+    id: string;
+    who?: string;
+    operation?: string;
+    info?: string;
+    created?: string;
+}
+/** The holder a lock info names. */
+export declare function holderOf(held: LockHolder): LockHolderInfo;
+/** A lock held by another run stopped the take; nothing was pulled. */
+export declare class StateLockedError extends Error {
+    readonly root: string;
+    readonly lockLocation: string;
+    readonly holder?: LockHolderInfo | undefined;
+    constructor(root: string, lockLocation: string, holder?: LockHolderInfo | undefined);
+}
+/** What taking a lock needs of a store: a caller with a store of its own (terragucci's, which also reads versions) passes that. */
+export type LockStore = Pick<StateStore, "location" | "lockLocation" | "heldLock" | "lock" | "unlock" | "adopt">;
+/** A lock taken, on one root's state. */
+export interface HeldLock<S extends LockStore = StateStore> {
+    root: string;
+    store: S;
+    /** The lock was another run's, kept on purpose with a state it could not write, and this take took it over. */
+    adopted: boolean;
+    release: () => Promise<void>;
+}
+/**
+ * Take the lock of each state, in the order given. Releases what it took and
+ * throws StateLockedError when one is held and `adopt` does not take it over.
+ * `adopt` sees a held lock and says whether this take takes it over (a lock
+ * an earlier run of the same operation left held on purpose).
+ */
+export declare function takeLocks<S extends LockStore = StateStore>(stores: readonly {
+    root: string;
+    store: S;
+}[], now: string, op: LockOperation, adopt?: (root: string, store: S, held: LockHolder) => Promise<boolean>, who?: string): Promise<HeldLock<S>[]>;
+/**
+ * The lock of a workspace a state is read from, taken through the
+ * workspace's own API (Terraform Cloud's `actions/lock`), not a lock object
+ * beside a state. `lock` takes it with a reason the workspace shows, and
+ * returns its release; it throws when another run holds it.
+ */
+export interface SourceLock {
+    root: string;
+    /** The workspace, for messages. */
+    location: string;
+    lock(reason: string): Promise<() => Promise<void>>;
+}
+/** A source workspace's lock, taken. */
+export interface HeldSourceLock {
+    root: string;
+    location: string;
+    release: () => Promise<void>;
+}
+/** A source workspace's lock could not be taken: another run holds it, or the API refused. Nothing was read. */
+export declare class SourceLockedError extends Error {
+    readonly root: string;
+    readonly location: string;
+    readonly reason: string;
+    constructor(root: string, location: string, reason: string);
+}
+/** The reason a source workspace's lock shows: the operation and its info, as a state lock's info names them. */
+export declare const sourceLockReason: (op: LockOperation) => string;
+/**
+ * Take each source workspace's lock, in the order given, so no run writes a
+ * state while it is read. Releases what it took and throws SourceLockedError
+ * when one cannot be taken.
+ */
+export declare function takeSourceLocks(sources: readonly SourceLock[], op: LockOperation): Promise<HeldSourceLock[]>;
+export interface LocksWithSourcesInput<S extends LockStore> {
+    /** The workspaces states are read from, locked first. */
+    sources: readonly SourceLock[];
+    /** The states written, locked after the sources, in the order given. */
+    stores: readonly {
+        root: string;
+        store: S;
+    }[];
+    now: string;
+    /** What the state locks name. */
+    op: LockOperation;
+    /** What a source workspace's lock names; default `op`. A run that only reads the source says so here. */
+    sourceOp?: LockOperation;
+    adopt?: (root: string, store: S, held: LockHolder) => Promise<boolean>;
+    who?: string;
+}
+/**
+ * Every lock a run that reads from source workspaces and writes states
+ * holds: the source workspaces' first, then the states'. When any cannot be
+ * taken, every lock taken so far is released, and the error is
+ * SourceLockedError or StateLockedError.
+ */
+export declare function takeLocksWithSources<S extends LockStore = StateStore>(input: LocksWithSourcesInput<S>): Promise<{
+    sources: HeldSourceLock[];
+    locks: HeldLock<S>[];
+}>;
+//# sourceMappingURL=locks.d.ts.map

package/dist/state/locks.d.ts.map

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

package/dist/state/locks.js

@@ -0,0 +1,130 @@
+/**
+ * Taking a set of state locks in one order, each the way its backend takes
+ * it, with lock info that names the operation and the run. A lock another
+ * run holds stops the take: every lock taken so far is released, and the
+ * error names the holder from the lock info it left.
+ *
+ * A run can also hold the lock of a workspace a state is read from, which
+ * no backend block of the root names (a Terraform Cloud or Enterprise
+ * workspace a state migration moves from, terragucci#1274): the workspace's
+ * own lock, taken through its API before any state lock (`takeSourceLocks`,
+ * `takeLocksWithSources`).
+ *
+ * Lifted from terragucci's `migrate.ts` (c493e0e): `lockInfo`,
+ * `LockOperation`, `HeldLock` and `takeLocks`, and the source-workspace lock
+ * of its `takeLocks` (lines 1045 to 1056).
+ */
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+/** The lock info a run writes, in the shape the binary writes and prints when it finds a lock held. */
+export function lockInfo(path, now, op, who = `chant@${hostname()}`) {
+    return JSON.stringify({ ID: randomUUID(), Operation: op.operation, Info: op.info, Who: who, Version: "", Created: now, Path: path });
+}
+/** The holder a lock info names. */
+export function holderOf(held) {
+    let v = {};
+    try {
+        v = JSON.parse(held.info);
+    }
+    catch {
+        // Lock info that is not JSON names no one.
+    }
+    const s = (k) => (typeof v[k] === "string" && v[k] !== "" ? v[k] : undefined);
+    return { id: held.id, ...(s("Who") ? { who: s("Who") } : {}), ...(s("Operation") ? { operation: s("Operation") } : {}), ...(s("Info") ? { info: s("Info") } : {}), ...(s("Created") ? { created: s("Created") } : {}) };
+}
+/** A lock held by another run stopped the take; nothing was pulled. */
+export class StateLockedError extends Error {
+    constructor(root, lockLocation, holder) {
+        const by = holder ? [holder.who && `by ${holder.who}`, holder.operation, holder.info && `(${holder.info})`, holder.created && `since ${holder.created}`].filter(Boolean).join(" ") : "";
+        super(`${root}: its state is locked at ${lockLocation}${by ? ` ${by}` : ""}, so nothing was pulled`);
+        this.root = root;
+        this.lockLocation = lockLocation;
+        this.holder = holder;
+        this.name = "StateLockedError";
+    }
+}
+/**
+ * Take the lock of each state, in the order given. Releases what it took and
+ * throws StateLockedError when one is held and `adopt` does not take it over.
+ * `adopt` sees a held lock and says whether this take takes it over (a lock
+ * an earlier run of the same operation left held on purpose).
+ */
+export async function takeLocks(stores, now, op, adopt, who) {
+    const held = [];
+    const releaseAll = async () => {
+        for (const h of held.reverse())
+            await h.release().catch(() => { });
+    };
+    for (const { root, store } of stores) {
+        let got;
+        try {
+            got = await store.lock(lockInfo(store.location.replace(/^[a-z0-9]+:\/\//, ""), now, op, who));
+        }
+        catch (e) {
+            await releaseAll();
+            throw new Error(`${root}: the lock ${store.lockLocation} could not be taken: ${e.message}`);
+        }
+        if (got) {
+            held.push({ root, store, adopted: false, release: () => store.unlock() });
+            continue;
+        }
+        const info = await store.heldLock().catch(() => undefined);
+        if (info && adopt && (await adopt(root, store, info).catch(() => false))) {
+            store.adopt(info);
+            held.push({ root, store, adopted: true, release: () => store.unlock() });
+            continue;
+        }
+        await releaseAll();
+        throw new StateLockedError(root, store.lockLocation, info ? holderOf(info) : undefined);
+    }
+    return held;
+}
+/** A source workspace's lock could not be taken: another run holds it, or the API refused. Nothing was read. */
+export class SourceLockedError extends Error {
+    constructor(root, location, reason) {
+        super(`${root}: the lock of the workspace it is read from (${location}) could not be taken: ${reason}`);
+        this.root = root;
+        this.location = location;
+        this.reason = reason;
+        this.name = "SourceLockedError";
+    }
+}
+/** The reason a source workspace's lock shows: the operation and its info, as a state lock's info names them. */
+export const sourceLockReason = (op) => `${op.operation}: ${op.info}`;
+/**
+ * Take each source workspace's lock, in the order given, so no run writes a
+ * state while it is read. Releases what it took and throws SourceLockedError
+ * when one cannot be taken.
+ */
+export async function takeSourceLocks(sources, op) {
+    const held = [];
+    for (const s of sources) {
+        try {
+            held.push({ root: s.root, location: s.location, release: await s.lock(sourceLockReason(op)) });
+        }
+        catch (e) {
+            for (const h of held.reverse())
+                await h.release().catch(() => { });
+            throw new SourceLockedError(s.root, s.location, e.message);
+        }
+    }
+    return held;
+}
+/**
+ * Every lock a run that reads from source workspaces and writes states
+ * holds: the source workspaces' first, then the states'. When any cannot be
+ * taken, every lock taken so far is released, and the error is
+ * SourceLockedError or StateLockedError.
+ */
+export async function takeLocksWithSources(input) {
+    const sources = await takeSourceLocks(input.sources, input.sourceOp ?? input.op);
+    try {
+        const locks = await takeLocks(input.stores, input.now, input.op, input.adopt, input.who);
+        return { sources, locks };
+    }
+    catch (e) {
+        for (const h of sources.reverse())
+            await h.release().catch(() => { });
+        throw e;
+    }
+}

package/dist/state/object-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What the state stores share: the fetch they call, their errors, and how a
+ * key goes into a URL. Lifted from terragucci's `report/object-store.ts`
+ * (c493e0e), cut to what a state's lock and write need.
+ */
+export type StoreFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string | Uint8Array;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    /** A store that sends no headers (or a test's fake) gets no conditional writes. */
+    headers?: {
+        get(name: string): string | null;
+    };
+}>;
+export declare class StoreError extends Error {
+}
+/** A conditional write that lost: the object changed (412) or another write to it was in flight (409). */
+export declare class StoreConflict extends StoreError {
+}
+/** A condition on a write: the version the object must still have, or `*` for "there is no object yet". */
+export type StoreCondition = {
+    ifMatch: string;
+} | {
+    ifNoneMatch: "*";
+};
+/** A key as a URL path: each segment percent-encoded the strict way (RFC 3986), the slashes kept. */
+export declare const encodePath: (key: string) => string;
+export declare const encodeStrict: (v: string) => string;
+/** The first value of an XML element, unescaped. Enough for the small answers these stores send. */
+export declare const xmlText: (xml: string, tag: string) => string | undefined;
+/** The global fetch, as a StoreFetch. */
+export declare const defaultFetch: StoreFetch;
+//# sourceMappingURL=object-store.d.ts.map

package/dist/state/object-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../../src/state/object-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,KAAK,OAAO,CAAC;IACvI,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,mFAAmF;IACnF,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAChD,CAAC,CAAC;AAEH,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,0GAA0G;AAC1G,qBAAa,aAAc,SAAQ,UAAU;CAAG;AAEhD,2GAA2G;AAC3G,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,WAAW,EAAE,GAAG,CAAA;CAAE,CAAC;AAExE,qGAAqG;AACrG,eAAO,MAAM,UAAU,QAAS,MAAM,KAAG,MAAoD,CAAC;AAE9F,eAAO,MAAM,YAAY,MAAO,MAAM,KAAG,MAA4G,CAAC;AAEtJ,oGAAoG;AACpG,eAAO,MAAM,OAAO,QAAS,MAAM,OAAO,MAAM,KAAG,MAAM,GAAG,SAG3D,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,YAAY,EAAE,UAA2D,CAAC"}

package/dist/state/object-store.js

@@ -0,0 +1,20 @@
+/**
+ * What the state stores share: the fetch they call, their errors, and how a
+ * key goes into a URL. Lifted from terragucci's `report/object-store.ts`
+ * (c493e0e), cut to what a state's lock and write need.
+ */
+export class StoreError extends Error {
+}
+/** A conditional write that lost: the object changed (412) or another write to it was in flight (409). */
+export class StoreConflict extends StoreError {
+}
+/** A key as a URL path: each segment percent-encoded the strict way (RFC 3986), the slashes kept. */
+export const encodePath = (key) => key.split("/").map(encodeStrict).join("/");
+export const encodeStrict = (v) => encodeURIComponent(v).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+/** The first value of an XML element, unescaped. Enough for the small answers these stores send. */
+export const xmlText = (xml, tag) => {
+    const m = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+    return m?.[1].replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&").trim();
+};
+/** The global fetch, as a StoreFetch. */
+export const defaultFetch = (url, init) => fetch(url, init);