@zackbart/connecta 0.34.1 → 0.36.0

package/dist/http/client.js

@@ -0,0 +1,439 @@
+import { confinementBase, REDIRECT_STATUSES, BODILESS_STATUSES } from "../http-policy.js";
+import { guardedTransport, sendGuarded } from "../guarded-transport.js";
+// Guarded HTTP transport (decision 0010, B.2). Unreachable from src/index.ts.
+//
+// The guarded transport as an Effect `HttpClient`, with the behaviour of
+// src/connectors/guarded-fetch.ts: requests confined beneath one base URL,
+// credentials applied last and registered as sent secrets, redirects refused,
+// bodies read under a byte ceiling, and network failures normalized. It is
+// built with `HttpClient.makeWith`, not `HttpClient.make`, so it carries no
+// span, no `traceparent`/`b3` header, and no response registry: what leaves
+// connecta is exactly what this file assembles. It is also the one place a
+// request reaches `fetch`, so it keeps the call's dispatch ledger and refuses
+// a second dispatch of any logical write, whatever above it asked for one.
+// Each request enters the core's ledger (src/provider-call.ts) synchronously
+// before `fetch`, with its method, any idempotency key it carries, and its
+// status once answered: the facts `api()`'s boundary decides a write from.
+//
+// effect/http is annotated unstable in 4.0.5. Only client.ts, oauth.ts and
+// vendor.ts import the HTTP area modules; providers never do.
+import { Context, Effect, Stream } from "effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as Url from "effect/http/Url";
+import { ConnectorCallError } from "../errors.js";
+import { readRequest, recordProviderResponse } from "../provider-call.js";
+import { recordRequestField } from "../provider-call-facts.js";
+import { fromSignal } from "../runtime/run.js";
+import { RedirectRefused, Refusal, RequestRefused, ResendRefused, ResponseTooLarge, TransportFailure, } from "./errors.js";
+import { Classification, Dispatches, IdempotencyKey, Ledger, RequestFacts, Secrets, Signal, WriteCapacity, reserveWrite, writeRequestKey, } from "./services.js";
+const decoder = new TextDecoder();
+const responseEntries = new WeakMap();
+/** The core's physical request, also available to direct HttpClient middleware. */
+export function responseRequest(response) {
+    return responseEntries.get(response);
+}
+export function guardedClient(options) {
+    const { provider, maxResponseBytes: limit } = options;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error(`${provider} maxResponseBytes must be a whole number of bytes >= 1; received ${String(limit)}.`);
+    }
+    const unauthorizedLimit = options.maxUnauthorizedResponseBytes;
+    if (unauthorizedLimit !== undefined && (!Number.isInteger(unauthorizedLimit) || unauthorizedLimit < 1))
+        throw new Error("maxUnauthorizedResponseBytes must be a whole number of bytes >= 1.");
+    const responseLimit = (status) => (status === 401 ? Math.min(limit, unauthorizedLimit ?? limit) : limit);
+    if (options.timeoutMs !== undefined && (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1))
+        throw new Error("timeoutMs must be a positive whole number.");
+    const base = confinementBase(provider, options.baseUrl);
+    const basePath = base.pathname.replace(/\/+$/, "");
+    const constant = { ...options.headers };
+    const refuse = (message) => Effect.fail(new RequestRefused({ message }));
+    const preparedEntries = new WeakMap();
+    // Confine, then authenticate last, then register what will be sent.
+    const preprocess = (request) => Effect.gen(function* () {
+        const facts = yield* RequestFacts;
+        const idempotency = facts.effect === "call" ? yield* IdempotencyKey : undefined;
+        const entry = (yield* Ledger).open({
+            auxiliary: facts.effect === "read",
+            provider,
+            method: request.method,
+            ...(idempotency ? { key: idempotency.key } : {}),
+        });
+        const path = request.url;
+        if (!path.startsWith("/")) {
+            return yield* refuse(`A ${provider} request path is provider-relative and must begin with "/".`);
+        }
+        if (path.includes("?") || path.includes("#") || request.hash._tag === "Some") {
+            return yield* refuse(`A ${provider} request path carries no query or fragment; put query parameters in the query argument.`);
+        }
+        let url;
+        try {
+            url = new URL(`${base.origin}${basePath}${path}`);
+        }
+        catch {
+            return yield* refuse(`A ${provider} request path did not resolve to a valid URL.`);
+        }
+        if (url.origin !== base.origin || !`${url.pathname}/`.startsWith(`${basePath}/`)) {
+            return yield* refuse(`A ${provider} request path escaped the connector's base URL.`);
+        }
+        let confined = HttpClientRequest.setUrl(request, url.href);
+        if (options.admit)
+            yield* options.admit(wireUrl(confined), {
+                method: confined.method,
+                ...(bodyText(confined) === undefined ? {} : { body: bodyText(confined) }),
+            });
+        for (const [name, value] of Object.entries(constant)) {
+            if (confined.headers[name.toLowerCase()] === undefined)
+                confined = HttpClientRequest.setHeader(confined, name, value);
+        }
+        const secrets = yield* Secrets;
+        for (const [name, value] of Object.entries(yield* options.authenticate)) {
+            if (confined.headers[name.toLowerCase()] !== undefined) {
+                return yield* refuse(`A ${provider} request may not set the ${name.toLowerCase()} header; authentication is connector-owned.`);
+            }
+            confined = HttpClientRequest.setHeader(confined, name, value);
+            secrets.header(value);
+        }
+        // Registered as guarded-fetch registers: the final URL, headers, and a
+        // text body (a form body's secrets are read from it).
+        const text = bodyText(confined);
+        secrets.request(wireUrl(confined), {
+            headers: Object.fromEntries(Object.entries(confined.headers)),
+            ...(text === undefined ? {} : { body: text }),
+        });
+        preparedEntries.set(confined, entry);
+        return confined;
+    });
+    const postprocess = (prepared) => Effect.gen(function* () {
+        const callSignal = yield* Signal;
+        const live = () => callSignal?.aborted ? refuse("This call has ended; no transport work may continue.") : Effect.void;
+        yield* live();
+        const facts = yield* RequestFacts;
+        const ledger = yield* Dispatches;
+        // A new attempt: until it is handed to `fetch`, no failure is its answer.
+        if (facts.sent)
+            delete facts.sent.dispatch;
+        const earlyWrite = (yield* Classification) === "write";
+        const capacity = yield* WriteCapacity;
+        // Claim the early Send reservation (or reserve a direct HttpClient call)
+        // atomically, before evaluating `prepared`. A wrapper cannot reuse it.
+        const claim = () => {
+            const reserved = facts.sent?.reservation ?? reserveWrite(ledger, capacity, facts);
+            if (reserved instanceof RequestRefused || reserved instanceof ResendRefused)
+                return reserved;
+            if (reserved.state !== "reserved")
+                return new ResendRefused({ first: reserved });
+            reserved.state = "preparing";
+            return reserved;
+        };
+        const initial = yield* Effect.sync(() => (earlyWrite ? claim() : undefined));
+        if (initial instanceof RequestRefused || initial instanceof ResendRefused)
+            return yield* Effect.fail(initial);
+        let slot = initial;
+        return yield* Effect.gen(function* () {
+            const preparation = callSignal
+                ? Effect.raceFirst(prepared, fromSignal(callSignal).pipe(Effect.mapError(() => new RequestRefused({ message: "This call has ended; no transport work may continue." }))))
+                : prepared;
+            const request = yield* preparation;
+            const url = wireUrl(request);
+            yield* live();
+            const headers = Object.fromEntries(Object.entries(request.headers).filter(([name]) => name !== "content-length"));
+            // A genuine key the vendor honors rides only on the tool's own request,
+            // added after sent-secret registration like guarded-fetch's visible
+            // headers. Only a key sent here is recorded, so only it can make the
+            // write repeatable or earn key-reuse advice (`keyProtectsCall`).
+            const idempotency = facts.effect === "call" ? yield* IdempotencyKey : undefined;
+            if (idempotency) {
+                const name = idempotency.header.toLowerCase();
+                if (Object.keys(headers).some((header) => header.toLowerCase() === name)) {
+                    return yield* refuse(`A ${provider} request sets the ${name} header twice.`);
+                }
+                headers[idempotency.header] = idempotency.key;
+            }
+            const core = yield* Ledger;
+            const entry = preparedEntries.get(request) ??
+                core.open({
+                    auxiliary: facts.effect === "read",
+                    provider,
+                    method: request.method,
+                    ...(idempotency ? { key: idempotency.key } : {}),
+                });
+            const write = !readRequest({ classification: entry.classification, method: request.method }, headers);
+            // Preparation can reveal a write in a served read or auxiliary request.
+            // The core's actual facts and final headers decide before any dispatch.
+            if (write && !slot) {
+                const reserved = yield* Effect.sync(claim);
+                if (reserved instanceof RequestRefused || reserved instanceof ResendRefused)
+                    return yield* Effect.fail(reserved);
+                slot = reserved;
+            }
+            const expected = slot ? capacity.get(slot.step)?.get(slot.item) : undefined;
+            if (expected) {
+                const text = bodyText(request);
+                const contentType = request.headers["content-type"]?.split(";")[0]?.trim();
+                if (request.body._tag !== "Empty" &&
+                    (text === undefined ||
+                        !["application/x-www-form-urlencoded", "application/json"].includes(contentType ?? ""))) {
+                    return yield* refuse("A bulk item request must use its declared form or JSON body.");
+                }
+                const actual = yield* Effect.try({
+                    try: () => writeRequestKey({
+                        method: request.method,
+                        path: url.pathname.slice(basePath.length),
+                        template: expected.template,
+                        query: [...url.searchParams],
+                        ...(text === undefined
+                            ? {}
+                            : contentType === "application/json"
+                                ? { json: text }
+                                : { form: [...new URLSearchParams(text)] }),
+                        ...(expected.multiValue ? { multiValue: expected.multiValue } : {}),
+                    }),
+                    catch: () => new RequestRefused({ message: "Duplicate or invalid identifying content in this write item's request." }),
+                });
+                if (actual !== writeRequestKey(expected))
+                    return yield* refuse("This write item's request differs from its declared identifying content.");
+            }
+            // Resolve the runtime-owned sender before recording a physical dispatch.
+            const transport = yield* Effect.try({
+                try: () => guardedTransport(write),
+                catch: (error) => new Refusal({ error: error }),
+            });
+            const body = bodyInit(request);
+            // A reservation is never released, including preparation failures and
+            // failures to connect. Only a new deliberate call gets capacity.
+            const dispatch = slot ?? {
+                write: false,
+                ...(facts.operation ? { operation: facts.operation } : {}),
+                state: "pending",
+            };
+            if (!slot)
+                ledger.push(dispatch);
+            dispatch.request = entry;
+            if (facts.sent)
+                facts.sent.dispatch = dispatch;
+            const refused = (failure) => {
+                dispatch.failure = failure;
+                responseEntries.set(failure, entry);
+                return Effect.fail(failure);
+            };
+            const response = yield* Effect.tryPromise({
+                try: (interrupted) => {
+                    // Synchronous with the send: from here the core counts it as left,
+                    // and it refuses a request whose call has already ended.
+                    if (facts.effect === "read" && !readRequest({ classification: "read", method: request.method }, headers))
+                        recordRequestField(entry, "blocksAuxiliaryProof", true);
+                    dispatch.state = "pending";
+                    return sendGuarded(transport, url, {
+                        method: request.method,
+                        headers,
+                        ...body,
+                        // A redirect re-sends the credential wherever `Location` points.
+                        redirect: "manual",
+                        signal: AbortSignal.any([
+                            interrupted,
+                            ...(callSignal ? [callSignal] : []),
+                            ...(options.timeoutMs === undefined ? [] : [AbortSignal.timeout(options.timeoutMs)]),
+                        ]),
+                    }, () => core.dispatch(entry, headers, request.method));
+                },
+                catch: (failure) => {
+                    if (!entry.dispatched) {
+                        return failure instanceof ConnectorCallError
+                            ? new Refusal({ error: failure })
+                            : new RequestRefused({ message: "This call has ended; no transport work may continue." });
+                    }
+                    // No rejection proves a write unsent: one fetch can hide several
+                    // attempts (a 421 or HTTP/2 refused-stream resend, a retrying
+                    // dispatcher), whatever the last one reports (#902 round 8).
+                    dispatch.state = "lost";
+                    return (dispatch.failure = new TransportFailure({ failure, host: url.href }));
+                },
+            });
+            dispatch.state = "answered";
+            dispatch.status = response.status;
+            recordProviderResponse(entry, response.status);
+            dispatch.headers = response.headers;
+            if (REDIRECT_STATUSES.has(response.status)) {
+                yield* cancel(response);
+                return yield* refused(new RedirectRefused({ status: response.status }));
+            }
+            const declared = Number(response.headers.get("content-length"));
+            const ceiling = responseLimit(response.status);
+            if (Number.isFinite(declared) &&
+                declared > ceiling &&
+                request.method !== "HEAD" &&
+                !(facts.successPrefix && response.ok)) {
+                yield* cancel(response);
+                return yield* refused(tooLarge(provider, ceiling, `a declared ${declared} bytes`));
+            }
+            const answer = HttpClientResponse.fromWeb(request, response);
+            responseEntries.set(answer, entry);
+            return answer;
+        }).pipe(Effect.tapError((failure) => Effect.sync(() => {
+            if (slot && slot.failure === undefined && failure._tag !== "ResendRefused")
+                slot.failure = failure;
+        })));
+    });
+    return {
+        provider,
+        client: HttpClient.makeWith(postprocess, preprocess),
+        read: (response, maxBytes, format, prefix) => {
+            if (maxBytes !== undefined && (!Number.isInteger(maxBytes) || maxBytes < 1))
+                throw new Error("A read ceiling must be a whole number of bytes >= 1.");
+            if (prefix && response.status >= 200 && response.status <= 299) {
+                if (!Number.isSafeInteger(prefix.maxBytes) || prefix.maxBytes < (format === "bytes" ? 0 : 1))
+                    throw new Error("A success prefix needs a whole byte ceiling >= 0 for bytes or >= 1 for text.");
+                if (prefix.timeoutMs !== undefined && (!Number.isSafeInteger(prefix.timeoutMs) || prefix.timeoutMs < 1))
+                    throw new Error("A success prefix timeout must be a positive whole number.");
+                return readSuccessPrefix(response, {
+                    ...prefix,
+                    maxBytes: Math.min(limit, maxBytes ?? limit, prefix.maxBytes),
+                    ...(prefix.timeoutMs === undefined
+                        ? {}
+                        : {
+                            timeoutMs: Math.min(prefix.timeoutMs, options.timeoutMs ?? Infinity),
+                        }),
+                }, format);
+            }
+            return readReply(provider, Math.min(responseLimit(response.status), maxBytes ?? limit), response, format);
+        },
+    };
+}
+/** The exact URL `fetch` receives: confined path plus encoded query. */
+function wireUrl(request) {
+    const built = Url.make(request.url, request.urlParams, undefined);
+    if (built._tag === "Failure")
+        throw new Error("A confined request URL failed to build.");
+    return built.success;
+}
+/** A JSON, form, or text body as the string guarded-fetch would have sent. */
+function bodyText(request) {
+    const body = request.body;
+    if (body._tag === "Uint8Array")
+        return body.text;
+    return body._tag === "Raw" && typeof body.body === "string" ? body.body : undefined;
+}
+function bodyInit(request) {
+    const body = request.body;
+    switch (body._tag) {
+        case "Empty":
+            return {};
+        case "Raw":
+            return { body: body.body };
+        case "Uint8Array":
+            // The retained text when there is one, so the wire carries exactly the
+            // string guarded-fetch sent.
+            return { body: (body.text ?? body.body) };
+        case "FormData":
+            return { body: body.formData };
+        case "Stream":
+            // A stream cannot be read twice or measured; no kit operation sends one.
+            throw new Error("The guarded client does not send stream bodies.");
+    }
+}
+function tooLarge(provider, limit, detail) {
+    return new ResponseTooLarge({
+        detail: `${provider} returned ${detail}, past this connector's ${limit}-byte response ceiling.`,
+    });
+}
+function cancel(response) {
+    return Effect.promise(() => response.body?.cancel().catch(() => { }) ?? Promise.resolve());
+}
+/** Stream finalization cancels the unread body on every early stop or interruption. */
+function readSuccessPrefix(response, prefix, format) {
+    return Effect.suspend(() => {
+        const parts = [];
+        let total = 0;
+        let stopped = "end";
+        const source = response.stream.pipe(Stream.catch((error) => error.reason._tag === "EmptyBodyError"
+            ? Stream.fromEffect(response.arrayBuffer.pipe(Effect.map((buffer) => new Uint8Array(buffer))))
+            : Stream.fail(error)));
+        const consume = Stream.runForEachWhile(source, (chunk) => {
+            const kept = chunk.subarray(0, Math.max(0, prefix.maxBytes - total));
+            parts.push(kept);
+            total += kept.byteLength;
+            if (kept.byteLength < chunk.byteLength) {
+                stopped = "bytes";
+                return Effect.succeed(false);
+            }
+            // A callback closes over no Effect services from the invoking request.
+            return Effect.sync(() => prefix.stop?.(kept.slice()) === true).pipe(Effect.setContext(Context.empty()), Effect.map((stop) => {
+                if (stop)
+                    stopped = "stop";
+                return !stop;
+            }));
+        });
+        const timed = prefix.timeoutMs === undefined
+            ? consume
+            : Effect.raceFirst(consume, Effect.sleep(prefix.timeoutMs).pipe(Effect.tap(() => Effect.sync(() => {
+                stopped = "time";
+            }))));
+        return timed.pipe(Effect.match({
+            onFailure: () => ({
+                status: response.status,
+                headers: new Headers(Object.entries(response.headers)),
+                text: undefined,
+            }),
+            onSuccess: () => {
+                const bytes = new Uint8Array(total);
+                let offset = 0;
+                for (const part of parts) {
+                    bytes.set(part, offset);
+                    offset += part.byteLength;
+                }
+                return {
+                    status: response.status,
+                    headers: new Headers(Object.entries(response.headers)),
+                    ...(format === "bytes" ? { text: undefined, bytes } : { text: decoder.decode(bytes) }),
+                    prefix: { truncated: stopped !== "end", bytes: total, stopped },
+                };
+            },
+        }));
+    });
+}
+/**
+ * The body as UTF-8 decoded from bounded bytes (never `text()`, whose runtime
+ * log can quote a non-text Content-Type, INV-6). The stream is abandoned at
+ * the chunk that crosses the ceiling, and its reader is cancelled when the
+ * read ends either way. A runtime with no body stream has buffered already,
+ * so the buffer is measured instead. Any other read failure leaves `text`
+ * undefined, as guarded-fetch's `jsonResult` reported a parse failure.
+ */
+function readReply(provider, limit, response, format) {
+    const reply = (text, bytes, readFailed) => ({
+        status: response.status,
+        headers: new Headers(Object.entries(response.headers)),
+        text,
+        ...(bytes === undefined ? {} : { bytes }),
+        ...(readFailed ? { readFailed } : {}),
+    });
+    if (BODILESS_STATUSES.has(response.status) || response.request.method === "HEAD")
+        return Effect.succeed(format === "bytes" ? reply(undefined, new Uint8Array()) : reply(""));
+    const buffered = response.arrayBuffer.pipe(Effect.matchEffect({
+        onFailure: () => Effect.succeed(reply(undefined, undefined, true)),
+        onSuccess: (buffer) => buffer.byteLength > limit
+            ? Effect.fail(tooLarge(provider, limit, `${buffer.byteLength} bytes`))
+            : Effect.succeed(format === "bytes" ? reply(undefined, new Uint8Array(buffer)) : reply(decoder.decode(buffer))),
+    }));
+    return response.stream.pipe(Stream.runFoldEffect(() => ({ parts: [], total: 0 }), (read, chunk) => {
+        read.total += chunk.byteLength;
+        if (read.total > limit)
+            return Effect.fail(tooLarge(provider, limit, "more bytes than it may"));
+        read.parts.push(chunk);
+        return Effect.succeed(read);
+    }), Effect.map(({ parts, total }) => {
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const part of parts) {
+            bytes.set(part, offset);
+            offset += part.byteLength;
+        }
+        return format === "bytes" ? reply(undefined, bytes) : reply(decoder.decode(bytes));
+    }), Effect.catch((error) => error._tag === "ResponseTooLarge"
+        ? Effect.fail(error)
+        : error.reason._tag === "EmptyBodyError"
+            ? buffered
+            : Effect.succeed(reply(undefined, undefined, true))));
+}