# Corsica
[](https://travis-ci.org/whatyouhide/corsica)
[](http://inch-ci.org/github/whatyouhide/corsica)
Corsica is a plug and a DSL for handling [CORS][cors-wiki] requests.
[Documentation can be found online][docs].
![Nice Corsica pic][image]
*(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
* Is compliant with the [W3C CORS specification][cors-spec]
* Provides both low-level CORS utilities as well as high-level facilities (like
a built-in plug and a CORS-focused router)
* Handles preflight requests like a breeze
* Never sends any CORS headers if the CORS request is not valid (smaller
requests, yay!)
## Installation
Just add the `:corsica` dependency to your project's `mix.exs`:
```elixir
defp dependencies do
[{:plug, "~> 0.11"},
{:corsica, "~> 0.2"}]
end
```
and then run `$ mix deps.get`. Corsica is a plug and thus depends on
[Plug][plug] too, but you have to explicitly list Plug as a dependency of your
project (since the dependency is `optional: true` in Corsica).
## Overview
You can use Corsica both as a plug as well as a router generator. To use it as a
plug, just plug it into your plug pipeline:
```elixir
defmodule MyApp.Endpoint do
plug Logger
plug Corsica, origins: "http://foo.com"
plug MyApp.Router
end
```
To gain finer control over which resources are CORS-enabled and with what
options, you can use the `Corsica.Router` module:
```elixir
defmodule MyApp.CORS do
use Corsica.Router
@opts [
origins: ["http://foo.com", "http://bar.com"],
allow_credentials: true,
max_age: 600,
]
resource "/public/*", Keyword.merge(@opts, origins: "*")
resource "/*", @opts
end
defmodule MyApp.Endpoint do
plug Logger
plug MyApp.CORS
plug MyApp.Router
end
```
This is only a brief overview of what Corsica can do. To find out more, head to
the [online documentation][docs].
## 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][cors-spec], 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](https://help.github.com/articles/using-pull-requests/)). 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:
```bash
$ 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](LICENSE.txt).
[image]: http://i.imgur.com/n2DZpEU.jpg
[docs]: https://hexdocs.pm/corsica
[cors-wiki]: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing
[cors-spec]: http://www.w3.org/TR/cors
[plug]: https://github.com/elixir-lang/plug
