Plack:...Origin(3pm)

📦
version 0.014 · 2 versions
  • 0.014 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 0.014 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🌈 Plack::Middleware::CrossOrigin 🌈

aka the page that makes cross-origin requests stop being a whole entire problem, bestie 💖

✨ NAME ✨

Plack::Middleware::CrossOrigin — it adds headers so Cross-Origin Resource Sharing can actually happen. slay.

🎀 SYNOPSIS 🎀

# Allow any WebDAV or standard HTTP request from any location.
builder {
    enable 'CrossOrigin', origins => '*';
    $app;
};

# Allow GET and POST requests from any location, cache results for 30 days.
builder {
    enable 'CrossOrigin',
        origins => '*', methods => ['GET', 'POST'], max_age => 60*60*24*30;
    $app;
};

💖 DESCRIPTION 💖

okay so basically this adds the Cross Origin Request Sharing headers that modern browsers are obsessed with, so that XMLHttpRequest can vibe across domains. ✨ Bonus: in some browsers it also helps protect you against CSRF attacks. two for one, we love that.

It lowkey tries to fully conform to the CORS spec, while still letting you have extra flexibility in the values you specify for the headers. flexible but responsible, the dream.

It also makes sure the response has a Vary: Origin header, so caches don't cause you mysterious problems later. 🦋 no cap, that one matters.

🔥 CORS REQUESTS IN BRIEF 🔥

There are literally two types of CORS requests: simple requests and preflighted requests.

🌸 Simple Requests

A simple request is one that a standard HTML form could've generated. Either a GET or POST request, with no extra headers. For these, the server just processes the request like normal and attaches the correct CORS headers in the response. Then the browser looks at those headers and decides whether to let the client script see the response. server does its thing, browser does the vibe check 👑

💅 Preflighted Requests

If extra headers are specified, or a method other than GET or POST is used, the request has to be preflighted. Meaning: the browser first sends a special request to the server to check if access is even allowed. If the server says yes by responding with the correct headers, then the actual request happens. ask permission first, iconic behaviour ✨

🫶 CSRF Protection 🫶

Some browsers also send the same headers along with cross domain POST requests coming from HTML forms. Those requests get checked against the allowed origins and rejected before they ever reach the rest of your Plack application. 💀 goodbye, sketchy form.

💜 CONFIGURATION 💜

  • origins — a list of allowed origins. Origins should be formatted as a URL scheme and host, with no path info (http://www.example.com). You can specify '*' to allow access from literally any location. Wildcards (*) can also be included in the host to match any part of a host name (e.g. https://*.example.com). At least one origin must be specified for this middleware to do anything at all. This gets matched against the Origin request header, and it controls the Access-Control-Allow-Origin response header. If the origin doesn't match, the request is aborted. no match, no entry.
  • headers — a list of allowed request headers. '*' can be specified to allow any headers. Controls the Access-Control-Allow-Headers response header. It includes a set of headers by default to simplify working with WebDAV and AJAX frameworks:
    • Cache-Control
    • Depth
    • If-Modified-Since
    • User-Agent
    • X-File-Name
    • X-File-Size
    • X-Prototype-Version
    • X-Requested-With
  • methods — a list of allowed methods. '*' can be specified to allow any methods. Controls the Access-Control-Allow-Methods response header. Defaults to all of the standard HTTP and WebDAV methods.
  • max_age — the max length in seconds to cache the response data for. Controls the Access-Control-Max-Age response header. If you don't specify it, the web browser decides how long to use. 🕰️
  • expose_headers — a list of allowed headers to expose to the client. '*' can be specified to allow the browser to see all of the response headers. Controls the Access-Control-Expose-Headers response header.
  • credentials — whether the resource will be allowed with user credentials (cookies, HTTP authentication, and client-side SSL certificates) supplied. Controls the Access-Control-Allow-Credentials response header.
  • continue_on_failure — normally, simple requests with an Origin that hasn't been allowed get stopped before they continue to the main app. If this option is set, the request is allowed to continue, but no CORS headers will be added to the response. This matches how non-allowed requests would be handled if this module wasn't used at all.
🚨 This disables the CSRF protection and is not recommended. It could be needed for applications that need to allow cross-origin HTML form POSTs without whitelisting domains. you've been warned, bestie.

🌈 BROWSER SUPPORT 🌈

Different browsers have different levels of support for CORS headers. the chaos of it all 🙈

Gecko (Firefox, Seamonkey)

Initially supported in Gecko 1.9.1 (Firefox 3.5). Supports the complete CORS spec for XMLHttpRequests.

Does not yet provide the Origin header for CSRF protection (Bugzilla #446344 <https://bugzilla.mozilla.org/show_bug.cgi?id=446344>).

WebKit (Safari, Google Chrome)

Initially supported in Safari 4 and Chrome 3. Supports the complete CORS spec.

The expose_headers feature has been supported since WebKit v535.18 (Safari 6, Chrome 18). Preflighted requests were buggy prior to WebKit v534.19 (Safari 5.1, Chrome 11), but this module uses a workaround where possible (using the Referer header).

Also provides the Origin header for CSRF protection starting with WebKit v528.5 (Chrome 2, Safari 4).

Internet Explorer

Initially supported in IE8. Not supported with the standard XMLHttpRequest object. A separate object, XDomainRequest, must be used. Only GET and POST methods are allowed. No extra headers can be added to the request. Neither the status code or any headers aside from Content-Type can be retrieved from the response. 💀

IE10 supports CORS via the standard XMLHttpRequest object.

Opera

Opera and Opera Mobile support CORS since version 12.

🌟 SEE ALSO 🌟

🍓 CORS Resources

🧚 CSRF Resources

👑 AUTHOR 👑

Graham Knop <haarg@haarg.org>

This software is copyright (c) 2011 by Graham Knop.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

👑 AUTHOR 👑

haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>

🌸 CONTRIBUTORS 🌸

None so far. (bestie… that could be you 👀)

Copyright (c) 2011 the Plack::Middleware::CrossOrigin AUTHOR and CONTRIBUTORS as listed above.

📜 LICENSE 📜

This library is free software and may be distributed under the same terms as perl itself.

and that's the whole page, fr fr 💅 this doc is from perl v5.36.0, dated 2022-11-19 — now go forth and let your XMLHttpRequests cross those origins, no cap 🌈✨

📦 where this page comes from