Skip to content

🎥 Make videos programmatically with React

`@remotion/serverless`: Make artifact retries idempotent

JonnyBurger419289c8da73
diff --git a/packages/serverless/src/artifact-registry.ts b/packages/serverless/src/artifact-registry.ts
new file mode 100644
index 0000000000..e5ef0ad509
--- /dev/null
+++ b/packages/serverless/src/artifact-registry.ts
@@ -0,0 +1,56 @@
+import type {EmittedArtifact} from '@remotion/renderer';
+
+type ArtifactRegistration = {
+ chunk: number;
+ frame: number;
+ attempt: number;
+ filename: string;
+};
+
+export type ArtifactRegistrationResult =
+ | {type: 'accepted'}
+ | {type: 'retry-replay'}
+ | {type: 'conflict'};
+
+export type OnArtifactFromRenderer = (params: {
+ artifact: EmittedArtifact;
+ chunk: number;
+ attempt: number;
+}) => ArtifactRegistrationResult;
+
+export const makeArtifactRegistry = () => {
+ const artifactsByFilename = new Map<string, ArtifactRegistration>();
+ const artifactsByAttempt = new Set<string>();
+
+ const registerArtifact = (
+ artifact: ArtifactRegistration,
+ ): ArtifactRegistrationResult => {
+ const attemptKey = JSON.stringify([
+ artifact.chunk,
+ artifact.attempt,
+ artifact.filename,
+ ]);
+ if (artifactsByAttempt.has(attemptKey)) {
+ return {type: 'conflict'};
+ }
+
+ artifactsByAttempt.add(attemptKey);
+ const existingArtifact = artifactsByFilename.get(artifact.filename);
+ if (!existingArtifact) {
+ artifactsByFilename.set(artifact.filename, artifact);
+ return {type: 'accepted'};
+ }
+
+ if (
+ existingArtifact.chunk === artifact.chunk &&
+ existingArtifact.frame === artifact.frame &&
+ artifact.attempt > existingArtifact.attempt
+ ) {
+ return {type: 'retry-replay'};
+ }
+
+ return {type: 'conflict'};
+ };
+
+ return {registerArtifact};
+};
diff --git a/packages/serverless/src/handlers/launch.ts b/packages/serverless/src/handlers/launch.ts
index 16df9fec90..73a1142cbe 100644
--- a/packages/serverless/src/handlers/launch.ts
+++ b/packages/serverless/src/handlers/launch.ts
@@ -2,7 +2,7 @@ import {existsSync, mkdirSync, rmSync} from 'fs';
import {type EventEmitter} from 'node:events';
import {join} from 'path';
/* eslint-disable @typescript-eslint/no-use-before-define */
-import type {EmittedArtifact, LogOptions} from '@remotion/renderer';
+import type {LogOptions} from '@remotion/renderer';
import {RenderInternals} from '@remotion/renderer';
import {validateCodec, VERSION} from '@remotion/serverless-client';
import type {
@@ -29,6 +29,10 @@ import {
validatePrivacy,
writeCancellationSignal,
} from '@remotion/serverless-client';
+import {
+ makeArtifactRegistry,
+ type OnArtifactFromRenderer,
+} from '../artifact-registry';
import {cleanupProps} from '../cleanup-props';
import {findOutputFileInBucket} from '../find-output-file-in-bucket';
import type {LaunchedBrowser} from '../get-browser-instance';
@@ -421,14 +425,17 @@ const innerLaunchHandler = async <Provider extends CloudProvider>({
mkdirSync(outdir);
const files: string[] = [];
-
- const onArtifact = (artifact: EmittedArtifact): {alreadyExisted: boolean} => {
- if (
- overallProgress
- .getReceivedArtifacts()
- .find((a) => a.filename === artifact.filename)
- ) {
- return {alreadyExisted: true};
+ const artifactRegistry = makeArtifactRegistry();
+
+ const onArtifact: OnArtifactFromRenderer = ({artifact, chunk, attempt}) => {
+ const artifactRegistration = artifactRegistry.registerArtifact({
+ chunk,
+ frame: artifact.frame,
+ attempt,
+ filename: artifact.filename,
+ });
+ if (artifactRegistration.type !== 'accepted') {
+ return artifactRegistration;
}
const region = insideFunctionSpecifics.getCurrentRegionInFunction();
@@ -476,9 +483,9 @@ const innerLaunchHandler = async <Provider extends CloudProvider>({
stack: (err as Error).stack as string,
tmpDir: null,
frame: artifact.frame,
- chunk: null,
+ chunk,
isFatal: false,
- attempt: 1,
+ attempt,
willRetry: false,
totalAttempts: 1,
});
@@ -489,7 +496,7 @@ const innerLaunchHandler = async <Provider extends CloudProvider>({
err,
);
});
- return {alreadyExisted: false};
+ return artifactRegistration;
};
await Promise.all(
diff --git a/packages/serverless/src/stream-renderer.ts b/packages/serverless/src/stream-renderer.ts
index ebbd414111..dfc536e72f 100644
--- a/packages/serverless/src/stream-renderer.ts
+++ b/packages/serverless/src/stream-renderer.ts
@@ -17,6 +17,7 @@ import {
ServerlessRoutines,
streamToString,
} from '@remotion/serverless-client';
+import type {OnArtifactFromRenderer} from './artifact-registry';
import type {OverallProgressHelper} from './overall-render-progress';
import type {InsideFunctionSpecifics} from './provider-implementation';
import {artifactFromS3} from './s3-renderer-output';
@@ -49,7 +50,7 @@ const streamRenderer = <Provider extends CloudProvider>({
overallProgress: OverallProgressHelper<Provider>;
files: string[];
logLevel: LogLevel;
- onArtifact: (asset: EmittedArtifact) => {alreadyExisted: boolean};
+ onArtifact: OnArtifactFromRenderer;
providerSpecifics: ProviderSpecifics<Provider>;
insideFunctionSpecifics: InsideFunctionSpecifics<Provider>;
requestHandler: Provider['requestHandler'] | null;
@@ -156,8 +157,12 @@ const streamRenderer = <Provider extends CloudProvider>({
artifact.filename,
artifact.content.length + 'bytes.',
);
- const {alreadyExisted} = onArtifact(artifact);
- if (alreadyExisted) {
+ const artifactRegistration = onArtifact({
+ artifact,
+ chunk: payload.chunk,
+ attempt: payload.attempt,
+ });
+ if (artifactRegistration.type === 'conflict') {
return resolve({
type: 'error',
error: `Chunk ${payload.chunk} emitted an asset filename ${message.payload.artifact.filename} at frame ${message.payload.artifact.frame} but there is already another artifact with the same name. https://remotion.dev/docs/artifacts`,
@@ -165,6 +170,13 @@ const streamRenderer = <Provider extends CloudProvider>({
});
}
+ if (artifactRegistration.type === 'retry-replay') {
+ RenderInternals.Log.info(
+ {indent: false, logLevel},
+ `Ignoring artifact ${artifact.filename} replayed by attempt ${payload.attempt} of chunk ${payload.chunk}`,
+ );
+ }
+
return;
}
@@ -291,7 +303,7 @@ const s3Renderer = async <Provider extends CloudProvider>({
overallProgress: OverallProgressHelper<Provider>;
files: string[];
logLevel: LogLevel;
- onArtifact: (asset: EmittedArtifact) => {alreadyExisted: boolean};
+ onArtifact: OnArtifactFromRenderer;
providerSpecifics: ProviderSpecifics<Provider>;
insideFunctionSpecifics: InsideFunctionSpecifics<Provider>;
requestHandler: Provider['requestHandler'] | null;
@@ -460,14 +472,25 @@ const s3Renderer = async <Provider extends CloudProvider>({
}
for (const emittedArtifact of emittedArtifacts) {
- const {alreadyExisted} = onArtifact(emittedArtifact);
- if (alreadyExisted) {
+ const artifactRegistration = onArtifact({
+ artifact: emittedArtifact,
+ chunk: payload.chunk,
+ attempt: payload.attempt,
+ });
+ if (artifactRegistration.type === 'conflict') {
return {
type: 'error',
error: `Chunk ${payload.chunk} emitted an asset filename ${emittedArtifact.filename} at frame ${emittedArtifact.frame} but there is already another artifact with the same name. https://remotion.dev/docs/artifacts`,
shouldRetry: false,
};
}
+
+ if (artifactRegistration.type === 'retry-replay') {
+ RenderInternals.Log.info(
+ {indent: false, logLevel},
+ `Ignoring artifact ${emittedArtifact.filename} replayed by attempt ${payload.attempt} of chunk ${payload.chunk}`,
+ );
+ }
}
files.push(...downloadedFiles);
@@ -550,7 +573,7 @@ export const renderRendererFunctionWithRetry = async <
overallProgress: OverallProgressHelper<Provider>;
files: string[];
logLevel: LogLevel;
- onArtifact: (asset: EmittedArtifact) => {alreadyExisted: boolean};
+ onArtifact: OnArtifactFromRenderer;
providerSpecifics: ProviderSpecifics<Provider>;
insideFunctionSpecifics: InsideFunctionSpecifics<Provider>;
requestHandler: Provider['requestHandler'] | null;
diff --git a/packages/serverless/src/test/artifact-registry.test.ts b/packages/serverless/src/test/artifact-registry.test.ts
new file mode 100644
index 0000000000..b5172caefa
--- /dev/null
+++ b/packages/serverless/src/test/artifact-registry.test.ts
@@ -0,0 +1,73 @@
+import {expect, test} from 'bun:test';
+import {
+ type ArtifactRegistrationResult,
+ makeArtifactRegistry,
+} from '../artifact-registry';
+
+test('classifies new artifacts, retry replays, and filename conflicts', () => {
+ const cases: Array<{
+ name: string;
+ artifacts: Array<{
+ chunk: number;
+ frame: number;
+ attempt: number;
+ filename: string;
+ }>;
+ expected: Array<ArtifactRegistrationResult['type']>;
+ }> = [
+ {
+ name: 'new artifact',
+ artifacts: [{chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'}],
+ expected: ['accepted'],
+ },
+ {
+ name: 'retry replay',
+ artifacts: [
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ {chunk: 0, frame: 10, attempt: 2, filename: 'file.txt'},
+ ],
+ expected: ['accepted', 'retry-replay'],
+ },
+ {
+ name: 'duplicate in the first attempt',
+ artifacts: [
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ ],
+ expected: ['accepted', 'conflict'],
+ },
+ {
+ name: 'duplicate in a retry attempt',
+ artifacts: [
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ {chunk: 0, frame: 10, attempt: 2, filename: 'file.txt'},
+ {chunk: 0, frame: 10, attempt: 2, filename: 'file.txt'},
+ ],
+ expected: ['accepted', 'retry-replay', 'conflict'],
+ },
+ {
+ name: 'same filename on another frame',
+ artifacts: [
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ {chunk: 0, frame: 11, attempt: 2, filename: 'file.txt'},
+ ],
+ expected: ['accepted', 'conflict'],
+ },
+ {
+ name: 'same filename in another chunk',
+ artifacts: [
+ {chunk: 0, frame: 10, attempt: 1, filename: 'file.txt'},
+ {chunk: 1, frame: 10, attempt: 2, filename: 'file.txt'},
+ ],
+ expected: ['accepted', 'conflict'],
+ },
+ ];
+
+ for (const testCase of cases) {
+ const registry = makeArtifactRegistry();
+ const results = testCase.artifacts.map(
+ (artifact) => registry.registerArtifact(artifact).type,
+ );
+ expect(results, testCase.name).toEqual(testCase.expected);
+ }
+});
diff --git a/packages/serverless/src/test/s3-renderer-launcher.test.ts b/packages/serverless/src/test/s3-renderer-launcher.test.ts
index 41e0ce1c9f..18e96b7c75 100644
--- a/packages/serverless/src/test/s3-renderer-launcher.test.ts
+++ b/packages/serverless/src/test/s3-renderer-launcher.test.ts
@@ -121,6 +121,7 @@ test('S3 launcher invokes, polls, downloads, and normalizes a renderer result',
} as unknown as InsideFunctionSpecifics<MockProvider>;
const files: string[] = [];
const artifacts: EmittedArtifact[] = [];
+ const artifactSources: Array<{chunk: number; attempt: number}> = [];
await renderRendererFunctionWithRetry({
payload: {
@@ -137,9 +138,10 @@ test('S3 launcher invokes, polls, downloads, and normalizes a renderer result',
outdir: directory,
overallProgress,
logLevel: 'info',
- onArtifact: (artifact) => {
+ onArtifact: ({artifact, chunk, attempt}) => {
artifacts.push(artifact);
- return {alreadyExisted: false};
+ artifactSources.push({chunk, attempt});
+ return {type: 'accepted'};
},
providerSpecifics,
insideFunctionSpecifics,
@@ -159,6 +161,7 @@ test('S3 launcher invokes, polls, downloads, and normalizes a renderer result',
downloadBehavior: null,
},
]);
+ expect(artifactSources).toEqual([{chunk: 0, attempt: 1}]);
expect(files).toHaveLength(1);
expect(await readFile(files[0]!, 'utf8')).toBe('video');
expect(deleted.sort()).toEqual([artifactKey, statusKey, videoKey].sort());
diff --git a/packages/serverless/src/test/streaming-renderer-launcher.test.ts b/packages/serverless/src/test/streaming-renderer-launcher.test.ts
new file mode 100644
index 0000000000..56e8b1ef8d
--- /dev/null
+++ b/packages/serverless/src/test/streaming-renderer-launcher.test.ts
@@ -0,0 +1,143 @@
+import {expect, test} from 'bun:test';
+import type {EmittedArtifact} from '@remotion/renderer';
+import type {
+ OnMessage,
+ ProviderSpecifics,
+ ServerlessPayload,
+} from '@remotion/serverless-client';
+import {
+ serializeArtifact,
+ ServerlessRoutines,
+} from '@remotion/serverless-client';
+import {makeArtifactRegistry} from '../artifact-registry';
+import type {OverallProgressHelper} from '../overall-render-progress';
+import type {InsideFunctionSpecifics} from '../provider-implementation';
+import {renderRendererFunctionWithRetry} from '../stream-renderer';
+
+type MockProvider = {
+ type: 'mock';
+ region: 'mock-region';
+ receivedArtifactType: never;
+ creationFunctionOptions: never;
+ storageClass: never;
+ requestHandler: never;
+};
+
+test('an artifact replayed by a retried streaming chunk is idempotent', async () => {
+ const attempts: number[] = [];
+ const providerSpecifics = {
+ getRendererFunctionTransport: () => 'response-streaming',
+ callFunctionStreaming: ({
+ payload,
+ receivedStreamingPayload,
+ }: {
+ payload: ServerlessPayload<MockProvider>;
+ receivedStreamingPayload: OnMessage<MockProvider>;
+ }) => {
+ if (payload.type !== ServerlessRoutines.renderer) {
+ throw new Error('Expected renderer payload');
+ }
+
+ attempts.push(payload.attempt);
+ receivedStreamingPayload({
+ successType: 'success',
+ message: {
+ type: 'artifact-emitted',
+ payload: {
+ artifact: serializeArtifact({
+ filename: 'thumbnail.jpeg',
+ frame: 0,
+ content: 'thumbnail',
+ downloadBehavior: null,
+ }),
+ },
+ },
+ });
+
+ if (payload.attempt === 1) {
+ receivedStreamingPayload({
+ successType: 'error',
+ message: {
+ type: 'error-occurred',
+ payload: {
+ error: 'Flaky renderer error',
+ shouldRetry: true,
+ errorInfo: {} as never,
+ },
+ },
+ });
+ } else {
+ receivedStreamingPayload({
+ successType: 'success',
+ message: {
+ type: 'chunk-complete',
+ payload: {start: 100, rendered: 200},
+ },
+ });
+ }
+
+ return Promise.resolve();
+ },
+ } as unknown as ProviderSpecifics<MockProvider>;
+ const retries: number[] = [];
+ let completedChunks = 0;
+ const overallProgress = {
+ setFrames: () => undefined,
+ addErrorWithoutUpload: () => undefined,
+ addRetry: ({attempt}: {attempt: number}) => retries.push(attempt),
+ addChunkCompleted: () => {
+ completedChunks++;
+ },
+ } as unknown as OverallProgressHelper<MockProvider>;
+ const insideFunctionSpecifics = {
+ getCurrentRegionInFunction: () => 'mock-region',
+ } as unknown as InsideFunctionSpecifics<MockProvider>;
+ const artifactRegistry = makeArtifactRegistry();
+ const acceptedArtifacts: EmittedArtifact[] = [];
+
+ await renderRendererFunctionWithRetry({
+ payload: {
+ type: 'renderer',
+ bucketName: 'bucket',
+ renderId: 'render-id',
+ chunk: 0,
+ attempt: 1,
+ retriesLeft: 1,
+ forcePathStyle: false,
+ } as never,
+ files: [],
+ functionName: 'renderer-function',
+ outdir: '/tmp',
+ overallProgress,
+ logLevel: 'info',
+ onArtifact: ({artifact, chunk, attempt}) => {
+ const result = artifactRegistry.registerArtifact({
+ chunk,
+ frame: artifact.frame,
+ attempt,
+ filename: artifact.filename,
+ });
+ if (result.type === 'accepted') {
+ acceptedArtifacts.push(artifact);
+ }
+
+ return result;
+ },
+ providerSpecifics,
+ insideFunctionSpecifics,
+ requestHandler: null,
+ expectedBucketOwner: 'owner',
+ });
+
+ expect(attempts).toEqual([1, 2]);
+ expect(retries).toEqual([2]);
+ expect(completedChunks).toBe(1);
+ expect(acceptedArtifacts).toEqual([
+ {
+ filename: 'thumbnail.jpeg',
+ frame: 0,
+ content: 'thumbnail',
+ downloadBehavior: null,
+ },
+ ]);
+});