@caelo-cms/provisioning 0.10.44 → 0.10.47

package/dist/state-store.d.ts

@@ -0,0 +1,82 @@
+import { type GcloudResult } from "./gcloud.js";
+/** The two documents a store holds. */
+export type StateFile = "install.json" | "progress.json";
+/** Reads and writes an install's metadata documents. */
+export interface StateStore {
+    readonly kind: "local" | "gcs";
+    /** The document's text, or null when it does not exist. */
+    read(file: StateFile): string | null;
+    /** Replace the document. Refuses secret material. */
+    write(file: StateFile, value: unknown): void;
+}
+/** A synchronous gcloud invocation; `input` is fed on stdin. Tests pass a fake. */
+export type SyncGcloud = (args: string[], input?: string) => GcloudResult;
+/** The real {@link SyncGcloud}: `gcloud` with prompts disabled. */
+export declare const realSyncGcloud: SyncGcloud;
+/**
+ * Serialize a document after the checkpoint-secrets guard. install.json is
+ * checked for any secret; progress.json with the checkpoint rules (step
+ * payloads, outputs).
+ */
+export declare function serializeGuarded(file: StateFile, value: unknown): string;
+/** install.json + progress.json in `~/.caelo-<id>/`. */
+export declare class LocalStateStore implements StateStore {
+    private readonly root;
+    readonly kind: "local";
+    constructor(root: string);
+    read(file: StateFile): string | null;
+    write(file: StateFile, value: unknown): void;
+}
+/**
+ * install.json + progress.json in the ops bucket, mirrored to
+ * `~/.caelo-<id>/`. The first read of a document in a process fetches it
+ * from the bucket; later reads use the in-memory copy, which every write
+ * updates. A bucket error throws — the bucket is the source of truth, so
+ * silently using the local mirror could resume from a stale checkpoint.
+ */
+export declare class GcsStateStore implements StateStore {
+    private readonly bucket;
+    private readonly root;
+    private readonly run;
+    readonly kind: "gcs";
+    private readonly cache;
+    constructor(bucket: string, root: string, run?: SyncGcloud);
+    /** `gs://<bucket>/install/<file>`. */
+    objectUrl(file: StateFile): string;
+    /**
+     * The document as the bucket holds it right now, without caching it or
+     * touching the local mirror — for looking at a bucket this machine may
+     * not own (the wizard's "is this project already an install?" check).
+     */
+    peek(file: StateFile): string | null;
+    read(file: StateFile): string | null;
+    write(file: StateFile, value: unknown): void;
+}
+/** `gs://<bucket>/install/state.lock` — see {@link acquireBucketStateLock}. */
+export declare function bucketStateLockUrl(bucket: string): string;
+/**
+ * The install's state lock in its ops bucket, created only if absent
+ * (`--if-generation-match=0`). Held by every writer of a bucket-backed
+ * install's state — an installer run's `pulumi up`, `state migrate` — so
+ * none writes a backend another is switching away from. A lock left by a
+ * crashed run is reported with the command to remove it, never broken
+ * automatically.
+ *
+ * @returns the release function
+ */
+export declare function acquireBucketStateLock(bucket: string, purpose: string, run?: SyncGcloud): () => void;
+/**
+ * The same lock for an install whose state is on this machine:
+ * `~/.caelo-<id>/state.lock`, created exclusively.
+ *
+ * @returns the release function
+ */
+export declare function acquireLocalStateLock(root: string, purpose: string): () => void;
+/** The state lock for whichever backend `bucket` (gcs) or `root` (local) names. */
+export declare function acquireStateLock(backend: {
+    readonly kind: "local";
+} | {
+    readonly kind: "gcs";
+    readonly bucket: string;
+}, root: string, purpose: string, run?: SyncGcloud): () => void;
+//# sourceMappingURL=state-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../src/state-store.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,aAAa,CAAC;AAG3D,uCAAuC;AACvC,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,eAAe,CAAC;AAEzD,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IAC/B,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,qDAAqD;IACrD,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC;AAE1E,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,UAc5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAIxE;AAcD,wDAAwD;AACxD,qBAAa,eAAgB,YAAW,UAAU;IAEpC,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;gBACJ,IAAI,EAAE,MAAM;IAEzC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAKpC,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAG7C;AAKD;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,UAAU;IAK5C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IANtB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;gBAG1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,UAA2B;IAGnD,sCAAsC;IACtC,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM;IAIlC;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IASpC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAQpC,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAc7C;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAYD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,UAA2B,GAC/B,MAAM,IAAI,CAgBZ;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,IAAI,CAa/E;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACvF,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,UAA2B,GAC/B,MAAM,IAAI,CAIZ"}

package/dist/state-store.js

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Where install.json and progress.json are read from and written to (#696).
+ *
+ *   - {@link LocalStateStore}: `~/.caelo-<id>/` — every install before #696,
+ *     and self-hosted always.
+ *   - {@link GcsStateStore}: the install's ops bucket
+ *     (`gs://<project>-caelo-ops/install/`), which is authoritative. A local
+ *     copy is kept in `~/.caelo-<id>/` so `listInstalls` and the install
+ *     picker work offline, but every read in a process starts from the
+ *     bucket and every write goes to the bucket first.
+ *
+ * Both stores refuse to write secret material (checkpoint-secrets.ts, #656 /
+ * #659): install.json and progress.json are read by tooling, backups and
+ * agents, and a bucket copy is no place for a database password either. The
+ * guard sits inside each store's `write`, so no caller can skip it.
+ *
+ * The interface is synchronous on purpose: install-state.ts's callers (the
+ * wizard steps, `markStepDone`, the lifecycle commands) are synchronous, and
+ * the bucket store shells out to `gcloud storage` synchronously.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { assertNoCheckpointSecrets, assertNoSecrets } from "./checkpoint-secrets.js";
+import { gcloudEnv } from "./gcloud.js";
+import { OPS_INSTALL_PREFIX } from "./state-backend.js";
+/** The real {@link SyncGcloud}: `gcloud` with prompts disabled. */
+export const realSyncGcloud = (args, input) => {
+    const r = spawnSync("gcloud", args, {
+        env: gcloudEnv(),
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        ...(input !== undefined ? { input } : { stdio: ["ignore", "pipe", "pipe"] }),
+    });
+    if (r.error)
+        throw r.error;
+    return {
+        ok: r.status === 0,
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+        exitCode: r.status ?? 1,
+    };
+};
+/**
+ * Serialize a document after the checkpoint-secrets guard. install.json is
+ * checked for any secret; progress.json with the checkpoint rules (step
+ * payloads, outputs).
+ */
+export function serializeGuarded(file, value) {
+    if (file === "install.json")
+        assertNoSecrets(value, file);
+    else
+        assertNoCheckpointSecrets(value, file);
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/** Atomic mode-0600 write (temp file + rename in the same directory). */
+function writeTextAtomic(path, text) {
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        writeFileSync(tmp, text, { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+}
+/** install.json + progress.json in `~/.caelo-<id>/`. */
+export class LocalStateStore {
+    root;
+    kind = "local";
+    constructor(root) {
+        this.root = root;
+    }
+    read(file) {
+        const path = join(this.root, file);
+        return existsSync(path) ? readFileSync(path, "utf8") : null;
+    }
+    write(file, value) {
+        writeTextAtomic(join(this.root, file), serializeGuarded(file, value));
+    }
+}
+/** gcloud's wording for an object that is not there. */
+const NOT_FOUND = /matched no objects|No URLs matched|NotFound|404|does not exist/i;
+/**
+ * install.json + progress.json in the ops bucket, mirrored to
+ * `~/.caelo-<id>/`. The first read of a document in a process fetches it
+ * from the bucket; later reads use the in-memory copy, which every write
+ * updates. A bucket error throws — the bucket is the source of truth, so
+ * silently using the local mirror could resume from a stale checkpoint.
+ */
+export class GcsStateStore {
+    bucket;
+    root;
+    run;
+    kind = "gcs";
+    cache = new Map();
+    constructor(bucket, root, run = realSyncGcloud) {
+        this.bucket = bucket;
+        this.root = root;
+        this.run = run;
+    }
+    /** `gs://<bucket>/install/<file>`. */
+    objectUrl(file) {
+        return `gs://${this.bucket}/${OPS_INSTALL_PREFIX}/${file}`;
+    }
+    /**
+     * The document as the bucket holds it right now, without caching it or
+     * touching the local mirror — for looking at a bucket this machine may
+     * not own (the wizard's "is this project already an install?" check).
+     */
+    peek(file) {
+        const r = this.run(["storage", "cat", this.objectUrl(file)]);
+        if (r.ok)
+            return r.stdout;
+        if (NOT_FOUND.test(r.stderr))
+            return null;
+        throw new Error(`Could not read ${this.objectUrl(file)}: ${r.stderr.trim() || `gcloud exited ${r.exitCode}`}. Check that you are signed in (gcloud auth login) as an account with access to the install's ops bucket.`);
+    }
+    read(file) {
+        if (this.cache.has(file))
+            return this.cache.get(file) ?? null;
+        const text = this.peek(file);
+        this.cache.set(file, text);
+        if (text !== null)
+            writeTextAtomic(join(this.root, file), text);
+        return text;
+    }
+    write(file, value) {
+        const text = serializeGuarded(file, value);
+        const r = this.run(["storage", "cp", "-", this.objectUrl(file), "--content-type=application/json"], text);
+        if (!r.ok) {
+            throw new Error(`Could not write ${this.objectUrl(file)}: ${r.stderr.trim() || `gcloud exited ${r.exitCode}`}. Nothing was changed locally; fix access to the ops bucket and re-run.`);
+        }
+        this.cache.set(file, text);
+        writeTextAtomic(join(this.root, file), text);
+    }
+}
+/** `gs://<bucket>/install/state.lock` — see {@link acquireBucketStateLock}. */
+export function bucketStateLockUrl(bucket) {
+    return `gs://${bucket}/${OPS_INSTALL_PREFIX}/state.lock`;
+}
+/** Who holds a lock, for the refusal message. */
+function lockBody(purpose) {
+    return JSON.stringify({
+        purpose,
+        host: hostname(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    });
+}
+/**
+ * The install's state lock in its ops bucket, created only if absent
+ * (`--if-generation-match=0`). Held by every writer of a bucket-backed
+ * install's state — an installer run's `pulumi up`, `state migrate` — so
+ * none writes a backend another is switching away from. A lock left by a
+ * crashed run is reported with the command to remove it, never broken
+ * automatically.
+ *
+ * @returns the release function
+ */
+export function acquireBucketStateLock(bucket, purpose, run = realSyncGcloud) {
+    const url = bucketStateLockUrl(bucket);
+    const r = run(["storage", "cp", "-", url, "--if-generation-match=0"], lockBody(purpose));
+    if (!r.ok) {
+        if (/PreconditionFailed|412|At least one of the pre-conditions/i.test(r.stderr)) {
+            const held = run(["storage", "cat", url]);
+            throw new Error(`Another run is changing this install's state (${held.ok ? held.stdout.trim() : url}). Re-run once it has finished; if none is running, remove the stale lock: gcloud storage rm ${url}`);
+        }
+        throw new Error(`Could not take the state lock ${url}: ${r.stderr.trim()}`);
+    }
+    return () => {
+        const rm = run(["storage", "rm", url]);
+        if (!rm.ok)
+            throw new Error(`Could not release ${url}; remove it: gcloud storage rm ${url}`);
+    };
+}
+/**
+ * The same lock for an install whose state is on this machine:
+ * `~/.caelo-<id>/state.lock`, created exclusively.
+ *
+ * @returns the release function
+ */
+export function acquireLocalStateLock(root, purpose) {
+    const path = join(root, "state.lock");
+    try {
+        writeFileSync(path, lockBody(purpose), { flag: "wx", mode: 0o600 });
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            throw new Error(`Another run is changing this install's state (${readFileSync(path, "utf8").trim()}). Re-run once it has finished; if none is running, remove the stale lock: rm ${path}`);
+        }
+        throw e;
+    }
+    return () => rmSync(path, { force: true });
+}
+/** The state lock for whichever backend `bucket` (gcs) or `root` (local) names. */
+export function acquireStateLock(backend, root, purpose, run = realSyncGcloud) {
+    return backend.kind === "gcs"
+        ? acquireBucketStateLock(backend.bucket, purpose, run)
+        : acquireLocalStateLock(root, purpose);
+}
+//# sourceMappingURL=state-store.js.map

package/dist/state-store.js.map

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

package/dist/upgrade/app-roll.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The app-roll half of an upgrade (epic #696): migrations with the new admin
+ * image, then admin and gateway onto their new images with the env contract
+ * riding the same revision, traffic onto the new revisions, a deep health
+ * check, and — on any failure — traffic back onto the revisions that served
+ * before.
+ *
+ * It never changes IAM, never creates a service account or secret and never
+ * touches other cloud resources: everything here works under an identity
+ * that may only deploy Cloud Run revisions, run the migration job and take a
+ * Cloud SQL backup. That is the identity the in-cloud upgrader job runs as.
+ * Whatever needs more lives in converge.ts; `cms-provision upgrade` runs
+ * both, and the upgrader job refuses to run while the install needs a
+ * converge (`needsConverge`).
+ *
+ * Converge steps that must sit between app-roll steps — a database role that
+ * a migration creates gets its password after migrations and before the
+ * gateway rolls — come in through {@link AppRollHooks}. The upgrader job
+ * passes none.
+ *
+ * All gcloud calls go through the injected runner, all output through the
+ * injected reporter, so the whole sequence runs against a fake in tests.
+ */
+import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
+import type { ImageDigests } from "../install-state.js";
+import { type EnvChange, type LiveEnvValue, type LiveVolumes } from "../stack-converge.js";
+import { type SqlBackup } from "./backup.js";
+import type { HealthProbe } from "./health.js";
+import type { UpgradeReporter } from "./reporter.js";
+export type RollSlug = "admin" | "gateway";
+/** The roll order: the gateway follows the admin, never the other way round. */
+export declare const ROLL_ORDER: readonly RollSlug[];
+/** The install an app-roll acts on. */
+export interface AppRollInstall {
+    readonly provider: "gcp" | "gcp-firebase";
+    readonly projectId: string;
+    readonly region: string;
+    /** Pulumi stack name (`production`). */
+    readonly env: string;
+    readonly domain: string;
+    /** The protected staging host the admin is told about (#650). */
+    readonly stagingHost: string;
+}
+/** The release image one service rolls to. */
+export interface ReleaseImage {
+    /** Fully qualified, digest-pinned reference (`…/admin@sha256:…`). */
+    readonly imageRef: string;
+    readonly digest: string;
+}
+/** A service as it runs now, plus the image it rolls to. */
+export interface ServicePlan {
+    readonly slug: RollSlug;
+    readonly serviceName: string;
+    readonly imageRef: string;
+    readonly digest: string;
+    readonly priorRevision: string;
+    readonly liveEnv: ReadonlyMap<string, LiveEnvValue>;
+    /** Container memory limit now (null = Cloud Run's default). */
+    readonly liveMemory: string | null;
+    readonly liveVolumes: LiveVolumes;
+}
+/** A service plan plus the changes its roll applies. */
+export interface RollPlan extends ServicePlan {
+    readonly envFlags: readonly string[];
+    readonly envChanges: readonly EnvChange[];
+    /** #553 — e.g. `--memory=2Gi` when the admin runs below the stack default. */
+    readonly resourceFlags: readonly string[];
+    /** The admin's media bucket volume when it is (partly) missing; empty otherwise. */
+    readonly volumeFlags: readonly string[];
+    readonly volumeChanges: readonly string[];
+}
+/** Everything an app-roll will do, computed read-only before anything changes. */
+export interface AppRollPlan {
+    readonly install: AppRollInstall;
+    /** In {@link ROLL_ORDER}. */
+    readonly services: readonly RollPlan[];
+    /** Notes for the operator (e.g. a memory limit left as is). */
+    readonly warnings: readonly string[];
+}
+export type PlanResult = {
+    readonly ok: true;
+    readonly plan: AppRollPlan;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Read both services and plan their rolls: prior revisions (the rollback
+ * targets), env-contract changes, the admin's memory and media volume. Makes
+ * no change; fails when anything a roll needs is missing.
+ */
+export declare function planAppRoll(install: AppRollInstall, images: Readonly<Record<RollSlug, ReleaseImage>>, run: GcloudRunner): Promise<PlanResult>;
+/**
+ * The plan with `names` left exactly as the services have them — for env
+ * vars that point at something a converge step could not set up.
+ */
+export declare function leavingEnvUntouched(plan: AppRollPlan, names: readonly string[]): AppRollPlan;
+/** Print what the plan will change, one line per change. */
+export declare function reportPlan(plan: AppRollPlan, reporter: UpgradeReporter): void;
+/** Converge steps that must sit between app-roll steps (none for the upgrader job). */
+export interface AppRollHooks {
+    /**
+     * After migrations, before any service rolls. Returns the contract env
+     * vars the rolls must leave untouched because what they point at could
+     * not be set up; `ok: false` aborts the upgrade (nothing rolled yet).
+     */
+    afterMigrations?(): Promise<{
+        readonly ok: true;
+        readonly leaveUntouched: readonly string[];
+    } | {
+        readonly ok: false;
+    }>;
+    /** Right before `slug` rolls; `ok: false` aborts and rolls back what rolled. */
+    beforeRoll?(slug: RollSlug): Promise<{
+        readonly ok: true;
+    } | {
+        readonly ok: false;
+        readonly error: string;
+    }>;
+    /** After `slug` went back to its prior revision (or its roll failed). */
+    afterRollback?(slug: RollSlug): Promise<void>;
+}
+export interface AppRollDeps {
+    readonly run: GcloudRunner;
+    readonly sleep?: Sleep;
+    readonly reporter: UpgradeReporter;
+    /** Runs both migration targets with `imageRef` (the NEW admin image). */
+    readonly migrate: (imageRef: string) => Promise<{
+        readonly ok: boolean;
+        readonly error?: string;
+    }>;
+    /** The deep health check, or null when the operator explicitly skipped it. */
+    readonly health: HealthProbe | null;
+    /** Persist the digests now serving (install.json, stack config, …). */
+    readonly recordDigests: (digests: ImageDigests) => Promise<void>;
+}
+export interface AppRollInput {
+    readonly plan: AppRollPlan;
+    /**
+     * The backup taken before this roll. Required: migrations never run
+     * without a backup to go back to.
+     */
+    readonly backup: SqlBackup;
+    /** The release version rolled to, when known (`0.11.0`; null for a channel tag). */
+    readonly targetVersion: string | null;
+    /**
+     * Whether the release's migrations are contract-type (destructive for the
+     * previous release; from the signed release manifest). null = unknown.
+     */
+    readonly migrationsContract: boolean | null;
+}
+export type AppRollPhase = "health-baseline" | "migrations" | "converge" | "roll" | "health";
+export type AppRollResult = {
+    readonly ok: true;
+    readonly digests: ImageDigests;
+} | {
+    readonly ok: false;
+    readonly phase: AppRollPhase;
+    /** Whether migrations ran before the failure (the backup matters then). */
+    readonly migrated: boolean;
+};
+/** Run the app-roll. See the file comment for the sequence. */
+export declare function executeAppRoll(input: AppRollInput, hooks: AppRollHooks, deps: AppRollDeps): Promise<AppRollResult>;
+//# sourceMappingURL=app-roll.d.ts.map

package/dist/upgrade/app-roll.d.ts.map

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