Pyjoyment.Plugin.CORS - Cross-Origin Resource Sharing plugin

# Pyjoyment
app.plugin('CORS')

# Pyjoyment.Lite
plugin('CORS')

# The pages of two sites, with their cookies, for the API only
app.plugin(
    'CORS',
    origins=['https://app.example.com', 'https://admin.example.com'],
    credentials=True,
    paths=['/api'],
    max_age=600,
)

Pyjoyment.Plugin.CORS lets the pages of other sites read the responses of the application, with the protocol of CORS of Fetch. It answers a preflight request, an OPTIONS request with Access-Control-Request-Method that a browser sends before a request that a page of another site could not send without CORS, with 204 No Content before the routes, and adds Access-Control-Allow-Origin to the responses, of the actions and the static files alike, for a request with an Origin header of one of its origins. A response that has Access-Control-Allow-Origin already, as one that an action sets, is kept.

A request of an origin that is not one of the origins gets no headers of CORS, so that the browser does not give the response to the page, and its preflight request is answered without them too, so that it reaches no action. CORS protects what a page of another site may read, not what it may request: a form of another site can still post to the application, which the CSRF protection of the forms is for.

With Pyjoyment.Plugin.AllowedHosts, which rejects a request of an origin that is not one of its own with 403 Forbidden, the origins of CORS are among its origins too.

See Pyjoyment.Plugins for a list of plugins that are available by default.

Options

Pyjoyment.Plugin.CORS supports the following options.

credentials

app.plugin('CORS', origins=['https://app.example.com'], credentials=True)

Let the pages send their cookies and the authentication of HTTP with the
requests, with ``Access-Control-Allow-Credentials: true``, defaults to
``False``. It needs the origins of their own, as a browser does not take
``*`` with credentials, and a page of any site that the user visits
would read the responses for the user otherwise.

expose

app.plugin('CORS', expose=['Server-Timing', 'X-Request-Id'])

The headers of the responses, other than the ones that every page may
read, as ``Content-Type``, that a page may read, with
``Access-Control-Expose-Headers``, defaults to none.

headers

app.plugin('CORS', headers=['Authorization', 'Content-Type'])

The headers that the requests of the pages may have, with
``Access-Control-Allow-Headers``, defaults to ``None``, the ones that a
preflight request asks for in ``Access-Control-Request-Headers``.

max_age

app.plugin('CORS', max_age=600)

How long a browser keeps the answer of a preflight request, in seconds,
with ``Access-Control-Max-Age``, defaults to ``None``, for which a
browser keeps it for 5 seconds. Chromium keeps it for 2 hours at most.

methods

app.plugin('CORS', methods=['GET', 'POST'])

The methods that the requests of the pages may have, with
``Access-Control-Allow-Methods``, defaults to ``GET``, ``HEAD``,
``POST``, ``PUT``, ``PATCH`` and ``DELETE``.

origins

app.plugin('CORS', origins=['https://app.example.com', 'http://localhost:5173'])
app.plugin('CORS', origins=[re.compile(r'^https://pr-\d+\.example\.com$')])
app.plugin('CORS', origins=lambda c, origin: origin.endswith('.example.com'))

The origins of the pages that may read the responses, defaults to
``*``, every origin, without credentials. An origin is a scheme, a host
and a port, as ``Origin`` has it, compared without its case, a regular
expression searches it, and a function takes the controller and the
origin, and returns true for an origin that may.

paths

app.plugin('CORS', paths=['/api', re.compile(r'^/v\d+/')])

The paths of the requests that CORS is for, defaults to ``None``, every
path. A path is the one of a request and its subpaths, as ``/api`` of
``/api`` and ``/api/users``, and a regular expression searches the path
of a request.

See also

Pyjoyment, https://mojolicious.org.

It has no counterpart in Mojolicious.

Classes

class Pyjoyment.Plugin.CORS.Pyjoyment_Plugin_CORS[source]

Pyjoyment.Plugin.CORS inherits all methods from Pyjoyment.Plugin and implements the following new ones.

register(app: Pyjoyment_App, conf: dict[str, Any] | None = None) → None[source]
plugin.register(Pyjoyment.new())
plugin.register(Pyjoyment.new(), {'origins': ['https://app.example.com']})

Register the hooks in Pyjoyment application.