wehub-resource-sync
246 lines
8.6 KiB
JavaScript
246 lines
8.6 KiB
JavaScript
#!/usr/bin/env node
|
|
|
|
/**
|
|
* reserve-report-num.mjs — Atomically reserve the next report number.
|
|
*
|
|
* Fixes the race condition described in #749: when two Claude Code windows
|
|
* (or batch workers) run simultaneously they each compute `max(existing)+1`
|
|
* independently and collide on the same report-number slot.
|
|
*
|
|
* ## How it works
|
|
*
|
|
* Uses `fs.writeFileSync(path, data, { flag: 'wx' })` — which maps to
|
|
* `open(O_CREAT|O_EXCL)` on POSIX and `CreateFile(CREATE_NEW)` on Windows —
|
|
* to create a sentinel file atomically. If two processes try to claim the
|
|
* same number simultaneously only one succeeds; the loser increments and
|
|
* retries. No external lock daemon or advisory file is needed.
|
|
*
|
|
* The sentinel is a zero-byte marker named `NNN-RESERVED.md` inside
|
|
* `reports/`. The caller (mode file or agent) must:
|
|
* 1. Run this script to get a number.
|
|
* 2. Write the real report file `NNN-{slug}-{date}.md`.
|
|
* 3. Delete the sentinel (or let verify-pipeline.mjs GC it on next run).
|
|
*
|
|
* ## Usage
|
|
*
|
|
* node reserve-report-num.mjs
|
|
* # stdout: 035 (zero-padded, 3 digits)
|
|
*
|
|
* node reserve-report-num.mjs --count 8
|
|
* # stdout: 042-049 (reserves a contiguous range — for multi-agent
|
|
* # fan-outs: reserve first, hand each parallel
|
|
* # worker its own number. On collision the whole
|
|
* # range restarts past the taken slot, so skipped
|
|
* # numbers become permanent gaps — expected, not
|
|
* # corruption. Range protection follows the normal
|
|
* # sentinel TTL: reserve right before spawning.)
|
|
*
|
|
* node reserve-report-num.mjs --release 035
|
|
* node reserve-report-num.mjs --release 042-049
|
|
* # Deletes the sentinel(s) (call after writing the real report(s)).
|
|
*
|
|
* node reserve-report-num.mjs --gc
|
|
* # Removes all stale sentinels older than MAX_SENTINEL_AGE_MS.
|
|
* # Called automatically by verify-pipeline.mjs.
|
|
*
|
|
* The script exits with code 0 on success, non-zero on fatal error.
|
|
*/
|
|
|
|
import { readdirSync, writeFileSync, unlinkSync, statSync, existsSync, mkdirSync } from 'fs';
|
|
import { join, dirname } from 'path';
|
|
import { fileURLToPath } from 'url';
|
|
|
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
const REPORTS_DIR = process.env.CAREER_OPS_REPORTS_DIR || join(__dirname, 'reports');
|
|
|
|
// Sentinels older than this are considered stale and may be GC'd.
|
|
// 4 hours covers any reasonable interactive or batch session.
|
|
const MAX_SENTINEL_AGE_MS = 4 * 60 * 60 * 1000;
|
|
|
|
// Maximum number of retries before giving up (guards against pathological
|
|
// contention — in practice 2-3 parallel windows will resolve in < 5 tries).
|
|
const MAX_RETRIES = 50;
|
|
|
|
// Maximum range size for --count (guards typos like --count 800).
|
|
const MAX_COUNT = 50;
|
|
|
|
// ── helpers ─────────────────────────────────────────────────────────────────
|
|
|
|
function pad(n) {
|
|
return String(n).padStart(3, '0');
|
|
}
|
|
|
|
/** Return the highest numeric slot currently taken in reports/ (files + sentinels). */
|
|
function maxSlot() {
|
|
if (!existsSync(REPORTS_DIR)) return 0;
|
|
const entries = readdirSync(REPORTS_DIR);
|
|
let max = 0;
|
|
for (const name of entries) {
|
|
const m = name.match(/^(\d+)-/);
|
|
if (m) max = Math.max(max, parseInt(m[1], 10));
|
|
}
|
|
return max;
|
|
}
|
|
|
|
/**
|
|
* One readdir pass → Set of numeric prefixes currently occupying slots
|
|
* (e.g. "042" from "042-acme-2026-07-02.md" or "042-RESERVED.md").
|
|
* Advisory only — real atomicity comes from claimSlot's O_CREAT|O_EXCL write.
|
|
*/
|
|
function takenPrefixes() {
|
|
const taken = new Set();
|
|
if (!existsSync(REPORTS_DIR)) return taken;
|
|
for (const name of readdirSync(REPORTS_DIR)) {
|
|
const m = name.match(/^(\d+)-/);
|
|
if (m) taken.add(m[1]);
|
|
}
|
|
return taken;
|
|
}
|
|
|
|
/**
|
|
* Attempt to atomically claim slot `n`. Returns true on success.
|
|
* `taken` is an optional pre-scanned Set from takenPrefixes(); without it,
|
|
* the occupancy pre-check scans REPORTS_DIR itself. Either way the check is
|
|
* only advisory — the 'wx' write below is what guarantees atomicity.
|
|
*/
|
|
function claimSlot(n, taken = null) {
|
|
// Check if any file (real report or sentinel) already occupies this slot
|
|
const occupied = taken
|
|
? taken.has(pad(n))
|
|
: existsSync(REPORTS_DIR) && readdirSync(REPORTS_DIR).some(name => name.startsWith(`${pad(n)}-`));
|
|
if (occupied) return false;
|
|
|
|
const sentinel = join(REPORTS_DIR, `${pad(n)}-RESERVED.md`);
|
|
try {
|
|
// 'wx' = O_CREAT | O_EXCL — fails if file already exists.
|
|
writeFileSync(sentinel, '', { flag: 'wx' });
|
|
return true;
|
|
} catch (err) {
|
|
if (err.code === 'EEXIST') return false; // another process beat us
|
|
throw err; // unexpected FS error
|
|
}
|
|
}
|
|
|
|
/** Release (delete) the sentinel for slot `n`. */
|
|
function releaseSlot(n) {
|
|
const sentinel = join(REPORTS_DIR, `${pad(n)}-RESERVED.md`);
|
|
if (existsSync(sentinel)) unlinkSync(sentinel);
|
|
}
|
|
|
|
/**
|
|
* Reserve `count` contiguous slots. All-or-nothing per attempt: if any slot
|
|
* in the candidate range is already taken, release the slots claimed so far
|
|
* and restart past the collision. Each slot claim is individually atomic
|
|
* (O_CREAT|O_EXCL), which is all the pipeline needs — contiguity is an
|
|
* ergonomic property, not a correctness one. Skipped numbers become
|
|
* permanent gaps; report numbers are opaque IDs, so gaps are harmless.
|
|
* Returns the array of reserved numbers, or null if MAX_RETRIES attempts
|
|
* were exhausted. Terminates under contention: `base` strictly advances
|
|
* past every collision, so two racing ranges can never livelock.
|
|
*/
|
|
function reserveRange(count) {
|
|
let base = maxSlot() + 1;
|
|
let tries = 0;
|
|
// One directory scan per attempt, shared by every per-slot check;
|
|
// refreshed only after a collision forces a retry.
|
|
let taken = takenPrefixes();
|
|
while (tries < MAX_RETRIES) {
|
|
const claimed = [];
|
|
let failedAt = -1;
|
|
for (let n = base; n < base + count; n++) {
|
|
if (claimSlot(n, taken)) {
|
|
claimed.push(n);
|
|
} else {
|
|
failedAt = n;
|
|
break;
|
|
}
|
|
}
|
|
if (failedAt === -1) return claimed;
|
|
for (const n of claimed) releaseSlot(n);
|
|
base = failedAt + 1;
|
|
tries++;
|
|
taken = takenPrefixes();
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** GC stale sentinels (no real report was written within MAX_SENTINEL_AGE_MS). */
|
|
function gc() {
|
|
if (!existsSync(REPORTS_DIR)) return;
|
|
const now = Date.now();
|
|
let removed = 0;
|
|
for (const name of readdirSync(REPORTS_DIR)) {
|
|
if (!name.endsWith('-RESERVED.md')) continue;
|
|
const full = join(REPORTS_DIR, name);
|
|
try {
|
|
const { mtimeMs } = statSync(full);
|
|
if (now - mtimeMs > MAX_SENTINEL_AGE_MS) {
|
|
unlinkSync(full);
|
|
removed++;
|
|
process.stderr.write(`reserve-report-num: GC stale sentinel ${name}\n`);
|
|
}
|
|
} catch {
|
|
// Already gone — fine.
|
|
}
|
|
}
|
|
if (removed > 0) {
|
|
process.stderr.write(`reserve-report-num: removed ${removed} stale sentinel(s)\n`);
|
|
}
|
|
}
|
|
|
|
// ── CLI ──────────────────────────────────────────────────────────────────────
|
|
|
|
const [,, cmd, arg] = process.argv;
|
|
|
|
if (cmd === '--release') {
|
|
const m = (arg || '').match(/^(\d+)(?:-(\d+))?$/);
|
|
if (!m) {
|
|
process.stderr.write('Usage: node reserve-report-num.mjs --release <NNN>[-<MMM>]\n');
|
|
process.exit(1);
|
|
}
|
|
const start = parseInt(m[1], 10);
|
|
const end = m[2] ? parseInt(m[2], 10) : start;
|
|
if (end < start) {
|
|
process.stderr.write('reserve-report-num: --release range end must be >= start\n');
|
|
process.exit(1);
|
|
}
|
|
for (let n = start; n <= end; n++) releaseSlot(n);
|
|
process.exit(0);
|
|
}
|
|
|
|
if (cmd === '--gc') {
|
|
gc();
|
|
process.exit(0);
|
|
}
|
|
|
|
// Default (or --count N): reserve the next slot(s).
|
|
let count = 1;
|
|
if (cmd === '--count') {
|
|
if (!/^\d+$/.test(arg || '')) {
|
|
process.stderr.write(`Usage: node reserve-report-num.mjs --count <1-${MAX_COUNT}>\n`);
|
|
process.exit(1);
|
|
}
|
|
count = parseInt(arg, 10);
|
|
if (count < 1 || count > MAX_COUNT) {
|
|
process.stderr.write(`Usage: node reserve-report-num.mjs --count <1-${MAX_COUNT}>\n`);
|
|
process.exit(1);
|
|
}
|
|
}
|
|
// Any other/unknown cmd falls through to a single reserve — unchanged
|
|
// legacy behavior.
|
|
|
|
mkdirSync(REPORTS_DIR, { recursive: true });
|
|
|
|
const nums = reserveRange(count);
|
|
if (!nums) {
|
|
process.stderr.write(`reserve-report-num: could not claim ${count} slot(s) after ${MAX_RETRIES} retries\n`);
|
|
process.exit(1);
|
|
}
|
|
|
|
process.stdout.write(
|
|
count === 1
|
|
? pad(nums[0]) + '\n'
|
|
: `${pad(nums[0])}-${pad(nums[nums.length - 1])}\n`
|
|
);
|
|
process.exit(0);
|