Skip to content

Commit cddb34f

Browse files
perf(cli): cloud render downloads the finished video over parallel connections (#5864)
* perf(cli): cloud render checks render status every 2 seconds instead of 10 A finished render was noticed up to 10 s late. Polling every 2 s cuts that wait to at most 2 s and stays well under the status endpoint's rate limit. `--poll-interval` still overrides it. * perf(cli): cloud render downloads the finished video over parallel connections The first request asks for the first 8 MB. When the server answers 206 with the full size, the rest of the file is fetched in up to 7 more ranged requests at once and each part is written at its offset into the staged file. A server that ignores Range (200), a small file, or an empty file is still fetched in one request. A failed part cancels the others and the existing output is kept, as before.
1 parent d369159 commit cddb34f

8 files changed

Lines changed: 204 additions & 45 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1827,7 +1827,7 @@ Lifecycle and control:
18271827
| `--callback-id` | Opaque tracking ID echoed in webhook payloads |
18281828
| `--asset-id` | Skip zip and upload; submit an already-uploaded composition. Mutually exclusive with the project dir and `--url`. |
18291829
| `--url` | Submit a public HTTPS zip URL. Same mutual exclusion as `--asset-id`. |
1830-
| `--poll-interval` | Poll cadence in seconds (default 10) |
1830+
| `--poll-interval` | Poll cadence in seconds (default 2) |
18311831
| `--max-wait` | Maximum poll duration in minutes (default 60) |
18321832
| `--idempotency-key` | `Idempotency-Key` for safe retries. 1–255 characters from `[A-Za-z0-9_:.-]`. |
18331833
| `--json` | Machine-readable JSON instead of human progress |

‎packages/cli/src/cloud/download.test.ts‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ import {
1010
symlinkSync,
1111
writeFileSync,
1212
} from "node:fs";
13+
import { createServer, type Server } from "node:http";
14+
import type { AddressInfo } from "node:net";
1315
import { tmpdir } from "node:os";
1416
import { join } from "node:path";
1517
import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -30,6 +32,57 @@ function makeErrorFetch(status: number, statusText = "Not Found"): typeof fetch
3032
return (async () => new Response("nope", { status, statusText })) as unknown as typeof fetch;
3133
}
3234

35+
interface RangeServer {
36+
url: string;
37+
ranges: (string | undefined)[];
38+
close: () => Promise<void>;
39+
}
40+
41+
async function serveBytes(
42+
body: Buffer,
43+
options: { honourRange: boolean; failRangeStart?: number },
44+
): Promise<RangeServer> {
45+
const ranges: (string | undefined)[] = [];
46+
const server: Server = createServer((req, res) => {
47+
ranges.push(req.headers.range);
48+
const match = /^bytes=(\d+)-(\d+)$/.exec(req.headers.range ?? "");
49+
if (!options.honourRange || !match) {
50+
res.writeHead(200, { "content-length": body.length }).end(body);
51+
return;
52+
}
53+
const start = Number(match[1]);
54+
if (start >= body.length) {
55+
res.writeHead(416, { "content-range": `bytes */${body.length}` }).end();
56+
return;
57+
}
58+
const end = Math.min(Number(match[2]), body.length - 1);
59+
res.writeHead(206, {
60+
"content-length": end - start + 1,
61+
"content-range": `bytes ${start}-${end}/${body.length}`,
62+
});
63+
if (start === options.failRangeStart) {
64+
res.write(body.subarray(start, start + 1024), () => res.destroy());
65+
return;
66+
}
67+
res.end(body.subarray(start, end + 1));
68+
});
69+
await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
70+
const { port } = server.address() as AddressInfo;
71+
return {
72+
url: `http://127.0.0.1:${port}/video.mp4`,
73+
ranges,
74+
close: () => new Promise((resolve) => server.close(() => resolve())),
75+
};
76+
}
77+
78+
const MiB = 1024 * 1024;
79+
80+
function patternBytes(length: number): Buffer {
81+
const bytes = Buffer.alloc(length);
82+
for (let i = 0; i < length; i++) bytes[i] = (i * 31 + (i >> 13)) & 0xff;
83+
return bytes;
84+
}
85+
3386
describe("cloud/download", () => {
3487
let dir: string;
3588
beforeEach(() => {
@@ -221,4 +274,60 @@ describe("cloud/download", () => {
221274
expect(readdirSync(join(dir, "root")).sort()).toEqual(["sub"]);
222275
},
223276
);
277+
278+
describe("over HTTP", () => {
279+
const servers: RangeServer[] = [];
280+
afterEach(async () => {
281+
await Promise.all(servers.splice(0).map((server) => server.close()));
282+
});
283+
async function serve(...args: Parameters<typeof serveBytes>) {
284+
const server = await serveBytes(...args);
285+
servers.push(server);
286+
return server;
287+
}
288+
289+
it("splits a large file into parallel ranged requests", async () => {
290+
const body = patternBytes(60 * MiB + 123);
291+
const server = await serve(body, { honourRange: true });
292+
const dest = join(dir, "out.mp4");
293+
const result = await downloadToFile(server.url, dest);
294+
expect(result.bytes).toBe(body.length);
295+
expect(readFileSync(dest).equals(body)).toBe(true);
296+
expect(server.ranges).toHaveLength(8);
297+
expect(server.ranges[0]).toBe(`bytes=0-${8 * MiB - 1}`);
298+
expect(readdirSync(dir)).toEqual(["out.mp4"]);
299+
});
300+
301+
it("fetches small and empty files in one request", async () => {
302+
for (const size of [1000, 0]) {
303+
const body = patternBytes(size);
304+
const server = await serve(body, { honourRange: true });
305+
const dest = join(dir, `out-${size}.mp4`);
306+
await downloadToFile(server.url, dest);
307+
expect(readFileSync(dest).equals(body)).toBe(true);
308+
expect(server.ranges[0]).toBe(`bytes=0-${8 * MiB - 1}`);
309+
expect(server.ranges.slice(1)).toEqual(size === 0 ? [undefined] : []);
310+
}
311+
});
312+
313+
it("streams the whole file in one request when the server ignores Range", async () => {
314+
const body = patternBytes(20 * MiB);
315+
const server = await serve(body, { honourRange: false });
316+
const dest = join(dir, "out.mp4");
317+
await downloadToFile(server.url, dest);
318+
expect(readFileSync(dest).equals(body)).toBe(true);
319+
expect(server.ranges).toEqual([`bytes=0-${8 * MiB - 1}`]);
320+
});
321+
322+
it("keeps the previous output and leaves no staged file when one part fails", async () => {
323+
const body = patternBytes(50 * MiB);
324+
const server = await serve(body, { honourRange: true, failRangeStart: 8 * MiB });
325+
const dest = join(dir, "out.mp4");
326+
writeFileSync(dest, "previous render");
327+
await expect(downloadToFile(server.url, dest)).rejects.toThrow();
328+
expect(server.ranges.length).toBeGreaterThan(1);
329+
expect(readFileSync(dest, "utf8")).toBe("previous render");
330+
expect(readdirSync(dir)).toEqual(["out.mp4"]);
331+
});
332+
});
224333
});

‎packages/cli/src/cloud/download.ts‎

Lines changed: 86 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,15 @@
1313
* existing destination is replaced only after the download succeeds.
1414
*/
1515

16-
import {
17-
chmodSync,
18-
createWriteStream,
19-
mkdirSync,
20-
mkdtempSync,
21-
renameSync,
22-
rmSync,
23-
statSync,
24-
} from "node:fs";
16+
import { chmodSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync } from "node:fs";
17+
import { open } from "node:fs/promises";
2518
import { dirname, join } from "node:path";
2619
import { resolveWritePath } from "@hyperframes/core/atomic-file";
27-
import { pipeline } from "node:stream/promises";
20+
21+
// The first request asks for PART_BYTES; a larger file is split into up to
22+
// CONNECTIONS ranged GETs. A server that ignores Range answers 200 and is streamed.
23+
const PART_BYTES = 8 * 1024 * 1024;
24+
const CONNECTIONS = 8;
2825

2926
export interface DownloadOptions {
3027
signal?: AbortSignal;
@@ -54,44 +51,78 @@ export async function downloadToFile(
5451
options: DownloadOptions = {},
5552
): Promise<DownloadResult> {
5653
const fetchImpl = options.fetchImpl ?? fetch;
57-
const res = await fetchImpl(url, { signal: options.signal });
58-
if (!res.ok) {
59-
throw new Error(`Failed to download ${url}: HTTP ${res.status} ${res.statusText}`);
60-
}
61-
if (!res.body) {
62-
throw new Error(`Failed to download ${url}: empty response body`);
54+
// Cancels the sibling parts when one fails.
55+
const failFast = new AbortController();
56+
const signal = options.signal
57+
? AbortSignal.any([options.signal, failFast.signal])
58+
: failFast.signal;
59+
const get = async (range?: string) => fetchImpl(url, { signal, headers: range ? { range } : {} });
60+
61+
let first = await get(`bytes=0-${PART_BYTES - 1}`);
62+
// 416 (empty file) or a 206 without a total cannot be split: fetch it whole.
63+
if (first.status === 416 || (first.status === 206 && contentRangeTotal(first) === undefined)) {
64+
await first.body?.cancel();
65+
first = await get();
6366
}
67+
assertOk(first, url);
68+
const ranged = first.status === 206;
69+
const total = ranged ? contentRangeTotal(first) : contentLength(first);
6470

6571
mkdirSync(dirname(destPath), { recursive: true });
6672

67-
const totalHeader = res.headers.get("content-length");
68-
const total = totalHeader ? Number.parseInt(totalHeader, 10) : undefined;
69-
const totalOpt = total !== undefined && Number.isFinite(total) ? total : undefined;
70-
7173
// Writes through a caller-selected symlink, as before.
7274
const destination = resolveWritePath(destPath);
7375
const previous = statSync(destination, { throwIfNoEntry: false });
7476
const stage = mkdtempSync(join(dirname(destination), ".hf-download-"));
7577
const stagedFile = join(stage, "download");
7678
let bytes = 0;
79+
let firstError: unknown;
7780
try {
78-
await pipeline(
79-
async function* () {
80-
for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
81-
bytes += chunk.byteLength;
82-
options.onProgress?.(bytes, totalOpt);
83-
yield chunk;
84-
}
85-
if (totalOpt !== undefined && bytes !== totalOpt) {
86-
throw new Error(
87-
`Truncated download: got ${bytes} bytes, expected ${totalOpt} (content-length). ` +
88-
`The presigned URL may have expired mid-transfer — refetch via \`hyperframes cloud get\`.`,
89-
);
90-
}
91-
},
92-
createWriteStream(stagedFile, { flags: "wx" }),
93-
{ signal: options.signal },
81+
const file = await open(stagedFile, "wx");
82+
const writePart = async (res: Response, start: number, length: number | undefined) => {
83+
let written = 0;
84+
for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
85+
await file.write(chunk, 0, chunk.byteLength, start + written);
86+
written += chunk.byteLength;
87+
bytes += chunk.byteLength;
88+
signal.throwIfAborted();
89+
options.onProgress?.(bytes, total);
90+
}
91+
if (length !== undefined && written !== length) {
92+
throw new Error(
93+
`Truncated download: got ${written} bytes, expected ${length} (content-length). ` +
94+
`The presigned URL may have expired mid-transfer — refetch via \`hyperframes cloud get\`.`,
95+
);
96+
}
97+
};
98+
const parts: Promise<void>[] = [];
99+
if (ranged && total !== undefined) {
100+
parts.push(writePart(first, 0, Math.min(PART_BYTES, total)));
101+
const rest = total - PART_BYTES;
102+
const size = Math.ceil(rest / Math.min(CONNECTIONS - 1, Math.ceil(rest / PART_BYTES)));
103+
for (let start = PART_BYTES; start < total; start += size) {
104+
const end = Math.min(start + size, total) - 1;
105+
parts.push(
106+
get(`bytes=${start}-${end}`).then((res) => {
107+
assertOk(res, url);
108+
if (res.status !== 206) throw new Error(`Failed to download ${url}: range ignored`);
109+
return writePart(res, start, end - start + 1);
110+
}),
111+
);
112+
}
113+
} else {
114+
parts.push(writePart(first, 0, total));
115+
}
116+
await Promise.all(
117+
parts.map((part) =>
118+
part.catch((error: unknown) => {
119+
firstError ??= error;
120+
failFast.abort(error);
121+
}),
122+
),
94123
);
124+
await file.close();
125+
if (firstError !== undefined) throw firstError;
95126
options.signal?.throwIfAborted();
96127
if (previous?.isFile()) chmodSync(stagedFile, previous.mode & 0o777);
97128
renameSync(stagedFile, destination);
@@ -104,3 +135,22 @@ export async function downloadToFile(
104135
}
105136
return { path: destPath, bytes };
106137
}
138+
139+
function assertOk(res: Response, url: string): void {
140+
if (!res.ok) {
141+
throw new Error(`Failed to download ${url}: HTTP ${res.status} ${res.statusText}`);
142+
}
143+
if (!res.body) {
144+
throw new Error(`Failed to download ${url}: empty response body`);
145+
}
146+
}
147+
148+
function contentLength(res: Response): number | undefined {
149+
const total = Number.parseInt(res.headers.get("content-length") ?? "", 10);
150+
return Number.isFinite(total) ? total : undefined;
151+
}
152+
153+
function contentRangeTotal(res: Response): number | undefined {
154+
const match = /^bytes \d+-\d+\/(\d+)$/.exec(res.headers.get("content-range") ?? "");
155+
return match ? Number(match[1]) : undefined;
156+
}

‎packages/cli/src/cloud/poll.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@ describe("cloud/poll", () => {
4343
});
4444

4545
describe("defaults", () => {
46-
it("matches the documented 10s / 60min defaults", () => {
47-
expect(DEFAULT_POLL_INTERVAL_MS).toBe(10_000);
46+
it("matches the documented 2s / 60min defaults", () => {
47+
expect(DEFAULT_POLL_INTERVAL_MS).toBe(2_000);
4848
expect(DEFAULT_MAX_WAIT_MS).toBe(60 * 60 * 1000);
4949
});
5050
});

‎packages/cli/src/cloud/poll.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
/**
22
* Poll a HyperFrames render until it reaches a terminal state.
33
*
4-
* Defaults: 10s interval, 60min cap — confirmed with the API owner. The
5-
* `start_to_close` timeout on the underlying Temporal workflow is the
4+
* Defaults: 2s interval (well under the status GET's per-user rate limit), 60min cap.
5+
* The `start_to_close` timeout on the underlying Temporal workflow is the
66
* same order of magnitude, so polling longer would only hide a stuck
77
* workflow rather than recover from one.
88
*
@@ -25,7 +25,7 @@ export interface PollOptions {
2525
signal?: AbortSignal;
2626
}
2727

28-
export const DEFAULT_POLL_INTERVAL_MS = 10_000;
28+
export const DEFAULT_POLL_INTERVAL_MS = 2_000;
2929
export const DEFAULT_MAX_WAIT_MS = 60 * 60 * 1000;
3030

3131
const TERMINAL_STATUSES: ReadonlySet<HyperframesRenderStatus> = new Set(["completed", "failed"]);

‎packages/cli/src/commands/cloud/render.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import { failCommand } from "../../utils/commandResult.js";
1616
* `project: {type:"asset_id", asset_id}` shape.
1717
* 5. If `--no-wait`: print the `render_id` and exit immediately.
1818
* Otherwise poll `GET /v3/hyperframes/renders/{id}` every
19-
* `--poll-interval` (default 10s, max 60min). `--callback-url`
19+
* `--poll-interval` (default 2s, max 60min). `--callback-url`
2020
* can be combined with either mode: the webhook always fires when
2121
* the server-side render terminates, independent of whether the
2222
* CLI is still polling.

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
"files": 8
3131
},
3232
"hyperframes-cli": {
33-
"hash": "3c8d1fac9e0a02fe",
33+
"hash": "35688a15a6d0617b",
3434
"files": 11
3535
},
3636
"hyperframes-core": {

‎skills/hyperframes-cli/references/cloud.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ npx hyperframes cloud render --callback-url https://example.com/hf-hook --no-wai
137137
| `--no-wait` | Submit and exit immediately; print the `render_id`. |
138138
| `--callback-url` | HTTPS webhook fired when the render terminates. |
139139
| `--callback-id` | Opaque tracking ID echoed in webhook payloads. |
140-
| `--poll-interval` | Poll cadence in seconds (default `10`). |
140+
| `--poll-interval` | Poll cadence in seconds (default `2`). |
141141
| `--max-wait` | Max poll duration in minutes (default `60`). |
142142

143143
## Managing renders

0 commit comments

Comments
 (0)