snap-core-1.0.5.1: Snap: A Haskell Web Framework (core interfaces and types)

Safe Haskell | None
Language | Haskell2010

Snap.Util.CORS

Contents

- Applying CORS to a specific response
- Option Specification
  - Origin lists
- Internals

Description

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

Synopsis

- applyCORS :: MonadSnap m => CORSOptions m -> m () -> m ()
- data CORSOptions (m :: Type -> Type) = CORSOptions {
  - corsAllowOrigin :: m OriginList
  - corsAllowCredentials :: m Bool
  - corsExposeHeaders :: m (HashSet (CI ByteString))
  - corsAllowedMethods :: m (HashSet HashableMethod)
  - corsAllowedHeaders :: HashSet ByteString -> m (HashSet ByteString)
  }
- defaultOptions :: forall (m :: Type -> Type). Monad m => CORSOptions m
- data OriginList
  - = Everywhere
  - | Nowhere
  - | Origins OriginSet
- data OriginSet
- mkOriginSet :: [URI] -> OriginSet
- origins :: OriginSet -> HashSet HashableURI
- newtype HashableURI = HashableURI URI
- newtype HashableMethod = HashableMethod Method

# Applying CORS to a specific response

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

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 :: Type -> Type) Source #

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 :: forall (m :: Type -> Type). Monad m => CORSOptions m Source #

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 Source #

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 Source #

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 Source #

origins :: OriginSet -> HashSet HashableURI Source #

# Internals

newtype HashableURI Source #

A `newtype` over `URI` with a `Hashable` instance.

Constructors

HashableURI URI |

#### Instances

Instances details

Show HashableURI Source # |
Instance details Defined in Snap.Util.CORS Methods showsPrec :: Int -> HashableURI -> ShowS Source # show :: HashableURI -> String Source # showList :: [HashableURI] -> ShowS Source #
Eq HashableURI Source # |
Instance details Defined in Snap.Util.CORS Methods (==) :: HashableURI -> HashableURI -> Bool Source # (/=) :: HashableURI -> HashableURI -> Bool Source #
Hashable HashableURI Source # |
Instance details Defined in Snap.Util.CORS Methods hashWithSalt :: Int -> HashableURI -> Int Source # hash :: HashableURI -> Int Source #

newtype HashableMethod Source #

Constructors

HashableMethod Method |

#### Instances

Instances details

Show HashableMethod Source # |
Instance details Defined in Snap.Util.CORS Methods showsPrec :: Int -> HashableMethod -> ShowS Source # show :: HashableMethod -> String Source # showList :: [HashableMethod] -> ShowS Source #
Eq HashableMethod Source # |
Instance details Defined in Snap.Util.CORS Methods (==) :: HashableMethod -> HashableMethod -> Bool Source # (/=) :: HashableMethod -> HashableMethod -> Bool Source #
Hashable HashableMethod Source # |
Instance details Defined in Snap.Util.CORS Methods hashWithSalt :: Int -> HashableMethod -> Int Source # hash :: HashableMethod -> Int Source #