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
356 lines
14 KiB
TypeScript
356 lines
14 KiB
TypeScript
/**
|
||
* 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;
|
||
}
|
||
}
|