-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | CORS for WAI
--   
--   This package provides an implemenation of Cross-Origin resource
--   sharing (CORS) for Wai that aims to be compliant with
--   http://www.w3.org/TR/cors.
@package wai-cors
@version 0.2.7

-- | An implemenation of Cross-Origin resource sharing (CORS) for WAI that
--   aims to be compliant with http://www.w3.org/TR/cors.
--   
--   The function simpleCors enables support of simple cross-origin
--   requests. More advanced CORS policies can be enabled by passing a
--   CorsResourcePolicy to the cors middleware.
--   
--   
Note On Security
--   
--   This implementation doens't include any server side enforcement. By
--   complying with the CORS standard it enables the client (i.e. the web
--   browser) to enforce the CORS policy. For application authors it is
--   strongly recommended to take into account the security considerations
--   in section 6.3 of http://www.w3.org/TR/cors. In particular the
--   application should check that the value of the Origin header
--   matches it's expectations.
--   
--   
Websockets
--   
--   Websocket connections don't support CORS and are ignored by this CORS
--   implementation. However Websocket requests usually (at least for some
--   browsers) include the Origin header. Applications are
--   expected to check the value of this header and respond with an error
--   in case that its content doesn't match the expectations.
--   
--   
Example
--   
--   The following is an example how to enable support for simple
--   cross-origin requests for a scotty application.
--   
--   
--   {-# LANGUAGE UnicodeSyntax #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   module Main
--   ( main
--   ) where
--   
--   import Network.Wai.Middleware.Cors
--   import Web.Scotty
--   
--   main ∷ IO ()
--   main = scotty 8080 $ do
--       middleware simpleCors
--       matchAny  "/" $ text "Success"
--   
--   
--   The result of following curl command will include the HTTP response
--   header Access-Control-Allow-Origin: *.
--   
--   
--   curl -i http://127.0.0.1:8888 -H 'Origin: 127.0.0.1' -v
--   
module Network.Wai.Middleware.Cors

-- | Origins are expected to be formated as described in RFC6454
--   (section 6.2). In particular the string * is not a valid
--   origin (but the string null is).
type Origin = ByteString
data CorsResourcePolicy
CorsResourcePolicy :: !Maybe ([Origin], Bool) -> ![Method] -> ![HeaderName] -> !Maybe [HeaderName] -> !Maybe Int -> !Bool -> !Bool -> !Bool -> CorsResourcePolicy

-- | HTTP origins that are allowed in CORS requests.
--   
--   A value of Nothing indicates unrestricted cross-origin sharing
--   and results in * as value for the
--   Access-Control-Allow-Origin HTTP response header. Note if you
--   send *, credentials cannot be sent with the request.
--   
--   A value other than Nothing is a tuple that consists of a list
--   of origins and a Boolean flag that indicates if credentials are used
--   to access the resource via CORS.
--   
--   Origins must be formated as described in RFC6454 (section 6.2).
--   In particular the string * is not a valid origin (but the
--   string null is).
--   
--   Credentials include cookies, authorization headers and TLS client
--   certificates. For credentials to be sent with requests, the
--   withCredentials setting of XmlHttpRequest in the
--   browser must be set to true.
[corsOrigins] :: CorsResourcePolicy -> !Maybe ([Origin], Bool)

-- | HTTP methods that are allowed in CORS requests.
[corsMethods] :: CorsResourcePolicy -> ![Method]

-- | Field names of HTTP request headers that are allowed in CORS requests.
--   Header names that are included in simpleHeaders, except for
--   content-type, are implicitly included and thus optional in
--   this list.
[corsRequestHeaders] :: CorsResourcePolicy -> ![HeaderName]

-- | Field names of HTTP headers that are exposed to the client in the
--   response.
[corsExposedHeaders] :: CorsResourcePolicy -> !Maybe [HeaderName]

-- | Number of seconds that the OPTIONS preflight response may be cached by
--   the client.
--   
--   Tip: Set this to Nothing while testing your CORS
--   implementation, then increase it once you deploy to production.
[corsMaxAge] :: CorsResourcePolicy -> !Maybe Int

-- | If the resource is shared by multiple origins but
--   Access-Control-Allow-Origin is not set to * this may
--   be set to True to cause the server to include a Vary:
--   Origin header in the response, thus indicating that the value of
--   the Access-Control-Allow-Origin header may vary between
--   different requests for the same resource. This prevents caching of the
--   responses which may not apply accross different origins.
[corsVaryOrigin] :: CorsResourcePolicy -> !Bool

-- | If this is True and the request does not include an
--   Origin header the response has HTTP status 400 (bad request)
--   and the body contains a short error message.
--   
--   If this is False and the request does not include an
--   Origin header the request is passed on unchanged to the
--   application.
[corsRequireOrigin] :: CorsResourcePolicy -> !Bool

-- | In the case that
--   
--   
--   
- the request contains an Origin header and
--   
- the client does not conform with the CORS protocol (request is
--   out of scope)
--   
--   
--   then
--   
--   
--   
- the request is passed on unchanged to the application if this
--   field is True or
--   
- an response with HTTP status 400 (bad request) and short error
--   message is returned if this field is False.
--   
--   
--   Note: Your application needs to will receive preflight OPTIONS
--   requests if set to True.
[corsIgnoreFailures] :: CorsResourcePolicy -> !Bool

-- | A CorsResourcePolicy that supports simple cross-origin
--   requests as defined in http://www.w3.org/TR/cors/.
--   
--   
--   
- The HTTP header Access-Control-Allow-Origin is set to
--   *.
--   
- Request methods are constraint to simple methods
--   (GET, HEAD, POST).
--   
- Request headers are constraint to simple request headers
--   (Accept, Accept-Language, Content-Language,
--   Content-Type).
--   
- If the request is a POST request the content type is
--   constraint to simple content types
--   (application/x-www-form-urlencoded,
--   multipart/form-data, text/plain),
--   
- Only simple response headers may be exposed on the client
--   (Cache-Control, Content-Language,
--   Content-Type, Expires, Last-Modified,
--   Pragma)
--   
- The Vary-Origin header is left unchanged (possibly
--   unset).
--   
- If the request doesn't include an Origin header the
--   request is passed unchanged to the application.
--   
- If the request includes an Origin header but does not
--   conform to the CORS protocol (request is out of scope) an
--   response with HTTP status 400 (bad request) and a short error message
--   is returned.
--   
--   
--   For simple cross-origin requests a preflight request is not
--   required. However, if the client chooses to make a preflight request
--   it is answered in accordance with the policy for simple
--   cross-origin requests.
simpleCorsResourcePolicy :: CorsResourcePolicy

-- | A Cross-Origin resource sharing (CORS) middleware.
--   
--   The middleware is given a function that serves as a pattern to decide
--   whether a requested resource is available for CORS. If the match fails
--   with Nothing the request is passed unmodified to the inner
--   application.
--   
--   The current version of this module does only aim at compliance with
--   the CORS protocol as specified in http://www.w3.org/TR/cors/.
--   In accordance with that standard the role of the server side is to
--   support the client to enforce CORS restrictions. This module does not
--   implement any enforcement of authorization policies that are possibly
--   implied by the CorsResourcePolicy. It is up to the inner WAI
--   application to enforce such policy and make sure that it is in
--   accordance with the configuration of the cors middleware.
--   
--   Matches are done as follows: * matches every origin. For all
--   other cases a match succeeds if and only if the ASCII serializations
--   (as described in RCF6454 section 6.2) are equal.
--   
--   The OPTIONS method may return options for resources that are not
--   actually available. In particular for preflight requests the
--   implementation returns for the HTTP response headers
--   Access-Control-Allow-Headers and
--   Access-Control-Allow-Methods all values specified in the
--   CorsResourcePolicy together with the respective values for
--   simple requests (except content-type). This does not imply
--   that the application actually supports the respective values are for
--   the requested resource. Thus, depending on the application, an actual
--   request may still fail with 404 even if the preflight request
--   supported the usage of the HTTP method with CORS.
--   
--   The implementation does not distinguish between simple requests and
--   requests that require preflight. The client is free to omit a
--   preflight request or do a preflight request in cases when it wouldn't
--   be required.
--   
--   For application authors it is strongly recommended to take into
--   account the security considerations in section 6.3 of
--   http://www.w3.org/TR/cors.
--   
--   TODO
--   
--   
--   
- We may consider adding optional enforcment aspects to this module:
--   we may check if a request respects our origin restrictions and we may
--   check that a CORS request respects the restrictions that we publish in
--   the preflight responses.
--   
- Even though slightly out of scope we may (optionally) check if
--   host header matches the actual host of the resource, since clients
--   using CORS may expect this, since this check is recommended in
--   http://www.w3.org/TR/cors.
--   
- We may consider integrating CORS policy handling more closely with
--   the handling of the source, for instance by integrating with
--   ActionM from scotty.
--   
cors :: (Request -> Maybe CorsResourcePolicy) -> Middleware

-- | A CORS middleware that supports simple cross-origin requests for all
--   resources.
--   
--   This middleware does not check if the resource corresponds to the
--   restrictions for simple requests. This is in accordance with
--   http://www.w3.org/TR/cors/. It is the responsibility of the
--   client (user-agent) to enforce CORS policy. The role of the server is
--   to provide the client with the respective policy constraints.
--   
--   It is out of the scope of the this module if the server chooses to
--   enforce rules on its resources in relation to CORS policy itself.
simpleCors :: Middleware

-- | Whether the given method and headers constitute a simple request, i.e.
--   the method is simple, all headers are simple, and, if a POST request,
--   the content-type is simple.
isSimple :: Method -> RequestHeaders -> Bool

-- | Simple HTTP response headers as defined in
--   https://www.w3.org/TR/cors/#simple-response-header
simpleResponseHeaders :: [HeaderName]

-- | Simple HTTP headers are defined in
--   https://www.w3.org/TR/cors/#simple-header
simpleHeaders :: [HeaderName]

-- | Simple content types are defined in
--   https://www.w3.org/TR/cors/#simple-header
simpleContentTypes :: [CI ByteString]

-- | Simple HTTP methods as defined in
--   https://www.w3.org/TR/cors/#simple-method
simpleMethods :: [Method]
instance GHC.Classes.Eq Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Classes.Ord Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Internal.Read.Read Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Internal.Show.Show Network.Wai.Middleware.Cors.CorsResourcePolicy
