RFC: Simplifying CORS #1029

Key information

• RFC PR: feat: module to ease cors configuration #831
• Related issue(s), if known:
• Area: new module
• Meet tenets: Yes

Summary

When working with API Gateway + Lambda, developers need to handle CORS Headers properly, to make sure their API can be called by a web frontend and to avoid cross origin requests to be blocked. This module would simplify adding CORS headers in the response of their Lambda function when used with an API Gateway Proxy.

Motivation

Adding CORS in the response headers is either forgotten (and nothing works as expected), either boring (a lot of boilerplate code, with very specific syntax). With the wish to simplify developer life, Lambda Powertools could bring something.

Proposal

• Adding a new annotation for the function handler method: @CrossOrigin
• When using this annotation with a handler implementing RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent>, the annotation will automatically add the headers Access-Control-Expose-Headers, Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Credentials, Access-Control-Max-Age to the response object.

public class FunctionProxy implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
    @CrossOrigin
    public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
        // CORS headers will be automatically added in the following object:
        return new APIGatewayProxyResponseEvent()
            .withStatusCode(200)
            .withBody(body);
    }
}

• The annotation can obviously be configured to specify the different values (there are some default values to simplify the job of developpers):

Example:

@CrossOrigin(
        origins = "http://origin.com, https://other.origin.com",
        allowedHeaders = "Authorization, Content-Type, X-API-Key",
        methods = "POST, OPTIONS"
)
public APIGatewayProxyResponseEvent handleRequest(final APIGatewayProxyRequestEvent input, final Context context) {
    // ...
}

• The annotation can also be configured with environment variables, to simplify even further and allow configuration in infra as code (SAM for example)

• When using multiple origins in the configuration (comma-separated), the annotation will find the one matching the request and use this specific one in the header, as browsers don't support multiple origins in the header.

Drawbacks

This new module can bring a few additional kb to the lambda package size. It does not use any dependency which is not already in the core module.

Rationale and alternatives

• What other designs have been considered? Why not them? N/A
• What is the impact of not doing this? N/A

Unresolved questions

N/A