@opengeni/api-router 0.30.3 → 1.0.0

package/src/sandbox/rematerialize.ts

@@ -1,4 +1,5 @@
 import type { Settings } from "@opengeni/config";
+import { parseWorkspaceArchiveObjectRef } from "@opengeni/contracts";
 import {
   adoptLegacyModalCheckpointArtifact,
   beginSandboxRematerialization,
@@ -6,6 +7,7 @@ import {
   failSandboxRematerialization,
   failWarmingToCold,
   markSandboxRestoreVerifying,
+  sessionHoldsFreshWorkspaceRecovery,
   recordWarmingSandboxCreated,
   SandboxLeaseRecoveryBlockedError,
   SandboxLeaseSupersededError,
@@ -13,6 +15,7 @@ import {
   type LeaseSnapshot,
 } from "@opengeni/db";
 import {
+  inlineWorkspaceArchiveForRestore,
   describeLegacyNativeSnapshotArchive,
   establishSandboxSessionFromEnvelope,
   isProviderSandboxNotFoundError,
@@ -30,17 +33,68 @@ import {
   type EstablishedSandboxSession,
   type WorkspaceArchiveDescriptor,
 } from "@opengeni/runtime/sandbox";
+import {
+  downloadWorkspaceArchiveSpool,
+  WorkspaceArchiveStorageError,
+  type ObjectStorage,
+} from "@opengeni/storage";
 
 function hasWorkspaceArchive(envelope: Record<string, unknown> | null): boolean {
   const sessionState =
-    envelope?.sessionState && typeof envelope.sessionState === "object"
+    envelope?.sessionState &&
+    typeof envelope.sessionState === "object" &&
+    !Array.isArray(envelope.sessionState)
       ? (envelope.sessionState as Record<string, unknown>)
       : null;
   return (
-    typeof sessionState?.workspaceArchive === "string" && sessionState.workspaceArchive.length > 0
+    (typeof sessionState?.workspaceArchive === "string" &&
+      sessionState.workspaceArchive.length > 0) ||
+    parseWorkspaceArchiveObjectRef(sessionState?.workspaceArchiveRef) !== null
   );
 }
 
+async function materializeArchiveObjectRef(
+  envelope: Record<string, unknown> | null,
+  objectStorage: ObjectStorage | null | undefined,
+): Promise<Record<string, unknown> | null> {
+  if (!envelope) return null;
+  const sessionState =
+    envelope.sessionState &&
+    typeof envelope.sessionState === "object" &&
+    !Array.isArray(envelope.sessionState)
+      ? (envelope.sessionState as Record<string, unknown>)
+      : null;
+  if (!sessionState) return envelope;
+  if (sessionState.workspaceArchiveRef == null) return envelope;
+  if (!parseWorkspaceArchiveObjectRef(sessionState.workspaceArchiveRef)) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_metadata_invalid",
+      "workspace archive object reference is malformed",
+    );
+  }
+  if (!objectStorage) {
+    throw new WorkspaceArchiveIntegrityError(
+      "archive_storage_unavailable",
+      "workspace archive object storage is not configured",
+      { retryable: true },
+    );
+  }
+  const descriptor = parseWorkspaceArchiveDescriptor(sessionState.workspaceArchiveMeta);
+  if (
+    process.platform === "linux" &&
+    descriptor?.version === 1 &&
+    descriptor.workspace.projection === "sdk_local_archive_v1"
+  ) {
+    return envelope;
+  }
+  return {
+    ...envelope,
+    sessionState: await inlineWorkspaceArchiveForRestore(sessionState, (key) =>
+      objectStorage.getObjectBytes(key),
+    ),
+  };
+}
+
 function legacyNativeArchiveFromEnvelope(envelope: Record<string, unknown> | null) {
   const sessionState =
     envelope?.sessionState && typeof envelope.sessionState === "object"
@@ -82,14 +136,31 @@ export async function establishApiSandboxSpawner(input: {
   acquiredLease: LeaseSnapshot;
   fallbackEnvelope: Record<string, unknown> | null;
   dataPlaneUrl: string | null;
+  objectStorage?: ObjectStorage | null;
 }): Promise<{ established: EstablishedSandboxSession; lease: LeaseSnapshot }> {
+  // An audited decision to continue a definitively lost workspace on a new
+  // EMPTY box: hydrate nothing, including a per-session legacy archive, and
+  // never resume a prior provider identity. Commit verifies the decision.
+  const freshWorkspaceRecoveryId = input.acquiredLease.freshWorkspaceRecoveryId ?? null;
+  // Backstop: a session already told its workspace is empty never gets a
+  // legacy per-session archive back, even if the lease marker was lost.
+  const legacyFallbackRefused =
+    !freshWorkspaceRecoveryId &&
+    input.acquiredLease.recovery.archive.status === "none" &&
+    hasWorkspaceArchive(input.fallbackEnvelope) &&
+    (await sessionHoldsFreshWorkspaceRecovery(input.db, input.workspaceId, input.sessionId));
   const fallbackArchiveEnvelope =
+    !freshWorkspaceRecoveryId &&
+    !legacyFallbackRefused &&
     input.acquiredLease.recovery.archive.status === "none" &&
     hasWorkspaceArchive(input.fallbackEnvelope)
       ? withoutSandboxProviderIdentity(input.fallbackEnvelope)
       : null;
-  let spawnEnvelope =
-    fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope;
+  let spawnEnvelope = freshWorkspaceRecoveryId
+    ? null
+    : legacyFallbackRefused
+      ? (input.acquiredLease.resumeState ?? null)
+      : (fallbackArchiveEnvelope ?? input.acquiredLease.resumeState ?? input.fallbackEnvelope);
   const archiveSource =
     input.acquiredLease.recovery.archive.status === "none"
       ? fallbackArchiveEnvelope
@@ -108,9 +179,12 @@ export async function establishApiSandboxSpawner(input: {
   const continuityRecovery = input.acquiredLease.recovery.continuity;
   try {
     if (
-      (input.acquiredLease.recovery.archive.status === "available" &&
-        input.acquiredLease.archiveComplete) ||
-      (input.acquiredLease.recovery.archive.status === "none" && hasWorkspaceArchive(archiveSource))
+      !freshWorkspaceRecoveryId &&
+      ((input.acquiredLease.recovery.archive.status === "available" &&
+        (input.acquiredLease.archiveComplete ||
+          input.acquiredLease.historicalRecoveryAuthorized === true)) ||
+        (input.acquiredLease.recovery.archive.status === "none" &&
+          hasWorkspaceArchive(archiveSource)))
     ) {
       const id = crypto.randomUUID();
       const legacyNativeArchive = legacyNativeArchiveFromEnvelope(archiveSource);
@@ -153,7 +227,11 @@ export async function establishApiSandboxSpawner(input: {
         legacyCheckpoint: begun.checkpointArtifact === null ? legacyNativeArchive : null,
         legacyProviderBinding: null,
       };
-    } else if (input.acquiredLease.recovery.archive.status !== "none" && !continuityRecovery) {
+    } else if (
+      !freshWorkspaceRecoveryId &&
+      input.acquiredLease.recovery.archive.status !== "none" &&
+      !continuityRecovery
+    ) {
       throw new SandboxLeaseRecoveryBlockedError(
         input.sandboxGroupId,
         input.expectedEpoch,
@@ -162,10 +240,32 @@ export async function establishApiSandboxSpawner(input: {
       );
     }
 
+    const hydrateEnvelope = await materializeArchiveObjectRef(spawnEnvelope, input.objectStorage);
+
     const providerCreateStartedAt = new Date();
-    established = await establishSandboxSessionFromEnvelope(input.settings, spawnEnvelope, {
+    established = await establishSandboxSessionFromEnvelope(input.settings, hydrateEnvelope, {
       sessionId: input.sessionId,
       recovery: "create-or-restore",
+      ...(input.objectStorage
+        ? {
+            loadHostWorkspaceArchive: async (ref) => {
+              try {
+                return await downloadWorkspaceArchiveSpool(input.objectStorage!, ref.key, {
+                  bytes: ref.bytes,
+                  sha256: ref.sha256,
+                });
+              } catch (error) {
+                if (error instanceof WorkspaceArchiveStorageError) {
+                  throw new WorkspaceArchiveIntegrityError(error.code, error.message, {
+                    retryable: error.retryable,
+                    cause: error,
+                  });
+                }
+                throw error;
+              }
+            },
+          }
+        : {}),
       backendOverride: input.backend as never,
       environment: input.environment,
       onSandboxCreated: async (created) => {
@@ -308,16 +408,18 @@ export async function establishApiSandboxSpawner(input: {
       dataPlaneUrl: input.dataPlaneUrl,
       resumeBackendId: established.backendId,
       resumeState,
-      ...(established.providerContinuity
-        ? { continuityRecovery: established.providerContinuity }
-        : rematerialization
-          ? {
-              rematerialization: {
-                id: rematerialization.id,
-                verifiedRevision: rematerialization.selectedRevision,
-              },
-            }
-          : {}),
+      ...(freshWorkspaceRecoveryId
+        ? { freshWorkspace: { operationId: freshWorkspaceRecoveryId } }
+        : established.providerContinuity
+          ? { continuityRecovery: established.providerContinuity }
+          : rematerialization
+            ? {
+                rematerialization: {
+                  id: rematerialization.id,
+                  verifiedRevision: rematerialization.selectedRevision,
+                },
+              }
+            : {}),
       leaseTtlMs: input.settings.sandboxLeaseTtlMs,
     });
     if (!committed.committed || !committed.lease) {

package/src/sandbox/session-attach-variable-sets.ts

@@ -0,0 +1,131 @@
+import type { Settings } from "@opengeni/config";
+import {
+  getScheduledScopedRigVersionMetadata,
+  loadWorkspaceEnvironmentForRun,
+  nestedPostgresSqlState,
+  type Database,
+} from "@opengeni/db";
+import { ApiHttpError } from "../http/api-error";
+
+export type SessionAttachVariableSetSession = {
+  id: string;
+  rigId?: string | null | undefined;
+  rigVersionId?: string | null | undefined;
+  variableSetIds?: readonly string[] | null | undefined;
+  /** Legacy final-entry alias for projections that predate the plural field. */
+  variableSetId?: string | null | undefined;
+};
+
+type VariableSetSource = "sandbox_environment_default" | "session_selection";
+
+/**
+ * Decrypted Variable Set values for a direct session attach (terminal, Files,
+ * Git, desktop viewer), in the same order and precedence as the worker turn:
+ * the frozen Sandbox Environment version defaults first, then the session's
+ * own selection, so a box first warmed by an attach declares exactly the
+ * environment the next turn declares.
+ *
+ * A Variable Set the session can no longer use (the database seam answers
+ * 42501 and records a `variable_set.materialize.denied` fact) becomes a 403
+ * instead of a bare 500. Every failure is logged with the session, set, source
+ * and SQLSTATE, never a value.
+ */
+export async function loadSessionAttachVariableSetValues(
+  db: Database,
+  settings: Settings,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    session: SessionAttachVariableSetSession;
+    /** The authenticated route subject driving the attach; null records the
+     *  legacy service sentinel on the materialization audit fact. */
+    subjectId: string | null;
+  },
+): Promise<Record<string, string>> {
+  const { accountId, workspaceId, session, subjectId } = input;
+  const values: Record<string, string> = {};
+  let defaultVariableSetIds: readonly string[] = [];
+  if (session.rigId && session.rigVersionId) {
+    try {
+      const rigVersion = await getScheduledScopedRigVersionMetadata(
+        db,
+        { accountId, workspaceId, subjectId: subjectId ?? "session-attach" },
+        session.rigId,
+        session.rigVersionId,
+      );
+      defaultVariableSetIds = rigVersion?.version.defaultVariableSetIds ?? [];
+    } catch (error) {
+      logAttachFailure("sandbox environment lookup failed", error, {
+        sessionId: session.id,
+        rigId: session.rigId,
+        rigVersionId: session.rigVersionId,
+      });
+      throw error;
+    }
+  }
+  // Older persisted/test projections can omit the plural field. Preserve the
+  // legacy final alias as the single explicit selection.
+  const selectedVariableSetIds =
+    session.variableSetIds ?? (session.variableSetId ? [session.variableSetId] : []);
+  const ordered: Array<{ variableSetId: string; source: VariableSetSource }> = [
+    ...defaultVariableSetIds.map((variableSetId) => ({
+      variableSetId,
+      source: "sandbox_environment_default" as const,
+    })),
+    ...selectedVariableSetIds.map((variableSetId) => ({
+      variableSetId,
+      source: "session_selection" as const,
+    })),
+  ];
+  for (const { variableSetId, source } of ordered) {
+    try {
+      const loaded = await loadWorkspaceEnvironmentForRun(db, settings, {
+        accountId,
+        workspaceId,
+        variableSetId,
+        authority: { kind: "session_attach", sessionId: session.id, subjectId },
+      });
+      Object.assign(values, loaded?.values ?? {});
+    } catch (error) {
+      logAttachFailure("variable set materialization failed", error, {
+        sessionId: session.id,
+        variableSetId,
+        source,
+      });
+      if (nestedPostgresSqlState(error) === "42501") {
+        throw new ApiHttpError(403, {
+          code: "forbidden",
+          message:
+            source === "sandbox_environment_default"
+              ? "A default Variable Set of this session's Sandbox Environment is not available to this session."
+              : "A Variable Set selected for this session is not available to this session.",
+          retryable: false,
+          details: { variableSetId, source },
+        });
+      }
+      throw error;
+    }
+  }
+  return values;
+}
+
+function logAttachFailure(message: string, error: unknown, context: Record<string, string>): void {
+  const sqlState = nestedPostgresSqlState(error);
+  console.warn(`[session-attach] ${message}`, {
+    ...context,
+    ...(sqlState ? { sqlState } : {}),
+    error: rootCauseMessage(error),
+  });
+}
+
+/** The innermost cause's message: the database's own reason rather than the
+ *  query-builder wrapper that repeats the statement text. */
+function rootCauseMessage(error: unknown): string {
+  let current: unknown = error;
+  for (let depth = 0; depth < 8; depth += 1) {
+    const cause = current instanceof Error ? current.cause : undefined;
+    if (!(cause instanceof Error)) break;
+    current = cause;
+  }
+  return current instanceof Error ? current.message : String(current);
+}