Skip to content

🎥 Make videos programmatically with React

`@remotion/lambda`: Stream chunks to disk instead of buffering them in memory (#10639)

Jonny Burger87239d64bb70
diff --git a/packages/lambda-client/src/call-lambda-streaming.ts b/packages/lambda-client/src/call-lambda-streaming.ts
index 97c2da8b05..8c6ec34f2e 100644
--- a/packages/lambda-client/src/call-lambda-streaming.ts
+++ b/packages/lambda-client/src/call-lambda-streaming.ts
@@ -7,12 +7,14 @@ import {
import type {
CallFunctionOptions,
CloudProvider,
+ GetBinaryPayloadSink,
MessageTypeId,
OnMessage,
ServerlessRoutines,
StreamingMessage,
} from '@remotion/serverless-client';
import {
+ binaryPayloadSinkForStreamer,
formatMap,
makeStreamer,
messageTypeIdToMessageType,
@@ -93,8 +95,10 @@ const callLambdaWithStreamingWithoutRetry = async <
timeoutInTest,
receivedStreamingPayload,
requestHandler,
+ getBinaryPayloadSink,
}: CallFunctionOptions<T, Provider> & {
receivedStreamingPayload: OnMessage<Provider>;
+ getBinaryPayloadSink: GetBinaryPayloadSink | null;
}): Promise<void> => {
const res = await invokeStreamOrTimeout({
functionName,
@@ -105,25 +109,30 @@ const callLambdaWithStreamingWithoutRetry = async <
requestHandler,
});
- const {onData, clear} = makeStreamer((status, messageTypeId, data) => {
- const messageType = messageTypeIdToMessageType(
- messageTypeId as MessageTypeId,
- );
- const innerPayload =
- formatMap[messageType] === 'json'
- ? parseJsonOrThrowSource(data, messageType)
- : data;
-
- const message: StreamingMessage<Provider> = {
- successType: status,
- message: {
- type: messageType,
- payload: innerPayload,
- },
- };
-
- receivedStreamingPayload(message);
- });
+ const {onData, clear} = makeStreamer(
+ (status, messageTypeId, data) => {
+ const messageType = messageTypeIdToMessageType(
+ messageTypeId as MessageTypeId,
+ );
+ const innerPayload =
+ formatMap[messageType] === 'json'
+ ? parseJsonOrThrowSource(data, messageType)
+ : data;
+
+ const message: StreamingMessage<Provider> = {
+ successType: status,
+ message: {
+ type: messageType,
+ payload: innerPayload,
+ },
+ };
+
+ receivedStreamingPayload(message);
+ },
+ getBinaryPayloadSink
+ ? binaryPayloadSinkForStreamer(getBinaryPayloadSink)
+ : null,
+ );
const dumpBuffers = () => {
clear();
@@ -141,46 +150,52 @@ const callLambdaWithStreamingWithoutRetry = async <
const events =
res.EventStream as AsyncIterable<InvokeWithResponseStreamResponseEvent>;
- for await (const event of events) {
- // There are two types of events you can get on a stream.
+ try {
+ for await (const event of events) {
+ // There are two types of events you can get on a stream.
+
+ // `PayloadChunk`: These contain the actual raw bytes of the chunk
+ // It has a single property: `Payload`
+ if (event.PayloadChunk && event.PayloadChunk.Payload) {
+ // Awaiting applies backpressure to the response stream when the
+ // payload is being streamed to a sink
+ await onData(event.PayloadChunk.Payload);
+ }
- // `PayloadChunk`: These contain the actual raw bytes of the chunk
- // It has a single property: `Payload`
- if (event.PayloadChunk && event.PayloadChunk.Payload) {
- onData(event.PayloadChunk.Payload);
- }
+ if (event.InvokeComplete) {
+ if (event.InvokeComplete.ErrorCode) {
+ const {consoleDomain} = getAwsRegionMetadata(region as AwsRegion);
+ const logs = `https://${region}.${consoleDomain}/cloudwatch/home?region=${region}#logsV2:logs-insights$3FqueryDetail$3D~(end~0~start~-3600~timeType~'RELATIVE~unit~'seconds~editorString~'fields*20*40timestamp*2c*20*40requestId*2c*20*40message*0a*7c*20filter*20*40requestId*20like*20*${res.$metadata.requestId}*22*0a*7c*20sort*20*40timestamp*20asc~source~(~'*2faws*2flambda*2f${functionName}))`;
+ if (event.InvokeComplete.ErrorCode === 'Unhandled') {
+ throw new Error(
+ `Lambda function ${functionName} failed with an unhandled error: ${
+ event.InvokeComplete.ErrorDetails as string
+ } See ${logs} to see the logs of this invocation.`,
+ );
+ }
- if (event.InvokeComplete) {
- if (event.InvokeComplete.ErrorCode) {
- const {consoleDomain} = getAwsRegionMetadata(region as AwsRegion);
- const logs = `https://${region}.${consoleDomain}/cloudwatch/home?region=${region}#logsV2:logs-insights$3FqueryDetail$3D~(end~0~start~-3600~timeType~'RELATIVE~unit~'seconds~editorString~'fields*20*40timestamp*2c*20*40requestId*2c*20*40message*0a*7c*20filter*20*40requestId*20like*20*${res.$metadata.requestId}*22*0a*7c*20sort*20*40timestamp*20asc~source~(~'*2faws*2flambda*2f${functionName}))`;
- if (event.InvokeComplete.ErrorCode === 'Unhandled') {
throw new Error(
- `Lambda function ${functionName} failed with an unhandled error: ${
- event.InvokeComplete.ErrorDetails as string
- } See ${logs} to see the logs of this invocation.`,
+ `Lambda function ${functionName} failed with error code ${event.InvokeComplete.ErrorCode}: ${event.InvokeComplete.ErrorDetails}. See ${logs} to see the logs of this invocation.`,
);
}
-
- throw new Error(
- `Lambda function ${functionName} failed with error code ${event.InvokeComplete.ErrorCode}: ${event.InvokeComplete.ErrorDetails}. See ${logs} to see the logs of this invocation.`,
- );
}
- }
- // Don't put a `break` statement here, as it will cause the socket to not properly exit.
- }
-
- // @ts-expect-error - We are adding a listener to a global variable
- if (globalThis._dumpUnreleasedBuffers) {
+ // Don't put a `break` statement here, as it will cause the socket to not properly exit.
+ }
+ } finally {
// @ts-expect-error - We are adding a listener to a global variable
- (globalThis._dumpUnreleasedBuffers as EventEmitter).removeListener(
- 'dump-unreleased-buffers',
- dumpBuffers,
- );
- }
+ if (globalThis._dumpUnreleasedBuffers) {
+ // @ts-expect-error - We are adding a listener to a global variable
+ (globalThis._dumpUnreleasedBuffers as EventEmitter).removeListener(
+ 'dump-unreleased-buffers',
+ dumpBuffers,
+ );
+ }
- clear();
+ // Also closes the active payload sink if the stream aborted
+ // mid-payload, so no file descriptor is leaked
+ clear();
+ }
};
export const callFunctionWithStreamingImplementation = async <
@@ -190,6 +205,7 @@ export const callFunctionWithStreamingImplementation = async <
options: CallFunctionOptions<T, Provider> & {
receivedStreamingPayload: OnMessage<Provider>;
retriesRemaining: number;
+ getBinaryPayloadSink: GetBinaryPayloadSink | null;
},
): Promise<void> => {
// As of August 2023, Lambda streaming sometimes misses parts of the JSON response.
diff --git a/packages/lambda-client/src/render-still-on-lambda.ts b/packages/lambda-client/src/render-still-on-lambda.ts
index 17c6ed534b..764302bb57 100644
--- a/packages/lambda-client/src/render-still-on-lambda.ts
+++ b/packages/lambda-client/src/render-still-on-lambda.ts
@@ -118,6 +118,7 @@ const innerRenderStillOnLambda = async (
},
timeoutInTest: 120000,
retriesRemaining: input.maxRetries,
+ getBinaryPayloadSink: null,
requestHandler: input.requestHandler,
})
.then(() => {
diff --git a/packages/lambda/src/test/mocks/aws-clients.ts b/packages/lambda/src/test/mocks/aws-clients.ts
index 24f0f6a625..d71c1e1984 100644
--- a/packages/lambda/src/test/mocks/aws-clients.ts
+++ b/packages/lambda/src/test/mocks/aws-clients.ts
@@ -4,6 +4,7 @@ import type {
CallFunctionOptions,
CallFunctionStreaming,
CallFunctionSync,
+ GetBinaryPayloadSink,
MessageTypeId,
OnMessage,
OrError,
@@ -12,6 +13,7 @@ import type {
StreamingMessage,
} from '@remotion/serverless';
import {
+ binaryPayloadSinkForStreamer,
formatMap,
innerHandler,
messageTypeIdToMessageType,
@@ -29,29 +31,35 @@ export const getMockCallFunctionStreaming: CallFunctionStreaming<
params: CallFunctionOptions<T, AwsProvider> & {
receivedStreamingPayload: OnMessage<AwsProvider>;
retriesRemaining: number;
+ getBinaryPayloadSink: GetBinaryPayloadSink | null;
},
) => {
const responseStream = new ResponseStream();
- const {onData, clear} = makeStreamer((status, messageTypeId, data) => {
- const messageType = messageTypeIdToMessageType(
- messageTypeId as MessageTypeId,
- );
- const innerPayload =
- formatMap[messageType] === 'json'
- ? LambdaClientInternals.parseJsonOrThrowSource(data, messageType)
- : data;
+ const {onData, clear} = makeStreamer(
+ (status, messageTypeId, data) => {
+ const messageType = messageTypeIdToMessageType(
+ messageTypeId as MessageTypeId,
+ );
+ const innerPayload =
+ formatMap[messageType] === 'json'
+ ? LambdaClientInternals.parseJsonOrThrowSource(data, messageType)
+ : data;
- const message: StreamingMessage<AwsProvider> = {
- successType: status,
- message: {
- type: messageType,
- payload: innerPayload,
- },
- };
+ const message: StreamingMessage<AwsProvider> = {
+ successType: status,
+ message: {
+ type: messageType,
+ payload: innerPayload,
+ },
+ };
- params.receivedStreamingPayload(message);
- });
+ params.receivedStreamingPayload(message);
+ },
+ params.getBinaryPayloadSink
+ ? binaryPayloadSinkForStreamer(params.getBinaryPayloadSink)
+ : null,
+ );
Log.verbose(
{indent: false, logLevel: params.payload.logLevel},
@@ -61,9 +69,8 @@ export const getMockCallFunctionStreaming: CallFunctionStreaming<
await innerHandler<AwsProvider>({
params: params.payload,
responseWriter: {
- write(message) {
- onData(message);
- return Promise.resolve();
+ async write(message) {
+ await onData(message);
},
end() {
clear();
diff --git a/packages/serverless-client/src/index.ts b/packages/serverless-client/src/index.ts
index 8f315bb9b0..9d0c590003 100644
--- a/packages/serverless-client/src/index.ts
+++ b/packages/serverless-client/src/index.ts
@@ -115,7 +115,10 @@ export {
export {OrError, ServerlessReturnValues} from './return-values';
export {streamToString} from './stream-to-string';
export {
+ BinaryMessageType,
+ binaryPayloadSinkForStreamer,
formatMap,
+ GetBinaryPayloadSink,
makeStreamPayload,
MessageTypeId,
messageTypeIdToMessageType,
diff --git a/packages/serverless-client/src/provider-implementation.ts b/packages/serverless-client/src/provider-implementation.ts
index 6ddf9b3e90..29808029db 100644
--- a/packages/serverless-client/src/provider-implementation.ts
+++ b/packages/serverless-client/src/provider-implementation.ts
@@ -6,7 +6,7 @@ import type {BillingCurrency} from './format-costs-info';
import type {RenderMetadata} from './render-metadata';
import type {RendererFunctionTransport} from './renderer-transport';
import type {ServerlessReturnValues} from './return-values';
-import type {OnMessage} from './streaming/streaming';
+import type {GetBinaryPayloadSink, OnMessage} from './streaming/streaming';
import type {CallFunctionOptions, CloudProvider} from './types';
export type ParseFunctionName = (functionName: string) => {
@@ -159,6 +159,7 @@ export type CallFunctionStreaming<Provider extends CloudProvider> = <
options: CallFunctionOptions<T, Provider> & {
receivedStreamingPayload: OnMessage<Provider>;
retriesRemaining: number;
+ getBinaryPayloadSink: GetBinaryPayloadSink | null;
},
) => Promise<void>;
diff --git a/packages/serverless-client/src/streaming/streaming.ts b/packages/serverless-client/src/streaming/streaming.ts
index cc0298a0ce..a84eb7ca78 100644
--- a/packages/serverless-client/src/streaming/streaming.ts
+++ b/packages/serverless-client/src/streaming/streaming.ts
@@ -1,3 +1,4 @@
+import type {GetPayloadSink, PayloadSink} from '@remotion/streaming';
import {makeStreamPayloadMessage} from '@remotion/streaming';
import type {SerializedArtifact} from '../serialize-artifact';
import type {CloudProvider, RenderStillFunctionResponsePayload} from '../types';
@@ -126,6 +127,34 @@ export type OnMessage<Provider extends CloudProvider> = (
options: StreamingMessage<Provider>,
) => void;
+export type BinaryMessageType =
+ | typeof videoChunkRendered
+ | typeof audioChunkRendered;
+
+// If a sink is returned, the binary payload is streamed into it instead of
+// being accumulated in memory. The corresponding message is then delivered
+// with an empty payload after the sink has ended.
+export type GetBinaryPayloadSink = (params: {
+ messageType: BinaryMessageType;
+ length: number;
+}) => PayloadSink | null;
+
+export const binaryPayloadSinkForStreamer = (
+ getBinaryPayloadSink: GetBinaryPayloadSink,
+): GetPayloadSink => {
+ return (_statusType, nonce, length) => {
+ const messageType = messageTypeIdToMessageType(nonce as MessageTypeId);
+ if (formatMap[messageType] !== 'binary') {
+ return null;
+ }
+
+ return getBinaryPayloadSink({
+ messageType: messageType as BinaryMessageType,
+ length,
+ });
+ };
+};
+
export type OnStream<Provider extends CloudProvider> = (
payload: StreamingPayload<Provider>,
) => Promise<void>;
diff --git a/packages/serverless/src/stream-renderer.ts b/packages/serverless/src/stream-renderer.ts
index 61467536b5..ebbd414111 100644
--- a/packages/serverless/src/stream-renderer.ts
+++ b/packages/serverless/src/stream-renderer.ts
@@ -5,6 +5,7 @@ import type {EmittedArtifact, LogLevel} from '@remotion/renderer';
import {RenderInternals} from '@remotion/renderer';
import type {
CloudProvider,
+ GetBinaryPayloadSink,
OnMessage,
ProviderSpecifics,
ServerlessPayload,
@@ -59,6 +60,35 @@ const streamRenderer = <Provider extends CloudProvider>({
}
return new Promise<StreamRendererResponse>((resolve) => {
+ const chunkFilename = (type: 'video' | 'audio') =>
+ join(outdir, `chunk:${String(payload.chunk).padStart(8, '0')}:${type}`);
+
+ // Stream the chunks to disk as they arrive instead of buffering them
+ // in memory. With many chunks arriving concurrently, buffering can
+ // exhaust the memory of the main function.
+ const getBinaryPayloadSink: GetBinaryPayloadSink = ({messageType}) => {
+ const filename = chunkFilename(
+ messageType === 'video-chunk-rendered' ? 'video' : 'audio',
+ );
+ const writeStream = createWriteStream(filename);
+ return {
+ write: (data) =>
+ new Promise<void>((resolve_, reject) => {
+ writeStream.write(data, (err) => {
+ if (err) {
+ reject(err);
+ } else {
+ resolve_();
+ }
+ });
+ }),
+ end: () =>
+ new Promise<void>((resolve_) => {
+ writeStream.end(resolve_);
+ }),
+ };
+ };
+
const receivedStreamingPayload: OnMessage<Provider> = ({message}) => {
if (message.type === 'lambda-invoked') {
overallProgress.setLambdaInvoked(payload.chunk);
@@ -75,11 +105,12 @@ const streamRenderer = <Provider extends CloudProvider>({
}
if (message.type === 'video-chunk-rendered') {
- const filename = join(
- outdir,
- `chunk:${String(payload.chunk).padStart(8, '0')}:video`,
- );
- writeFileSync(filename, new Uint8Array(message.payload));
+ const filename = chunkFilename('video');
+ // An empty payload means the chunk was already streamed to disk
+ if (message.payload.length > 0) {
+ writeFileSync(filename, message.payload);
+ }
+
files.push(filename);
RenderInternals.Log.verbose(
{indent: false, logLevel},
@@ -90,12 +121,12 @@ const streamRenderer = <Provider extends CloudProvider>({
}
if (message.type === 'audio-chunk-rendered') {
- const filename = join(
- outdir,
- `chunk:${String(payload.chunk).padStart(8, '0')}:audio`,
- );
+ const filename = chunkFilename('audio');
+ // An empty payload means the chunk was already streamed to disk
+ if (message.payload.length > 0) {
+ writeFileSync(filename, message.payload);
+ }
- writeFileSync(filename, new Uint8Array(message.payload));
RenderInternals.Log.verbose(
{indent: false, logLevel},
`Received audio chunk for chunk ${payload.chunk}`,
@@ -181,6 +212,7 @@ const streamRenderer = <Provider extends CloudProvider>({
type: ServerlessRoutines.renderer,
receivedStreamingPayload,
requestHandler,
+ getBinaryPayloadSink,
})
.then(() => {
resolve({
diff --git a/packages/streaming/package.json b/packages/streaming/package.json
index d60b38b537..a5c6a4ec0b 100644
--- a/packages/streaming/package.json
+++ b/packages/streaming/package.json
@@ -10,6 +10,7 @@
"lint": "eslint src",
"formatting": "oxfmt src --check",
"format": "oxfmt src",
+ "test": "bun test src",
"make": "tsgo -d && bun --env-file=../.env.bundle bundle.ts"
},
"author": "Jonny Burger <[email protected]>",
diff --git a/packages/streaming/src/index.ts b/packages/streaming/src/index.ts
index bfc6dc8c54..f2e219ab52 100644
--- a/packages/streaming/src/index.ts
+++ b/packages/streaming/src/index.ts
@@ -1,2 +1,3 @@
export {makeStreamPayloadMessage} from './make-stream-payload-message';
export {makeStreamer} from './make-streamer';
+export type {GetPayloadSink, PayloadSink} from './make-streamer';
diff --git a/packages/streaming/src/make-streamer.ts b/packages/streaming/src/make-streamer.ts
index f4ee894a7b..0c3d83b0e9 100644
--- a/packages/streaming/src/make-streamer.ts
+++ b/packages/streaming/src/make-streamer.ts
@@ -1,11 +1,26 @@
export const streamingKey = 'remotion_buffer:';
+export type PayloadSink = {
+ write: (data: Uint8Array) => void | Promise<void>;
+ end: () => void | Promise<void>;
+};
+
+export type GetPayloadSink = (
+ statusType: 'success' | 'error',
+ nonce: string,
+ length: number,
+) => PayloadSink | null;
+
export const makeStreamer = (
onMessage: (
statusType: 'success' | 'error',
nonce: string,
data: Uint8Array,
) => void,
+ // If a sink is returned for a message, its payload is streamed into the
+ // sink piece by piece instead of being accumulated in memory. `onMessage`
+ // is then called with an empty payload after the sink has ended.
+ getPayloadSink: GetPayloadSink | null = null,
) => {
const separator = new Uint8Array(streamingKey.length);
for (let i = 0; i < streamingKey.length; i++) {
@@ -17,6 +32,12 @@ export const makeStreamer = (
let missingData: null | {
dataMissing: number;
} = null;
+ let activeSink: null | {
+ sink: PayloadSink;
+ remaining: number;
+ nonce: string;
+ statusType: 'success' | 'error';
+ } = null;
const findSeparatorIndex = () => {
let searchIndex = 0;
@@ -40,7 +61,7 @@ export const makeStreamer = (
}
};
- const processInput = () => {
+ const processInput = (): void | Promise<void> => {
let separatorIndex = findSeparatorIndex(); // Start checking for the first byte of the separator
if (separatorIndex === -1) {
return;
@@ -99,6 +120,48 @@ export const makeStreamer = (
const length = Number(lengthString);
const status = Number(statusString);
+ const statusType = status === 1 ? 'error' : 'success';
+
+ const sink = getPayloadSink
+ ? getPayloadSink(statusType, nonceString, length)
+ : null;
+ if (sink) {
+ const payloadStart = separatorIndex + 1;
+ const available = Math.min(outputBuffer.length - payloadStart, length);
+ const payloadPiece = outputBuffer.subarray(
+ payloadStart,
+ payloadStart + available,
+ );
+ // Copy the remainder so the current backing buffer can be released
+ const rest = new Uint8Array(
+ outputBuffer.subarray(payloadStart + available),
+ );
+ outputBuffer = new Uint8Array(0);
+ missingData = null;
+
+ return (async () => {
+ if (available > 0) {
+ await sink.write(payloadPiece);
+ }
+
+ if (available < length) {
+ activeSink = {
+ sink,
+ remaining: length - available,
+ nonce: nonceString,
+ statusType,
+ };
+ return;
+ }
+
+ await sink.end();
+ onMessage(statusType, nonceString, new Uint8Array(0));
+ if (rest.length > 0) {
+ outputBuffer = rest;
+ return processInput();
+ }
+ })();
+ }
const dataLength = outputBuffer.length - separatorIndex - 1;
if (dataLength < length) {
@@ -120,10 +183,42 @@ export const makeStreamer = (
separatorIndex + Number(lengthString) + 1,
);
- processInput();
+ return processInput();
+ };
+
+ // Returns the bytes that belong to the next message, if any
+ const feedSink = async (data: Uint8Array): Promise<Uint8Array | null> => {
+ if (!activeSink) {
+ throw new Error('No active sink');
+ }
+
+ const take = Math.min(activeSink.remaining, data.length);
+ // Awaiting each write applies backpressure to the caller
+ await activeSink.sink.write(data.subarray(0, take));
+ activeSink.remaining -= take;
+
+ if (activeSink.remaining > 0) {
+ return null;
+ }
+
+ const {sink, nonce, statusType} = activeSink;
+ activeSink = null;
+ await sink.end();
+ onMessage(statusType, nonce, new Uint8Array(0));
+
+ const leftover = data.subarray(take);
+ return leftover.length > 0 ? leftover : null;
};
- const onData = (data: Uint8Array) => {
+ const onDataInner = (data: Uint8Array): void | Promise<void> => {
+ if (activeSink) {
+ return feedSink(data).then((leftover) => {
+ if (leftover) {
+ return onDataInner(leftover);
+ }
+ });
+ }
+
unprocessedBuffers.push(data);
if (missingData) {
@@ -150,7 +245,22 @@ export const makeStreamer = (
unprocessedBuffers = [];
- processInput();
+ return processInput();
+ };
+
+ // When payload sinks are in use, processing may be asynchronous. Serialize
+ // the handling of incoming data so callers that do not await `onData` still
+ // get correct behavior. Without sinks, processing is fully synchronous and
+ // behaves exactly as before.
+ let chain: Promise<void> = Promise.resolve();
+
+ const onData = (data: Uint8Array): void | Promise<void> => {
+ if (!getPayloadSink) {
+ return onDataInner(data);
+ }
+
+ chain = chain.then(() => onDataInner(data));
+ return chain;
};
return {
@@ -159,6 +269,15 @@ export const makeStreamer = (
clear: () => {
unprocessedBuffers = [];
outputBuffer = new Uint8Array(0);
+ if (activeSink) {
+ // Best-effort: close the sink so no file descriptor is leaked
+ // if the stream aborted mid-payload
+ const {sink} = activeSink;
+ activeSink = null;
+ try {
+ Promise.resolve(sink.end()).catch(() => undefined);
+ } catch {}
+ }
},
};
};
diff --git a/packages/streaming/src/test/make-streamer.test.ts b/packages/streaming/src/test/make-streamer.test.ts
new file mode 100644
index 0000000000..f3f88115dc
--- /dev/null
+++ b/packages/streaming/src/test/make-streamer.test.ts
@@ -0,0 +1,222 @@
+import {expect, test} from 'bun:test';
+import {makeStreamPayloadMessage} from '../make-stream-payload-message';
+import type {PayloadSink} from '../make-streamer';
+import {makeStreamer} from '../make-streamer';
+
+type ReceivedMessage = {
+ statusType: 'success' | 'error';
+ nonce: string;
+ data: Uint8Array;
+};
+
+const concat = (arrays: Uint8Array[]) => {
+ const total = arrays.reduce((acc, val) => acc + val.length, 0);
+ const result = new Uint8Array(total);
+ let offset = 0;
+ for (const arr of arrays) {
+ result.set(arr, offset);
+ offset += arr.length;
+ }
+
+ return result;
+};
+
+const splitIntoPieces = (data: Uint8Array, pieceSize: number) => {
+ const pieces: Uint8Array[] = [];
+ for (let i = 0; i < data.length; i += pieceSize) {
+ pieces.push(data.subarray(i, Math.min(i + pieceSize, data.length)));
+ }
+
+ return pieces;
+};
+
+test('should buffer messages when no payload sink is given', () => {
+ const received: ReceivedMessage[] = [];
+ const {onData} = makeStreamer((statusType, nonce, data) => {
+ received.push({statusType, nonce, data: new Uint8Array(data)});
+ });
+
+ const body = new TextEncoder().encode('hello world');
+ const wire = makeStreamPayloadMessage({nonce: '1', status: 0, body});
+
+ for (const piece of splitIntoPieces(wire, 3)) {
+ onData(piece);
+ }
+
+ expect(received.length).toBe(1);
+ expect(received[0].statusType).toBe('success');
+ expect(received[0].nonce).toBe('1');
+ expect(new TextDecoder().decode(received[0].data)).toBe('hello world');
+});
+
+test('should stream payload into sink instead of buffering', async () => {
+ const received: ReceivedMessage[] = [];
+ const sinkWrites: Uint8Array[] = [];
+ let sinkEnded = false;
+ let sinkEndedBeforeMessage = false;
+ let requestedLength: number | null = null;
+
+ const sink: PayloadSink = {
+ write: (data) => {
+ sinkWrites.push(new Uint8Array(data));
+ },
+ end: () => {
+ sinkEnded = true;
+ },
+ };
+
+ const {onData} = makeStreamer(
+ (statusType, nonce, data) => {
+ sinkEndedBeforeMessage = sinkEnded;
+ received.push({statusType, nonce, data: new Uint8Array(data)});
+ },
+ (_statusType, nonce, length) => {
+ if (nonce !== '4') {
+ return null;
+ }
+
+ requestedLength = length;
+ return sink;
+ },
+ );
+
+ // A large binary payload that gets a sink, followed by a JSON-ish message
+ // that stays buffered
+ const binaryBody = new Uint8Array(100_000).map((_, i) => i % 256);
+ const jsonBody = new TextEncoder().encode('{"rendered": 5}');
+ const wire = concat([
+ makeStreamPayloadMessage({nonce: '4', status: 0, body: binaryBody}),
+ makeStreamPayloadMessage({nonce: '1', status: 0, body: jsonBody}),
+ ]);
+
+ for (const piece of splitIntoPieces(wire, 1024)) {
+ await onData(piece);
+ }
+
+ expect(requestedLength as number | null).toBe(binaryBody.length);
+ expect(sinkEnded).toBe(true);
+ expect(concat(sinkWrites)).toEqual(binaryBody);
+
+ expect(received.length).toBe(2);
+ // The sinked message is delivered with an empty payload after the sink
+ // has ended
+ expect(received[0].nonce).toBe('4');
+ expect(received[0].data.length).toBe(0);
+ expect(sinkEndedBeforeMessage).toBe(true);
+ expect(received[1].nonce).toBe('1');
+ expect(new TextDecoder().decode(received[1].data)).toBe('{"rendered": 5}');
+});
+
+test('should apply backpressure from an async sink', async () => {
+ const sinkWrites: Uint8Array[] = [];
+ let pendingWrites = 0;
+ let maxPendingWrites = 0;
+
+ const sink: PayloadSink = {
+ write: async (data) => {
+ pendingWrites++;
+ maxPendingWrites = Math.max(maxPendingWrites, pendingWrites);
+ await new Promise((resolve) => {
+ setTimeout(resolve, 1);
+ });
+ sinkWrites.push(new Uint8Array(data));
+ pendingWrites--;
+ },
+ end: () => {},
+ };
+
+ const {onData} = makeStreamer(
+ () => {},
+ () => sink,
+ );
+
+ const body = new Uint8Array(10_000).map((_, i) => (i * 7) % 256);
+ const wire = makeStreamPayloadMessage({nonce: '4', status: 0, body});
+
+ for (const piece of splitIntoPieces(wire, 512)) {
+ await onData(piece);
+ }
+
+ expect(maxPendingWrites).toBe(1);
+ expect(concat(sinkWrites)).toEqual(body);
+});
+
+test('should end the active sink when cleared after an aborted stream', async () => {
+ let sinkEnded = false;
+
+ const {onData, clear} = makeStreamer(
+ () => {},
+ () => ({
+ write: () => {},
+ end: () => {
+ sinkEnded = true;
+ },
+ }),
+ );
+
+ const body = new Uint8Array(10_000).fill(3);
+ const wire = makeStreamPayloadMessage({nonce: '4', status: 0, body});
+
+ // Deliver only part of the payload, then abort
+ await onData(wire.subarray(0, 5000));
+ expect(sinkEnded).toBe(false);
+
+ clear();
+ // clear() is synchronous; sink.end() is invoked best-effort
+ await Promise.resolve();
+ expect(sinkEnded).toBe(true);
+
+ // After clearing, a new message must be parseable from scratch
+ let received = 0;
+ const fullWire = makeStreamPayloadMessage({
+ nonce: '4',
+ status: 0,
+ body: new Uint8Array(100).fill(1),
+ });
+ const streamerAfterRetry = makeStreamer(
+ () => {
+ received++;
+ },
+ () => ({write: () => {}, end: () => {}}),
+ );
+ await streamerAfterRetry.onData(fullWire);
+ expect(received).toBe(1);
+});
+
+test('should handle multiple sinked messages and messages split mid-header', async () => {
+ const sinks: Record<string, Uint8Array[]> = {};
+ const received: ReceivedMessage[] = [];
+
+ const {onData} = makeStreamer(
+ (statusType, nonce, data) => {
+ received.push({statusType, nonce, data: new Uint8Array(data)});
+ },
+ (_statusType, nonce) => {
+ sinks[nonce] = sinks[nonce] ?? [];
+ const writes = sinks[nonce];
+ return {
+ write: (data) => {
+ writes.push(new Uint8Array(data));
+ },
+ end: () => {},
+ };
+ },
+ );
+
+ const videoBody = new Uint8Array(5000).fill(7);
+ const audioBody = new Uint8Array(3000).fill(9);
+ const wire = concat([
+ makeStreamPayloadMessage({nonce: '4', status: 0, body: videoBody}),
+ makeStreamPayloadMessage({nonce: '5', status: 1, body: audioBody}),
+ ]);
+
+ // Piece size chosen so that message boundaries fall mid-header
+ for (const piece of splitIntoPieces(wire, 7)) {
+ await onData(piece);
+ }
+
+ expect(concat(sinks['4'])).toEqual(videoBody);
+ expect(concat(sinks['5'])).toEqual(audioBody);
+ expect(received.map((r) => r.nonce)).toEqual(['4', '5']);
+ expect(received[1].statusType).toBe('error');
+});