mcp-wayback-machine/dist/utils/cache.d.ts

MCP server and CLI tool for interacting with the Wayback Machine without API keys

/**
 * HTTP request caching with in-memory and pluggable persistent backends.
 * Stores serialised responses (status, headers, body) with TTL-based expiry.
 * Supports per-endpoint TTL via URL pattern matching.
 *
 * The default disk cache lives under the user's cache directory (XDG_CACHE_HOME
 * or ~/.cache on Linux/macOS, %LOCALAPPDATA% on Windows) with 0700 / 0600
 * permissions so it cannot be poisoned by other users on a shared host.
 *
 * Alternative backends (e.g. Cloudflare KV) implement the CacheBackend interface
 * and are passed via the CachingFetcher constructor.
 */
import * as z from "zod";
export declare const CachedResponse: z.ZodObject<{
    status: z.ZodNumber;
    statusText: z.ZodString;
    headers: z.ZodRecord<z.ZodString, z.ZodString>;
    body: z.ZodString;
    expiry: z.ZodNumber;
}, z.core.$strip>;
type CachedResponse = z.infer<typeof CachedResponse>;
/**

 * TTL durations in milliseconds

 */
export declare const TTL: {
    /**
     * Archived snapshot content — immutable once captured
     */
    readonly SNAPSHOT: number;
    /**
     * Availability API — snapshots don't change often
     */
    readonly AVAILABILITY: number;
    /**
     * CDX search — snapshot list grows but never mutates
     */
    readonly CDX_SEARCH: number;
    /**
     * Sparkline capture statistics — grows, never mutates
     */
    readonly SPARKLINE: number;
    /**
     * Save (POST) — idempotent per URL
     */
    readonly SAVE: number;
    /**
     * Save status polling — changes during active jobs
     */
    readonly SAVE_STATUS: number;
};
/**
 * Persistent cache backend — read/write cached HTTP responses.
 * Implemented by disk (Node.js), KV (Cloudflare Workers), etc.
 */
export interface CacheBackend {
    get(key: string): Promise<CachedResponse | undefined>;
    set(key: string, entry: CachedResponse): Promise<void>;
    delete(key: string): Promise<void>;
    clear(): Promise<void>;
}
interface CacheConfig {
    /**
     * Default TTL in milliseconds
     */
    ttl: number;
    /**
     * Persistent cache backend. Defaults to disk cache if not provided.
     */
    backend: CacheBackend;
}
/**
 * Disk-backed cache backend using the filesystem.
 * Uses restrictive permissions (0700 dir, 0600 files) to prevent cache poisoning.
 */
export declare class DiskCacheBackend implements CacheBackend {
    private readonly dir;
    constructor(dir: string);
    get(key: string): Promise<CachedResponse | undefined>;
    set(key: string, entry: CachedResponse): Promise<void>;
    delete(key: string): Promise<void>;
    clear(): Promise<void>;
}
export declare class CachingFetcher {
    private readonly config;
    private readonly memoryCache;
    constructor(config?: Partial<CacheConfig>);
    /**
     * The persistent backend in use (disk, KV, etc.).
     */
    get backend(): CacheBackend;
    /**
     * Fetch with caching. Returns cached response if fresh,
     * otherwise fetches from network and populates both caches.
     *
     * TTL is resolved automatically from the URL pattern.
     * Pass cacheTtl to override, or false to bypass cache entirely.
     */
    fetch(url: string, options?: {
        method?: string;
        headers?: Record<string, string>;
        body?: string;
        timeout?: number;
    }, cacheTtl?: number | false): Promise<Response>;
    clear(): Promise<void>;
    getStats(): {
        memoryEntries: number;
    };
    prune(): Promise<void>;
}
/**
 * Disk-backed cache backend using the filesystem.
 * Uses restrictive permissions (0700 dir, 0600 files) to prevent cache poisoning.
 */
/**
 * Shared instance for use across tools in stdio mode.
 */
export declare const cachingFetcher: CachingFetcher;
export {};
//# sourceMappingURL=cache.d.ts.map