API Gateway Image Optimization 502 Error with Response Streaming

# API Gateway Image Optimization 502 Error with Response Streaming

## Problem

When using `NextjsRegionalFunctions` with API Gateway REST API, image optimization requests to `/_next/image` return 502 Bad Gateway errors when Lambda Web Adapter is configured with `AWS_LWA_INVOKE_MODE: "response_stream"`.

## Current Workaround

Setting `AWS_LWA_INVOKE_MODE: "buffered"` resolves the image issue but disables streaming for all routes:

```typescript
nextjsApi: {
dynamicIntegrationProps: {
responseTransferMode: ResponseTransferMode.BUFFERED,
},
},
nextjsFunctions: {
dockerImageFunctionProps: {
environment: {
AWS_LWA_INVOKE_MODE: "buffered",
},
},
},
```

## Desired Behavior

- **`/_next/image` route**: Buffered (binary data compatibility)
- **All other routes**: Streaming (performance benefits for HTML/RSC)

## What Was Tried

### Attempt 1: Different Integration Modes per Route

Modified `NextjsApi` to use different `LambdaIntegration` configurations:

```typescript
// Image route - buffered
const imageIntegration = new LambdaIntegration(serverFunction, {
// No ResponseTransferMode.STREAM
});

// Other routes - streaming
const streamingIntegration = new LambdaIntegration(serverFunction, {
responseTransferMode: ResponseTransferMode.STREAM,
});
```

**Result**: Still getting 502 errors on `/_next/image` route

### Attempt 2: Investigation Points

- Lambda completes successfully (logs show image optimization, caching to S3)
- 502 occurs after Lambda returns to API Gateway
- `binaryMediaTypes: ["*/*"]` is configured on REST API
- Cache handler stores images as JSON with Buffer serialization (UTF-8) which works correctly

## Logs

Lambda logs show successful execution:

```
2026-01-23T02:51:29.112Z cdk-nextjs:proxy request.url: http://0.0.0.0:3000/prod/static/eniko-kis-KsLPTsYaqIQ-unsplash.jpg
2026-01-23T02:51:29.112Z cdk-nextjs:proxy { status: 200, statusText: '', body: null }
2026-01-23T02:51:29.329Z cdk-nextjs:cache-handler:memory MEMORY CACHE SET: DiIwMZnOiQPbxRayEvr9lo9P5I41YqIgVxViv7OwHRU (IMAGE)
2026-01-23T02:51:29.442Z cdk-nextjs:cache-handler:s3 S3 CACHE STORED: DiIwMZnOiQPbxRayEvr9lo9P5I41YqIgVxViv7OwHRU (IMAGE)
END RequestId: fd1e175e-ebe9-45db-b71e-dce054893bb5
REPORT RequestId: fd1e175e-ebe9-45db-b71e-dce054893bb5 Duration: 440.48 ms
```

But API Gateway returns:

```
< HTTP/2 502
< content-type: application/json
< x-amzn-errortype: InternalServerErrorException
{"message": "Internal server error"}
```

## Environment

- Next.js: 16.1.1-canary.19
- Lambda Web Adapter: latest (via Docker)
- API Gateway: REST API with regional endpoint
- CDK: aws-cdk-lib latest

## Next Steps for Debugging

1. **Enable API Gateway execution logs** to see the actual error from Lambda integration
2. **Test with a minimal Lambda function** that returns binary data with streaming enabled to isolate if it's an API Gateway + streaming + binary issue
3. **Check Lambda response format** - ensure Lambda Web Adapter with `response_stream` returns responses in the format API Gateway expects for binary data
4. **Investigate API Gateway streaming limitations** - there may be documented restrictions on binary media types with response streaming
5. **Try AWS_LWA_INVOKE_MODE as request header** - investigate if Lambda Web Adapter can be controlled per-request instead of via environment variable
6. **Consider Lambda Function URLs** - they support response streaming and binary data natively, though would require different architecture

## Code References

- API Gateway integration: `src/nextjs-api.ts` line 248-268
- Lambda Web Adapter config: `src/nextjs-compute/nextjs-functions.ts` line 62
- Workaround: `examples/regional-functions/app.ts` line 60

## Related

- Lambda Web Adapter response streaming: https://github.com/awslabs/aws-lambda-web-adapter#response-streaming
- API Gateway binary media types: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings.html