@agent-native/core 0.134.1 → 0.135.1

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -17,6 +17,7 @@ import {
   readAppState,
   writeAppState,
 } from "@agent-native/core/application-state";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { runWithRequestContext } from "@agent-native/core/server";
 import { track } from "@agent-native/core/tracking";
 import { normalizeChunkUploadNumber } from "@shared/recording-core.js";
@@ -34,6 +35,7 @@ import {
 } from "h3";
 
 import finalizeRecording from "../../../../../actions/finalize-recording.js";
+import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
 import { getDb, schema } from "../../../../db/index.js";
 import { debugLog } from "../../../../lib/debug.js";
 import {
@@ -45,6 +47,7 @@ import {
   ownerEmailMatches,
 } from "../../../../lib/recordings.js";
 import {
+  deleteResumableSession,
   getResumableSession,
   setResumableSession,
   type StoredResumableSession,
@@ -166,6 +169,26 @@ export default defineEventHandler(async (event: H3Event) => {
   }
 
   const query = getQuery(event);
+  const attemptIdValue = Array.isArray(query.attemptId)
+    ? query.attemptId[0]
+    : query.attemptId;
+  const attemptId =
+    typeof attemptIdValue === "string" &&
+    attemptIdValue.length > 0 &&
+    attemptIdValue.length <= 128 &&
+    !/[\r\n]/.test(attemptIdValue)
+      ? attemptIdValue
+      : null;
+  const uploadGenerationIdValue = Array.isArray(query.uploadGenerationId)
+    ? query.uploadGenerationId[0]
+    : query.uploadGenerationId;
+  const uploadGenerationId =
+    typeof uploadGenerationIdValue === "string" &&
+    uploadGenerationIdValue.length > 0 &&
+    uploadGenerationIdValue.length <= 128 &&
+    !/[\r\n]/.test(uploadGenerationIdValue)
+      ? uploadGenerationIdValue
+      : null;
   const index = Number(query.index ?? 0);
   const total = Number(query.total ?? 0);
   const isFinal = query.isFinal === "1" || query.isFinal === "true";
@@ -188,7 +211,12 @@ export default defineEventHandler(async (event: H3Event) => {
     mimeType,
   });
 
-  if (!Number.isFinite(index) || !Number.isInteger(index) || index < 0) {
+  if (
+    !Number.isFinite(index) ||
+    !Number.isInteger(index) ||
+    index < 0 ||
+    index > 999_999
+  ) {
     throw createError({ statusCode: 400, message: "Invalid chunk index" });
   }
 
@@ -210,6 +238,23 @@ export default defineEventHandler(async (event: H3Event) => {
   }
   debugLog("[chunk] resolved owner:", ownerEmail);
 
+  if (
+    attemptId !== null &&
+    !(await isFeatureFlagEnabled(UPLOAD_RETRY_RESUME_FLAG, {
+      userEmail: ownerEmail,
+      userKey: ownerEmail,
+      orgId,
+    }))
+  ) {
+    setResponseStatus(event, 409);
+    return {
+      ok: false,
+      error: "Resumable upload retry is disabled.",
+      restartRequired: true,
+      recoveryEnabled: false,
+    };
+  }
+
   return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
     const db = getDb();
 
@@ -219,6 +264,7 @@ export default defineEventHandler(async (event: H3Event) => {
       .select({
         id: schema.recordings.id,
         status: schema.recordings.status,
+        uploadGenerationId: schema.recordings.uploadGenerationId,
       })
       .from(schema.recordings)
       .where(
@@ -252,13 +298,31 @@ export default defineEventHandler(async (event: H3Event) => {
     // The first renewal admits the request. Later renewals immediately before
     // every durable write/finalization boundary close the body-read/provider
     // gap where /abort can otherwise commit while this request is in flight.
+    if ((existing.uploadGenerationId ?? null) !== uploadGenerationId) {
+      setResponseStatus(event, 409);
+      return {
+        ok: false,
+        error: "A newer upload generation is already active.",
+        staleAttempt: true,
+      };
+    }
     const lease = await renewUploadLease(recordingId, {
+      attemptId,
+      generationId: uploadGenerationId,
       uploadProgress:
         total > 0
           ? Math.min(100, Math.round(((index + 1) / total) * 100))
           : undefined,
     });
     if (!lease.held) {
+      if (lease.staleAttempt) {
+        setResponseStatus(event, 409);
+        return {
+          ok: false,
+          error: "A newer upload retry is already active.",
+          staleAttempt: true,
+        };
+      }
       if (lease.status === "ready") {
         const readyState = await readAppState(
           `recording-upload-${recordingId}`,
@@ -273,7 +337,11 @@ export default defineEventHandler(async (event: H3Event) => {
           sourceSizeBytes: stateNumber(readyState, "sourceSizeBytes"),
         };
       }
-      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+      await deleteRecordingChunks(
+        ownerEmail,
+        recordingId,
+        uploadGenerationId,
+      ).catch((err) => {
         console.warn("[chunk] failed upload chunk cleanup failed:", {
           recordingId,
           err: err instanceof Error ? err.message : String(err),
@@ -285,9 +353,16 @@ export default defineEventHandler(async (event: H3Event) => {
     }
 
     const rejectIfLeaseLost = async () => {
-      const current = await renewUploadLease(recordingId);
+      const current = await renewUploadLease(recordingId, {
+        attemptId,
+        generationId: uploadGenerationId,
+      });
       if (current.held) return null;
-      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+      await deleteRecordingChunks(
+        ownerEmail,
+        recordingId,
+        uploadGenerationId,
+      ).catch((err) => {
         console.warn("[chunk] failed upload chunk cleanup failed:", {
           recordingId,
           err: err instanceof Error ? err.message : String(err),
@@ -308,7 +383,10 @@ export default defineEventHandler(async (event: H3Event) => {
     }
 
     // Resumable streaming path — forward chunks directly to the provider.
-    const resumableSession = await getResumableSession(recordingId);
+    const resumableSession = await getResumableSession(
+      recordingId,
+      uploadGenerationId,
+    );
     if (resumableSession && isStreamingUploadDisabled()) {
       console.warn(
         `[chunk] streaming uploads are disabled, but preserving existing resumable session for in-flight recording: ${recordingId}`,
@@ -324,6 +402,8 @@ export default defineEventHandler(async (event: H3Event) => {
         mimeType,
         query,
         ownerEmail,
+        attemptId,
+        uploadGenerationId,
       );
     }
 
@@ -418,7 +498,11 @@ export default defineEventHandler(async (event: H3Event) => {
         maxBytes: MAX_RECORDING_UPLOAD_BYTES,
         updatedAt: now,
       });
-      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+      await deleteRecordingChunks(
+        ownerEmail,
+        recordingId,
+        uploadGenerationId,
+      ).catch((err) => {
         console.warn("[chunk] oversized upload chunk cleanup failed:", {
           recordingId,
           err: err instanceof Error ? err.message : String(err),
@@ -439,12 +523,13 @@ export default defineEventHandler(async (event: H3Event) => {
       // Pad index to 6 digits so string-sort order matches numeric order if the
       // finalize path ever sorts lexically. (finalize also parses back to a number.)
       const paddedIndex = String(index).padStart(6, "0");
-      const chunkKey = `recording-chunks-${recordingId}-${paddedIndex}`;
+      const chunkKey = `recording-chunks-${recordingId}${uploadGenerationId ? `-${uploadGenerationId}` : ""}-${paddedIndex}`;
       const previousChunk = await readAppState(chunkKey);
       const previousBytes = stateNumber(previousChunk, "bytes") ?? 0;
       const persistedBytesBefore = await sumRecordingChunkBytes(
         ownerEmail,
         recordingId,
+        uploadGenerationId,
       );
       const nextBytes =
         Math.max(0, persistedBytesBefore - previousBytes) + bytes.byteLength;
@@ -463,7 +548,11 @@ export default defineEventHandler(async (event: H3Event) => {
         data: toBase64(bytes),
         createdAt: new Date().toISOString(),
       });
-      bytesReceived = await sumRecordingChunkBytes(ownerEmail, recordingId);
+      bytesReceived = await sumRecordingChunkBytes(
+        ownerEmail,
+        recordingId,
+        uploadGenerationId,
+      );
       if (bytesReceived > MAX_RECORDING_UPLOAD_BYTES) {
         return failRecordingTooLarge(bytesReceived);
       }
@@ -487,6 +576,7 @@ export default defineEventHandler(async (event: H3Event) => {
       if (leaseFailure) return leaseFailure;
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
+        uploadGenerationId,
         status: isFinal ? "processing" : "uploading",
         progress,
         chunksReceived,
@@ -508,6 +598,7 @@ export default defineEventHandler(async (event: H3Event) => {
       if (leaseFailure) return leaseFailure;
       await writeAppState(`recording-upload-${recordingId}`, {
         recordingId,
+        uploadGenerationId,
         status: isFinal ? "processing" : "uploading",
         chunksReceived: Math.max(
           stateNumber(uploadState, "chunksReceived") ?? 0,
@@ -532,7 +623,11 @@ export default defineEventHandler(async (event: H3Event) => {
     if (isFinal) {
       const leaseFailure = await rejectIfLeaseLost();
       if (leaseFailure) return leaseFailure;
-      bytesReceived = await sumRecordingChunkBytes(ownerEmail, recordingId);
+      bytesReceived = await sumRecordingChunkBytes(
+        ownerEmail,
+        recordingId,
+        uploadGenerationId,
+      );
       if (bytesReceived > MAX_RECORDING_UPLOAD_BYTES) {
         return failRecordingTooLarge(bytesReceived);
       }
@@ -541,7 +636,7 @@ export default defineEventHandler(async (event: H3Event) => {
       debugLog("[chunk] isFinal — invoking finalize", { recordingId });
       try {
         const result = await finalizeRecording.run(
-          buildFinalizeArgs(recordingId, mimeType, query),
+          buildFinalizeArgs(recordingId, mimeType, query, uploadGenerationId),
         );
         debugLog("[chunk] finalize ok", {
           recordingId,
@@ -713,6 +808,7 @@ function buildFinalizeArgs(
   recordingId: string,
   mimeType: string,
   query: Record<string, unknown>,
+  uploadGenerationId: string | null,
 ) {
   const queryBoolean = (value: unknown): boolean | undefined => {
     if (value === undefined) return undefined;
@@ -729,6 +825,7 @@ function buildFinalizeArgs(
     hasCamera: queryBoolean(query.hasCamera),
     locallyTranscoded: queryBoolean(query.locallyTranscoded),
     mimeType,
+    ...(uploadGenerationId ? { uploadGenerationId } : {}),
   };
 }
 
@@ -743,6 +840,8 @@ async function handleResumableChunk(
   mimeType: string,
   query: Record<string, unknown>,
   ownerEmail: string,
+  attemptId: string | null,
+  uploadGenerationId: string | null,
 ) {
   const uploadProvider = await resolveResumableUploadProvider(
     session.providerId,
@@ -771,7 +870,10 @@ async function handleResumableChunk(
         error: "Cannot finalize an empty resumable upload",
       };
     }
-    const lease = await renewUploadLease(recordingId);
+    const lease = await renewUploadLease(recordingId, {
+      attemptId,
+      generationId: uploadGenerationId,
+    });
     if (!lease.held) {
       setResponseStatus(event, 409);
       return {
@@ -798,7 +900,10 @@ async function handleResumableChunk(
       };
     }
     if (closeRes.updatedMeta) {
-      const postCloseLease = await renewUploadLease(recordingId);
+      const postCloseLease = await renewUploadLease(recordingId, {
+        attemptId,
+        generationId: uploadGenerationId,
+      });
       if (!postCloseLease.held) {
         setResponseStatus(event, 409);
         return {
@@ -808,10 +913,14 @@ async function handleResumableChunk(
             "Recording upload has already failed.",
         };
       }
-      await setResumableSession(recordingId, {
-        ...session,
-        meta: { ...session.meta, ...closeRes.updatedMeta },
-      });
+      await setResumableSession(
+        recordingId,
+        {
+          ...session,
+          meta: { ...session.meta, ...closeRes.updatedMeta },
+        },
+        uploadGenerationId,
+      );
     }
   } else {
     // Idempotent replay guard: a client retry (after a lost response) can
@@ -835,7 +944,10 @@ async function handleResumableChunk(
         };
       }
     } else {
-      const lease = await renewUploadLease(recordingId);
+      const lease = await renewUploadLease(recordingId, {
+        attemptId,
+        generationId: uploadGenerationId,
+      });
       if (!lease.held) {
         setResponseStatus(event, 409);
         return {
@@ -866,14 +978,25 @@ async function handleResumableChunk(
         ? putResult.ok && putResult.status !== 308
         : putResult.ok;
       if (!resultOk) {
-        setResponseStatus(event, 502);
+        const restartRequired =
+          putResult.status === 404 || putResult.status === 410;
+        if (restartRequired) {
+          await deleteResumableSession(recordingId, uploadGenerationId).catch(
+            () => {},
+          );
+        }
+        setResponseStatus(event, restartRequired ? 409 : 502);
         return {
           ok: false,
           error: `Chunk upload failed (${putResult.status})`,
+          ...(restartRequired ? { restartRequired: true } : {}),
         };
       }
 
-      const postUploadLease = await renewUploadLease(recordingId);
+      const postUploadLease = await renewUploadLease(recordingId, {
+        attemptId,
+        generationId: uploadGenerationId,
+      });
       if (!postUploadLease.held) {
         setResponseStatus(event, 409);
         return {
@@ -883,14 +1006,18 @@ async function handleResumableChunk(
             "Recording upload has already failed.",
         };
       }
-      await setResumableSession(recordingId, {
-        ...session,
-        ...(putResult.updatedMeta
-          ? { meta: { ...session.meta, ...putResult.updatedMeta } }
-          : {}),
-        bytesUploaded: start + bytes.byteLength,
-        lastCommittedIndex: index,
-      });
+      await setResumableSession(
+        recordingId,
+        {
+          ...session,
+          ...(putResult.updatedMeta
+            ? { meta: { ...session.meta, ...putResult.updatedMeta } }
+            : {}),
+          bytesUploaded: start + bytes.byteLength,
+          lastCommittedIndex: index,
+        },
+        uploadGenerationId,
+      );
       finalizedSourceSizeBytes = start + bytes.byteLength;
 
       if (!isFinal) {
@@ -901,7 +1028,10 @@ async function handleResumableChunk(
 
   // isFinal — delegate to finalize-recording, which reads the resumable
   // session and calls provider.resumable.completeSession.
-  const finalLease = await renewUploadLease(recordingId);
+  const finalLease = await renewUploadLease(recordingId, {
+    attemptId,
+    generationId: uploadGenerationId,
+  });
   if (!finalLease.held) {
     setResponseStatus(event, 409);
     return {
@@ -911,7 +1041,7 @@ async function handleResumableChunk(
   }
   try {
     const result = await finalizeRecording.run(
-      buildFinalizeArgs(recordingId, mimeType, query),
+      buildFinalizeArgs(recordingId, mimeType, query, uploadGenerationId),
     );
     if ((result as any)?.status === "failed") {
       setResponseStatus(event, 409);

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/interrupt.post.ts

@@ -0,0 +1,197 @@
+// guard:allow-api-route — Upload transport interruption preserves resumable state for desktop recovery.
+
+/**
+ * Mark a live upload as interrupted without discarding its provider session or
+ * buffered chunks. Explicit cancellation continues to use /abort.
+ *
+ * Route: POST /api/uploads/:recordingId/interrupt
+ */
+
+import {
+  compareAndSetAppState,
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+import { runWithRequestContext } from "@agent-native/core/server";
+import { and, eq, isNull } from "drizzle-orm";
+import {
+  defineEventHandler,
+  getRouterParam,
+  readBody,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
+import { getDb, schema } from "../../../../db/index.js";
+import {
+  getEventOwnerContext,
+  ownerEmailMatches,
+} from "../../../../lib/recordings.js";
+import {
+  isRetryableUploadInterruption,
+  RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+} from "../../../../lib/upload-interruption.js";
+import abortUpload from "./abort.post.js";
+
+export default defineEventHandler(async (event: H3Event) => {
+  const recordingId = getRouterParam(event, "recordingId");
+  if (!recordingId) {
+    setResponseStatus(event, 400);
+    return { error: "Missing recordingId" };
+  }
+
+  const { userEmail: ownerEmail, orgId } = await getEventOwnerContext(event);
+  if (
+    !(await isFeatureFlagEnabled(UPLOAD_RETRY_RESUME_FLAG, {
+      userEmail: ownerEmail,
+      userKey: ownerEmail,
+      orgId,
+    }))
+  ) {
+    return abortUpload(event);
+  }
+  const body = (await readBody(event).catch(() => null)) as {
+    detail?: unknown;
+    attemptId?: unknown;
+    uploadGenerationId?: unknown;
+  } | null;
+  const attemptId =
+    typeof body?.attemptId === "string" &&
+    body.attemptId.length > 0 &&
+    body.attemptId.length <= 128
+      ? body.attemptId
+      : null;
+  const interruptionDetail =
+    typeof body?.detail === "string" && body.detail.trim()
+      ? body.detail.trim().slice(0, 1000)
+      : null;
+  const uploadGenerationId =
+    typeof body?.uploadGenerationId === "string" &&
+    body.uploadGenerationId.length > 0 &&
+    body.uploadGenerationId.length <= 128
+      ? body.uploadGenerationId
+      : null;
+
+  return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
+    const db = getDb();
+    const [existing] = await db
+      .select({
+        id: schema.recordings.id,
+        status: schema.recordings.status,
+        failureReason: schema.recordings.failureReason,
+        videoUrl: schema.recordings.videoUrl,
+        uploadAttemptId: schema.recordings.uploadAttemptId,
+        uploadGenerationId: schema.recordings.uploadGenerationId,
+      })
+      .from(schema.recordings)
+      .where(
+        and(
+          eq(schema.recordings.id, recordingId),
+          ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+        ),
+      );
+
+    if (!existing) {
+      setResponseStatus(event, 404);
+      return { error: "Recording not found" };
+    }
+    if (existing.status === "ready" || existing.status === "processing") {
+      return {
+        ok: true,
+        recordingId,
+        status: existing.status,
+        alreadyAccepted: true,
+      };
+    }
+    if ((existing.uploadAttemptId ?? null) !== attemptId) {
+      setResponseStatus(event, 409);
+      return {
+        error: "A newer upload retry is already active.",
+        staleAttempt: true,
+      };
+    }
+    if ((existing.uploadGenerationId ?? null) !== uploadGenerationId) {
+      setResponseStatus(event, 409);
+      return {
+        error: "A newer upload generation is already active.",
+        staleAttempt: true,
+      };
+    }
+    const alreadyInterrupted =
+      existing.status === "failed" &&
+      isRetryableUploadInterruption(existing.failureReason);
+    if (existing.status !== "uploading" && !alreadyInterrupted) {
+      setResponseStatus(event, 409);
+      return { error: "Recording upload is no longer active" };
+    }
+
+    const uploadStateKey = `recording-upload-${recordingId}`;
+    const uploadStateRaw = await readAppState(uploadStateKey);
+    const uploadState = uploadStateRaw ?? {};
+    const interruptedAt = new Date().toISOString();
+    if (!alreadyInterrupted) {
+      const interrupted = await db
+        .update(schema.recordings)
+        .set({
+          status: "failed",
+          failureReason: RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+          updatedAt: interruptedAt,
+        })
+        .where(
+          and(
+            eq(schema.recordings.id, recordingId),
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            eq(schema.recordings.status, "uploading"),
+            attemptId === null
+              ? isNull(schema.recordings.uploadAttemptId)
+              : eq(schema.recordings.uploadAttemptId, attemptId),
+            uploadGenerationId === null
+              ? isNull(schema.recordings.uploadGenerationId)
+              : eq(schema.recordings.uploadGenerationId, uploadGenerationId),
+          ),
+        )
+        .returning({ id: schema.recordings.id });
+
+      if (interrupted.length !== 1) {
+        setResponseStatus(event, 409);
+        return { error: "Recording upload changed while it was interrupted" };
+      }
+    }
+
+    const uploadStateUpdated = await compareAndSetAppState(
+      uploadStateKey,
+      uploadStateRaw,
+      {
+        ...uploadState,
+        recordingId,
+        status: "failed",
+        failureReason: RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+        retryableInterruption: true,
+        uploadAttemptId: attemptId,
+        uploadGenerationId,
+        ...(interruptionDetail ? { interruptionDetail } : {}),
+        updatedAt: interruptedAt,
+      },
+    );
+    if (!uploadStateUpdated) {
+      console.info(
+        `[upload-interrupt] upload state changed after interruption claim; preserving replacement state for ${recordingId}`,
+      );
+    }
+    await writeAppState("refresh-signal", { ts: Date.now() });
+
+    console.info("[upload-interrupt] resumable state preserved", {
+      recordingId,
+      hasInterruptionDetail: interruptionDetail !== null,
+    });
+    return {
+      ok: true,
+      recordingId,
+      status: "failed",
+      resumable: true,
+      ...(alreadyInterrupted ? { alreadyInterrupted: true } : {}),
+    };
+  });
+});