Lambda Large Response Middleware

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).

Middleware Configuration:

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,
}),