Merge branch 'master' into 309-handle-application-exceptions-with-500-errors

Author: Sasa Bogicevic

.travis.yml

@@ -13,7 +13,6 @@ git:
 branches:
   only:
     - master
-    - release-0.12
 
 cache:
   directories:
@@ -35,19 +34,19 @@ matrix:
   include:
     - compiler: "ghc-8.4.3"
     # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,ghc-8.4.3], sources: [hvr-ghc]}}
+      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-2.2,ghc-8.4.3], sources: [hvr-ghc]}}
     - compiler: "ghc-8.2.2"
     # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,ghc-8.2.2], sources: [hvr-ghc]}}
+      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-2.2,ghc-8.2.2], sources: [hvr-ghc]}}
     - compiler: "ghc-8.0.2"
     # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,ghc-8.0.2], sources: [hvr-ghc]}}
+      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-2.2,ghc-8.0.2], sources: [hvr-ghc]}}
     - compiler: "ghc-7.10.3"
     # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,ghc-7.10.3], sources: [hvr-ghc]}}
+      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-2.2,ghc-7.10.3], sources: [hvr-ghc]}}
     - compiler: "ghc-7.8.4"
     # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,ghc-7.8.4], sources: [hvr-ghc]}}
+      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-2.2,ghc-7.8.4], sources: [hvr-ghc]}}
 
 before_install:
   - HC=${CC}
@@ -59,34 +58,27 @@ before_install:
   - HCNUMVER=$(( $(${HC} --numeric-version|sed -E 's/([0-9]+)\.([0-9]+)\.([0-9]+).*/\1 * 10000 + \2 * 100 + \3/') ))
   - echo $HCNUMVER
 
-  # Let's download "better" cabal
-  - "curl -L http://oleg.fi/cabal-grayjay-buildable-fix.xz | xz -d > $HOME/.local/bin/cabal"
-  - |
-    if [ "$(cd $HOME/.local/bin && sha256sum cabal)" != "e281e9466b8eef30ac0d1371e8ea83c9d2e856bda4714a728ac474138b09b20f  cabal" ]; then
-      rm -f $HOME/.local/bin/cabal;
-      sha256sum $HOME/.local/bin/cabal;
-      false;
-    else
-      chmod a+x $HOME/.local/bin/cabal;
-    fi
-
 install:
   - cabal --version
   - echo "$(${HC} --version) [$(${HC} --print-project-git-commit-id 2> /dev/null || echo '?')]"
   - BENCH=${BENCH---enable-benchmarks}
   - TEST=${TEST---enable-tests}
   - HADDOCK=${HADDOCK-true}
-  - INSTALLED=${INSTALLED-true}
+  - UNCONSTRAINED=${UNCONSTRAINED-true}
+  - NOINSTALLEDCONSTRAINTS=${NOINSTALLEDCONSTRAINTS-false}
   - GHCHEAD=${GHCHEAD-false}
   - travis_retry cabal update -v
   - "sed -i.bak 's/^jobs:/-- jobs:/' ${HOME}/.cabal/config"
   - rm -fv cabal.project cabal.project.local
   - "if [ $HCNUMVER -ge 70800 ]; then sed -i.bak 's/-- ghc-options:.*/ghc-options: -j2/' ${HOME}/.cabal/config; fi"
   - grep -Ev -- '^\s*--' ${HOME}/.cabal/config | grep -Ev '^\s*$'
-  - "printf 'packages: \"servant\" \"servant-client\" \"servant-client-core\" \"servant-docs\" \"servant-foreign\" \"servant-server\" \"doc/tutorial\" \"doc/cookbook/basic-auth\" \"doc/cookbook/db-postgres-pool\" \"doc/cookbook/db-sqlite-simple\" \"doc/cookbook/https\" \"doc/cookbook/pagination\" \"doc/cookbook/structuring-apis\" \"doc/cookbook/using-custom-monad\"\\n' > cabal.project"
+  - "printf 'packages: \"servant\" \"servant-client\" \"servant-client-core\" \"servant-docs\" \"servant-foreign\" \"servant-server\" \"doc/tutorial\" \"doc/cookbook/basic-auth\" \"doc/cookbook/db-postgres-pool\" \"doc/cookbook/db-sqlite-simple\" \"doc/cookbook/file-upload\" \"doc/cookbook/https\" \"doc/cookbook/jwt-and-basic-auth\" \"doc/cookbook/pagination\" \"doc/cookbook/structuring-apis\" \"doc/cookbook/using-custom-monad\"\\n' > cabal.project"
   - "echo 'constraints: foundation >=0.0.14,memory <0.14.12 || >0.14.12' >> cabal.project"
-  - "echo 'allow-newer: servant-auth-server:http-types,servant-auth-server:servant-server, http-media:base' >> cabal.project"
-  - cat cabal.project
+  - "echo 'allow-newer: servant-auth-server:http-types,servant-auth-server:servant-server, servant-pagination:servant,servant-pagination:servant-server' >> cabal.project"
+  - touch cabal.project.local
+  - "if ! $NOINSTALLEDCONSTRAINTS; then for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/^/constraints: /' | sed 's/-[^-]*$/ installed/' >> cabal.project.local; done; fi"
+  - cat cabal.project || true
+  - cat cabal.project.local || true
   - if [ -f "servant/configure.ac" ]; then
       (cd "servant" && autoreconf -i);
     fi
@@ -117,9 +109,15 @@ install:
   - if [ -f "doc/cookbook/db-sqlite-simple/configure.ac" ]; then
       (cd "doc/cookbook/db-sqlite-simple" && autoreconf -i);
     fi
+  - if [ -f "doc/cookbook/file-upload/configure.ac" ]; then
+      (cd "doc/cookbook/file-upload" && autoreconf -i);
+    fi
   - if [ -f "doc/cookbook/https/configure.ac" ]; then
       (cd "doc/cookbook/https" && autoreconf -i);
     fi
+  - if [ -f "doc/cookbook/jwt-and-basic-auth/configure.ac" ]; then
+      (cd "doc/cookbook/jwt-and-basic-auth" && autoreconf -i);
+    fi
   - if [ -f "doc/cookbook/pagination/configure.ac" ]; then
       (cd "doc/cookbook/pagination" && autoreconf -i);
     fi
@@ -130,7 +128,7 @@ install:
       (cd "doc/cookbook/using-custom-monad" && autoreconf -i);
     fi
   - rm -f cabal.project.freeze
-  - rm -rf .ghc.environment.* "servant"/dist "servant-client"/dist "servant-client-core"/dist "servant-docs"/dist "servant-foreign"/dist "servant-server"/dist "doc/tutorial"/dist "doc/cookbook/basic-auth"/dist "doc/cookbook/db-postgres-pool"/dist "doc/cookbook/db-sqlite-simple"/dist "doc/cookbook/https"/dist "doc/cookbook/pagination"/dist "doc/cookbook/structuring-apis"/dist "doc/cookbook/using-custom-monad"/dist
+  - rm -rf .ghc.environment.* "servant"/dist "servant-client"/dist "servant-client-core"/dist "servant-docs"/dist "servant-foreign"/dist "servant-server"/dist "doc/tutorial"/dist "doc/cookbook/basic-auth"/dist "doc/cookbook/db-postgres-pool"/dist "doc/cookbook/db-sqlite-simple"/dist "doc/cookbook/file-upload"/dist "doc/cookbook/https"/dist "doc/cookbook/jwt-and-basic-auth"/dist "doc/cookbook/pagination"/dist "doc/cookbook/structuring-apis"/dist "doc/cookbook/using-custom-monad"/dist
   - DISTDIR=$(mktemp -d /tmp/dist-test.XXXX)
 
 # Here starts the actual work to be performed for the package under test;
@@ -148,22 +146,26 @@ script:
   - (cd "doc/cookbook/basic-auth" && cabal sdist)
   - (cd "doc/cookbook/db-postgres-pool" && cabal sdist)
   - (cd "doc/cookbook/db-sqlite-simple" && cabal sdist)
+  - (cd "doc/cookbook/file-upload" && cabal sdist)
   - (cd "doc/cookbook/https" && cabal sdist)
+  - (cd "doc/cookbook/jwt-and-basic-auth" && cabal sdist)
   - (cd "doc/cookbook/pagination" && cabal sdist)
   - (cd "doc/cookbook/structuring-apis" && cabal sdist)
   - (cd "doc/cookbook/using-custom-monad" && cabal sdist)
   - echo -en 'travis_fold:end:sdist\\r'
   - echo Unpacking... && echo -en 'travis_fold:start:unpack\\r'
-  - mv "servant"/dist/servant-*.tar.gz "servant-client"/dist/servant-client-*.tar.gz "servant-client-core"/dist/servant-client-core-*.tar.gz "servant-docs"/dist/servant-docs-*.tar.gz "servant-foreign"/dist/servant-foreign-*.tar.gz "servant-server"/dist/servant-server-*.tar.gz "doc/tutorial"/dist/tutorial-*.tar.gz "doc/cookbook/basic-auth"/dist/cookbook-basic-auth-*.tar.gz "doc/cookbook/db-postgres-pool"/dist/cookbook-db-postgres-pool-*.tar.gz "doc/cookbook/db-sqlite-simple"/dist/cookbook-db-sqlite-simple-*.tar.gz "doc/cookbook/https"/dist/cookbook-https-*.tar.gz "doc/cookbook/pagination"/dist/cookbook-pagination-*.tar.gz "doc/cookbook/structuring-apis"/dist/cookbook-structuring-apis-*.tar.gz "doc/cookbook/using-custom-monad"/dist/cookbook-using-custom-monad-*.tar.gz ${DISTDIR}/
+  - mv "servant"/dist/servant-*.tar.gz "servant-client"/dist/servant-client-*.tar.gz "servant-client-core"/dist/servant-client-core-*.tar.gz "servant-docs"/dist/servant-docs-*.tar.gz "servant-foreign"/dist/servant-foreign-*.tar.gz "servant-server"/dist/servant-server-*.tar.gz "doc/tutorial"/dist/tutorial-*.tar.gz "doc/cookbook/basic-auth"/dist/cookbook-basic-auth-*.tar.gz "doc/cookbook/db-postgres-pool"/dist/cookbook-db-postgres-pool-*.tar.gz "doc/cookbook/db-sqlite-simple"/dist/cookbook-db-sqlite-simple-*.tar.gz "doc/cookbook/file-upload"/dist/cookbook-file-upload-*.tar.gz "doc/cookbook/https"/dist/cookbook-https-*.tar.gz "doc/cookbook/jwt-and-basic-auth"/dist/cookbook-jwt-and-basic-auth-*.tar.gz "doc/cookbook/pagination"/dist/cookbook-pagination-*.tar.gz "doc/cookbook/structuring-apis"/dist/cookbook-structuring-apis-*.tar.gz "doc/cookbook/using-custom-monad"/dist/cookbook-using-custom-monad-*.tar.gz ${DISTDIR}/
   - cd ${DISTDIR} || false
   - find . -maxdepth 1 -name '*.tar.gz' -exec tar -xvf '{}' \;
-  - "printf 'packages: servant-*/*.cabal servant-client-*/*.cabal servant-client-core-*/*.cabal servant-docs-*/*.cabal servant-foreign-*/*.cabal servant-server-*/*.cabal tutorial-*/*.cabal cookbook-basic-auth-*/*.cabal cookbook-db-postgres-pool-*/*.cabal cookbook-db-sqlite-simple-*/*.cabal cookbook-https-*/*.cabal cookbook-pagination-*/*.cabal cookbook-structuring-apis-*/*.cabal cookbook-using-custom-monad-*/*.cabal\\n' > cabal.project"
+  - "printf 'packages: servant-*/*.cabal servant-client-*/*.cabal servant-client-core-*/*.cabal servant-docs-*/*.cabal servant-foreign-*/*.cabal servant-server-*/*.cabal tutorial-*/*.cabal cookbook-basic-auth-*/*.cabal cookbook-db-postgres-pool-*/*.cabal cookbook-db-sqlite-simple-*/*.cabal cookbook-file-upload-*/*.cabal cookbook-https-*/*.cabal cookbook-jwt-and-basic-auth-*/*.cabal cookbook-pagination-*/*.cabal cookbook-structuring-apis-*/*.cabal cookbook-using-custom-monad-*/*.cabal\\n' > cabal.project"
   - "echo 'constraints: foundation >=0.0.14,memory <0.14.12 || >0.14.12' >> cabal.project"
-  - "echo 'allow-newer: servant-auth-server:http-types,servant-auth-server:servant-server, http-media:base' >> cabal.project"
-  - cat cabal.project
+  - "echo 'allow-newer: servant-auth-server:http-types,servant-auth-server:servant-server, servant-pagination:servant,servant-pagination:servant-server' >> cabal.project"
+  - touch cabal.project.local
+  - "if ! $NOINSTALLEDCONSTRAINTS; then for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/^/constraints: /' | sed 's/-[^-]*$/ installed/' >> cabal.project.local; done; fi"
+  - cat cabal.project || true
+  - cat cabal.project.local || true
   - echo -en 'travis_fold:end:unpack\\r'
 
-
   - echo Building with tests and benchmarks... && echo -en 'travis_fold:start:build-everything\\r'
   # build & run tests, build benchmarks
   - cabal new-build -w ${HC} ${TEST} ${BENCH} all
@@ -176,5 +178,10 @@ script:
   - if $HADDOCK; then cabal new-haddock -w ${HC} ${TEST} ${BENCH} all; else echo "Skipping haddock generation";fi
 
   - echo -en 'travis_fold:end:haddock\\r'
+  - echo Building without installed constraints for packages in global-db... && echo -en 'travis_fold:start:build-installed\\r'
+  # Build without installed constraints for packages in global-db
+  - if $UNCONSTRAINED; then rm -f cabal.project.local; echo cabal new-build -w ${HC} --disable-tests --disable-benchmarks all; else echo "Not building without installed constraints"; fi
+
+  - echo -en 'travis_fold:end:build-installed\\r'
 # REGENDATA ["--config=cabal.make-travis-yml","--output=.travis.yml","cabal.project"]
 # EOF

cabal.make-travis-yml

@@ -1,12 +1,11 @@
 folds: all-but-test
-branches: master release-0.12
+branches: master
 
 -- We have inplace packages (servant-js) so we skip installing dependencies in a separate step
 install-dependencies-step: False
 
 -- this speed-ups the build a little, but we have to check these for release
 no-tests-no-benchmarks: False
-build-with-installed-step: False
 
 -- Don't run cabal check, as cookbook examples won't pass it
 cabal-check: False

cabal.project

@@ -11,11 +11,10 @@ packages: servant/
   doc/cookbook/basic-auth
   doc/cookbook/db-postgres-pool
   doc/cookbook/db-sqlite-simple
-  -- MkLink changed
-  -- doc/cookbook/file-upload
+  doc/cookbook/file-upload
+  doc/cookbook/generic
   doc/cookbook/https
-  -- servant-auth-* doesn't support GHC-8.4
-  -- doc/cookbook/jwt-and-basic-auth
+  doc/cookbook/jwt-and-basic-auth
   doc/cookbook/pagination
   doc/cookbook/structuring-apis
   doc/cookbook/using-custom-monad
@@ -30,4 +29,5 @@ constraints:
   memory <0.14.12 || >0.14.12
 
 allow-newer:
-  http-media:base
+  servant-pagination:servant,
+  servant-pagination:servant-server

doc/cookbook/generic/Generic.lhs

@@ -0,0 +1,106 @@
+# Using generics
+
+```haskell
+{-# LANGUAGE DataKinds     #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE RankNTypes    #-}
+{-# LANGUAGE TypeOperators #-}
+module Main (main, api, getLink, routesLinks, cliGet) where
+
+import Control.Exception        (throwIO)
+import Data.Proxy               (Proxy (..))
+import Network.Wai.Handler.Warp (run)
+import System.Environment       (getArgs)
+
+import Servant
+import Servant.Client
+
+import Servant.API.Generic
+import Servant.Client.Generic
+import Servant.Server.Generic
+```
+
+The usage is simple, if you only need a collection of routes.
+First you define a record with field types prefixed by a parameter `route`:
+
+```haskell
+data Routes route = Routes
+    { _get :: route :- Capture "id" Int :> Get '[JSON] String
+    , _put :: route :- ReqBody '[JSON] Int :> Put '[JSON] Bool
+    }
+  deriving (Generic)
+```
+
+Then we'll use this data type to define API, links, server and client.
+
+## API
+
+You can get a `Proxy` of the API using `genericApi`:
+
+```haskell
+api :: Proxy (ToServantApi Routes)
+api = genericApi (Proxy :: Proxy Routes)
+```
+
+It's recommented to use `genericApi` function, as then you'll get
+better error message, for example if you forget to `derive Generic`.
+
+## Links
+
+The clear advantage of record-based generics approach, is that
+we can get safe links very conviently. We don't need to define endpoint types,
+as field accessors work as proxies:
+
+```haskell
+getLink :: Int -> Link
+getLink = fieldLink _get
+```
+
+We can also get all links at once, as a record:
+
+```haskell
+routesLinks :: Routes (AsLink Link)
+routesLinks = allFieldLinks
+```
+
+## Client
+
+Even more power starts to show when we generate a record of client functions.
+Here we use `genericClientHoist` function, which let us simultaneously
+hoist the monad, in this case from `ClientM` to `IO`.
+
+```haskell
+cliRoutes :: Routes (AsClientT IO)
+cliRoutes = genericClientHoist
+    (\x -> runClientM x env >>= either throwIO return)
+  where
+    env = error "undefined environment"
+
+cliGet :: Int -> IO String
+cliGet = _get cliRoutes
+```
+
+## Server
+
+Finally, probably the most handy usage: we can convert record of handlers into
+the server implementation:
+
+```haskell
+record :: Routes AsServer
+record = Routes
+    { _get = return . show
+    , _put = return . odd
+    }
+
+app :: Application
+app = genericServe record
+
+main :: IO ()
+main = do
+    args <- getArgs
+    case args of
+        ("run":_) -> do
+            putStrLn "Starting cookbook-generic at http://localhost:8000"
+            run 8000 app
+        _ -> putStrLn "To run, pass 'run' argument: cabal new-run cookbook-generic run"
+```

doc/cookbook/generic/generic.cabal

@@ -0,0 +1,25 @@
+name:                cookbook-generic
+version:             0.1
+synopsis:            Using custom monad to pass a state between handlers
+homepage:            http://haskell-servant.readthedocs.org/
+license:             BSD3
+license-file:        ../../../servant/LICENSE
+author:              Servant Contributors
+maintainer:          [email protected]
+build-type:          Simple
+cabal-version:       >=1.10
+tested-with:         GHC==7.8.4, GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.3
+
+executable cookbook-using-custom-monad
+  main-is:             Generic.lhs
+  build-depends:       base == 4.*
+                     , servant
+                     , servant-client
+                     , servant-client-core
+                     , servant-server
+                     , base-compat
+                     , warp >= 3.2
+                     , transformers >= 0.3
+  default-language:    Haskell2010
+  ghc-options:         -Wall -pgmL markdown-unlit
+  build-tool-depends: markdown-unlit:markdown-unlit >= 0.4

doc/cookbook/index.rst

@@ -18,6 +18,7 @@ you name it!
   :maxdepth: 1
 
   structuring-apis/StructuringApis.lhs
+  generic/Generic.lhs
   https/Https.lhs
   db-sqlite-simple/DBConnection.lhs
   db-postgres-pool/PostgresPool.lhs

doc/index.rst

@@ -3,22 +3,24 @@ servant – A Type-Level Web DSL
 
 .. image:: https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png
 
-**servant** is a set of packages for declaring web APIs at the type-level and
-then using those API specifications to:
+**servant** is a set of Haskell libraries for writing *type-safe* web
+applications but also *deriving* clients (in Haskell and other languages) or
+generating documentation for them, and more.
 
-- write servers (this part of **servant** can be considered a web framework),
-- obtain client functions (in haskell),
-- generate client functions for other programming languages,
-- generate documentation for your web applications
-- and more...
+This is achieved by taking as input a description of the web API
+as a Haskell type. Servant is then able to check that your server-side request
+handlers indeed implement your web API faithfully, or to automatically derive
+Haskell functions that can hit a web application that implements this API,
+generate a Swagger description or code for client functions in some other
+languages directly.
 
-All in a type-safe manner.
+If you would like to learn more, click the tutorial link below.
 
 .. toctree::
   :maxdepth: 2
 
-  introduction.rst
   tutorial/index.rst
   cookbook/index.rst
   examples.md
   links.rst
+  principles.rst

doc/introduction.rst renamed to doc/principles.rst

@@ -1,5 +1,5 @@
-Introduction
-------------
+Principles
+----------
 
 **servant** has the following guiding principles:
 

doc/tutorial/Javascript.lhs

@@ -477,7 +477,7 @@ data AngularOptions = AngularOptions
   }
 ```
 
-# Custom function name builder
+## Custom function name builder
 
 Servant comes with three name builders included:
 
@@ -518,4 +518,3 @@ var get_books = function(q, onSuccess, onError)
 }
 
 ```
-