@elysra/tungsten-runtime 0.0.0-stage → 0.1.1

package/dist/classify.js

@@ -0,0 +1,301 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Classification of HTTP responses and lost requests into results and
+ * diagnostic envelopes (planning/06 "Diagnostic error envelope",
+ * "Unknown outcome", planning/04 "Remediation table resolution").
+ */
+import { categoryForStatus, diagnostic, GENERIC_REMEDIATION, isCategory, isRetryable } from "./envelope.js";
+import { hasReplayProtection } from "./idempotency.js";
+import { getPath, isRecord } from "./util.js";
+/** Headers that carry a request id, in lookup order. */
+const REQUEST_ID_HEADERS = ["x-request-id", "request-id", "x-correlation-id", "x-amzn-requestid", "cf-ray"];
+export function requestIdOf(headers) {
+    for (const name of REQUEST_ID_HEADERS) {
+        const value = headers[name];
+        if (value)
+            return value.slice(0, 200);
+    }
+    return null;
+}
+/** The media type without parameters, lowercased; "" when absent. */
+export function mediaTypeOf(headers) {
+    return (headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+}
+export function isJsonMedia(media) {
+    return media === "application/json" || media.endsWith("+json") || media === "text/json";
+}
+const JSONL_MEDIA = new Set(["application/jsonl", "application/x-jsonl", "application/ndjson", "application/x-ndjson"]);
+/** JSON Lines media types: one JSON value per line. */
+export function isJsonlMedia(media) {
+    return JSONL_MEDIA.has(media);
+}
+/** The response descriptor matching a status: exact, then `NXX`, then `default`. */
+export function matchResponse(responses, status) {
+    const list = Array.isArray(responses) ? responses.filter(isRecord) : [];
+    return (list.find((r) => r.status === status) ??
+        list.find((r) => typeof r.status === "string" && r.status === `${Math.floor(status / 100)}XX`) ??
+        list.find((r) => r.status === "default"));
+}
+export function decodeBody(bytes, headers, declared) {
+    const announced = mediaTypeOf(headers);
+    const media = announced || (declared ?? "").toLowerCase();
+    const text = () => new TextDecoder().decode(bytes);
+    // An empty body is no body, unless the server says it is JSON Lines: then it is no lines.
+    if (bytes.byteLength === 0 && !isJsonlMedia(announced))
+        return { value: undefined, json: false, invalidJson: false, empty: true };
+    if (isJsonlMedia(announced || media.split(";")[0].trim())) {
+        const raw = text();
+        const values = [];
+        const lines = raw.split("\n");
+        for (const [index, line] of lines.entries()) {
+            if (line.trim() === "")
+                continue;
+            try {
+                values.push(JSON.parse(line));
+            }
+            catch {
+                return { value: raw, json: false, invalidJson: true, empty: false, jsonl: true, badLine: index + 1 };
+            }
+        }
+        return { value: values, json: false, invalidJson: false, empty: false, jsonl: true };
+    }
+    if (isJsonMedia(media)) {
+        const raw = text();
+        try {
+            return { value: JSON.parse(raw), json: true, invalidJson: false, empty: false };
+        }
+        catch {
+            return { value: raw, json: false, invalidJson: true, empty: false };
+        }
+    }
+    if (media === "" || media.startsWith("text/") || media === "application/problem+xml" || media.endsWith("+xml") || media === "application/xml") {
+        const raw = text();
+        if (media === "" && /^\s*[[{]/.test(raw)) {
+            try {
+                return { value: JSON.parse(raw), json: true, invalidJson: false, empty: false };
+            }
+            catch {
+                // not JSON after all; keep the text
+            }
+        }
+        return { value: raw, json: false, invalidJson: false, empty: false };
+    }
+    return { value: bytes, json: false, invalidJson: false, empty: false };
+}
+const MESSAGE_FIELDS = ["message", "error.message", "detail", "error_description", "title", "error"];
+function serverMessage(body) {
+    for (const field of MESSAGE_FIELDS) {
+        const value = getPath(body, field);
+        if (typeof value === "string" && value.trim() !== "")
+            return value.trim().slice(0, 200);
+    }
+    return null;
+}
+function errorCode(op, body) {
+    const field = op.errorCodeField;
+    if (!field)
+        return null;
+    const value = getPath(body, field);
+    if (typeof value === "string" && value !== "")
+        return value.slice(0, 200);
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+function remediationEntry(table, code) {
+    if (code === null || !isRecord(table))
+        return undefined;
+    const entry = Object.prototype.hasOwnProperty.call(table, code) ? table[code] : undefined;
+    return isRecord(entry) ? entry : undefined;
+}
+/** Whether the verification hook's arguments can be built without the
+ * call's response: after a lost or ambiguous answer there is no success
+ * body, so a hook whose args reference `$response` cannot be called. */
+export function verifyCallable(verify) {
+    const refersToResponse = (node, depth) => {
+        if (depth > 32)
+            return true;
+        if (typeof node === "string")
+            return node === "$response" || node.startsWith("$response.");
+        if (Array.isArray(node))
+            return node.some((item) => refersToResponse(item, depth + 1));
+        if (isRecord(node))
+            return Object.values(node).some((item) => refersToResponse(item, depth + 1));
+        return false;
+    };
+    return isRecord(verify) && !refersToResponse(verify.args, 0);
+}
+/** What resolves an unknown outcome: the verification hook when it can be
+ * called without the lost response, else repeating the call under its
+ * replay protection (the same key, or the identical body), which answers
+ * the original result instead of applying the effect twice. Null when
+ * nothing can resolve it safely. */
+function nextActionHint(ctx) {
+    const verify = ctx.op.agent.verify;
+    if (verify && typeof verify.operation === "string" && verifyCallable(verify)) {
+        const keys = isRecord(verify.args) ? Object.keys(verify.args) : [];
+        const withArgs = keys.length > 0 ? ` with ${keys.join(", ")}` : "";
+        return `Call ${verify.operation}${withArgs} to check whether ${ctx.op.id} took effect before doing anything else.`;
+    }
+    if (ctx.op.agent.idempotency.policy === "content_identity") {
+        return `Call ${ctx.op.id} again with the identical body; the body is its own identity, so the server answers the original result instead of applying it twice.`;
+    }
+    if (ctx.key !== null) {
+        return `Call ${ctx.op.id} again with the same ${ctx.keyHeader} value and identical arguments; the server answers the original result instead of applying it twice.`;
+    }
+    return null;
+}
+/** The change an operation makes, in words, for remediation text: its
+ * summary when it has one (`the change "Rotate an endpoint's signing
+ * secret"`). */
+export function changeOf(op) {
+    const summary = typeof op.summary === "string" ? op.summary.trim().replace(/\.$/, "") : "";
+    return summary === "" ? `the change ${op.id} makes` : `the change ${JSON.stringify(summary)}`;
+}
+/** OUTCOME_UNKNOWN for a mutation whose effect cannot be known. Without
+ * replay protection (no key, no identity body) a repeat can apply the
+ * effect twice, so the envelope never offers one: `retryable` is
+ * `after_remediation` (check the state first), not `same_key_only`, and
+ * the remediation and `next_action` say what to check before repeating:
+ * `ctx.check` when the client found a read that shows it, else the
+ * operation's own change in words. */
+export function outcomeUnknown(ctx, cause, fields = {}) {
+    const op = ctx.op;
+    let rule;
+    let hint = null;
+    if (op.agent.idempotency.policy === "content_identity") {
+        rule = "If you retry, resend the identical bytes only; the body is its own identity.";
+    }
+    else if (ctx.key !== null) {
+        rule = `If you retry, reuse the SAME ${ctx.keyHeader} value; a new key can apply the effect twice.`;
+    }
+    else if (ctx.check) {
+        // What to verify, specific to the operation: its verification hook, or
+        // a read of the resource it changes.
+        const { call, shows } = ctx.check;
+        rule = `This operation has no idempotency key, so repeating it can apply the effect twice. Before calling ${op.id} again, call ${call} and check ${shows}: if it does, ${op.id} took effect and must not be repeated; call it again only if it did not.`;
+        hint = `Call ${call} and check ${shows}; call ${op.id} again only if it did not take effect.`;
+    }
+    else {
+        const change = changeOf(op);
+        rule = `This operation has no idempotency key and no registered way to verify it, so ${op.id} may have taken effect and a repeat can apply the effect twice: do not retry it blindly. Check the outcome by other means if you can (look for ${change}); if you cannot, ask whoever owns the task before calling it again.`;
+        hint = `Do not retry ${op.id} blindly: it may have taken effect. Check for ${change} if you can; call ${op.id} again only if it is not there, or after the task owner accepts that it may apply twice.`;
+    }
+    return diagnostic(op.id, "OUTCOME_UNKNOWN", {
+        remediation: `${cause} The server may or may not have applied ${op.id}. ${rule}`,
+        retryable: hasReplayProtection(op, ctx.key) ? "same_key_only" : "after_remediation",
+        next_action: fields.next_action ?? hint ?? nextActionHint(ctx),
+        http_status: fields.http_status ?? null,
+        code: fields.code ?? null,
+        request_id: fields.request_id ?? null,
+        retry_after_ms: fields.retry_after_ms ?? null,
+        trace: { attempts: ctx.attempts },
+    });
+}
+/** Categories that say the request was not applied, or that a repeat is
+ * pointless: a manifest entry with one of them (or with `retryable`
+ * `never` / `after_remediation`) is a definite answer even for a status
+ * that is otherwise ambiguous. */
+const DEFINITE_CATEGORIES = new Set([
+    "VALIDATION_FAILED",
+    "MALFORMED_REQUEST",
+    "REQUEST_TOO_LARGE",
+    "AUTH_FAILED",
+    "NOT_FOUND",
+    "CONFLICT",
+    "PRECONDITION_FAILED",
+    "RATE_LIMITED",
+    "GATE_DISABLED",
+]);
+function definite(entry) {
+    if (!entry)
+        return false;
+    if (entry.retryable === "never" || entry.retryable === "after_remediation")
+        return true;
+    return typeof entry.category === "string" && DEFINITE_CATEGORIES.has(entry.category);
+}
+export function isMutation(op) {
+    return op.agent.safety !== "read_only";
+}
+/** The classification of an HTTP error status. */
+export function classifyError(ctx, status, headers, decoded, retryAfterMs) {
+    const { api, op } = ctx;
+    const requestId = requestIdOf(headers);
+    const base = { http_status: status, request_id: requestId, retry_after_ms: retryAfterMs, trace: { attempts: ctx.attempts } };
+    const code = decoded.json ? errorCode(op, decoded.value) : null;
+    // A disabled gate answers its status without the API's error document
+    // (ZROtext: the route is not mounted, so axum's bare 404). An answer
+    // with an error code comes from the mounted route, so it is classified
+    // by its code like any other error (an unknown id is NOT_FOUND).
+    if (op.status.kind === "gated" && status === op.status.disabledStatus && code === null) {
+        const gates = isRecord(api.gates) ? api.gates : {};
+        const text = typeof gates[op.status.envVar] === "string" ? gates[op.status.envVar] : null;
+        return diagnostic(op.id, "GATE_DISABLED", {
+            ...base,
+            code,
+            remediation: text ??
+                `This deployment disables ${op.id} because ${op.status.envVar} is off (HTTP ${status}). It is a deployment setting, not a missing resource; do not retry.`,
+            retryable: "never",
+        });
+    }
+    const entry = remediationEntry(op.agent.remediation, code) ?? remediationEntry(api.errorCodes, code);
+    const media = decoded.empty ? "none" : mediaTypeOf(headers) || "none";
+    const nonJson = decoded.json
+        ? undefined
+        : (Array.isArray(api.nonJson) ? api.nonJson : []).find((n) => isRecord(n) && n.status === status && (n.media === media || (n.media === "none" && decoded.empty)));
+    const declared = matchResponse(op.responses, status);
+    // On a mutation, a status listed as ambiguous, a response declared
+    // ambiguous, and any 5xx leave the outcome unknown (a gateway's 502/504
+    // or an intermediary's 500 says nothing about whether the origin
+    // committed), unless the manifest's entry for the answer's code or
+    // non-JSON shape says it is a definite rejection (billing_pending,
+    // retryable: never).
+    const ambiguous = (Array.isArray(api.ambiguousStatuses) && api.ambiguousStatuses.includes(status)) ||
+        declared?.kind === "ambiguous" ||
+        (status >= 500 && status <= 599);
+    if (ambiguous && isMutation(op) && !definite(entry ?? (isRecord(nonJson) ? nonJson : undefined))) {
+        // The manifest's text for this answer still explains it.
+        const said = entry && typeof entry.text === "string" ? entry.text : nonJson && typeof nonJson.text === "string" ? nonJson.text : null;
+        return outcomeUnknown(ctx, `HTTP ${status} leaves the outcome of this call unknown.${said ? ` ${said}` : ""}`, {
+            ...base,
+            code,
+            next_action: typeof entry?.next_action === "string" ? entry.next_action : null,
+        });
+    }
+    let category;
+    let retryable;
+    let text = null;
+    let nextAction = null;
+    if (entry) {
+        category = isCategory(entry.category) ? entry.category : categoryForStatus(status, decoded.json);
+        retryable = isRetryable(entry.retryable) ? entry.retryable : undefined;
+        text = typeof entry.text === "string" ? entry.text : null;
+        nextAction = typeof entry.next_action === "string" ? entry.next_action : null;
+    }
+    else if (nonJson && isCategory(nonJson.category)) {
+        category = nonJson.category;
+        retryable = isRetryable(nonJson.retryable) ? nonJson.retryable : undefined;
+        text = typeof nonJson.text === "string" ? nonJson.text : null;
+    }
+    else {
+        category = categoryForStatus(status, decoded.json);
+    }
+    if (category === "OUTCOME_UNKNOWN" && !isMutation(op)) {
+        // A read has no effect whose outcome could be unknown: the answer only
+        // says the service did not respond in time.
+        category = "UPSTREAM_UNAVAILABLE";
+        if (retryable === undefined || retryable === "same_key_only")
+            retryable = "after_delay";
+    }
+    if (text === null) {
+        const said = decoded.json ? serverMessage(decoded.value) : null;
+        text = `${GENERIC_REMEDIATION[category]}${said ? ` Server message: ${JSON.stringify(said)}` : ""}`;
+    }
+    return diagnostic(op.id, category, {
+        ...base,
+        code,
+        remediation: text,
+        ...(retryable ? { retryable } : {}),
+        next_action: nextAction,
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { OAuthFlow } from "./oauth.js";
+import { EventStream } from "./streams.js";
+import type { ApiDescriptor, CallOptions, ClientCoreApi, ClientCoreExtensions, ClientOptions, MacroDescriptor, OperationDescriptor, Page, Predicate, PreviewResult, Result } from "./types.js";
+/**
+ * The runtime core used by generated clients. One instance per client:
+ * it owns the idempotency store, the confirmation-token key, the OAuth2
+ * token cache and the registry of operations resolvable by id.
+ */
+export declare class ClientCore implements ClientCoreApi, ClientCoreExtensions {
+    #private;
+    readonly api: ApiDescriptor;
+    readonly options: ClientOptions;
+    constructor(api: ApiDescriptor, options?: ClientOptions);
+    /** Make operations resolvable by id for verification hooks, endpoint
+     * previews and macro steps. Invalid entries are ignored. */
+    register(...ops: OperationDescriptor[]): void;
+    /** A registered operation by id. */
+    operation(id: string): OperationDescriptor | undefined;
+    /** Validate, authenticate, apply idempotency and confirmation rules,
+     * send with retries and classify the response. Never throws. */
+    call<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): Promise<Result<T>>;
+    /** Run the operation's preview mode: local rendering (no network), a
+     * dry-run header, or a preview endpoint. Mutating operations get a
+     * confirmation token bound to these exact arguments for five minutes. */
+    preview(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): Promise<Result<PreviewResult>>;
+    /** Iterate pages (cursor, offset, page number or `Link` header); stops
+     * after the last page or after yielding the first error. */
+    pages<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): AsyncIterable<Result<Page<T>>>;
+    /** Iterate the events of the operation's event stream: one item per
+     * server-sent event, decoded from JSON, then the end of the stream or a
+     * final failure item. Never throws. */
+    stream<T>(op: OperationDescriptor, args: Record<string, unknown>, opts?: CallOptions): EventStream<T>;
+    /** Call a read operation until `until` holds on its body or the budget
+     * runs out (`timedOut: true` with the last result). */
+    poll<T>(op: OperationDescriptor, args: Record<string, unknown>, until: Predicate, intervalMs: number, budgetMs: number, opts?: CallOptions): Promise<Result<T> & {
+        timedOut?: boolean;
+    }>;
+    /** Run a compiled macro: steps in order, each step's success body bound
+     * to its `as` name; returns the evaluated output, or the first failing
+     * step's envelope (its remediation names the steps already completed). */
+    runMacro<T>(macro: MacroDescriptor, input: Record<string, unknown>, opts?: CallOptions): Promise<Result<T>>;
+    /** Preview a macro: no request is sent. Validates and renders the first
+     * step, lists the effects of every step, and returns a confirmation token
+     * bound to the macro and this exact input unless the macro is read-only. */
+    previewMacro(macro: MacroDescriptor, input: Record<string, unknown>, opts?: CallOptions): Promise<Result<PreviewResult>>;
+    /** The OAuth2 authorization-code helpers of the scheme `scheme`: PKCE, the
+     * authorization URL, the code exchange and refresh. */
+    oauth(scheme: string): OAuthFlow;
+}