During a deployment two Heimdall processes exist at once under distinct UIDs and namespaces, and both are configured with the same CultCache store path. Exactly one may write it. Idunn decides which by publishing a lease record naming an incarnation; nothing in Heimdall read it, so both generations would have written heimdall.service.cc. src/process-write-lease.ts answers one question -- may this process write state right now -- by reading the lease and the runtime bundle's expected.cc, and comparing incarnation identity. It grants nothing and throws nothing outward: every failure is a decision of mayWrite:false with a reason, because for a warming candidate "not yet my turn" is the expected condition and crashing would turn it into a failed deployment. Records are decoded as the canonical positional MessagePack Idunn writes (14 fields for the lease, schema-checked), and the tests build the same envelope bytes rather than convenient objects. publishHeimdallVerseState is the single writer, so that is the only place gated. Outside Idunn no lease path is configured and writes proceed unconditionally, which keeps developer runs and the current plain unit working. Second defect found while wiring it: health publication hardcoded state "active". A candidate would have claimed active from its first pulse, which is both untrue and structurally broken -- Idunn must observe `warming` presence before it fences the incumbent, so a candidate that never reports warming cannot be promoted. State is now derived from the lease: warming until held, active after, with the reason carried in the detail string. 49 tests across 11 files; tsc clean under exactOptionalPropertyTypes. The recipe's status banner now records the contract as implemented, with the honest caveat that none of it has been through a live `idunn up` -- the daemon on yggdrasil is still the previous generation, so the first deployment remains the real verification. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
150 lines
5.5 KiB
TypeScript
150 lines
5.5 KiB
TypeScript
import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
|
|
import { encode } from "@msgpack/msgpack";
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import { resolveWriteLease } from "../src/process-write-lease.js";
|
|
|
|
/**
|
|
* Idunn writes CultCache envelopes whose payload is the canonical positional
|
|
* MessagePack encoding of the record. These helpers reproduce that shape, so
|
|
* the tests exercise the same bytes the daemon will actually be handed rather
|
|
* than a convenient object.
|
|
*/
|
|
function envelope(key: string, type: string, payload: Uint8Array): Uint8Array {
|
|
return encode([{ key, type, payload, storedAt: "2026-09-06T00:00:00.000Z" }]);
|
|
}
|
|
|
|
function expectedIncarnation(target: string, incarnationId: string): Uint8Array {
|
|
const fields = new Array(12).fill("x");
|
|
fields[0] = "idunn.expected_incarnation.v2";
|
|
fields[1] = target;
|
|
fields[3] = incarnationId;
|
|
return encode(fields);
|
|
}
|
|
|
|
function writeLease(target: string, incarnationId: string, epoch = 3): Uint8Array {
|
|
const fields: unknown[] = new Array(14).fill("x");
|
|
fields[0] = "idunn.process_write_lease.v1";
|
|
fields[1] = target;
|
|
fields[4] = incarnationId;
|
|
fields[10] = "runtime-instance-1";
|
|
fields[12] = epoch;
|
|
fields[13] = 1757116800000;
|
|
return encode(fields);
|
|
}
|
|
|
|
async function bundleWith(
|
|
expectedBytes: Uint8Array | undefined,
|
|
leaseBytes: Uint8Array | undefined
|
|
): Promise<{ bundle: string; lease: string }> {
|
|
const root = await mkdtemp(path.join(os.tmpdir(), "heimdall-lease-"));
|
|
const bundle = path.join(root, "runtime-instance-1");
|
|
await mkdir(bundle, { recursive: true });
|
|
|
|
if (expectedBytes) {
|
|
await writeFile(
|
|
path.join(bundle, "expected.cc"),
|
|
envelope("heimdall", "idunn.expected_incarnation", expectedBytes)
|
|
);
|
|
}
|
|
|
|
const lease = path.join(root, "process-write-lease.cc");
|
|
if (leaseBytes) {
|
|
await writeFile(lease, envelope("heimdall", "idunn.process_write_lease", leaseBytes));
|
|
}
|
|
|
|
return { bundle, lease };
|
|
}
|
|
|
|
describe("Idunn process write lease", () => {
|
|
it("permits writes when not launched by Idunn", async () => {
|
|
// A developer run and the current plain systemd unit have no second
|
|
// generation to collide with.
|
|
await expect(resolveWriteLease({})).resolves.toMatchObject({
|
|
mayWrite: true,
|
|
reason: "not-under-idunn",
|
|
});
|
|
});
|
|
|
|
it("permits writes when the lease names this incarnation", async () => {
|
|
const { bundle, lease } = await bundleWith(
|
|
expectedIncarnation("heimdall", "incarnation-a"),
|
|
writeLease("heimdall", "incarnation-a", 7)
|
|
);
|
|
|
|
await expect(
|
|
resolveWriteLease({ leasePath: lease, runtimeBundlePath: bundle })
|
|
).resolves.toMatchObject({ mayWrite: true, reason: "held", incarnationId: "incarnation-a", leaseEpoch: 7 });
|
|
});
|
|
|
|
it("refuses writes when the lease names the other generation", async () => {
|
|
// The case the lease exists for: a warming candidate while the incumbent
|
|
// still holds the store.
|
|
const { bundle, lease } = await bundleWith(
|
|
expectedIncarnation("heimdall", "incarnation-candidate"),
|
|
writeLease("heimdall", "incarnation-incumbent")
|
|
);
|
|
|
|
const decision = await resolveWriteLease({ leasePath: lease, runtimeBundlePath: bundle });
|
|
expect(decision.mayWrite).toBe(false);
|
|
expect(decision.reason).toContain("incarnation-incumbent");
|
|
});
|
|
|
|
it("refuses writes when no lease has been granted yet", async () => {
|
|
const { bundle, lease } = await bundleWith(
|
|
expectedIncarnation("heimdall", "incarnation-a"),
|
|
undefined
|
|
);
|
|
|
|
const decision = await resolveWriteLease({ leasePath: lease, runtimeBundlePath: bundle });
|
|
expect(decision.mayWrite).toBe(false);
|
|
expect(decision.reason).toContain("no readable write lease");
|
|
});
|
|
|
|
it("refuses writes when the lease belongs to another target", async () => {
|
|
const { bundle, lease } = await bundleWith(
|
|
expectedIncarnation("heimdall", "incarnation-a"),
|
|
writeLease("ghostlight", "incarnation-a")
|
|
);
|
|
|
|
const decision = await resolveWriteLease({ leasePath: lease, runtimeBundlePath: bundle });
|
|
expect(decision.mayWrite).toBe(false);
|
|
expect(decision.reason).toContain("ghostlight");
|
|
});
|
|
|
|
it("refuses writes on a wrong-length or wrong-schema lease", async () => {
|
|
const short = encode(new Array(9).fill("x"));
|
|
const wrongSchema = encode(
|
|
Object.assign(new Array(14).fill("x"), { 0: "idunn.process_write_lease.v0", 12: 1 })
|
|
);
|
|
|
|
for (const bytes of [short, wrongSchema]) {
|
|
const { bundle, lease } = await bundleWith(
|
|
expectedIncarnation("heimdall", "incarnation-a"),
|
|
bytes
|
|
);
|
|
const decision = await resolveWriteLease({ leasePath: lease, runtimeBundlePath: bundle });
|
|
expect(decision.mayWrite).toBe(false);
|
|
}
|
|
});
|
|
|
|
it("refuses writes when a lease path is set without a runtime bundle", async () => {
|
|
// Launch inputs are incoherent; declining is the safe reading.
|
|
const decision = await resolveWriteLease({ leasePath: "/nonexistent/lease.cc" });
|
|
expect(decision.mayWrite).toBe(false);
|
|
expect(decision.reason).toContain("GAMECULT_IDUNN_RUNTIME_BUNDLE");
|
|
});
|
|
|
|
it("refuses writes when the runtime bundle is unreadable", async () => {
|
|
const { lease } = await bundleWith(undefined, writeLease("heimdall", "incarnation-a"));
|
|
const decision = await resolveWriteLease({
|
|
leasePath: lease,
|
|
runtimeBundlePath: "/nonexistent/bundle",
|
|
});
|
|
expect(decision.mayWrite).toBe(false);
|
|
expect(decision.reason).toContain("unreadable runtime bundle");
|
|
});
|
|
});
|