Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

28.3 KB
Raw Blame
import { createHash } from "node:crypto";
import { db } from "@cap/database";
import { users, videos } from "@cap/database/schema";
import { serverEnv } from "@cap/env";
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 { getStepMetadata, sleep } from "workflow";
import { z } from "zod";
import { isAiGenerationEnabledForUser } from "@/lib/ai-generation-entitlement";
import { observeDesktopRecordingJob } from "@/lib/desktop-recording-job-status";
import {
	attachRemoteJob,
	claimProcessingAttempt,
	type DesktopRecordingAttempt,
	type DesktopRecordingAttemptFence,
	deferWithoutMediaServer,
	ensureSegmentProcessingJob,
	getProcessingState,
	heartbeatAttempt,
	initializeSourceCommitCheckpoint,
	markSourceBlocked,
	persistCommittedSource,
	persistSourceCommitCheckpoint,
	scheduleRetry,
	waitForDesktopRecordingCapacity,
} from "@/lib/desktop-recording-jobs";
import {
	advanceDesktopRecordingSourceCommit,
	buildDesktopRecordingSourceUrls,
	buildPreverifiedRunUrls,
	getDesktopRecordingOutputKey,
} from "@/lib/desktop-recording-source";
import type { RecordingVerification } from "@/lib/desktop-recording-verification";
import { invalidateGoogleDriveStorageQuotaCache } from "@/lib/google-drive-storage-quota-cache";
import {
	MediaProcessingBudgetError,
	reserveMediaProcessingBudget,
} from "@/lib/media-processing-budget";
import { getMediaServerCapacityDelay } from "@/lib/media-server-backpressure";
import { transcribeVideo } from "@/lib/transcribe";
import { decodeStorageVideo } from "@/lib/video-storage";
import { runWorkflowPromise } from "@/lib/workflow-runtime";

interface FinalizeDesktopRecordingWorkflowPayload {
	videoId: string;
	userId: User.UserId;
	generation?: string;
	verification?: RecordingVerification;
}

type WorkflowResult = {
	success: boolean;
	jobId?: string;
	reason?:
		| "source-blocked"
		| "superseded"
		| "already-processing"
		| "media-server-unconfigured";
};

type SourceCommitResult =
	| "progress"
	| "ready"
	| "source-blocked"
	| "superseded";

type DesktopSegmentsOutputUpload =
	| { type: "put"; url: string; ifNoneMatch: "*" }
	| {
			type: "multipart";
			videoId: string;
			generation: string;
			attemptId: string;
			key: string;
			uploadId: string;
			partSize: number;
			signPartUrl: string;
			completeUrl: string;
			abortUrl: string;
			webhookSecret?: string;
	  };

const COMPLETION_POLL_INTERVAL_MS = 15_000;
const ATTEMPT_MAX_DURATION_MS = 6 * 60 * 60 * 1_000;
const PRESIGNED_EXPIRES_SECONDS = 6 * 60 * 60;
const MULTIPART_OUTPUT_PART_SIZE_BYTES = 64 * 1024 * 1024;
// A remux is about as large as its source, so a source that fits in one part is
// uploaded with one PUT instead of sign-part + PUT + complete round trips.
const SINGLE_PUT_OUTPUT_MAX_SOURCE_BYTES = MULTIPART_OUTPUT_PART_SIZE_BYTES;
const SOURCE_COMMIT_BATCH_MAX_CHECKPOINTS = 128;
// A page can still run for its 180 s timeout after this budget is spent, so a step stays far inside
// the function's max duration while a long commit needs a third of the step hops it did at 15 s.
const SOURCE_COMMIT_BATCH_DURATION_MS = 45_000;
const TRANSCRIPTION_QUEUE_MAX_ATTEMPTS = 12;

function getErrorMessage(error: unknown) {
	return error instanceof Error ? error.message : String(error);
}

function getSourceErrorCode(error: unknown) {
	if (error && typeof error === "object" && "code" in error) {
		const code = error.code;
		if (
			code === "source-incomplete" ||
			code === "source-missing" ||
			code === "source-changed" ||
			code === "source-invalid"
		) {
			return code;
		}
	}
	return null;
}

function getMediaServerWebhookUrl(baseUrl: string, path: string) {
	const normalizedBaseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
	return new URL(path.replace(/^\//, ""), normalizedBaseUrl).toString();
}

export async function finalizeDesktopRecordingWorkflow(
	payload: FinalizeDesktopRecordingWorkflowPayload,
): Promise<WorkflowResult> {
	"use workflow";

	// Every step costs a queue hop (~0.7 s in prod), so skip the lookup when the caller already knows the generation.
	const generation = payload.generation ?? (await ensureWorkflowJob(payload));
	let completedJobId: string | undefined;
	let mediaServerUnavailable = false;
	let retainedAttempt: DesktopRecordingAttempt | undefined;
	processing: for (;;) {
		const next = retainedAttempt
			? { status: "attempt" as const, attempt: retainedAttempt }
			: await acquireAndStartDesktopRecordingAttempt({
					...payload,
					generation,
				});
		retainedAttempt = undefined;
		if (next.status === "verified") break;
		if (next.status === "wait") {
			await sleep(next.until);
			continue;
		}
		if (next.status !== "attempt") {
			return { success: false, reason: next.status };
		}
		const attempt = next.attempt;
		try {
			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);
			}
			if (committed.committed !== "ready") {
				return { success: false, reason: committed.committed };
			}
			const started = committed.dispatched
				? committed.started
				: await startDesktopRecordingJob(attempt);
			if (typeof started === "object") {
				if (started.status === "media-server-unconfigured") {
					mediaServerUnavailable = true;
					break;
				}
				if (started.status === "capacity") {
					retainedAttempt = attempt;
					await sleep(started.retryAfterMs);
				}
				continue;
			}
			const deadline = new Date(Date.now() + ATTEMPT_MAX_DURATION_MS);
			const jobId = started;
			for (;;) {
				await sleep(COMPLETION_POLL_INTERVAL_MS);
				const status = await pollDesktopRecordingAttempt({
					videoId: attempt.videoId,
					generation: attempt.generation,
					attemptId: attempt.attemptId,
					jobId,
					deadline,
				});
				if (status === "verified") {
					completedJobId = jobId;
					break processing;
				}
				if (status === "waiting") continue;
				if (status === "retry") break;
				return { success: false, jobId, reason: status };
			}
		} catch (error) {
			const retained = await retryDesktopRecordingAttempt(
				attempt,
				getErrorMessage(error),
				getSourceErrorCode(error),
			);
			if (retained === "verified") break;
			if (retained === "waiting") {
				retainedAttempt = attempt;
				await sleep(COMPLETION_POLL_INTERVAL_MS);
				continue;
			}
			if (retained !== "retry") return { success: false, reason: retained };
		}
	}
	for (let attempt = 0; attempt < TRANSCRIPTION_QUEUE_MAX_ATTEMPTS; attempt++) {
		let queued: boolean;
		try {
			queued = await queueFinalizedRecordingTranscription(
				payload.videoId,
				payload.userId,
			);
		} catch {
			queued = false;
		}
		if (queued) break;
		if (attempt + 1 < TRANSCRIPTION_QUEUE_MAX_ATTEMPTS) {
			await sleep(Math.min(15_000 * 2 ** Math.min(attempt, 5), 300_000));
		}
	}
	return mediaServerUnavailable
		? { success: false, reason: "media-server-unconfigured" }
		: { success: true, ...(completedJobId ? { jobId: completedJobId } : {}) };
}

async function ensureWorkflowJob(
	payload: FinalizeDesktopRecordingWorkflowPayload,
): Promise<string> {
	"use step";

	if (payload.generation) return payload.generation;
	const { job } = await ensureSegmentProcessingJob({
		videoId: Video.VideoId.make(payload.videoId),
		userId: payload.userId,
		verification: payload.verification,
	});
	return job.generation;
}

type AttemptAcquisition =
	| { status: "attempt"; attempt: DesktopRecordingAttempt }
	| { status: "wait"; until: Date }
	| {
			status:
				| "verified"
				| "source-blocked"
				| "superseded"
				| "already-processing";
	  };

async function acquireAttempt({
	videoId,
	userId,
	generation,
	attemptIdFor,
}: {
	videoId: string;
	userId: User.UserId;
	generation: string;
	attemptIdFor?: (attemptCount: number) => 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();
	const live = Boolean(job.leaseExpiresAt && job.leaseExpiresAt > now);
	const ownLive =
		live &&
		attemptIdFor !== undefined &&
		job.attemptId === attemptIdFor(job.attemptCount);
	if (live && !ownLive) return { status: "already-processing" };
	if (!ownLive && job.nextRetryAt > now)
		return { status: "wait", until: job.nextRetryAt };
	const attempt = await claimProcessingAttempt({
		videoId: id,
		generation,
		attemptIdFor,
		now,
	});
	return attempt
		? { status: "attempt", attempt }
		: { 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 ids derived from it and the attempt number let the retry recognise
// its own claim, including a replacement claimed after its earlier attempt's lease expired.
function stepAttemptId(stepId: string, attemptCount: number) {
	const digest = createHash("sha256")
		.update(`${stepId}:${attemptCount}`)
		.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 { stepId } = getStepMetadata();
	const acquired = await acquireAttempt({
		...input,
		attemptIdFor: (attemptCount) => stepAttemptId(stepId, attemptCount),
	});
	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> {
	"use step";

	return commitDesktopRecordingBatch(attempt);
}

// Each step costs a queue hop, so a commit that finishes inside its batch budget dispatches in the same step.
// 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 }
> {
	const startedAt = Date.now();
	const committed = await commitDesktopRecordingBatch(attempt);
	if (
		committed !== "ready" ||
		Date.now() - startedAt >= SOURCE_COMMIT_BATCH_DURATION_MS
	)
		return { committed };
	return {
		committed,
		dispatched: true,
		started: await dispatchDesktopRecordingJob(attempt),
	};
}

async function commitDesktopRecordingBatch(
	attempt: DesktopRecordingAttempt,
): Promise<SourceCommitResult> {
	const startedAt = Date.now();
	for (let index = 0; index < SOURCE_COMMIT_BATCH_MAX_CHECKPOINTS; index++) {
		try {
			const result = await advanceDesktopRecordingAttempt(attempt);
			if (result !== "progress") return result;
		} catch (error) {
			if (index === 0) throw error;
			// Saved pages must not consume the next checkpoint's durable retry budget.
			console.warn("[commitDesktopRecordingAttempt] Resuming saved progress", {
				videoId: attempt.videoId,
				generation: attempt.generation,
				attemptId: attempt.attemptId,
				error: getErrorMessage(error),
			});
			return "progress";
		}
		if (Date.now() - startedAt >= SOURCE_COMMIT_BATCH_DURATION_MS)
			return "progress";
	}
	return "progress";
}

async function advanceDesktopRecordingAttempt(
	attempt: DesktopRecordingAttempt,
): Promise<SourceCommitResult> {
	const startedAt = performance.now();
	const current = await getProcessingState(attempt);
	if (!current || current.attemptId !== attempt.attemptId) return "superseded";
	if (current.source) return "ready";
	const [video] = await db()
		.select()
		.from(videos)
		.where(
			and(eq(videos.id, attempt.videoId), eq(videos.ownerId, attempt.ownerId)),
		);
	if (!video) return "superseded";
	try {
		const checkpoint = await initializeSourceCommitCheckpoint(attempt);
		if (!checkpoint) return "superseded";
		const loadedAt = performance.now();
		let heartbeatMs = 0;
		const result = await advanceDesktopRecordingSourceCommit(
			video,
			checkpoint,
			current.verification ?? undefined,
			async () => {
				const heartbeatAt = performance.now();
				const alive = await heartbeatAttempt(attempt);
				heartbeatMs += performance.now() - heartbeatAt;
				if (!alive) {
					throw new Error("Recording source commit lease was superseded");
				}
			},
		);
		const advancedAt = performance.now();
		const outcome =
			"checkpoint" in result
				? (await persistSourceCommitCheckpoint(attempt, result.checkpoint))
					? "progress"
					: "superseded"
				: (await persistCommittedSource(attempt, result.source))
					? "ready"
					: "superseded";
		console.info(
			JSON.stringify({
				event: "desktop_source_commit_advance",
				videoId: attempt.videoId,
				attemptId: attempt.attemptId,
				phase: checkpoint.phase,
				next: "checkpoint" in result ? result.checkpoint.phase : "committed",
				outcome,
				loadMs: Math.round(loadedAt - startedAt),
				heartbeatMs: Math.round(heartbeatMs),
				advanceMs: Math.round(advancedAt - loadedAt),
				persistMs: Math.round(performance.now() - advancedAt),
			}),
		);
		return outcome;
	} catch (error) {
		const code = getSourceErrorCode(error);
		if (!code) throw error;
		const marked = await markSourceBlocked({
			...attempt,
			errorCode: code,
			errorMessage: getErrorMessage(error),
		});
		return marked ? "source-blocked" : "superseded";
	}
}

async function completeWithoutMediaServerIfUnavailable(
	attempt: DesktopRecordingAttempt,
): Promise<boolean> {
	if (serverEnv().MEDIA_SERVER_URL) return false;
	const deferred = await deferWithoutMediaServer(attempt);
	if (deferred) {
		const [video] = await db()
			.select({ storageIntegrationId: videos.storageIntegrationId })
			.from(videos)
			.where(eq(videos.id, attempt.videoId));
		await invalidateGoogleDriveStorageQuotaCache(video?.storageIntegrationId);
	}
	return true;
}

async function buildDesktopSegmentsOutput({
	video,
	attempt,
	sourceBytes,
}: {
	video: typeof videos.$inferSelect;
	attempt: DesktopRecordingAttemptFence;
	sourceBytes: number;
}) {
	const [bucket, customBucket] = await Storage.getAccessForVideo(
		decodeStorageVideo(video),
	).pipe(runWorkflowPromise);
	const outputKey = getDesktopRecordingOutputKey(
		video.ownerId,
		video.id,
		attempt.generation,
		attempt.attemptId,
	);
	const candidateDirectory = outputKey.slice(0, -4);
	const env = serverEnv();
	const webhookBaseUrl = env.MEDIA_SERVER_WEBHOOK_URL || env.WEB_URL;
	const webhookSecret = env.MEDIA_SERVER_WEBHOOK_SECRET;
	// Each Google Drive target is a resumable session costing two Drive round trips, so create them together.
	const [
		outputVerificationUrl,
		outputPresignedUrl,
		thumbnailPresignedUrl,
		previewGifPresignedUrl,
	] = await Promise.all([
		bucket
			.getInternalSignedObjectUrl(outputKey, {
				expiresIn: PRESIGNED_EXPIRES_SECONDS,
			})
			.pipe(runWorkflowPromise),
		bucket
			.getInternalPresignedPutUrl(
				outputKey,
				{ ContentType: "video/mp4" },
				{ expiresIn: PRESIGNED_EXPIRES_SECONDS },
			)
			.pipe(runWorkflowPromise),
		bucket
			.getInternalPresignedPutUrl(
				`${candidateDirectory}/screenshot.jpg`,
				{ ContentType: "image/jpeg" },
				{ expiresIn: PRESIGNED_EXPIRES_SECONDS },
			)
			.pipe(runWorkflowPromise),
		bucket
			.getInternalPresignedPutUrl(
				`${candidateDirectory}/preview.gif`,
				{
					ContentType: "image/gif",
					CacheControl: "public, max-age=31536000, immutable",
				},
				{ expiresIn: PRESIGNED_EXPIRES_SECONDS },
			)
			.pipe(runWorkflowPromise),
	]);
	let outputUpload: DesktopSegmentsOutputUpload = {
		type: "put",
		url: outputPresignedUrl,
		ifNoneMatch: "*",
	};
	const singlePut =
		bucket.provider === "s3" &&
		Option.isNone(customBucket) &&
		sourceBytes <= SINGLE_PUT_OUTPUT_MAX_SOURCE_BYTES;
	if (bucket.provider === "s3" && webhookSecret && !singlePut) {
		const multipart = await bucket.multipart
			.create(outputKey, { ContentType: "video/mp4" })
			.pipe(runWorkflowPromise);
		if (!multipart.UploadId)
			throw new Error("Storage did not return a multipart upload id");
		outputUpload = {
			type: "multipart",
			videoId: video.id,
			generation: attempt.generation,
			attemptId: attempt.attemptId,
			key: outputKey,
			uploadId: multipart.UploadId,
			partSize: MULTIPART_OUTPUT_PART_SIZE_BYTES,
			signPartUrl: getMediaServerWebhookUrl(
				webhookBaseUrl,
				"/api/webhooks/media-server/multipart/sign-part",
			),
			completeUrl: getMediaServerWebhookUrl(
				webhookBaseUrl,
				"/api/webhooks/media-server/multipart/complete",
			),
			abortUrl: getMediaServerWebhookUrl(
				webhookBaseUrl,
				"/api/webhooks/media-server/multipart/abort",
			),
			webhookSecret,
		};
	}
	return {
		outputKey,
		outputVerificationUrl,
		outputPresignedUrl,
		outputUpload,
		thumbnailPresignedUrl,
		previewGifPresignedUrl,
	};
}

type DesktopRecordingDispatch =
	| string
	| undefined
	| { status: "deferred" }
	| { status: "capacity"; retryAfterMs: number }
	| { status: "media-server-unconfigured" };

export async function startDesktopRecordingJob(
	attempt: DesktopRecordingAttempt,
): Promise<DesktopRecordingDispatch> {
	"use step";

	return dispatchDesktopRecordingJob(attempt);
}

async function dispatchDesktopRecordingJob(
	attempt: DesktopRecordingAttempt,
): Promise<DesktopRecordingDispatch> {
	if (await completeWithoutMediaServerIfUnavailable(attempt)) {
		return { status: "media-server-unconfigured" };
	}

	const current = await getProcessingState(attempt);
	if (!current || current.attemptId !== attempt.attemptId || !current.source) {
		throw new Error("Recording processing attempt was superseded");
	}
	if (current.remoteJobId) return current.remoteJobId;
	if (current.state === "retry") return { status: "deferred" };
	const remainingCapacityWait = current.nextRetryAt.getTime() - Date.now();
	if (
		current.output &&
		typeof current.output === "object" &&
		"kind" in current.output &&
		current.output.kind === "desktop-recording-capacity-wait" &&
		remainingCapacityWait > 0
	) {
		return { status: "capacity", retryAfterMs: remainingCapacityWait };
	}
	const [video] = await db()
		.select()
		.from(videos)
		.where(
			and(eq(videos.id, current.videoId), eq(videos.ownerId, current.ownerId)),
		);
	if (!video) throw new Error("Recording does not exist");
	const env = serverEnv();
	if (!env.MEDIA_SERVER_URL || !env.MEDIA_SERVER_WEBHOOK_SECRET) {
		throw new Error("Recording content verification is not configured");
	}
	const urls = await buildDesktopRecordingSourceUrls(
		video,
		current.source,
	).catch(async (error: unknown) => {
		const code = getSourceErrorCode(error);
		if (code) {
			await markSourceBlocked({
				...attempt,
				errorCode: code,
				errorMessage: getErrorMessage(error),
			});
		}
		throw error;
	});
	const sourceBytes = urls.sourceObjects.reduce(
		(total, object) => total + object.size,
		0,
	);
	let downloadBudgetBytes: number;
	try {
		downloadBudgetBytes = await reserveMediaProcessingBudget({
			videoId: current.videoId,
			generation: current.generation,
			attemptId: attempt.attemptId,
			sourceBytes,
		});
	} catch (error) {
		if (error instanceof MediaProcessingBudgetError) {
			await markSourceBlocked({
				videoId: current.videoId,
				generation: current.generation,
				attemptId: attempt.attemptId,
				errorCode: "processing-budget-exhausted",
				errorMessage: error.message,
			});
		}
		throw error;
	}
	const webhookBaseUrl = env.MEDIA_SERVER_WEBHOOK_URL || env.WEB_URL;
	const context = {
		downloadBudgetBytes,
		processingPriority: current.attemptCount > 1 ? "recovery" : "interactive",
		videoId: current.videoId,
		userId: current.ownerId,
		generation: current.generation,
		attemptId: attempt.attemptId,
		inventorySha256: current.source.inventorySha256,
		requiredAudio:
			current.source.requiredAudio ||
			current.verification?.requiredAudio === true,
		webhookUrl: getMediaServerWebhookUrl(
			webhookBaseUrl,
			"/api/webhooks/media-server/progress?retryable=true",
		),
		webhookSecret: env.MEDIA_SERVER_WEBHOOK_SECRET,
	};
	let path: string;
	let body: Record<string, unknown>;
	if (current.source.kind === "mp4") {
		const mp4 = current.source.mp4;
		if (
			!mp4 ||
			!urls.videoUrl ||
			!urls.sourceObjectIdentity ||
			!urls.outputKey
		) {
			throw new Error("Committed MP4 source is missing its immutable identity");
		}
		path = "/video/verify-recording";
		body = {
			...context,
			...urls,
			fileSize: mp4.fileSize,
			duration:
				current.verification?.artifact.kind === "mp4"
					? current.verification.artifact.duration
					: mp4.duration,
			objectIdentity: mp4.objectIdentity,
			originalObjectIdentity: mp4.objectIdentity,
			outputKey: urls.outputKey,
		};
	} else {
		if (!urls.videoInitUrl || !urls.videoSegmentUrls?.length) {
			throw new Error(
				"Committed segmented source is missing its video inventory",
			);
		}
		path = "/video/mux-segments";
		const [output, preverifiedRunUrls] = await Promise.all([
			buildDesktopSegmentsOutput({ video, attempt, sourceBytes }),
			buildPreverifiedRunUrls(video),
		]);
		body = {
			audioLevels: true,
			...context,
			...urls,
			...output,
			manifestSha256: current.source.manifestSha256,
			...(preverifiedRunUrls.length > 0 ? { preverifiedRunUrls } : {}),
		};
	}
	try {
		const response = await fetch(
			`${env.MEDIA_SERVER_URL.replace(/\/$/, "")}${path}`,
			{
				method: "POST",
				headers: {
					"Content-Type": "application/json",
					"x-media-server-secret": env.MEDIA_SERVER_WEBHOOK_SECRET,
				},
				body: JSON.stringify(body),
				signal: AbortSignal.timeout(30_000),
			},
		);
		if (response.status === 503) {
			const result: unknown = await response.json();
			const retryAfterMs = getMediaServerCapacityDelay({
				response,
				videoId: attempt.videoId,
			});
			if (
				result &&
				typeof result === "object" &&
				"code" in result &&
				result.code === "SERVER_BUSY" &&
				(await waitForDesktopRecordingCapacity({ ...attempt, retryAfterMs }))
			) {
				return { status: "capacity", retryAfterMs };
			}
		}
		if (response.ok) {
			const result = z
				.object({
					jobId: z.string().min(1),
					recordingWorkerVersion: z.literal(1).optional(),
				})
				.parse(await response.json());
			if (
				result.recordingWorkerVersion === undefined &&
				(await attachRemoteJob({ ...attempt, remoteJobId: result.jobId }))
			) {
				return result.jobId;
			}
		}
	} catch {
		console.warn(
			"[finalizeDesktopRecordingWorkflow] Reconciling worker dispatch",
			{
				videoId: attempt.videoId,
				generation: attempt.generation,
				attemptId: attempt.attemptId,
			},
		);
	}
	const reconciled = await getProcessingState(attempt);
	return reconciled?.attemptId === attempt.attemptId
		? (reconciled.remoteJobId ?? undefined)
		: undefined;
}

export async function pollDesktopRecordingAttempt({
	videoId,
	generation,
	attemptId,
	jobId,
	deadline,
}: DesktopRecordingAttemptFence & {
	jobId?: string;
	deadline: Date;
}): Promise<
	"waiting" | "verified" | "retry" | "source-blocked" | "superseded"
> {
	"use step";

	const fence = { videoId, generation, attemptId };
	let current = await getProcessingState(fence);
	if (!current) return "superseded";
	if (current.state === "verified") return "verified";
	if (current.attemptId !== fence.attemptId) return "superseded";
	if (current.state === "source-blocked") return "source-blocked";
	if (current.state === "retry") return "retry";
	const now = new Date();
	if (now >= deadline) {
		return (await scheduleRetry({
			...fence,
			errorCode: "processing-timeout",
			errorMessage:
				"Processing did not finish within its attempt lease; source files are retained.",
			now,
		}))
			? "retry"
			: "superseded";
	}
	const env = serverEnv();
	const ownerJobId = current.remoteJobId ?? jobId;
	if (env.MEDIA_SERVER_URL && current.source && ownerJobId) {
		const observation = await observeDesktopRecordingJob({
			...fence,
			jobId: ownerJobId,
			inventorySha256: current.source.inventorySha256,
			mediaServerUrl: env.MEDIA_SERVER_URL,
			webhookUrl: getMediaServerWebhookUrl(
				env.MEDIA_SERVER_WEBHOOK_URL || env.WEB_URL,
				"/api/webhooks/media-server/progress?retryable=true",
			),
			secret: env.MEDIA_SERVER_WEBHOOK_SECRET,
		});
		if (observation.status === "active" && !observation.workerProtocol) {
			await heartbeatAttempt(fence);
		}
	}
	current = await getProcessingState(fence);
	if (!current) return "superseded";
	if (current.state === "verified") return "verified";
	if (current.attemptId !== fence.attemptId) return "superseded";
	if (current.state === "source-blocked") return "source-blocked";
	if (current.state === "retry") return "retry";
	if (!current.leaseExpiresAt || current.leaseExpiresAt <= new Date()) {
		return (await scheduleRetry({
			...fence,
			errorCode: "worker-lease-expired",
			errorMessage:
				"Processing worker is unavailable. Retrying from the retained recording source.",
		}))
			? "retry"
			: "superseded";
	}
	return "waiting";
}

async function retryDesktopRecordingAttempt(
	{ videoId, generation, attemptId }: DesktopRecordingAttemptFence,
	errorMessage: string,
	sourceErrorCode: ReturnType<typeof getSourceErrorCode>,
): Promise<"waiting" | "verified" | "retry" | "source-blocked" | "superseded"> {
	"use step";

	const fence = { videoId, generation, attemptId };
	const current = await getProcessingState(fence);
	if (current?.state === "verified") return "verified";
	if (!current || current.attemptId !== attemptId) return "superseded";
	if (current.state === "source-blocked") return "source-blocked";
	if (sourceErrorCode) {
		return (await markSourceBlocked({
			...fence,
			errorCode: sourceErrorCode,
			errorMessage,
		}))
			? "source-blocked"
			: "superseded";
	}
	if (
		current.state === "processing" &&
		current.source &&
		current.leaseExpiresAt &&
		current.leaseExpiresAt > new Date()
	) {
		return "waiting";
	}
	return (await scheduleRetry({
		...fence,
		errorCode: "processing-interrupted",
		errorMessage,
	}))
		? "retry"
		: "superseded";
}

async function queueFinalizedRecordingTranscription(
	videoId: string,
	userId: User.UserId,
): Promise<boolean> {
	"use step";

	if (!serverEnv().ASSEMBLY_API_KEY) return true;
	try {
		const [[owner], [video]] = await Promise.all([
			db()
				.select({
					email: users.email,
					stripeSubscriptionStatus: users.stripeSubscriptionStatus,
					thirdPartyStripeSubscriptionId: users.thirdPartyStripeSubscriptionId,
				})
				.from(users)
				.where(eq(users.id, userId)),
			db()
				.select({ id: videos.id })
				.from(videos)
				.where(
					and(
						eq(videos.id, Video.VideoId.make(videoId)),
						eq(videos.ownerId, userId),
					),
				),
		]);
		if (!owner || !video) return true;
		const result = await transcribeVideo(
			Video.VideoId.make(videoId),
			userId,
			isAiGenerationEnabledForUser(owner),
		);
		if (result.success) return true;
		console.warn(
			"[finalizeDesktopRecordingWorkflow] Transcription enqueue failed",
			{ videoId, message: result.message },
		);
	} catch (error) {
		console.warn(
			"[finalizeDesktopRecordingWorkflow] Transcription enqueue interrupted",
			{ videoId, error: getErrorMessage(error) },
		);
	}
	return false;
}