### 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() ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.