falcon_cors package

Submodules

falcon_cors.middleware module

class falcon_cors.middleware.CORSMiddleware(cors, default_enabled=True)

This is the middleware that applies a CORS object to requests.

Args:

cors (CORS, required): An instance of CORS. default_enabled (bool, optional): Whether CORS processing should

take place for every resource. Default True.

process_resource(req, resp, resource, *args)

Module contents

This module implements the configuration for handling CORS requests.

class falcon_cors.CORS(**cors_config)

Bases: object

Initialize a CORS object, passing in configuration options. All of the configuration settings are optional, however if none of them are specified the default configuration will simply deny all CORS requests. You can pass this to API for a global configuration. After enabling globally, you can override the settings for a particular resource by setting the ‘cors’ attribute on it to an instance of this class.

Args:

logger(logging.Logger(), optional):

Specifies the logger to use. A basic logger and StreamHandler will be configure for you if none is provided.

allow_all_origins(bool, optional): Specifies whether CORS

should allow requests from all origins. Default is False.

allow_origins_list(list, optional): A list of

origins that are allowed to make CORS requests. Default is empty.

allow_origins_regex(str, optional): A string containing

a Python regular expression that matches origins which are allowed to make CORS requests. Default is None.

allow_all_headers(bool, optional): If True, when the server is

responding to a preflight request it will approve any headers requested by the client via the Access-Control-Request-Headers header, setting each requested header in the value of the Access-Control-Allow-Headers header in the response. Default is False.

allow_headers_list(list, optional): A list of headers which are

allowed values for the Access-Control-Allow-Headers header in response to a preflight request. When the server is responding to a preflight request, it will check each header requested by the client in the Access-Control-Request-Headers header to see if it exists in this list. If it does, it will be included in the Access-Control-Allow-Headers header in the response to the preflight request. Default is empty.

allow_headers_regex(str, optional): A string containing a Python

regular expression that matches headers that should be allowed in response to a preflight request. If this is set, when a preflight request is received by the server, it will try to match each header requested by the client via the Access-Control-Request-Headers header of the request. If the requested header is matched by this regex, it will be included in the value of the Access-Control-Allow-Headers header of the response.

expose_headers_list(list, optional): A list of headers that

should be sent as values to the Access-Control-Expose-Headers header in response to simple or actual requests.

allow_all_methods(bool, optional): Specifies whether all methods

are allowed via CORS requests. Default is False.

allow_methods_list(list, optional): A list of methods which are

allowed via CORS requests. These should be values from falcon.HTTP_METHODS, which are strings like ‘GET’ and ‘PATCH’. Default is empty.

allow_credentials_all_origins(bool, optional): Where or not the

Access-Control-Allow-Credentials should be set to True and set on all responses. Default is False.

allow_credentials_origins_list(list, optional): A list of

origins for which the Access-Control-Allow-Credentials header should be set to True and included with all responses. Default is empty.

allow_credentials_origins_regex(string, optional): A string

containing a Python regular expression matching origins for which the Access-Control-Allow-Credentials header should be set to True and included in all responses. Default is None.

max_age(int, optional): If set to an integer, this value

will be used as the value of the Access-Control-Max-Age header in response to preflight requests. This is in seconds the maximum amount of time a client may cache responses to preflight requests. Default is None (no header sent).

Note:

The arguments above are inclusie, meaning a header, origin, or method will only be disallowed if it doesn’t match ANY specification. First the allow_all directive is checked, then the list directive, then the regex directive if applicable, then list by method if applicable, and lastly regex by method if applicable. For instance, this means if you specify ‘Auth-Key’ in allow_headers_list, it will be allowed for all methods regardless of the values in header_list_By_method.

Note:

Headers are converted to lower-case for you. Methods are converted to upper-case for you. Take note of this if you are writing regular expressions.

Note:

The allow_headers_* settings relate to the Access-Control-Allow-Headers header which is only sent in response to pre-flight requests. This is different from the Access-Control-Expose-Headers header which is set via the expose_headers_list setting and is sent only in response to basic or actual requests.

Warning:

Exercise caution when using the regex enabled settings. It is very easy to misunderstand Python regex syntax and accidentally introduce an unintentionally allowed origin or other vulnerability into your application.

middleware

A property which returns a CORSMiddleware instance

process(req, resp, resource)