Enables Lambdas to return responses larger than 6MB by offloading the content to S3 and returning a reference to the S3 file.
Limitations
- This implementation currently provides support for API Gateway with Lambda Proxy Integration only.
- There are plans to extend this work as described here #issue-1
When a client can handle a Large Response, it must send a request with the HTTP Header Accept: application/large-response.vnd+json. The application/large-response.vnd+json is a custom MIME type indicating that the client agrees to receive a large response payload when necessary. The response body for the large-response.vnd+json MIME type is in the following format:
{
"$payload_ref": "http://<s3 file reference link>"
}If the client provides the large response MIME type, the Lambda will not log an error using Log.error. Instead, it will rewrite the original response with a reference to the offloaded large payload. Furthermore, the rewritten response will include the HTTP header Content-Type with the value application/large-response.vnd+json.
When the client doesn't provide the large response MIME type, and prefers to deal with the large response as a bad request instead of an HTTP 500, the client can send the Handle-Large-Response: true header. The Lambda will rewrite the original response with a custom message and HTTP status code 413 (Payload Too Large). This enables the client to detect a large response and handle it accordingly, by calling the API with a more strict filtering criteria.
If the client does not provide the large response MIME type, the Lambda will log an error with Log.error and rewrite the original response with a custom message (can be configured) and HTTP status code 413 (Payload Too Large).
Supported Parameters:
| Parameter | Type | Description |
|---|---|---|
| thresholdWarn | number |
Warning threshold level (percentage of sizeLimitInMB), e.g: 0.80 |
| thresholdError | number |
Error threshold level (percentage of sizeLimitInMB), e.g: 0.90 |
| sizeLimitInMB | number |
Maximum allowed size limit in MB, e.g 6 |
| outputBucket | string |
Identifier or name of the output S3 bucket |
| customErrorMessage | string | (event:APIGatewayProxyEventV2) => string |
Custom error message to be returned when the response is too large and the client does not support large responses (no accept header) |
| groupRequestsBy | function - mapper |
Function to group requests, based on API Gateway event V2. Defaults to 'all' |
Example Usage:
withLargeResponseHandler({
thresholdWarn: 0.85, // 85% of the limit = 5.1MB
thresholdError: 0.9, // 90% of the limit = 5.4MB
sizeLimitInMB: 6,
}),