NAME

Dancer::Plugin::CORS - A plugin for using cross origin resource sharing

VERSION

version 0.13

DESCRIPTION

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.

SYNOPSIS

    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,
        ;

METHODS

share($route, %options)

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.

sharing

This keyword is a helper for re-using rules for many routes.

See Dancer::Plugin::CORS::Sharing for more information about this feature.

BUGS

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.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by David Zurborg.

This is free software, licensed under:

  The ISC License

cpanm Dancer::Plugin::CORS

perl -MCPAN -e shell
install Dancer::Plugin::CORS