Dancer::Plugin::CORS - A plugin for using cross origin resource sharing
Cross origin resource sharing is a feature used by modern web browser to bypass
cross site scripting restrictions. A webservice can provide those rules from
which origin a client is allowed to make cross-site requests. This module
helps you to setup such rules.
use Dancer::Plugin::CORS;
get '/foo' => sub { ... };
share '/foo' =>
origin => 'http://localhost/',
credentials => 1,
expose => [qw[ Content-Type ]],
method => 'GET',
headers => [qw[ X-Requested-With ]],
maxage => 7200,
timing => 1,
;
The parameter $route may be any valid path like used
get, post, put, delete or patch but not
option.
Alternatively a Dancer::Route object may be used instead:
$route = post '/' => sub { ... };
share $route => ... ;
Or a arrayref to one or more Routes:
@head_and_get = get '/' => sub { ... };
share \@head_and_get => ...;
This syntax works too:
share [ get ('/' => sub { ... }) ] => ...;
For any route more than one rule may be defined. The order is
relevant: the first matching rule wins.
Following keywords recognized by
%options:
- origin
- This key defines a static origin (scalar), a list (arrayref), a regex or a
subroutine.
If not specified, any origin is allowed.
If a subroutine is used, the first passed parameter is a URI
object. It should return a true value if this origin is allowed to
access the route in question; otherwise false.
origin => sub {
my $host = shift->host;
# allow only from localhost
grep { $host eq $_ } qw(localhost 127.0.0.1 ::1)
}
Hint: a origin consists of protocol, hostname and maybe a
port. Examples:
"http://www.example.com",
"https://securesite.com",
"http://localhost:3000",
"http://127.0.0.1",
"http://[::1]"
- credentials
- This indicates whether cookies, HTTP authentication and/or client-side SSL
certificates may sent by a client. Allowed values are
0 or 1.
This option must be used together with origin.
- expose
- A comma-seperated list of headers, that a client may extract from response
for use in a client application.
- methods
- A arrayref of allowed methods. If no methods are specified, all methods
are allowed.
- method
- A string containing a single supported method. This parameter is
autofilled when share() is used together with
a Dancer::Route object. If no method is specified, any method is
allowed.
- headers
- A arrayref of allowed request headers. In most cases that should be
"[ 'X-Requested-With' ]" when ajax
requests are made. If no headers are specified, all requested headers are
allowed.
- maxage
- A maximum time (in seconds) a client may cache a preflight request. This
can decrease the amount of requests made to the webservice.
- timing
- Allow access to the resource timing information. If set to 1, the header
"Timing-Allow-Origin" is set to the same
value as Access-Control-Allow-Origin. Otherwise, its set to the
value null. If the keyword is not present, no
Timing-Allow-Origin header will be appended to response. See
<http://www.w3.org/TR/resource-timing/#cross-origin-resources> for
more information.
This keyword is a helper for re-using rules for many routes.
See Dancer::Plugin::CORS::Sharing for more information about this
feature.
Please report any bugs or feature requests on the bugtracker website
https://github.com/zurborg/libdancer-plugin-cors-perl/issues
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
David Zurborg <zurborg@cpan.org>
This software is Copyright (c) 2014 by David Zurborg.
This is free software, licensed under:
The ISC License