@opengeni/api-router 0.11.2 → 0.12.0

package/src/routes/workspace-instruction-policies.ts

@@ -0,0 +1,243 @@
+import {
+  ActivateWorkspaceInstructionPolicyRequest,
+  CreateWorkspaceInstructionPolicyDraftRequest,
+  ImportLegacyWorkspaceInstructionPolicyDraftRequest,
+  RollbackWorkspaceInstructionPolicyRequest,
+  WorkspaceInstructionPolicyActivationResponse,
+  WorkspaceInstructionPolicyConflictResponse,
+  WorkspaceInstructionPolicyDiffRequest,
+  WorkspaceInstructionPolicyDiffResponse,
+  WorkspaceInstructionPolicyListQuery,
+  WorkspaceInstructionPolicyListResponse,
+  WorkspaceInstructionPolicyRevision,
+} from "@opengeni/contracts";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  activateWorkspaceInstructionPolicyRevision,
+  createWorkspaceInstructionPolicyDraft,
+  diffWorkspaceInstructionPolicyRevisions,
+  getWorkspaceInstructionPolicyRevision,
+  importLegacyWorkspaceInstructionPolicyDraft,
+  listWorkspaceInstructionPolicyRevisions,
+  rollbackWorkspaceInstructionPolicyRevision,
+  WorkspaceInstructionPolicyConflictError,
+  WorkspaceInstructionPolicyInvalidOperationError,
+  WorkspaceInstructionPolicyLegacyUnavailableError,
+  WorkspaceInstructionPolicyNotFoundError,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const WorkspaceInstructionPolicyRevisionId = z.string().uuid();
+
+async function parseBody<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "Invalid workspace instruction-policy request" });
+  }
+  return parsed.data;
+}
+
+function policyErrorResponse(context: Context, error: unknown): Response {
+  if (error instanceof WorkspaceInstructionPolicyConflictError) {
+    return context.json(
+      WorkspaceInstructionPolicyConflictResponse.parse({
+        code: error.code,
+        message: error.message,
+        currentHead: error.currentHead,
+      }),
+      409,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyNotFoundError) {
+    return context.json(
+      { code: "WORKSPACE_INSTRUCTION_POLICY_NOT_FOUND", message: error.message },
+      404,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyLegacyUnavailableError) {
+    return context.json(
+      { code: "WORKSPACE_INSTRUCTION_POLICY_LEGACY_UNAVAILABLE", message: error.message },
+      409,
+    );
+  }
+  if (error instanceof WorkspaceInstructionPolicyInvalidOperationError) {
+    return context.json(
+      { code: "INVALID_WORKSPACE_INSTRUCTION_POLICY_OPERATION", message: error.message },
+      422,
+    );
+  }
+  throw error;
+}
+
+function assertBoundedActor(subjectId: string): void {
+  if (subjectId.trim().length < 1 || subjectId.length > 1_024) {
+    throw new HTTPException(400, { message: "Workspace instruction-policy actor is invalid" });
+  }
+}
+
+function parseRevisionId(context: Context): string {
+  const parsed = WorkspaceInstructionPolicyRevisionId.safeParse(context.req.param("revisionId"));
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "Invalid workspace instruction-policy revision id" });
+  }
+  return parsed.data;
+}
+
+export function registerWorkspaceInstructionPolicyRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/instruction-policies";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const parsed = WorkspaceInstructionPolicyListQuery.safeParse({
+      kind: context.req.query("kind"),
+      scope: context.req.query("scope"),
+      roleKey: context.req.query("roleKey"),
+      afterRevision: context.req.query("afterRevision"),
+      limit: context.req.query("limit"),
+    });
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "Invalid workspace instruction-policy query" });
+    }
+    return context.json(
+      WorkspaceInstructionPolicyListResponse.parse(
+        await listWorkspaceInstructionPolicyRevisions(deps.db, workspaceId, parsed.data),
+      ),
+    );
+  });
+
+  app.post(`${base}/drafts`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    assertBoundedActor(grant.subjectId);
+    const request = await parseBody(context, CreateWorkspaceInstructionPolicyDraftRequest);
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyRevision.parse(
+          await createWorkspaceInstructionPolicyDraft(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            createdBySubjectId: grant.subjectId,
+            kind: request.kind,
+            scope: request.scope,
+            roleKey: request.roleKey,
+            content: request.content,
+            provenanceSource: request.provenanceSource,
+            provenanceSourceId: request.provenanceSourceId,
+            supersedesRevisionId: request.supersedesRevisionId,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
+  app.post(`${base}/import-legacy`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    assertBoundedActor(grant.subjectId);
+    const request = await parseBody(context, ImportLegacyWorkspaceInstructionPolicyDraftRequest);
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyRevision.parse(
+          await importLegacyWorkspaceInstructionPolicyDraft(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            createdBySubjectId: grant.subjectId,
+            supersedesRevisionId: request.supersedesRevisionId,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
+  app.get(`${base}/diff`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const parsed = WorkspaceInstructionPolicyDiffRequest.safeParse({
+      fromRevisionId: context.req.query("fromRevisionId"),
+      toRevisionId: context.req.query("toRevisionId"),
+    });
+    if (!parsed.success) {
+      throw new HTTPException(422, { message: "Invalid workspace instruction-policy diff query" });
+    }
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyDiffResponse.parse(
+          await diffWorkspaceInstructionPolicyRevisions(deps.db, workspaceId, parsed.data),
+        ),
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
+  app.post(`${base}/rollback`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    assertBoundedActor(grant.subjectId);
+    const request = await parseBody(context, RollbackWorkspaceInstructionPolicyRequest);
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyActivationResponse.parse(
+          await rollbackWorkspaceInstructionPolicyRevision(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            targetRevisionId: request.targetRevisionId,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            actorSubjectId: grant.subjectId,
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
+  app.get(`${base}/:revisionId`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const revisionId = parseRevisionId(context);
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyRevision.parse(
+          await getWorkspaceInstructionPolicyRevision(deps.db, workspaceId, revisionId),
+        ),
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+
+  app.post(`${base}/:revisionId/activate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    assertBoundedActor(grant.subjectId);
+    const revisionId = parseRevisionId(context);
+    const request = await parseBody(context, ActivateWorkspaceInstructionPolicyRequest);
+    try {
+      return context.json(
+        WorkspaceInstructionPolicyActivationResponse.parse(
+          await activateWorkspaceInstructionPolicyRevision(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            revisionId,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            actorSubjectId: grant.subjectId,
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      return policyErrorResponse(context, error);
+    }
+  });
+}

package/src/sandbox/channel-a.ts

@@ -3,16 +3,16 @@
 // The structured services (FileSystem / Git / Terminal) are SYNCHRONOUS point
 // queries served client -> API -> box IN-PROCESS. Each call:
 //
-//   1. acquires an exact direct-request lease holder (warming the box when cold — the
-//      same cold->warming CAS attachViewer runs; a Postgres txn the API OWNS),
-//   2. resumes the box BY ID from the group lease's resume_state envelope,
-//   3. builds ONE SandboxChannelAService around the live `session` handle,
-//   4. runs the op (fsList/gitDiff/ptyWrite/...), returns inline JSON,
-//   5. releases the viewer holder + drops the live handle.
+// For a provider-backed home it acquires an exact direct-request lease holder,
+// resumes the box by id, and releases the holder after the operation. For a
+// Connected Machine home it follows the durable active pointer directly and
+// uses its NATS request/reply control channel; it creates no phantom cloud lease.
+// Both paths build one SandboxChannelAService, run the operation, and return the
+// result inline.
 //
-// NO Temporal, NO worker RPC, NO NATS round-trip in this path — reads never ride
-// the bus (which would corrupt SSE gap-fill). Only the side-effect NOTIFICATIONS
-// (fs.changed/git.changed/terminal.pty.*) ride A1 via appendAndPublishEvents.
+// NO Temporal or worker RPC sits in this path. Provider-backed reads remain
+// process-local; Connected Machine operations necessarily ride NATS. Side-effect
+// notifications (fs.changed/git.changed/terminal.pty.*) ride A1.
 //
 // IMPORT DISCIPLINE: sandbox symbols come ONLY from @opengeni/runtime/sandbox
 // (the agent-loop-free leaf) — enforced by sandbox-access-import-guard.test.ts.
@@ -29,8 +29,10 @@ import type { Session } from "@opengeni/contracts";
 import {
   acquireLease,
   getSandboxSessionEnvelope,
+  getSandbox,
   loadWorkspaceEnvironmentForRun,
   markWarmLeaseInstanceLost,
+  readActiveSandbox,
   readLease,
   releaseLeaseHolder,
   type Database,
@@ -40,9 +42,11 @@ import { appendAndPublishEvents, type EventBus } from "@opengeni/events";
 import { HTTPException } from "hono/http-exception";
 
 import {
+  buildSelfhostedBackendSession,
   establishSandboxSessionFromEnvelope,
   isProviderSandboxNotFoundError,
   SandboxChannelAService,
+  NatsControlRpc,
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
@@ -55,7 +59,7 @@ import {
   type EstablishedSandboxSession,
   type RoutingSandboxSession,
 } from "@opengeni/runtime/sandbox";
-import { wrapChannelABoxWithRouting } from "@opengeni/core";
+import { relayConfigFromSettings, wrapChannelABoxWithRouting } from "@opengeni/core";
 import { establishApiSandboxSpawner } from "./rematerialize";
 
 export type ChannelAServices = {
@@ -76,7 +80,9 @@ export type ChannelAContext = {
 // (for the pty exec-session epoch fence + revision seeding).
 export type ChannelAHandle = {
   service: SandboxChannelAService;
-  lease: LeaseSnapshot;
+  /** Connected Machine homes deliberately have no cloud lease. Durable PTYs
+   * require a real home-provider lease and reject this null case. */
+  lease: LeaseSnapshot | null;
   routingSession: RoutingSandboxSession;
   requestId: string;
 };
@@ -107,6 +113,117 @@ export async function withChannelA<T>(
   const holderId = `direct:${requestId}`;
   const leaseTtlMs = settings.sandboxLeaseTtlMs;
 
+  // The STABLE run-environment used by both a cloud home and a machine home.
+  // It also carries the per-session Toolspace pointer selected below.
+  const workspaceEnvironment = await loadWorkspaceEnvironmentForRun(
+    db,
+    settings,
+    workspaceId,
+    session.environmentId,
+  );
+  const settingsForSession =
+    session.sandboxBackend !== settings.sandboxBackend
+      ? { ...settings, sandboxBackend: session.sandboxBackend }
+      : settings;
+  const environment = stableSandboxEnvironmentForRun(
+    settingsForSession,
+    workspaceEnvironment?.values ?? {},
+    { workspaceId },
+  );
+  if (hasGitCredentialRepositorySelection(session.resources)) {
+    applyGitAuthPointerEnvironment(
+      environment,
+      hasGitHubRepositorySelection(session.resources) ? githubAppBotIdentity(settings) : null,
+    );
+  }
+
+  const runEstablished = async (
+    routed: EstablishedSandboxSession,
+    lease: LeaseSnapshot | null,
+  ): Promise<T> => {
+    const emit = async (events: { type: string; payload: unknown }[]): Promise<void> => {
+      await appendAndPublishEvents(
+        db,
+        bus,
+        workspaceId,
+        session.id,
+        events.map((e) => ({ type: e.type as never, payload: e.payload })),
+      );
+    };
+    const routingSession = routed.session as RoutingSandboxSession;
+    const credentialSession = withRunCredentialsSession(routingSession as object, session.id);
+    const scopedSession = environment.OPENGENI_TOOLSPACE_TOKEN_FILE
+      ? withToolspaceTokenSession(
+          credentialSession,
+          toolspaceTokenFileFromEnvironment(environment, session.id),
+        )
+      : credentialSession;
+    const service = new SandboxChannelAService({
+      session: scopedSession as ChannelASession,
+      leaseEpoch: lease?.leaseEpoch ?? session.activeEpoch,
+      emit,
+    });
+    return await fn({ service, lease, routingSession, requestId });
+  };
+
+  // A machine-targeted top-level session has an honest selfhosted HOME label.
+  // It has no cloud provider box and therefore must not acquire or establish a
+  // phantom home lease before following its active machine pointer.
+  if (session.sandboxBackend === "selfhosted") {
+    let established: EstablishedSandboxSession | undefined;
+    try {
+      const pointer = await readActiveSandbox(db, workspaceId, session.id);
+      if (!pointer?.activeSandboxId) {
+        throw new HTTPException(409, {
+          message: "machine-home session has no active Connected Machine",
+        });
+      }
+      const sandbox = await getSandbox(db, workspaceId, pointer.activeSandboxId);
+      if (sandbox?.kind !== "selfhosted" || !sandbox.enrollmentId) {
+        throw new HTTPException(409, {
+          message: "machine-home session points to an unavailable Connected Machine",
+        });
+      }
+      const built = await buildSelfhostedBackendSession({
+        workspaceId,
+        agentId: sandbox.enrollmentId,
+        relay: relayConfigFromSettings(settings),
+        controlRpcFactory: () => new NatsControlRpc(async () => bus.getRequestConnection()),
+        epoch: pointer.activeEpoch,
+        environment,
+        workingDir: pointer.workingDir,
+        timeoutMs: settings.sandboxSelfhostedControlTimeoutMs,
+        execTimeoutMs: settings.sandboxSelfhostedExecTimeoutMs,
+      });
+      established = {
+        client: built.client,
+        session: built.session,
+        sessionState: { agentId: sandbox.enrollmentId },
+        instanceId: sandbox.enrollmentId,
+        backendId: "selfhosted",
+      };
+      const routed = wrapChannelABoxWithRouting(
+        { db, settings, bus },
+        {
+          accountId,
+          workspaceId,
+          sessionId: session.id,
+          pinnedSelfhosted: {
+            sandboxId: sandbox.id,
+            epoch: pointer.activeEpoch,
+          },
+          directRequest: { requestId, holderId },
+        },
+        established,
+      );
+      return await runEstablished(routed, null);
+    } catch (error) {
+      throw mapChannelAError(error);
+    } finally {
+      await dropEstablishedHandle(established);
+    }
+  }
+
   const release = async (): Promise<void> => {
     await releaseLeaseHolder(db, {
       accountId,
@@ -150,36 +267,6 @@ export async function withChannelA<T>(
 
   try {
     const envelope = await getSandboxSessionEnvelope(db, workspaceId, session.id);
-    // The STABLE run-environment a COLD box must be created with so a later worker
-    // turn's agent-manifest apply finds an EMPTY env delta (config base + git
-    // identity + decrypted workspace env + HOME + — for a repo-attached session —
-    // the stable git-auth pointers the turn declares). Only the rotating token
-    // VALUE stays off (it lives in the box file the clone hook seeds). Keyed off
-    // the SESSION's backend (the establish below passes backendOverride:
-    // session.sandboxBackend, and HOME/token-file/askpass are backend-derived),
-    // NOT the deployment default — mirrors sessionAttachEnvironment.
-    const workspaceEnvironment = await loadWorkspaceEnvironmentForRun(
-      db,
-      settings,
-      workspaceId,
-      session.environmentId,
-    );
-    const settingsForSession =
-      session.sandboxBackend !== settings.sandboxBackend
-        ? { ...settings, sandboxBackend: session.sandboxBackend }
-        : settings;
-    const environment = stableSandboxEnvironmentForRun(
-      settingsForSession,
-      workspaceEnvironment?.values ?? {},
-      { workspaceId },
-    );
-    if (hasGitCredentialRepositorySelection(session.resources)) {
-      applyGitAuthPointerEnvironment(
-        environment,
-        hasGitHubRepositorySelection(session.resources) ? githubAppBotIdentity(settings) : null,
-      );
-    }
-
     if (acquired.role === "spawner") {
       // We won the cold->warming CAS: establish the box from the envelope, then
       // commit warm. The established handle IS our live handle for the op.
@@ -261,22 +348,10 @@ export async function withChannelA<T>(
       }
     }
 
-    const emit = async (events: { type: string; payload: unknown }[]): Promise<void> => {
-      await appendAndPublishEvents(
-        db,
-        bus,
-        workspaceId,
-        session.id,
-        // SessionEventType is a string enum at the contract; the producer parses
-        // the payload, so this cast is the same shape the worker emits.
-        events.map((e) => ({ type: e.type as never, payload: e.payload })),
-      );
-    };
-
     // Route every call through the same proxy, even when hot-swap is disabled:
     // routing may be dormant, but its direct mutation admission is mandatory for
     // every persistable provider write.
-    const routedSession = wrapChannelABoxWithRouting(
+    const routed = wrapChannelABoxWithRouting(
       { db, settings, bus },
       {
         accountId,
@@ -291,22 +366,8 @@ export async function withChannelA<T>(
         directRequest: { requestId, holderId },
       },
       established,
-    ).session as RoutingSandboxSession;
-    const credentialSession = withRunCredentialsSession(routedSession as object, session.id);
-    const scopedSession = environment.OPENGENI_TOOLSPACE_TOKEN_FILE
-      ? withToolspaceTokenSession(
-          credentialSession,
-          toolspaceTokenFileFromEnvironment(environment, session.id),
-        )
-      : credentialSession;
-
-    const service = new SandboxChannelAService({
-      session: scopedSession as ChannelASession,
-      leaseEpoch: leaseSnapshot.leaseEpoch,
-      emit,
-    });
-
-    return await fn({ service, lease: leaseSnapshot, routingSession: routedSession, requestId });
+    );
+    return await runEstablished(routed, leaseSnapshot);
   } catch (error) {
     throw mapChannelAError(error);
   } finally {