Files
0pt/src/clients/http.ts
T
Simon AxelssonandClaude Fable 5 b7038d7675 feat(platform): canonical SIAX context/errors + real-contract clients, no prod mock fallback
- src/platform/: SiaxRequestContext + propagation headers + 12 canonical
  error codes (documented mirror of cl0ud packages/contract), SiaxError,
  resource refs (st0re:artifact:...), and the §3/§10 dependency-mode guard:
  production runtime + unconfigured dependency/store => hard
  DEPENDENCY_UNAVAILABLE at construction, never silent mock/in-memory.
- src/clients/: all four platform clients rewritten against the REAL wire
  contracts verified on sibling main branches this session:
  * cl0ud: POST /api/policy/evaluate ({data} envelope, allow+requiresApproval)
    - the old /v1/cl0ud/policies/evaluate path never existed on CL0UD
  * st0re: camelCase ArtifactInput on /v1/st0re/artifacts/register incl.
    X-Tenant-Id/X-Actor-Id + X-Idempotency-Key - the old snake_case body
    would have been a 400 against the live registry
  * n0d: required_role + resource_requirements + body idempotency_key +
    CloudEvents callback_url per n0d createJobSchema; adds getJob/getJobResult
  * aud0: /v1/aud0/openlineage is AUD0's only lineage ingest -
    /v1/aud0/lineage/events never existed; legacy shape converts to a
    spec-shaped OpenLineage RunEvent (deterministic runId dedup)
- src/lineage/: OpenLineage subset types + LineageEmitter (never-throw,
  §16 evidence semantics)
- shared SiaxHttp transport: timeouts, typed SiaxError mapping, context
  propagation, no raw upstream bodies in errors

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-31 16:35:01 +02:00

118 lines
4.6 KiB
TypeScript

/**
* src/clients/http.ts
* ====================
* Shared HTTP core for 0pt's four platform clients (cl0ud/st0re/n0d/aud0).
* One place for the behaviours Master-DoD §6/§10 require of every
* cross-product call:
*
* - request timeout (no hung platform call can wedge a capability),
* - typed `SiaxError` mapping from upstream status codes (retryable vs
* permanent explicit, correlation id carried, no raw upstream body leaked
* into the error message),
* - canonical SIAX context propagation headers (src/platform/siax-context.ts)
* plus optional service `Authorization` bearer (never the end-user token),
* - JSON body handling.
*
* Each client keeps its own wire mapping (the four dependencies genuinely
* differ: ST0RE is camelCase + X-Tenant-Id/X-Actor-Id, AUD0 is snake_case,
* CL0UD wraps in a `{ data, meta }` envelope, N0D is snake_case + 202) — this
* module owns only the transport discipline they share.
*/
import { SiaxError, siaxErrorCodeForUpstreamStatus } from "../platform/errors";
import { toPropagationHeaders, type SiaxRequestContext } from "../platform/siax-context";
export interface SiaxHttpOptions {
/** Dependency name for error attribution, e.g. "st0re". */
dependency: string;
baseUrl: string;
/** Service bearer token (machine identity). Optional — some deployments gate by network + headers. */
token?: string;
/** Per-request timeout in ms. Default 15_000. */
timeoutMs?: number;
}
export interface SiaxRequestOptions {
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
path: string;
/** Query string parameters (skipped when undefined). */
query?: Record<string, string | undefined>;
body?: unknown;
/** Canonical SIAX context — serialized to propagation headers when present. */
context?: SiaxRequestContext;
/** Extra headers (e.g. ST0RE's X-Idempotency-Key). Applied last. */
headers?: Record<string, string>;
/** Statuses the caller handles itself (returned, not thrown). */
acceptStatuses?: number[];
}
export interface SiaxHttpResponse {
status: number;
/** Parsed JSON body, or undefined when the body was empty/non-JSON. */
json: unknown;
}
export class SiaxHttp {
private readonly dependency: string;
private readonly baseUrl: string;
private readonly token?: string;
private readonly timeoutMs: number;
constructor(opts: SiaxHttpOptions) {
this.dependency = opts.dependency;
this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
this.token = opts.token;
this.timeoutMs = opts.timeoutMs ?? 15_000;
}
async request(opts: SiaxRequestOptions): Promise<SiaxHttpResponse> {
const url = new URL(`${this.baseUrl}${opts.path}`);
for (const [k, v] of Object.entries(opts.query ?? {})) {
if (v !== undefined) url.searchParams.set(k, v);
}
const headers: Record<string, string> = { "Content-Type": "application/json" };
if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
if (opts.context) Object.assign(headers, toPropagationHeaders(opts.context));
Object.assign(headers, opts.headers ?? {});
const correlationId = opts.context?.correlationId;
let res: Response;
try {
// NOTE: fetch is called with a STRING (not a URL object) so test fetch
// stubs that inspect `url.includes(...)` keep working.
res = await fetch(url.toString(), {
method: opts.method,
headers,
body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
signal: AbortSignal.timeout(this.timeoutMs),
});
} catch (cause) {
// Network failure / timeout: the dependency is unavailable — retryable.
throw new SiaxError(
"DEPENDENCY_UNAVAILABLE",
this.dependency,
`${opts.method} ${opts.path} failed to reach ${this.dependency} (${cause instanceof Error ? cause.name : "fetch error"})`,
{ correlationId, cause }
);
}
if (!res.ok && !(opts.acceptStatuses ?? []).includes(res.status)) {
// Read the upstream machine-readable code when present, but never embed
// the raw body in the error (§6: no sensitive internals).
const upstream = (await res.json().catch(() => undefined)) as
| { error?: { code?: string; message?: string } }
| undefined;
const upstreamCode = upstream?.error?.code;
throw new SiaxError(
siaxErrorCodeForUpstreamStatus(res.status),
this.dependency,
`${opts.method} ${opts.path} → HTTP ${res.status}${upstreamCode ? ` (${upstreamCode})` : ""}`,
{ correlationId }
);
}
const json = (await res.json().catch(() => undefined)) as unknown;
return { status: res.status, json };
}
}