Corsica Documentation

repository·main·Indexed 19 days ago

An Elixir library providing a Plug and Domain Specific Language (DSL) for handling W3C compliant Cross-Origin Resource Sharing (CORS) requests. It supports automatic preflight request handling, global configuration via a plug, and fine-grained route control using Corsica.Router.

Tokens: 880
Snippets: 4
Records: 5
Agent score: 18%

What's inside Corsica

Install Corsica via mix
main
To use Corsica in your Elixir project, add :corsica to your mix.exs dependencies. Note that :plug is also required as a dependency.
```
defp deps do
  [
    {:plug, "~> 1.0"},
    {:corsica, "~> 2.0"}
  ]
end
```
https://github.com/whatyouhide/corsica/blob/main/README.md
Troubleshoot missing CORS headers
main
Corsica is W3C compliant and will not send any CORS response headers if the incoming request is not a valid CORS request. A common mistake is failing to include the Origin header in the request. If the Origin header is missing, Corsica treats the request as a standard request and adds no CORS headers.
To test a CORS request via curl, ensure you include the Origin header:
```
curl localhost:4000 -v -H "Origin: http://foo.com"
```
https://github.com/whatyouhide/corsica/blob/main/README.md
Troubleshoot 'Origin is therefore not allowed access' errors
main
If your browser logs a Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource error, it means your server is not correctly configured to allow the CORS request. This is typically caused by one of three issues:
1. Incorrect Plug Pipeline Order: The Corsica plug (either plug Corsica or the router generated by use Corsica.Router) must be placed higher in your plug pipeline than any plug that sends a response (such as Plug.Router, Phoenix.Router, or Plug.Static). If a router or static file plug handles the request first, Corsica cannot intercept the response to add the necessary CORS headers.
2. Unrecognized Origin: The browser's current URL (the origin) is not included in the :origins option passed to Corsica. Ensure the :origins list contains the exact URL of the client application (e.g., http://localhost:8100) or use "*" to allow all origins.
3. Disallowed Headers: The client is requesting specific headers (via the Access-Control-Request-Headers preflight header) that are not explicitly permitted by your Corsica configuration. You must add these headers to the :allow_headers option in your Corsica setup.
https://github.com/whatyouhide/corsica/blob/main/pages/Common%20issues.md
Use Corsica.Router for fine-grained CORS control
main
If you need different CORS settings for different URL paths, use Corsica.Router. You can define a module that uses Corsica.Router and provides global configuration (like origins, allow_credentials, and max_age), then use the resource/2 macro to define specific CORS policies for different routes.
```
defmodule MyApp.CORS do
  use Corsica.Router,
    origins: ["http://localhost", ~r{^https?://(.*\.)?foo\.com$}],
    allow_credentials: true,
    max_age: 600

  resource "/public/*", origins: "*"
  resource "/*"
end

defmodule MyApp.Endpoint do
  plug Logger
  plug MyApp.CORS
  plug MyApp.Router
end
```
https://github.com/whatyouhide/corsica/blob/main/README.md
Use Corsica as a Plug
main
For a simple setup where the same CORS configuration applies to your entire application, you can use Corsica directly as a plug in your endpoint pipeline. You can specify origins (as a string or list) to restrict which domains can access your resources.
```
defmodule MyApp.Endpoint do
  plug Logger
  plug Corsica, origins: "http://foo.com"
  plug MyApp.Router
end
```
https://github.com/whatyouhide/corsica/blob/main/README.md