NAME

       Mojolicious::Plugin::OpenAPI::Cors - OpenAPI plugin for Cross-Origin Resource Sharing

SYNOPSIS

   Application
       Set "add_preflighted_routes" to 1, if you want "Preflighted" CORS requests to be sent to
       your already existing actions.

         $app->plugin(OpenAPI => {add_preflighted_routes => 1, %openapi_parameters});

       See "register" in Mojolicious::Plugin::OpenAPI for what %openapi_parameters might contain.

   Simple exchange
       The following example will automatically set default CORS response headers after
       validating the request against "openapi_cors_allowed_origins":

         package MyApp::Controller::User;

         sub get_user {
           my $c = shift->openapi->cors_exchange->openapi->valid_input or return;

           # Will only run this part if both the cors_exchange and valid_input was successful.
           $c->render(openapi => {user => {}});
         }

   Using the specification
       It's possible to enable preflight and simple CORS support directly in the specification.
       Here is one example:

         "/user/{id}/posts": {
           "parameters": [
             { "in": "header", "name": "Origin", "type": "string", "pattern": "https?://example.com" }
           ],
           "options": {
             "x-mojo-to": "#openapi_plugin_cors_exchange",
             "responses": {
               "200": { "description": "Cors exchange", "schema": { "type": "string" } }
             }
           },
           "put": {
             "x-mojo-to": "user#add_post",
             "responses": {
               "200": { "description": "Add a new post.", "schema": { "type": "object" } }
             }
           }
         }

       The special part can be found in the "OPTIONS" request It has the "x-mojo-to" key set to
       "#openapi_plugin_cors_exchange". This will enable Mojolicious::Plugin::OpenAPI::Cors to
       take over the route and add a custom callback to validate the input headers using regular
       OpenAPI rules and respond with a "200 OK" and the default headers as listed under
       "openapi.cors_exchange" if the input is valid. The only extra part that needs to be done
       in the "add_post()" action is this:

         sub add_post {
           my $c = shift->openapi->valid_input or return;

           # Need to respond with a "Access-Control-Allow-Origin" header if
           # the input "Origin" header was validated
           $c->res->headers->access_control_allow_origin($c->req->headers->origin)
             if $c->req->headers->origin;

           # Do the rest of your custom logic
           $c->respond(openapi => {});
         }

   Custom exchange
       If you need full control, you must pass a callback to "openapi.cors_exchange":

         package MyApp::Controller::User;

         sub get_user {
           # Validate incoming CORS request with _validate_cors()
           my $c = shift->openapi->cors_exchange("_validate_cors")->openapi->valid_input or return;

           # Will only run this part if both the cors_exchange and valid_input was
           # successful.
           $c->render(openapi => {user => {}});
         }

         # This method must return undef on success. Any true value will be used as an error.
         sub _validate_cors {
           my $c     = shift;
           my $req_h = $c->req->headers;
           my $res_h = $c->res->headers;

           # The following "Origin" header check is the same for both simple and
           # preflighted.
           return "/Origin" unless $req_h->origin =~ m!^https?://whatever.example.com!;

           # The following checks are only valid if preflighted...

           # Check the Access-Control-Request-Headers header
           my $headers = $req_h->header('Access-Control-Request-Headers');
           return "Bad stuff." if $headers and $headers =~ /X-No-Can-Do/;

           # Check the Access-Control-Request-Method header
           my $method = $req_h->header('Access-Control-Request-Methods');
           return "Not cool." if $method and $method eq "DELETE";

           # Set the following header for both simple and preflighted on success
           # or just let the auto-renderer handle it.
           $c->res->headers->access_control_allow_origin($req_h->origin);

           # Set Preflighted response headers, instead of using the default
           if ($c->stash("openapi_cors_type") eq "preflighted") {
             $c->res->headers->header("Access-Control-Allow-Headers" => "X-Whatever, X-Something");
             $c->res->headers->header("Access-Control-Allow-Methods" => "POST, GET, OPTIONS");
             $c->res->headers->header("Access-Control-Max-Age" => 86400);
           }

           # Return undef on success.
           return undef;
         }

DESCRIPTION

       Mojolicious::Plugin::OpenAPI::Cors is a plugin for accepting Preflighted or Simple Cross-
       Origin Resource Sharing requests. See
       <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS> for more details.

       This plugin is loaded by default by Mojolicious::Plugin::OpenAPI.

       Note that this plugin currently EXPERIMENTAL! Please comment on
       <https://github.com/jhthorsen/mojolicious-plugin-openapi/pull/102> if you have any
       feedback or create a new issue.

STASH VARIABLES

       The following "stash variables" can be set in "defaults" in Mojolicious, "to" in
       Mojolicious::Routes::Route or "stash" in Mojolicious::Controller.

   openapi_cors_allowed_origins
       This variable should hold an array-ref of regexes that will be matched against the
       "Origin" header in case the default "openapi_cors_default_exchange_callback" is used.
       Examples:

         $app->defaults(openapi_cors_allowed_origins => [qr{^https?://whatever.example.com}]);
         $c->stash(openapi_cors_allowed_origins => [qr{^https?://whatever.example.com}]);

   openapi_cors_default_exchange_callback
       This value holds a default callback that will be used by "openapi.cors_exchange", unless
       you pass on a $callback. The default provided by this plugin will simply validate the
       "Origin" header against "openapi_cors_allowed_origins".

       Here is an example to allow every "Origin"

         $app->defaults(openapi_cors_default_exchange_callback => sub {
           my $c = shift;
           $c->res->headers->header("Access-Control-Allow-Origin" => "*");
           return undef;
         });

   openapi_cors_default_max_age
       Holds the default value for the "Access-Control-Max-Age" response header set by
       "openapi.cors_preflighted". Examples:

         $app->defaults(openapi_cors_default_max_age => 86400);
         $c->stash(openapi_cors_default_max_age => 86400);

       Default value is 1800.

   openapi_cors_type
       This stash variable is available inside the callback passed on to "openapi.cors_exchange".
       It will be either "preflighted", "real" or "simple".  "real" is the type that comes after
       "preflighted" when the actual request is sent to the server, but with "Origin" header set.

HELPERS

   openapi.cors_exchange
         $c = $c->openapi->cors_exchange($callback);
         $c = $c->openapi->cors_exchange("MyApp::cors_validator");
         $c = $c->openapi->cors_exchange("_some_controller_method");
         $c = $c->openapi->cors_exchange(sub { ... });
         $c = $c->openapi->cors_exchange;

       Used to validate either a simple CORS request, preflighted CORS request or a real request.
       It will be called as soon as the "Origin" request header is seen.

       The $callback will be called with the current Mojolicious::Controller object and must
       return an error or "undef()" on success:

         my $error = $callback->($c);

       The $error must be in one of the following formats:

       • "undef()"

         Returning "undef()" means that the CORS request is valid.

       • A string starting with "/"

         Shortcut for generating a 400 Bad Request response with a header name. Example:

           return "/Access-Control-Request-Headers";

       • Any other string

         Used to generate a 400 Bad Request response with a completely custom message.

       • An array-ref

         Used to generate a completely custom 400 Bad Request response. Example:

           return [{message => "Some error!", path => "/Whatever"}];
           return [{message => "Some error!"}];
           return [JSON::Validator::Error->new];

       On success, the following headers will be set, unless already set by $callback:

       • Access-Control-Allow-Headers

         Set to the header of the incoming "Access-Control-Request-Headers" header.

       • Access-Control-Allow-Methods

         Set to the list of HTTP methods defined in the OpenAPI spec for this path.

       • Access-Control-Allow-Origin

         Set to the "Origin" header in the request.

       • Access-Control-Max-Age

         Set to "openapi_cors_default_max_age".

METHODS

   register
       Called by Mojolicious::Plugin::OpenAPI.

SEE ALSO

       Mojolicious::Plugin::OpenAPI.