@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/dist/services/managed-processes.js

@@ -34,7 +34,22 @@ export function managedProcessRuntimeHome(record, authority) {
         return authority.ddFlowHome;
     return null;
 }
-export function registerManagedProcess(context, input) {
+export function prepareManagedProcessRegistration(context, input) {
+    requireProcessText(input.kind, "kind");
+    requireProcessText(input.ownerId, "owner");
+    for (const field of ["id", "projectId", "runId", "workId", "checkId", "operationId", "stdoutPath", "stderrPath"]) {
+        if (input[field] !== undefined && input[field] !== null)
+            requireProcessText(input[field], field);
+    }
+    for (const field of ["pid", "ownerPid", "processGroupId"]) {
+        if (input[field] !== undefined)
+            requireProcessPid(input[field], field);
+    }
+    if (input.uniqueActiveOperation !== undefined && typeof input.uniqueActiveOperation !== "boolean")
+        throw new AppError("validation", "uniqueActiveOperation must be boolean", 2);
+    if (input.metadata !== undefined && (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata)))
+        throw new AppError("validation", "metadata must be a JSON object", 2);
+    prepareManagedProcessLease(context, input.leaseMs);
     const observer = input.kind === "eval-observer";
     const observerBirth = observer && input.pid ? processStartedAt(input.pid) : null;
     if (observer) {
@@ -42,17 +57,41 @@ export function registerManagedProcess(context, input) {
             throw new AppError("process_ownership_unknown", "EVAL observer registration requires its live self-owned process identity", 1);
         input = { ...input, ownerPid: input.pid, uniqueActiveOperation: true };
     }
+    if (input.uniqueActiveOperation && !input.operationId)
+        throw new AppError("validation", "Unique managed operation requires operationId", 2);
+    let metadataJson;
+    try {
+        metadataJson = JSON.stringify({ ...input.metadata, dd_flow_home: context.ddFlowHome, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) });
+    }
+    catch {
+        throw new AppError("validation", "metadata must be JSON-serializable", 2);
+    }
+    const reader = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        if (input.id && reader.get("SELECT 1 FROM managed_processes WHERE id = ?", [input.id]))
+            throw new AppError("validation", "Managed process ID already exists; use its retained registration", 2, { process_id: input.id });
+        if (input.uniqueActiveOperation) {
+            const existing = reader.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
+            if (existing)
+                throw new AppError("managed_operation_in_progress", "The operation already owns a managed process; observe it instead of spawning a duplicate", 1, { process_id: existing.id, operation_id: input.operationId });
+        }
+    }
+    finally {
+        reader.close?.();
+    }
+    return { input, observer, observerBirth, metadataJson };
+}
+export function registerManagedProcess(context, rawInput) {
+    const { input, observer, observerBirth, metadataJson } = prepareManagedProcessRegistration(context, rawInput);
     if (!input.uniqueActiveOperation)
-        return insertManagedProcess(context, input);
-    if (!input.operationId)
-        throw new Error("Unique managed operation requires operationId");
+        return insertManagedProcess(context, input, metadataJson);
     const db = registry(context);
     db.beginWriteTransaction();
     try {
         const existing = db.get("SELECT * FROM managed_processes WHERE operation_id = ? AND state IN ('starting','running','stopping','orphaned')", [input.operationId]);
         if (existing)
             throw new AppError("managed_operation_in_progress", "The operation already owns a managed process; observe it instead of spawning a duplicate", 1, { process_id: existing.id, operation_id: input.operationId });
-        let result = insertManagedProcess(context, input);
+        let result = insertManagedProcess(context, input, metadataJson);
         if (observer) {
             result = confirmManagedProcess(context, { id: result.id, leaseToken: result.lease_token, pid: input.pid, ...(input.processGroupId ? { processGroupId: input.processGroupId } : {}) });
             if (result.pid_started_at !== observerBirth || !processIsAlive(result))
@@ -66,20 +105,36 @@ export function registerManagedProcess(context, input) {
         throw error;
     }
 }
-function insertManagedProcess(context, input) {
+function insertManagedProcess(context, input, metadataJson) {
     const db = registry(context);
     const now = context.now();
     const id = input.id ?? `PROC-${crypto.randomUUID()}`;
     const token = crypto.randomUUID();
     db.run(`INSERT INTO managed_processes
       (id, kind, pid, pid_started_at, owner_id, lease_token, lease_expires_at, project_id, run_id, work_id, check_id, operation_id, stdout_path, stderr_path, state, started_at, updated_at, finished_at, termination_reason, metadata_json)
-     VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, NULL, NULL, ?)`, [id, input.kind, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.projectId ?? null, input.runId ?? null, input.workId ?? null, input.checkId ?? null, input.operationId ?? null, input.stdoutPath ?? null, input.stderrPath ?? null, now, now, JSON.stringify({ ...input.metadata, dd_flow_home: context.ddFlowHome, ...(input.ownerPid ? { owner_pid: input.ownerPid, owner_pid_started_at: processStartedAt(input.ownerPid) } : {}) })]);
+     VALUES (?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, NULL, NULL, ?)`, [id, input.kind, input.ownerId, token, leaseExpiry(now, input.leaseMs), input.projectId ?? null, input.runId ?? null, input.workId ?? null, input.checkId ?? null, input.operationId ?? null, input.stdoutPath ?? null, input.stderrPath ?? null, now, now, metadataJson]);
     return requireProcess(db, id);
 }
+export function prepareManagedProcessConfirmation(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    requireProcessPid(input.pid, "pid");
+    if (input.ownerPid !== undefined)
+        requireProcessPid(input.ownerPid, "owner-pid");
+    if (input.processGroupId !== undefined && input.processGroupId !== null)
+        requireProcessPid(input.processGroupId, "process-group-id");
+    prepareManagedProcessLease(context, input.leaseMs);
+    const current = readManagedProcess(context, input.id);
+    if (current.lease_token !== input.leaseToken)
+        throw new AppError("process_lease_lost", "Managed process lease does not match", 1);
+    if (current.state !== "starting")
+        throw new AppError("process_confirmation_rejected", "Only a starting managed process can be confirmed", 1, { process_id: current.id, state: current.state });
+    return current;
+}
 export function confirmManagedProcess(context, input) {
+    const current = prepareManagedProcessConfirmation(context, input);
     const db = registry(context);
     const now = context.now();
-    const current = requireProcess(db, input.id);
     const metadata = parseMetadata(current.metadata_json);
     if (input.processGroupId)
         metadata.process_group_id = input.processGroupId;
@@ -94,15 +149,40 @@ export function confirmManagedProcess(context, input) {
         throw new Error(`Managed process cannot be confirmed: ${input.id}`);
     return requireProcess(db, input.id);
 }
+export function prepareManagedProcessHeartbeat(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    prepareManagedProcessLease(context, input.leaseMs);
+}
 export function heartbeatManagedProcess(context, input) {
+    prepareManagedProcessHeartbeat(context, input);
+    const reader = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        if (!reader.get("SELECT 1 FROM managed_processes WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping')", [input.id, input.leaseToken]))
+            return false;
+    }
+    finally {
+        reader.close?.();
+    }
     const db = registry(context);
     return db.run("UPDATE managed_processes SET lease_expires_at = ?, updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping')", [leaseExpiry(context.now(), input.leaseMs), context.now(), input.id, input.leaseToken]).changes === 1;
 }
+export function prepareManagedProcessFinish(context, input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    if (input.state !== "stopped" && input.state !== "failed")
+        throw new AppError("validation", "--state must be stopped or failed", 2);
+    if (input.reason !== undefined && input.reason !== null && typeof input.reason !== "string")
+        throw new AppError("validation", "reason must be a string or null", 2);
+    return readManagedProcess(context, input.id);
+}
 export function finishManagedProcess(context, input) {
-    const db = registry(context);
-    const existing = requireProcess(db, input.id);
+    const existing = prepareManagedProcessFinish(context, input);
     if (existing.lease_token === input.leaseToken && existing.state === input.state)
         return true;
+    if (existing.lease_token !== input.leaseToken || !["starting", "running", "stopping", "orphaned"].includes(existing.state))
+        return false;
+    const db = registry(context);
     const now = context.now();
     const updated = db.run("UPDATE managed_processes SET state = ?, termination_reason = ?, finished_at = ?, updated_at = ?, lease_expires_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','stopping','orphaned')", [input.state, input.reason ?? null, now, now, now, input.id, input.leaseToken]).changes === 1;
     if (updated)
@@ -183,20 +263,47 @@ export function managedLeaseReleased(record) {
         && ["stopped", "failed"].includes(record.state) && Boolean(record.finished_at);
 }
 export function managedProcessStatus(context) {
-    return registry(context).all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
+    const db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        return db.all("SELECT * FROM managed_processes ORDER BY updated_at DESC, id");
+    }
+    finally {
+        db.close?.();
+    }
+}
+export function prepareManagedProcessStopOperation(context, input) {
+    const graceMs = prepareManagedProcessStop(input);
+    const record = readManagedProcess(context, input.id);
+    assertStopOwnership(record, input.leaseToken);
+    return { record, graceMs };
+}
+function readManagedProcess(context, id) {
+    const db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        return requireProcess(db, id);
+    }
+    finally {
+        db.close?.();
+    }
+}
+function assertStopOwnership(record, leaseToken) {
+    if (record.lease_token !== leaseToken)
+        throw new AppError("process_lease_lost", "Managed process lease does not match", 1);
+    if (["stopped", "failed"].includes(record.state) && !processTreeIsAlive(record))
+        return;
+    if (!record.pid || !record.pid_started_at)
+        throw new AppError("process_identity_unknown", "Managed process has no confirmed physical identity; retain its pending launch", 1);
 }
 export async function stopManagedProcess(context, input) {
+    const { graceMs } = prepareManagedProcessStopOperation(context, input);
     const db = registry(context), record = requireProcess(db, input.id);
-    if (record.lease_token !== input.leaseToken)
-        throw new Error("Managed process lease does not match");
+    assertStopOwnership(record, input.leaseToken);
     if (["stopped", "failed"].includes(record.state) && !processTreeIsAlive(record))
         return record;
-    if (!record.pid || !record.pid_started_at)
-        throw Object.assign(new Error("Managed process has no confirmed physical identity; retain its pending launch"), { code: "process_identity_unknown" });
     db.run("UPDATE managed_processes SET state = 'stopping', updated_at = ? WHERE id = ? AND lease_token = ? AND state IN ('starting','running','orphaned')", [context.now(), record.id, record.lease_token]);
     if (processTreeIsAlive(record)) {
         terminateOwnedProcess(record, "SIGTERM");
-        await delay(input.graceMs ?? 1_000);
+        await delay(graceMs);
         if (input.force !== false && processTreeIsAlive(record)) {
             terminateOwnedProcess(record, "SIGKILL");
             await delay(250);
@@ -210,6 +317,7 @@ export async function stopManagedProcess(context, input) {
 }
 /** Reconcile only records the system owns and has atomically claimed. */
 export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs = 1_000) {
+    prepareManagedProcessReconcile(ownerId, graceMs);
     const claimed = claimExpiredManagedProcesses(context, ownerId);
     const outcomes = [];
     for (const processRecord of claimed) {
@@ -230,7 +338,34 @@ export async function reconcileExpiredManagedProcesses(context, ownerId, graceMs
     }
     return outcomes;
 }
+export function prepareManagedProcessStop(input) {
+    requireProcessText(input.id, "id");
+    requireProcessText(input.leaseToken, "lease-token");
+    if (input.reason !== undefined)
+        requireProcessText(input.reason, "reason");
+    if (input.force !== undefined && typeof input.force !== "boolean")
+        throw new AppError("validation", "force must be boolean", 2);
+    return prepareProcessGrace(input.graceMs);
+}
+export function prepareManagedProcessReconcile(ownerId, graceMs) {
+    requireProcessText(ownerId, "owner");
+    return prepareProcessGrace(graceMs);
+}
+function requireProcessText(value, parameter) {
+    if (typeof value !== "string" || !value.trim())
+        throw new AppError("validation", `--${parameter} must be nonempty text`, 2);
+}
+function requireProcessPid(value, parameter) {
+    if (!Number.isSafeInteger(value) || Number(value) <= 0)
+        throw new AppError("validation", `--${parameter} must be a positive integer`, 2);
+}
+function prepareProcessGrace(value = 1_000) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 2 ** 31 - 1)
+        throw new AppError("validation", "--grace-ms must be a nonnegative integer within the supported timer range", 2);
+    return value;
+}
 export async function reservePorts(context, input) {
+    prepareManagedProcessLease(context, input.leaseMs);
     const db = registry(context);
     const claims = [];
     const ports = {};
@@ -258,8 +393,13 @@ export async function reservePorts(context, input) {
 }
 function registry(context) { return getResourceDatabase(resourceHome(context)); }
 function requireProcess(db, id) { const row = db.get("SELECT * FROM managed_processes WHERE id = ?", [id]); if (!row)
-    throw new Error(`Managed process is missing: ${id}`); return row; }
-function leaseExpiry(now, leaseMs = defaultLeaseMs) { return new Date(Date.parse(now) + leaseMs).toISOString(); }
+    throw new AppError("not_found", `Managed process is missing: ${id}`, 1); return row; }
+export function prepareManagedProcessLease(context, leaseMs) { return leaseExpiry(context.now(), leaseMs); }
+function leaseExpiry(now, leaseMs = defaultLeaseMs) {
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || !Number.isFinite(new Date(Date.parse(now) + leaseMs).getTime()))
+        throw new AppError("validation", "--lease-ms must be a positive integer within the supported date range", 2);
+    return new Date(Date.parse(now) + leaseMs).toISOString();
+}
 export function processStartedAt(pid) { const result = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" }); const value = result.status === 0 ? result.stdout.trim() : ""; return value || null; }
 function releasePortClaims(db, claims) { for (const claim of claims)
     db.run("DELETE FROM managed_resources WHERE resource_kind = 'port' AND resource_key = ? AND lease_token = ?", [claim.key, claim.token]); }