Snap.Util.CORS

Add CORS (cross-origin resource sharing) headers to a Snap application. CORS headers can be added either conditionally or unconditionally to the entire site, or you can apply CORS headers to a single route.

To use in a snaplet, simply use wrapSite:

wrapSite $ applyCORS defaultOptions

Applying CORS to a specific response

applyCORS :: MonadSnap m => CORSOptions m -> m () -> m ()

Apply CORS headers to a specific request. This is useful if you only have a single action that needs CORS headers, and you don't want to pay for conditional checks on every request.

You should note that applyCORS needs to be used before you add any method combinators. For example, the following won't do what you want:

method POST $ applyCORS defaultOptions $ myHandler

This fails to work as CORS requires an OPTIONS request in the preflighting stage, but this would get filtered out. Instead, use

applyCORS defaultOptions $ method POST $ myHandler

Option Specification

data CORSOptions m

Specify the options to use when building CORS headers for a response. Most of these options are Handler actions to allow you to conditionally determine the setting of each header.

Constructors

CORSOptions

Fields

• corsAllowOrigin :: m OriginList

  Which origins are allowed to make cross-origin requests.

• corsAllowCredentials :: m Bool

  Whether or not to allow exposing the response when the omit credentials flag is unset.

• corsExposeHeaders :: m (HashSet (CI ByteString))

  A list of headers that are exposed to clients. This allows clients to read the values of these headers, if the response includes them.

• corsAllowedMethods :: m (HashSet HashableMethod)

  A list of request methods that are allowed.

• corsAllowedHeaders :: HashSet ByteString -> m (HashSet ByteString)

  An action to determine which of the request headers are allowed. This action is supplied the parsed contents of Access-Control-Request-Headers.

defaultOptions :: Monad m => CORSOptions m

Liberal default options. Specifies that:

• All origins may make cross-origin requests
• allow-credentials is true.
• No extra headers beyond simple headers are exposed.
• GET, POST, PUT, DELETE and HEAD are all allowed.
• All request headers are allowed.

All options are determined unconditionally.

Origin lists

data OriginList

Used to specify the contents of the Access-Control-Allow-Origin header.

Constructors

Everywhere

Allow any origin to access this resource. Corresponds to Access-Control-Allow-Origin: *

Nowhere

Do not allow cross-origin requests

Origins OriginSet

Allow cross-origin requests from these origins.

data OriginSet

A set of origins. RFC 6454 specifies that origins are a scheme, host and port, so the OriginSet wrapper around a HashSet ensures that each URI constists of nothing more than this.

mkOriginSet :: [URI] -> OriginSet

origins :: OriginSet -> HashSet HashableURI

Internals

newtype HashableURI

A newtype over URI with a Hashable instance.

Constructors

HashableURI URI

Instances

Eq HashableURI

Methods

(==) :: HashableURI -> HashableURI -> Bool

(/=) :: HashableURI -> HashableURI -> Bool

Show HashableURI

Methods

showsPrec :: Int -> HashableURI -> ShowS

show :: HashableURI -> String

showList :: [HashableURI] -> ShowS

Hashable HashableURI

Methods

hashWithSalt :: Int -> HashableURI -> Int

hash :: HashableURI -> Int

newtype HashableMethod

Constructors

HashableMethod Method

Instances

Eq HashableMethod

Methods

(==) :: HashableMethod -> HashableMethod -> Bool

(/=) :: HashableMethod -> HashableMethod -> Bool

Show HashableMethod

Methods

showsPrec :: Int -> HashableMethod -> ShowS

show :: HashableMethod -> String

showList :: [HashableMethod] -> ShowS

Hashable HashableMethod

Methods

hashWithSalt :: Int -> HashableMethod -> Int

hash :: HashableMethod -> Int