@canister-software/consensus-cli 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/proxy-client.js

@@ -0,0 +1,466 @@
+import { AsyncLocalStorage } from "async_hooks";
+const DEFAULT_SERVER_URL = process.env.CONSENSUS_SERVER_URL || "https://consensus.canister.software";
+const USD_SCALE = 1_000_000;
+const PROXY_PAID_REQUEST_COST_USD = 0.0001;
+class ProxyClientError extends Error {
+    /** HTTP status from proxy response when available. */
+    status;
+    /** Parsed proxy error payload when available. */
+    data;
+}
+const proxyFetchContext = new AsyncLocalStorage();
+let interceptorInstalled = false;
+let passthroughFetch = typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : null;
+function trimTrailingSlash(value) {
+    return String(value || "").replace(/\/+$/, "");
+}
+function normalizePath(value) {
+    const path = String(value || "/").split("?")[0] || "/";
+    if (path === "/")
+        return "/";
+    const normalized = path.replace(/\/+$/, "");
+    return normalized || "/";
+}
+function normalizeHeaders(headers) {
+    if (!headers)
+        return {};
+    if (typeof Headers !== "undefined" && headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers.map(([key, value]) => [String(key), String(value)]));
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "undefined" || value === null)
+            continue;
+        result[key] = String(value);
+    }
+    return result;
+}
+function pathMatches(pathname, route, matchSubroutes = false) {
+    const requestPath = normalizePath(pathname);
+    const configuredRoute = normalizePath(route);
+    if (requestPath === configuredRoute)
+        return true;
+    if (!matchSubroutes)
+        return false;
+    if (configuredRoute === "/")
+        return true;
+    return requestPath.startsWith(`${configuredRoute}/`);
+}
+function shouldProxyPath(pathname, options) {
+    const mode = options.mode === "exclusive" ? "exclusive" : "inclusive";
+    const routes = Array.isArray(options.routes) ? options.routes : [];
+    const matchSubroutes = Boolean(options.matchSubroutes);
+    const matched = routes.some((route) => pathMatches(pathname, route, matchSubroutes));
+    return mode === "exclusive" ? matched : !matched;
+}
+function controlHeadersFromOptions(options) {
+    const headers = {};
+    if (typeof options.cache_ttl !== "undefined" && options.cache_ttl !== null) {
+        headers["x-cache-ttl"] = String(options.cache_ttl);
+    }
+    if (options.verbose === true) {
+        headers["x-verbose"] = "true";
+    }
+    if (typeof options.node_region === "string" && options.node_region.trim()) {
+        headers["x-node-region"] = options.node_region.trim();
+    }
+    if (typeof options.node_domain === "string" && options.node_domain.trim()) {
+        headers["x-node-domain"] = options.node_domain.trim();
+    }
+    if (typeof options.node_exclude === "string" && options.node_exclude.trim()) {
+        headers["x-node-exclude"] = options.node_exclude.trim();
+    }
+    return headers;
+}
+function parseMaybeJson(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function parseUsdToMicros(value, fieldName) {
+    if (typeof value === "undefined" || value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${fieldName} must be a non-negative number`);
+    }
+    const micros = Math.round(value * USD_SCALE);
+    const normalized = micros / USD_SCALE;
+    if (Math.abs(normalized - value) > 1e-9) {
+        throw new TypeError(`${fieldName} supports at most 6 decimal places`);
+    }
+    return micros;
+}
+function microsToUsd(micros) {
+    return Number((micros / USD_SCALE).toFixed(6));
+}
+function normalizeBody(body, headers) {
+    if (typeof body === "undefined" || body === null)
+        return undefined;
+    if (typeof body === "string")
+        return body;
+    if (typeof body === "number" || typeof body === "boolean")
+        return body;
+    if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) {
+        if (!headers["content-type"] && !headers["Content-Type"]) {
+            headers["content-type"] = "application/x-www-form-urlencoded;charset=UTF-8";
+        }
+        return body.toString();
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(body)) {
+        return body.toString("utf8");
+    }
+    if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+        const bytes = body instanceof ArrayBuffer
+            ? new Uint8Array(body)
+            : new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+        if (typeof Buffer !== "undefined")
+            return Buffer.from(bytes).toString("utf8");
+        return new TextDecoder().decode(bytes);
+    }
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        throw new Error("FormData request bodies are not supported by ProxyClient");
+    }
+    if (typeof body === "object") {
+        if (!headers["content-type"] && !headers["Content-Type"]) {
+            headers["content-type"] = "application/json";
+        }
+        return body;
+    }
+    throw new Error(`Unsupported request body type: ${typeof body}`);
+}
+function bodyToInit(body, headers) {
+    const normalized = normalizeBody(body, headers);
+    if (typeof normalized === "undefined")
+        return undefined;
+    if (typeof normalized === "string")
+        return normalized;
+    if (typeof normalized === "object" &&
+        normalized !== null &&
+        !(normalized instanceof ArrayBuffer) &&
+        !ArrayBuffer.isView(normalized)) {
+        return JSON.stringify(normalized);
+    }
+    return normalized;
+}
+async function buildProxyPayload(input, init = {}, controlHeaders) {
+    let targetUrl;
+    let method = "GET";
+    let headers = {};
+    let body;
+    if (typeof Request !== "undefined" && input instanceof Request) {
+        targetUrl = input.url;
+        method = input.method || method;
+        headers = normalizeHeaders(input.headers);
+        if (!("body" in init) && method !== "GET" && method !== "HEAD") {
+            const raw = await input.clone().text();
+            if (raw.length > 0)
+                body = raw;
+        }
+    }
+    else if (typeof input === "string" || input instanceof URL) {
+        targetUrl = String(input);
+    }
+    else {
+        throw new Error("ProxyClient fetch input must be URL string, URL, or Request");
+    }
+    method = String(init.method || method || "GET").toUpperCase();
+    headers = {
+        ...controlHeaders,
+        ...headers,
+        ...normalizeHeaders(init.headers),
+    };
+    if ("body" in init) {
+        body = init.body;
+    }
+    const normalizedBody = normalizeBody(body, headers);
+    return {
+        target_url: targetUrl,
+        method,
+        headers,
+        ...(typeof normalizedBody !== "undefined" ? { body: normalizedBody } : {}),
+    };
+}
+function toProxyResult(response, data) {
+    if (data && typeof data === "object" && "status" in data && "data" in data) {
+        const maybe = data;
+        return {
+            status: Number(maybe.status) || response.status || 200,
+            statusText: maybe.statusText || response.statusText || "",
+            headers: maybe.headers || {},
+            data: maybe.data,
+            meta: maybe.meta ?? null,
+        };
+    }
+    return {
+        status: response.status || 500,
+        statusText: response.statusText || "",
+        headers: {},
+        data,
+        meta: null,
+    };
+}
+function toFetchResponse(proxyResult, requestUrl) {
+    const headers = new Headers(proxyResult.headers || {});
+    const payload = proxyResult.data;
+    const body = payload === null || typeof payload === "undefined"
+        ? null
+        : typeof payload === "string"
+            ? payload
+            : JSON.stringify(payload);
+    if (payload !== null && typeof payload === "object" && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const response = new Response(body, {
+        status: proxyResult.status,
+        statusText: proxyResult.statusText || "",
+        headers,
+    });
+    Object.defineProperty(response, "consensus", {
+        value: {
+            request_url: requestUrl,
+            meta: proxyResult.meta || null,
+        },
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return response;
+}
+function responseHeadersToRecord(headers) {
+    const record = {};
+    headers.forEach((value, key) => {
+        record[key] = value;
+    });
+    return record;
+}
+function isLikelyPaidProxyResponse(proxyResult) {
+    const meta = proxyResult.meta;
+    if (meta && typeof meta === "object" && "cached" in meta) {
+        return meta.cached !== true;
+    }
+    return true;
+}
+function ensureInterceptorInstalled() {
+    if (interceptorInstalled)
+        return;
+    if (typeof globalThis.fetch === "function") {
+        passthroughFetch = globalThis.fetch.bind(globalThis);
+    }
+    if (!passthroughFetch) {
+        throw new Error("Global fetch is unavailable; use strategy: 'manual' or polyfill fetch.");
+    }
+    globalThis.fetch = ((input, init) => {
+        const state = proxyFetchContext.getStore();
+        if (state?.proxyFetch)
+            return state.proxyFetch(input, init);
+        return passthroughFetch(input, init);
+    });
+    interceptorInstalled = true;
+}
+function currentPassthroughFetch() {
+    if (passthroughFetch)
+        return passthroughFetch;
+    if (typeof globalThis.fetch === "function") {
+        passthroughFetch = globalThis.fetch.bind(globalThis);
+    }
+    return passthroughFetch;
+}
+export function ProxyClient(fetchWithPayment, options = {}) {
+    if (typeof fetchWithPayment !== "function") {
+        throw new TypeError("ProxyClient requires fetchWithPayment as the first argument");
+    }
+    const strategy = options.strategy === "manual" ? "manual" : "auto";
+    const serverUrl = trimTrailingSlash(DEFAULT_SERVER_URL);
+    const proxyEndpoint = `${serverUrl}/proxy`;
+    const baseControlHeaders = controlHeadersFromOptions(options);
+    const limitMicros = parseUsdToMicros(options.limit_usd, "limit_usd");
+    const requestCostMicros = parseUsdToMicros(PROXY_PAID_REQUEST_COST_USD, "proxy_request_cost_usd") ?? 0;
+    let spentMicros = 0;
+    let limitCallbackFired = false;
+    function computeStandDownState() {
+        if (limitMicros === null)
+            return false;
+        if (spentMicros >= limitMicros)
+            return true;
+        if (requestCostMicros <= 0)
+            return false;
+        return spentMicros + requestCostMicros > limitMicros;
+    }
+    function getBudget() {
+        const remainingMicros = limitMicros === null ? null : Math.max(0, limitMicros - spentMicros);
+        return {
+            limit_usd: limitMicros === null ? null : microsToUsd(limitMicros),
+            request_cost_usd: microsToUsd(requestCostMicros),
+            spent_usd: microsToUsd(spentMicros),
+            remaining_usd: remainingMicros === null ? null : microsToUsd(remainingMicros),
+            exhausted: computeStandDownState(),
+        };
+    }
+    function isStandDown() {
+        const exhausted = computeStandDownState();
+        if (exhausted &&
+            !limitCallbackFired &&
+            typeof options.on_limit_reached === "function") {
+            limitCallbackFired = true;
+            options.on_limit_reached(getBudget());
+        }
+        return exhausted;
+    }
+    function incrementSpend(proxyResult) {
+        if (requestCostMicros <= 0)
+            return;
+        if (!isLikelyPaidProxyResponse(proxyResult))
+            return;
+        spentMicros += requestCostMicros;
+        if (limitMicros !== null && spentMicros > limitMicros)
+            spentMicros = limitMicros;
+        isStandDown();
+    }
+    function resetBudget() {
+        spentMicros = 0;
+        limitCallbackFired = false;
+    }
+    async function passthroughFetchOrThrow(input, init) {
+        const directFetch = currentPassthroughFetch();
+        if (!directFetch) {
+            throw new ProxyClientError("Global fetch is unavailable; cannot bypass proxy while in stand-down mode.");
+        }
+        return directFetch(input, init);
+    }
+    async function requestProxy(payload) {
+        const response = await fetchWithPayment(proxyEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        const raw = await response.text();
+        const parsed = parseMaybeJson(raw);
+        if (!response.ok && !(parsed && typeof parsed === "object" && "status" in parsed)) {
+            const message = parsed?.message ||
+                parsed?.error ||
+                `Proxy request failed (${response.status})`;
+            const error = new ProxyClientError(message);
+            error.status = response.status;
+            error.data = parsed;
+            throw error;
+        }
+        return toProxyResult(response, parsed);
+    }
+    async function requestDirectFromPayload(payload, reason) {
+        const targetUrl = String(payload.target_url || "").trim();
+        if (!targetUrl) {
+            throw new ProxyClientError("target_url is required when proxy is in stand-down mode");
+        }
+        const method = String(payload.method || "GET").toUpperCase();
+        const headers = normalizeHeaders(payload.headers);
+        const init = {
+            method,
+            headers,
+        };
+        if (!["GET", "HEAD"].includes(method) && typeof payload.body !== "undefined") {
+            const convertedBody = bodyToInit(payload.body, headers);
+            if (typeof convertedBody !== "undefined")
+                init.body = convertedBody;
+        }
+        const response = await passthroughFetchOrThrow(targetUrl, init);
+        const raw = await response.text();
+        const parsed = parseMaybeJson(raw);
+        return {
+            status: response.status,
+            statusText: response.statusText || "",
+            headers: responseHeadersToRecord(response.headers),
+            data: parsed,
+            meta: { bypassed: true, reason },
+        };
+    }
+    async function proxiedFetch(input, init = {}, perRequestOptions = {}) {
+        if (isStandDown()) {
+            return passthroughFetchOrThrow(input, init);
+        }
+        const controlHeaders = {
+            ...baseControlHeaders,
+            ...controlHeadersFromOptions(perRequestOptions),
+        };
+        const payload = await buildProxyPayload(input, init, controlHeaders);
+        const proxyResult = await requestProxy(payload);
+        incrementSpend(proxyResult);
+        const requestUrl = typeof Request !== "undefined" && input instanceof Request ? input.url : String(input);
+        return toFetchResponse(proxyResult, requestUrl);
+    }
+    async function proxiedRequest(payload = {}, perRequestOptions = {}) {
+        if (isStandDown()) {
+            return requestDirectFromPayload(payload, "limit_reached");
+        }
+        const controlHeaders = {
+            ...baseControlHeaders,
+            ...controlHeadersFromOptions(perRequestOptions),
+            ...normalizeHeaders(payload.headers),
+        };
+        const proxyResult = await requestProxy({
+            target_url: String(payload.target_url || ""),
+            method: String(payload.method || "GET").toUpperCase(),
+            headers: controlHeaders,
+            ...(typeof payload.body !== "undefined" ? { body: payload.body } : {}),
+        });
+        incrementSpend(proxyResult);
+        return proxyResult;
+    }
+    function createFetch(pathname = "/") {
+        return (input, init) => {
+            if (!shouldProxyPath(pathname, options)) {
+                return passthroughFetchOrThrow(input, init);
+            }
+            return proxiedFetch(input, init);
+        };
+    }
+    async function runWithPath(pathname, run) {
+        if (typeof run !== "function") {
+            throw new TypeError("runWithPath requires a callback function");
+        }
+        ensureInterceptorInstalled();
+        const shouldProxy = shouldProxyPath(pathname, options);
+        return new Promise((resolve, reject) => {
+            proxyFetchContext.run({ proxyFetch: shouldProxy ? proxiedFetch : null }, () => {
+                Promise.resolve()
+                    .then(run)
+                    .then(resolve, reject);
+            });
+        });
+    }
+    const middleware = ((req, _res, next) => {
+        const routePath = req?.path || req?.url || "/";
+        const shouldProxy = shouldProxyPath(routePath, options) && !isStandDown();
+        req.consensus = {
+            strategy,
+            shouldProxy,
+            fetch: proxiedFetch,
+            request: proxiedRequest,
+            passthroughFetch: currentPassthroughFetch(),
+            createFetch,
+            getBudget,
+            isStandDown,
+        };
+        if (strategy !== "auto") {
+            next();
+            return;
+        }
+        ensureInterceptorInstalled();
+        proxyFetchContext.run({ proxyFetch: shouldProxy ? proxiedFetch : null }, () => next());
+    });
+    middleware.fetch = proxiedFetch;
+    middleware.request = proxiedRequest;
+    middleware.runWithPath = runWithPath;
+    middleware.createFetch = createFetch;
+    middleware.getBudget = getBudget;
+    middleware.resetBudget = resetBudget;
+    middleware.isStandDown = isStandDown;
+    return middleware;
+}