Corsica

https://hexdocs.pm/corsica/v2.1.3/
Admin
Corsica is a comprehensive Elixir library that provides low-level functions, plugs, and routers for...
Tokens:3,865
Snippets:44
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example CORS Preflight Plug Router

Source: https://hexdocs.pm/corsica

This example demonstrates how to use send_preflight_resp within a Plug.Router to handle preflight requests for a specific route. It sets up an OPTIONS route that uses send_preflight_resp and a GET route for the actual resource.

```elixir
defmodule MyRouter do
  use Plug.Router
  plug :match
  plug :dispatch

  options "/foo",
    do: Corsica.send_preflight_resp(conn, origins: "*")
  get "/foo",
    do: send_resp(conn, 200, "ok")
end
```

--------------------------------

### Configure Corsica Plug with Wildcard Origin

Source: https://hexdocs.pm/corsica

Use this configuration to allow all origins to access your resources. Ensure '*' is the only value for :origins.

```elixir
plug Corsica, origins: "*"
```

--------------------------------

### Using Corsica as a Plug

Source: https://hexdocs.pm/corsica

Plug Corsica before any router-like plugs to intercept all requests and set CORS headers. This prevents 404 errors for OPTIONS requests.

```elixir
defmodule MyApp.Endpoint do
  plug Head
  plug Corsica, max_age: 600, origins: "*", expose_headers: ~w(X-Foo)
  plug Plug.Static
  plug MyApp.Router
end
```

--------------------------------

### Configure Corsica Plug with Specific Origins

Source: https://hexdocs.pm/corsica

Use this configuration to allow only specific origins to access your resources. Provide a list of allowed origin strings.

```elixir
plug Corsica, origins: ["http://foo.com", "http://bar.com"]
```

--------------------------------

### Corsica Plug Configuration

Source: https://hexdocs.pm/corsica

How to integrate Corsica into an Elixir Plug pipeline to handle CORS requests.

```APIDOC
## Plug Integration

### Description
Integrate Corsica as a plug in your endpoint pipeline to handle CORS requests automatically. It should be placed before router-like plugs to ensure preflight requests are handled correctly.

### Request Example
```elixir
defmodule MyApp.Endpoint do
  plug Head
  plug Corsica, max_age: 600, origins: "*", expose_headers: ~w(X-Foo)
  plug Plug.Static
  plug MyApp.Router
end
```
```

--------------------------------

### Corsica Plug-in Configuration

Source: https://hexdocs.pm/corsica

Configuration options for the Corsica plug-in to manage CORS requests.

```APIDOC
## Corsica Plug-in Configuration

### Description
Configures the Corsica plug-in to handle Cross-Origin Resource Sharing (CORS) requests.

### Method
`plug` (in Elixir/Phoenix context)

### Endpoint
N/A (This is a plug configuration, not a specific API endpoint)

### Parameters

#### Plug Options

- **origins** (regex or `"*"`) - Required - The origin(s) allowed for CORS requests. Can be a regular expression or the wildcard `"*"`.
- **allow_methods** (list of `String.t/0` or `:all`) - Optional - List of HTTP methods allowed in preflight requests. Defaults to `["PUT", "PATCH", "DELETE"]` alongside simple methods.
- **allow_headers** (list of `String.t/0` or `:all`) - Optional - List of HTTP headers allowed in preflight requests. Defaults to `[]` (only simple headers allowed).
- **allow_credentials** (`boolean/0`) - Optional - If `true`, sends the `Access-Control-Allow-Credentials: true` header. Defaults to `false`.
- **allow_private_network** (`boolean/0`) - Optional - If `true`, sets the `Access-Control-Allow-Private-Network` header. Defaults to `false`.
- **expose_headers** (list of `String.t/0`) - Optional - Sets the `Access-Control-Expose-Headers` response header. If not provided, this header is not sent.
- **max_age** (`String.t/0` or `non_neg_integer/0`) - Optional - Sets the `Access-Control-Max-Age` header for preflight requests. If not provided, this header is not sent.
- **telemetry_metadata** (`map/0`) - Optional - Extra telemetry metadata to be included in emitted events. Available since v2.0.0.
- **passthrough_non_cors_requests** (`boolean/0`) - Optional - If `true`, allows non-CORS requests to pass through without strict CORS verification. Defaults to `false`. Available since v2.1.0.

### Request Example
```elixir
plug Corsica, origins: ~r{^https?://(.*\\. )?foo\.com$}, allow_credentials: true
```

### Response Headers

- **access-control-allow-origin** - Always sent. Value is `"*"` if `:origins` is `"*"`, otherwise it's the mirrored request origin if allowed.
- **access-control-allow-methods** - Sent for preflight requests. Value depends on `:allow_methods` configuration.
- **access-control-allow-headers** - Sent for preflight requests. Value depends on `:allow_headers` configuration.
- **access-control-allow-credentials** - Sent if `:allow_credentials` is `true`.
- **access-control-expose-headers** - Sent if `:expose_headers` is configured.
- **access-control-max-age** - Sent for preflight requests if `:max_age` is configured.
- **access-control-allow-private-network** - Sent if `:allow_private_network` is `true`.

### Error Handling
Corsica handles CORS preflight and actual requests according to the CORS specification. Incorrect configurations may lead to browsers blocking cross-origin requests.
```

--------------------------------

### Match Allowed Origins with Regex

Source: https://hexdocs.pm/corsica

Configure Corsica to allow requests from specific origins using a regular expression. This directly influences the `Access-Control-Allow-Origin` header.

```elixir
plug Corsica, origins: ~r{^https?://(.*\\. )?foo\.com$}
```

--------------------------------

### Add simple response headers

Source: https://hexdocs.pm/corsica

Injects CORS headers into a simple CORS request response.

```elixir
@spec put_cors_simple_resp_headers(Plug.Conn.t(), options()) :: Plug.Conn.t()
```

```elixir
conn
|> put_cors_simple_resp_headers(origins: "*", allow_credentials: true)
|> send_resp(200, "Hello!")
```

--------------------------------

### Add preflight response headers

Source: https://hexdocs.pm/corsica

Injects CORS headers into a preflight request response.

```elixir
@spec put_cors_preflight_resp_headers(Plug.Conn.t(), options()) :: Plug.Conn.t()
```

```elixir
put_cors_preflight_resp_headers conn, [
  max_age: 86400,
  allow_headers: ~w(X-Header),
  allow_private_network: true,
  origins: ~r/w+.foo.com$/
]
```

--------------------------------

### Corsica Options Type Definition

Source: https://hexdocs.pm/corsica

Defines the accepted options for Corsica functions and the Corsica plug. The %Options{} struct is used internally for performance.

```elixir
@type options() ::
  keyword()
  | %Corsica.Options{
      allow_credentials: term(),
      allow_headers: term(),
      allow_methods: term(),
      allow_private_network: term(),
      expose_headers: term(),
      max_age: term(),
      origins: term(),
      passthrough_non_cors_requests: term(),
      telemetry_metadata: term()
    }
```

--------------------------------

### put_cors_simple_resp_headers/2

Source: https://hexdocs.pm/corsica

Adds CORS response headers to a simple CORS request.

```APIDOC
## put_cors_simple_resp_headers(conn, opts)

### Description
Adds CORS response headers to a simple CORS request. If the request is invalid or the origin is not allowed, the connection is returned unchanged.

### Parameters
#### Request Body
- **conn** (Plug.Conn.t) - Required - The connection to modify.
- **opts** (options) - Required - Configuration options for CORS headers.

### Response
- **Plug.Conn.t** - The modified connection with CORS headers added.
```

--------------------------------

### preflight_req?/1

Source: https://hexdocs.pm/corsica

Checks if a connection is a CORS preflight request.

```APIDOC
## preflight_req?(conn)

### Description
Checks whether a given connection holds a preflight CORS request. A request is considered a preflight request if the method is 'OPTIONS' and it contains an 'Access-Control-Request-Method' header.

### Parameters
#### Request Body
- **conn** (Plug.Conn.t) - Required - The connection to check.

### Response
- **boolean** - Returns true if it is a preflight request, false otherwise.
```

--------------------------------

### put_cors_preflight_resp_headers/2

Source: https://hexdocs.pm/corsica

Adds CORS response headers to a preflight request.

```APIDOC
## put_cors_preflight_resp_headers(conn, opts)

### Description
Adds CORS response headers to a preflight request. If the request is invalid, the connection is returned unchanged.

### Parameters
#### Request Body
- **conn** (Plug.Conn.t) - Required - The connection to modify.
- **opts** (options) - Required - Configuration options for CORS headers.

### Response
- **Plug.Conn.t** - The modified connection with CORS headers added.
```

--------------------------------

### Check for preflight request

Source: https://hexdocs.pm/corsica

Determines if a connection is a CORS preflight request.

```elixir
@spec preflight_req?(Plug.Conn.t()) :: boolean()
```

--------------------------------

### Corsica Utility Functions

Source: https://hexdocs.pm/corsica

Functions for checking and manipulating CORS requests within a connection.

```APIDOC
## CORS Utility Functions

### cors_req?(conn)
Checks whether a given connection holds a CORS request.

### preflight_req?(conn)
Checks whether a given connection holds a preflight CORS request.

### put_cors_preflight_resp_headers(conn, opts)
Adds CORS response headers to a preflight request to `conn`.

### put_cors_simple_resp_headers(conn, opts)
Adds CORS response headers to a simple CORS request to `conn`.

### send_preflight_resp(conn, status, body, opts)
Sends a CORS preflight response regardless of the request being a valid CORS request or not.
```

--------------------------------

### Send CORS Preflight Response

Source: https://hexdocs.pm/corsica

Sends a CORS preflight response. It assumes nothing about the connection and halts the connection before sending. If the request is valid, CORS headers are set using put_cors_preflight_resp_headers/2.

```elixir
@spec send_preflight_resp(Plug.Conn.t(), 100..599, binary(), options()) ::
  Plug.Conn.t()
```

--------------------------------

### send_preflight_resp Function

Source: https://hexdocs.pm/corsica

Sends a CORS preflight response. This function can be used to manually build a plug that responds to preflight requests.

```APIDOC
## send_preflight_resp/3

### Description
Sends a CORS preflight response regardless of the request being a valid CORS request or not. This function assumes nothing about `conn`. If it's a valid CORS preflight request with an allowed origin, CORS headers are set by calling `put_cors_preflight_resp_headers/2` and the response is sent with status `status` and body `body`. `conn` is halted before being sent.

The response is always sent because if the request is not a valid CORS request, then no CORS headers will be added to the response. This behaviour will be interpreted by the browser as a non-allowed preflight request, as expected.

### Method
POST (implied by preflight request handling)

### Endpoint
N/A (Function used within a Plug)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```elixir
defmodule MyRouter do
  use Plug.Router
  plug :match
  plug :dispatch

  options "/foo",
    do: Corsica.send_preflight_resp(conn, origins: "*")
  get "/foo",
    do: send_resp(conn, 200, "ok")
end
```

### Response
#### Success Response (200)
- **conn** (Plug.Conn.t()) - The connection with CORS headers and response body.

#### Response Example
(Response headers and body depend on `put_cors_preflight_resp_headers/2` and the provided `status` and `body` arguments.)
```

--------------------------------

### cors_req?/1

Source: https://hexdocs.pm/corsica

Checks if a connection is a CORS request by verifying the presence of an Origin header.

```APIDOC
## cors_req?(conn)

### Description
Checks whether a given connection holds a CORS request. It verifies the presence of an 'Origin' request header.

### Parameters
#### Request Body
- **conn** (Plug.Conn.t) - Required - The connection to check.

### Response
- **boolean** - Returns true if it is a CORS request, false otherwise.
```

--------------------------------

### Define origin type

Source: https://hexdocs.pm/corsica

Specifies the allowed origin types for CORS configuration.

```elixir
@type origin() ::
  String.t() | Regex.t() | {module(), function :: atom(), args :: [term()]}
```

--------------------------------

### Check for CORS request

Source: https://hexdocs.pm/corsica

Determines if a connection contains a CORS request by checking for an Origin header.

```elixir
@spec cors_req?(Plug.Conn.t()) :: boolean()
```
Tokens:
Raw