@ciphore/radiocli 0.2.4 → 0.2.6

package/dist/providers/cache.js

@@ -1,91 +1,287 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { platformPaths } from '../platform/paths.js';
+import { parseJsonAsync, stringifyJsonAsync } from '../platform/json-worker.js';
 import { join } from 'node:path';
 const maxCacheEntries = 256;
 const maxCacheBytes = 128 * 1024 * 1024;
+// Permit small timestamp skew between writers, but never extend freshness by
+// hours or days after a system clock correction.
+const maxFutureClockSkewMs = 1000;
 export class ProviderCache {
     filePath;
-    cache;
-    writesSincePrune = 0;
-    constructor(filePath = defaultProviderCachePath()) {
+    options;
+    cache = { version: 1, entries: Object.create(null) };
+    // This set is tied to retained entries; eviction must allow disk reads again.
+    checkedShards = new Set();
+    entrySizes = new Map();
+    memoryBytes = 0;
+    legacyAbsent = false;
+    legacyLoadPromise = null;
+    pendingShardReads = new Map();
+    pendingWrites = new Map();
+    pendingWriteCount = 0;
+    prunePromise = Promise.resolve();
+    constructor(filePath = defaultProviderCachePath(), options = {}) {
         this.filePath = filePath;
-        this.cache = this.read();
+        this.options = options;
     }
     get(key, maxAgeMs) {
-        const entry = this.cache.entries[key] ?? this.readShard(key);
-        if (!entry) {
-            return null;
-        }
-        if (Date.now() - entry.createdAt > maxAgeMs) {
-            return null;
-        }
-        return entry.value;
+        const entry = this.loadEntry(key);
+        return entry && withinAge(entry, maxAgeMs) ? entry.value : null;
     }
     getStale(key, maxAgeMs = 30 * 24 * 60 * 60 * 1000) {
-        const entry = this.cache.entries[key] ?? this.readShard(key);
-        return entry && Date.now() - entry.createdAt <= maxAgeMs ? entry.value : null;
+        return this.get(key, maxAgeMs);
+    }
+    async getAsync(key, maxAgeMs) {
+        // A caller reading during a refresh observes the completed newest write.
+        await this.pendingWrites.get(key)?.catch(() => undefined);
+        const entry = this.memoryEntry(key) ?? await this.loadEntryAsync(key);
+        return entry && withinAge(entry, maxAgeMs) ? entry.value : null;
+    }
+    getStaleAsync(key, maxAgeMs = 30 * 24 * 60 * 60 * 1000) {
+        return this.getAsync(key, maxAgeMs);
     }
     set(key, value) {
-        this.cache.entries[key] = { createdAt: Date.now(), value };
-        this.writeEntry(key, this.cache.entries[key]);
+        if (this.pendingWrites.has(key))
+            throw new Error('Provider cache is refreshing this entry. Use setAsync to keep writes ordered.');
+        const read = this.pendingShardReads.get(key);
+        if (read)
+            read.invalidated = true;
+        const entry = { createdAt: Date.now(), value };
+        const serialized = JSON.stringify({ version: 1, key, ...entry });
+        this.remember(key, entry, retainedBytes(serialized));
+        const directory = this.shardDirectory();
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        writeAtomically(this.shardPath(key), serialized);
+        this.pruneShards(directory);
+    }
+    async setAsync(key, value) {
+        if (this.pendingWriteCount >= (this.options.maxPendingOperations ?? 16))
+            throw new Error('Provider cache write capacity reached.');
+        const entry = { createdAt: Date.now(), value };
+        const read = this.pendingShardReads.get(key);
+        if (read)
+            read.invalidated = true;
+        this.pendingWriteCount += 1;
+        const previous = this.pendingWrites.get(key) ?? Promise.resolve();
+        const pending = previous.catch(() => undefined).then(async () => {
+            const serialized = await stringifyJsonAsync({ version: 1, key, ...entry }, isLargeValue(value));
+            this.remember(key, entry, retainedBytes(serialized));
+            const directory = this.shardDirectory();
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            const path = this.shardPath(key);
+            const tempPath = `${path}.tmp-${process.pid}-${randomUUID()}`;
+            try {
+                await writeFile(tempPath, `${serialized}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+                await rename(tempPath, path);
+            }
+            catch (error) {
+                await rm(tempPath, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            const prune = this.prunePromise.catch(() => undefined).then(() => this.pruneShardsAsync(directory));
+            this.prunePromise = prune;
+            await prune;
+        });
+        this.pendingWrites.set(key, pending);
+        try {
+            await pending;
+        }
+        finally {
+            this.pendingWriteCount -= 1;
+            if (this.pendingWrites.get(key) === pending)
+                this.pendingWrites.delete(key);
+        }
+    }
+    memoryEntry(key) {
+        const entry = this.cache.entries[key];
+        if (entry) {
+            const bytes = this.entrySizes.get(key);
+            this.entrySizes.delete(key);
+            this.entrySizes.set(key, bytes);
+        }
+        return entry;
     }
-    read() {
-        if (!existsSync(this.filePath)) {
-            return { version: 1, entries: {} };
+    remember(key, entry, bytes = retainedBytes(JSON.stringify(entry))) {
+        this.forget(key);
+        if (bytes > (this.options.maxMemoryBytes ?? 64 * 1024 * 1024))
+            return;
+        this.cache.entries[key] = entry;
+        this.entrySizes.set(key, bytes);
+        this.checkedShards.add(key);
+        this.memoryBytes += bytes;
+        while (this.entrySizes.size > (this.options.maxMemoryEntries ?? maxCacheEntries) || this.memoryBytes > (this.options.maxMemoryBytes ?? 64 * 1024 * 1024)) {
+            const oldest = this.entrySizes.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.forget(oldest);
         }
+    }
+    forget(key) {
+        this.memoryBytes -= this.entrySizes.get(key) ?? 0;
+        this.entrySizes.delete(key);
+        this.checkedShards.delete(key);
+        delete this.cache.entries[key];
+    }
+    loadEntry(key) {
+        const memory = this.memoryEntry(key);
+        if (memory)
+            return memory;
+        const legacy = this.readLegacy().entries[key];
+        const shard = this.readShard(key);
+        const entry = newerEntry(legacy, shard);
+        if (entry)
+            this.remember(key, entry);
+        return entry;
+    }
+    async loadEntryAsync(key) {
+        const pending = this.pendingShardReads.get(key);
+        if (pending)
+            return pending.promise;
+        // Cache misses can proceed to the directory instead of growing an unbounded
+        // queue of disk reads. No negative entry prevents a later shard discovery.
+        if (this.pendingShardReads.size >= (this.options.maxPendingOperations ?? 16))
+            return undefined;
+        const record = { invalidated: false, promise: Promise.resolve(undefined) };
+        const work = async () => {
+            do {
+                record.invalidated = false;
+                const [legacy, shard] = await Promise.all([this.readLegacyAsync(), this.readShardAsync(key)]);
+                if (!record.invalidated) {
+                    const entry = newerEntry(legacy.entries[key], shard);
+                    if (entry) {
+                        const serialized = await stringifyJsonAsync(entry, isLargeValue(entry.value));
+                        if (record.invalidated) {
+                            await this.pendingWrites.get(key)?.catch(() => undefined);
+                            const current = this.memoryEntry(key);
+                            if (current)
+                                return current;
+                            continue;
+                        }
+                        this.remember(key, entry, retainedBytes(serialized));
+                    }
+                    return entry;
+                }
+                await this.pendingWrites.get(key)?.catch(() => undefined);
+                const current = this.memoryEntry(key);
+                if (current)
+                    return current;
+            } while (true);
+        };
+        record.promise = work().finally(() => { if (this.pendingShardReads.get(key) === record)
+            this.pendingShardReads.delete(key); });
+        this.pendingShardReads.set(key, record);
+        return record.promise;
+    }
+    readLegacy() {
+        if (this.legacyAbsent)
+            return emptyEnvelope();
         try {
-            const parsed = JSON.parse(readFileSync(this.filePath, 'utf8'));
-            return parsed.version === 1 && parsed.entries ? parsed : { version: 1, entries: {} };
+            if (statSync(this.filePath).size > (this.options.maxDiskBytes ?? maxCacheBytes))
+                return emptyEnvelope();
+            return validEnvelope(JSON.parse(readFileSync(this.filePath, 'utf8')));
         }
-        catch {
-            backupBadFile(this.filePath);
-            return { version: 1, entries: {} };
+        catch (error) {
+            if (error.code === 'ENOENT')
+                this.legacyAbsent = true;
+            else if (error instanceof SyntaxError)
+                backupBadFile(this.filePath);
+            return emptyEnvelope();
         }
     }
+    readLegacyAsync() {
+        if (this.legacyAbsent)
+            return Promise.resolve(emptyEnvelope());
+        if (this.legacyLoadPromise)
+            return this.legacyLoadPromise;
+        const reading = (async () => {
+            try {
+                if ((await stat(this.filePath)).size > (this.options.maxDiskBytes ?? maxCacheBytes))
+                    return emptyEnvelope();
+                return validEnvelope(await parseJsonAsync(await readFile(this.filePath, 'utf8')));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    this.legacyAbsent = true;
+                else if (error instanceof SyntaxError)
+                    await rename(this.filePath, `${this.filePath}.bad-${Date.now()}-${randomUUID()}`).catch(() => undefined);
+                return emptyEnvelope();
+            }
+        })();
+        const tracked = reading.finally(() => { if (this.legacyLoadPromise === tracked)
+            this.legacyLoadPromise = null; });
+        this.legacyLoadPromise = tracked;
+        return tracked;
+    }
     readShard(key) {
-        const path = join(this.shardDirectory(), `${createHash('sha256').update(key).digest('hex')}.json`);
-        if (!existsSync(path))
+        try {
+            const path = this.shardPath(key);
+            if (statSync(path).size > (this.options.maxDiskBytes ?? maxCacheBytes))
+                return undefined;
+            return validShard(JSON.parse(readFileSync(path, 'utf8')), key);
+        }
+        catch {
             return undefined;
+        }
+    }
+    async readShardAsync(key) {
         try {
-            const entry = JSON.parse(readFileSync(path, 'utf8'));
-            if (entry.version !== 1 || entry.key !== key || !Number.isFinite(entry.createdAt))
+            const path = this.shardPath(key);
+            if ((await stat(path)).size > (this.options.maxDiskBytes ?? maxCacheBytes))
                 return undefined;
-            const cached = { createdAt: entry.createdAt, value: entry.value };
-            this.cache.entries[key] = cached;
-            return cached;
+            return validShard(await parseJsonAsync(await readFile(path, 'utf8')), key);
         }
         catch {
             return undefined;
         }
     }
-    writeEntry(key, entry) {
-        const directory = this.shardDirectory();
-        mkdirSync(directory, { recursive: true, mode: 0o700 });
-        const path = join(directory, `${createHash('sha256').update(key).digest('hex')}.json`);
-        writeJsonAtomically(path, { version: 1, key, ...entry });
-        this.writesSincePrune += 1;
-        if (this.writesSincePrune >= 16) {
-            this.writesSincePrune = 0;
-            this.pruneShards(directory);
+    async pruneShardsAsync(directory) {
+        const names = (await readdir(directory)).filter(name => name.endsWith('.json'));
+        const files = [];
+        for (let index = 0; index < names.length; index += 32) {
+            const entries = await Promise.all(names.slice(index, index + 32).map(async (name) => {
+                const path = join(directory, name);
+                try {
+                    const info = await stat(path);
+                    return { path, bytes: info.size, modified: info.mtimeMs, inode: info.ino };
+                }
+                catch {
+                    return null;
+                }
+            }));
+            files.push(...entries.filter((entry) => entry !== null));
+        }
+        files.sort((left, right) => right.modified - left.modified);
+        let totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
+        while (files.length > (this.options.maxDiskEntries ?? maxCacheEntries) || totalBytes > (this.options.maxDiskBytes ?? maxCacheBytes)) {
+            const file = files.pop();
+            if (!file)
+                break;
+            try {
+                const current = await stat(file.path);
+                if (current.ino !== file.inode || current.mtimeMs !== file.modified || current.size !== file.bytes)
+                    continue;
+                await unlink(file.path);
+                totalBytes -= file.bytes;
+            }
+            catch { /* Another process may have refreshed or evicted the shard. */ }
         }
     }
     pruneShards(directory) {
-        const files = readdirSync(directory)
-            .filter(name => name.endsWith('.json'))
-            .flatMap(name => {
+        const files = readdirSync(directory).filter(name => name.endsWith('.json')).flatMap(name => {
+            const path = join(directory, name);
             try {
-                const path = join(directory, name);
-                const stat = statSync(path);
-                return [{ path, bytes: stat.size, modified: stat.mtimeMs }];
+                const info = statSync(path);
+                return [{ path, bytes: info.size, modified: info.mtimeMs }];
             }
             catch {
                 return [];
             }
-        })
-            .sort((left, right) => right.modified - left.modified);
-        let totalBytes = files.reduce((total, file) => total + file.bytes, 0);
-        while (files.length > maxCacheEntries || totalBytes > maxCacheBytes) {
+        }).sort((left, right) => right.modified - left.modified);
+        let totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
+        while (files.length > (this.options.maxDiskEntries ?? maxCacheEntries) || totalBytes > (this.options.maxDiskBytes ?? maxCacheBytes)) {
             const file = files.pop();
             if (!file)
                 break;
@@ -93,42 +289,62 @@ export class ProviderCache {
                 unlinkSync(file.path);
                 totalBytes -= file.bytes;
             }
-            catch {
-                // Cache eviction is best-effort.
-            }
+            catch { /* Cache eviction is best-effort. */ }
         }
     }
-    shardDirectory() {
-        return `${this.filePath}.d`;
-    }
+    shardDirectory() { return `${this.filePath}.d`; }
+    shardPath(key) { return join(this.shardDirectory(), `${createHash('sha256').update(key).digest('hex')}.json`); }
+}
+function retainedBytes(serialized) { return serialized.length * 2 + 128; }
+function isLargeValue(value) { return Array.isArray(value) && value.length >= 1000 || typeof value === 'string' && value.length >= 256 * 1024; }
+function emptyEnvelope() { return { version: 1, entries: Object.create(null) }; }
+function validEnvelope(value) {
+    const envelope = value;
+    if (envelope?.version !== 1 || !envelope.entries || typeof envelope.entries !== 'object' || Array.isArray(envelope.entries))
+        return emptyEnvelope();
+    const entries = Object.create(null);
+    for (const [key, entry] of Object.entries(envelope.entries))
+        if (entry && Number.isFinite(entry.createdAt) && 'value' in entry)
+            entries[key] = entry;
+    return { version: 1, entries };
+}
+function validShard(value, key) {
+    const entry = value;
+    return entry?.version === 1 && entry.key === key && Number.isFinite(entry.createdAt) && 'value' in entry ? { createdAt: entry.createdAt, value: entry.value } : undefined;
+}
+function newerEntry(legacy, shard) {
+    const now = Date.now();
+    if (legacy && !withinAge(legacy, Infinity, now))
+        legacy = undefined;
+    if (shard && !withinAge(shard, Infinity, now))
+        shard = undefined;
+    return shard && (!legacy || shard.createdAt >= legacy.createdAt) ? shard : legacy;
+}
+function withinAge(entry, maxAgeMs, now = Date.now()) {
+    const age = now - entry.createdAt;
+    return age >= -maxFutureClockSkewMs && Math.max(0, age) <= maxAgeMs;
 }
 function defaultProviderCachePath() {
     const { cache, legacyCache } = platformPaths();
     return existsSync(cache) || !existsSync(legacyCache) ? cache : legacyCache;
 }
-function writeJsonAtomically(filePath, value) {
-    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+function writeAtomically(path, serialized) {
+    const temp = `${path}.tmp-${process.pid}-${randomUUID()}`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600 });
-        renameSync(tempPath, filePath);
-        if (process.platform !== 'win32') {
-            chmodSync(filePath, 0o600);
-        }
+        writeFileSync(temp, `${serialized}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        renameSync(temp, path);
     }
     catch (error) {
-        rmSync(tempPath, { force: true });
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch { }
         throw error;
     }
 }
-function backupBadFile(filePath) {
-    if (!existsSync(filePath)) {
-        return;
-    }
-    const backupPath = `${filePath}.bad-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+function backupBadFile(path) {
     try {
-        renameSync(filePath, backupPath);
-    }
-    catch {
-        // If backup fails, leave the original in place and continue with defaults in memory.
+        renameSync(path, `${path}.bad-${Date.now()}-${randomUUID()}`);
     }
+    catch { /* Cache data is recoverable. */ }
 }

package/dist/providers/discovery-session.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+/** Cursor state is private, bounded, and committed only after a complete page.
+ * One-page replay makes retries safe without retaining every returned station. */
+export class DiscoverySessions {
+    sizeOf;
+    options;
+    sessions = new Map();
+    constructor(sizeOf, options = {}) {
+        this.sizeOf = sizeOf;
+        this.options = options;
+    }
+    async page(fingerprint, cursor, create, produce, signal) {
+        signal?.throwIfAborted();
+        const now = this.options.now?.() ?? Date.now();
+        this.prune(now);
+        let session;
+        let index = 0;
+        if (cursor) {
+            const match = /^([a-f0-9-]{36}):(\d+)$/.exec(cursor);
+            const found = match ? this.sessions.get(match[1]) : undefined;
+            index = Number(match?.[2]);
+            if (!found || !Number.isSafeInteger(index))
+                throw cursorError();
+            if (found.fingerprint !== fingerprint)
+                throw new Error('Discovery cursor does not match this query or its filters. Start the search again.');
+            session = found;
+        }
+        else {
+            this.makeRoom(1, 0);
+            const state = create();
+            session = { id: randomUUID(), fingerprint, state, nextPage: 0, touchedAt: now, bytes: this.sizeOf(state) };
+            this.sessions.set(session.id, session);
+        }
+        session.touchedAt = now;
+        if (session.last?.index === index)
+            return structuredClone(session.last.page);
+        if (session.pending?.index === index)
+            return structuredClone(await abortable(session.pending.promise, signal));
+        if (index !== session.nextPage || session.pending)
+            throw cursorError();
+        // Keep offsets and overflow intact if a request fails or its caller cancels.
+        const draft = structuredClone(session.state);
+        const work = (async () => {
+            const page = await produce(draft);
+            signal?.throwIfAborted();
+            const bytes = this.sizeOf(draft) + JSON.stringify(page).length * 2;
+            this.makeRoom(0, bytes - session.bytes, session.id);
+            const result = {
+                ...page,
+                nextCursor: page.exhausted ? undefined : `${session.id}:${index + 1}`
+            };
+            session.state = draft;
+            session.bytes = bytes;
+            session.nextPage = index + 1;
+            session.last = { index, page: result };
+            return result;
+        })();
+        session.pending = { index, promise: work };
+        try {
+            return structuredClone(await work);
+        }
+        catch (error) {
+            if (session.nextPage === 0)
+                this.sessions.delete(session.id);
+            throw error;
+        }
+        finally {
+            if (session.pending?.promise === work)
+                session.pending = undefined;
+        }
+    }
+    prune(now) {
+        const ttl = this.options.ttlMs ?? 10 * 60_000;
+        for (const [id, session] of this.sessions) {
+            if (!session.pending && (now < session.touchedAt || now - session.touchedAt >= ttl))
+                this.sessions.delete(id);
+        }
+    }
+    makeRoom(additionalCount, additionalBytes, protectedId) {
+        const maxSessions = this.options.maxSessions ?? 16;
+        const maxBytes = this.options.maxBytes ?? 32 * 1024 * 1024;
+        let bytes = [...this.sessions.values()].reduce((sum, entry) => sum + entry.bytes, 0) + additionalBytes;
+        const candidates = [...this.sessions.values()]
+            .filter(entry => entry.id !== protectedId && !entry.pending)
+            .sort((left, right) => left.touchedAt - right.touchedAt);
+        while (this.sessions.size + additionalCount > maxSessions || bytes > maxBytes) {
+            const oldest = candidates.shift();
+            if (!oldest)
+                throw new Error('Discovery session capacity reached. Finish another search or start a narrower query.');
+            this.sessions.delete(oldest.id);
+            bytes -= oldest.bytes;
+        }
+    }
+}
+/** Abort the wait even when an injected provider or DNS resolver ignores signal. */
+export function abortable(work, signal) {
+    if (!signal)
+        return work;
+    if (signal.aborted) {
+        void work.catch(() => undefined);
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(signal.reason);
+        signal.addEventListener('abort', aborted, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+    });
+}
+function cursorError() {
+    return new Error('Discovery cursor expired or is no longer available. Start the search again.');
+}