@sponson/adapters 0.4.0 → 0.5.0

package/dist/http-adapter-client.js

@@ -0,0 +1,156 @@
+/**
+ * The generic `http` adapter's client and the requests both of its ops send: the API from the line's provider
+ * block (`actx.provider` is `providers.http.<api>`, narrowed by `OpSpec.providerFor`), its credential from the
+ * environment variable(s) the block names, and writes with the idempotency each method has.
+ */
+import { SponsonError, canonicalJson, markerKind } from "@sponson/core";
+import { clientFor, optionalEnv } from "./common.js";
+import { isObject, isProviderError } from "./http.js";
+import { DEFAULT_AUTH_DEPS, credentialFor } from "./http-adapter-auth.js";
+import { ADAPTER, at, pointerTokens, parseApi } from "./http-adapter-spec.js";
+/** The dependencies an op was built with, by the adapter context each of its calls received (see `withDeps`). */
+const DEPS = new WeakMap();
+/**
+ * `op` with every call's adapter context carrying `deps` (how `auth.command` runs a CLI, the clock), so the
+ * clients built inside see them. The built-in adapter uses the real ones; tests inject fakes.
+ */
+export function withDeps(op, deps) {
+    const bind = (actx) => {
+        const bound = { ...actx };
+        DEPS.set(bound, deps);
+        return bound;
+    };
+    return {
+        ...op,
+        read: (actx, params) => op.read(bind(actx), params),
+        apply: (actx, params, live) => op.apply(bind(actx), params, live),
+        destroy: (actx, resources) => op.destroy(bind(actx), resources),
+        ...(op.listScope ? { listScope: (actx, params) => op.listScope(bind(actx), params) } : {}),
+    };
+}
+/** A line's own credential value (`credential`), by the adapter context its calls use (see `withLineCredential`). */
+const LINE_CREDENTIAL = new WeakMap();
+/**
+ * `actx` for a line with `credential` (ADR 0017, "Line credentials"): its clients send that value instead of the
+ * API block's variable. The value is registered as a secret before any request carries it (the engine masks
+ * sensitive outputs and secrets already; this covers an engine without the hook). Without one, `actx` itself.
+ */
+export function withLineCredential(actx, value) {
+    if (value === undefined)
+        return actx;
+    if (typeof value !== "string" || value === "" || markerKind(value) !== null) {
+        throw new SponsonError("PARAM_INVALID", `${ADAPTER}: \`credential\` has no value to authenticate with (a reference not resolved yet, or a once-only output kept from an earlier run)`, { adapter: ADAPTER, param: "credential" });
+    }
+    actx.secret?.(value);
+    const bound = { ...actx };
+    const deps = DEPS.get(actx);
+    if (deps)
+        DEPS.set(bound, deps);
+    LINE_CREDENTIAL.set(bound, value);
+    return bound;
+}
+/** The variables holding a credential's secret part, for `refuse_credential`. */
+function secretEnvs(auth) {
+    switch (auth.kind) {
+        case "bearer":
+        case "header":
+            return [auth.env];
+        case "headers":
+            return auth.headers.map((h) => h.env);
+        case "basic":
+        case "digest":
+            return [auth.passwordEnv];
+        case "oauth2":
+            return [auth.clientSecretEnv];
+        case "sigv4":
+            return [auth.secretAccessKeyEnv];
+        case "command":
+        case "none":
+            return [];
+    }
+}
+/**
+ * Refuse a credential the API refuses (`refuse_credential`): PROVIDER_AUTH naming the variable and the prefix,
+ * never the value, before any request is sent.
+ */
+function refuseCredentials(cfg, env, line) {
+    if (!cfg.refuse || /^(1|true)$/i.test(env[cfg.refuse.unlessEnv] ?? ""))
+        return;
+    // A line's own credential is checked like the variable it replaces, and named as `credential`.
+    const values = line === undefined ? secretEnvs(cfg.auth).map((name) => [name, env[name] ?? ""]) : [["credential", line]];
+    for (const [name, value] of values) {
+        const prefix = cfg.refuse.prefixes.find((p) => value.startsWith(p));
+        if (!prefix)
+            continue;
+        throw new SponsonError("PROVIDER_AUTH", `${ADAPTER}: ${name} holds a \`${prefix}…\` credential, which this API refuses (refuse_credential): a preview environment must not write with it. ` +
+            `Use a test-mode credential, or set ${cfg.refuse.unlessEnv}=1 if this run really is meant to use it.`, { adapter: ADAPTER, env: name });
+    }
+}
+/**
+ * The client for the line's API. The credential (a static header, or a signer for the forms obtained or computed
+ * per request) comes from http-adapter-auth.ts; everything it holds or obtains is masked in this client's error text
+ * too, whatever the engine already masks. `opts`: where the block is, for messages; whether a block without `auth`
+ * sends no credential (a manual step's verify request); the adapter named in errors.
+ */
+export function httpClient(actx, req = {}, opts = {}) {
+    const cfg = parseApi(actx.provider, opts.where ?? "providers.http.<api>", opts);
+    const baseUrl = (cfg.baseUrlEnv ? optionalEnv(actx.env, cfg.baseUrlEnv) : undefined) ?? cfg.baseUrl;
+    let hidden = () => [];
+    const redact = (t) => hidden().reduce((s, h) => (h.length >= 4 ? s.split(h).join("****") : s), actx.redact(t));
+    const line = LINE_CREDENTIAL.get(actx);
+    refuseCredentials(cfg, actx.env, line);
+    const cred = credentialFor(actx, cfg.auth, DEPS.get(actx) ?? DEFAULT_AUTH_DEPS, redact, line);
+    hidden = () => [cred.token, ...cred.masks()];
+    const contentType = req.contentType ?? cfg.mediaType;
+    return clientFor({ ...actx, redact }, opts.adapter ?? ADAPTER, {
+        baseUrl,
+        token: cred.token,
+        authHeader: cred.authHeader,
+        ...(cred.signer ? { signer: cred.signer } : {}),
+        headers: { ...cfg.headers, ...(req.headers ?? {}) },
+        encoding: req.encoding ?? cfg.encoding,
+        ...(contentType ? { contentType } : {}),
+        ...(cfg.mediaType ? { accept: cfg.mediaType } : {}),
+    });
+}
+/**
+ * A write that sets state. PUT is idempotent by method; a PATCH or POST that sets fields (or replaces a whole
+ * list) may safely be sent twice, so a dropped connection is retried like a read. `idempotent: false` is for a
+ * create without an idempotency key: sending it twice could make two objects.
+ */
+export function write(api, method, path, body, idempotent) {
+    if (method === "PUT")
+        return api.put(path, body);
+    if (method === "PATCH")
+        return api.patch(path, body, undefined, { idempotent });
+    if (method === "DELETE")
+        return api.delete(path);
+    return api.post(path, body, undefined, { idempotent });
+}
+/** A provider error whose status is one of `statuses`, or of `code`. */
+export function failedWith(e, code, statuses) {
+    if (isProviderError(e, code))
+        return true;
+    return isProviderError(e) && e.details.status !== undefined && statuses.includes(e.details.status);
+}
+/** An output value: literals as they are, anything structured as canonical JSON, absent as undefined. */
+export function literalOf(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        return v;
+    return canonicalJson(v);
+}
+/** A provider id at `idPath` in `item`: a non-empty string or a number. */
+export function idOf(item, idPath) {
+    const v = at(item, pointerTokens(idPath));
+    if ((typeof v === "string" && v !== "") || typeof v === "number")
+        return String(v);
+    return undefined;
+}
+/** The object at `itemPath` in a response body, when it is one. */
+export function itemOf(body, itemPath) {
+    const v = at(body, pointerTokens(itemPath));
+    return isObject(v) ? v : undefined;
+}
+//# sourceMappingURL=http-adapter-client.js.map

package/dist/http-adapter-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-adapter-client.js","sourceRoot":"","sources":["../src/http-adapter-client.ts"],"names":[],"mappings":"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"}

package/dist/http-adapter-graphql.d.ts

@@ -0,0 +1,39 @@
+import { type ApiClient, type ProviderErrorCode } from "./http.js";
+/** One GraphQL request of a line: the document, its variables (values may be references), and where the result is. */
+export interface GraphqlSpec {
+    query: string;
+    variables: Record<string, unknown>;
+    /** JSON pointer into `data` to the result (the object, the list); absent: the op's `item_path` / `find.list_path`. */
+    dataPath?: string;
+    /** The mutation sets state (an upsert), so a dropped connection may be retried. */
+    idempotent: boolean;
+}
+/** The placeholder a variable may hold to receive the object's id: a string leaf that is exactly this. */
+export declare const ID_VARIABLE = "{id}";
+export declare function parseGraphql(v: unknown, param: string, idAllowed: boolean): GraphqlSpec;
+/**
+ * The first top-level field the operation selects (`variables` in `query($p: String!) { variables(projectId: $p) }`,
+ * after any alias): it names the request in keys and labels. Undefined when the document has none.
+ */
+export declare function rootField(query: string): string | undefined;
+/** True when some string leaf of `v` is exactly `{id}`. */
+export declare function usesId(v: unknown): boolean;
+/** `v` with every `{id}` leaf replaced by `id`. */
+export declare function fillVariables(v: unknown, id: string | undefined): unknown;
+/** True when a variable is still a pending reference or an unresolved secret (the request cannot be made yet). */
+export declare function variablesPending(v: unknown): boolean;
+/**
+ * How a locating request (`read`, `find`) is named in resource keys: `graphql:variables({"environmentId":"…"})`.
+ * Never the query text, so rewording a query does not re-identify the resource.
+ */
+export declare function requestName(g: GraphqlSpec): string;
+/**
+ * The PROVIDER_* code of a GraphQL error: its message first (Railway answers a denied token with
+ * `INTERNAL_SERVER_ERROR` "Not Authorized"), then `extensions.code`, then PROVIDER_INVALID.
+ */
+export declare function classifyGraphqlError(message: string, code: string | undefined): ProviderErrorCode;
+/**
+ * Send one GraphQL request and return its `data` (null when absent). HTTP failures are classified by the client as
+ * for any request; a 2xx answer with `errors` is classified here.
+ */
+export declare function graphqlRequest(api: ApiClient, g: GraphqlSpec, id: string | undefined, redact: (t: string) => string, mutation: boolean): Promise<unknown>;

package/dist/http-adapter-graphql.js

@@ -0,0 +1,157 @@
+/**
+ * GraphQL requests for `http.resource`: any of `find`, `read`, `create`, `update` and `delete` may be
+ * `{ graphql: { query, variables?, data_path? } }` instead of a method and a path. The request is a POST of
+ * `{ query, variables }` as JSON to the API's `base_url` (the GraphQL endpoint); what it answers is `data`, and a
+ * non-empty `errors` array is a provider error classified like an HTTP status would be (not found, conflict, not
+ * authorised, …). See ADR 0017 (amendment) and docs/plan-format.md#graphql-requests.
+ */
+import { SponsonError, canonicalJson, markerKind } from "@sponson/core";
+import { paramError } from "./common.js";
+import { isObject } from "./http.js";
+const ADAPTER = "http";
+/** The placeholder a variable may hold to receive the object's id: a string leaf that is exactly this. */
+export const ID_VARIABLE = "{id}";
+const GRAPHQL_KEYS = ["query", "variables", "data_path", "idempotent"];
+/** `<param>.graphql`, checked. `{id}` may appear as a variable value only where the id is known (not in find or create). */
+function queryParam(v, param) {
+    if (typeof v !== "string" || !v.includes("{") || rootField(v) === undefined) {
+        throw paramError(ADAPTER, `\`${param}\` must be a GraphQL document with one operation, e.g. "mutation($input: X!) { thing(input: $input) }"`, param);
+    }
+    return v;
+}
+function variablesParam(v, param, idAllowed) {
+    const variables = v ?? {};
+    if (!isObject(variables))
+        throw paramError(ADAPTER, `\`${param}\` must be a map of variable name to value`, param);
+    if (!idAllowed && usesId(variables))
+        throw paramError(ADAPTER, `\`${param}\` uses "${ID_VARIABLE}", which is not known here (the id exists only once the object does)`, param);
+    return variables;
+}
+export function parseGraphql(v, param, idAllowed) {
+    if (!isObject(v))
+        throw paramError(ADAPTER, `\`${param}\` must be a map: { query, variables?, data_path? }`, param);
+    const extra = Object.keys(v).find((k) => !GRAPHQL_KEYS.includes(k));
+    if (extra)
+        throw paramError(ADAPTER, `\`${param}.${extra}\` is not known (known: ${GRAPHQL_KEYS.join(", ")})`, `${param}.${extra}`);
+    const query = queryParam(v.query, `${param}.query`);
+    const variables = variablesParam(v.variables, `${param}.variables`, idAllowed);
+    const dp = v.data_path;
+    if (dp !== undefined && (typeof dp !== "string" || (dp !== "" && !dp.startsWith("/"))))
+        throw paramError(ADAPTER, `\`${param}.data_path\` must be a JSON pointer into \`data\`, e.g. /app/secrets`, `${param}.data_path`);
+    if (v.idempotent !== undefined && typeof v.idempotent !== "boolean")
+        throw paramError(ADAPTER, `\`${param}.idempotent\` must be true or false`, `${param}.idempotent`);
+    return { query, variables, ...(typeof dp === "string" ? { dataPath: dp } : {}), idempotent: v.idempotent === true };
+}
+/**
+ * The first top-level field the operation selects (`variables` in `query($p: String!) { variables(projectId: $p) }`,
+ * after any alias): it names the request in keys and labels. Undefined when the document has none.
+ */
+export function rootField(query) {
+    const withoutComments = query.replace(/#[^\n]*/g, "");
+    const body = withoutComments.slice(withoutComments.indexOf("{") + 1);
+    const m = /^\s*([_A-Za-z][_0-9A-Za-z]*)(\s*:\s*([_A-Za-z][_0-9A-Za-z]*))?/.exec(body);
+    return m ? (m[3] ?? m[1]) : undefined;
+}
+/** True when some string leaf of `v` is exactly `{id}`. */
+export function usesId(v) {
+    if (v === ID_VARIABLE)
+        return true;
+    if (Array.isArray(v))
+        return v.some(usesId);
+    return isObject(v) && Object.values(v).some(usesId);
+}
+/** `v` with every `{id}` leaf replaced by `id`. */
+export function fillVariables(v, id) {
+    if (v === ID_VARIABLE && id !== undefined)
+        return id;
+    if (Array.isArray(v))
+        return v.map((x) => fillVariables(x, id));
+    if (isObject(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, fillVariables(x, id)]));
+    return v;
+}
+/** True when a variable is still a pending reference or an unresolved secret (the request cannot be made yet). */
+export function variablesPending(v) {
+    const kind = markerKind(v);
+    if (kind === "pending" || kind === "secret")
+        return true;
+    if (Array.isArray(v))
+        return v.some(variablesPending);
+    return isObject(v) && Object.values(v).some(variablesPending);
+}
+/**
+ * How a locating request (`read`, `find`) is named in resource keys: `graphql:variables({"environmentId":"…"})`.
+ * Never the query text, so rewording a query does not re-identify the resource.
+ */
+export function requestName(g) {
+    return `graphql:${rootField(g.query) ?? "operation"}(${canonicalJson(g.variables)})`;
+}
+const BY_CODE = {
+    UNAUTHENTICATED: "PROVIDER_AUTH",
+    UNAUTHORIZED: "PROVIDER_AUTH",
+    FORBIDDEN: "PROVIDER_AUTH",
+    NOT_FOUND: "PROVIDER_NOT_FOUND",
+    CONFLICT: "PROVIDER_CONFLICT",
+    ALREADY_EXISTS: "PROVIDER_CONFLICT",
+    RATE_LIMITED: "PROVIDER_TRANSIENT",
+    TOO_MANY_REQUESTS: "PROVIDER_TRANSIENT",
+    SERVICE_UNAVAILABLE: "PROVIDER_TRANSIENT",
+    BAD_USER_INPUT: "PROVIDER_INVALID",
+    GRAPHQL_VALIDATION_FAILED: "PROVIDER_INVALID",
+    GRAPHQL_PARSE_FAILED: "PROVIDER_INVALID",
+};
+/**
+ * The PROVIDER_* code of a GraphQL error: its message first (Railway answers a denied token with
+ * `INTERNAL_SERVER_ERROR` "Not Authorized"), then `extensions.code`, then PROVIDER_INVALID.
+ */
+export function classifyGraphqlError(message, code) {
+    if (/\b(not authori[sz]ed|unauthori[sz]ed|unauthenticated|forbidden|permission denied)\b/i.test(message))
+        return "PROVIDER_AUTH";
+    if (/\b(not found|does not exist|could not find|no such)\b/i.test(message))
+        return "PROVIDER_NOT_FOUND";
+    if (/\b(already exists|already taken|duplicate)\b/i.test(message))
+        return "PROVIDER_CONFLICT";
+    const byCode = code === undefined ? undefined : BY_CODE[code.toUpperCase()];
+    if (byCode)
+        return byCode;
+    return code?.toUpperCase() === "INTERNAL_SERVER_ERROR" ? "PROVIDER_TRANSIENT" : "PROVIDER_INVALID";
+}
+function errorOf(errors, name, redact) {
+    const first = isObject(errors[0]) ? errors[0] : {};
+    const message = typeof first.message === "string" ? first.message : JSON.stringify(first);
+    const ext = isObject(first.extensions) ? first.extensions : {};
+    const code = typeof ext.code === "string" ? ext.code : undefined;
+    const text = redact(message).replace(/\s+/g, " ").slice(0, 300);
+    const more = errors.length > 1 ? ` (and ${errors.length - 1} more)` : "";
+    return new SponsonError(classifyGraphqlError(message, code), `${ADAPTER}: GraphQL ${name} → ${code ?? "error"}: ${text}${more}`, {
+        adapter: ADAPTER,
+        method: "POST",
+        path: name,
+        ...(code ? { graphqlCode: code } : {}),
+    });
+}
+/**
+ * Send one GraphQL request and return its `data` (null when absent). HTTP failures are classified by the client as
+ * for any request; a 2xx answer with `errors` is classified here.
+ */
+export async function graphqlRequest(api, g, id, redact, mutation) {
+    const body = { query: g.query, variables: fillVariables(g.variables, id) };
+    // Named by its root field only: a mutation's variables may hold the very secret it writes.
+    const name = rootField(g.query) ?? "operation";
+    let answer;
+    try {
+        answer = await api.post("", body, undefined, { idempotent: !mutation || g.idempotent });
+    }
+    catch (e) {
+        // The client names the request `POST <path>`, and a GraphQL request's path is empty: name the operation instead.
+        if (e instanceof SponsonError)
+            throw new SponsonError(e.code, e.message.replace(/^http: POST {2}→/, `${ADAPTER}: GraphQL ${name} →`), { ...e.details, path: name });
+        throw e;
+    }
+    if (!isObject(answer))
+        throw new SponsonError("PROVIDER_RESPONSE", `${ADAPTER}: GraphQL ${name}: the answer is not a JSON object`, { adapter: ADAPTER, method: "POST", path: name });
+    if (Array.isArray(answer.errors) && answer.errors.length > 0)
+        throw errorOf(answer.errors, name, redact);
+    return answer.data ?? null;
+}
+//# sourceMappingURL=http-adapter-graphql.js.map

package/dist/http-adapter-graphql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-adapter-graphql.js","sourceRoot":"","sources":["../src/http-adapter-graphql.ts"],"names":[],"mappings":"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"}

package/dist/http-adapter-list.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `http.list_item`: one value kept in a collection held by a parent object (an allowed origin, a callback URL, a
+ * config var), by read-modify-write. The collection is a JSON array, a delimited string or a keyed map (`shape`).
+ * See ADR 0017 and docs/plan-format.md#httplist_item.
+ *
+ * - Key: `<parent.path>#<list_path>=<item>`: which collection, and which item in it (for map items of an array,
+ *   the value of `key_field`; for a keyed map, the entry's name). The provider block is part of the ledger
+ *   identity already.
+ * - Id: the item's locator as canonical JSON (how to read and write the parent, where and how the collection is
+ *   stored, which item), so `destroy` needs nothing but the ledger.
+ * - Hash: the item's state in canonical JSON: the value itself, the declared fields of a map item, or a keyed
+ *   entry's value.
+ * - Writes replace the whole collection (`PUT`, or `PATCH`/`POST` sent as idempotent, so a dropped connection is
+ *   retried), except a keyed map with `send: field`, which is sent as a merge patch of the one entry (`null`
+ *   deletes it). Then the parent is read again: the write counts only once the item is seen as planned. A
+ *   collection that loses the item to a concurrent writer is written again, up to MAX_ATTEMPTS times.
+ * - Lock: the parent object (`lockOn`, ADR 0019), so Sponson's writers in other scopes and environments never
+ *   interleave between a read and a write. There is no precondition (ETag): only a writer outside Sponson can.
+ */
+import { type OpSpec } from "@sponson/core";
+import { type ListItemSpec } from "./http-adapter-spec.js";
+/** Read-modify-write rounds before giving up on a collection that keeps changing under us. */
+export declare const MAX_ATTEMPTS = 3;
+/**
+ * What the ledger knows a line's item by: its key and record id (the locator), or undefined while pending. The
+ * recipe identity lock (recipes.test.ts) pins it per recipe op.
+ */
+export declare function listItemIdentity(spec: ListItemSpec): {
+    key: string;
+    id: string;
+} | undefined;
+/** `http.list_item`: one value kept in a collection on a parent object, by read-modify-write. */
+export declare const listItem: OpSpec;