- 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>
118 lines
4.6 KiB
TypeScript
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 };
|
|
}
|
|
}
|