toolcraft-openapi 0.0.139 → 0.0.141

package/README.md

@@ -50,6 +50,45 @@ export const client = defineGeneratedClient({
 Generated lower-level group and operation exports remain available when callers
 want a curated command surface with `defineClient()`.
 
+## Live runtime clients
+
+`defineClientFromSpec()` materializes the same OpenAPI command model at process startup without
+writing generated source files:
+
+```ts
+const client = await defineClientFromSpec("https://api.example.com/openapi.json", {
+  name: "internal-agent",
+  baseUrl: "https://api.example.com",
+  auth,
+  cache: {
+    onFallback: (message) => process.stderr.write(`${message}\n`)
+  }
+});
+```
+
+HTTP sources use a cross-process disk cache by default when the built-in `fetch` is used.
+Successful documents remain fresh for the server's `Cache-Control: max-age`, or five
+minutes when the server does not provide one. Stale entries revalidate with `If-None-Match` when
+an ETag is available. Fetching and reading the response have a three-second timeout; a transport
+failure or timeout uses the last successfully materialized document. HTTP errors and invalid live
+documents still fail visibly.
+
+Runtime source options:
+
+- `cache: false` - disables HTTP source caching and offline fallback.
+- `cache.directory` - absolute cache directory override.
+- `cache.maxAgeMs` - fallback freshness when the response does not define cache behavior.
+- `cache.onFallback(message)` - reports when a stale document is used after a transport failure.
+- `onTimeout({ source, timeoutMs, usingCachedDocument })` - application hook for presenting
+  network-access guidance without coupling the library to a specific network or VPN.
+- `timeoutMs` - total HTTP fetch/body timeout. Defaults to `3000`; `0` disables it.
+
+Supplying a custom `fetch` disables automatic caching unless `cache` is explicitly provided. Use a
+different `cache.directory` for each identity when explicitly caching authenticated custom fetches.
+A custom filesystem participates when it provides `realpath` and the cache write operations;
+read-only filesystems still load the live document without persisting it. New cache entries are
+committed only after the command tree materializes successfully.
+
 ### CI drift check
 
 ```sh
@@ -79,6 +118,9 @@ toolcraft-openapi-generate --check
 - `AUTH_BACKEND` - forwarded to `auth-store` to select `file` or `keychain` storage.
 - `TOOLCRAFT_OPENAPI_ENV` - selects a configured OpenAPI environment when using
   `resolveOpenApiBaseUrl`.
+- `TOOLCRAFT_OPENAPI_CACHE_DIR` - absolute directory for live HTTP OpenAPI cache entries.
+- `TOOLCRAFT_OPENAPI_CACHE` - set to `0` or `false` to disable the default live HTTP cache.
+- `XDG_CACHE_HOME` - cache root fallback; defaults to `~/.cache`.
 
 ## Configuration
 

package/dist/composition.json

@@ -38,12 +38,12 @@
     },
     {
       "name": "toolcraft-openapi",
-      "version": "0.0.139",
+      "version": "0.0.141",
       "license": "MIT"
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.139",
+      "version": "0.0.141",
       "license": "MIT"
     },
     {

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { InspectOpenApiSourceOptions, OpenApiInspectionSource } from "./ins
 export { renderOpenApiInspection } from "./render-inspection.js";
 export { commandsFromSpec, defineClientFromSpec, resolveOpenApiBaseUrl } from "./runtime.js";
 export type { CommandsFromSpecOptions, DefineClientFromSpecOptions, OpenApiDocumentSource } from "./runtime.js";
+export type { OpenApiSpecCacheFileSystem, OpenApiSpecCacheOptions, OpenApiTimeoutContext } from "./spec-cache.js";
 export type { DefineClientOptions, DefinedClient, OpenApiClientServices } from "./define-client.js";
 export type { AuthProvider, CommandContributor, TokenSource } from "./auth/types.js";
 export { bearerTokenAuth } from "./auth/bearer-token-auth.js";

package/dist/network-error.js

@@ -24,6 +24,12 @@ export function classifyNetworkError(error, url) {
             return new UserError(`Temporary DNS failure for ${host}. Network may be down.`, {
                 cause: error
             });
+        case "UND_ERR_SOCKET":
+            return new UserError(`Network connection failed: ${redactedUrl}.`, { cause: error });
+        case "UND_ERR_CONNECT_TIMEOUT":
+        case "UND_ERR_HEADERS_TIMEOUT":
+        case "UND_ERR_BODY_TIMEOUT":
+            return new UserError(`Request timed out: ${redactedUrl}.`, { cause: error });
     }
     if (findAbortError(error) !== null) {
         return new UserError(`Request aborted: ${redactedUrl}.`, { cause: error });

package/dist/runtime.d.ts

@@ -2,12 +2,15 @@ import { type CommandNode } from "toolcraft";
 import { type DefineClientOptions, type DefinedClient, type OpenApiClientServices } from "./define-client.js";
 import { type OpenApiDocument } from "./generate.js";
 import type { ToolcraftConfig } from "./config.js";
-import { type OpenApiSourceFileSystem } from "./spec-source.js";
+import { type OpenApiSpecCacheFileSystem, type OpenApiSpecCacheOptions, type OpenApiTimeoutContext } from "./spec-cache.js";
 export type OpenApiDocumentSource = OpenApiDocument | string | URL;
 export interface CommandsFromSpecOptions {
     cwd?: string;
     fetch?: typeof globalThis.fetch;
-    fs?: OpenApiSourceFileSystem;
+    fs?: OpenApiSpecCacheFileSystem;
+    cache?: false | OpenApiSpecCacheOptions;
+    onTimeout?: (context: OpenApiTimeoutContext) => void | Promise<void>;
+    timeoutMs?: number;
     config?: ToolcraftConfig;
 }
 export type DefineClientFromSpecOptions<TServices extends object = Record<string, never>> = Omit<DefineClientOptions<TServices>, "baseUrl" | "commands"> & CommandsFromSpecOptions & {

package/dist/runtime.js

@@ -5,15 +5,27 @@ import { collectTagDescriptions, collectSchemaOptionEntries, collectGeneratedCom
 import { groupByNoun } from "./group-by-noun.js";
 import { prepareMultipartFileInputs, requestJson, writeBinaryResponseOutput } from "./http.js";
 import { buildRequestShape, executePreflightBlocks } from "./interpreter.js";
+import { DEFAULT_OPENAPI_FETCH_TIMEOUT_MS, loadCachedOpenApiSource } from "./spec-cache.js";
 import { parseOpenApiDocument, readOpenApiSourceText } from "./spec-source.js";
 const RUNTIME_COMMAND_SCOPE = ["cli", "mcp", "sdk"];
 export async function commandsFromSpec(source, options = {}) {
-    const document = await resolveDocument(source, options);
-    return createRuntimeNodes(document, options.config);
+    const resolved = await resolveDocument(source, options);
+    const commands = createRuntimeNodes(resolved.document, options.config);
+    await resolved.commit?.();
+    return commands;
 }
 export async function defineClientFromSpec(spec, options) {
-    const { cwd, fetch, fs: specFs, config, baseUrl, environment, env, ...clientOptions } = options;
-    const document = await resolveDocument(spec, { cwd, fetch, fs: specFs, config });
+    const { cwd, fetch, fs: specFs, cache, onTimeout, timeoutMs, config, baseUrl, environment, env, ...clientOptions } = options;
+    const resolved = await resolveDocument(spec, {
+        cwd,
+        fetch,
+        fs: specFs,
+        cache,
+        onTimeout,
+        timeoutMs,
+        config
+    });
+    const document = resolved.document;
     const resolvedBaseUrl = baseUrl ??
         resolveOpenApiBaseUrl({
             document,
@@ -25,18 +37,51 @@ export async function defineClientFromSpec(spec, options) {
         throw new UserError("defineClientFromSpec could not resolve a base URL. Pass baseUrl, configure an environment, or define OpenAPI servers[0].url.");
     }
     const commands = createRuntimeNodes(document, config);
-    return defineClient({ ...clientOptions, baseUrl: resolvedBaseUrl, commands });
+    const client = defineClient({ ...clientOptions, baseUrl: resolvedBaseUrl, commands });
+    await resolved.commit?.();
+    return client;
 }
 async function resolveDocument(source, options) {
     if (typeof source !== "string" && !(source instanceof URL)) {
-        return source;
+        return { document: source };
+    }
+    const sourceUrl = source instanceof URL ? source : tryParseUrl(source);
+    if (sourceUrl !== null && (sourceUrl.protocol === "http:" || sourceUrl.protocol === "https:")) {
+        const loaded = await loadCachedOpenApiSource(sourceUrl, {
+            cache: options.cache ?? resolveDefaultCache(options),
+            fetch: options.fetch ?? globalThis.fetch,
+            fs: options.fs ?? fs,
+            onTimeout: options.onTimeout,
+            timeoutMs: options.timeoutMs ?? DEFAULT_OPENAPI_FETCH_TIMEOUT_MS
+        });
+        return {
+            document: loaded.document,
+            ...(loaded.commit === undefined ? {} : { commit: loaded.commit })
+        };
     }
     const sourceText = await readOpenApiSourceText(source, {
         cwd: options.cwd ?? process.cwd(),
         fetch: options.fetch ?? globalThis.fetch,
         fs: options.fs ?? fs
     });
-    return parseOpenApiDocument(sourceText, source);
+    return { document: parseOpenApiDocument(sourceText, source) };
+}
+function resolveDefaultCache(options) {
+    if (options.fetch !== undefined) {
+        return false;
+    }
+    const configured = Object.prototype.hasOwnProperty.call(process.env, "TOOLCRAFT_OPENAPI_CACHE")
+        ? process.env.TOOLCRAFT_OPENAPI_CACHE?.trim().toLowerCase()
+        : undefined;
+    return configured === "0" || configured === "false" ? false : {};
+}
+function tryParseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
 }
 export function resolveOpenApiBaseUrl(options) {
     const environments = options.environments;

package/dist/spec-cache.d.ts

@@ -0,0 +1,41 @@
+import { type OpenApiSourceFileSystem } from "./spec-source.js";
+import type { OpenApiDocument } from "./generate.js";
+export declare const DEFAULT_OPENAPI_FETCH_TIMEOUT_MS = 3000;
+export declare const DEFAULT_OPENAPI_CACHE_MAX_AGE_MS: number;
+export interface OpenApiSpecCacheOptions {
+    directory?: string;
+    maxAgeMs?: number;
+    onFallback?: (message: string) => void | Promise<void>;
+}
+export interface LoadCachedOpenApiSourceOptions {
+    cache: false | OpenApiSpecCacheOptions;
+    fetch: typeof globalThis.fetch;
+    fs: OpenApiSpecCacheFileSystem;
+    onTimeout?: (context: OpenApiTimeoutContext) => void | Promise<void>;
+    timeoutMs?: number;
+}
+export interface OpenApiTimeoutContext {
+    source: string;
+    timeoutMs: number;
+    usingCachedDocument: boolean;
+}
+export interface OpenApiSpecCacheFileSystem extends OpenApiSourceFileSystem {
+    writeFile?(filePath: string, contents: string, options?: {
+        encoding?: BufferEncoding;
+        flag?: string;
+        mode?: number;
+    }): Promise<void>;
+    rename?(fromPath: string, toPath: string): Promise<void>;
+    mkdir?(directoryPath: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<unknown>;
+    unlink?(filePath: string): Promise<void>;
+    realpath?(filePath: string): Promise<string>;
+}
+export interface LoadedOpenApiSource {
+    sourceText: string;
+    document: OpenApiDocument;
+    commit?: () => Promise<void>;
+}
+export declare function loadCachedOpenApiSource(inputUrl: URL, options: LoadCachedOpenApiSourceOptions): Promise<LoadedOpenApiSource>;

package/dist/spec-cache.js

@@ -0,0 +1,376 @@
+import { createHash, randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { UserError } from "toolcraft";
+import { hasOwnErrorCode } from "./error-codes.js";
+import { fetchOpenApiHttpSource, OpenApiTimeoutError, OpenApiTransportError, parseOpenApiDocument } from "./spec-source.js";
+import { redactSensitiveQueryValues } from "./redaction.js";
+export const DEFAULT_OPENAPI_FETCH_TIMEOUT_MS = 3_000;
+export const DEFAULT_OPENAPI_CACHE_MAX_AGE_MS = 5 * 60_000;
+export async function loadCachedOpenApiSource(inputUrl, options) {
+    validateTimeout(options.timeoutMs);
+    if (options.cache === false) {
+        let result;
+        try {
+            result = await fetchOpenApiHttpSource(inputUrl, options.fetch, {
+                timeoutMs: options.timeoutMs
+            });
+        }
+        catch (error) {
+            notifyTimeout(options, inputUrl, error, false);
+            throw error;
+        }
+        if (result.status === "not-modified") {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        return {
+            sourceText: result.sourceText,
+            document: parseOpenApiDocument(result.sourceText, inputUrl)
+        };
+    }
+    validateMaxAge(options.cache.maxAgeMs);
+    const directory = resolveCacheDirectory(options.cache.directory);
+    const cachePath = resolveCachePath(inputUrl, directory);
+    const cached = await readCacheEntry(cachePath, options.fs);
+    const now = Date.now();
+    const freshnessMs = cached?.entry.maxAgeMs;
+    if (cached !== null &&
+        cached.entry.validatedAt <= now &&
+        freshnessMs !== undefined &&
+        now - cached.entry.validatedAt < freshnessMs) {
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document
+        };
+    }
+    let result;
+    try {
+        result = await fetchOpenApiHttpSource(inputUrl, options.fetch, {
+            ...(cached?.entry.etag === undefined ? {} : { etag: cached.entry.etag }),
+            timeoutMs: options.timeoutMs
+        });
+    }
+    catch (error) {
+        notifyTimeout(options, inputUrl, error, cached !== null);
+        if (!(error instanceof OpenApiTransportError) || cached === null) {
+            throw error;
+        }
+        notifyFallback(options.cache, inputUrl, error);
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document
+        };
+    }
+    const writableFs = getWritableFileSystem(options.fs);
+    if (result.status === "not-modified") {
+        if (cached === null) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        if (cached.entry.etag === undefined) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached validator.`);
+        }
+        const policy = result.cacheControl === undefined
+            ? {
+                store: true,
+                maxAgeMs: Math.max(0, cached.entry.maxAgeMs - (parseDeltaSeconds(result.age ?? "") ?? 0) * 1_000)
+            }
+            : resolveCachePolicy(result.cacheControl, result.age, options.cache.maxAgeMs, cached.entry.maxAgeMs);
+        if (!policy.store) {
+            return {
+                sourceText: cached.entry.sourceText,
+                document: cached.document,
+                ...(writableFs === null ? {} : { commit: () => removeCacheEntry(cachePath, writableFs) })
+            };
+        }
+        const entry = {
+            ...cached.entry,
+            validatedAt: now,
+            maxAgeMs: policy.maxAgeMs,
+            ...(result.etag === undefined ? {} : { etag: result.etag })
+        };
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document,
+            ...(writableFs === null
+                ? {}
+                : { commit: () => persistCacheEntry(cachePath, entry, writableFs) })
+        };
+    }
+    const policy = resolveCachePolicy(result.cacheControl, result.age, options.cache.maxAgeMs, DEFAULT_OPENAPI_CACHE_MAX_AGE_MS);
+    const document = parseOpenApiDocument(result.sourceText, inputUrl);
+    if (!policy.store) {
+        return {
+            sourceText: result.sourceText,
+            document,
+            ...(writableFs === null ? {} : { commit: () => removeCacheEntry(cachePath, writableFs) })
+        };
+    }
+    const entry = {
+        version: 1,
+        sourceText: result.sourceText,
+        validatedAt: now,
+        maxAgeMs: policy.maxAgeMs,
+        ...(result.etag === undefined ? {} : { etag: result.etag })
+    };
+    return {
+        sourceText: result.sourceText,
+        document,
+        ...(writableFs === null
+            ? {}
+            : { commit: () => persistCacheEntry(cachePath, entry, writableFs) })
+    };
+}
+function notifyTimeout(options, inputUrl, error, usingCachedDocument) {
+    if (!(error instanceof OpenApiTimeoutError) || options.onTimeout === undefined) {
+        return;
+    }
+    try {
+        void Promise.resolve(options.onTimeout({
+            source: redactSensitiveQueryValues(inputUrl.toString()),
+            timeoutMs: error.timeoutMs,
+            usingCachedDocument
+        })).catch(() => undefined);
+    }
+    catch {
+        // A presentation hook cannot change source-loading behavior.
+    }
+}
+function resolveCachePolicy(cacheControl, age, configuredMaxAgeMs, fallbackMaxAgeMs) {
+    const directives = (cacheControl ?? "")
+        .split(",")
+        .map((directive) => directive.trim().toLowerCase());
+    if (directives.includes("no-store")) {
+        return { store: false, maxAgeMs: 0 };
+    }
+    if (directives.includes("no-cache")) {
+        return { store: true, maxAgeMs: 0 };
+    }
+    for (const directive of directives) {
+        if (!directive.startsWith("max-age=")) {
+            continue;
+        }
+        const seconds = parseDeltaSeconds(directive.slice("max-age=".length));
+        if (seconds !== null) {
+            const responseAge = parseDeltaSeconds(age ?? "") ?? 0;
+            return { store: true, maxAgeMs: Math.max(0, seconds - responseAge) * 1_000 };
+        }
+    }
+    return {
+        store: true,
+        maxAgeMs: configuredMaxAgeMs ?? fallbackMaxAgeMs
+    };
+}
+function parseDeltaSeconds(value) {
+    const trimmed = value.trim();
+    const unquoted = trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    if (unquoted.length === 0) {
+        return null;
+    }
+    const seconds = Number(unquoted);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+function resolveCacheDirectory(configuredDirectory) {
+    const envDirectory = readOwnEnvValue(process.env, "TOOLCRAFT_OPENAPI_CACHE_DIR");
+    const xdgCacheHome = readOwnEnvValue(process.env, "XDG_CACHE_HOME");
+    const directory = configuredDirectory ?? envDirectory;
+    if (directory !== undefined) {
+        if (!path.isAbsolute(directory)) {
+            throw new UserError("OpenAPI cache directory must be an absolute path.");
+        }
+        return directory;
+    }
+    const cacheRoot = xdgCacheHome ?? path.join(os.homedir(), ".cache");
+    if (!path.isAbsolute(cacheRoot)) {
+        throw new UserError("XDG_CACHE_HOME must be an absolute path.");
+    }
+    return path.join(cacheRoot, "toolcraft-openapi", "specs");
+}
+function resolveCachePath(inputUrl, directory) {
+    const canonicalUrl = new URL(inputUrl);
+    canonicalUrl.hash = "";
+    const key = createHash("sha256").update(canonicalUrl.toString()).digest("hex");
+    return path.join(directory, `${key}.json`);
+}
+async function readCacheEntry(cachePath, fs) {
+    if (!hasRealpath(fs)) {
+        return null;
+    }
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        const parsed = JSON.parse(await fs.readFile(cachePath, "utf8"));
+        if (!isCacheEntry(parsed)) {
+            return null;
+        }
+        return {
+            entry: sanitizeCacheEntry(parsed),
+            document: parseOpenApiDocument(parsed.sourceText, cachePath)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function sanitizeCacheEntry(entry) {
+    if (entry.etag === undefined || isValidEtag(entry.etag)) {
+        return entry;
+    }
+    const withoutEtag = { ...entry };
+    delete withoutEtag.etag;
+    return withoutEtag;
+}
+function isValidEtag(etag) {
+    try {
+        new Headers({ "If-None-Match": etag });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function persistCacheEntry(cachePath, entry, fs) {
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        await fs.mkdir(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+        await assertSafeCachePath(cachePath, fs);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const temporaryPath = `${cachePath}.${randomUUID()}.tmp`;
+            let temporaryCreated = false;
+            try {
+                await fs.writeFile(temporaryPath, JSON.stringify(entry), {
+                    encoding: "utf8",
+                    flag: "wx",
+                    mode: 0o600
+                });
+                temporaryCreated = true;
+                await fs.rename(temporaryPath, cachePath);
+                return;
+            }
+            catch (error) {
+                if (temporaryCreated || !hasOwnErrorCode(error, "EEXIST")) {
+                    await fs.unlink(temporaryPath).catch(() => undefined);
+                }
+                if (!hasOwnErrorCode(error, "EEXIST")) {
+                    return;
+                }
+            }
+        }
+    }
+    catch {
+        // Cache writes are best-effort; the materialized live document remains usable.
+    }
+}
+async function removeCacheEntry(cachePath, fs) {
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        await fs.unlink(cachePath);
+    }
+    catch {
+        // Cache removal is best-effort; the materialized live document remains usable.
+    }
+}
+function getWritableFileSystem(fs) {
+    if (typeof fs.writeFile !== "function" ||
+        typeof fs.rename !== "function" ||
+        typeof fs.mkdir !== "function" ||
+        typeof fs.unlink !== "function" ||
+        typeof fs.realpath !== "function") {
+        return null;
+    }
+    return fs;
+}
+function hasRealpath(fs) {
+    return typeof fs.realpath === "function";
+}
+async function assertSafeCachePath(cachePath, fs) {
+    const directory = path.resolve(path.dirname(cachePath));
+    let existingPath = directory;
+    while (true) {
+        try {
+            if (path.resolve(await fs.realpath(existingPath)) !== existingPath) {
+                throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+            }
+            break;
+        }
+        catch (error) {
+            if (!hasOwnErrorCode(error, "ENOENT")) {
+                throw error;
+            }
+            const parentPath = path.dirname(existingPath);
+            if (parentPath === existingPath) {
+                throw error;
+            }
+            existingPath = parentPath;
+        }
+    }
+    try {
+        if (path.resolve(await fs.realpath(directory)) !== directory) {
+            throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+        }
+    }
+    catch (error) {
+        if (hasOwnErrorCode(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    try {
+        const canonicalCachePath = path.resolve(await fs.realpath(cachePath));
+        if (canonicalCachePath !== path.resolve(cachePath)) {
+            throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+        }
+    }
+    catch (error) {
+        if (!hasOwnErrorCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+function isCacheEntry(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const entry = value;
+    return (Object.hasOwn(entry, "version") &&
+        entry.version === 1 &&
+        Object.hasOwn(entry, "sourceText") &&
+        typeof entry.sourceText === "string" &&
+        Object.hasOwn(entry, "validatedAt") &&
+        typeof entry.validatedAt === "number" &&
+        Number.isFinite(entry.validatedAt) &&
+        Object.hasOwn(entry, "maxAgeMs") &&
+        typeof entry.maxAgeMs === "number" &&
+        Number.isFinite(entry.maxAgeMs) &&
+        entry.maxAgeMs >= 0 &&
+        (!Object.hasOwn(entry, "etag") || typeof entry.etag === "string"));
+}
+function notifyFallback(cache, inputUrl, error) {
+    if (cache.onFallback === undefined) {
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+        void Promise.resolve(cache.onFallback(`Using cached OpenAPI document for ${JSON.stringify(redactSensitiveQueryValues(inputUrl.toString()))} because refresh failed: ${message}`)).catch(() => undefined);
+    }
+    catch {
+        // Cache fallback remains usable even if a presentation callback fails.
+    }
+}
+function validateTimeout(timeoutMs) {
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+        throw new UserError("OpenAPI fetch timeout must be a finite non-negative number.");
+    }
+}
+function validateMaxAge(maxAgeMs) {
+    if (maxAgeMs !== undefined && (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)) {
+        throw new UserError("OpenAPI cache maxAgeMs must be a finite non-negative number.");
+    }
+}
+function readOwnEnvValue(env, key) {
+    if (!Object.prototype.hasOwnProperty.call(env, key)) {
+        return undefined;
+    }
+    const value = env[key]?.trim();
+    return value === undefined || value.length === 0 ? undefined : value;
+}

package/dist/spec-source.d.ts

@@ -1,3 +1,4 @@
+import { UserError } from "toolcraft";
 import type { OpenApiDocument } from "./generate.js";
 export interface OpenApiSourceFileSystem {
     readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
@@ -7,5 +8,30 @@ export interface OpenApiSourceServices {
     fetch: typeof globalThis.fetch;
     fs: OpenApiSourceFileSystem;
 }
+export interface OpenApiHttpSourceOptions {
+    etag?: string;
+    timeoutMs?: number;
+}
+export type OpenApiHttpSourceResult = {
+    status: "modified";
+    sourceText: string;
+    etag?: string;
+    cacheControl?: string;
+    age?: string;
+} | {
+    status: "not-modified";
+    etag?: string;
+    cacheControl?: string;
+    age?: string;
+};
+export declare class OpenApiHttpStatusError extends UserError {
+}
+export declare class OpenApiTransportError extends UserError {
+}
+export declare class OpenApiTimeoutError extends OpenApiTransportError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: ErrorOptions);
+}
 export declare function readOpenApiSourceText(input: string | URL, services: OpenApiSourceServices): Promise<string>;
+export declare function fetchOpenApiHttpSource(inputUrl: URL, fetch: typeof globalThis.fetch, options?: OpenApiHttpSourceOptions): Promise<OpenApiHttpSourceResult>;
 export declare function parseOpenApiDocument(sourceText: string, input: string | URL): OpenApiDocument;

package/dist/spec-source.js

@@ -4,6 +4,18 @@ import { parse as parseYaml } from "yaml";
 import { UserError } from "toolcraft";
 import { renderSourceSnippet } from "toolcraft/source-snippet";
 import { classifyNetworkError } from "./network-error.js";
+import { redactSensitiveQueryValues } from "./redaction.js";
+export class OpenApiHttpStatusError extends UserError {
+}
+export class OpenApiTransportError extends UserError {
+}
+export class OpenApiTimeoutError extends OpenApiTransportError {
+    timeoutMs;
+    constructor(message, timeoutMs, options) {
+        super(message, options);
+        this.timeoutMs = timeoutMs;
+    }
+}
 export async function readOpenApiSourceText(input, services) {
     const inputUrl = input instanceof URL ? input : tryParseUrl(input);
     const sourceLabel = formatSourceLabel(input);
@@ -20,29 +32,118 @@ export async function readOpenApiSourceText(input, services) {
         if (inputUrl.protocol !== "http:" && inputUrl.protocol !== "https:") {
             throw new UserError(`Unsupported OpenAPI input URL protocol ${JSON.stringify(inputUrl.protocol)}.`);
         }
+        const result = await fetchOpenApiHttpSource(inputUrl, services.fetch);
+        if (result.status === "not-modified") {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        return result.sourceText;
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            throw error;
+        }
+        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+export async function fetchOpenApiHttpSource(inputUrl, fetch, options = {}) {
+    validateTimeout(options.timeoutMs);
+    const url = inputUrl.toString();
+    const timeoutMs = options.timeoutMs;
+    const controller = timeoutMs === undefined || timeoutMs === 0 ? undefined : new AbortController();
+    const requestInit = createOpenApiRequestInit(options.etag, controller?.signal);
+    const request = async () => {
         let response;
         try {
-            response = await services.fetch(inputUrl.toString());
+            response = requestInit === undefined ? await fetch(url) : await fetch(url, requestInit);
         }
         catch (error) {
-            throw classifyNetworkError(error, inputUrl.toString()) ?? error;
+            throw toTransportError(error, url) ?? error;
+        }
+        if (response.status === 304) {
+            return {
+                status: "not-modified",
+                ...readResponseCacheHeaders(response)
+            };
         }
         if (!response.ok) {
             const contentType = response.headers.get("content-type") ?? "";
             const text = await response.text().catch(() => "");
             const snippet = text.length === 0 ? "" : `\n  body: ${truncate(text, 500)}`;
-            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: ` +
+            throw new OpenApiHttpStatusError(`Failed to fetch ${JSON.stringify(url)}: ` +
                 `${response.status} ${response.statusText}` +
                 (contentType ? ` (content-type: ${contentType})` : "") +
                 snippet);
         }
-        return await response.text();
+        try {
+            return {
+                status: "modified",
+                sourceText: await response.text(),
+                ...readResponseCacheHeaders(response)
+            };
+        }
+        catch (error) {
+            throw (toTransportError(error, url) ??
+                new OpenApiTransportError(`Failed to read the OpenAPI response body from ${JSON.stringify(redactSensitiveQueryValues(url))}.`, { cause: error }));
+        }
+    };
+    if (controller === undefined || timeoutMs === undefined) {
+        return await request();
     }
-    catch (error) {
-        if (error instanceof UserError) {
-            throw error;
+    const timeoutCause = Object.assign(new Error("OpenAPI request timed out"), {
+        code: "ETIMEDOUT",
+        timeout: timeoutMs
+    });
+    const classified = classifyNetworkError(timeoutCause, url);
+    const timeoutError = new OpenApiTimeoutError(classified?.message ?? `OpenAPI request timed out after ${timeoutMs}ms.`, timeoutMs, { cause: timeoutCause });
+    let timeout;
+    try {
+        return await Promise.race([
+            request(),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    reject(timeoutError);
+                    controller.abort(timeoutError);
+                }, timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
         }
-        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+function toTransportError(error, url) {
+    if (error instanceof OpenApiTransportError) {
+        return error;
+    }
+    const classified = classifyNetworkError(error, url);
+    return classified === null
+        ? null
+        : new OpenApiTransportError(classified.message, { cause: error });
+}
+function createOpenApiRequestInit(etag, signal) {
+    if (etag === undefined && signal === undefined) {
+        return undefined;
+    }
+    return {
+        ...(etag === undefined ? {} : { headers: { "If-None-Match": etag } }),
+        ...(signal === undefined ? {} : { signal })
+    };
+}
+function readResponseCacheHeaders(response) {
+    const etag = response.headers.get("etag") ?? undefined;
+    const cacheControl = response.headers.get("cache-control") ?? undefined;
+    const age = response.headers.get("age") ?? undefined;
+    return {
+        ...(etag === undefined ? {} : { etag }),
+        ...(cacheControl === undefined ? {} : { cacheControl }),
+        ...(age === undefined ? {} : { age })
+    };
+}
+function validateTimeout(timeoutMs) {
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+        throw new UserError("OpenAPI fetch timeout must be a finite non-negative number.");
     }
 }
 export function parseOpenApiDocument(sourceText, input) {

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.139",
+  "version": "0.0.141",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-openapi",
-  "version": "0.0.139",
+  "version": "0.0.141",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
     "toolcraft-openapi-generate": "dist/bin/generate.js"
   },
   "dependencies": {
-    "toolcraft": "0.0.139",
+    "toolcraft": "0.0.141",
     "auth-store": "^0.0.1",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",
@@ -46,7 +46,7 @@
     "directory": "packages/toolcraft-openapi"
   },
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.139",
+    "toolcraft-schema": "0.0.141",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*"
   },