MIT licensed and maintained by Lars Kuhtz
This version can be pinned in stack with:wai-cors-0.2.7@sha256:c3309a9c9db001cb5c3c777222ba3389f35c2ec57425731cddf2af8515b204b2,2905

Module documentation for 0.2.7

Build Status

Cross-Origin Resource Sharing (CORS) For Wai

This package provides a Haskell implementation of CORS for WAI that aims to be compliant with http://www.w3.org/TR/cors.

Note On Security

This implementation doesn’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 the CORS standard. In particular the application should check that the value of the Origin header matches the expectations.

Websocket connections don’t support CORS and are ignored by the CORS implementation in this package. 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.

Installation

Assuming the availability of recent versions of GHC and cabal this package is installed via

cabal update
cabal install wai-cors

Usage

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.

The file examples/Scotty.hs shows how to support simple cross-origin requests (as defined in http://www.w3.org/TR/cors) in a scotty application.

{-# 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:8080 -H 'Origin: 127.0.0.1' -v

Documentation for more general usage can be found in the module Network.Wai.Middleware.Cors.

Test

In order to run the automated test suite PhantomJS (at least version 2.0) must be installed in the system.

cabal install --only-dependencies --enable-tests
cabal test --show-details=streaming

If PhantomJS is not available the tests can be exectued manually in a modern web-browser as follows.

Start the server application:

cd test
ghc -main-is Server Server.hs
./Server

Open the file test/index.html in a modern web-browser. On page load a Javascript script is exectued that runs the test suite and prints the result on the page.

Changes

0.2.7 (2019-06-06)

  • Remove support for wai<3 and older versions of GHC from the code base.
  • Fix a documentation bug #23.

0.2.6 (2017-12-01)

  • Removed ghc-7.6.3 and versions of wai<3.0 from the CI test matrix. These versions are still supported in the code but cabal may need some manual help to resolve dependencies.

  • Fixes and improvements to the documentation. Thanks to Frederik Hanghøj Iversen, Alex Collins, and Maximilian Tagher.

0.2.5

  • Support GHC-8.0.1.

  • Removed dependencies on parsers package.

0.2.4

  • Fix bug #1. Response header Vary: Origin is now included when corsVaryOrigin is True and corsOrigins does not equal Nothing.

0.2.3

0.2.2

  • Support GHC-7.10/base-4.8 without compiler warnings.

  • Drop dependency on errors package.

0.2.1

  • Fix bug #8. Accept empty list as value for Access-Control-Request-Headers.

0.2

This version may break existing code by changing the type of CorsResourcePolicy.

This version changes the behavior of simpleCorsResourcePolicy: Before it was a failure when the request didn’t contain an @Origin@ header. With this version the request is passed unchanged to the application. If an failure occurs during CORS processing the response has HTTP status 400 (bad request) and contains a short error messages. This behavior can be changed with the new settings corsRequireOrigin and corsIgnorefailure.

  • Remove setting corsVerboseResponse from CorsResourcePolicy.

  • Add new settings corsRequireOrigin and corsIgnoreFailure to CorsResourcePolicy.

0.1.4

  • Support wai-3

0.1.3

  • Improved documentation

0.1.2

  • Export type synonym Origin

  • New easy-to-use middleware function simpleCors that supports just simple cross-origin requests

  • The new value simpleCorseResourcePolicy is a CorseResourcePolicy for simple cross-origin requests.

  • Documentation has been slightly improved

  • Some code for testing simpleCors from a browser

0.1.1

  • Drop redundant dependencies on lens and ghc-prim

  • Fix typo in HTTP header field name Access-Control-Allow-Credentials

0.1.0

  • Initial version