feat(event-handler): HTTP response streaming on Lambda and self-hosted

[adrians5j]

Adds incremental HTTP response delivery to Webiny — on self-hosted Node and on AWS Lambda — plus a File Manager "Re-enrich with AI" action that exercises it end to end.

Verified working on both hosting types: self-hosted via webiny-server watch, and on a real AWS deployment through CloudFront with chunks arriving incrementally.

Core primitive

HttpStreamBody (@webiny/event-handler-core) is an explicit marker a route wraps its source in to opt into streaming. Additive — IHttpResponse.body was already any, so no existing route changes. Transports that can stream write chunks as they are produced; transports that cannot call collect().

Duck-typing Symbol.asyncIterator was rejected deliberately: a plain object body could satisfy it accidentally, and ReadableStream's async-iterator support isn't in the DOM types.

Self-hosted

createServerHandler flushes headers, writes per chunk, honours back-pressure, and stops pulling when the client disconnects.

Also fixes a latent bug the streaming path made reachable: the error handler called writeHead(500) unconditionally, which throws ERR_HTTP_HEADERS_SENT once headers are out and masks the real error.

AWS

API Gateway buffers the entire Lambda response regardless of how it's produced, so it cannot stream at all. Streaming needs a Lambda Function URL with InvokeMode: RESPONSE_STREAM, and a Lambda's handler entry is fixed per function — hence a second function off the same bundle (handler.streamHandler), fronted by a Function URL instead of API Gateway.

New transport: Function URL event type, translator (cookies arrive as an array, not a header; no stage prefix to strip), a terminal handler that writes to the response stream, and createStreamLambdaHandler.

The existing API Gateway translator now drains a streaming body instead of failing, so a streaming route still works over that transport as a single buffered response.

Auth

Adds x-webiny-authorization, read ahead of Authorization by both the AWS and self-hosted extractors. Behind CloudFront with Origin Access Control, SigV4 occupies Authorization, so a viewer bearer token can't survive to the origin. A separate header keeps the Function URL private (AWS_IAM + OAC) without depending on that interaction.

Infra

ApiGraphqlStream (Lambda + Function URL, reusing the graphql IAM role, 300s timeout), a CloudFront OAC, and a /stream/* behavior ordered first with compress: false — CloudFront compression buffers chunks and defeats incremental delivery.

File Manager

The AI enrichment logic is extracted out of AiImageEnrichmentTask into Prepare/Apply use cases shared with the new SSE route, so the task and the route can't drift. The route resolves everything it can before opening the stream, so missing file / non-image / no provider / license come back as real status codes rather than buried in a 200.

Frontend adds ApiStreamClient and a generic readServerSentEvents reader, with auth and tenant decorators mirroring the GraphQL client. GraphQLClient couldn't carry this: execute(): Promise<TResult> is a buffered contract by type, and graphql-js 16 has no incremental delivery.

Four bugs found by deploying

Each of these failed silently and would have shipped a non-streaming endpoint that looked fine:

1. rspack tree-shook streamHandler away. Nothing imports an entry's exports, so the unused one went along with every module reachable only from it. handler survived by accident of being first. Fixed by declaring the entry a module library.
2. The WCP telemetry wrapper re-exported only handler. It renames the bundle to _handler.mjs and substitutes a downloaded wrapper, so handler.streamHandler didn't exist in the deployed artifact. Re-exported unwrapped (the streamifyResponse marker must survive) via a namespace import (the self-hosted bundle has no such export, and a named re-export of a missing binding is a hard ESM error).
3. Missing IAM permission. OAC-for-Lambda requires both lambda:InvokeFunctionUrl and lambda:InvokeFunction; with only the first, Lambda denied every signed CloudFront request and the function was never invoked.
4. The prelude was never flushed. The runtime emits it lazily on the first write, so a body-less response (every CORS preflight is 204) sent nothing and Lambda substituted a default 200 application/octet-stream with all headers dropped. A direct streaming invoke returned 0 bytes. Every path now guarantees one write.

Tests

79 new tests across event-handler-core, event-handler-server, event-handler-aws, app, and ai-powerups. The server test gates its producer on the client having read the first chunk, so a buffering transport deadlocks rather than passing.

Reviewer notes

• The prelude flush relies on the runtime's _onBeforeFirstWrite, which isn't public API. Tests can only assert we call write once; if AWS changes that hook it regresses to the silent empty-200.
• We append a re-export to a wrapper downloaded from api.webiny.com/clients/latest.mjs. If that file's shape changes, this breaks.
• library: { type: "module" } is in shared build-tools and affects every function bundle on both hosting types. Both were verified to build and import, but it has the widest blast radius here.
• The /stream/* route is a new public surface; authorization leans on the WCP gate plus UpdateFileUseCase. No route-level permission checks were added.
• The FM button isn't license-gated client-side, so a non-entitled license gets a 403 dialog.
• OAC does not sign request bodies, so a future streaming route that POSTs a body needs the client to send x-amz-content-sha256. The enrich route sends none.

🤖 Generated with Claude Code