File size: 4,968 Bytes
311fa35 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | import * as fs from "node:fs";
import * as path from "node:path";
export interface IdempotencyRecord {
key: string;
jobId: string;
createdAt: string;
}
export type IdempotencyReservation =
| { reserved: true; record: IdempotencyRecord }
| { reserved: false; record: IdempotencyRecord };
export interface IdempotencyStore {
/** Look up a key. Records whose job directory no longer exists are pruned. */
get(key: string): IdempotencyRecord | null;
/** Atomically reserve a key for a job. Returns the existing record on conflict. */
reserve(key: string, jobId: string): IdempotencyReservation;
/** Remove a key (used when enqueueing fails). */
release(key: string): void;
/** Remove every key that points at a deleted job. */
removeJob(jobId: string): void;
/** All live records, for diagnostics. */
list(): IdempotencyRecord[];
}
interface IdempotencyFile {
version: 1;
records: Record<string, IdempotencyRecord>;
}
const FILE_NAME = ".idempotency.json";
/**
* A reservation is written before the job directory exists. Only prune records
* whose job directory has been missing for longer than this grace period, so an
* in-flight reservation is never mistaken for a stale one.
*/
const STALE_AFTER_MS = 10 * 60 * 1000;
function emptyFile(): IdempotencyFile {
return { version: 1, records: {} };
}
function isRecord(value: unknown): value is IdempotencyRecord {
if (!value || typeof value !== "object") return false;
const record = value as Record<string, unknown>;
return (
typeof record["key"] === "string" &&
typeof record["jobId"] === "string" &&
typeof record["createdAt"] === "string"
);
}
function readFile(file: string): IdempotencyFile {
try {
const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf-8"));
if (!parsed || typeof parsed !== "object") return emptyFile();
const records = (parsed as { records?: unknown }).records;
if (!records || typeof records !== "object") return emptyFile();
const clean: Record<string, IdempotencyRecord> = {};
for (const [key, value] of Object.entries(records as Record<string, unknown>)) {
if (isRecord(value) && value.key === key) clean[key] = value;
}
return { version: 1, records: clean };
} catch {
// Missing or corrupt files are treated as empty. Never crash the API.
return emptyFile();
}
}
function writeFile(file: string, data: IdempotencyFile): void {
fs.mkdirSync(path.dirname(file), { recursive: true });
const tmp = `${file}.tmp`;
fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
fs.renameSync(tmp, file);
}
/**
* File-backed idempotency-key store.
*
* The API server is a single process, so synchronous read-modify-write is
* atomic enough for reserve(). Writes use tmp+rename so a crash cannot leave
* a truncated JSON file behind.
*/
export function createIdempotencyStore(jobsDir: string): IdempotencyStore {
const file = path.join(jobsDir, FILE_NAME);
function isStale(record: IdempotencyRecord): boolean {
if (fs.existsSync(path.join(jobsDir, record.jobId))) return false;
const createdAt = Date.parse(record.createdAt);
if (Number.isNaN(createdAt)) return true;
return Date.now() - createdAt > STALE_AFTER_MS;
}
function pruneStale(data: IdempotencyFile, keepKey?: string): boolean {
let changed = false;
for (const [key, record] of Object.entries(data.records)) {
if (key === keepKey) continue;
if (isStale(record)) {
delete data.records[key];
changed = true;
}
}
return changed;
}
return {
get(key) {
const data = readFile(file);
const record = data.records[key];
if (!record) return null;
if (isStale(record)) {
delete data.records[key];
writeFile(file, data);
return null;
}
return record;
},
reserve(key, jobId) {
const data = readFile(file);
const existing = data.records[key];
if (existing && !isStale(existing)) {
return { reserved: false, record: existing };
}
const record: IdempotencyRecord = {
key,
jobId,
createdAt: new Date().toISOString(),
};
data.records[key] = record;
pruneStale(data, key);
writeFile(file, data);
return { reserved: true, record };
},
release(key) {
const data = readFile(file);
if (!data.records[key]) return;
delete data.records[key];
writeFile(file, data);
},
removeJob(jobId) {
const data = readFile(file);
let changed = false;
for (const [key, record] of Object.entries(data.records)) {
if (record.jobId === jobId) {
delete data.records[key];
changed = true;
}
}
if (changed) writeFile(file, data);
},
list() {
const data = readFile(file);
if (pruneStale(data)) writeFile(file, data);
return Object.values(data.records);
},
};
}
|