@opengeni/api-router 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { getSettings } from '@opengeni/config';
+import { ScheduledTaskOverlapPolicy, ScheduledTaskScheduleSpec } from '@opengeni/contracts';
+import { ScheduleOverlapPolicy, ScheduleSpec } from '@temporalio/client';
+import { SessionWorkflowClient, DocumentIndexClient } from '@opengeni/core';
+
+declare function createTemporalWorkflowClient(settings: ReturnType<typeof getSettings>): Promise<{
+    client: SessionWorkflowClient;
+    documentIndexer: DocumentIndexClient;
+    close: () => Promise<void>;
+}>;
+declare function startApi(): Promise<{
+    server: Bun.Server<undefined>;
+    close: () => Promise<void>;
+}>;
+declare function temporalOverlapPolicy(policy: ScheduledTaskOverlapPolicy): ScheduleOverlapPolicy;
+declare function shouldCreateScheduleAfterUpdateError(error: unknown): boolean;
+declare function temporalScheduleSpec(schedule: ScheduledTaskScheduleSpec): ScheduleSpec;
+
+export { createTemporalWorkflowClient, shouldCreateScheduleAfterUpdateError, startApi, temporalOverlapPolicy, temporalScheduleSpec };

package/dist/index.js

@@ -0,0 +1,567 @@
+import {
+  createApp
+} from "./chunk-XSYUDIX3.js";
+
+// src/index.ts
+import { dbSearchPath, getSettings, resolveNatsCalloutConfig, resolveNatsControlPlaneAuth, retryStartupDependency, startupRetryOptions } from "@opengeni/config";
+import { createDb } from "@opengeni/db";
+import { createNatsEventBus } from "@opengeni/events";
+import { createObservability, logStartupDependencyRetry } from "@opengeni/observability";
+import { Connection, Client as TemporalClient, ScheduleNotFoundError, ScheduleOverlapPolicy, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+
+// src/sandbox/auth-callout.ts
+import { resolveEnrollmentSigningSecret } from "@opengeni/config";
+import { verifyEnrollmentBearer } from "@opengeni/contracts";
+import { getEnrollment } from "@opengeni/db";
+import {
+  createResponderConnection,
+  decodeAuthRequest,
+  mintAuthResponse,
+  mintUserJwt,
+  workspaceAgentPermissions
+} from "@opengeni/events";
+var AUTH_CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH";
+async function handleAuthorizationRequest(deps, requestBytes) {
+  const requestJwt = Buffer.from(requestBytes).toString("utf8");
+  const decoded = decodeAuthRequest(requestJwt);
+  if (!decoded) {
+    deps.observability?.warn?.("auth-callout: undecodable authorization request", {});
+    throw new Error("undecodable authorization request");
+  }
+  const deny = (reason) => {
+    const response2 = mintAuthResponse({
+      userPublicKey: decoded.userNkey,
+      serverId: decoded.serverId,
+      accountSeed: deps.callout.accountSeed,
+      error: reason
+    });
+    return Buffer.from(response2, "utf8");
+  };
+  const bearer = decoded.authToken;
+  if (!bearer) {
+    return deny("missing enrollment bearer");
+  }
+  const secret = resolveEnrollmentSigningSecret(deps.settings);
+  if (!secret) {
+    return deny("enrollment credential plane disabled");
+  }
+  const claims = await verifyEnrollmentBearer(secret, bearer);
+  if (!claims) {
+    deps.observability?.warn?.("auth-callout: rejected an invalid enrollment bearer", {});
+    return deny("invalid or expired enrollment bearer");
+  }
+  const enrollment = await getEnrollment(deps.db, claims.workspaceId, claims.enrollmentId);
+  if (!enrollment || enrollment.status !== "active") {
+    deps.observability?.warn?.("auth-callout: denied a revoked or unknown enrollment", {
+      workspaceId: claims.workspaceId,
+      agentId: claims.agentId
+    });
+    return deny("enrollment is not active");
+  }
+  if (enrollment.id !== claims.enrollmentId) {
+    return deny("enrollment identity mismatch");
+  }
+  const permissions = workspaceAgentPermissions(claims.workspaceId);
+  const userJwt = mintUserJwt({
+    userPublicKey: decoded.userNkey,
+    accountSeed: deps.callout.accountSeed,
+    name: claims.agentId,
+    permissions,
+    // Server-config-mode placement: the embedded user JWT's `aud` is the account
+    // the user binds to (the configured `auth_callout.account`). All agents +
+    // the privileged control plane share this account so subjects route; the
+    // per-workspace isolation is carried by the subject permissions above.
+    audienceAccount: deps.callout.accountName,
+    // Tie the credential's life to the bearer's remaining life: a revoked/expired
+    // enrollment cannot outlive its bearer at the NATS layer either.
+    expiresAtSeconds: claims.exp
+  });
+  const response = mintAuthResponse({
+    userPublicKey: decoded.userNkey,
+    serverId: decoded.serverId,
+    accountSeed: deps.callout.accountSeed,
+    userJwt
+  });
+  deps.observability?.info?.("auth-callout: granted a workspace-scoped NATS credential", {
+    workspaceId: claims.workspaceId,
+    agentId: claims.agentId
+  });
+  return Buffer.from(response, "utf8");
+}
+async function startAuthCalloutResponder(deps, natsUrl) {
+  const connection = await createResponderConnection(
+    natsUrl,
+    { kind: "user-password", user: deps.callout.user, pass: deps.callout.password },
+    AUTH_CALLOUT_SUBJECT,
+    (bytes) => handleAuthorizationRequest(deps, bytes),
+    { name: "opengeni-auth-callout" }
+  );
+  deps.observability?.info?.("OpenGeni NATS auth-callout responder started", {
+    subject: AUTH_CALLOUT_SUBJECT
+  });
+  return connection;
+}
+
+// src/sandbox/metrics-ingestion.ts
+import {
+  getEnrollment as getEnrollment2,
+  ingestMachineMetricsSample,
+  setEnrollmentHasDisplay,
+  touchEnrollmentLastSeen
+} from "@opengeni/db";
+import { AgentEvent, Hello } from "@opengeni/agent-proto";
+var AGENT_EVENTS_SUBJECT = "agent.*.*.events";
+var AGENT_HELLO_SUBJECT = "agent.*.*.hello";
+function parseAgentSubject(subject, tail) {
+  const parts = subject.split(".");
+  if (parts.length !== 4 || parts[0] !== "agent" || parts[3] !== tail) {
+    return null;
+  }
+  return { workspaceId: parts[1], agentId: parts[2] };
+}
+function parseAgentEventSubject(subject) {
+  return parseAgentSubject(subject, "events");
+}
+function parseAgentHelloSubject(subject) {
+  return parseAgentSubject(subject, "hello");
+}
+function wireSampleToDbSample(wire) {
+  const num = (v) => typeof v === "number" ? v : Number(v);
+  const firstGpu = wire.gpus[0];
+  return {
+    cpuPercent: wire.cpuPercent,
+    load1: wire.load1,
+    load5: wire.load5,
+    load15: wire.load15,
+    memUsedBytes: num(wire.memUsedBytes),
+    memTotalBytes: num(wire.memTotalBytes),
+    diskUsedBytes: num(wire.diskUsedBytes),
+    diskTotalBytes: num(wire.diskTotalBytes),
+    gpuUtilPercent: firstGpu ? firstGpu.utilPercent : null,
+    gpuMemUsedBytes: firstGpu ? num(firstGpu.memUsedBytes) : null,
+    gpuMemTotalBytes: firstGpu ? num(firstGpu.memTotalBytes) : null,
+    contention: wire.runQueue,
+    // The sample carries its own wall-clock stamp (epoch ms); fall back to now on
+    // a missing/zero stamp so a series row is never NULL-dated.
+    sampledAt: wire.sampledAtMs && Number(wire.sampledAtMs) > 0 ? new Date(Number(wire.sampledAtMs)) : /* @__PURE__ */ new Date()
+  };
+}
+async function ingestHeartbeat(db, input) {
+  const enrollment = await getEnrollment2(db, input.workspaceId, input.agentId);
+  if (!enrollment) {
+    return { ingested: false, seriesAppended: false };
+  }
+  const sample = wireSampleToDbSample(input.sample);
+  await touchEnrollmentLastSeen(db, {
+    accountId: enrollment.accountId,
+    workspaceId: input.workspaceId,
+    enrollmentId: input.agentId
+  });
+  const result = await ingestMachineMetricsSample(db, {
+    accountId: enrollment.accountId,
+    workspaceId: input.workspaceId,
+    enrollmentId: input.agentId,
+    sample
+  });
+  return { ingested: true, seriesAppended: result.seriesAppended };
+}
+async function handleAgentEventPayload(db, observability, payload, subject) {
+  const ids = parseAgentEventSubject(subject);
+  if (!ids) {
+    return;
+  }
+  let event;
+  try {
+    event = AgentEvent.decode(payload);
+  } catch (error) {
+    observability?.warn?.("Failed to decode an agent event for metrics ingestion", {
+      subject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return;
+  }
+  if (event.event?.$case !== "heartbeat") {
+    return;
+  }
+  const metrics = event.event.heartbeat.metrics;
+  if (!metrics) {
+    return;
+  }
+  try {
+    await ingestHeartbeat(db, { workspaceId: ids.workspaceId, agentId: ids.agentId, sample: metrics });
+  } catch (error) {
+    observability?.warn?.("Failed to ingest a machine metrics heartbeat", {
+      subject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+function startMetricsIngestion(deps) {
+  return deps.bus.subscribeAgentEvents(
+    AGENT_EVENTS_SUBJECT,
+    (payload, subject) => handleAgentEventPayload(deps.db, deps.observability, payload, subject)
+  );
+}
+function helloReportsDisplay(hello) {
+  const caps = hello.capabilities;
+  if (!caps) {
+    return false;
+  }
+  return caps.desktop === true || caps.display != null;
+}
+async function refreshEnrollmentDisplay(db, input) {
+  const enrollment = await getEnrollment2(db, input.workspaceId, input.agentId);
+  if (!enrollment) {
+    return { updated: false };
+  }
+  if (enrollment.hasDisplay === input.hasDisplay) {
+    return { updated: false };
+  }
+  return await setEnrollmentHasDisplay(db, {
+    accountId: enrollment.accountId,
+    workspaceId: input.workspaceId,
+    enrollmentId: input.agentId,
+    hasDisplay: input.hasDisplay
+  });
+}
+async function handleHelloPayload(db, observability, payload, subject) {
+  const ids = parseAgentHelloSubject(subject);
+  if (!ids) {
+    return;
+  }
+  let hello;
+  try {
+    hello = Hello.decode(payload);
+  } catch (error) {
+    observability?.warn?.("Failed to decode an agent Hello for display refresh", {
+      subject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return;
+  }
+  try {
+    await refreshEnrollmentDisplay(db, {
+      workspaceId: ids.workspaceId,
+      agentId: ids.agentId,
+      hasDisplay: helloReportsDisplay(hello)
+    });
+  } catch (error) {
+    observability?.warn?.("Failed to refresh an enrollment's display from a Hello", {
+      subject,
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+function startHelloIngestion(deps) {
+  return deps.bus.subscribeAgentEvents(
+    AGENT_HELLO_SUBJECT,
+    (payload, subject) => handleHelloPayload(deps.db, deps.observability, payload, subject)
+  );
+}
+
+// src/index.ts
+function isWorkflowAlreadyStarted(error) {
+  return error instanceof WorkflowExecutionAlreadyStartedError;
+}
+var TEMPORAL_MONTHS = [
+  "JANUARY",
+  "FEBRUARY",
+  "MARCH",
+  "APRIL",
+  "MAY",
+  "JUNE",
+  "JULY",
+  "AUGUST",
+  "SEPTEMBER",
+  "OCTOBER",
+  "NOVEMBER",
+  "DECEMBER"
+];
+async function createTemporalWorkflowClient(settings) {
+  const connection = await Connection.connect({ address: settings.temporalHost });
+  const temporal = new TemporalClient({
+    connection,
+    namespace: settings.temporalNamespace
+  });
+  const client = {
+    signalUserMessage: async ({ eventId, workflowId }) => {
+      await temporal.workflow.getHandle(workflowId).signal("userMessage", eventId);
+    },
+    wakeSessionWorkflow: async ({ accountId, workspaceId, sessionId, workflowId }) => {
+      await temporal.workflow.signalWithStart("sessionWorkflow", {
+        taskQueue: settings.temporalTaskQueue,
+        workflowId,
+        workflowIdReusePolicy: "ALLOW_DUPLICATE",
+        args: [{ accountId, workspaceId, sessionId }],
+        signal: "queueChanged"
+      });
+    },
+    signalApprovalDecision: async ({ eventId, workflowId }) => {
+      await temporal.workflow.getHandle(workflowId).signal("approvalDecision", eventId);
+    },
+    signalInterrupt: async ({ accountId, workspaceId, sessionId, eventId, workflowId }) => {
+      await temporal.workflow.signalWithStart("sessionWorkflow", {
+        taskQueue: settings.temporalTaskQueue,
+        workflowId,
+        workflowIdReusePolicy: "ALLOW_DUPLICATE",
+        args: [{ accountId, workspaceId, sessionId }],
+        signal: "interrupt",
+        signalArgs: [eventId]
+      });
+    },
+    syncScheduledTask: async ({ task }) => {
+      const schedule = temporal.schedule.getHandle(task.temporalScheduleId);
+      const options = temporalScheduleOptions(task, settings.temporalTaskQueue);
+      try {
+        await schedule.update(() => temporalScheduleUpdateOptions(options));
+      } catch (error) {
+        if (!shouldCreateScheduleAfterUpdateError(error)) {
+          throw error;
+        }
+        await temporal.schedule.create(options);
+      }
+    },
+    deleteScheduledTaskSchedule: async ({ temporalScheduleId }) => {
+      await temporal.schedule.getHandle(temporalScheduleId).delete().catch(() => void 0);
+    },
+    triggerScheduledTask: async ({ task, agentRunUsageIdempotencyKey, triggerWorkflowId }) => {
+      const workflowId = triggerWorkflowId ?? `scheduled-task-${task.id}-manual-${crypto.randomUUID()}`;
+      try {
+        await temporal.workflow.start("scheduledTaskFireWorkflow", {
+          taskQueue: settings.temporalTaskQueue,
+          workflowId,
+          workflowIdReusePolicy: "REJECT_DUPLICATE",
+          args: [{
+            accountId: task.accountId,
+            workspaceId: task.workspaceId,
+            taskId: task.id,
+            triggerType: "manual",
+            agentRunUsageIdempotencyKey
+          }]
+        });
+      } catch (error) {
+        if (isWorkflowAlreadyStarted(error)) {
+          return;
+        }
+        throw error;
+      }
+    }
+  };
+  const documentIndexer = {
+    indexDocument: async ({ accountId, workspaceId, documentId }) => {
+      const workflowId = `document-index-${documentId}-${crypto.randomUUID()}`;
+      await temporal.workflow.start("documentIndexWorkflow", {
+        taskQueue: settings.temporalTaskQueue,
+        workflowId,
+        args: [{ accountId, workspaceId, documentId }]
+      });
+    }
+  };
+  return {
+    client,
+    documentIndexer,
+    close: async () => {
+      await connection.close();
+    }
+  };
+}
+async function startApi() {
+  const settings = getSettings();
+  const observability = createObservability(settings, { component: "api" });
+  const searchPath = dbSearchPath(settings);
+  const dbClient = createDb(settings.databaseUrl, {
+    ...searchPath ? { searchPath } : {},
+    rlsStrategy: settings.rlsStrategy
+  });
+  let bus;
+  let workflowClient;
+  const retryOptions = startupRetryOptions(settings);
+  const onRetry = (event) => logStartupDependencyRetry(observability, event);
+  const controlPlaneAuth = resolveNatsControlPlaneAuth(settings);
+  try {
+    bus = await retryStartupDependency(
+      "NATS",
+      () => createNatsEventBus(
+        settings.natsUrl,
+        controlPlaneAuth ? { user: controlPlaneAuth.user, pass: controlPlaneAuth.password } : void 0
+      ),
+      {
+        ...retryOptions,
+        onRetry
+      }
+    );
+    workflowClient = await retryStartupDependency("Temporal", () => createTemporalWorkflowClient(settings), {
+      ...retryOptions,
+      onRetry
+    });
+  } catch (error) {
+    await Promise.allSettled([
+      bus?.close(),
+      workflowClient?.close(),
+      dbClient.close()
+    ]);
+    throw error;
+  }
+  if (!bus || !workflowClient) {
+    await dbClient.close();
+    throw new Error("OpenGeni API startup dependencies were not initialized");
+  }
+  const app = createApp({
+    settings,
+    db: dbClient.db,
+    bus,
+    workflowClient: workflowClient.client,
+    documentIndexer: workflowClient.documentIndexer,
+    observability
+  });
+  const server = Bun.serve({
+    hostname: settings.apiHost,
+    port: settings.apiPort,
+    idleTimeout: 255,
+    fetch: app.fetch
+  });
+  let stopMetricsIngestion;
+  let stopHelloIngestion;
+  let authCalloutResponder;
+  if (settings.sandboxSelfhostedEnabled) {
+    stopMetricsIngestion = startMetricsIngestion({ db: dbClient.db, bus, observability });
+    stopHelloIngestion = startHelloIngestion({ db: dbClient.db, bus, observability });
+    observability.info("OpenGeni machine-metrics + hello ingestion consumers started", {});
+    const callout = resolveNatsCalloutConfig(settings);
+    if (callout) {
+      try {
+        authCalloutResponder = await startAuthCalloutResponder(
+          { db: dbClient.db, settings, callout, observability },
+          settings.natsUrl
+        );
+      } catch (error) {
+        observability.error("OpenGeni NATS auth-callout responder failed to start", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    } else {
+      observability.warn(
+        "OpenGeni selfhosted enabled but the NATS auth-callout plane is not configured; selfhosted agents cannot connect",
+        {}
+      );
+    }
+  }
+  observability.info("OpenGeni API listening", {
+    host: settings.apiHost,
+    port: settings.apiPort
+  });
+  return {
+    server,
+    close: async () => {
+      server.stop(true);
+      stopMetricsIngestion?.();
+      stopHelloIngestion?.();
+      await Promise.allSettled([
+        authCalloutResponder?.close(),
+        bus.close(),
+        workflowClient.close(),
+        dbClient.close()
+      ]);
+    }
+  };
+}
+if (import.meta.main) {
+  await startApi();
+}
+function temporalOverlapPolicy(policy) {
+  if (policy === "skip") {
+    return ScheduleOverlapPolicy.SKIP;
+  }
+  if (policy === "buffer_one") {
+    return ScheduleOverlapPolicy.BUFFER_ONE;
+  }
+  return ScheduleOverlapPolicy.ALLOW_ALL;
+}
+function shouldCreateScheduleAfterUpdateError(error) {
+  return error instanceof ScheduleNotFoundError;
+}
+function temporalScheduleSpec(schedule) {
+  if (schedule.type === "interval") {
+    return {
+      intervals: [{ every: `${schedule.everySeconds}s` }],
+      ...schedule.startAt ? { startAt: new Date(schedule.startAt) } : {},
+      ...schedule.endAt ? { endAt: new Date(schedule.endAt) } : {}
+    };
+  }
+  if (schedule.type === "calendar") {
+    return {
+      calendars: [{
+        hour: schedule.hour,
+        minute: schedule.minute,
+        second: 0,
+        ...schedule.daysOfWeek ? { dayOfWeek: schedule.daysOfWeek } : {}
+      }],
+      timezone: schedule.timeZone
+    };
+  }
+  const runAt = new Date(schedule.runAt);
+  return {
+    calendars: [{
+      year: runAt.getUTCFullYear(),
+      month: temporalMonth(runAt.getUTCMonth()),
+      dayOfMonth: runAt.getUTCDate(),
+      hour: runAt.getUTCHours(),
+      minute: runAt.getUTCMinutes(),
+      second: runAt.getUTCSeconds()
+    }],
+    timezone: "UTC"
+  };
+}
+function temporalMonth(monthIndex) {
+  return TEMPORAL_MONTHS[monthIndex];
+}
+function temporalScheduleOptions(task, taskQueue) {
+  return {
+    scheduleId: task.temporalScheduleId,
+    spec: temporalScheduleSpec(task.schedule),
+    action: {
+      type: "startWorkflow",
+      workflowType: "scheduledTaskFireWorkflow",
+      taskQueue,
+      args: [{
+        accountId: task.accountId,
+        workspaceId: task.workspaceId,
+        taskId: task.id,
+        triggerType: "scheduled"
+      }]
+    },
+    policies: {
+      overlap: temporalOverlapPolicy(task.overlapPolicy),
+      catchupWindow: "24h",
+      pauseOnFailure: false
+    },
+    state: {
+      paused: task.status === "paused",
+      ...task.schedule.type === "once" ? { remainingActions: 1 } : {}
+    },
+    memo: {
+      accountId: task.accountId,
+      workspaceId: task.workspaceId,
+      scheduledTaskId: task.id,
+      name: task.name
+    }
+  };
+}
+function temporalScheduleUpdateOptions(options) {
+  return {
+    spec: options.spec,
+    action: options.action,
+    ...options.policies ? { policies: options.policies } : {},
+    state: options.state ?? {},
+    ...options.searchAttributes ? { searchAttributes: options.searchAttributes } : {},
+    ...options.typedSearchAttributes ? { typedSearchAttributes: options.typedSearchAttributes } : {}
+  };
+}
+export {
+  createTemporalWorkflowClient,
+  shouldCreateScheduleAfterUpdateError,
+  startApi,
+  temporalOverlapPolicy,
+  temporalScheduleSpec
+};
+//# sourceMappingURL=index.js.map