-- 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 <a>Wai</a> that aims to be compliant with
--   <a>http://www.w3.org/TR/cors</a>.
@package wai-cors
@version 0.2.5


-- | An implemenation of Cross-Origin resource sharing (CORS) for WAI that
--   aims to be compliant with <a>http://www.w3.org/TR/cors</a>.
--   
--   The function <a>simpleCors</a> enables support of simple cross-origin
--   requests. More advanced CORS policies can be enabled by passing a
--   <a>CorsResourcePolicy</a> to the <a>cors</a> middleware.
--   
--   <h1>Note On Security</h1>
--   
--   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 <a>http://wwww.w3.org/TR/cors</a>. In particular the
--   application should check that the value of the <tt>Origin</tt> header
--   matches it's expectations.
--   
--   <h1>Websockets</h1>
--   
--   Websocket connections don't support CORS and are ignored by this CORS
--   implementation. However Websocket requests usually (at least for some
--   browsers) include the <tt>Origin</tt> 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.
--   
--   <h1>Example</h1>
--   
--   The following is an example how to enable support for simple
--   cross-origin requests for a <a>scotty</a> application.
--   
--   <pre>
--   {-# 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"
--   </pre>
--   
--   The result of following curl command will include the HTTP response
--   header <tt>Access-Control-Allow-Origin: *</tt>.
--   
--   <pre>
--   curl -i http://127.0.0.1:8888 -H 'Origin: 127.0.0.1' -v
--   </pre>
module Network.Wai.Middleware.Cors

-- | Origins are expected to be formated as described in <a>RFC6454</a>
--   (section 6.2). In particular the string <tt>*</tt> is not a valid
--   origin (but the string <tt>null</tt> 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 <a>Nothing</a> indicates unrestricted cross-origin sharing
--   and results in <tt>*</tt> as value for the
--   <tt>Access-Control-Allow-Origin</tt> HTTP response header.
--   
--   A value other than <a>Nothing</a> is a tuple that consists of a list
--   of origins each with a Boolean flag that indicates if credentials are
--   used to access the resource via CORS.
--   
--   Origins must be formated as described in <a>RFC6454</a> (section 6.2).
--   In particular the string <tt>*</tt> is not a valid origin (but the
--   string <tt>null</tt> is).
[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 <a>simpleHeaders</a>, except for
--   <tt>content-type</tt>, are implicitely included an thus optional in
--   this list.
[corsRequestHeaders] :: CorsResourcePolicy -> ![HeaderName]

-- | Field names of HTTP headers that are exposed on the client.
[corsExposedHeaders] :: CorsResourcePolicy -> !(Maybe [HeaderName])

-- | Number of seconds that the response may be cached by the client.
[corsMaxAge] :: CorsResourcePolicy -> !(Maybe Int)

-- | If the resource is shared by multiple origins but
--   <tt>Access-Control-Allow-Origin</tt> is not set to <tt>*</tt> this may
--   be set to <a>True</a> to cause the server to include a <tt>Vary:
--   Origin</tt> header in the response, thus indicating that the value of
--   the <tt>Access-Control-Allow-Origin</tt> 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 <a>True</a> and the request does not include an
--   <tt>Origin</tt> header the response has HTTP status 400 (bad request)
--   and the body contains a short error message.
--   
--   If this is <a>False</a> and the request does not include an
--   <tt>Origin</tt> header the request is passed on unchanged to the
--   application.
[corsRequireOrigin] :: CorsResourcePolicy -> !Bool

-- | In the case that
--   
--   <ul>
--   <li>the request contains an <tt>Origin</tt> header and</li>
--   <li>the client does not conform with the CORS protocol (<i>request is
--   out of scope</i>)</li>
--   </ul>
--   
--   then
--   
--   <ul>
--   <li>the request is passed on unchanged to the application if this
--   field is <a>True</a> or</li>
--   <li>an response with HTTP status 400 (bad request) and short error
--   message is returned if this field is <a>False</a>.</li>
--   </ul>
[corsIgnoreFailures] :: CorsResourcePolicy -> !Bool

-- | A <a>CorsResourcePolicy</a> that supports <i>simple cross-origin
--   requests</i> as defined in <a>http://www.w3.org/TR/cors/</a>.
--   
--   <ul>
--   <li>The HTTP header <tt>Access-Control-Allow-Origin</tt> is set to
--   <tt>*</tt>.</li>
--   <li>Request methods are constraint to <i>simple methods</i>
--   (<tt>GET</tt>, <tt>HEAD</tt>, <tt>POST</tt>).</li>
--   <li>Request headers are constraint to <i>simple request headers</i>
--   (<tt>Accept</tt>, <tt>Accept-Language</tt>, <tt>Content-Language</tt>,
--   <tt>Content-Type</tt>).</li>
--   <li>If the request is a <tt>POST</tt> request the content type is
--   constraint to <i>simple content types</i>
--   (<tt>application/x-www-form-urlencoded</tt>,
--   <tt>multipart/form-data</tt>, <tt>text/plain</tt>),</li>
--   <li>Only <i>simple response headers</i> may be exposed on the client
--   (<tt>Cache-Control</tt>, <tt>Content-Language</tt>,
--   <tt>Content-Type</tt>, <tt>Expires</tt>, <tt>Last-Modified</tt>,
--   <tt>Pragma</tt>)</li>
--   <li>The <tt>Vary-Origin</tt> header is left unchanged (possibly
--   unset).</li>
--   <li>If the request doesn't include an <tt>Origin</tt> header the
--   request is passed unchanged to the application.</li>
--   <li>If the request includes an <tt>Origin</tt> header but does not
--   conform to the CORS protocol (<i>request is out of scope</i>) an
--   response with HTTP status 400 (bad request) and a short error message
--   is returned.</li>
--   </ul>
--   
--   For <i>simple cross-origin requests</i> 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 <i>simple
--   cross-origin requests</i>.
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 <a>Nothing</a> 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 <a>http://www.w3.org/TR/cors/</a>.
--   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 <a>CorsResourcePolicy</a>. 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 <a>cors</a> middleware.
--   
--   Matches are done as follows: <tt>*</tt> 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
--   <tt>Access-Control-Allow-Headers</tt> and
--   <tt>Access-Control-Allow-Methods</tt> all values specified in the
--   <a>CorsResourcePolicy</a> together with the respective values for
--   simple requests (except <tt>content-type</tt>). 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
--   <i>supported</i> 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
--   <a>http://wwww.w3.org/TR/cors</a>.
--   
--   <i>TODO</i>
--   
--   <ul>
--   <li>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.</li>
--   <li>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
--   <a>http://www.w3.org/TR/cors</a>.</li>
--   <li>We may consider integrating CORS policy handling more closely with
--   the handling of the source, for instance by integrating with
--   <tt>ActionM</tt> from scotty.</li>
--   </ul>
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
--   <a>http://www.w3.org/TR/cors/</a>. The client (user-agent) is supposed
--   to enforcement 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
isSimple :: Method -> RequestHeaders -> Bool

-- | Simple HTTP response headers as defined in
--   <a>http://www.w3.org/TR/cors/</a>
simpleResponseHeaders :: [HeaderName]
simpleHeaders :: [HeaderName]
simpleContentTypes :: [CI ByteString]

-- | Simple HTTP methods as defined in <a>http://www.w3.org/TR/cors/</a>
simpleMethods :: [Method]
instance GHC.Classes.Ord Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Classes.Eq Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Read.Read Network.Wai.Middleware.Cors.CorsResourcePolicy
instance GHC.Show.Show Network.Wai.Middleware.Cors.CorsResourcePolicy
