Files
0pt/src/clients/n0d-client.ts
T
admin 2d34cb1629
CI (SIAX Cloud) / security (pull_request) Successful in 16s
CI (SIAX Cloud) / security (push) Successful in 16s
Security Scan (SIAX Cloud) / security (push) Successful in 17s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 23s
CI (SIAX Cloud) / integration (push) Failing after 27s
CI (SIAX Cloud) / integration (pull_request) Failing after 31s
CI (SIAX Cloud) / quality (pull_request) Successful in 42s
CI (SIAX Cloud) / quality (push) Successful in 42s
feat(P-001, P-002): 0pt→N0D quality delegation + internal OpenAPI
2026-09-08 22:38:47 +02:00

356 lines
14 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* src/clients/n0d-client.ts
* ==========================
* 0pt's ONLY path for REQUESTING heavy compute jobs from N0D (the Compute
* OS). 0pt requests jobs and holds the returned `job_id`; it never executes
* heavy work in-process and never owns N0D's scheduling decisions.
*
* REWRITTEN 2026-08-31 against N0D's REAL wire contract (sax3l/n0d branch
* feat/siax-platforms-p0-compute-os, `src/api/schemas.ts` createJobSchema +
* `src/api/mappers.ts` jobRecordToWire + `src/api/routes/job-lifecycle.ts`,
* verified this session):
*
* createJob -> POST {baseUrl}/v1/n0d/jobs (202 Accepted)
* runDataQuality -> POST {baseUrl}/v1/n0d/quality/run (202 Accepted)
* getJob -> GET {baseUrl}/v1/n0d/jobs/:jobId
* getJobResult -> GET {baseUrl}/v1/n0d/jobs/:jobId/result
*
* Real-contract facts encoded here:
* - required create fields: job_type, capability_id, tenant_id,
* required_role (enum), resource_requirements {cpu, memory_gb, disk_gb};
* - idempotency is BODY-ONLY (`idempotency_key`; there is no
* Idempotency-Key header on N0D) — same-tenant replay returns the
* existing record, foreign-tenant probe is a 404 (no existence oracle);
* - completion can be pushed as CloudEvents to `callback_url`
* (io.siax.n0d.job.*.v1) or polled via getJob/getJobResult;
* - the legacy fields this client used to send (`requested_by_app_id`,
* `required_node_roles[]`, `resource_profile`, `output_artifact_type`,
* `risk_level`) are NOT part of N0D's create schema. They remain
* accepted on the 0pt-side input for call-site stability and are MAPPED
* (documented per field below); tests/contracts/n0d-client.contract.test.ts
* pins the wire shape.
*
* Production fallback policy (Master-DoD §3/§10): no base URL in a
* production runtime throws `SiaxError("DEPENDENCY_UNAVAILABLE")` at
* construction. The in-memory mock (ids prefixed "mock_job_") survives only
* for non-production runtimes; it never runs anything.
*/
import crypto from "crypto";
import { SiaxHttp } from "./http";
import { resolveDependencyBaseUrl } from "../platform/dependency-mode";
import type { SiaxRequestContext } from "../platform/siax-context";
/** N0D node roles (verbatim from n0d's createJobSchema). */
export type N0dRequiredRole =
| "control_plane"
| "ai_gpu"
| "compute_general"
| "storage"
| "shared_utility";
/** N0D resource requirements (verbatim from n0d's createJobSchema). */
export interface N0dResourceRequirements {
cpu: number;
memory_gb: number;
gpu?: number;
vram_gb?: number;
disk_gb: number;
}
/**
* Named resource profiles 0pt uses when a call site does not spell out raw
* requirements. The mapping is 0pt-owned (N0D takes only raw numbers).
*/
export const N0D_RESOURCE_PROFILES: Readonly<Record<string, N0dResourceRequirements>> = {
small: { cpu: 1, memory_gb: 2, gpu: 0, disk_gb: 5 },
standard: { cpu: 2, memory_gb: 4, gpu: 0, disk_gb: 10 },
large: { cpu: 8, memory_gb: 16, gpu: 0, disk_gb: 50 },
gpu_standard: { cpu: 4, memory_gb: 16, gpu: 1, vram_gb: 16, disk_gb: 50 },
};
export interface N0dCreateJobInput {
tenant_id: string;
project_id: string;
job_type: string;
capability_id: string;
/** Mapped to wire `app_id`. */
requested_by_app_id: string;
/** Mapped to wire `requested_by`. */
requested_by_actor_id: string;
input_artifact_ids?: string[];
/** NOT on N0D's wire contract; folded into input artifact ids by callers that need it. */
input_dataset_ids?: string[];
/** Mapped to wire `output_policy.artifact_type` (+ write_to_st0re: true). */
output_artifact_type: string;
/** Mapped to wire `requires_shared_backbone`. */
requires_backbone: boolean;
/** Drives the required_role default (ai_gpu when true) + resource profile default. */
requires_gpu: boolean;
/** Legacy multi-role list; first entry that matches N0D's enum wins as `required_role`. */
required_node_roles: string[];
/** Named profile resolved via {@link N0D_RESOURCE_PROFILES} unless resource_requirements given. */
resource_profile: string;
/** Risk level L0–L5. NOT on N0D's create schema (documented inert there); kept for 0pt audit emission. */
risk_level: string;
correlation_id?: string;
/** Explicit raw requirements (wins over resource_profile). */
resource_requirements?: N0dResourceRequirements;
/** Explicit role (wins over required_node_roles/requires_gpu inference). */
required_role?: N0dRequiredRole;
priority?: "low" | "normal" | "high";
timeout_seconds?: number;
max_retries?: number;
/** Body-only idempotency key (tenant-scoped on N0D's side). */
idempotency_key?: string;
/** CloudEvents completion callback URL (must be on N0D's callback allowlist). */
callback_url?: string;
}
/** Alias so both historical import names resolve to the same shape. */
export type CreateJobInput = N0dCreateJobInput;
/** N0D's real 13-state job lifecycle (verbatim; no `succeeded` state exists). */
export type N0dJobStatus =
| "created"
| "validated"
| "queued"
| "scheduled"
| "running"
| "retrying"
| "waiting_for_capacity"
| "waiting_for_approval"
| "completed"
| "completed_with_warnings"
| "failed"
| "cancelled"
| "expired";
/** Alias kept for the older name used elsewhere in this repo's history. */
export type N0dJobState = N0dJobStatus;
/** The wire job record (n0d jobRecordToWire; tolerant-reader subset). */
export interface N0dJob {
job_id: string;
job_type: string;
tenant_id: string;
project_id?: string;
status: N0dJobStatus;
capability_id?: string;
app_id?: string;
requested_by?: string;
resource_requirements?: N0dResourceRequirements;
assigned_node_id?: string | null;
placement_reason?: string | null;
created_at: string;
updated_at?: string;
error?: string | null;
}
/** GET /v1/n0d/jobs/:id/result (n0d job-lifecycle.ts). */
export interface N0dJobResult {
job_id: string;
run_id?: string;
outcome?: "succeeded" | "failed" | "cancelled" | "expired";
exit_code?: number | null;
result?: unknown;
error?: string | null;
metrics?: Record<string, number>;
completed_at?: string;
input_artifacts?: { st0re_artifact_id: string; artifact_type?: string }[];
output_artifacts?: { st0re_artifact_id: string; artifact_type?: string }[];
}
/** Quality rule-set body for the N0D data-quality delegation (n0dRunDataQuality). */
export interface RunDataQualityInput {
tenant_id: string;
dataset_id: string;
quality_rule_set_id: string;
project_id?: string;
app_id?: string;
requested_by?: string;
run_inline?: {
dataset_csv: string;
rules: Record<string, unknown>[];
};
priority?: "low" | "normal" | "high";
risk_level?: string;
idempotency_key?: string;
timeout_seconds?: number;
max_retries?: number;
callback_url?: string;
}
export interface N0dClient {
createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise<N0dJob>;
runDataQuality(input: RunDataQualityInput, context?: SiaxRequestContext): Promise<N0dJob>;
getJob(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJob>;
getJobResult(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJobResult>;
}
export function createN0dClient(baseUrl?: string, opts?: { token?: string }): N0dClient {
const resolved = resolveDependencyBaseUrl("n0d", baseUrl ?? process.env.N0D_URL);
if (!resolved) return new MockN0dClient();
return new HttpN0dClient(resolved, opts?.token ?? process.env.N0D_SERVICE_TOKEN);
}
const N0D_ROLE_VALUES: ReadonlySet<string> = new Set([
"control_plane",
"ai_gpu",
"compute_general",
"storage",
"shared_utility",
]);
/** Resolve the wire `required_role` from the richer 0pt-side input. */
export function resolveRequiredRole(input: N0dCreateJobInput): N0dRequiredRole {
if (input.required_role) return input.required_role;
const legacy = input.required_node_roles.find((r) => N0D_ROLE_VALUES.has(r));
if (legacy) return legacy as N0dRequiredRole;
return input.requires_gpu ? "ai_gpu" : "compute_general";
}
/** Resolve the wire `resource_requirements` from the richer 0pt-side input. */
export function resolveResourceRequirements(input: N0dCreateJobInput): N0dResourceRequirements {
if (input.resource_requirements) return input.resource_requirements;
const profile = N0D_RESOURCE_PROFILES[input.resource_profile];
if (profile) return input.requires_gpu && !profile.gpu ? N0D_RESOURCE_PROFILES.gpu_standard : profile;
return input.requires_gpu ? N0D_RESOURCE_PROFILES.gpu_standard : N0D_RESOURCE_PROFILES.standard;
}
/** Non-production runtimes only: deterministic mock job; runs nothing. */
class MockN0dClient implements N0dClient {
private readonly jobs = new Map<string, N0dJob>();
async createJob(input: N0dCreateJobInput): Promise<N0dJob> {
const job: N0dJob = {
job_id: `mock_job_${crypto.randomUUID()}`,
job_type: input.job_type,
tenant_id: input.tenant_id,
project_id: input.project_id,
capability_id: input.capability_id,
app_id: input.requested_by_app_id,
requested_by: input.requested_by_actor_id,
resource_requirements: resolveResourceRequirements(input),
status: "queued",
created_at: new Date().toISOString(),
};
this.jobs.set(job.job_id, job);
return job;
}
async getJob(jobId: string, tenantId: string): Promise<N0dJob> {
const job = this.jobs.get(jobId);
if (!job || job.tenant_id !== tenantId) {
throw new Error(`mock N0D: job ${jobId} not found`);
}
return job;
}
async getJobResult(jobId: string, tenantId: string): Promise<N0dJobResult> {
await this.getJob(jobId, tenantId);
throw new Error(`mock N0D: job ${jobId} has no result (mock jobs never run)`);
}
async runDataQuality(input: RunDataQualityInput): Promise<N0dJob> {
const job: N0dJob = {
job_id: `mock_job_${crypto.randomUUID()}`,
job_type: "0pt.data_quality_job",
tenant_id: input.tenant_id,
project_id: input.project_id,
capability_id: "0pt.quality.run.v1",
app_id: input.app_id ?? input.requested_by ?? "0pt",
requested_by: input.requested_by ?? "svc_0pt",
resource_requirements: { cpu: 2, memory_gb: 4, gpu: 0, disk_gb: 10 },
status: "queued",
created_at: new Date().toISOString(),
};
this.jobs.set(job.job_id, job);
return job;
}
}
class HttpN0dClient implements N0dClient {
private readonly http: SiaxHttp;
constructor(baseUrl: string, token?: string) {
this.http = new SiaxHttp({ dependency: "n0d", baseUrl, token });
}
async createJob(input: N0dCreateJobInput, context?: SiaxRequestContext): Promise<N0dJob> {
const res = await this.http.request({
method: "POST",
path: "/v1/n0d/jobs",
context,
headers: { "X-Tenant-Id": input.tenant_id },
body: {
job_type: input.job_type,
capability_id: input.capability_id,
tenant_id: input.tenant_id,
project_id: input.project_id,
app_id: input.requested_by_app_id,
requested_by: input.requested_by_actor_id,
required_role: resolveRequiredRole(input),
resource_requirements: resolveResourceRequirements(input),
priority: input.priority ?? "normal",
requires_shared_backbone: input.requires_backbone,
...(input.input_artifact_ids?.length ? { input: { artifact_ids: input.input_artifact_ids } } : {}),
output_policy: { write_to_st0re: true, artifact_type: input.output_artifact_type },
...(input.timeout_seconds ? { timeout_seconds: input.timeout_seconds } : {}),
...(input.max_retries !== undefined ? { max_retries: input.max_retries } : {}),
...(input.idempotency_key ? { idempotency_key: input.idempotency_key } : {}),
...(input.callback_url ? { callback_url: input.callback_url } : {}),
...(input.correlation_id ? { correlation_id: input.correlation_id } : {}),
},
acceptStatuses: [202],
});
return (res.json ?? {}) as N0dJob;
}
async runDataQuality(input: RunDataQualityInput, context?: SiaxRequestContext): Promise<N0dJob> {
const res = await this.http.request({
method: "POST",
path: "/v1/n0d/quality/run",
context,
headers: { "X-Tenant-Id": input.tenant_id },
body: {
tenant_id: input.tenant_id,
project_id: input.project_id,
dataset_id: input.dataset_id,
quality_rule_set_id: input.quality_rule_set_id,
run_inline: input.run_inline,
app_id: input.app_id,
requested_by: input.requested_by,
priority: input.priority ?? "normal",
risk_level: input.risk_level ?? "L2",
requires_shared_backbone: false,
...(input.idempotency_key ? { idempotency_key: input.idempotency_key } : {}),
...(input.timeout_seconds ? { timeout_seconds: input.timeout_seconds } : {}),
...(input.max_retries !== undefined ? { max_retries: input.max_retries } : {}),
...(input.callback_url ? { callback_url: input.callback_url } : {}),
},
acceptStatuses: [202],
});
return (res.json ?? {}) as N0dJob;
}
async getJob(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJob> {
const res = await this.http.request({
method: "GET",
path: `/v1/n0d/jobs/${encodeURIComponent(jobId)}`,
context,
headers: { "X-Tenant-Id": tenantId },
});
return (res.json ?? {}) as N0dJob;
}
async getJobResult(jobId: string, tenantId: string, context?: SiaxRequestContext): Promise<N0dJobResult> {
const res = await this.http.request({
method: "GET",
path: `/v1/n0d/jobs/${encodeURIComponent(jobId)}/result`,
context,
headers: { "X-Tenant-Id": tenantId },
});
return (res.json ?? {}) as N0dJobResult;
}
}