@hyperframes/aws-lambda 0.8.209 → 0.8.211

package/dist/_chunks/{chunk-OTRGQBLD.js → chunk-QU5TSGIK.js}

@@ -24,7 +24,7 @@ import {
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync2, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
 import { availableParallelism, tmpdir as tmpdir2 } from "node:os";
 import { basename, join as join2 } from "node:path";
-import { GetAccountSettingsCommand, LambdaClient } from "@aws-sdk/client-lambda";
+import { GetAccountSettingsCommand, InvokeCommand, LambdaClient } from "@aws-sdk/client-lambda";
 import { S3Client } from "@aws-sdk/client-s3";
 import {
   assemble,
@@ -119,6 +119,7 @@ import {
 } from "@aws-sdk/client-s3";
 import { buildStitchedHeader, readMp4Layout } from "@hyperframes/producer/distributed";
 var MIN_PART_BYTES = 5 * 1024 * 1024;
+var HELPER_BATCH_BYTES = 32 * 1024 * 1024;
 var segmentSize = (s) => "bytes" in s ? s.bytes.length : s.end - s.start;
 function planParts(segments, min = MIN_PART_BYTES) {
   const parts = [];
@@ -174,32 +175,79 @@ async function sendPart(s3, part, partNumber, target) {
   );
   return result.ETag;
 }
-async function sendParts(s3, parts, target) {
-  const settled = await Promise.allSettled(
-    parts.map(async (part, index) => {
-      const etag = await sendPart(s3, part, index + 1, target);
-      if (!etag) throw new Error(`[s3Stitch] part ${index + 1} returned no ETag`);
-      return etag;
-    })
-  );
+async function settleAll(tasks) {
+  const settled = await Promise.allSettled(tasks);
   const failure = settled.find(
     (result) => result.status === "rejected"
   );
   if (failure) throw failure.reason;
-  return settled.map((result, index) => ({
-    ETag: result.value,
-    PartNumber: index + 1
-  }));
+  return settled.map((result) => result.value);
+}
+var rangesOnly = (part) => "upload" in part && part.upload.every((s) => "uri" in s) ? part.upload : void 0;
+var rangeBytes = (ranges) => ranges.reduce((total, r) => total + segmentSize(r), 0);
+function helperBatches(parts, maxBatches = Infinity) {
+  const total = parts.reduce((sum, part) => sum + rangeBytes(rangesOnly(part) ?? []), 0);
+  const batchBytes = Math.max(HELPER_BATCH_BYTES, Math.ceil(total / maxBatches));
+  const batches = [];
+  let batch = [];
+  let bytes = 0;
+  parts.forEach((part, index) => {
+    const ranges = rangesOnly(part);
+    if (!ranges) return;
+    batch.push({ partNumber: index + 1, ranges });
+    bytes += rangeBytes(ranges);
+    if (bytes < batchBytes) return;
+    batches.push(batch);
+    batch = [];
+    bytes = 0;
+  });
+  if (batch.length) batches.push(batch);
+  return batches;
+}
+async function sendRangeParts(s3, target, parts) {
+  return settleAll(
+    parts.map(async ({ partNumber, ranges }) => {
+      const etag = await sendPart(s3, { upload: ranges }, partNumber, target);
+      if (!etag) throw new Error(`[s3Stitch] part ${partNumber} returned no ETag`);
+      return etag;
+    })
+  );
 }
-async function uploadParts(s3, parts, destUri, contentType) {
+async function sendParts(s3, parts, target, helper) {
+  const batches = helper ? helperBatches(parts, helper.maxInvocations) : [];
+  const remote = new Set(batches.flat().map((p) => p.partNumber));
+  const local = parts.flatMap(
+    (part, index) => remote.has(index + 1) ? [] : [{ partNumber: index + 1, part }]
+  );
+  const done = await settleAll([
+    ...local.map(async ({ partNumber, part }) => [
+      { PartNumber: partNumber, ETag: await sendPart(s3, part, partNumber, target) }
+    ]),
+    ...batches.map(async (batch) => {
+      const etags = await helper.send(target, batch);
+      return batch.map((p, i) => ({ PartNumber: p.partNumber, ETag: etags[i] }));
+    })
+  ]);
+  const completed = done.flat().sort((a, b) => a.PartNumber - b.PartNumber);
+  const missing = completed.find((p) => !p.ETag);
+  if (missing || completed.length !== parts.length) {
+    throw new Error(`[s3Stitch] part ${missing?.PartNumber ?? "?"} returned no ETag`);
+  }
+  return completed;
+}
+async function uploadParts(s3, parts, destUri, contentType, helper) {
   const { bucket, key } = parseS3Uri(destUri);
   await multipartUpload(
     s3,
     { Bucket: bucket, Key: key, ContentType: contentType },
-    (target) => sendParts(s3, parts, target)
+    (target) => sendParts(s3, parts, target, helper)
   );
 }
-async function stitchMp4InS3(s3, chunkUris, destUri, { audioUri, minPartBytes = MIN_PART_BYTES } = {}) {
+async function stitchMp4InS3(s3, chunkUris, destUri, {
+  audioUri,
+  minPartBytes = MIN_PART_BYTES,
+  helper
+} = {}) {
   const sourceUris = audioUri ? [audioUri, ...chunkUris] : chunkUris;
   const layouts = await Promise.all(
     sourceUris.map((uri) => readMp4Layout((start, end) => getRange(s3, uri, start, end)))
@@ -214,12 +262,24 @@ async function stitchMp4InS3(s3, chunkUris, destUri, { audioUri, minPartBytes =
     }))
   ];
   const parts = planParts(segments, minPartBytes);
-  await uploadParts(s3, parts, destUri, "video/mp4");
+  let helperFallbacks = 0;
+  const helperOrLocal = helper && {
+    maxInvocations: helper.maxInvocations,
+    // A throttled helper (another render may hold the reservation) costs time, not the render.
+    send: (target, batch) => helper.send(target, batch).catch((error) => {
+      helperFallbacks++;
+      console.warn(`[s3Stitch] helper failed, building ${batch.length} parts here:`, error);
+      return sendRangeParts(s3, target, batch);
+    })
+  };
+  await uploadParts(s3, parts, destUri, "video/mp4", helperOrLocal);
   const uploaded = parts.flatMap((part) => "upload" in part ? part.upload : []);
   return {
     fileSize: segments.reduce((total, s) => total + segmentSize(s), 0),
     parts: parts.length,
-    downloadedBytes: uploaded.reduce((total, s) => total + ("uri" in s ? segmentSize(s) : 0), 0)
+    downloadedBytes: uploaded.reduce((total, s) => total + ("uri" in s ? segmentSize(s) : 0), 0),
+    helpers: helper ? helperBatches(parts, helper.maxInvocations).length : 0,
+    helperFallbacks
   };
 }
 
@@ -350,6 +410,9 @@ async function handler(event, deps) {
     await ensureChromePath(deps);
     return { Action: "warm" };
   }
+  if (event.Action === "stitchParts") {
+    return await handleStitchParts(event, deps);
+  }
   const unwrapped = unwrapEvent(event);
   validatePlanProtocolShape(unwrapped);
   validateEventS3Uris(unwrapped);
@@ -508,9 +571,13 @@ async function resolveWorkerConcurrency(event, deps) {
     return DEFAULT_MAX_PARALLEL_CHUNKS;
   }
 }
-async function functionConcurrency(lambda = new LambdaClient({})) {
+function reservedConcurrency() {
   const reserved = Number(process.env.HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY);
-  if (reserved > 0) return reserved;
+  return reserved > 0 ? reserved : void 0;
+}
+async function functionConcurrency(lambda = new LambdaClient({})) {
+  const reserved = reservedConcurrency();
+  if (reserved) return reserved;
   const { AccountLimit } = await lambda.send(new GetAccountSettingsCommand({}));
   const unreserved = AccountLimit?.UnreservedConcurrentExecutions;
   if (unreserved === void 0) throw new Error("no UnreservedConcurrentExecutions in the reply");
@@ -869,7 +936,7 @@ async function handleAssembleV2(event, deps) {
       throw error;
     }
     if (chunksAreStitchedMp4(planDir, event.Cfr === true)) {
-      return await stitchChunksInS3(s3, event, manifest, started);
+      return await stitchChunksInS3(s3, event, manifest, started, deps?.lambda);
     }
     let audioPath = resolvePlanAudioPath(planDir);
     if (event.AudioS3Uri !== null) {
@@ -909,7 +976,7 @@ async function handleAssembleV2(event, deps) {
     cleanupDir(work);
   }
 }
-async function stitchChunksInS3(s3, event, plan2, started) {
+async function stitchChunksInS3(s3, event, plan2, started, lambda) {
   if (event.ChunkS3Uris.length !== plan2.chunkCount) {
     throw new Error(
       `[handler] ${event.ChunkS3Uris.length} chunk URIs for a plan of ${plan2.chunkCount} chunks`
@@ -917,7 +984,8 @@ async function stitchChunksInS3(s3, event, plan2, started) {
   }
   const stitchStarted = Date.now();
   const stitched = await stitchMp4InS3(s3, event.ChunkS3Uris, event.OutputS3Uri, {
-    audioUri: event.AudioS3Uri ?? void 0
+    audioUri: event.AudioS3Uri ?? void 0,
+    helper: stitchHelper(lambda)
   });
   logEvent({
     event: "assemble_stages",
@@ -925,7 +993,9 @@ async function stitchChunksInS3(s3, event, plan2, started) {
     planMs: stitchStarted - started,
     stitchMs: Date.now() - stitchStarted,
     parts: stitched.parts,
-    downloadedBytes: stitched.downloadedBytes
+    downloadedBytes: stitched.downloadedBytes,
+    helpers: stitched.helpers,
+    helperFallbacks: stitched.helperFallbacks
   });
   return {
     Action: "assemble",
@@ -1035,10 +1105,47 @@ function getEventS3Uris(event) {
       ].filter((u) => u != null);
   }
 }
+function stitchHelper(lambda) {
+  const functionName = process.env.HYPERFRAMES_STITCH_FUNCTION?.trim();
+  if (!functionName) return void 0;
+  const client = lambda ?? new LambdaClient({});
+  const reserved = reservedConcurrency();
+  const maxInvocations = reserved ? Math.max(1, reserved - 1) : Infinity;
+  const send = async (target, parts) => {
+    const event = { Action: "stitchParts", ...target, Parts: parts };
+    const response = await client.send(
+      new InvokeCommand({ FunctionName: functionName, Payload: JSON.stringify(event) })
+    );
+    const body = JSON.parse(
+      new TextDecoder().decode(response.Payload)
+    );
+    if (response.FunctionError) {
+      const error = new Error(
+        `[handler] stitchParts on ${functionName} failed: ${body.errorMessage ?? response.FunctionError}`
+      );
+      if (body.errorType) error.name = body.errorType;
+      throw error;
+    }
+    return body.ETags;
+  };
+  return { send, maxInvocations };
+}
+async function handleStitchParts(event, deps) {
+  const { Bucket, Key, UploadId, Parts } = event;
+  assertAllowedBuckets([
+    `s3://${Bucket}/${Key}`,
+    ...Parts.flatMap((part) => part.ranges.map((r) => r.uri))
+  ]);
+  const ETags = await sendRangeParts(deps?.s3 ?? getS3Client(), { Bucket, Key, UploadId }, Parts);
+  return { Action: "stitchParts", ETags };
+}
 function validateEventS3Uris(event) {
+  assertAllowedBuckets(getEventS3Uris(event));
+}
+function assertAllowedBuckets(uris) {
   const allowedBucket = process.env.HYPERFRAMES_RENDER_BUCKET?.trim();
   if (!allowedBucket) return;
-  for (const uri of getEventS3Uris(event)) {
+  for (const uri of uris) {
     const { bucket } = parseS3Uri(uri);
     if (bucket !== allowedBucket) {
       const err = new Error(
@@ -1089,5 +1196,6 @@ export {
   resolveChromeArgs,
   S3PlanV2ArtifactPublisher,
   handler,
-  unwrapEvent
+  unwrapEvent,
+  stitchHelper
 };

package/dist/cdk/index.js

@@ -6,7 +6,7 @@ import {
 // src/cdk/HyperframesRenderStack.ts
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Duration, RemovalPolicy, Size } from "aws-cdk-lib";
+import { ArnFormat, Duration, RemovalPolicy, Size, Stack } from "aws-cdk-lib";
 import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as lambda from "aws-cdk-lib/aws-lambda";
@@ -72,13 +72,26 @@ var HyperframesRenderStack = class extends Construct {
         TMPDIR: "/tmp",
         HYPERFRAMES_LAMBDA_CHROME_SOURCE: chromeSource,
         HYPERFRAMES_RENDER_BUCKET: this.bucket.bucketName,
-        HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: String(props.reservedConcurrency ?? -1)
+        HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: String(props.reservedConcurrency ?? -1),
+        HYPERFRAMES_STITCH_FUNCTION: `${projectName}-render`
       }
     });
     this.bucket.grantReadWrite(this.renderFunction);
     this.renderFunction.addToRolePolicy(
       new iam.PolicyStatement({ actions: ["lambda:GetAccountSettings"], resources: ["*"] })
     );
+    const renderFunctionArnWithoutRoleCycle = Stack.of(this).formatArn({
+      service: "lambda",
+      resource: "function",
+      resourceName: `${projectName}-render`,
+      arnFormat: ArnFormat.COLON_RESOURCE_NAME
+    });
+    this.renderFunction.addToRolePolicy(
+      new iam.PolicyStatement({
+        actions: ["lambda:InvokeFunction"],
+        resources: [renderFunctionArnWithoutRoleCycle]
+      })
+    );
     const stateMachineLogGroup = new logs.LogGroup(this, "RenderStateMachineLogGroup", {
       logGroupName: `/aws/states/${projectName}-render`,
       retention: logs.RetentionDays.ONE_MONTH,

package/dist/events.d.ts

@@ -22,6 +22,21 @@ export type LambdaAction = "plan" | "audio" | "renderChunk" | "assemble";
 export interface WarmEvent {
     Action: "warm";
 }
+/** Assemble hands a helper part of the final mp4's multipart upload: each part's S3 ranges, in order. */
+export interface StitchPartsEvent {
+    Action: "stitchParts";
+    Bucket: string;
+    Key: string;
+    UploadId: string;
+    Parts: {
+        partNumber: number;
+        ranges: {
+            uri: string;
+            start: number;
+            end: number;
+        }[];
+    }[];
+}
 /** Transport protocol selected for one complete distributed render. */
 export type LambdaPlanProtocol = "v1" | "v2";
 /**
@@ -32,7 +47,7 @@ export type LambdaPlanProtocol = "v1" | "v2";
  * handler unwraps both `event.Payload` and `event.Input` before
  * dispatching.
  */
-export type LambdaEvent = PlanEvent | AudioEvent | RenderChunkEvent | AssembleEvent | WarmEvent | {
+export type LambdaEvent = PlanEvent | AudioEvent | RenderChunkEvent | AssembleEvent | WarmEvent | StitchPartsEvent | {
     Payload: LambdaEvent;
 } | {
     Input: LambdaEvent;
@@ -205,4 +220,8 @@ export interface AssembleLambdaResult {
 export interface WarmLambdaResult {
     Action: "warm";
 }
-export type LambdaResult = WarmLambdaResult | PlanLambdaResult | AudioLambdaResult | RenderChunkLambdaResult | AssembleLambdaResult;
+export interface StitchPartsLambdaResult {
+    Action: "stitchParts";
+    ETags: string[];
+}
+export type LambdaResult = WarmLambdaResult | StitchPartsLambdaResult | PlanLambdaResult | AudioLambdaResult | RenderChunkLambdaResult | AssembleLambdaResult;

package/dist/handler.d.ts

@@ -13,6 +13,7 @@
 import { LambdaClient } from "@aws-sdk/client-lambda";
 import { S3Client } from "@aws-sdk/client-s3";
 import { assemble, buildPlanAudio, type ChunkRenderer, plan, planV2WithPublisher } from "@hyperframes/producer/distributed";
+import { type StitchHelper } from "./s3Stitch.js";
 import type { AssembleEvent, AudioEvent, LambdaEvent, LambdaResult, PlanEvent, RenderChunkEvent } from "./events.js";
 /**
  * Optional injection points used by the handler's unit tests. Production
@@ -49,3 +50,8 @@ export interface HandlerDeps {
  */
 export declare function handler(event: LambdaEvent, deps?: HandlerDeps): Promise<LambdaResult>;
 export declare function unwrapEvent(event: LambdaEvent): PlanEvent | AudioEvent | RenderChunkEvent | AssembleEvent;
+/**
+ * Parts S3 cannot copy go to the function the stack names: it just ran the chunks, so it is warm,
+ * and each invocation brings its own network link.
+ */
+export declare function stitchHelper(lambda?: LambdaClient): StitchHelper | undefined;

package/dist/handler.js

@@ -1,10 +1,12 @@
 import {
   handler,
+  stitchHelper,
   unwrapEvent
-} from "./_chunks/chunk-OTRGQBLD.js";
+} from "./_chunks/chunk-QU5TSGIK.js";
 import "./_chunks/chunk-6TIVMKTV.js";
 import "./_chunks/chunk-4CK3RKM2.js";
 export {
   handler,
+  stitchHelper,
   unwrapEvent
 };

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   resolveChromeExecutablePath,
   resolveChromeSource,
   unwrapEvent
-} from "./_chunks/chunk-OTRGQBLD.js";
+} from "./_chunks/chunk-QU5TSGIK.js";
 import {
   InvalidConfigError,
   computeRenderCost,

package/dist/s3Stitch.d.ts

@@ -1,4 +1,5 @@
 import { type S3Client } from "@aws-sdk/client-s3";
+import { type MultipartTarget } from "./s3Transport.js";
 /** Bytes `[start, end)` of an S3 object. */
 interface RangeSegment {
     uri: string;
@@ -13,17 +14,31 @@ export type Part = {
 } | {
     upload: Segment[];
 };
+export interface RangePart {
+    partNumber: number;
+    ranges: RangeSegment[];
+}
+export type SendRangeParts = (target: MultipartTarget, parts: RangePart[]) => Promise<string[]>;
+export interface StitchHelper {
+    send: SendRangeParts;
+    maxInvocations: number;
+}
 export declare function planParts(segments: readonly Segment[], min?: number): Part[];
+export declare function helperBatches(parts: readonly Part[], maxBatches?: number): RangePart[][];
+export declare function sendRangeParts(s3: S3Client, target: MultipartTarget, parts: readonly RangePart[]): Promise<string[]>;
 /** Writes `parts` in order to `destUri`; a failure aborts the upload so no parts linger. */
-export declare function uploadParts(s3: S3Client, parts: readonly Part[], destUri: string, contentType: string): Promise<void>;
+export declare function uploadParts(s3: S3Client, parts: readonly Part[], destUri: string, contentType: string, helper?: StitchHelper): Promise<void>;
 export interface StitchResult {
     fileSize: number;
     parts: number;
     downloadedBytes: number;
+    helpers: number;
+    helperFallbacks: number;
 }
 /** One faststart mp4 at `destUri` from the stitched mp4 chunks at `chunkUris`, plus `audioUri`'s track when given. */
-export declare function stitchMp4InS3(s3: S3Client, chunkUris: readonly string[], destUri: string, { audioUri, minPartBytes }?: {
+export declare function stitchMp4InS3(s3: S3Client, chunkUris: readonly string[], destUri: string, { audioUri, minPartBytes, helper, }?: {
     audioUri?: string;
     minPartBytes?: number;
+    helper?: StitchHelper;
 }): Promise<StitchResult>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/aws-lambda",
-  "version": "0.8.209",
+  "version": "0.8.211",
   "description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
     "ffprobe-static": "^3.1.0",
     "puppeteer-core": "^25.8.0",
     "tar": "^7.4.3",
-    "@hyperframes/producer": "^0.8.209"
+    "@hyperframes/producer": "^0.8.211"
   },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.146",

package/prebuilt/handler-zip.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.8.209",
-  "url": "https://github.com/heygen-com/hyperframes/releases/download/v0.8.209/hyperframes-lambda-handler.zip",
-  "sha256": "45fd9cd14093354d363ab0a7582b8ba2789cadaed676a5bd368837997bb88066",
-  "bytes": 129296570
+  "version": "0.8.211",
+  "url": "https://github.com/heygen-com/hyperframes/releases/download/v0.8.211/hyperframes-lambda-handler.zip",
+  "sha256": "35fc9f082e8a753c517a530b27db89423a4c6c36a0ac0421e3c56d882a4f8c9b",
+  "bytes": 129299191
 }

package/prebuilt/template.yaml

@@ -170,9 +170,21 @@ Resources:
           TMPDIR: /tmp
           HYPERFRAMES_RENDER_BUCKET: !Ref RenderBucket
           HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: !Ref ReservedConcurrency
+          # Assemble spreads the parts S3 cannot copy across the warm function that ran the chunks.
+          HYPERFRAMES_STITCH_FUNCTION: !If
+            - HasVideoFunction
+            - !Sub "${ProjectName}-video"
+            - !Sub "${ProjectName}-render"
       Policies:
         - S3CrudPolicy:
             BucketName: !Ref RenderBucket
+        - Statement:
+            - Effect: Allow
+              Action: lambda:InvokeFunction
+              Resource: !If
+                - HasVideoFunction
+                - !Sub "arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${ProjectName}-video"
+                - !Sub "arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${ProjectName}-render"
         - Statement:
             - Effect: Allow
               Action: s3:AbortMultipartUpload

package/prebuilt/video-function.yaml

@@ -62,6 +62,10 @@ Resources:
               - Effect: Allow
                 Action: lambda:GetAccountSettings
                 Resource: "*"
+              # Stitch helpers, should this function ever run an assemble.
+              - Effect: Allow
+                Action: lambda:InvokeFunction
+                Resource: !Sub "arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:${ProjectName}-video"
       Tags:
         - Key: Project
           Value: !Ref ProjectName
@@ -95,6 +99,7 @@ Resources:
           TMPDIR: /tmp
           HYPERFRAMES_RENDER_BUCKET: !Ref RenderBucket
           HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: !Ref ReservedConcurrency
+          HYPERFRAMES_STITCH_FUNCTION: !Sub "${ProjectName}-video"
       Tags:
         - Key: Project
           Value: !Ref ProjectName

package/prebuilt/video-image.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.8.209",
-  "url": "https://github.com/heygen-com/hyperframes/releases/download/v0.8.209/hyperframes-lambda-video-arm64.oci.tar",
-  "sha256": "b4a69c565bbc12450f04f0b346189cafb82bcdcf78b0e112ae87362be804f372",
-  "bytes": 244675072
+  "version": "0.8.211",
+  "url": "https://github.com/heygen-com/hyperframes/releases/download/v0.8.211/hyperframes-lambda-video-arm64.oci.tar",
+  "sha256": "c8b4eb268c992dda44b20a9cec45c53731e43c06a1eadbac1f42b6a07ce42c96",
+  "bytes": 244679168
 }