@opengeni/api-router 0.30.1 → 1.0.0

package/src/site-uploads.ts

@@ -0,0 +1,224 @@
+import { WorkspaceArtifactSourceBundle, type AccessGrant } from "@opengeni/contracts";
+import type { ApiRouteDeps, ObjectStorageDependency } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
+import {
+  createWorkspaceArtifactUpload,
+  getWorkspaceArtifactUpload,
+  expireWorkspaceArtifactUploads,
+  WorkspaceArtifactOperationError,
+} from "@opengeni/db";
+import {
+  prepareWorkspaceArtifactContent,
+  type PreparedWorkspaceArtifactContent,
+} from "./workspace-artifact-content";
+import { userContentSignedGetUrlOptions } from "./http/user-content";
+type Storage = NonNullable<ObjectStorageDependency>;
+export const MAX_SITE_SOURCE_BYTES = 64 * 1024 * 1024;
+
+export async function validateSiteSource(storage: Storage, key: string, sizeBytes: number) {
+  if (sizeBytes > MAX_SITE_SOURCE_BYTES) {
+    throw new WorkspaceArtifactOperationError(
+      "Editable source JSON must be at most 64 MiB. Exclude dependencies and build output; HTML has a separate storage limit.",
+    );
+  }
+  const content = await retryWhileMissing(() => storage.getObjectBytes(key));
+  if (!content) {
+    throw new WorkspaceArtifactOperationError(
+      "Site source is not available yet. Retry publication with the same upload.",
+    );
+  }
+  try {
+    WorkspaceArtifactSourceBundle.parse(
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(content.bytes)),
+    );
+  } catch {
+    throw new WorkspaceArtifactOperationError(
+      "Source must be JSON {entrypoint, files: [{path, content}]}. Correct it and prepare a new upload.",
+    );
+  }
+}
+function keys(workspaceId: string, id: string) {
+  const base = `workspaces/${workspaceId}/workspace-artifacts`;
+  return {
+    html: `${base}/uploads/${id}/index.html`,
+    source: `${base}/uploads/${id}/source.json`,
+    frozenHtml: `${base}/blobs/${id}.html`,
+    frozenSource: `${base}/sources/${id}.json`,
+  };
+}
+function owner(grant: AccessGrant) {
+  return typeof grant.metadata?.sessionId === "string"
+    ? `session:${grant.metadata.sessionId}`
+    : `subject:${grant.subjectId}`;
+}
+export async function prepareWorkspaceArtifactUpload(deps: ApiRouteDeps, grant: AccessGrant) {
+  const storage = deps.objectStorage;
+  if (!storage) throw new Error("Object storage is not configured");
+  const expired = await expireWorkspaceArtifactUploads(deps.db, grant.workspaceId);
+  await Promise.allSettled(
+    expired.flatMap((row) => {
+      const paths = keys(row.workspaceId, row.id);
+      return (row.status === "published" ? [paths.html, paths.source] : Object.values(paths)).map(
+        (key) => storage.deleteObject(key),
+      );
+    }),
+  );
+  const row = await createWorkspaceArtifactUpload(deps.db, {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    ownerId: owner(grant),
+  });
+  const paths = keys(grant.workspaceId, row.id);
+  const audience = grant.principalKind === "agent_attempt" ? "sandbox" : "public";
+  const [html, source] = await Promise.all([
+    storage.createPutUrl({ key: paths.html, contentType: "text/html", audience }),
+    storage.createPutUrl({ key: paths.source, contentType: "application/json", audience }),
+  ]);
+  return {
+    uploadId: row.id,
+    html: { putUrl: html.url, requiredHeaders: html.requiredHeaders },
+    source: { putUrl: source.url, requiredHeaders: source.requiredHeaders },
+    expiresAt: new Date(
+      Math.min(html.expiresAt.getTime(), source.expiresAt.getTime()),
+    ).toISOString(),
+  };
+}
+/** Provider version-pinned reads, without Site SHA checks or full HTML buffering. */
+export async function* readArtifactObject(
+  storage: Storage,
+  key: string,
+  expectedHead?: Awaited<ReturnType<NonNullable<Storage["headObject"]>>>,
+) {
+  if (!storage.headObject || !storage.getObjectRange)
+    throw new Error("Object storage cannot stream Site content");
+  const head = expectedHead ?? (await storage.headObject(key));
+  if (!head || !head.VersionToken || head.ContentLength === undefined)
+    throw new Error("Site content is unavailable");
+  for (let start = 0; start < head.ContentLength; start += 1024 * 1024) {
+    const endInclusive = Math.min(head.ContentLength - 1, start + 1024 * 1024 - 1);
+    const part = await storage.getObjectRange({
+      key,
+      start,
+      endInclusive,
+      expectedVersionToken: head.VersionToken,
+    });
+    if (
+      !part ||
+      part.versionToken !== head.VersionToken ||
+      part.bytes.length !== endInclusive - start + 1
+    )
+      throw new Error("Site object changed during transfer");
+    yield part.bytes;
+  }
+}
+async function freeze(
+  storage: Storage,
+  from: string,
+  to: string,
+  contentType: string,
+  optional = false,
+) {
+  if (!storage.headObject || !storage.putObjectStreamIfAbsent)
+    throw new Error("Object storage cannot freeze Site uploads");
+  const existing = await storage.headObject(to);
+  if (existing) return existing.ContentLength!;
+  const head = await storage.headObject(from);
+  if (!head && optional) return null;
+  if (!head || !head.ContentLength)
+    throw new WorkspaceArtifactOperationError("Upload HTML before publishing the Site");
+  if (head.ContentLength > storage.maxSinglePutSizeBytes)
+    throw new Error("Site exceeds the storage upload limit");
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  async function* chunks() {
+    for await (const part of readArtifactObject(storage, from, head)) {
+      decoder.decode(part, { stream: true });
+      yield part;
+    }
+    decoder.decode();
+  }
+  const created = await storage.putObjectStreamIfAbsent({
+    key: to,
+    contentType,
+    byteSize: head.ContentLength,
+    chunks: chunks(),
+  });
+  // A successful conditional PUT is the receipt. A following visibility miss
+  // cannot invalidate it. Only a conflict needs the existing winner's metadata.
+  if (created) return head.ContentLength;
+  const stored = await retryWhileMissing(() => storage.headObject!(to));
+  if (!stored || stored.ContentLength === undefined) {
+    throw new WorkspaceArtifactOperationError(
+      "Frozen Site upload is unavailable. Retry publication with the same upload.",
+    );
+  }
+  return stored.ContentLength;
+}
+type Input = Partial<Parameters<typeof prepareWorkspaceArtifactContent>[2]> & { uploadId?: string };
+export async function prepareWorkspaceArtifactPublication(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  input: Input,
+): Promise<PreparedWorkspaceArtifactContent & { uploadId?: string }> {
+  const storage = deps.objectStorage;
+  if (!storage) throw new Error("Object storage is not configured");
+  if (Boolean(input.uploadId) === (input.html !== undefined))
+    throw new Error("Provide either uploadId or inline html, not both");
+  if (!input.uploadId) {
+    return prepareWorkspaceArtifactContent(storage, grant.workspaceId, {
+      ...input,
+      html: input.html!,
+    });
+  }
+  if (input.source) throw new Error("Upload source JSON using the source upload URL");
+  const row = await getWorkspaceArtifactUpload(deps.db, grant.workspaceId, input.uploadId);
+  if (
+    !row ||
+    row.ownerId !== owner(grant) ||
+    row.status === "expired" ||
+    (row.status === "pending" && row.expiresAt.getTime() <= Date.now())
+  )
+    throw new WorkspaceArtifactOperationError("Site upload expired or unavailable");
+  const paths = keys(grant.workspaceId, row.id);
+  const sizeBytes = await freeze(storage, paths.html, paths.frozenHtml, "text/html; charset=utf-8");
+  const sourceSizeBytes =
+    row.status === "published" && !(await storage.headObject!(paths.frozenSource))
+      ? null
+      : await freeze(storage, paths.source, paths.frozenSource, "application/json", true);
+  if (sourceSizeBytes !== null) {
+    await validateSiteSource(storage, paths.frozenSource, sourceSizeBytes);
+  }
+  return {
+    uploadId: row.id,
+    contentKey: paths.frozenHtml,
+    contentSha256: null,
+    sizeBytes: sizeBytes!,
+    sourceKey: sourceSizeBytes === null ? null : paths.frozenSource,
+    sourceSha256: null,
+    sourceSizeBytes,
+    ...(input.requestedTools === undefined ? {} : { requestedTools: input.requestedTools }),
+    persistContent: async () => {},
+    discardContent: async () => {},
+  };
+}
+export async function workspaceArtifactDownloads(
+  storage: Storage,
+  ref: { contentKey: string; sourceKey: string | null },
+  audience: "sandbox" | "public",
+) {
+  const [html, source] = await Promise.all([
+    // Site HTML runs publisher scripts; opened directly from storage it would
+    // render outside the console's opaque-origin frame, so it downloads.
+    storage.createGetUrl({
+      key: ref.contentKey,
+      audience,
+      ...userContentSignedGetUrlOptions("text/html", "site.html"),
+    }),
+    ref.sourceKey ? storage.createGetUrl({ key: ref.sourceKey, audience }) : null,
+  ]);
+  return {
+    html: { url: html.url, expiresAt: html.expiresAt },
+    source: source
+      ? { url: source.url, expiresAt: source.expiresAt, format: "source-bundle-json" }
+      : null,
+  };
+}

package/src/slack-reaction-files.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { FileResourceRef } from "@opengeni/contracts";
 import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
-import type { ObjectHead, ObjectStorage } from "@opengeni/storage";
+import { retryWhileMissing, type ObjectHead, type ObjectStorage } from "@opengeni/storage";
 import type { DownloadedSlackReactionImage } from "./integrations/slack-bot";
 
 const IMPORT_IDENTITY_VERSION = "slack-reaction-image-v1";
@@ -77,13 +77,15 @@ export async function importSlackReactionImage(
     if (existing) {
       assertStoredSlackImage(existing, image, sha256);
     } else if (storage.putObjectIfAbsent) {
-      await storage.putObjectIfAbsent({
+      const created = await storage.putObjectIfAbsent({
         key: objectKey,
         contentType: image.contentType,
         body: image.bytes,
         sha256,
       });
-      assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
+      if (!created) {
+        await assertVisibleSlackImage(storage, objectKey, image, sha256);
+      }
     } else {
       await storage.putObject({
         key: objectKey,
@@ -91,7 +93,6 @@ export async function importSlackReactionImage(
         body: image.bytes,
         sha256,
       });
-      assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
     }
     file = await (dependencies.completeFile ?? completeFileUpload)(
       dependencies.db,
@@ -99,7 +100,7 @@ export async function importSlackReactionImage(
       uploadId,
     );
   } else {
-    assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
+    await assertVisibleSlackImage(storage, objectKey, image, sha256);
   }
 
   if (
@@ -153,6 +154,16 @@ export function safeSlackImageFilename(
   return `${stem}${extension}`;
 }
 
+async function assertVisibleSlackImage(
+  storage: ObjectStorage,
+  objectKey: string,
+  image: DownloadedSlackReactionImage,
+  sha256: string,
+): Promise<void> {
+  const head = await retryWhileMissing(async () => await storage.headObject!(objectKey));
+  assertStoredSlackImage(head, image, sha256);
+}
+
 function assertStoredSlackImage(
   head: ObjectHead | null,
   image: DownloadedSlackReactionImage,

package/src/temporal-schedule-cleanup.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import {
   claimTemporalScheduleCleanups,
+  completeTemporalScheduleConnectorCleanup,
   settleTemporalScheduleCleanup,
   type Database,
   type TemporalScheduleCleanupClaim,
@@ -13,6 +14,7 @@ const CLEANUP_POLL_INTERVAL_MS = 1_000;
 
 type TemporalScheduleCleanupDependencies = {
   db: Database;
+  cleanupConnectorAuthorization?: (claim: TemporalScheduleCleanupClaim) => Promise<void>;
   deleteSchedule: (temporalScheduleId: string) => Promise<void>;
   observability?: Pick<Observability, "info" | "warn" | "error">;
 };
@@ -39,6 +41,17 @@ export async function processTemporalScheduleCleanupClaims(
   const results = await Promise.all(
     claims.map(async (claim): Promise<"deleted" | "failed" | "stale"> => {
       try {
+        if (claim.connectorCleanupSnapshot && !claim.connectorCleanupCompletedAt) {
+          if (!deps.cleanupConnectorAuthorization) {
+            throw new Error("scheduled connector cleanup dependency is unavailable");
+          }
+          await deps.cleanupConnectorAuthorization(claim);
+          const completed = await completeTemporalScheduleConnectorCleanup(deps.db, {
+            id: claim.id,
+            claimId: claim.claimId,
+          });
+          if (!completed) return "stale";
+        }
         await deps.deleteSchedule(claim.temporalScheduleId);
         const settled = await settleTemporalScheduleCleanup(deps.db, {
           id: claim.id,

package/src/temporal-schedule-sync.ts

@@ -0,0 +1,74 @@
+import type { ScheduledTask } from "@opengeni/contracts";
+import { getScheduledTaskIncludingDeleted, type Database } from "@opengeni/db";
+import { sql } from "drizzle-orm";
+
+const LOCK_TIMEOUT = "5s";
+const WRITE_TIMEOUT_MS = 5_000;
+
+type TemporalScheduleSyncDependencies = {
+  db: Database;
+  withDeadline<T>(deadline: number, work: () => Promise<T>): Promise<T>;
+  upsert(task: ScheduledTask): Promise<void>;
+  /** Idempotent: an absent Temporal schedule is already removed. */
+  remove(temporalScheduleId: string): Promise<void>;
+};
+
+/**
+ * Serialize external writes across API replicas, independently of task edits.
+ * A queued sync rereads the newest committed row after acquiring this lock;
+ * input snapshots never become desired state. Cleanup uses the same key, so
+ * an in-flight upsert finishes before its tombstone's external deletion.
+ * Failure compensation commits before releasing the lock, so a queued writer
+ * cannot read the row being restored and then publish that failed edit.
+ *
+ * Deadlines bound both lock admission and network occupancy. A thrown network
+ * error retains its unknown-outcome semantics; this is not durable recovery
+ * for a process crash or a lost Temporal acknowledgement.
+ */
+export function createTemporalScheduleSynchronizer(deps: TemporalScheduleSyncDependencies) {
+  const write = async <T>(
+    temporalScheduleId: string,
+    work: (tx: Database) => Promise<T>,
+  ): Promise<T> =>
+    deps.db.transaction(async (tx) => {
+      await tx.execute(sql`select set_config('lock_timeout', ${LOCK_TIMEOUT}, true)`);
+      await tx.execute(sql`select pg_advisory_xact_lock(
+        hashtextextended(${`scheduled-task-temporal:${temporalScheduleId}`}, 0)
+      )`);
+      return await work(tx);
+    });
+
+  return {
+    async sync(
+      task: Pick<ScheduledTask, "id" | "workspaceId" | "temporalScheduleId">,
+      onFailure?: (tx: Database, error: unknown) => Promise<Error>,
+    ) {
+      const result = await write(task.temporalScheduleId, async (tx) => {
+        try {
+          await deps.withDeadline(Date.now() + WRITE_TIMEOUT_MS, async () => {
+            const current = await getScheduledTaskIncludingDeleted(tx, task.workspaceId, task.id);
+            if (current && current.temporalScheduleId !== task.temporalScheduleId)
+              throw new Error("Scheduled task Temporal identity changed");
+            if (!current || current.deletedAt !== null || current.schedule.type === "manual") {
+              await deps.remove(task.temporalScheduleId);
+              return;
+            }
+            const { deletedAt: _deletedAt, ...latest } = current;
+            await deps.upsert(latest);
+          });
+          return { ok: true as const };
+        } catch (error) {
+          return { ok: false as const, error: onFailure ? await onFailure(tx, error) : error };
+        }
+      });
+      // Throw after commit: throwing inside the transaction would also undo a
+      // successful compensation. A failed commit cannot claim that receipt.
+      if (!result.ok) throw result.error;
+    },
+    async remove(temporalScheduleId: string) {
+      await write(temporalScheduleId, async () =>
+        deps.withDeadline(Date.now() + WRITE_TIMEOUT_MS, () => deps.remove(temporalScheduleId)),
+      );
+    },
+  };
+}

package/src/transcription/providers/codex-subscription.ts

@@ -45,6 +45,7 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
       );
       if (!account) {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });
@@ -55,6 +56,7 @@ export function createCodexSubscriptionTranscriptionProvider(input: {
         token = await resolver.getToken();
       } catch {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });

package/src/transcription/providers/openai.ts

@@ -53,6 +53,7 @@ function audioBlob(audio: Uint8Array, mimeType: string): Blob {
 export function responseError(status: number): TranscriptionServiceError {
   if (status === 401 || status === 403) {
     return new TranscriptionServiceError({
+      fallbackSafe: true,
       code: "unavailable",
       message: "Transcription is unavailable.",
     });

package/src/transcription/providers/xai-subscription.ts

@@ -62,6 +62,7 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
       } catch {
         throw new TranscriptionServiceError({
           code: "unavailable",
+          fallbackSafe: true,
           message: "Transcription is unavailable.",
         });
       }
@@ -86,16 +87,28 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
           ...(signal ? { signal } : {}),
         });
       };
+      const tokenForRequest = async (refresh: boolean) => {
+        try {
+          return await (refresh ? auth.context.refresh() : auth.context.getToken());
+        } catch {
+          throw new TranscriptionServiceError({
+            code: "unavailable",
+            message: "Reconnect the SuperGrok account to use transcription.",
+            fallbackSafe: true,
+          });
+        }
+      };
       let response: Response;
       try {
-        let token = await auth.context.getToken();
+        let token = await tokenForRequest(false);
         response = await request(token.accessToken);
-        if (response.status === 401) {
+        if (response.status === 401 || (await isXaiInvalidCredentialResponse(response))) {
           await response.body?.cancel().catch(() => undefined);
-          token = await auth.context.refresh();
+          token = await tokenForRequest(true);
           response = await request(token.accessToken);
         }
       } catch (error) {
+        if (error instanceof TranscriptionServiceError) throw error;
         throw fetchError(error);
       }
       if (!response.ok) throw responseError(response.status);
@@ -108,3 +121,36 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
     },
   };
 }
+
+export async function isXaiInvalidCredentialResponse(response: Response): Promise<boolean> {
+  if (response.status !== 403) return false;
+  const reader = response.clone().body?.getReader();
+  if (!reader) return false;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 16_384) return false;
+      chunks.push(chunk.value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const body = JSON.parse(new TextDecoder().decode(bytes));
+    return (
+      typeof body?.error === "string" &&
+      body.error.includes("[WKE=unauthenticated:bad-credentials]")
+    );
+  } catch {
+    return false;
+  } finally {
+    void reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/src/transcription/segmenter.ts

@@ -220,8 +220,14 @@ function extensionForMimeType(mimeType: string): string {
 }
 
 async function commandSucceeds(command: string, args: string[]): Promise<boolean> {
-  const result = await runCommand(command, args);
-  return !result.spawnError && result.exitCode === 0;
+  try {
+    const result = await runCommand(command, args);
+    return !result.spawnError && result.exitCode === 0;
+  } catch {
+    // Some runtimes throw during spawn instead of emitting an error event.
+    // An unavailable optional audio tool must not prevent client startup.
+    return false;
+  }
 }
 
 async function runCommand(

package/src/transcription/service.ts

@@ -74,7 +74,7 @@ export function createTranscriptionService(input: {
       );
     },
     async selectProvider(context) {
-      return (await firstAvailable(providers, context))?.id ?? null;
+      return (await firstAvailable(orderedProviders(providers, context), context))?.id ?? null;
     },
     async transcribe(request) {
       const mimeType = normalizeMimeType(request.mimeType);
@@ -106,12 +106,10 @@ export function createTranscriptionService(input: {
             workspaceId: request.workspaceId,
             subjectId: request.subjectId,
           })
-        : await firstAvailable(providers, {
-            workspaceId: request.workspaceId,
-            subjectId: request.subjectId,
-          });
+        : await firstAvailable(orderedProviders(providers, request), request);
       if (!provider) {
         throw new TranscriptionServiceError({
+          fallbackSafe: true,
           code: "unavailable",
           message: "Transcription is unavailable.",
         });
@@ -164,6 +162,23 @@ export function createTranscriptionService(input: {
             retryable: true,
           });
         }
+        if (
+          error instanceof TranscriptionServiceError &&
+          error.fallbackSafe &&
+          !request.providerId &&
+          request.fallbackEnabled !== false &&
+          !request.signal?.aborted
+        ) {
+          const excludedProviders = [...(request.excludedProviders ?? []), provider.id];
+          if (
+            await firstAvailable(
+              orderedProviders(providers, { ...request, excludedProviders }),
+              request,
+            )
+          ) {
+            return await this.transcribe({ ...request, excludedProviders });
+          }
+        }
         throw error;
       } finally {
         deadline.dispose();
@@ -217,12 +232,34 @@ function createProviderRequestDeadline(
   };
 }
 
+export function orderedProviders(
+  providers: readonly TranscriptionProvider[],
+  context: TranscriptionAvailabilityContext,
+): TranscriptionProvider[] {
+  const preferred = providers.filter((provider) => provider.id === context.preferredProvider);
+  const ordered = context.preferredProvider
+    ? context.fallbackEnabled === false
+      ? preferred
+      : [...preferred, ...providers.filter((provider) => provider.id !== context.preferredProvider)]
+    : context.fallbackEnabled === false
+      ? providers.slice(0, 1)
+      : [...providers];
+  const remaining = context.afterProvider
+    ? ordered.slice(ordered.findIndex((provider) => provider.id === context.afterProvider) + 1)
+    : ordered;
+  return remaining.filter((provider) => !context.excludedProviders?.includes(provider.id));
+}
+
 async function firstAvailable(
   providers: readonly TranscriptionProvider[],
   context: TranscriptionAvailabilityContext,
 ) {
   for (const provider of providers) {
-    if (await provider.available(context)) return provider;
+    try {
+      if (await provider.available(context)) return provider;
+    } catch {
+      /* No audio sent; another configured provider may be ready. */
+    }
   }
   return null;
 }