@abelxiaoxing/cadence 2.0.25 → 2.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,6 +19,12 @@ import {
19
19
  oneOf,
20
20
  text,
21
21
  } from "./contracts/core.ts";
22
+ import {
23
+ decodeMarkFields,
24
+ holderState,
25
+ selfMark,
26
+ stampTime,
27
+ } from "./liveness.ts";
22
28
  import {
23
29
  DirectoryWalks,
24
30
  encoded,
@@ -120,7 +126,7 @@ function reservation(r: Registration): Reservation {
120
126
  } = r;
121
127
  return row;
122
128
  }
123
- function decodeRegistration(value: unknown): Registration {
129
+ export function decodeRegistration(value: unknown): Registration {
124
130
  const o = closed(value, registrationKeys);
125
131
  const row = Object.fromEntries(reservationKeys.map((k) => [k, o[k]]));
126
132
  return {
@@ -156,38 +162,42 @@ interface RegistryLock {
156
162
  token: string;
157
163
  pid: number;
158
164
  host: string;
165
+ boot: string | null;
166
+ started: string | null;
167
+ }
168
+ /** Older locks lack the liveness marks; new ones carry both. */
169
+ export function markedKeys(value: unknown, keys: string[]): string[] {
170
+ const has = (key: string) =>
171
+ !!value && typeof value === "object" && Object.hasOwn(value, key);
172
+ return [
173
+ ...keys,
174
+ ...(has("boot") ? ["boot"] : []),
175
+ ...(has("started") ? ["started"] : []),
176
+ ];
159
177
  }
160
- function decodeRegistryLock(snapshot: FileSnapshot): RegistryLock {
161
- const o = closed(json(snapshot), ["schema", "token", "pid", "host"]);
178
+ export function decodeRegistryLock(snapshot: FileSnapshot): RegistryLock {
179
+ const raw = json(snapshot);
180
+ const o = closed(raw, markedKeys(raw, ["schema", "token", "pid", "host"]));
162
181
  return {
163
182
  schema: literal(o.schema, "cadence-service-registry-lock/1"),
164
183
  token: decodeId(o.token),
165
184
  // kill(0)/negative process-group probes must never be possible.
166
185
  pid: integer(o.pid, 1, 2147483647),
167
186
  host: text(o.host, 255, true),
187
+ ...decodeMarkFields(o),
168
188
  };
169
189
  }
170
190
  export interface RegistryLockDiagnostic {
171
191
  reason: "registry-locked";
172
192
  owner: "live" | "absent" | "ambiguous" | "unreadable";
173
193
  }
174
- export interface RegistryRecoveryInspection {
175
- scope: "global-registry";
176
- epoch: string; // exact lock incarnation, not a service epoch
177
- coordinationDigest: string;
178
- owner: "live" | "absent" | "ambiguous";
179
- process: { pid: number; host: string };
180
- reservations: number;
181
- previousResolver: "live" | "absent" | "ambiguous" | null;
182
- resolution: "local-interactive-only";
183
- }
184
194
  const registryNames = [
185
195
  "format.json",
186
196
  "roots.json",
187
197
  "registry.lock",
188
198
  "recovery-v1",
189
199
  ];
190
- interface RegistryView {
200
+ export interface RegistryView {
191
201
  format: FileSnapshot;
192
202
  snapshot: FileSnapshot;
193
203
  value: Registry;
@@ -202,39 +212,6 @@ interface Selected {
202
212
  checkout?: FileSnapshot;
203
213
  value?: Registration;
204
214
  }
205
- export function recoveryOwnerStatus(
206
- pid: number,
207
- host: string,
208
- ): "live" | "absent" | "ambiguous" {
209
- if (host !== hostname()) return "ambiguous";
210
- try {
211
- process.kill(pid, 0);
212
- return "live";
213
- } catch (error) {
214
- return error instanceof Error && "code" in error && error.code === "ESRCH"
215
- ? "absent"
216
- : "ambiguous";
217
- }
218
- }
219
- function recoveryDigest(registry: RegistryView, selected: Selected): string {
220
- return hash(
221
- encoded([
222
- registry.format.identity,
223
- registry.format.stamp,
224
- registry.snapshot.identity,
225
- registry.snapshot.stamp,
226
- selected.capability?.stamp ?? null, // incarnation only; never a secret-derived capability digest
227
- ...[
228
- selected.manifest,
229
- selected.config,
230
- selected.hostConfig,
231
- selected.registration,
232
- selected.owner,
233
- selected.checkout,
234
- ].map((value) => (value ? [value.identity, value.stamp] : null)),
235
- ]),
236
- );
237
- }
238
215
  export type CoordinationStatus =
239
216
  | { status: "absent" | "unavailable" }
240
217
  | {
@@ -408,13 +385,11 @@ export class ServiceCoordination {
408
385
  throw new ContractError("quarantine");
409
386
  if (value && value.phase !== "stopped") {
410
387
  if (!owner || !checkout || !capability) refused();
411
- const lock = closed(json(owner), [
412
- "schema",
413
- "epoch",
414
- "token",
415
- "pid",
416
- "host",
417
- ]);
388
+ const raw = json(owner);
389
+ const lock = closed(
390
+ raw,
391
+ markedKeys(raw, ["schema", "epoch", "token", "pid", "host"]),
392
+ );
418
393
  literal(lock.schema, "cadence-service-owner-lock/1");
419
394
  literal(lock.epoch, value.epoch);
420
395
  literal(lock.token, value.ownerToken);
@@ -496,6 +471,20 @@ export class ServiceCoordination {
496
471
  }),
497
472
  );
498
473
  }
474
+ /** Validated registry, or undefined before the first reservation. */
475
+ registryView(): RegistryView | undefined {
476
+ return this.registry();
477
+ }
478
+ /** The short exclusive registry section, for self-healing reclaims. */
479
+ mutateRegistry<T>(
480
+ operation: (
481
+ view: RegistryView,
482
+ mutate: () => void,
483
+ assertHeld: () => void,
484
+ ) => T,
485
+ ): T {
486
+ return this.withRegistry(operation);
487
+ }
499
488
  private withRegistry<T>(
500
489
  operation: (
501
490
  view: RegistryView,
@@ -508,6 +497,7 @@ export class ServiceCoordination {
508
497
  const lockPath = this.registryPath("registry.lock");
509
498
  let lock: FileSnapshot;
510
499
  try {
500
+ const mark = selfMark();
511
501
  lock = this.files.create(
512
502
  lockPath,
513
503
  encoded({
@@ -515,6 +505,8 @@ export class ServiceCoordination {
515
505
  token: randomUUID(),
516
506
  pid: process.pid,
517
507
  host: hostname(),
508
+ boot: mark.boot,
509
+ started: mark.started,
518
510
  }),
519
511
  );
520
512
  } catch (error) {
@@ -648,6 +640,7 @@ export class ServiceCoordination {
648
640
  const checkout = this.store.acquire();
649
641
  const checkoutFile = this.files.read(this.store.lockPath, 8192);
650
642
  if (!checkoutFile) refused();
643
+ const mark = selfMark();
651
644
  const owner = this.files.create(
652
645
  this.path("owner.lock"),
653
646
  encoded({
@@ -656,6 +649,8 @@ export class ServiceCoordination {
656
649
  token: row.ownerToken,
657
650
  pid: row.pid,
658
651
  host: row.host,
652
+ boot: mark.boot,
653
+ started: mark.started,
659
654
  }),
660
655
  );
661
656
  const capability = this.files.create(
@@ -758,323 +753,20 @@ export class ServiceCoordination {
758
753
  const lock = this.files.read(this.registryPath("registry.lock"));
759
754
  if (!lock) return undefined;
760
755
  const value = decodeRegistryLock(lock);
756
+ const holder = holderState(value, stampTime(lock.stamp)).state;
761
757
  return {
762
758
  reason: "registry-locked",
763
- owner: recoveryOwnerStatus(value.pid, value.host),
759
+ owner:
760
+ holder === "live"
761
+ ? "live"
762
+ : holder === "dead"
763
+ ? "absent"
764
+ : "ambiguous",
764
765
  };
765
766
  } catch {
766
767
  return { reason: "registry-locked", owner: "unreadable" };
767
768
  }
768
769
  }
769
- private registryRecoveryState() {
770
- const lock = this.files.read(this.registryPath("registry.lock"));
771
- if (!lock) throw new ContractError("conflict");
772
- const value = decodeRegistryLock(lock);
773
- names(this.registryDirectory, registryNames);
774
- const format = this.files.read(this.registryPath("format.json"));
775
- const roots = this.files.read(
776
- this.registryPath("roots.json"),
777
- REGISTRY_BYTES,
778
- );
779
- // A crash immediately after exclusive creation may precede initialization.
780
- const registry = !format && !roots ? undefined : this.registry();
781
- const entries = registry?.value.entries ?? [];
782
- const protectedRoots = new Set(entries.map((row) => hash(row.root)));
783
- const proofs: unknown[] = [];
784
- // Older releases removed a reservation BEFORE the checkout fence. A dead
785
- // short-lock PID cannot make those unreserved, partially released projects
786
- // safe. Verify every unreserved service selection; never repair it here.
787
- const directory = opendirSync(this.files.namespace);
788
- try {
789
- let count = 0;
790
- for (
791
- let entry = directory.readSync();
792
- entry;
793
- entry = directory.readSync()
794
- ) {
795
- if (++count > 1024) throw new ContractError("capacity");
796
- if (
797
- !/^[a-f0-9]{64}$/.test(entry.name) ||
798
- protectedRoots.has(entry.name)
799
- )
800
- continue;
801
- const service = join(this.files.namespace, entry.name, "service-v1");
802
- if (!this.files.directory(service)) continue;
803
- const manifest = this.files.read(join(service, "format.json"));
804
- if (!manifest) refused();
805
- const f = closed(json(manifest), [
806
- "schema",
807
- "root",
808
- "stateHome",
809
- "configIdentity",
810
- ]);
811
- const root = pathValue(f.root);
812
- if (hash(root) !== entry.name) refused();
813
- // Retained stopped metadata remains checkable even when the consumer
814
- // deleted/moved that old working directory. Never resolve/recreate it.
815
- const selected = this.selected(service, root, true);
816
- if (!selected) throw new ContractError("quarantine");
817
- proofs.push([
818
- entry.name,
819
- ...[
820
- selected.manifest,
821
- selected.config,
822
- selected.hostConfig,
823
- selected.registration,
824
- ].map((file) => (file ? [file.identity, file.stamp] : null)),
825
- ]);
826
- }
827
- } finally {
828
- directory.closeSync();
829
- }
830
- proofs.sort((a, b) =>
831
- JSON.stringify(a).localeCompare(JSON.stringify(b), "en"),
832
- );
833
- const stateDigest = hash(
834
- encoded([
835
- lock.identity,
836
- lock.stamp,
837
- format ? [format.identity, format.stamp] : null,
838
- roots ? [roots.identity, roots.stamp] : null,
839
- proofs,
840
- ]),
841
- );
842
- const epoch = hash(encoded([lock.identity, lock.stamp]));
843
- const archive = this.registryPath(join("recovery-v1", epoch));
844
- const attempts: FileSnapshot[] = [];
845
- let previousResolver: RegistryRecoveryInspection["previousResolver"] = null;
846
- if (this.files.directory(archive)) {
847
- // Immutable, exclusive attempts serialize resolvers. If one crashes before
848
- // release, a fresh confirmation may append the next attempt ONLY after its
849
- // PID is absent. No stale secondary lock needs deletion or takeover.
850
- names(
851
- archive,
852
- Array.from({ length: 128 }, (_, n) => `${n}.json`),
853
- );
854
- for (let n = 0; n < 128; n++) {
855
- const attempt = this.files.read(join(archive, `${n}.json`), 32768);
856
- if (!attempt) {
857
- names(
858
- archive,
859
- attempts.map((_, i) => `${i}.json`),
860
- );
861
- break;
862
- }
863
- const o = closed(json(attempt, 32768), [
864
- "schema",
865
- "lock",
866
- "pid",
867
- "host",
868
- "digest",
869
- ]);
870
- literal(o.schema, "cadence-registry-recovery/1");
871
- literal(o.lock, lock.bytes.toString("utf8"));
872
- decodeHash(o.digest);
873
- previousResolver = recoveryOwnerStatus(
874
- integer(o.pid, 1, 2147483647),
875
- text(o.host, 255, true),
876
- );
877
- attempts.push(attempt);
878
- }
879
- }
880
- const inspection: RegistryRecoveryInspection = {
881
- scope: "global-registry",
882
- epoch,
883
- coordinationDigest: hash(
884
- encoded([stateDigest, attempts.map((a) => [a.identity, a.stamp])]),
885
- ),
886
- owner: recoveryOwnerStatus(value.pid, value.host),
887
- process: { pid: value.pid, host: value.host },
888
- reservations: entries.length,
889
- previousResolver,
890
- resolution: "local-interactive-only",
891
- };
892
- return { lock, archive, attempts, stateDigest, inspection };
893
- }
894
- inspectRegistryRecovery(): RegistryRecoveryInspection {
895
- return this.registryRecoveryState().inspection;
896
- }
897
- /** Local native management only. Retire just the proven dead short lock after
898
- * durable evidence; reservations, owner/checkout locks and history stay intact. */
899
- resolveRegistryRecovery(
900
- expected: RegistryRecoveryInspection,
901
- assertAuthority: () => void,
902
- ) {
903
- assertAuthority();
904
- const state = this.registryRecoveryState();
905
- if (encoded(state.inspection) !== encoded(expected))
906
- throw new ContractError("conflict");
907
- if (
908
- expected.owner !== "absent" ||
909
- (expected.previousResolver !== null &&
910
- expected.previousResolver !== "absent")
911
- )
912
- throw new ContractError("quarantine");
913
- if (state.attempts.length >= 128) throw new ContractError("capacity");
914
- assertAuthority();
915
- const receiptPath = join(state.archive, `${state.attempts.length}.json`);
916
- const receipt = this.files.create(
917
- receiptPath,
918
- encoded({
919
- schema: "cadence-registry-recovery/1",
920
- lock: state.lock.bytes.toString("utf8"),
921
- pid: process.pid,
922
- host: hostname(),
923
- digest: expected.coordinationDigest,
924
- }),
925
- 32768,
926
- );
927
- // create fsyncs/closes the original receipt before any release effect.
928
- assertAuthority();
929
- const current = this.registryRecoveryState();
930
- if (
931
- current.stateDigest !== state.stateDigest ||
932
- current.inspection.owner !== "absent" ||
933
- current.attempts.length !== state.attempts.length + 1
934
- )
935
- throw new ContractError("conflict");
936
- for (const [n, attempt] of state.attempts.entries())
937
- this.files.assert(join(state.archive, `${n}.json`), attempt, 32768);
938
- this.files.assert(receiptPath, receipt, 32768);
939
- assertAuthority();
940
- this.files.remove(this.registryPath("registry.lock"), state.lock);
941
- return {
942
- status: "resolved",
943
- scope: "global-registry",
944
- recoveryId: expected.epoch,
945
- notice: "registry-only-project-fences-preserved",
946
- } as const;
947
- }
948
- /** Capture exact private resources BEFORE the append/confirmation awaits. The
949
- * closure is internal local management authority, never a wire capability.
950
- * A durable bridge must be verified by the caller before EVERY release effect. */
951
- prepareRecoveryRelease(
952
- expected: string,
953
- assertAuthority: () => void,
954
- ): (assertDurable: () => void) => void {
955
- assertAuthority();
956
- if (this.recoverySnapshot().digest !== expected)
957
- throw new ContractError("conflict");
958
- const selected = this.selected();
959
- if (
960
- !selected?.value ||
961
- !selected.registration ||
962
- !selected.owner ||
963
- !selected.checkout ||
964
- !selected.capability
965
- )
966
- throw new ContractError("quarantine");
967
- const r = selected.value;
968
- const absent = () => {
969
- assertAuthority();
970
- if (recoveryOwnerStatus(r.pid, r.host) !== "absent")
971
- throw new ContractError("quarantine");
972
- };
973
- absent();
974
- let used = false;
975
- return (assertDurable) => {
976
- if (used) throw new ContractError("consumed-grant");
977
- used = true;
978
- this.withRegistry((view, mutate, assertHeld) => {
979
- let registry = view.snapshot;
980
- let registration = selected.registration;
981
- let capability = selected.capability;
982
- let owner = selected.owner;
983
- let checkout = selected.checkout;
984
- if (!registration || !capability || !owner || !checkout)
985
- throw new ContractError("conflict");
986
- if (recoveryDigest(view, selected) !== expected)
987
- throw new ContractError("conflict");
988
- const assert = () => {
989
- absent();
990
- assertHeld();
991
- this.assertNamespace();
992
- this.files.assert(
993
- this.registryPath("roots.json"),
994
- registry,
995
- REGISTRY_BYTES,
996
- );
997
- for (const [name, snapshot] of [
998
- ["format.json", selected.manifest],
999
- ["config.json", selected.config],
1000
- ["host-config.json", selected.hostConfig],
1001
- ["registration.json", registration],
1002
- ["local-capability.json", capability],
1003
- ["owner.lock", owner],
1004
- ] as const)
1005
- this.files.assert(this.path(name), snapshot);
1006
- this.files.assert(this.store.lockPath, checkout, 8192);
1007
- assertDurable();
1008
- };
1009
- assert();
1010
- const matching = view.value.entries.filter(
1011
- (row) => row.epoch === r.epoch,
1012
- );
1013
- if (
1014
- matching.length !== 1 ||
1015
- encoded(matching[0]) !== encoded(reservation(r))
1016
- )
1017
- throw new ContractError("conflict");
1018
- mutate(); // every subsequent partial failure retains the registry fence
1019
- registration = this.files.replace(
1020
- this.path("registration.json"),
1021
- registration,
1022
- encoded({ ...r, phase: "stopped" }),
1023
- );
1024
- assert();
1025
- registry = this.files.replace(
1026
- this.registryPath("roots.json"),
1027
- registry,
1028
- encoded({
1029
- ...view.value,
1030
- entries: view.value.entries.filter((row) => row.epoch !== r.epoch),
1031
- }),
1032
- REGISTRY_BYTES,
1033
- );
1034
- assert();
1035
- this.files.remove(this.path("local-capability.json"), capability);
1036
- capability = undefined;
1037
- assert();
1038
- this.files.remove(this.path("owner.lock"), owner);
1039
- owner = undefined;
1040
- assert();
1041
- // Only the exact v1 lock tied to THIS registration, never a legacy lock.
1042
- this.files.remove(this.store.lockPath, checkout, 8192);
1043
- checkout = undefined;
1044
- assert();
1045
- });
1046
- };
1047
- }
1048
- /** Private recovery identity only. Does not read/scan task records or logs.
1049
- * W3 independently supplies the affected-history digest; capability bytes and
1050
- * their hashes are deliberately absent from this recovery projection. */
1051
- recoverySnapshot(): { registration: Registration; digest: string } {
1052
- if (this.files.read(this.registryPath("registry.lock")))
1053
- throw new ContractError("quarantine");
1054
- const registry = this.registry();
1055
- const selected = this.selected();
1056
- if (
1057
- !registry ||
1058
- !selected?.value ||
1059
- !selected.registration ||
1060
- !selected.owner ||
1061
- !selected.checkout
1062
- )
1063
- refused();
1064
- const value = selected.value;
1065
- const matching = registry.value.entries.filter(
1066
- (row) => row.epoch === value.epoch,
1067
- );
1068
- if (
1069
- matching.length !== 1 ||
1070
- encoded(matching[0]) !== encoded(reservation(value))
1071
- )
1072
- refused();
1073
- return {
1074
- registration: { ...selected.value },
1075
- digest: recoveryDigest(registry, selected),
1076
- };
1077
- }
1078
770
  }
1079
771
 
1080
772
  /** Held only by the original owner. Raw-byte AND inode/time identities supplement