Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

perf(web): claim and commit a desktop recording in one workflow step

Richie McIlroy94774cc91171
diff --git a/apps/web/__tests__/unit/desktop-recording-jobs.test.ts b/apps/web/__tests__/unit/desktop-recording-jobs.test.ts
index 42f44244e..952bda7c1 100644
--- a/apps/web/__tests__/unit/desktop-recording-jobs.test.ts
+++ b/apps/web/__tests__/unit/desktop-recording-jobs.test.ts
@@ -302,6 +302,78 @@ describe("durable recording job ownership", () => {
expect(rows.jobs?.[0]?.attemptCount).toBe(1);
});
+ it("returns a live attempt to the caller that claimed it under the same id", async () => {
+ const { job } = await ensureSegmentProcessingJob({ videoId, userId });
+ const first = await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ });
+ expect(first).toMatchObject({ attemptId: "step-attempt", attemptCount: 1 });
+ const output = {
+ kind: "desktop-recording-source-commit",
+ revision: 3,
+ };
+ Object.assign(rows.jobs?.[0] ?? {}, { output });
+ const resumed = await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ });
+ expect(resumed).toMatchObject({
+ attemptId: "step-attempt",
+ attemptCount: 1,
+ output,
+ });
+ expect(
+ await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "other-step",
+ }),
+ ).toBeNull();
+ expect(
+ await claimProcessingAttempt({ videoId, generation: job.generation }),
+ ).toBeNull();
+ expect(rows.jobs?.[0]?.attemptCount).toBe(1);
+ });
+
+ it("claims a fresh id when the caller's own attempt has expired", async () => {
+ const { job } = await ensureSegmentProcessingJob({ videoId, userId });
+ await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ });
+ vi.setSystemTime(new Date(now.getTime() + 6 * 60_000));
+ const next = await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ });
+ expect(next?.attemptId).toBeTruthy();
+ expect(next?.attemptId).not.toBe("step-attempt");
+ expect(next?.attemptCount).toBe(2);
+ });
+
+ it("does not resume a finished attempt under its old id", async () => {
+ const { job } = await ensureSegmentProcessingJob({ videoId, userId });
+ const first = await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ });
+ if (!first) throw new Error("Fixture attempt was not claimed");
+ Object.assign(rows.jobs?.[0] ?? {}, { state: "verified" });
+ expect(
+ await claimProcessingAttempt({
+ videoId,
+ generation: job.generation,
+ attemptId: "step-attempt",
+ }),
+ ).toBeNull();
+ });
+
it("keeps physical worker leases private and clears their checkpoint for a new attempt", async () => {
const first = await createAttempt();
expect(await persistCommittedSource(first, source)).toBe(true);
diff --git a/apps/web/__tests__/unit/finalize-desktop-recording.test.ts b/apps/web/__tests__/unit/finalize-desktop-recording.test.ts
index e7c420167..0b32b199a 100644
--- a/apps/web/__tests__/unit/finalize-desktop-recording.test.ts
+++ b/apps/web/__tests__/unit/finalize-desktop-recording.test.ts
@@ -35,6 +35,8 @@ const mocks = vi.hoisted(() => ({
reserveBudget: vi.fn(),
storage: vi.fn(),
multipartCreate: vi.fn(),
+ // Plain calls stand in for a step's last try; retry tests lower the attempt.
+ stepMetadata: vi.fn(() => ({ stepId: "step_test", attempt: 4 })),
}));
vi.mock("@/lib/media-processing-budget", () => ({
reserveMediaProcessingBudget: mocks.reserveBudget,
@@ -56,7 +58,10 @@ vi.mock("@cap/database", () => ({
vi.mock("@cap/database/schema", () => ({ users: {}, videos: {} }));
vi.mock("drizzle-orm", () => ({ and: vi.fn(), eq: vi.fn() }));
vi.mock("@cap/env", () => ({ serverEnv: mocks.env }));
-vi.mock("workflow", () => ({ sleep: mocks.sleep }));
+vi.mock("workflow", () => ({
+ sleep: mocks.sleep,
+ getStepMetadata: () => mocks.stepMetadata(),
+}));
vi.mock("@/lib/desktop-recording-jobs", () => ({
getProcessingState: mocks.state,
claimProcessingAttempt: mocks.claim,
@@ -105,6 +110,7 @@ vi.mock("@cap/web-backend/src/Storage/index", async () => {
});
import {
+ acquireAndStartDesktopRecordingAttempt,
commitAndStartDesktopRecordingAttempt,
commitDesktopRecordingAttempt,
finalizeDesktopRecordingWorkflow,
@@ -164,6 +170,7 @@ function withCurrent(update: Partial<DesktopRecordingJob>) {
}
beforeEach(() => {
+ mocks.stepMetadata.mockReturnValue({ stepId: "step_test", attempt: 4 });
mocks.reserveBudget.mockResolvedValue(100_000_000);
mocks.storage.mockImplementation(() => storageAccess("test"));
mocks.multipartCreate.mockImplementation(() =>
@@ -1171,6 +1178,148 @@ describe("source commitment and media request compatibility", () => {
});
});
+describe("first attempt step", () => {
+ it("claims, commits and dispatches the first attempt in one step", async () => {
+ withCurrent({
+ state: "committing",
+ source: null,
+ leaseExpiresAt: null,
+ attemptId: null,
+ });
+ const result = await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ });
+ expect(result).toMatchObject({
+ status: "attempt",
+ started: { committed: "ready", dispatched: true, started: "remote-job" },
+ });
+ expect(mocks.claim).toHaveBeenCalledWith(
+ expect.objectContaining({
+ attemptId: expect.stringMatching(
+ /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+ ),
+ }),
+ );
+ expect(mocks.fetch).toHaveBeenCalledOnce();
+ });
+
+ it("derives the same attempt id when the step is retried", async () => {
+ withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ });
+ const first = mocks.claim.mock.calls[0]?.[0].attemptId;
+ withCurrent({ attemptId: first });
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ });
+ expect(mocks.claim.mock.calls[1]?.[0].attemptId).toBe(first);
+ });
+
+ it("resumes its own live attempt instead of reporting it as already processing", async () => {
+ withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ });
+ const own = mocks.claim.mock.calls[0]?.[0].attemptId;
+ withCurrent({
+ attemptId: own,
+ leaseExpiresAt: new Date(Date.now() + 60_000),
+ nextRetryAt: new Date(Date.now() + 60_000),
+ });
+ mocks.claim.mockImplementationOnce(async () => current);
+ const retried = await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ });
+ expect(retried.status).toBe("attempt");
+ withCurrent({ attemptId: "someone-else" });
+ expect(
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ }),
+ ).toEqual({ status: "already-processing" });
+ });
+
+ it("rethrows an early failure so the step retry resumes the same attempt", async () => {
+ withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
+ mocks.stepMetadata.mockReturnValue({ stepId: "step_retry", attempt: 1 });
+ mocks.commitSource.mockRejectedValueOnce(new Error("storage blip"));
+ await expect(
+ acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ }),
+ ).rejects.toThrow("storage blip");
+ const claimed = mocks.claim.mock.calls[0]?.[0].attemptId;
+ withCurrent({ attemptId: claimed });
+ mocks.claim.mockImplementationOnce(async () => current);
+ mocks.stepMetadata.mockReturnValue({ stepId: "step_retry", attempt: 2 });
+ expect(
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ }),
+ ).toMatchObject({
+ status: "attempt",
+ attempt: { attemptId: claimed },
+ started: { committed: "ready", dispatched: true, started: "remote-job" },
+ });
+ expect(mocks.claim.mock.calls[1]?.[0].attemptId).toBe(claimed);
+ expect(mocks.fetch).toHaveBeenCalledOnce();
+ });
+
+ it("returns a failure after the last try as data for the workflow to retry", async () => {
+ withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
+ mocks.commitSource.mockRejectedValueOnce(
+ new Error("provider copy unavailable"),
+ );
+ expect(
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ }),
+ ).toMatchObject({
+ status: "attempt",
+ failure: { message: "provider copy unavailable", code: null },
+ });
+ });
+
+ it("blocks a missing source inside the step like the commit step does", async () => {
+ withCurrent({ state: "committing", source: null, leaseExpiresAt: null });
+ mocks.commitSource.mockRejectedValueOnce(
+ Object.assign(new Error("fragment missing"), { code: "source-missing" }),
+ );
+ expect(
+ await acquireAndStartDesktopRecordingAttempt({
+ videoId,
+ userId,
+ generation: fixture.generation,
+ }),
+ ).toMatchObject({
+ status: "attempt",
+ started: { committed: "source-blocked" },
+ });
+ expect(mocks.blocked).toHaveBeenCalledWith(
+ expect.objectContaining({ errorCode: "source-missing" }),
+ );
+ });
+});
+
describe("workflow retry lifetime", () => {
it("finishes normally when publication commits during a failing poll", async () => {
withCurrent({ state: "queued", leaseExpiresAt: null });
diff --git a/apps/web/lib/desktop-recording-jobs.ts b/apps/web/lib/desktop-recording-jobs.ts
index c6c6c876a..2e5568910 100644
--- a/apps/web/lib/desktop-recording-jobs.ts
+++ b/apps/web/lib/desktop-recording-jobs.ts
@@ -434,13 +434,16 @@ async function pauseExhaustedRecording(
.where(eq(videoUploads.videoId, videoId));
}
+// A caller that retries with the same attemptId gets its own live attempt back instead of being locked out by its lease.
export async function claimProcessingAttempt({
videoId,
generation,
+ attemptId,
now = new Date(),
}: {
videoId: Video.VideoId;
generation: string;
+ attemptId?: string;
now?: Date;
}): Promise<DesktopRecordingAttempt | null> {
return db().transaction(async (tx) => {
@@ -456,6 +459,16 @@ export async function claimProcessingAttempt({
.for("update");
if (!row) return null;
const job = parseDesktopRecordingJob(row);
+ const resumed = attemptId !== undefined && job.attemptId === attemptId;
+ if (
+ resumed &&
+ job.leaseExpiresAt &&
+ job.leaseExpiresAt > now &&
+ (job.state === "committing" ||
+ job.state === "queued" ||
+ job.state === "processing")
+ )
+ return { ...job, attemptId };
if (!isDesktopRecordingJobRecoverable(job, now)) return null;
if (job.attemptCount >= MAX_AUTOMATIC_ATTEMPTS) {
await pauseExhaustedRecording(
@@ -469,7 +482,8 @@ export async function claimProcessingAttempt({
const attempt: DesktopRecordingAttempt = {
...job,
state: job.source ? "processing" : "committing",
- attemptId: randomUUID(),
+ // An expired attempt never comes back under its old id, so a retry claims a fresh one.
+ attemptId: resumed ? randomUUID() : (attemptId ?? randomUUID()),
attemptCount: job.attemptCount + 1,
leaseExpiresAt: new Date(now.getTime() + DESKTOP_RECORDING_LEASE_MS),
remoteJobId: null,
diff --git a/apps/web/workflows/finalize-desktop-recording.ts b/apps/web/workflows/finalize-desktop-recording.ts
index aff95076d..df62f93dd 100644
--- a/apps/web/workflows/finalize-desktop-recording.ts
+++ b/apps/web/workflows/finalize-desktop-recording.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
import { db } from "@cap/database";
import { users, videos } from "@cap/database/schema";
import { serverEnv } from "@cap/env";
@@ -5,7 +6,7 @@ import { Storage } from "@cap/web-backend/src/Storage/index";
import { type User, Video } from "@cap/web-domain";
import { and, eq } from "drizzle-orm";
import { Option } from "effect";
-import { sleep } from "workflow";
+import { getStepMetadata, sleep } from "workflow";
import { z } from "zod";
import { isAiGenerationEnabledForUser } from "@/lib/ai-generation-entitlement";
import { observeDesktopRecordingJob } from "@/lib/desktop-recording-job-status";
@@ -130,7 +131,7 @@ export async function finalizeDesktopRecordingWorkflow(
processing: for (;;) {
const next = retainedAttempt
? { status: "attempt" as const, attempt: retainedAttempt }
- : await acquireDesktopRecordingAttempt({
+ : await acquireAndStartDesktopRecordingAttempt({
...payload,
generation,
});
@@ -145,7 +146,12 @@ export async function finalizeDesktopRecordingWorkflow(
}
const attempt = next.attempt;
try {
- let committed = await commitAndStartDesktopRecordingAttempt(attempt);
+ if ("failure" in next && next.failure)
+ throw new AttemptStepFailure(next.failure.message, next.failure.code);
+ let committed =
+ "started" in next && next.started
+ ? next.started
+ : await commitAndStartDesktopRecordingAttempt(attempt);
while (committed.committed === "progress") {
committed = await commitAndStartDesktopRecordingAttempt(attempt);
}
@@ -234,15 +240,7 @@ async function ensureWorkflowJob(
return job.generation;
}
-export async function acquireDesktopRecordingAttempt({
- videoId,
- userId,
- generation,
-}: {
- videoId: string;
- userId: User.UserId;
- generation: string;
-}): Promise<
+type AttemptAcquisition =
| { status: "attempt"; attempt: DesktopRecordingAttempt }
| { status: "wait"; until: Date }
| {
@@ -251,23 +249,35 @@ export async function acquireDesktopRecordingAttempt({
| "source-blocked"
| "superseded"
| "already-processing";
- }
-> {
- "use step";
+ };
+async function acquireAttempt({
+ videoId,
+ userId,
+ generation,
+ attemptId,
+}: {
+ videoId: string;
+ userId: User.UserId;
+ generation: string;
+ attemptId?: string;
+}): Promise<AttemptAcquisition> {
const id = Video.VideoId.make(videoId);
const job = await getProcessingState({ videoId: id, generation });
if (!job || job.ownerId !== userId) return { status: "superseded" };
if (job.state === "verified") return { status: "verified" };
if (job.state === "source-blocked") return { status: "source-blocked" };
const now = new Date();
- if (job.leaseExpiresAt && job.leaseExpiresAt > now) {
+ const own = attemptId !== undefined && job.attemptId === attemptId;
+ if (!own && job.leaseExpiresAt && job.leaseExpiresAt > now) {
return { status: "already-processing" };
}
- if (job.nextRetryAt > now) return { status: "wait", until: job.nextRetryAt };
+ if (!own && job.nextRetryAt > now)
+ return { status: "wait", until: job.nextRetryAt };
const attempt = await claimProcessingAttempt({
videoId: id,
generation,
+ attemptId,
now,
});
return attempt
@@ -275,6 +285,67 @@ export async function acquireDesktopRecordingAttempt({
: { status: "already-processing" };
}
+class AttemptStepFailure extends Error {
+ constructor(
+ message: string,
+ readonly code: ReturnType<typeof getSourceErrorCode>,
+ ) {
+ super(message);
+ }
+}
+
+// A retried step keeps its step id, so an attempt id derived from it lets the retry resume its own claim.
+function stepAttemptId(stepId: string) {
+ const digest = createHash("sha256").update(stepId).digest("hex");
+ const variant = (8 + (Number.parseInt(digest.charAt(16), 16) % 4)).toString(
+ 16,
+ );
+ return `${digest.slice(0, 8)}-${digest.slice(8, 12)}-4${digest.slice(13, 16)}-${variant}${digest.slice(17, 20)}-${digest.slice(20, 32)}`;
+}
+
+const ACQUIRE_AND_START_RETRIES = 3;
+
+// Claiming an attempt and committing its source share one step, saving the queue hop between them. A failure
+// is retried as a step, which resumes the same attempt; after the last try it comes back as data so the
+// workflow retries the claimed attempt as the separate commit step would have.
+export async function acquireAndStartDesktopRecordingAttempt(input: {
+ videoId: string;
+ userId: User.UserId;
+ generation: string;
+}): Promise<
+ | Exclude<AttemptAcquisition, { status: "attempt" }>
+ | {
+ status: "attempt";
+ attempt: DesktopRecordingAttempt;
+ started?: Awaited<ReturnType<typeof commitAndStart>>;
+ failure?: {
+ message: string;
+ code: ReturnType<typeof getSourceErrorCode>;
+ };
+ }
+> {
+ "use step";
+
+ const acquired = await acquireAttempt({
+ ...input,
+ attemptId: stepAttemptId(getStepMetadata().stepId),
+ });
+ if (acquired.status !== "attempt") return acquired;
+ try {
+ return { ...acquired, started: await commitAndStart(acquired.attempt) };
+ } catch (error) {
+ if (getStepMetadata().attempt <= ACQUIRE_AND_START_RETRIES) throw error;
+ return {
+ ...acquired,
+ failure: {
+ message: getErrorMessage(error),
+ code: getSourceErrorCode(error),
+ },
+ };
+ }
+}
+acquireAndStartDesktopRecordingAttempt.maxRetries = ACQUIRE_AND_START_RETRIES;
+
export async function commitDesktopRecordingAttempt(
attempt: DesktopRecordingAttempt,
): Promise<SourceCommitResult> {
@@ -287,12 +358,18 @@ export async function commitDesktopRecordingAttempt(
// A slow commit returns without dispatching and the workflow runs startDesktopRecordingJob as its own step.
export async function commitAndStartDesktopRecordingAttempt(
attempt: DesktopRecordingAttempt,
+) {
+ "use step";
+
+ return commitAndStart(attempt);
+}
+
+async function commitAndStart(
+ attempt: DesktopRecordingAttempt,
): Promise<
| { committed: SourceCommitResult; dispatched?: undefined }
| { committed: "ready"; dispatched: true; started: DesktopRecordingDispatch }
> {
- "use step";
-
const startedAt = Date.now();
const committed = await commitDesktopRecordingBatch(attempt);
if (