Corsica

Corsica is a plug and a DSL for handling CORS requests. Documentation can be found online.

(I had to include a nice pic because, let's be honest, CORS requests aren't the most fun thing in the world, are they?)

Features

• Ignores requests without an Origin header (yay, performance!)
• Handles preflight requests, including invalid requests where the request method or the request headers are not allowed
• Compiles CORS-enabled resources into functions based on pattern-matching in order to take advantage of the optimizations made by the VM (yay, double performance!)
• Is compliant with the CORS specification defined by the W3C.

Installation

Just add the :corsica dependency to your project's mix.exs:

defp dependencies do
  [{:plug, "~> 0.11"},
   {:corsica, "~> 0.1"}]
end

and then run $ mix deps.get. Corsica depends on Plug too, but you have to explicitly list Plug as a dependency of your project (since the dependency is optional: true in Corsica).

Usage

The Corsica module can be used both as a stand-alone plug:

defmodule MyApp.Endpoint do
  plug Corsica,
    origins: ["http://foo.com"],
    max_age: 600,
    allow_headers: ~w(X-Header),
    allow_methods: ~w(GET POST),
    expose_headers: ~w(Content-Type)

  plug Plug.Session
  plug :router
end

as well as a plug generator. Using it as a plug generator allows for finer control over the options and the headers of CORS responses; using the Corsica module in an arbitrary module automatically makes that module a plug that can be used in your application.

defmodule MyApp.CORS do
  use Corsica,
    origins: "*",
    max_age: 600,
    allow_headers: ~w(X-My-Header)

  resources ["/foo", "/bar"], allow_methods: ~w(PUT PATCH)

  resources ["/users"],
    allow_credentials: true,
    allow_methods: ~w(HEAD GET POST PUT PATCH DELETE)
end

# MyApp.CORS can now be used as a regular plug.
defmodule MyApp.Endpoint do
  plug MyApp.CORS
  plug :router
end

This is only a short overview of what Corsica can do; for more detailed information and for a reference on the methods and options that can be used with Corsica, refer to the online documentation.

Contributing

If you find a bug, something unclear (including in the documentation!) or a behaviour that is not compliant with the latest revision of the official CORS specification, please open an issue on GitHub.

If you want to contribute to code or documentation, fork the repository and then open a Pull Request (how-to). Before opening a Pull Request, make sure all the tests passes by running $ mix test in your shell. If you're contributing to documentation, you can preview the generated documentation locally by running:

$ MIX_ENV=docs mix do deps.get, docs

Documentation will be generated in the doc/ directory.

License

MIT © 2015 Andrea Leopardi, see the license file.