@cortexkit/common-auth 0.27.0 → 0.28.0

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.
@@ -2,7 +2,7 @@ import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
2
2
  import type { ClaustrumScopedClient } from './custody.js';
3
3
  export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
4
4
  export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
5
- export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
5
+ export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, DEFAULT_CONNECT_TIMEOUT_MS, type SendOptions, } from './consumer.js';
6
6
  export { type AccountIdentitySource, type ClassifyingClaustrumFamily, type ClaustrumFamily, type ClaustrumFamilyInput, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, type VaultRowFacts, } from './custody.js';
7
7
  export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
8
8
  export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
@@ -13,11 +13,20 @@ export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from
13
13
  export { drainVaultQuota } from './quota-writer.js';
14
14
  export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, type ReorderVaultRosterOptions, type ReorderVaultRosterResult, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, type VaultRosterSeed, vaultRosterSeed, vaultRoutingRows, } from './roster.js';
15
15
  export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
16
+ /** How long `connectClaustrumScopedClient` waits by default. */
17
+ export declare const SCOPED_CONNECT_TIMEOUT_MS = 10000;
16
18
  /**
17
19
  * Connect the client that lists and fetches this consumer's vault credentials
18
20
  * on the request path. `connectionFile` is required: this library
19
21
  * reads no environment, so the plugin resolves the vault's connection file.
22
+ *
23
+ * The wait is bounded by `connectTimeoutMs` (default 10 s) so a connect that
24
+ * never settles cannot leave a consumer with a pending connection forever; the
25
+ * caller then gets an unreachable error and may try again. A socket handshake
26
+ * has its own limit, but local reads before it (the connection file) do not,
27
+ * and a client that arrives after this deadline is closed, not returned.
20
28
  */
21
29
  export declare function connectClaustrumScopedClient(options: ClaustrumClientOptions & {
22
30
  connectionFile: string;
31
+ connectTimeoutMs?: number;
23
32
  }): Promise<ClaustrumScopedClient>;
@@ -4,10 +4,11 @@
4
4
  // declined-account interlock and the host-slot guard. Needs the optional
5
5
  // peer `@cortexkit/claustrum-client`.
6
6
  import { ClaustrumClient, } from '@cortexkit/claustrum-client';
7
+ import { ClaustrumUnreachableError } from './availability.js';
7
8
  import { insulaUsageTransport } from './insula.js';
8
9
  export { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
9
10
  export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, } from './availability.js';
10
- export { ClaustrumConsumer, } from './consumer.js';
11
+ export { ClaustrumConsumer, DEFAULT_CONNECT_TIMEOUT_MS, } from './consumer.js';
11
12
  export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, SERVING_MARGIN_MS, } from './custody.js';
12
13
  export { ClaustrumEnrollmentManager, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
13
14
  export { ClaustrumConsumerError, } from './errors.js';
@@ -18,12 +19,43 @@ export { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
18
19
  export { drainVaultQuota } from './quota-writer.js';
19
20
  export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, resolveVaultPrimary, vaultRosterSeed, vaultRoutingRows, } from './roster.js';
20
21
  export { ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, WATCH_RETRY_MS, } from './watch.js';
22
+ /** How long `connectClaustrumScopedClient` waits by default. */
23
+ export const SCOPED_CONNECT_TIMEOUT_MS = 10_000;
21
24
  /**
22
25
  * Connect the client that lists and fetches this consumer's vault credentials
23
26
  * on the request path. `connectionFile` is required: this library
24
27
  * reads no environment, so the plugin resolves the vault's connection file.
28
+ *
29
+ * The wait is bounded by `connectTimeoutMs` (default 10 s) so a connect that
30
+ * never settles cannot leave a consumer with a pending connection forever; the
31
+ * caller then gets an unreachable error and may try again. A socket handshake
32
+ * has its own limit, but local reads before it (the connection file) do not,
33
+ * and a client that arrives after this deadline is closed, not returned.
25
34
  */
26
35
  export async function connectClaustrumScopedClient(options) {
27
- const client = await ClaustrumClient.connect(options);
28
- return Object.assign(client, { insula: insulaUsageTransport(options) });
36
+ const { connectTimeoutMs, ...client } = options;
37
+ const limit = connectTimeoutMs ?? SCOPED_CONNECT_TIMEOUT_MS;
38
+ const connecting = ClaustrumClient.connect(client);
39
+ let expired = false;
40
+ let timer;
41
+ const deadline = new Promise((_resolve, reject) => {
42
+ timer = setTimeout(() => {
43
+ expired = true;
44
+ reject(new ClaustrumUnreachableError());
45
+ }, limit);
46
+ timer.unref?.();
47
+ });
48
+ try {
49
+ const client = await Promise.race([connecting, deadline]);
50
+ return Object.assign(client, { insula: insulaUsageTransport(options) });
51
+ }
52
+ catch (error) {
53
+ // A connection that arrives after the deadline still owns a socket.
54
+ void connecting.then((client) => client.close(), () => { });
55
+ throw error;
56
+ }
57
+ finally {
58
+ if (!expired && timer)
59
+ clearTimeout(timer);
60
+ }
29
61
  }
@@ -1,3 +1,4 @@
1
+ import { type QuotaCommitTimer } from '../quota/commit-interval.js';
1
2
  import { type QuotaObservation } from '../quota/index.js';
2
3
  import { type QuotaReceipt, type VaultRosterFile } from './roster.js';
3
4
  export type VaultQuotaPublication = {
@@ -8,11 +9,17 @@ export type VaultQuotaPublication = {
8
9
  };
9
10
  type Listener = (publication: VaultQuotaPublication) => void;
10
11
  /** Retain the shared writer; the last consumer's close drains it. */
11
- export declare function retainVaultQuotaWriter(path: string, listener: Listener): () => Promise<void>;
12
+ export declare function retainVaultQuotaWriter(path: string, listener: Listener, clock?: QuotaCommitTimer): () => Promise<void>;
12
13
  /** Enqueue without filesystem work; each quota field retains its own receipt fence. */
13
14
  export declare function enqueueVaultQuota(path: string, publication: VaultQuotaPublication): Promise<boolean>;
14
15
  /** Overlay uncommitted observations when a consumer reloads the durable roster. */
15
16
  export declare function pendingVaultQuota(path: string, roster: VaultRosterFile | undefined): VaultRosterFile | undefined;
17
+ /**
18
+ * Whether this process holds quota readings for `path` that no commit of the
19
+ * durable roster has written yet, so a reader of the file alone is not seeing
20
+ * everything this process would publish.
21
+ */
22
+ export declare function hasPendingVaultQuota(path: string): boolean;
16
23
  /** Wait at most timeoutMs for detached publication; shutdown loss is acceptable. */
17
24
  export declare function drainVaultQuota(path: string, timeoutMs?: number): Promise<void>;
18
25
  export {};
@@ -1,5 +1,6 @@
1
1
  import { resolve } from 'node:path';
2
2
  import { createLogger } from '../logger/index.js';
3
+ import { QUOTA_COMMIT_INTERVAL_MS, quotaCommitTimer, } from '../quota/commit-interval.js';
3
4
  import { isQuotaObservation } from '../quota/index.js';
4
5
  import { quotaFields } from '../quota/pending.js';
5
6
  import { applyVaultQuota, mutateVaultRoster, } from './roster.js';
@@ -7,7 +8,7 @@ import { applyVaultQuota, mutateVaultRoster, } from './roster.js';
7
8
  const writers = new Map();
8
9
  const logger = createLogger('claustrum');
9
10
  const COALESCE_MS = 100;
10
- function writerFor(path) {
11
+ function writerFor(path, clock = quotaCommitTimer) {
11
12
  const key = resolve(path);
12
13
  let writer = writers.get(key);
13
14
  if (!writer) {
@@ -17,6 +18,7 @@ function writerFor(path) {
17
18
  listeners: new Set(),
18
19
  wake: new Set(),
19
20
  abort: new AbortController(),
21
+ clock,
20
22
  failures: 0,
21
23
  draining: false,
22
24
  order: 0,
@@ -26,8 +28,8 @@ function writerFor(path) {
26
28
  return writer;
27
29
  }
28
30
  /** Retain the shared writer; the last consumer's close drains it. */
29
- export function retainVaultQuotaWriter(path, listener) {
30
- const writer = writerFor(path);
31
+ export function retainVaultQuotaWriter(path, listener, clock) {
32
+ const writer = writerFor(path, clock);
31
33
  writer.listeners.add(listener);
32
34
  let released;
33
35
  return () => (released ??= (() => {
@@ -93,37 +95,57 @@ export function pendingVaultQuota(path, roster) {
93
95
  }
94
96
  return roster;
95
97
  }
98
+ /**
99
+ * Whether this process holds quota readings for `path` that no commit of the
100
+ * durable roster has written yet, so a reader of the file alone is not seeing
101
+ * everything this process would publish.
102
+ */
103
+ export function hasPendingVaultQuota(path) {
104
+ return !!writers.get(resolve(path))?.pending.size;
105
+ }
96
106
  function schedule(writer, delay) {
97
107
  if (writer.running ||
98
108
  writer.timer ||
99
109
  !writer.pending.size ||
100
110
  writer.abort.signal.aborted)
101
111
  return;
102
- writer.timer = setTimeout(() => {
112
+ const remaining = writer.draining
113
+ ? 0
114
+ : (writer.committedAt ?? -Infinity) +
115
+ QUOTA_COMMIT_INTERVAL_MS -
116
+ writer.clock.now();
117
+ writer.timer = writer.clock.schedule(Math.max(delay, remaining), () => {
103
118
  writer.timer = undefined;
104
- flush(writer);
105
- }, delay);
119
+ return flush(writer);
120
+ });
106
121
  if (!writer.draining)
107
122
  writer.timer.unref?.();
108
123
  }
124
+ function cancelTimer(writer) {
125
+ writer.timer?.cancel();
126
+ writer.timer = undefined;
127
+ }
109
128
  function flush(writer) {
110
129
  if (writer.running || writer.abort.signal.aborted)
111
- return;
130
+ return writer.running ?? Promise.resolve();
112
131
  const batch = new Map([...writer.pending].map(([account, pending]) => [
113
132
  account,
114
133
  new Map(pending),
115
134
  ]));
116
135
  writer.running = (async () => {
117
136
  try {
118
- await mutateVaultRoster(writer.path, (current) => {
137
+ const committed = await mutateVaultRoster(writer.path, (current) => {
119
138
  let next = current;
120
139
  for (const field of orderedFields(batch)) {
121
140
  if (field.priorReading)
122
141
  next = applyVaultQuota(next, field.priorReading).roster;
123
142
  next = applyVaultQuota(next, field.publication).roster;
124
143
  }
125
- return { ...(next !== current && { next }), result: undefined };
144
+ const changed = JSON.stringify(next) !== JSON.stringify(current);
145
+ return { ...(changed && { next }), result: changed };
126
146
  }, { signal: writer.abort.signal });
147
+ if (committed)
148
+ writer.committedAt = writer.clock.now();
127
149
  for (const [account, fields] of batch) {
128
150
  const pending = writer.pending.get(account);
129
151
  for (const [key, field] of fields) {
@@ -155,6 +177,7 @@ function flush(writer) {
155
177
  schedule(writer, backoff);
156
178
  }
157
179
  })();
180
+ return writer.running;
158
181
  }
159
182
  /** Wait at most timeoutMs for detached publication; shutdown loss is acceptable. */
160
183
  export async function drainVaultQuota(path, timeoutMs = 1_000) {
@@ -163,8 +186,7 @@ export async function drainVaultQuota(path, timeoutMs = 1_000) {
163
186
  if (!writer)
164
187
  return;
165
188
  writer.draining = true;
166
- clearTimeout(writer.timer);
167
- writer.timer = undefined;
189
+ cancelTimer(writer);
168
190
  let deadline;
169
191
  let wake;
170
192
  const drained = new Promise((done) => {
@@ -194,7 +216,7 @@ export async function drainVaultQuota(path, timeoutMs = 1_000) {
194
216
  // must not discard its observations or stop its retries.
195
217
  if (!writer.listeners.size) {
196
218
  writer.abort.abort();
197
- clearTimeout(writer.timer);
219
+ cancelTimer(writer);
198
220
  writer.pending.clear();
199
221
  if (writers.get(key) === writer)
200
222
  writers.delete(key);
@@ -231,7 +231,8 @@ export declare function isVaultRosterLockRefusal(path: string, error: unknown):
231
231
  * failed list, or custody switching off mid-run, never writes anything; a
232
232
  * peer holding the lease means its last committed roster is served instead.
233
233
  * A write-lock timeout keeps the discovered inventory for the next poll,
234
- * unless a peer has superseded its base view in the meantime.
234
+ * unless a peer has superseded its base view in the meantime. A list that
235
+ * would write the file the roster already holds takes no write lock at all.
235
236
  */
236
237
  export declare function refreshVaultRoster(options: {
237
238
  path: string;
@@ -1,11 +1,12 @@
1
1
  import { createHash } from 'node:crypto';
2
+ import { stat } from 'node:fs/promises';
2
3
  import { resolve } from 'node:path';
3
4
  import { acquireRefreshFileLock, LockContentionError, LockOwnershipError, lockPathFor, PrivateFileError, withLock, writeJsonAtomic, } from '../fs/index.js';
4
5
  import { readPrivateText, windowsPrivateFiles } from '../fs/private-files.js';
5
6
  import { decodeQuotaMap, isQuotaObservation, mergeQuotaObservation, } from '../quota/index.js';
6
7
  import { ClaustrumConsumerError } from './errors.js';
7
8
  import { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
8
- import { enqueueVaultQuota, pendingVaultQuota, } from './quota-writer.js';
9
+ import { enqueueVaultQuota, hasPendingVaultQuota, pendingVaultQuota, } from './quota-writer.js';
9
10
  export { drainVaultQuota } from './quota-writer.js';
10
11
  /** Declines and account order of `roster`, and nothing else of it. */
11
12
  export function vaultRosterSeed(roster) {
@@ -624,6 +625,75 @@ export function isVaultRosterLockRefusal(path, error) {
624
625
  }
625
626
  return false;
626
627
  }
628
+ const UNLOCKED_READ_ATTEMPTS = 4;
629
+ /**
630
+ * What identifies one version of the file at `path`: the roster is always
631
+ * replaced by a rename, so any write gives it a different inode, and an
632
+ * in-place rewrite a different size or modification time. Undefined when it
633
+ * cannot be inspected, which callers must read as 'may have changed'.
634
+ */
635
+ async function fileStamp(path) {
636
+ try {
637
+ const { dev, ino, size, mtimeMs } = await stat(path);
638
+ return { dev, ino, size, mtimeMs };
639
+ }
640
+ catch {
641
+ return undefined;
642
+ }
643
+ }
644
+ /** Whether two `fileStamp` readings are of the same file version. */
645
+ function sameFileStamp(left, right) {
646
+ return (left !== undefined &&
647
+ right !== undefined &&
648
+ left.dev === right.dev &&
649
+ left.ino === right.ino &&
650
+ left.size === right.size &&
651
+ left.mtimeMs === right.mtimeMs);
652
+ }
653
+ /**
654
+ * Whether a roster list that lands unlocked would write exactly the file at
655
+ * `path`. `overlay` names what this process holds besides the file: `target` is
656
+ * the file's own roster, which the locked commit compares against, and `local`,
657
+ * when different, is that roster plus unwritten quota readings, which must
658
+ * equal the commit's result too. Both must equal `next(target)`'s bytes, which
659
+ * is the write the commit would make; any difference, a missing or unreadable
660
+ * file, or a read that a concurrent reader keeps changing all mean 'commit'.
661
+ */
662
+ async function readUnlockedCommitTarget(path, overlay, next) {
663
+ for (let attempt = 0; attempt < UNLOCKED_READ_ATTEMPTS; attempt++) {
664
+ // Roster files are replaced by rename, so each attempt reads one whole
665
+ // file either way.
666
+ const before = await fileStamp(path);
667
+ const current = await readVaultRoster(path);
668
+ let target;
669
+ let local;
670
+ let changed;
671
+ try {
672
+ ;
673
+ ({ target, local } = overlay(current));
674
+ const written = JSON.stringify(next(target));
675
+ changed =
676
+ JSON.stringify(target) !== written ||
677
+ (local !== undefined && JSON.stringify(local) !== written);
678
+ }
679
+ catch {
680
+ return 'commit';
681
+ }
682
+ // No lock was taken, so another writer may have replaced the file while
683
+ // it was being projected. The answer must describe the file as it is now,
684
+ // otherwise a later list of the same roster would find it changed again.
685
+ if (!sameFileStamp(before, await fileStamp(path)))
686
+ continue;
687
+ if (changed)
688
+ return 'commit';
689
+ // Quota readings this process enqueued while the file was being projected
690
+ // are not part of `current`, and a list that returns unchanged while they
691
+ // wait would be the only chance to serve them as this list's roster. They
692
+ // keep their own commit either way, so this path takes the locked one.
693
+ return hasPendingVaultQuota(path) ? 'commit' : 'unchanged';
694
+ }
695
+ return 'commit';
696
+ }
627
697
  /**
628
698
  * Discover and commit the roster. The lease covers the list call and the
629
699
  * commit, not just the write: an opaque view cannot tell a delayed old reply
@@ -631,7 +701,8 @@ export function isVaultRosterLockRefusal(path, error) {
631
701
  * failed list, or custody switching off mid-run, never writes anything; a
632
702
  * peer holding the lease means its last committed roster is served instead.
633
703
  * A write-lock timeout keeps the discovered inventory for the next poll,
634
- * unless a peer has superseded its base view in the meantime.
704
+ * unless a peer has superseded its base view in the meantime. A list that
705
+ * would write the file the roster already holds takes no write lock at all.
635
706
  */
636
707
  export async function refreshVaultRoster(options) {
637
708
  options.signal?.throwIfAborted();
@@ -671,8 +742,44 @@ export async function refreshVaultRoster(options) {
671
742
  };
672
743
  pendingDiscoveries.delete(key);
673
744
  const { inventory } = discovered;
674
- options.onInventory?.(inventory);
745
+ // Called, not awaited: a caller noting the list here may wait for this
746
+ // roster's write lock, and this refresh decides below whether it needs it.
747
+ void options.onInventory?.(inventory);
675
748
  options.signal?.throwIfAborted();
749
+ const projection = typeof options.projection === 'function'
750
+ ? options.projection()
751
+ : options.projection;
752
+ const next = (current) => projectVaultRoster(current, inventory, projection);
753
+ const isActive = async () => {
754
+ options.signal?.throwIfAborted();
755
+ await lease.assertOwned();
756
+ return active();
757
+ };
758
+ // The write lock costs a lock file, an eviction marker and staging files in
759
+ // the roster's directory on every poll, so it is skipped when the list
760
+ // would write the file that is already there. The read deciding that takes
761
+ // no lock: a writer that commits between the read and this decision only
762
+ // makes our comparison stale, and a stale comparison never writes (the
763
+ // commit below judges the file again under the lock). Only equality with
764
+ // every byte the commit would write skips; every other answer commits.
765
+ const decision = await readUnlockedCommitTarget(options.path, (current) => {
766
+ // A hub member listed over a base view of its file: the file's own view
767
+ // is what the commit compares, so the overlay is the plain file. The
768
+ // locked commit below still applies the base-view rule.
769
+ if (listedOver)
770
+ return { target: current };
771
+ // This process's unwritten quota readings are part of the roster it
772
+ // serves, so a list that matches everything but them still commits.
773
+ const local = pendingVaultQuota(options.path, current);
774
+ return { target: current, ...(local !== current && { local }) };
775
+ }, next);
776
+ if (decision === 'unchanged') {
777
+ if (!(await isActive()))
778
+ return undefined;
779
+ // Returned as a later read of the file: that is what today's locked
780
+ // unchanged commit returns, and memory keeps only what was committed.
781
+ return await readVaultRoster(options.path);
782
+ }
676
783
  return await mutateVaultRoster(options.path, async (current) => {
677
784
  if (!(await active()))
678
785
  return { result: undefined };
@@ -682,12 +789,9 @@ export async function refreshVaultRoster(options) {
682
789
  current?.view !== listedOver.view &&
683
790
  current?.view !== inventory.view)
684
791
  return { result: current };
685
- const projection = typeof options.projection === 'function'
686
- ? options.projection()
687
- : options.projection;
688
- const next = projectVaultRoster(current, inventory, projection);
689
- const changed = JSON.stringify(current) !== JSON.stringify(next);
690
- return { ...(changed && { next }), result: next };
792
+ const projected = next(current);
793
+ const changed = JSON.stringify(current) !== JSON.stringify(projected);
794
+ return { ...(changed && { next: projected }), result: projected };
691
795
  }, {
692
796
  signal: options.signal,
693
797
  beforePublish: async () => {
@@ -0,0 +1,8 @@
1
+ import type { Stats } from 'node:fs';
2
+ type FileIdentity = Stats | 'absent';
3
+ /** Process-local reads, capped at 64 path sets with one value per resolved set. */
4
+ export declare class FileReadCache<T> {
5
+ #private;
6
+ read(paths: readonly string[], read: (resolvedPaths: string[]) => Promise<T>, validateHit?: (identities: readonly FileIdentity[]) => void): Promise<T>;
7
+ }
8
+ export {};
@@ -0,0 +1,57 @@
1
+ import { lstat } from 'node:fs/promises';
2
+ import { resolve } from 'node:path';
3
+ async function identity(path) {
4
+ try {
5
+ const metadata = await lstat(path);
6
+ // Do not follow a symlink: its target can change without changing the link.
7
+ return metadata.isFile() ? metadata : undefined;
8
+ }
9
+ catch (error) {
10
+ return error.code === 'ENOENT'
11
+ ? 'absent'
12
+ : undefined;
13
+ }
14
+ }
15
+ function sameIdentity(left, right) {
16
+ if (left === 'absent' || right === 'absent')
17
+ return left === right;
18
+ return (left.dev === right.dev &&
19
+ left.ino === right.ino &&
20
+ left.size === right.size &&
21
+ left.mtimeMs === right.mtimeMs &&
22
+ left.ctimeMs === right.ctimeMs);
23
+ }
24
+ /** Process-local reads, capped at 64 path sets with one value per resolved set. */
25
+ export class FileReadCache {
26
+ #entries = new Map();
27
+ async read(paths, read, validateHit) {
28
+ const resolvedPaths = paths.map((path) => resolve(path));
29
+ const key = JSON.stringify(resolvedPaths);
30
+ const probed = await Promise.all(resolvedPaths.map(identity));
31
+ const identities = probed.every((entry) => entry !== undefined)
32
+ ? probed
33
+ : undefined;
34
+ const cached = this.#entries.get(key);
35
+ if (identities &&
36
+ cached &&
37
+ identities.every((entry, index) => {
38
+ const previous = cached.identities[index];
39
+ return previous !== undefined && sameIdentity(entry, previous);
40
+ })) {
41
+ validateHit?.(identities);
42
+ return cached.value;
43
+ }
44
+ // A failed probe or read must not leave a previous successful value reusable.
45
+ this.#entries.delete(key);
46
+ const value = await read(resolvedPaths);
47
+ if (identities) {
48
+ if (this.#entries.size >= 64) {
49
+ const oldest = this.#entries.keys().next().value;
50
+ if (oldest !== undefined)
51
+ this.#entries.delete(oldest);
52
+ }
53
+ this.#entries.set(key, { identities, value });
54
+ }
55
+ return value;
56
+ }
57
+ }
@@ -358,8 +358,19 @@ export async function acquireRefreshFileLockWithClock(options) {
358
358
  return 'missing';
359
359
  throw error;
360
360
  }
361
- if (windowsPrivateFiles)
362
- await verifyPrivate(evictPath, 'directory', true);
361
+ if (windowsPrivateFiles) {
362
+ try {
363
+ await verifyPrivate(evictPath, 'directory', true);
364
+ }
365
+ catch (error) {
366
+ // The marker's holder can remove it between the stat above and this
367
+ // check. Absence means the marker is free, as when the stat finds
368
+ // nothing; every other refusal still escapes.
369
+ if (error.code === 'ENOENT')
370
+ return 'missing';
371
+ throw error;
372
+ }
373
+ }
363
374
  if (evictStat.mtimeMs + EVICT_TTL > now())
364
375
  return 'fresh';
365
376
  if (options.onStep)
@@ -386,11 +397,13 @@ export async function acquireRefreshFileLockWithClock(options) {
386
397
  catch (error) {
387
398
  if (error.code === 'EEXIST') {
388
399
  if (windowsPrivateFiles) {
389
- await verifyPrivate(evictPath, 'directory', true);
390
400
  try {
401
+ await verifyPrivate(evictPath, 'directory', true);
391
402
  await readPrivateText(evictOwnerPath, true);
392
403
  }
393
404
  catch (ownerError) {
405
+ // A marker removed by its holder after the failed create is free:
406
+ // report it as unavailable for now so the caller retries.
394
407
  if (ownerError.code !== 'ENOENT')
395
408
  throw ownerError;
396
409
  }
@@ -0,0 +1,9 @@
1
+ export declare const QUOTA_COMMIT_INTERVAL_MS = 30000;
2
+ export interface QuotaCommitTimer {
3
+ now(): number;
4
+ schedule(delayMs: number, run: () => Promise<void>): {
5
+ cancel(): void;
6
+ unref?(): void;
7
+ };
8
+ }
9
+ export declare const quotaCommitTimer: QuotaCommitTimer;
@@ -0,0 +1,18 @@
1
+ // Atomic quota commits create locks, markers and a renamed temp file. Keep
2
+ // those filesystem events at least 30 s apart under normal load; routing sees
3
+ // pending readings immediately, while other processes may lag by one interval.
4
+ // Shutdown drains and a full bounded pool queue can commit sooner.
5
+ // The vault shares one gate per resolved path; each pool handle has its own.
6
+ // N pool handles on one file can therefore make N normal commits per interval
7
+ // in one process. These gates do not coordinate with other processes.
8
+ export const QUOTA_COMMIT_INTERVAL_MS = 30_000;
9
+ export const quotaCommitTimer = {
10
+ now: () => performance.now(),
11
+ schedule(delayMs, run) {
12
+ const timer = setTimeout(() => void run(), delayMs);
13
+ return {
14
+ cancel: () => clearTimeout(timer),
15
+ unref: () => timer.unref?.(),
16
+ };
17
+ },
18
+ };
@@ -5,57 +5,12 @@ import { recordSetupEnrollment, setupEnrollmentLine } from './command-error.js';
5
5
  import { defaultCommandRunner } from './command-runner.js';
6
6
  import { detectHosts } from './detect.js';
7
7
  import { connectSetupHost, HostNotEnrolledError } from './enroll.js';
8
+ import { parseSetupFlags, UNAVAILABLE_HOST_MESSAGE } from './flags.js';
8
9
  import { setupPaths } from './paths.js';
9
10
  import { assertHostsStopped, createProcessFence, ProcessFenceViolationError, ProcessInspectionError, } from './process-fence.js';
10
11
  import { selectSetupHosts } from './prompts.js';
11
12
  import { planOpenCodeRegistration, registerOpenCode, registerPi, } from './register.js';
12
13
  export const AMBIGUOUS_OPENCODE_MESSAGE = 'Multiple OpenCode generations found. Choose --opencode=1|2|both before running noninteractive setup.';
13
- const UNAVAILABLE_HOST_MESSAGE = 'Requested setup host is unknown or unavailable. Use --host=opencode or --host=pi with a detected host.';
14
- function flags(argv) {
15
- const result = {
16
- yes: false,
17
- dryRun: false,
18
- claustrum: false,
19
- noClaustrum: false,
20
- login: false,
21
- enrollOnly: false,
22
- hosts: [],
23
- opencode: undefined,
24
- };
25
- for (const arg of argv) {
26
- if (arg === '--yes')
27
- result.yes = true;
28
- else if (arg === '--dry-run')
29
- result.dryRun = true;
30
- else if (arg === '--claustrum')
31
- result.claustrum = true;
32
- else if (arg === '--no-claustrum')
33
- result.noClaustrum = true;
34
- else if (arg === '--login')
35
- result.login = true;
36
- else if (arg === '--enroll-only')
37
- result.enrollOnly = true;
38
- else if (arg.startsWith('--host=')) {
39
- const host = arg.slice('--host='.length);
40
- if (host !== 'opencode' && host !== 'pi')
41
- throw new Error(UNAVAILABLE_HOST_MESSAGE);
42
- result.hosts.push(host);
43
- }
44
- else if (/^--opencode=(1|2|both)$/.test(arg))
45
- result.opencode = arg.slice('--opencode='.length);
46
- else
47
- throw new Error(`Unknown setup argument: ${arg}`);
48
- }
49
- if (result.claustrum && result.noClaustrum)
50
- throw new Error('--claustrum and --no-claustrum cannot be used together.');
51
- if (result.login && result.claustrum)
52
- throw new Error('--login and --claustrum cannot be used together.');
53
- if (result.enrollOnly && result.login)
54
- throw new Error('--enroll-only and --login cannot be used together.');
55
- if (result.enrollOnly && result.noClaustrum)
56
- throw new Error('--enroll-only and --no-claustrum cannot be used together.');
57
- return result;
58
- }
59
14
  function validatePlugin(plugin) {
60
15
  for (const pkg of Object.values(plugin.packages)) {
61
16
  if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(pkg))
@@ -92,7 +47,7 @@ async function enrollmentReport(plugin, hosts, recorded) {
92
47
  return report;
93
48
  }
94
49
  export async function runSetup(plugin, argv = [], io = {}) {
95
- const options = flags(argv);
50
+ const options = parseSetupFlags(argv);
96
51
  validatePlugin(plugin);
97
52
  const terminal = io.terminal ?? processTerminal();
98
53
  const detection = await detectHosts(plugin, io);
@@ -234,7 +189,7 @@ export async function runSetup(plugin, argv = [], io = {}) {
234
189
  printLine(terminal, `${write.changed ? 'Would write' : 'Unchanged'} ${write.path}:\n${write.content}`);
235
190
  if (!options.enrollOnly && hosts.includes('pi'))
236
191
  printLine(terminal, `Would run ${detection.pi.executable} install npm:${plugin.packages.pi}@${plugin.version}`);
237
- if (!options.enrollOnly)
192
+ if (!options.enrollOnly && plugin.migrate)
238
193
  for (const host of hosts)
239
194
  printLine(terminal, `Would migrate ${host} using the plugin callback (provider-specific writes).`);
240
195
  }
@@ -277,7 +232,7 @@ export async function runSetup(plugin, argv = [], io = {}) {
277
232
  else
278
233
  await registerPi(plugin, detection.pi.executable, io);
279
234
  await stopped();
280
- await plugin.migrate(host, context);
235
+ await plugin.migrate?.(host, context);
281
236
  }
282
237
  }
283
238
  catch (error) {