ecbc04b...master · typeable/servant

.github/FUNDING.yml+1−1

since splitsnapshots

unifiedsplit

@@ -1,6 +1,6 @@

1# These are supported funding model platforms

2

3−github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]

3+github: [arianvp]

4patreon: # Replace with a single Patreon username

5open_collective: # Replace with a single Open Collective username

6ko_fi: # Replace with a single Ko-fi username

.github/run-ghcjs-tests.shnew file+14

@@ -0,0 +1,14 @@

1+#!/usr/bin/env bash

2+#

3+# cabal v2-test does not work with GHCJS

4+# See: https://github.com/haskell/cabal/issues/6175

5+#

6+# This invokes cabal-plan to figure out test binaries, and invokes them with node.

7+

8+cabal-plan list-bins '*:test:*' | while read -r line

9+do

10+ testpkg=$(echo "$line" | perl -pe 's/:.*//')

11+ testexe=$(echo "$line" | awk '{ print $2 }')

12+ echo "testing $textexe in package $textpkg"

13+ (cd "$testpkg" && node "$testexe".jsexe/all.js)

14+done

.github/workflows/master.ymlnew file+147

@@ -0,0 +1,147 @@

1+name: CI

2+

3+# Trigger the workflow on push or pull request, but only for the master branch

4+on:

5+ pull_request:

6+ push:

7+ branches: [master]

8+

9+jobs:

10+ cabal:

11+ name: ${{ matrix.os }} / ghc ${{ matrix.ghc }}

12+ runs-on: ${{ matrix.os }}

13+ strategy:

14+ matrix:

15+ os: [ubuntu-latest]

16+ cabal: ["3.6"]

17+ ghc:

18+ - "8.6.5"

19+ - "8.8.4"

20+ - "8.10.7"

21+ - "9.0.2"

22+ - "9.2.2"

23+

24+ steps:

25+ - uses: actions/checkout@v2

26+

27+ - uses: haskell/actions/setup@v1

28+ id: setup-haskell-cabal

29+ name: Setup Haskell

30+ with:

31+ ghc-version: ${{ matrix.ghc }}

32+ cabal-version: ${{ matrix.cabal }}

33+

34+ - name: Freeze

35+ run: |

36+ cabal configure --enable-tests --enable-benchmarks --test-show-details=direct

37+ cabal freeze

38+

39+ - uses: actions/cache@v2.1.3

40+ name: Cache ~/.cabal/store and dist-newstyle

41+ with:

42+ path: |

43+ ${{ steps.setup-haskell-cabal.outputs.cabal-store }}

44+ dist-newstyle

45+ key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}

46+ restore-keys: |

47+ ${{ runner.os }}-${{ matrix.ghc }}-

48+

49+ - name: Configure

50+ run: |

51+ cabal install --ignore-project -j2 doctest --constraint='doctest ^>=0.20'

52+

53+ - name: Build

54+ run: |

55+ cabal build all

56+

57+ - name: Test

58+ run: |

59+ cabal test all

60+

61+ - name: Run doctests

62+ run: |

63+ # Necessary for doctest to be found in $PATH

64+ export PATH="$HOME/.cabal/bin:$PATH"

65+

66+ DOCTEST="cabal repl --with-ghc=doctest --ghc-options=-w"

67+ (cd servant && eval $DOCTEST)

68+ (cd servant-client && eval $DOCTEST)

69+ (cd servant-client-core && eval $DOCTEST)

70+ (cd servant-http-streams && eval $DOCTEST)

71+ (cd servant-docs && eval $DOCTEST)

72+ (cd servant-foreign && eval $DOCTEST)

73+ (cd servant-server && eval $DOCTEST)

74+ (cd servant-machines && eval $DOCTEST)

75+ (cd servant-conduit && eval $DOCTEST)

76+ (cd servant-pipes && eval $DOCTEST)

77+

78+ stack:

79+ name: stack / ghc ${{ matrix.ghc }}

80+ runs-on: ubuntu-latest

81+ strategy:

82+ matrix:

83+ stack: ["2.7.5"]

84+ ghc: ["8.10.7"]

85+

86+ steps:

87+ - uses: actions/checkout@v2

88+

89+ - uses: haskell/actions/setup@v1

90+ name: Setup Haskell Stack

91+ with:

92+ ghc-version: ${{ matrix.ghc }}

93+ stack-version: ${{ matrix.stack }}

94+

95+ - uses: actions/cache@v2.1.3

96+ name: Cache ~/.stack

97+ with:

98+ path: ~/.stack

99+ key: ${{ runner.os }}-${{ matrix.ghc }}-stack

100+

101+ - name: Install dependencies

102+ run: |

103+ stack build --system-ghc --test --bench --no-run-tests --no-run-benchmarks --only-dependencies

104+

105+ - name: Build

106+ run: |

107+ stack build --system-ghc --test --bench --no-run-tests --no-run-benchmarks

108+

109+ - name: Test

110+ run: |

111+ stack test --system-ghc

112+

113+ ghcjs:

114+ name: ubuntu-latest / ghcjs 8.6

115+ runs-on: "ubuntu-latest"

116+

117+ steps:

118+ - uses: actions/checkout@v2

119+ - uses: cachix/install-nix-action@v13

120+ with:

121+ extra_nix_config: |

122+ trusted-public-keys = ryantrinkle.com-1:JJiAKaRv9mWgpVAz8dwewnZe0AzzEAzPkagE9SP5NWI=1aba6f367982bd6dd78ec2fda75ab246a62d32c5 cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

123+ substituters = https://nixcache.reflex-frp.org https://cache.nixos.org/

124+ - name: Setup

125+ run: |

126+ # Override cabal.project with the lightweight GHCJS one

127+ cp cabal.ghcjs.project cabal.project

128+ cat cabal.project

129+ nix-shell ghcjs.nix --run "cabal v2-update && cabal v2-freeze"

130+

131+ - uses: actions/cache@v2.1.3

132+ name: Cache ~/.cabal/store and dist-newstyle

133+ with:

134+ path: |

135+ ~/.cabal/store

136+ dist-newstyle

137+ key: ${{ runner.os }}-ghcjs8.6-${{ hashFiles('cabal.project.freeze') }}

138+ restore-keys: |

139+ ${{ runner.os }}-ghcjs8.6-

140+

141+ - name: Build

142+ run: |

143+ nix-shell ghcjs.nix --run "cabal v2-build --ghcjs --enable-tests --enable-benchmarks all"

144+

145+ - name: Tests

146+ run: |

147+ nix-shell ghcjs.nix --run ".github/run-ghcjs-tests.sh"

.gitignore+6

@@ -1,4 +1,5 @@

1**/*/dist

2+*~

2dist-*

3dist-*

3.ghc.environment.*

4.ghc.environment.*

4/bin

5/bin

@@ -29,6 +30,11 @@ doc/_build

29doc/venv

30doc/venv

30doc/tutorial/static/api.js

31doc/tutorial/static/api.js

31doc/tutorial/static/jq.js

32doc/tutorial/static/jq.js

33+shell.nix

34+.hspec-failures

35+

36+# nix

37+result*

32

38

33# local versions of things

39# local versions of things

34servant-multipart

40servant-multipart

.travis.ymldeleted−294

@@ -1,294 +0,0 @@

1−# This Travis job script has been generated by a script via

2−#

3−# haskell-ci '--config=cabal.haskell-ci' '--output=.travis.yml' 'cabal.project'

4−#

5−# For more information, see https://github.com/haskell-CI/haskell-ci

6−#

7−# version: 0.5.20180907

8−#

9−language: c

10−dist: xenial

11−git:

12− # whether to recursively clone submodules

13− submodules: false

14−branches:

15− only:

16− - master

17−cache:

18− directories:

19− - $HOME/.cabal/packages

20− - $HOME/.cabal/store

21−before_cache:

22− - rm -fv $CABALHOME/packages/hackage.haskell.org/build-reports.log

23− # remove files that are regenerated by 'cabal update'

24− - rm -fv $CABALHOME/packages/hackage.haskell.org/00-index.*

25− - rm -fv $CABALHOME/packages/hackage.haskell.org/*.json

26− - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.cache

27− - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.tar

28− - rm -fv $CABALHOME/packages/hackage.haskell.org/01-index.tar.idx

29− - rm -rfv $CABALHOME/packages/head.hackage

30−matrix:

31− include:

32− - compiler: ghcjs-8.4

33− addons: {"apt":{"sources":["hvr-ghc"],"packages":["cabal-install-3.0"]}}

34− - compiler: ghc-8.6.5

35− addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.6.5","cabal-install-3.0"]}}

36− - compiler: ghc-8.4.4

37− addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.4.4","cabal-install-3.0"]}}

38− - compiler: ghc-8.2.2

39− addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.2.2","cabal-install-3.0"]}}

40− - compiler: ghc-8.0.2

41− addons: {"apt":{"sources":["hvr-ghc"],"packages":["ghc-8.0.2","cabal-install-3.0"]}}

42−before_install:

43− - |

44− if echo $CC | grep -q ghcjs; then

45− GHCJS=true;

46− else

47− GHCJS=false;

48− fi

49− - |

50− if [ "$TRAVIS_OS_NAME" = "linux" ]; then

51− if $GHCJS ; then sudo add-apt-repository -y ppa:hvr/ghcjs ; fi;

52− if $GHCJS ; then curl -s https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add - ; fi;

53− if $GHCJS ; then sudo apt-add-repository 'https://deb.nodesource.com/node_8.x xenial main' ; fi;

54− if $GHCJS ; then sudo apt-get update ; fi;

55− sudo apt-get install $CC;

56− if $GHCJS ; then sudo apt-get install -y nodejs cabal-install-3.0 ; fi;

57− fi

58− - HC=$(echo "/opt/$CC/bin/ghc" | sed 's/-/\//')

59− - WITHCOMPILER="-w $HC"

60− - if $GHCJS ; then HC=${HC}js ; fi

61− - if $GHCJS ; then WITHCOMPILER="--ghcjs ${WITHCOMPILER}js" ; fi

62− - HADDOCK=$(echo "/opt/$CC/bin/haddock" | sed 's/-/\//')

63− - if $GHCJS ; then sudo apt-get install -y ghc-8.4.4 ; fi

64− - if $GHCJS ; then PATH="/opt/ghc/8.4.4/bin:$PATH" ; fi

65− - HCPKG="$HC-pkg"

66− - unset CC

67− - CABAL=/opt/ghc/bin/cabal

68− - CABALHOME=$HOME/.cabal

69− - export PATH="$CABALHOME/bin:$PATH"

70− - TOP=$(pwd)

71− - "HCNUMVER=$(${HC} --numeric-version|perl -ne '/^(\\d+)\\.(\\d+)\\.(\\d+)(\\.(\\d+))?$/; print(10000 * $1 + 100 * $2 + ($3 == 0 ? $5 != 1 : $3))')"

72− - echo $HCNUMVER

73− - CABAL="$CABAL -vnormal+nowrap+markoutput"

74− - set -o pipefail

75− - |

76− echo 'function blue(s) { printf "\033[0;34m" s "\033[0m " }' >> .colorful.awk

77− echo 'BEGIN { state = "output"; }' >> .colorful.awk

78− echo '/^-----BEGIN CABAL OUTPUT-----$/ { state = "cabal" }' >> .colorful.awk

79− echo '/^-----END CABAL OUTPUT-----$/ { state = "output" }' >> .colorful.awk

80− echo '!/^(-----BEGIN CABAL OUTPUT-----|-----END CABAL OUTPUT-----)/ {' >> .colorful.awk

81− echo ' if (state == "cabal") {' >> .colorful.awk

82− echo ' print blue($0)' >> .colorful.awk

83− echo ' } else {' >> .colorful.awk

84− echo ' print $0' >> .colorful.awk

85− echo ' }' >> .colorful.awk

86− echo '}' >> .colorful.awk

87− - cat .colorful.awk

88− - |

89− color_cabal_output () {

90− awk -f $TOP/.colorful.awk

91− }

92− - echo text | color_cabal_output

93−install:

94− - ${CABAL} --version

95− - echo "$(${HC} --version) [$(${HC} --print-project-git-commit-id 2> /dev/null || echo '?')]"

96− - node --version

97− - echo $GHCJS

98− - TEST=--enable-tests

99− - BENCH=--enable-benchmarks

100− - HEADHACKAGE=false

101− - rm -f $CABALHOME/config

102− - |

103− echo "verbose: normal +nowrap +markoutput" >> $CABALHOME/config

104− echo "remote-build-reporting: anonymous" >> $CABALHOME/config

105− echo "write-ghc-environment-files: always" >> $CABALHOME/config

106− echo "remote-repo-cache: $CABALHOME/packages" >> $CABALHOME/config

107− echo "logs-dir: $CABALHOME/logs" >> $CABALHOME/config

108− echo "world-file: $CABALHOME/world" >> $CABALHOME/config

109− echo "extra-prog-path: $CABALHOME/bin" >> $CABALHOME/config

110− echo "symlink-bindir: $CABALHOME/bin" >> $CABALHOME/config

111− echo "installdir: $CABALHOME/bin" >> $CABALHOME/config

112− echo "build-summary: $CABALHOME/logs/build.log" >> $CABALHOME/config

113− echo "store-dir: $CABALHOME/store" >> $CABALHOME/config

114− echo "install-dirs user" >> $CABALHOME/config

115− echo " prefix: $CABALHOME" >> $CABALHOME/config

116− echo "repository hackage.haskell.org" >> $CABALHOME/config

117− echo " url: http://hackage.haskell.org/" >> $CABALHOME/config

118− - |

119− echo "program-default-options" >> $CABALHOME/config

120− echo " ghc-options: -j2" >> $CABALHOME/config

121− - cat $CABALHOME/config

122− - rm -fv cabal.project cabal.project.local cabal.project.freeze

123− - travis_retry ${CABAL} v2-update -v

124− - if $GHCJS ; then (cd /tmp && ${CABAL} v2-install -w ghc-8.4.4 hspec-discover | color_cabal_output) ; fi

125− # Generate cabal.project

126− - rm -rf cabal.project cabal.project.local cabal.project.freeze

127− - touch cabal.project

128− - |

129− echo "packages: servant" >> cabal.project

130− if ! $GHCJS ; then echo "packages: servant-client" >> cabal.project ; fi

131− echo "packages: servant-client-core" >> cabal.project

132− if ! $GHCJS ; then echo "packages: servant-http-streams" >> cabal.project ; fi

133− if ! $GHCJS ; then echo "packages: servant-docs" >> cabal.project ; fi

134− if ! $GHCJS ; then echo "packages: servant-foreign" >> cabal.project ; fi

135− if ! $GHCJS ; then echo "packages: servant-server" >> cabal.project ; fi

136− if ! $GHCJS ; then echo "packages: doc/tutorial" >> cabal.project ; fi

137− if ! $GHCJS ; then echo "packages: servant-machines" >> cabal.project ; fi

138− if ! $GHCJS ; then echo "packages: servant-conduit" >> cabal.project ; fi

139− if ! $GHCJS ; then echo "packages: servant-pipes" >> cabal.project ; fi

140− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/basic-auth" >> cabal.project ; fi

141− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/curl-mock" >> cabal.project ; fi

142− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/basic-streaming" >> cabal.project ; fi

143− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/db-postgres-pool" >> cabal.project ; fi

144− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/db-sqlite-simple" >> cabal.project ; fi

145− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/file-upload" >> cabal.project ; fi

146− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/generic" >> cabal.project ; fi

147− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/https" >> cabal.project ; fi

148− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/pagination" >> cabal.project ; fi

149− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/testing" >> cabal.project ; fi

150− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/structuring-apis" >> cabal.project ; fi

151− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/using-custom-monad" >> cabal.project ; fi

152− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: doc/cookbook/using-free-client" >> cabal.project ; fi

153− - |

154− echo "constraints: foundation >=0.0.14" >> cabal.project

155− echo "constraints: memory <0.14.12 || >0.14.12" >> cabal.project

156− echo "allow-newer: servant-quickcheck:servant" >> cabal.project

157− echo "allow-newer: servant-quickcheck:servant-client" >> cabal.project

158− echo "allow-newer: servant-quickcheck:servant-server" >> cabal.project

159− echo "allow-newer: servant-quickcheck:hspec" >> cabal.project

160− echo "allow-newer: servant-quickcheck:http-client" >> cabal.project

161− echo "allow-newer: vault-0.3.1.2:hashable" >> cabal.project

162− echo "allow-newer: psqueues-0.2.7.1:hashable" >> cabal.project

163− echo "allow-newer: sqlite-simple-0.4.16.0:semigroups" >> cabal.project

164− echo "allow-newer: direct-sqlite-2.3.24:semigroups" >> cabal.project

165− echo "allow-newer: io-streams-1.5.1.0:network" >> cabal.project

166− echo "allow-newer: openssl-streams-1.2.2.0:network" >> cabal.project

167− echo "optimization: False" >> cabal.project

168− - "for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/-[^-]*$//' | (grep -vE -- '^(cookbook-basic-auth|cookbook-basic-streaming|cookbook-curl-mock|cookbook-db-postgres-pool|cookbook-db-sqlite-simple|cookbook-file-upload|cookbook-generic|cookbook-https|cookbook-pagination|cookbook-structuring-apis|cookbook-testing|cookbook-using-custom-monad|cookbook-using-free-client|servant|servant-client|servant-client-core|servant-conduit|servant-docs|servant-foreign|servant-http-streams|servant-machines|servant-pipes|servant-server|tutorial)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"

169− - cat cabal.project || true

170− - cat cabal.project.local || true

171− - if [ -f "servant/configure.ac" ]; then (cd "servant" && autoreconf -i); fi

172− - if [ -f "servant-client/configure.ac" ]; then (cd "servant-client" && autoreconf -i); fi

173− - if [ -f "servant-client-core/configure.ac" ]; then (cd "servant-client-core" && autoreconf -i); fi

174− - if [ -f "servant-http-streams/configure.ac" ]; then (cd "servant-http-streams" && autoreconf -i); fi

175− - if [ -f "servant-docs/configure.ac" ]; then (cd "servant-docs" && autoreconf -i); fi

176− - if [ -f "servant-foreign/configure.ac" ]; then (cd "servant-foreign" && autoreconf -i); fi

177− - if [ -f "servant-server/configure.ac" ]; then (cd "servant-server" && autoreconf -i); fi

178− - if [ -f "doc/tutorial/configure.ac" ]; then (cd "doc/tutorial" && autoreconf -i); fi

179− - if [ -f "servant-machines/configure.ac" ]; then (cd "servant-machines" && autoreconf -i); fi

180− - if [ -f "servant-conduit/configure.ac" ]; then (cd "servant-conduit" && autoreconf -i); fi

181− - if [ -f "servant-pipes/configure.ac" ]; then (cd "servant-pipes" && autoreconf -i); fi

182− - if [ -f "doc/cookbook/basic-auth/configure.ac" ]; then (cd "doc/cookbook/basic-auth" && autoreconf -i); fi

183− - if [ -f "doc/cookbook/curl-mock/configure.ac" ]; then (cd "doc/cookbook/curl-mock" && autoreconf -i); fi

184− - if [ -f "doc/cookbook/basic-streaming/configure.ac" ]; then (cd "doc/cookbook/basic-streaming" && autoreconf -i); fi

185− - if [ -f "doc/cookbook/db-postgres-pool/configure.ac" ]; then (cd "doc/cookbook/db-postgres-pool" && autoreconf -i); fi

186− - if [ -f "doc/cookbook/db-sqlite-simple/configure.ac" ]; then (cd "doc/cookbook/db-sqlite-simple" && autoreconf -i); fi

187− - if [ -f "doc/cookbook/file-upload/configure.ac" ]; then (cd "doc/cookbook/file-upload" && autoreconf -i); fi

188− - if [ -f "doc/cookbook/generic/configure.ac" ]; then (cd "doc/cookbook/generic" && autoreconf -i); fi

189− - if [ -f "doc/cookbook/https/configure.ac" ]; then (cd "doc/cookbook/https" && autoreconf -i); fi

190− - if [ -f "doc/cookbook/pagination/configure.ac" ]; then (cd "doc/cookbook/pagination" && autoreconf -i); fi

191− - if [ -f "doc/cookbook/testing/configure.ac" ]; then (cd "doc/cookbook/testing" && autoreconf -i); fi

192− - if [ -f "doc/cookbook/structuring-apis/configure.ac" ]; then (cd "doc/cookbook/structuring-apis" && autoreconf -i); fi

193− - if [ -f "doc/cookbook/using-custom-monad/configure.ac" ]; then (cd "doc/cookbook/using-custom-monad" && autoreconf -i); fi

194− - if [ -f "doc/cookbook/using-free-client/configure.ac" ]; then (cd "doc/cookbook/using-free-client" && autoreconf -i); fi

195− - ${CABAL} v2-freeze $WITHCOMPILER ${TEST} ${BENCH} | color_cabal_output

196− - "cat cabal.project.freeze | sed -E 's/^(constraints: *| *)//' | sed 's/any.//'"

197− - rm cabal.project.freeze

198−script:

199− - DISTDIR=$(mktemp -d /tmp/dist-test.XXXX)

200− # Packaging...

201− - echo 'Packaging...' && echo -en 'travis_fold:start:sdist\\r'

202− - ${CABAL} v2-sdist all | color_cabal_output

203− - echo -en 'travis_fold:end:sdist\\r'

204− # Unpacking...

205− - echo 'Unpacking...' && echo -en 'travis_fold:start:unpack\\r'

206− - mv dist-newstyle/sdist/*.tar.gz ${DISTDIR}/

207− - cd ${DISTDIR} || false

208− - find . -maxdepth 1 -type f -name '*.tar.gz' -exec tar -xvf '{}' \;

209− - find . -maxdepth 1 -type f -name '*.tar.gz' -exec rm '{}' \;

210− - PKGDIR_servant="$(find . -maxdepth 1 -type d -regex '.*/servant-[0-9.]*')"

211− - PKGDIR_servant_client="$(find . -maxdepth 1 -type d -regex '.*/servant-client-[0-9.]*')"

212− - PKGDIR_servant_client_core="$(find . -maxdepth 1 -type d -regex '.*/servant-client-core-[0-9.]*')"

213− - PKGDIR_servant_http_streams="$(find . -maxdepth 1 -type d -regex '.*/servant-http-streams-[0-9.]*')"

214− - PKGDIR_servant_docs="$(find . -maxdepth 1 -type d -regex '.*/servant-docs-[0-9.]*')"

215− - PKGDIR_servant_foreign="$(find . -maxdepth 1 -type d -regex '.*/servant-foreign-[0-9.]*')"

216− - PKGDIR_servant_server="$(find . -maxdepth 1 -type d -regex '.*/servant-server-[0-9.]*')"

217− - PKGDIR_tutorial="$(find . -maxdepth 1 -type d -regex '.*/tutorial-[0-9.]*')"

218− - PKGDIR_servant_machines="$(find . -maxdepth 1 -type d -regex '.*/servant-machines-[0-9.]*')"

219− - PKGDIR_servant_conduit="$(find . -maxdepth 1 -type d -regex '.*/servant-conduit-[0-9.]*')"

220− - PKGDIR_servant_pipes="$(find . -maxdepth 1 -type d -regex '.*/servant-pipes-[0-9.]*')"

221− - PKGDIR_cookbook_basic_auth="$(find . -maxdepth 1 -type d -regex '.*/cookbook-basic-auth-[0-9.]*')"

222− - PKGDIR_cookbook_curl_mock="$(find . -maxdepth 1 -type d -regex '.*/cookbook-curl-mock-[0-9.]*')"

223− - PKGDIR_cookbook_basic_streaming="$(find . -maxdepth 1 -type d -regex '.*/cookbook-basic-streaming-[0-9.]*')"

224− - PKGDIR_cookbook_db_postgres_pool="$(find . -maxdepth 1 -type d -regex '.*/cookbook-db-postgres-pool-[0-9.]*')"

225− - PKGDIR_cookbook_db_sqlite_simple="$(find . -maxdepth 1 -type d -regex '.*/cookbook-db-sqlite-simple-[0-9.]*')"

226− - PKGDIR_cookbook_file_upload="$(find . -maxdepth 1 -type d -regex '.*/cookbook-file-upload-[0-9.]*')"

227− - PKGDIR_cookbook_generic="$(find . -maxdepth 1 -type d -regex '.*/cookbook-generic-[0-9.]*')"

228− - PKGDIR_cookbook_https="$(find . -maxdepth 1 -type d -regex '.*/cookbook-https-[0-9.]*')"

229− - PKGDIR_cookbook_pagination="$(find . -maxdepth 1 -type d -regex '.*/cookbook-pagination-[0-9.]*')"

230− - PKGDIR_cookbook_testing="$(find . -maxdepth 1 -type d -regex '.*/cookbook-testing-[0-9.]*')"

231− - PKGDIR_cookbook_structuring_apis="$(find . -maxdepth 1 -type d -regex '.*/cookbook-structuring-apis-[0-9.]*')"

232− - PKGDIR_cookbook_using_custom_monad="$(find . -maxdepth 1 -type d -regex '.*/cookbook-using-custom-monad-[0-9.]*')"

233− - PKGDIR_cookbook_using_free_client="$(find . -maxdepth 1 -type d -regex '.*/cookbook-using-free-client-[0-9.]*')"

234− # Generate cabal.project

235− - rm -rf cabal.project cabal.project.local cabal.project.freeze

236− - touch cabal.project

237− - |

238− echo "packages: ${PKGDIR_servant}" >> cabal.project

239− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_client}" >> cabal.project ; fi

240− echo "packages: ${PKGDIR_servant_client_core}" >> cabal.project

241− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_http_streams}" >> cabal.project ; fi

242− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_docs}" >> cabal.project ; fi

243− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_foreign}" >> cabal.project ; fi

244− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_server}" >> cabal.project ; fi

245− if ! $GHCJS ; then echo "packages: ${PKGDIR_tutorial}" >> cabal.project ; fi

246− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_machines}" >> cabal.project ; fi

247− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_conduit}" >> cabal.project ; fi

248− if ! $GHCJS ; then echo "packages: ${PKGDIR_servant_pipes}" >> cabal.project ; fi

249− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_basic_auth}" >> cabal.project ; fi

250− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_curl_mock}" >> cabal.project ; fi

251− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_basic_streaming}" >> cabal.project ; fi

252− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_db_postgres_pool}" >> cabal.project ; fi

253− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_db_sqlite_simple}" >> cabal.project ; fi

254− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_file_upload}" >> cabal.project ; fi

255− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_generic}" >> cabal.project ; fi

256− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_https}" >> cabal.project ; fi

257− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_pagination}" >> cabal.project ; fi

258− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_testing}" >> cabal.project ; fi

259− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_structuring_apis}" >> cabal.project ; fi

260− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_using_custom_monad}" >> cabal.project ; fi

261− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_using_free_client}" >> cabal.project ; fi

262− - |

263− echo "constraints: foundation >=0.0.14" >> cabal.project

264− echo "constraints: memory <0.14.12 || >0.14.12" >> cabal.project

265− echo "allow-newer: servant-quickcheck:servant" >> cabal.project

266− echo "allow-newer: servant-quickcheck:servant-client" >> cabal.project

267− echo "allow-newer: servant-quickcheck:servant-server" >> cabal.project

268− echo "allow-newer: servant-quickcheck:hspec" >> cabal.project

269− echo "allow-newer: servant-quickcheck:http-client" >> cabal.project

270− echo "allow-newer: vault-0.3.1.2:hashable" >> cabal.project

271− echo "allow-newer: psqueues-0.2.7.1:hashable" >> cabal.project

272− echo "allow-newer: sqlite-simple-0.4.16.0:semigroups" >> cabal.project

273− echo "allow-newer: direct-sqlite-2.3.24:semigroups" >> cabal.project

274− echo "allow-newer: io-streams-1.5.1.0:network" >> cabal.project

275− echo "allow-newer: openssl-streams-1.2.2.0:network" >> cabal.project

276− echo "optimization: False" >> cabal.project

277− - "for pkg in $($HCPKG list --simple-output); do echo $pkg | sed 's/-[^-]*$//' | (grep -vE -- '^(cookbook-basic-auth|cookbook-basic-streaming|cookbook-curl-mock|cookbook-db-postgres-pool|cookbook-db-sqlite-simple|cookbook-file-upload|cookbook-generic|cookbook-https|cookbook-pagination|cookbook-structuring-apis|cookbook-testing|cookbook-using-custom-monad|cookbook-using-free-client|servant|servant-client|servant-client-core|servant-conduit|servant-docs|servant-foreign|servant-http-streams|servant-machines|servant-pipes|servant-server|tutorial)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"

278− - cat cabal.project || true

279− - cat cabal.project.local || true

280− - echo -en 'travis_fold:end:unpack\\r'

281− # Building with tests and benchmarks...

282− - echo 'Building with tests and benchmarks...' && echo -en 'travis_fold:start:build-everything\\r'

283− # build & run tests, build benchmarks

284− - ${CABAL} v2-build $WITHCOMPILER ${TEST} ${BENCH} all | color_cabal_output

285− - echo -en 'travis_fold:end:build-everything\\r'

286− # Testing...

287− - if ! $GHCJS ; then ${CABAL} v2-test $WITHCOMPILER ${TEST} ${BENCH} all | color_cabal_output ; fi

288− # haddock...

289− - echo 'haddock...' && echo -en 'travis_fold:start:haddock\\r'

290− - if ! $GHCJS ; then ${CABAL} v2-haddock $WITHCOMPILER --with-haddock $HADDOCK ${TEST} ${BENCH} all | color_cabal_output ; fi

291− - echo -en 'travis_fold:end:haddock\\r'

292−

293−# REGENDATA ["--config=cabal.haskell-ci","--output=.travis.yml","cabal.project"]

294−# EOF

CONTRIBUTING.md+33−4

@@ -35,7 +35,34 @@ Some things we like:

35Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs`

36files in the repository provide a good baseline for consistency.

37

38−**Important**: please do not modify the changelog files nor the versions of the servant packages you are sending patches for. We take care of this before every release and do it uniformly for all the servant packages, so there's no need to worry about this for your pull requests.

38+**Important**: please do not modify the versions of the servant packages you are sending patches for.

39+

40+## Changelog entries

41+

42+We experiment with using [changelog-d tool](https://github.com/phadej/changelog-d) to assemble changelogs.

43+You are not required to install it.

44+

45+In each PR please add a file to `changelog.d` directory named after issue you are solving or the pull request itself (in a separate commit after you know the pull request number). For example

46+

47+```cabal

48+synopsis: One sentence summary of the change.

49+prs: #1219

50+issues: #1028

51+

52+description: {

53+

54+A longer description. Small changes don't need this.

55+Bigger ones definitely do, for example we try to include migration hints

56+for breaking changes.

57+

58+However if you don't know what to write, that's ok too.

59+

60+By the way, the braces around are omitted when the file is parsed.

61+They can be used so the field doesn't need to be indented, which is handy

62+for prose.

63+

64+}

65+```

39

66

40## PR process

67## PR process

41

68

@@ -52,8 +79,10 @@ not been a timely response to a PR, you can ping the Maintainers group (with

52We encourage people to experiment with new combinators and instances - it is

79We encourage people to experiment with new combinators and instances - it is

53one of the most powerful ways of using `servant`, and a wonderful way of

80one of the most powerful ways of using `servant`, and a wonderful way of

54getting to know it better. If you do write a new combinator, we would love to

81getting to know it better. If you do write a new combinator, we would love to

55−know about it! Either hop on #servant on freenode and let us know, or open an

82+know about it! Either hop on

83+[#haskell-servant on libera.chat](https://web.libera.chat/#haskell-servant) and

56−issue with the `news` tag (which we will close when we read it).

84+let us know, or open an issue with the `news` tag (which we will close when we

85+read it).

57

86

58As for adding them to the main repo: maintaining combinators can be expensive,

87As for adding them to the main repo: maintaining combinators can be expensive,

59since official combinators must have instances for all classes (and new classes

88since official combinators must have instances for all classes (and new classes

@@ -76,7 +105,7 @@ the `news` label if you make a new package so we can know about it!

76

105

77## Release policy

106## Release policy

78

107

79−We are currently moving to a more aggresive release policy, so that you can get

108+We are currently moving to a more aggressive release policy, so that you can get

80what you contribute from Hackage fairly soon. However, note that prior to major

109what you contribute from Hackage fairly soon. However, note that prior to major

81releases it may take some time in between releases.

110releases it may take some time in between releases.

82

111

Makefiledeleted−22

@@ -1,22 +0,0 @@

1−# With common maintenance tasks

2−

3−HC ?= ghc-8.4.4

4−

5−all :

6− @echo "Don't try to make all at once!"

7−

8−really-all :

9− $(MAKE) build-ghc

10− $(MAKE) build-ghc HC=ghc-8.0.2

11− $(MAKE) build-ghc HC=ghc-8.2.2

12− $(MAKE) build-ghc HC=ghc-8.6.3

13− $(MAKE) build-ghcjs

14−

15−build-ghc :

16− cabal v2-build -w $(HC) all

17−

18−build-ghcjs :

19− cabal v2-build --builddir=dist-newstyle-ghcjs --project-file=cabal.ghcjs.project all

20−

21−packdeps :

22− packdeps */*.cabal

README.md+24−14

@@ -9,11 +9,11 @@ introduces the core features of servant. After this article, you should be able

9to write your first servant webservices, learning the rest from the haddocks'

10examples.

11

12−The central documentation can be found [here](http://docs.servant.dev/).

12+The core documentation can be found [here](http://docs.servant.dev/).

13Other blog posts, videos and slides can be found on the

14[website](http://www.servant.dev/).

15

16−If you need help, drop by the IRC channel (#servant on freenode) or [mailing

16+If you need help, drop by the IRC channel (#haskell-servant on libera.chat) or [mailing

17list](https://groups.google.com/forum/#!forum/haskell-servant).

18

19## Contributing

@@ -32,7 +32,7 @@ See `CONTRIBUTING.md`

32 - It's a good idea to separate these steps, as tests often pass, if they compile :)

33 - See `cabal.project` to selectively `allow-newer`

34 - If some packages are broken, on your discretisation there are two options:

35− - Fix them and make PRs: it's good idea to test against older `servant` version too.

35+ - Fix them and make PRs: it's a good idea to test against older `servant` version too.

36 - Temporarily comment out broken package

37 - If you make a commit for `servant-universe`, you can use it as submodule in private projects to test even more

38- When ripples are cleared out:

@@ -40,22 +40,32 @@ See `CONTRIBUTING.md`

40 - `git push --tags`

41 - `cabal sdist` and `cabal upload`

42

43−## travis

43+## TechEmpower framework benchmarks

44

45−`.travis.yml` is generated using `make-travis-yml` tool, in

45+We develop and maintain the servant TFB entry in https://github.com/haskell-servant/FrameworkBenchmarks/

46−[multi-ghc-travis](https://github.com/haskell-hvr/multi-ghc-travis) repository.

47

46

48−To regenerate the script use (*note:* atm you need to comment `doc/cookbook/` packages).

47+To verify (i.e. compile and test that it works)

49

48

50−```

49+```sh

51−runghc ~/Documents/other-haskell/multi-ghc-travis/make_travis_yml_2.hs regenerate

50+./tfb --mode verify --test servant servant-beam servant-psql-simple --type json plaintext db fortune

52```

51```

53

52

54−In case Travis jobs fail due failing build of dependency, you can temporarily

53+To compare with `warp`

55−add `constraints` to the `cabal.project`, and regenerate the `.travis.yml`.

56−For example, the following will disallow single `troublemaker-13.37` package version:

57

54

55+```sh

56+./tfb --mode benchmark --test warp servant servant-beam servant-psql-simple --type json plaintext db fortune

58```

57```

59−constraints:

58+

60− troublemaker <13.37 && > 13.37

59+To compare with `reitit` (Clojure framework)

60+

61+```sh

62+./tfb --mode benchmark --test reitit reitit-async reitit-jdbc servant servant-beam servant-psql-simple --type json plaintext db fortune

61```

63```

64+

65+You can see the visualised results at https://www.techempower.com/benchmarks/#section=test

66+

67+## Nix

68+

69+A developer shell.nix file is provided in the `nix` directory

70+

71+See [nix/README.md](nix/README.md)

cabal.ghcjs.project+6−1

@@ -2,8 +2,13 @@

2

3packages:

4 servant/

5+ servant-client/

5 servant-client-core/

6 servant-client-core/

6− servant-client-ghcjs/

7

8-- we need to tell cabal we are using GHCJS

9compiler: ghcjs

10+tests: True

11+

12+-- Constraints so that reflex-platform provided packages are selected.

13+constraints: attoparsec == 0.13.2.2

14+constraints: hashable == 1.3.0.0

cabal.haskell-cideleted−19

@@ -1,19 +0,0 @@

1−folds: all-but-test

2−branches: master

3−jobs-selection: any

4−

5−-- https://github.com/haskell/cabal/issues/6176

6−ghcjs-tools: hspec-discover

7−

8−-- We have inplace packages (servant-js) so we skip installing dependencies in a separate step

9−install-dependencies: False

10−

11−-- this speed-ups the build a little, but we have to check these for release

12−no-tests-no-benchmarks: False

13−unconstrained: False

14−

15−-- Don't run cabal check, as cookbook examples won't pass it

16−cabal-check: False

17−

18−-- ghc-options: -j2

19−jobs: :2

cabal.project+20−33

@@ -1,32 +1,48 @@

1packages:

2 servant/

3+ servant-auth/servant-auth

4+ servant-auth/servant-auth-client

5+ servant-auth/servant-auth-docs

6+ servant-auth/servant-auth-server

7+ servant-auth/servant-auth-swagger

8+

3 servant-client/

9 servant-client/

4 servant-client-core/

10 servant-client-core/

5 servant-http-streams/

11 servant-http-streams/

6 servant-docs/

12 servant-docs/

7 servant-foreign/

13 servant-foreign/

8 servant-server/

14 servant-server/

15+ servant-swagger/

9 doc/tutorial/

16 doc/tutorial/

10

17

18+-- servant streaming

19+packages:

11 servant-machines/

20 servant-machines/

12 servant-conduit/

21 servant-conduit/

13 servant-pipes/

22 servant-pipes/

14

23

15− -- doc/cookbook/*/*.cabal

24+-- servant GHCJS

25+-- packages:

26+-- servant-jsaddle/

16

27

28+-- Cookbooks

29+packages:

17 doc/cookbook/basic-auth

30 doc/cookbook/basic-auth

18 doc/cookbook/curl-mock

31 doc/cookbook/curl-mock

32+ doc/cookbook/custom-errors

19 doc/cookbook/basic-streaming

33 doc/cookbook/basic-streaming

20 doc/cookbook/db-postgres-pool

34 doc/cookbook/db-postgres-pool

21 doc/cookbook/db-sqlite-simple

35 doc/cookbook/db-sqlite-simple

22 doc/cookbook/file-upload

36 doc/cookbook/file-upload

23 doc/cookbook/generic

37 doc/cookbook/generic

24− -- doc/cookbook/hoist-server-with-context

38+ doc/cookbook/hoist-server-with-context

25 doc/cookbook/https

39 doc/cookbook/https

26− -- doc/cookbook/jwt-and-basic-auth/

40+ doc/cookbook/jwt-and-basic-auth

27 doc/cookbook/pagination

41 doc/cookbook/pagination

28 -- doc/cookbook/sentry

42 -- doc/cookbook/sentry

43+ -- Commented out because servant-quickcheck currently doesn't build.

29− doc/cookbook/testing

44+ -- doc/cookbook/testing

45+ doc/cookbook/uverb

30 doc/cookbook/structuring-apis

46 doc/cookbook/structuring-apis

31 doc/cookbook/using-custom-monad

47 doc/cookbook/using-custom-monad

32 doc/cookbook/using-free-client

48 doc/cookbook/using-free-client

@@ -35,32 +51,3 @@ packages:

35tests: True

51tests: True

36optimization: False

52optimization: False

37-- reorder-goals: True

53-- reorder-goals: True

38−

39−constraints:

40− -- see https://github.com/haskell-infra/hackage-trustees/issues/119

41− foundation >=0.0.14,

42− memory <0.14.12 || >0.14.12

43−

44−allow-newer:

45−-- servant-pagination:servant, servant-pagination:servant-server,

46−-- servant-multipart:servant, servant-multipart:servant-server,

47−-- servant-auth-server:servant, servant-auth-server:servant-server,

48−-- servant-js:servant, servant-js:servant-foreign

49−

50−-- servant-quickcheck

51−allow-newer:

52− servant-quickcheck:servant, servant-quickcheck:servant-client, servant-quickcheck:servant-server,

53− servant-quickcheck:hspec,

54− servant-quickcheck:http-client

55−

56−-- constraints: semigroups ^>=0.19

57−-- constraints: hashable ^>=1.3

58−-- constraints: network ^>=3.1

59−-- constraints: machines ^>=0.7

60−

61−allow-newer: vault-0.3.1.2:hashable

62−allow-newer: psqueues-0.2.7.1:hashable

63−allow-newer: sqlite-simple-0.4.16.0:semigroups

64−allow-newer: direct-sqlite-2.3.24:semigroups

65−allow-newer: io-streams-1.5.1.0:network

66−allow-newer: openssl-streams-1.2.2.0:network

changelog.d/1432new file+9

@@ -0,0 +1,9 @@

1+synopsis: Fixes encoding of URL parameters in servant-client

2+prs: #1432

3+issues: #1418

4+description: {

5+Some applications use query parameters to pass arbitrary (non-unicode) binary

6+data. This change modifies how servant-client handles query parameters, so

7+that application developers can use `ToHttpApiData` to marshal binary data into

8+query parameters.

9+}

changelog.d/1469new file+11

@@ -0,0 +1,11 @@

1+synopsis: Derive HasClient good response status from Verb status

2+prs: #1469

3+description: {

4+`HasClient` instances for the `Verb` datatype use `runRequest` in

5+`clientWithRoute` definitions.

6+This means that a request performed with `runClientM` will be successful if and

7+only if the endpoint specify a response status code >=200 and <300.

8+This change replaces `runRequest` with `runRequestAcceptStatus` in `Verb`

9+instances for the `HasClient` class, deriving the good response status from

10+the `Verb` status.

11+}

changelog.d/1477new file+9

@@ -0,0 +1,9 @@

1+synopsis: Enable FlexibleContexts in Servant.API.ContentTypes

2+prs: #1477

3+

4+description: {

5+

6+Starting with GHC 9.2, UndecidableInstances no longer implies FlexibleContexts.

7+Add this extension where it's needed to make compilation succeed.

8+

9+}

changelog.d/1529new file+10

@@ -0,0 +1,10 @@

1+synopsis: Fix performRequest in servant-client-ghcjs

2+prs: #1529

3+

4+description: {

5+

6+performRequest function in servant-client-ghcjs was not compatible with the

7+latest RunClient typeclass. Added the acceptStatus parameter and fixed the

8+functionality to match what servant-client provides.

9+

10+}

changelog.d/1556new file+81

@@ -0,0 +1,81 @@

1+synopsis: Display capture hints in router layout

2+prs: #1556

3+

4+description: {

5+

6+This PR enhances the `Servant.Server.layout` function, which produces a textual description of the routing layout of an API. More precisely, it changes `<capture>` blocks, so that they display the name and type of the variable being captured instead.

7+

8+Example:

9+

10+For the following API

11+```haskell

12+type API =

13+ "a" :> "d" :> Get '[JSON] NoContent

14+ :<|> "b" :> Capture "x" Int :> Get '[JSON] Bool

15+ :<|> "a" :> "e" :> Get '[JSON] Int

16+```

17+

18+we previously got the following output:

19+

20+```

21+/

22+├─ a/

23+│ ├─ d/

24+│ │ └─•

25+│ └─ e/

26+│ └─•

27+└─ b/

28+ └─ <capture>/

29+ ├─•

30+ ┆

31+ └─•

32+```

33+

34+now we get:

35+

36+```

37+/

38+├─ a/

39+│ ├─ d/

40+│ │ └─•

41+│ └─ e/

42+│ └─•

43+└─ b/

44+ └─ <x::Int>/

45+ ├─•

46+ ┆

47+ └─•

48+```

49+

50+This change is achieved by the introduction of a CaptureHint type, which is passed as an extra argument to the CaptureRouter and CaptureAllRouter constructors for the Router' type.

51+CaptureHint values are then used in routerLayout, to display the name and type of captured values, instead of just `<capture>` previously.

52+

53+N.B.:

54+Because the choice smart constructor for routers can aggregate Capture combinators with different capture hints, the Capture*Router constructors actually take a list of CaptureHint, instead of a single one.

55+

56+This PR also introduces Spec tests for the routerLayout function.

57+

58+Warning:

59+This change is potentially breaking, because it adds the constraint `Typeable a` to all types that are to be captured. Because all types are typeable since GHC 7.10, this is not as bad as it sounds ; it only break expressions where `a` is quantified in an expression with `Capture a`.

60+In those cases, the fix is easy: it suffices to add `Typeable a` to the left-hand side of the quantification constraint.

61+

62+For instance, the following code will no longer compile:

63+```haskell

64+type MyAPI a = Capture "foo" a :> Get '[JSON] ()

65+

66+myServer :: forall a. Server (MyAPI a)

67+myServer = const $ return ()

68+

69+myApi :: forall a. Proxy (MyAPI a)

70+myApi = Proxy

71+

72+app :: forall a. (FromHttpApiData a) => Application

73+app = serve (myApi @a) (myServer @a)

74+```

75+

76+Indeed, `app` should be replaced with:

77+```haskell

78+app :: forall a. (FromHttpApiData a, Typeable a) => Application

79+app = serve (myApi @a) (myServer @a)

80+```

81+}

changelog.d/1569new file+13

@@ -0,0 +1,13 @@

1+synopsis: Encode captures using toEncodedUrlPiece

2+prs: #1569

3+issues: #1511

4+

5+description: {

6+The `servant-client` library now makes direct use of `toEncodedUrlPiece` from `ToHttpApiData`

7+to encode captured values when building the request path. It gives user freedom to implement

8+URL-encoding however they need.

9+

10+Previous behavior was to use `toUrlPiece` and URL-encode its output using `toEncodedUrlPiece`

11+from the `Text` instance of `ToHttpApiData`. The issue with this approach is that

12+`ToHttpApiData Text` is overly zealous and also encodes characters, such as `*`, which are perfectly valid in a URL.

13+}

changelog.d/1580new file+12

@@ -0,0 +1,12 @@

1+synopsis: Allow IO in validationKeys

2+prs: #1580

3+issues: #1579

4+

5+description: {

6+

7+Currently validationKeys are a fixed JWKSet. This does not work with OIDC

8+providers such as AWS Cognito or Okta, which regularly fetching jwks_uri to

9+discover new and expired keys.

10+

11+This change alters the type of validationKeys from JWKSet to IO JWKSet.

12+}

changelog.d/1589new file+2

@@ -0,0 +1,2 @@

1+synopsis: Only include question mark for nonempty query strings

2+prs: 1589

changelog.d/1595new file+2

@@ -0,0 +1,2 @@

1+synopsis: Run ClientEnv's makeClientRequest in IO.

2+prs: #1595

changelog.d/confignew file+2

@@ -0,0 +1,2 @@

1+organization: haskell-servant

2+repository: servant

changelog.d/servant-docs-curlnew file+16

@@ -0,0 +1,16 @@

1+synopsis: Add sample cURL requests to generated documentation

2+prs: #1401

3+

4+description: {

5+

6+Add sample cURL requests to generated documentation.

7+

8+Those supplying changes to the Request `header` field manually using

9+lenses will need to add a sample bytestring value.

10+

11+`headers <>~ ["unicorn"]`

12+

13+becomes

14+

15+`headers <>~ [("unicorn", "sample value")]`

16+}

default.nixnew file+38

@@ -0,0 +1,38 @@

1+with (builtins.fromJSON (builtins.readFile ./nix/nixpkgs.json));

2+{

3+ pkgs ? import (builtins.fetchTarball {

4+ url = "https://github.com/NixOS/nixpkgs/archive/${rev}.tar.gz";

5+ inherit sha256;

6+ }) {}

7+, compiler ? "ghc883"

8+}:

9+let

10+ overrides = self: super: {

11+ servant = self.callCabal2nix "servant" ./servant {};

12+ servant-docs = self.callCabal2nix "servant-docs" ./servant-docs {};

13+ servant-pipes = self.callCabal2nix "servant-pipes" ./servant-pipes {};

14+ servant-server = self.callCabal2nix "servant-server" ./servant-server {};

15+ servant-client = self.callCabal2nix "servant-client" ./servant-client {};

16+ servant-foreign = self.callCabal2nix "servant-foreign" ./servant-foreign {};

17+ servant-conduit = self.callCabal2nix "servant-conduit" ./servant-conduit {};

18+ servant-machines = self.callCabal2nix "servant-machines" ./servant-machines {};

19+ servant-client-core = self.callCabal2nix "servant-client-core" ./servant-client-core {};

20+ servant-http-streams = self.callCabal2nix "servant-http-streams" ./servant-http-streams {};

21+ };

22+ hPkgs = pkgs.haskell.packages.${compiler}.override { inherit overrides; };

23+in

24+ with hPkgs;

25+ {

26+ inherit

27+ servant

28+ servant-client

29+ servant-client-core

30+ servant-conduit

31+ servant-docs

32+ servant-foreign

33+ servant-http-streams

34+ servant-machines

35+ servant-pipes

36+ servant-server;

37+ }

38+

doc/Makefile+1−1

@@ -10,7 +10,7 @@ BUILDDIR = _build

10

11# Put it first so that "make" without argument is like "make help".

12help:

13− @if [ ! -d venv ]; then echo "WARNING: There is no venv directory, did you forget to 'virtualenv venv'. Check building-the-docs file."; fi

13+ @if [ ! -d venv ]; then echo "WARNING: There is no venv directory, did you forget to 'virtualenv venv'. Check README.md."; fi

14 @if [ ! "z$$(which $(SPHINXBUILD))" = "z$$(pwd)/venv/bin/sphinx-build" ]; then echo "WARNING: Did you forgot to 'source venv/bin/activate'"; fi

15 @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

16

doc/conf.py+1−2

@@ -46,7 +46,7 @@ master_doc = 'index'

46

47# General information about the project.

48project = u'Servant'

49−copyright = u'2018, Servant Contributors'

49+copyright = u'2022, Servant Contributors'

50author = u'Servant Contributors'

51

52# The version info for the project you're documenting, acts as replacement for

@@ -169,4 +169,3 @@ texinfo_documents = [

169source_parsers = {

170 '.lhs': CommonMarkParser,

171}

172−

doc/cookbook/basic-auth/basic-auth.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-basic-auth

2name: cookbook-basic-auth

2version: 0.1

3version: 0.1

3synopsis: Basic Authentication cookbook example

4synopsis: Basic Authentication cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-basic-auth

14 main-is: BasicAuth.lhs

doc/cookbook/basic-streaming/Streaming.lhs+4−1

@@ -8,7 +8,10 @@ In other words, without streaming libraries.

8- Some basic usage doesn't require usage of streaming libraries,

9 like `conduit`, `pipes`, `machines` or `streaming`.

10 We have bindings for them though.

11−- This is similar example file, which is bundled with each of the packages (TODO: links)

11+- Similar example is bundled with each of our streaming library interop packages (see

12+[servant-pipes](https://github.com/haskell-servant/servant/blob/master/servant-pipes/example/Main.hs),

13+[servant-conduit](https://github.com/haskell-servant/servant/blob/master/servant-conduit/example/Main.hs) and

14+[servant-machines](https://github.com/haskell-servant/servant/blob/master/servant-machines/example/Main.hs))

12- `SourceT` doesn't have *Prelude* with handy combinators, so we have to write

15- `SourceT` doesn't have *Prelude* with handy combinators, so we have to write

13 things ourselves. (Note to self: `mapM` and `foldM` would be handy to have).

16 things ourselves. (Note to self: `mapM` and `foldM` would be handy to have).

14

17

doc/cookbook/basic-streaming/basic-streaming.cabal+4−4

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-basic-streaming

2name: cookbook-basic-streaming

2version: 2.1

3version: 2.1

3synopsis: Streaming in servant without streaming libs

4synopsis: Streaming in servant without streaming libs

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-basic-streaming

14 main-is: Streaming.lhs

@@ -17,7 +17,7 @@ executable cookbook-basic-streaming

17 ghc-options: -Wall -pgmL markdown-unlit -threaded -rtsopts

18

19 hs-source-dirs: .

20− build-depends: base >= 4.8 && <4.13

20+ build-depends: base >= 4.8 && <5

21 , aeson

22 , bytestring

23 , servant

doc/cookbook/curl-mock/CurlMock.lhs+8−21

@@ -1,7 +1,7 @@

1# Generating mock curl calls

2

3In this example we will generate curl requests with mock post data from a servant API.

4−This may be usefull for testing and development purposes.

4+This may be useful for testing and development purposes.

5Especially post requests with a request body are tedious to send manually.

6

7Also, we will learn how to use the servant-foreign library to generate stuff from servant APIs.

@@ -24,7 +24,6 @@ Language extensions and imports:

24import Control.Lens ((^.))

25import Data.Aeson

26import Data.Aeson.Text

27−import Data.Monoid ((<>))

28import Data.Proxy (Proxy (Proxy))

27import Data.Proxy (Proxy (Proxy))

29import Data.Text (Text)

28import Data.Text (Text)

30import Data.Text.Encoding (decodeUtf8)

29import Data.Text.Encoding (decodeUtf8)

@@ -86,7 +85,7 @@ listFromAPI :: (HasForeign lang ftype api, GenerateList ftype (Foreign ftype api

86```

85```

87

86

88This looks a bit confusing...

87This looks a bit confusing...

89−[Here](https://hackage.haskell.org/package/servant-foreign-0.11.1/docs/Servant-Foreign.html#t:HasForeignType) is the documentation for the `HasForeign` typeclass.

88+[Here](https://hackage.haskell.org/package/servant-foreign/docs/Servant-Foreign.html#t:HasForeign) is the documentation for the `HasForeign` typeclass.

90We will not go into details here, but this allows us to create a value of type `ftype` for any type `a` in our API.

89We will not go into details here, but this allows us to create a value of type `ftype` for any type `a` in our API.

91

90

92In our case we want to create a mock of every type `a`.

91In our case we want to create a mock of every type `a`.

@@ -130,24 +129,12 @@ generateCurl :: (GenerateList Mocked (Foreign Mocked api), HasForeign NoLang Moc

130generateCurl p host =

129generateCurl p host =

131 fmap T.unlines body

130 fmap T.unlines body

132 where

131 where

133− body = foldr (\endp curlCalls -> mCons (generateEndpoint host endp) curlCalls) (return [])

132+ body = mapM (generateEndpoint host)

134 $ listFromAPI (Proxy :: Proxy NoLang) (Proxy :: Proxy Mocked) p

133 $ listFromAPI (Proxy :: Proxy NoLang) (Proxy :: Proxy Mocked) p

135```

134```

136

135

137−To understand this function, better start at the end:

136+First, `listFromAPI` gives us a list of `Req Mocked`. Each `Req` describes one endpoint from the API type.

138−

137+We generate a curl call for each of them using the following helper.

139−`listFromAPI` gives us a list of endpoints. We iterate over them (`foldr`) and call `generateEndpoint` for every endpoint.

140−

141−As generate endpoint will not return `Text` but `IO Text` (remember we need some random bits to mock), we cannot just use the cons operator but need to build `IO [Text]` from `IO Text`s.

142−

143−``` haskell

144−mCons :: IO a -> IO [a] -> IO [a]

145−mCons ele list =

146− ele >>= \e -> list >>= \l -> return ( e : l )

147−```

148−

149−

150−Now comes the juicy part; accessing the endpoints data:

151

138

152``` haskell

139``` haskell

153generateEndpoint :: Text -> Req Mocked -> IO Text

140generateEndpoint :: Text -> Req Mocked -> IO Text

@@ -169,7 +156,7 @@ generateEndpoint host req =

169`servant-foreign` offers a multitude of lenses to be used with `Req`-values.

156`servant-foreign` offers a multitude of lenses to be used with `Req`-values.

170

157

171`reqMethod` gives us a straigthforward `Network.HTTP.Types.Method`, `reqUrl` the url part and so on.

158`reqMethod` gives us a straigthforward `Network.HTTP.Types.Method`, `reqUrl` the url part and so on.

172−Just take a look at [the docs](https://hackage.haskell.org/package/servant-foreign-0.11.1/docs/Servant-Foreign.html).

159+Just take a look at [the docs](https://hackage.haskell.org/package/servant-foreign/docs/Servant-Foreign.html).

173

160

174But how do we get our mocked json string? This seems to be a bit to short to be true:

161But how do we get our mocked json string? This seems to be a bit to short to be true:

175

162

@@ -201,7 +188,7 @@ And now, lets hook it all up in our main function:

201``` haskell

188``` haskell

202main :: IO ()

189main :: IO ()

203main =

190main =

204− generateCurl api "localhost:8081" >>= (\v -> T.IO.putStrLn v)

191+ generateCurl api "localhost:8081" >>= T.IO.putStrLn

205```

192```

206

193

207Done:

194Done:

@@ -213,6 +200,6 @@ curl -X POST -d '{"email":"wV򝣀_b򆎘:z񁊞򲙲!(3DM V","age":10,"name":"=|W"}

213```

200```

214

201

215This is of course no complete curl call mock generator, many things including path arguments are missing.

202This is of course no complete curl call mock generator, many things including path arguments are missing.

216−But it correctly generate mock calls for simple POST requests.

203+But it correctly generates mock calls for simple POST requests.

217

204

218Also, we now know how to use `HasForeignType` and `listFromAPI` to generate anything we want.

205Also, we now know how to use `HasForeignType` and `listFromAPI` to generate anything we want.

doc/cookbook/curl-mock/curl-mock.cabal+6−3

@@ -1,16 +1,19 @@

1+cabal-version: 2.2

1name: cookbook-curl-mock

2name: cookbook-curl-mock

2version: 0.1

3version: 0.1

3synopsis: Generate curl mock requests cookbook example

4synopsis: Generate curl mock requests cookbook example

4homepage: http://docs.servant.dev

5homepage: http://docs.servant.dev

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbock-curl-mock

14+ if impl(ghc >= 9.2)

15+ -- generic-arbitrary is incompatible

16+ buildable: False

14 main-is: CurlMock.lhs

17 main-is: CurlMock.lhs

15 build-depends: base == 4.*

18 build-depends: base == 4.*

16 , aeson

19 , aeson

doc/cookbook/custom-errors/CustomErrors.lhsnew file+189

@@ -0,0 +1,189 @@

1+# Customizing errors from Servant

2+

3+Servant handles a lot of parsing and validation of the input request. When it can't parse something: query

4+parameters, URL parts or request body, it will return appropriate HTTP codes like 400 Bad Request.

5+

6+These responses will contain the error message in their body without any formatting. However, it is often

7+desirable to be able to provide custom formatting for these error messages, for example, to wrap them in JSON.

8+

9+Recently Servant got a way to add such formatting. This Cookbook chapter demonstrates how to use it.

10+

11+Extensions and imports:

12+```haskell

13+{-# LANGUAGE DataKinds #-}

14+{-# LANGUAGE DeriveGeneric #-}

15+{-# LANGUAGE OverloadedStrings #-}

16+{-# LANGUAGE PolyKinds #-}

17+{-# LANGUAGE TypeFamilies #-}

18+{-# LANGUAGE TypeOperators #-}

19+

20+import Data.Aeson

21+import Data.Proxy

22+import Data.Text

23+import GHC.Generics

24+import Network.Wai

25+import Network.Wai.Handler.Warp

26+

27+import Servant

28+

29+import Data.String.Conversions

30+ (cs)

31+import Servant.API.ContentTypes

32+```

33+

34+The API (from `greet.hs` example in Servant sources):

35+

36+```haskell

37+-- | A greet message data type

38+newtype Greet = Greet { _msg :: Text }

39+ deriving (Generic, Show)

40+

41+instance FromJSON Greet

42+instance ToJSON Greet

43+

44+-- API specification

45+type TestApi =

46+ -- GET /hello/:name?capital={true, false} returns a Greet as JSON

47+ "hello" :> Capture "name" Text :> QueryParam "capital" Bool :> Get '[JSON] Greet

48+

49+ -- POST /greet with a Greet as JSON in the request body,

50+ -- returns a Greet as JSON

51+ :<|> "greet" :> ReqBody '[JSON] Greet :> Post '[JSON] Greet

52+

53+ -- DELETE /greet/:greetid

54+ :<|> "greet" :> Capture "greetid" Text :> Delete '[JSON] NoContent

55+

56+testApi :: Proxy TestApi

57+testApi = Proxy

58+

59+-- Server-side handlers.

60+--

61+-- There's one handler per endpoint, which, just like in the type

62+-- that represents the API, are glued together using :<|>.

63+--

64+-- Each handler runs in the 'Handler' monad.

65+server :: Server TestApi

66+server = helloH :<|> postGreetH :<|> deleteGreetH

67+

68+ where helloH name Nothing = helloH name (Just False)

69+ helloH name (Just False) = return . Greet $ "Hello, " <> name

70+ helloH name (Just True) = return . Greet . toUpper $ "Hello, " <> name

71+

72+ postGreetH greet = return greet

73+

74+ deleteGreetH _ = return NoContent

75+```

76+

77+## Error formatters

78+

79+`servant-server` provides an `ErrorFormatter` type to specify how the error message will be

80+formatted. A formatter is just a function accepting three parameters:

81+

82+- `TypeRep` from `Data.Typeable`: this is a runtime representation of the type of the combinator

83+ (like `Capture` or `ReqBody`) that generated the error. It can be used to display its name (with

84+ `show`) or even dynamically dispatch on the combinator type. See the docs for `Data.Typeable` and

85+ `Type.Reflection` modules.

86+- `Request`: full information for the request that led to the error.

87+- `String`: specific error message from the combinator.

88+

89+The formatter is expected to produce a `ServerError` which will be returned from the handler.

90+

91+Additionally, there is `NotFoundErrorFormatter`, which accepts only `Request` and can customize the

92+error in case when no route can be matched (HTTP 404).

93+

94+Let's make two formatters. First one will wrap our error in a JSON:

95+

96+```json

97+{

98+ "error": "ERROR MESSAGE",

99+ "combinator": "NAME OF THE COMBINATOR"

100+}

101+```

102+

103+Additionally, this formatter will examine the `Accept` header of the request and generate JSON

104+message only if client can accept it.

105+

106+```haskell

107+customFormatter :: ErrorFormatter

108+customFormatter tr req err =

109+ let

110+ -- aeson Value which will be sent to the client

111+ value = object ["combinator" .= show tr, "error" .= err]

112+ -- Accept header of the request

113+ accH = getAcceptHeader req

114+ in

115+ -- handleAcceptH is Servant's function that checks whether the client can accept a

116+ -- certain message type.

117+ -- In this case we call it with "Proxy '[JSON]" argument, meaning that we want to return a JSON.

118+ case handleAcceptH (Proxy :: Proxy '[JSON]) accH value of

119+ -- If client can't handle JSON, we just return the body the old way

120+ Nothing -> err400 { errBody = cs err }

121+ -- Otherwise, we return the JSON formatted body and set the "Content-Type" header.

122+ Just (ctypeH, body) -> err400

123+ { errBody = body

124+ , errHeaders = [("Content-Type", cs ctypeH)]

125+ }

126+

127+notFoundFormatter :: NotFoundErrorFormatter

128+notFoundFormatter req =

129+ err404 { errBody = cs $ "Not found path: " <> rawPathInfo req }

130+```

131+

132+If you don't need to react to the `Accept` header, you can just unconditionally return the JSON like

133+this (with `encode` from `Data.Aeson`):

134+

135+```

136+err400

137+ { errBody = encode body

138+ , errHeaders = [("Content-Type", "application/json")]

139+ }

140+```

141+

142+## Passing formatters to Servant

143+

144+Servant uses the Context to configure formatters. You only need to add a value of type

145+`ErrorFormatters` to your context. This is a record with the following fields:

146+

147+- `bodyParserErrorFormatter :: ErrorFormatter`

148+- `urlParseErrorFormatter :: ErrorFormatter`

149+- `headerParseErrorFormatter :: ErrorFormatter`

150+- `notFoundErrorFormatter :: NotFoundErrorFormatter`

151+

152+Default formatters are exported as `defaultErrorFormatters`, so you can use record update syntax to

153+set the only ones you need:

154+

155+```haskell

156+customFormatters :: ErrorFormatters

157+customFormatters = defaultErrorFormatters

158+ { bodyParserErrorFormatter = customFormatter

159+ , notFoundErrorFormatter = notFoundFormatter

160+ }

161+```

162+

163+And at last, use `serveWithContext` to run your server as usual:

164+

165+```haskell

166+app :: Application

167+app = serveWithContext testApi (customFormatters :. EmptyContext) server

168+

169+main :: IO ()

170+main = run 8000 app

171+```

172+

173+Now if we try to request something with a wrong body, we will get a nice error:

174+

175+```

176+$ http -j POST localhost:8000/greet 'foo=bar'

177+HTTP/1.1 400 Bad Request

178+Content-Type: application/json;charset=utf-8

179+Date: Fri, 17 Jul 2020 13:34:18 GMT

180+Server: Warp/3.3.12

181+Transfer-Encoding: chunked

182+

183+{

184+ "combinator": "ReqBody'",

185+ "error": "Error in $: parsing Main.Greet(Greet) failed, key \"_msg\" not found"

186+}

187+```

188+

189+Notice the `Content-Type` header set by our combinator.

doc/cookbook/custom-errors/custom-errors.cabalnew file+25

@@ -0,0 +1,25 @@

1+cabal-version: 2.2

2+name: cookbook-custom-errors

3+version: 0.1

4+synopsis: Return custom error messages from combinators

5+homepage: http://docs.servant.dev

6+license: BSD-3-Clause

7+license-file: ../../../servant/LICENSE

8+author: Servant Contributors

9+maintainer: haskell-servant-maintainers@googlegroups.com

10+build-type: Simple

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12+

13+executable cookbook-custom-errors

14+ main-is: CustomErrors.lhs

15+ build-depends: base == 4.*

16+ , aeson

17+ , servant

18+ , servant-server

19+ , string-conversions

20+ , text

21+ , wai

22+ , warp

23+ default-language: Haskell2010

24+ ghc-options: -Wall -pgmL markdown-unlit

25+ build-tool-depends: markdown-unlit:markdown-unlit

doc/cookbook/db-mysql-basics/MysqlBasics.lhs+1−1

@@ -2,7 +2,7 @@

2

3This doc will walk through a single-module implementation of a servant API connecting to a MySQL database. It will also include some basic CRUD operations.

4

5−Once you can wrap your head around this implemenation, understanding more complex features like resource pools would be beneficial next steps.

5+Once you can wrap your head around this implementation, understanding more complex features like resource pools would be beneficial next steps.

6

7The only *prerequisite* is that you have a MySQL database open on port 3306 of your machine. Docker is an easy way to manage this.

8

doc/cookbook/db-mysql-basics/mysql-basics.cabal+2−2

@@ -1,13 +1,13 @@

1+cabal-version: 2.2

1name: mysql-basics

2name: mysql-basics

2version: 0.1.0.0

3version: 0.1.0.0

3synopsis: Simple MySQL API cookbook example

4synopsis: Simple MySQL API cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11

12executable run

13 hs-source-dirs: .

doc/cookbook/db-postgres-pool/db-postgres-pool.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-db-postgres-pool

2name: cookbook-db-postgres-pool

2version: 0.1

3version: 0.1

3synopsis: Simple PostgreSQL connection pool cookbook example

4synopsis: Simple PostgreSQL connection pool cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-db-postgres-pool

14 main-is: PostgresPool.lhs

doc/cookbook/db-sqlite-simple/db-sqlite-simple.cabal+4−4

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-db-sqlite-simple

2name: cookbook-db-sqlite-simple

2version: 0.1

3version: 0.1

3synopsis: Simple SQLite DB cookbook example

4synopsis: Simple SQLite DB cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-db-sqlite-simple

14 main-is: DBConnection.lhs

@@ -23,7 +23,7 @@ executable cookbook-db-sqlite-simple

23 , http-types >= 0.12

24 , markdown-unlit >= 0.4

25 , http-client >= 0.5

26− , sqlite-simple >= 0.4

26+ , sqlite-simple >= 0.4.5.0

27 , transformers

28 default-language: Haskell2010

29 ghc-options: -Wall -pgmL markdown-unlit

doc/cookbook/file-upload/FileUpload.lhs+2−2

@@ -90,8 +90,8 @@ startServer = run 8080 (serve api upload)

90

91Finally, a main function that brings up our server and

92sends some test request with `http-client` (and not

93−servant-client this time, has servant-multipart does not

93+servant-client this time, as servant-multipart does not

94−yet have support for client generation.

94+yet have support for client generation).

95

96``` haskell

97main :: IO ()

doc/cookbook/file-upload/file-upload.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-file-upload

2name: cookbook-file-upload

2version: 0.1

3version: 0.1

3synopsis: File upload cookbook example

4synopsis: File upload cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-file-upload

14 main-is: FileUpload.lhs

doc/cookbook/generic/Generic.lhs+3−3

@@ -43,13 +43,13 @@ api :: Proxy (ToServantApi Routes)

43api = genericApi (Proxy :: Proxy Routes)

44```

45

46−It's recommented to use `genericApi` function, as then you'll get

46+It's recommended to use `genericApi` function, as then you'll get

47better error message, for example if you forget to `derive Generic`.

48

49## Links

50

51The clear advantage of record-based generics approach, is that

52−we can get safe links very conviently. We don't need to define endpoint types,

52+we can get safe links very conveniently. We don't need to define endpoint types,

53as field accessors work as proxies:

54

55```haskell

@@ -67,7 +67,7 @@ routesLinks = allFieldLinks

67## Client

68

69Even more power starts to show when we generate a record of client functions.

70−Here we use `genericClientHoist` function, which let us simultaneously

70+Here we use `genericClientHoist` function, which lets us simultaneously

71hoist the monad, in this case from `ClientM` to `IO`.

72

73```haskell

doc/cookbook/generic/generic.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-generic

2name: cookbook-generic

2version: 0.1

3version: 0.1

3synopsis: Using custom monad to pass a state between handlers

4synopsis: Using custom monad to pass a state between handlers

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-using-custom-monad

14 main-is: Generic.lhs

doc/cookbook/hoist-server-with-context/HoistServerWithContext.lhs+2−2

@@ -254,7 +254,7 @@ loginHandler cookieSettings jwtSettings form = do

254 liftIO $ pushLogStrLn logset $ toLogStr logMsg

255 throwError err401

256 Just applyCookies -> do

257− let successMsg = logMsg{message = "AdminUser succesfully authenticated!"}

257+ let successMsg = logMsg{message = "AdminUser successfully authenticated!"}

258 liftIO $ pushLogStrLn logset $ toLogStr successMsg

259 pure $ applyCookies successMsg

260loginHandler _ _ _ = throwError err401

@@ -287,7 +287,7 @@ mkApp cfg cs jwts ctx =

287 (flip runReaderT ctx) (adminServer cs jwts)

288```

289

290−One footenote: because we'd like our logs to be in JSON form, we'll also create a `Middleware` object

290+One footnote: because we'd like our logs to be in JSON form, we'll also create a `Middleware` object

291so that `Warp` *also* will emit logs as JSON. This will ensure *all* logs are emitted as JSON:

292

293```haskell

doc/cookbook/hoist-server-with-context/hoist-server-with-context.cabal+4−4

@@ -1,17 +1,17 @@

1+cabal-version: 2.2

1name: cookbook-hoist-server-with-context

2name: cookbook-hoist-server-with-context

2version: 0.0.1

3version: 0.0.1

3synopsis: JWT and basic access authentication with a Custom Monad cookbook example

4synopsis: JWT and basic access authentication with a Custom Monad cookbook example

4description: Using servant-auth to support both JWT-based and basic

5description: Using servant-auth to support both JWT-based and basic

5 authentication.

6 authentication.

6homepage: http://docs.servant.dev/

7homepage: http://docs.servant.dev/

7−license: BSD3

8+license: BSD-3-Clause

8license-file: ../../../servant/LICENSE

9license-file: ../../../servant/LICENSE

9author: Servant Contributors

10author: Servant Contributors

10maintainer: haskell-servant-maintainers@googlegroups.com

11maintainer: haskell-servant-maintainers@googlegroups.com

11category: Servant

12category: Servant

12build-type: Simple

13build-type: Simple

13−cabal-version: >=1.10

14−tested-with: GHC==8.4.4, GHC==8.6.5

14+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

15

16executable cookbook-hoist-server-with-context

17 main-is: HoistServerWithContext.lhs

@@ -24,7 +24,7 @@ executable cookbook-hoist-server-with-context

24 , servant

25 , servant-server

26 , servant-auth >= 0.3.2

27− , servant-auth-server

27+ , servant-auth-server >= 0.4.4.0

28 , time

29 , warp >= 3.2

30 , wai >= 3.2

doc/cookbook/https/Https.lhs+5−5

@@ -34,16 +34,16 @@ app = serve api server

34```

35

36It's now time to actually run the `Application`.

37−The [`warp-tls`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html)

37+The [`warp-tls`](https://hackage.haskell.org/package/warp-tls/docs/Network-Wai-Handler-WarpTLS.html)

38package provides two functions for running an `Application`, called

39−[`runTLS`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLS)

39+[`runTLS`](https://hackage.haskell.org/package/warp-tls/docs/Network-Wai-Handler-WarpTLS.html#v:runTLS)

40−and [`runTLSSocket`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLSSocket).

40+and [`runTLSSocket`](https://hackage.haskell.org/package/warp-tls/docs/Network-Wai-Handler-WarpTLS.html#v:runTLSSocket).

41We will be using the first one.

42

43It takes two arguments,

44−[the TLS settings](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#t:TLSSettings)

44+[the TLS settings](https://hackage.haskell.org/package/warp-tls/docs/Network-Wai-Handler-WarpTLS.html#t:TLSSettings)

45(certificates, keys, ciphers, etc)

46−and [the warp settings](https://hackage.haskell.org/package/warp-3.2.12/docs/Network-Wai-Handler-Warp-Internal.html#t:Settings)

46+and [the warp settings](https://hackage.haskell.org/package/warp/docs/Network-Wai-Handler-Warp-Internal.html#t:Settings)

47(port, logger, etc).

48

49We will be using very simple settings for this example but you are of

doc/cookbook/https/https.cabal+4−4

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-https

2name: cookbook-https

2version: 0.1

3version: 0.1

3synopsis: HTTPS cookbook example

4synopsis: HTTPS cookbook example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-https

14 main-is: Https.lhs

@@ -17,7 +17,7 @@ executable cookbook-https

17 , servant-server

18 , wai >= 3.2

19 , warp >= 3.2

20− , warp-tls >= 3.2

20+ , warp-tls >= 3.2.9

21 , markdown-unlit >= 0.4

22 default-language: Haskell2010

23 ghc-options: -Wall -pgmL markdown-unlit

doc/cookbook/index.rst+4−2

@@ -6,8 +6,8 @@ how to solve many common problems with servant. If you're

6interested in contributing examples of your own, feel free

7to open an issue or a pull request on

8`our github repository <https://github.com/haskell-servant/servant>`_

9−or even to just get in touch with us on the **#servant** IRC channel

9+or even to just get in touch with us on the `**#haskell-servant** IRC channel

10−on freenode or on

10+on libera.chat <https://web.libera.chat/#haskell-servant>_ or on

11`the mailing list <https://groups.google.com/forum/#!forum/haskell-servant>`_.

12

13The scope is very wide. Simple and fancy authentication schemes,

@@ -25,6 +25,8 @@ you name it!

25 db-postgres-pool/PostgresPool.lhs

26 using-custom-monad/UsingCustomMonad.lhs

27 using-free-client/UsingFreeClient.lhs

28+ custom-errors/CustomErrors.lhs

29+ uverb/UVerb.lhs

28 basic-auth/BasicAuth.lhs

30 basic-auth/BasicAuth.lhs

29 basic-streaming/Streaming.lhs

31 basic-streaming/Streaming.lhs

30 jwt-and-basic-auth/JWTAndBasicAuth.lhs

32 jwt-and-basic-auth/JWTAndBasicAuth.lhs

doc/cookbook/jwt-and-basic-auth/jwt-and-basic-auth.cabal+4−4

@@ -1,17 +1,17 @@

1+cabal-version: 2.2

1name: cookbook-jwt-and-basic-auth

2name: cookbook-jwt-and-basic-auth

2version: 0.0.1

3version: 0.0.1

3synopsis: JWT and basic access authentication cookbook example

4synopsis: JWT and basic access authentication cookbook example

4description: Using servant-auth to support both JWT-based and basic

5description: Using servant-auth to support both JWT-based and basic

5 authentication.

6 authentication.

6homepage: http://docs.servant.dev/

7homepage: http://docs.servant.dev/

7−license: BSD3

8+license: BSD-3-Clause

8license-file: ../../../servant/LICENSE

9license-file: ../../../servant/LICENSE

9author: Servant Contributors

10author: Servant Contributors

10maintainer: haskell-servant-maintainers@googlegroups.com

11maintainer: haskell-servant-maintainers@googlegroups.com

11category: Servant

12category: Servant

12build-type: Simple

13build-type: Simple

13−cabal-version: >=1.10

14−tested-with: GHC==8.4.4, GHC==8.6.5

14+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

15

16executable cookbook-jwt-and-basic-auth

17 main-is: JWTAndBasicAuth.lhs

@@ -22,7 +22,7 @@ executable cookbook-jwt-and-basic-auth

22 , servant

23 , servant-client

24 , servant-server

25− , servant-auth ==0.3.*

25+ , servant-auth == 0.4.*

26 , servant-auth-server >= 0.3.1.0

27 , warp >= 3.2

28 , wai >= 3.2

doc/cookbook/open-id-connect/OpenIdConnect.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: open-id-connect

2name: open-id-connect

2version: 0.1

3version: 0.1

3synopsis: OpenId Connect with Servant example

4synopsis: OpenId Connect with Servant example

4homepage: http://haskell-servant.readthedocs.org/

5homepage: http://haskell-servant.readthedocs.org/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >= 1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5

12

13executable cookbook-openidconnect

14 main-is: OpenIdConnect.lhs

doc/cookbook/open-id-connect/OpenIdConnect.lhs+16−16

@@ -8,8 +8,8 @@ some login token would be saved in the user agent local storage.

8

9Workflow:

10

11−1. user is presentend with a login button,

11+1. user is presented with a login button,

12−2. when the user click on the button it is redirected to the OIDC

12+2. when the user clicks on the button it is redirected to the OIDC

13 provider,

143. the user login in the OIDC provider,

154. the OIDC provider will redirect the user and provide a `code`,

@@ -221,9 +221,9 @@ The `AuthInfo` is about the infos we can grab from OIDC provider.

221

222To be more precise, the user should come with a `code` (a token) and

223POSTing that code to the correct OIDC provider endpoint should return a JSON

224−object. One of the field should be named `id_token` which should be a

224+object. One of the fields should be named `id_token` which should be a

225−JWT containing all the informations we need. Depending on the scopes we

225+JWT containing all the information we need. Depending on the scopes we

226−asked we might get more informations.

226+asked we might get more information.

227

228``` haskell

229-- | @AuthInfo@

@@ -248,16 +248,16 @@ instance JSON.ToJSON AuthInfo where

248type LoginHandler = AuthInfo -> IO (Either Text User)

249```

250

251−The `handleLoggedIn` is that part that will retrieve the informations from

251+The `handleLoggedIn` is that part that will retrieve the information from

252the user once he is redirected from the OIDC Provider after login.

253

254If the user is redirected to the `redirect_uri` but with an `error` query

255−parameter then it means something goes wrong.

255+parameter then it means something went wrong.

256If there is no error query param but a `code` query param it means the user

257−sucessfully logged in. From there we need to make a request to the token

257+successfully logged in. From there we need to make a request to the token

258−endpoint of the OIDC provider. Its a POST that should contains the code

258+endpoint of the OIDC provider. It's a POST that should contain the code

259−as well as the client id & secret.

259+as well as the client id and secret.

260−This is the role of the `requestTokens` to make this HTTP POST.

260+Making this HTTP POST is the responsibility of `requestTokens`.

261

262From there we extract the `claims` of the JWT contained in one of the value

263of the JSON returned by the POST HTTP Request.

@@ -329,12 +329,12 @@ data Customer = Customer {

329 }

330```

331

332−Here is the code that display the homepage.

332+Here is the code that displays the homepage.

333It should contain a link to the the `/login` URL.

334−When the user will click on this link it will be redirected to Google login page

334+When the user clicks on this link it will be redirected to Google login page

335−with some generated informations.

335+with some generated information.

336

337−The page also display the content of the local storage.

337+The page also displays the content of the local storage.

338And in particular the items `api-key` and `user-id`.

339Those items should be set after a successful login when the user is redirected to

340`/login/cb`.

@@ -366,7 +366,7 @@ instance ToMarkup Homepage where

366We need some helpers to generate random string for generating state and API Keys.

367

368``` haskell

369−-- | generate a random Bystestring, not necessarily extremely good randomness

369+-- | generate a random ByteString, not necessarily extremely good randomness

370-- still the password will be long enough to be very difficult to crack

371genRandomBS :: IO ByteString

372genRandomBS = do

doc/cookbook/pagination/Pagination.lhs+8−8

@@ -18,7 +18,7 @@ For example: `Range: createdAt 2017-01-15T23:14:67.000Z; offset 5; order desc` i

18the client is willing to retrieve the next batch of document in descending order that were

19created after the fifteenth of January, skipping the first 5.

20

21−As a response, the server may return the list of corresponding document, and augment the

21+As a response, the server may return the list of corresponding documents, and augment the

22response with 3 headers:

23

24- `Accept-Ranges`: A comma-separated list of fields upon which a range can be defined

@@ -127,7 +127,7 @@ defaultRange =

127 getDefaultRange (Proxy @Color)

128```

129

130−Note that `getFieldValue :: Proxy "name" -> Color -> String` is the minimal complete definintion

130+Note that `getFieldValue :: Proxy "name" -> Color -> String` is the minimal complete definition

131of the class. Yet, you can define `getRangeOptions` to provide different parsing options (see

132the last section of this guide). In the meantime, we've also defined a `defaultRange` as it will

133come in handy when defining our handler.

@@ -148,7 +148,7 @@ type MyHeaders =

148```

149

150`PageHeaders` is a type alias provided by the library to declare the necessary response headers

151−we mentionned in introduction. Expanding the alias boils down to the following:

151+we mentioned in introduction. Expanding the alias boils down to the following:

152

153``` haskell

154-- type MyHeaders =

@@ -165,7 +165,7 @@ not, _servant-pagination_ provides an easy way to lift a collection of resources

165#### Server

166

167Time to connect the last bits by defining the server implementation of our colorful API. The `Ranges`

168−type we've defined above (tight to the `Range` HTTP header) indicates the server to parse any `Range`

168+type we've defined above (tied to the `Range` HTTP header) indicates the server to parse any `Range`

169header, looking for the format defined in introduction with fields and target types we have just declared.

170If no such header is provided, we will end up receiving `Nothing`. Otherwise, it will be possible

171to _extract_ a `Range` from our `Ranges`.

@@ -192,7 +192,7 @@ the format we defined, where `<field>` here can only be `name` and `<value>` mus

192- `Range: <field> [<value>][; offset <o>][; limit <l>][; order <asc|desc>]`

193

194Beside the target field, everything is pretty much optional in the `Range` HTTP header. Missing parts

195−are deducted from the `RangeOptions` that are part of the `HasPagination` instance. Therefore, all

195+are deduced from the `RangeOptions` that are part of the `HasPagination` instance. Therefore, all

196following examples are valid requests to send to our server:

197

198- 1 - `curl http://localhost:1442/colors -vH 'Range: name'`

@@ -219,7 +219,7 @@ The previous ranges reads as follows:

219Note that in the simple above scenario, there's no ambiguity with `extractRange` and `returnRange`

220because there's only one possible `Range` defined on our resource. Yet, as you've most probably

221noticed, the `Ranges` combinator accepts a list of fields, each of which must declare a `HasPagination`

222−instance. Doing so will make the other helper functions more ambiguous and type annotation are

222+instance. Doing so will make the other helper functions more ambiguous and type annotations are

223highly likely to be needed.

224

225

@@ -235,8 +235,8 @@ instance HasPagination Color "hex" where

235#### Parsing Options

236

237By default, `servant-pagination` provides an implementation of `getRangeOptions` for each

238−`HasPagination` instance. However, this can be overwritten when defining the instance to provide

238+`HasPagination` instance. However, this can be overridden when defining the instance to provide

239−your own options. This options come into play when a `Range` header is received and isn't fully

239+your own options. These options come into play when a `Range` header is received and isn't fully

240specified (`limit`, `offset`, `order` are all optional) to provide default fallback values for those.

241

242For instance, let's say we wanted to change the default limit to `5` in a new range on

doc/cookbook/pagination/pagination.cabal+4−4

@@ -1,21 +1,21 @@

1+cabal-version: 2.2

1name: cookbook-pagination

2name: cookbook-pagination

2version: 2.1

3version: 2.1

3synopsis: Pagination with Servant example

4synopsis: Pagination with Servant example

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-pagination

14 main-is: Pagination.lhs

15 build-tool-depends: markdown-unlit:markdown-unlit

16 default-language: Haskell2010

17 ghc-options: -Wall -pgmL markdown-unlit

18− build-depends: base >= 4.8 && <4.13

18+ build-depends: base >= 4.9 && <5

19 , aeson

20 , servant

21 , servant-server

doc/cookbook/sentry/Sentry.lhs+2−2

@@ -79,14 +79,14 @@ It does three things. First it initializes the service which will communicate wi

79

80- the Sentry `DSN`, which is obtained when creating a new project on Sentry

81- a default way to update sentry fields, where we use the identity function

82−- an event trasport, which generally would be `sendRecord`, an HTTPS capable trasport which uses http-conduit

82+- an event transport, which generally would be `sendRecord`, an HTTPS capable transport which uses http-conduit

83- a fallback handler, which we choose to be `silentFallback` since later we are logging to the console anyway.

84

85In the second step it actually sends our message to Sentry with the `register` function. Its arguments are:

86

87- the configured Sentry service which we just created

88- the name of the logger

89−- the error level (see [SentryLevel](https://hackage.haskell.org/package/raven-haskell-0.1.2.0/docs/System-Log-Raven-Types.html#t:SentryLevel) for the possible options)

89+- the error level (see [SentryLevel](https://hackage.haskell.org/package/raven-haskell/docs/System-Log-Raven-Types.html#t:SentryLevel) for the possible options)

90- the message we want to send

91- an update function to handle the specific `SentryRecord`

92

doc/cookbook/sentry/sentry.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-sentry

2name: cookbook-sentry

2version: 0.1

3version: 0.1

3synopsis: Collecting runtime exceptions using Sentry

4synopsis: Collecting runtime exceptions using Sentry

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-sentry

14 main-is: Sentry.lhs

doc/cookbook/structuring-apis/StructuringApis.lhs+1−1

@@ -144,7 +144,7 @@ simpleAPIServer

144 :: m [a]

145 -> (i -> m a)

146 -> (a -> m NoContent)

147− -> Server (SimpleAPI name a i) m

147+ -> ServerT (SimpleAPI name a i) m

148simpleAPIServer listAs getA postA =

149 listAs :<|> getA :<|> postA

150

doc/cookbook/structuring-apis/structuring-apis.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-structuring-apis

2name: cookbook-structuring-apis

2version: 0.1

3version: 0.1

3synopsis: Example that shows how APIs can be structured

4synopsis: Example that shows how APIs can be structured

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-structuring-apis

14 main-is: StructuringApis.lhs

doc/cookbook/testing/testing.cabal+4−4

@@ -1,16 +1,16 @@

1+cabal-version: 2.2

1name: cookbook-testing

2name: cookbook-testing

2version: 0.0.1

3version: 0.0.1

3synopsis: Common testing patterns in Servant apps

4synopsis: Common testing patterns in Servant apps

4description: This recipe includes various strategies for writing tests for Servant.

5description: This recipe includes various strategies for writing tests for Servant.

5homepage: http://docs.servant.dev/

6homepage: http://docs.servant.dev/

6−license: BSD3

7+license: BSD-3-Clause

7license-file: ../../../servant/LICENSE

8license-file: ../../../servant/LICENSE

8author: Servant Contributors

9author: Servant Contributors

9maintainer: haskell-servant-maintainers@googlegroups.com

10maintainer: haskell-servant-maintainers@googlegroups.com

10category: Servant

11category: Servant

11build-type: Simple

12build-type: Simple

12−cabal-version: >=1.10

13−tested-with: GHC==8.4.4, GHC==8.6.5

13+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

14

15executable cookbook-testing

16 main-is: Testing.lhs

@@ -23,7 +23,7 @@ executable cookbook-testing

23 , servant

24 , servant-client

25 , servant-server

26− , servant-quickcheck

26+ , servant-quickcheck >= 0.0.10

27 , http-client

28 , http-types >= 0.12

29 , hspec

doc/cookbook/using-custom-monad/UsingCustomMonad.lhs+1−1

@@ -1,6 +1,6 @@

1# Using a custom monad

2

3−In this section we will create and API for a book shelf without any backing DB storage.

3+In this section we will create an API for a book shelf without any backing DB storage.

4We will keep state in memory and share it between requests using `Reader` monad and `STM`.

5

6We start with a pretty standard set of imports and definition of the model:

doc/cookbook/using-custom-monad/using-custom-monad.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-using-custom-monad

2name: cookbook-using-custom-monad

2version: 0.1

3version: 0.1

3synopsis: Using custom monad to pass a state between handlers

4synopsis: Using custom monad to pass a state between handlers

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-using-custom-monad

14 main-is: UsingCustomMonad.lhs

doc/cookbook/using-free-client/UsingFreeClient.lhs+6−6

@@ -2,7 +2,7 @@

2

3or simply put: _a practical introduction to `Servant.Client.Free`_.

4

5−Someone asked on IRC how one could access the intermediate Requests (resp. Responses)

5+Someone asked on IRC how one could access the intermediate Requests (resp. Responses)

6produced (resp. received) by client functions derived using servant-client.

7My response to such inquiries is: to extend `servant-client` in an ad-hoc way (e.g for testing or debugging

8purposes), use `Servant.Client.Free`. This recipe shows how.

@@ -119,7 +119,7 @@ Now we can use `servant-client`'s internals to convert servant's `Request`

119to http-client's `Request`, and we can inspect it:

120

121```haskell

122− let req' = I.requestToClientRequest burl req

122+ req' <- I.defaultMakeClientRequest burl req

123 putStrLn $ "Making request: " ++ show req'

124```

125

@@ -136,12 +136,12 @@ and calling the continuation. We should get a `Pure` value.

136

137```haskell

138 let res = I.clientResponseToResponse id res'

139−

139+

140 case k res of

141 Pure n ->

142 putStrLn $ "Expected 1764, got " ++ show n

143− _ ->

143+ _ ->

144− putStrLn "ERROR: didn't got a response"

144+ putStrLn "ERROR: didn't get a response"

145```

146

147So that's it. Using `Free` we can evaluate servant clients step-by-step, and

@@ -153,7 +153,7 @@ and responses available for us to inspect, since `RunClient` only gives us

153access to one `Request` or `Response` at a time.

154

155On the other hand, a "batch collection" of requests and/or responses can be achieved

156−with both free clients and a custom `RunClient` instance rather easily, for example

156+with both free clients and a custom `RunClient` instance rather easily, for example

157by using a `Writer [(Request, Response)]` monad.

158

159Here is an example of running our small `test` against a running server:

doc/cookbook/using-free-client/using-free-client.cabal+3−3

@@ -1,14 +1,14 @@

1+cabal-version: 2.2

1name: cookbook-using-free-client

2name: cookbook-using-free-client

2version: 0.1

3version: 0.1

3synopsis: Using Free client

4synopsis: Using Free client

4homepage: http://docs.servant.dev/

5homepage: http://docs.servant.dev/

5−license: BSD3

6+license: BSD-3-Clause

6license-file: ../../../servant/LICENSE

7license-file: ../../../servant/LICENSE

7author: Servant Contributors

8author: Servant Contributors

8maintainer: haskell-servant-maintainers@googlegroups.com

9maintainer: haskell-servant-maintainers@googlegroups.com

9build-type: Simple

10build-type: Simple

10−cabal-version: >=1.10

11−tested-with: GHC==8.4.4, GHC==8.6.5

11+tested-with: GHC==8.6.5, GHC==8.8.3, GHC ==8.10.7

12

13executable cookbook-using-free-client

14 main-is: UsingFreeClient.lhs

doc/cookbook/uverb/UVerb.lhsnew file+223

@@ -0,0 +1,223 @@

1+# Listing alternative responses and exceptions in your API types

2+

3+Servant allows you to talk about the exceptions you throw in your API

4+types. This is not limited to actual exceptions, you can write

5+handlers that respond with arbitrary open unions of types.

6+

7+## Compatibility

8+

9+:warning: This cookbook is compatible with GHC 8.6.1 or higher :warning:

10+

11+## Preliminaries

12+

13+```haskell

14+{-# LANGUAGE ConstraintKinds #-}

15+{-# LANGUAGE DataKinds #-}

16+{-# LANGUAGE DeriveGeneric #-}

17+{-# LANGUAGE DerivingStrategies #-}

18+{-# LANGUAGE DeriveAnyClass #-}

19+{-# LANGUAGE DerivingVia #-}

20+{-# LANGUAGE FlexibleContexts #-}

21+{-# LANGUAGE FlexibleInstances #-}

22+{-# LANGUAGE GeneralizedNewtypeDeriving #-}

23+{-# LANGUAGE InstanceSigs #-}

24+{-# LANGUAGE MultiParamTypeClasses #-}

25+{-# LANGUAGE OverloadedStrings #-}

26+{-# LANGUAGE ScopedTypeVariables #-}

27+{-# LANGUAGE StandaloneDeriving #-}

28+{-# LANGUAGE TypeApplications #-}

29+{-# LANGUAGE TypeFamilies #-}

30+{-# LANGUAGE TypeOperators #-}

31+{-# LANGUAGE UndecidableInstances #-}

32+{-# OPTIONS_GHC -Wall -Wno-orphans #-}

33+

34+import Control.Concurrent (threadDelay)

35+import Control.Concurrent.Async (async)

36+import Control.Monad (when)

37+import Control.Monad.Except (ExceptT (..), MonadError (..), MonadTrans (..), runExceptT)

38+import Data.Aeson (FromJSON (..), ToJSON (..))

39+import Data.Aeson.Encode.Pretty (encodePretty)

40+import Data.String.Conversions (cs)

41+import Data.Swagger (ToSchema)

42+import Data.Typeable (Proxy (Proxy))

43+import qualified GHC.Generics as GHC

44+import qualified Network.HTTP.Client as Client

45+import qualified Network.Wai.Handler.Warp as Warp

46+import Servant.API

47+import Servant.Client

48+import Servant.Server

49+import Servant.Swagger

50+```

51+

52+## The API

53+

54+This looks like a `Verb`-based routing table, except that `UVerb` has

55+no status, and carries a list of response types rather than a single

56+one. Each entry in the list carries its own response code.

57+

58+```haskell

59+type API =

60+ "fisx" :> Capture "bool" Bool

61+ :> UVerb 'GET '[JSON] '[FisxUser, WithStatus 303 String]

62+ :<|> "arian"

63+ :> UVerb 'GET '[JSON] '[WithStatus 201 ArianUser]

64+```

65+

66+Here are the details:

67+

68+```haskell

69+data FisxUser = FisxUser {name :: String}

70+ deriving (Eq, Show, GHC.Generic)

71+

72+instance ToJSON FisxUser

73+instance FromJSON FisxUser

74+instance ToSchema FisxUser

75+

76+-- | 'HasStatus' allows us to can get around 'WithStatus' if we want

77+-- to, and associate the status code with our resource types directly.

78+--

79+-- (To avoid orphan instances and make it more explicit what's in the

80+-- API and what isn't, we could even introduce a newtype 'Resource'

81+-- that wraps all the types we're using in our routing table, and then

82+-- define lots of 'HasStatus' instances for @Resource This@ and

83+-- @Resource That@.)

84+instance HasStatus FisxUser where

85+ type StatusOf FisxUser = 203

86+

87+data ArianUser = ArianUser

88+ deriving (Eq, Show, GHC.Generic)

89+

90+instance ToJSON ArianUser

91+instance FromJSON ArianUser

92+instance ToSchema ArianUser

93+```

94+

95+## Server, Client, Swagger

96+

97+You can just respond with any of the elements of the union in handlers.

98+

99+```haskell

100+fisx :: Bool -> Handler (Union '[FisxUser, WithStatus 303 String])

101+fisx True = respond (FisxUser "fisx")

102+fisx False = respond (WithStatus @303 ("still fisx" :: String))

103+

104+arian :: Handler (Union '[WithStatus 201 ArianUser])

105+arian = respond (WithStatus @201 ArianUser)

106+```

107+

108+You can create client functions like you're used to:

109+

110+```

111+fisxClient :: Bool -> ClientM (Union '[FisxUser, WithStatus 303 String])

112+arianClient :: ClientM (Union '[WithStatus 201 ArianUser])

113+(fisxClient :<|> arianClient) = client (Proxy @API)

114+```

115+

116+... and that's basically it! Here are a few sample commands that

117+show you how the swagger docs look like and how you can handle the

118+result unions in clients:

119+

120+```

121+main :: IO ()

122+main = do

123+ putStrLn . cs . encodePretty $ toSwagger (Proxy @API)

124+ _ <- async . Warp.run 8080 $ serve (Proxy @API) (fisx :<|> arian)

125+ threadDelay 50000

126+ mgr <- Client.newManager Client.defaultManagerSettings

127+ let cenv = mkClientEnv mgr (BaseUrl Http "localhost" 8080 "")

128+ result <- runClientM (fisxClient True) cenv

129+ print $ foldMapUnion (Proxy @Show) show <$> result

130+ print $ matchUnion @FisxUser <$> result

131+ print $ matchUnion @(WithStatus 303 String) <$> result

132+ pure ()

133+```

134+

135+## Idiomatic exceptions

136+

137+Since `UVerb` (probably) will mostly be used for error-like responses, it may be desirable to be able to early abort handler, like with current servant one would use `throwError` with `ServerError`.

138+

139+```haskell

140+newtype UVerbT xs m a = UVerbT { unUVerbT :: ExceptT (Union xs) m a }

141+ deriving (Functor, Applicative, Monad, MonadTrans)

142+

143+-- | Deliberately hide 'ExceptT's 'MonadError' instance to be able to use

144+-- underlying monad's instance.

145+instance MonadError e m => MonadError e (UVerbT xs m) where

146+ throwError = lift . throwError

147+ catchError (UVerbT act) h = UVerbT $ ExceptT $

148+ runExceptT act `catchError` (runExceptT . unUVerbT . h)

149+

150+-- | This combinator runs 'UVerbT'. It applies 'respond' internally, so the handler

151+-- may use the usual 'return'.

152+runUVerbT :: (Monad m, HasStatus x, IsMember x xs) => UVerbT xs m x -> m (Union xs)

153+runUVerbT (UVerbT act) = either id id <$> runExceptT (act >>= respond)

154+

155+-- | Short-circuit 'UVerbT' computation returning one of the response types.

156+throwUVerb :: (Monad m, HasStatus x, IsMember x xs) => x -> UVerbT xs m a

157+throwUVerb = UVerbT . ExceptT . fmap Left . respond

158+```

159+

160+Example usage:

161+

162+```haskell

163+data Foo = Foo Int Int Int

164+ deriving (Show, Eq, GHC.Generic, ToJSON)

165+ deriving HasStatus via WithStatus 200 Foo

166+

167+data Bar = Bar

168+ deriving (Show, Eq, GHC.Generic)

169+

170+instance ToJSON Bar

171+

172+h :: Handler (Union '[Foo, WithStatus 400 Bar])

173+h = runUVerbT $ do

174+ when ({- something bad -} True) $

175+ throwUVerb $ WithStatus @400 Bar

176+

177+ when ({- really bad -} False) $

178+ throwError $ err500

179+

180+ -- a lot of code here...

181+

182+ return $ Foo 1 2 3

183+```

184+

185+## Related Work

186+

187+There is the [issue from

188+2017](https://github.com/haskell-servant/servant/issues/841) that was

189+resolved by the introduction of `UVerb`, with a long discussion on

190+alternative designs.

191+

192+[servant-checked-exceptions](https://hackage.haskell.org/package/servant-checked-exceptions)

193+is a good solution to the problem, but it restricts the user to JSON

194+and a very specific envelop encoding for the union type, which is

195+often not acceptable. (One good reason for this design choice is that

196+it makes writing clients easier, where you need to get to the union

197+type from one representative, and you don't want to run several

198+parsers in the hope that the ones that should will always error out so

199+you can try until the right one returns a value.)

200+

201+[servant-exceptions](https://github.com/ch1bo/servant-exceptions) is

202+another shot at at the problem. It is inspired by

203+servant-checked-exceptions, so it may be worth taking a closer look.

204+The README claims that

205+[cardano-sl](https://github.com/input-output-hk/cardano-sl) also has

206+some code for generalized error handling.

207+

208+In an earier version of the `UVerb` implementation, we have used some

209+code from

210+[world-peace](https://hackage.haskell.org/package/world-peace), but

211+that package itself wasn't flexible enough, and we had to use

212+[sop-core](https://hackage.haskell.org/package/sop-core) to implement

213+the `HasServer` instance.

214+

215+Here is a blog post we found on the subject:

216+https://lukwagoallan.com/posts/unifying-servant-server-error-responses

217+

218+(If you have anything else, please add it here or let us know.)

219+

220+```haskell

221+main :: IO ()

222+main = return ()

223+```

doc/cookbook/uverb/uverb.cabalnew file+35

@@ -0,0 +1,35 @@

1+cabal-version: 2.2

2+name: cookbook-uverb

3+version: 0.0.1

4+synopsis: How to use the 'UVerb' type.

5+description: Listing alternative responses and exceptions in your API types.

6+homepage: http://docs.servant.dev/

7+license: BSD-3-Clause

8+license-file: ../../../servant/LICENSE

9+author: Servant Contributors

10+maintainer: haskell-servant-maintainers@googlegroups.com

11+category: Servant

12+build-type: Simple

13+tested-with: GHC==8.6.5, GHC==8.8.4, GHC==8.10.7

14+

15+executable cookbook-uverb

16+ main-is: UVerb.lhs

17+ build-depends: base == 4.*

18+ , aeson >= 1.2

19+ , aeson-pretty >= 0.8.8

20+ , async

21+ , http-client

22+ , mtl

23+ , servant

24+ , servant-client

25+ , servant-server

26+ , servant-swagger

27+ , string-conversions

28+ , swagger2

29+ , wai

30+ , warp

31+ if impl(ghc >= 9)

32+ buildable: False

33+ default-language: Haskell2010

34+ ghc-options: -Wall -pgmL markdown-unlit

35+ build-tool-depends: markdown-unlit:markdown-unlit

doc/links.rst+1−1

@@ -12,7 +12,7 @@ Helpful Links

12 `https://github.com/haskell-servant/servant/issues <https://github.com/haskell-servant/servant/issues>`_

13

14- the irc channel:

15− ``#servant`` on freenode

15+ `#haskell-servant on libera.chat <https://web.libera.chat/#haskell-servant>`_

16

17- the mailing list:

18 `groups.google.com/forum/#!forum/haskell-servant <https://groups.google.com/forum/#!forum/haskell-servant>`_

doc/tutorial/ApiType.lhs+30−4

@@ -177,13 +177,12 @@ type UserAPI5 = "user" :> Capture "userid" Integer :> Get '[JSON] User

177 -- except that we explicitly say that "userid"

178 -- must be an integer

179

180− :<|> "user" :> Capture "userid" Integer :> DeleteNoContent '[JSON] NoContent

180+ :<|> "user" :> Capture "userid" Integer :> DeleteNoContent

181 -- equivalent to 'DELETE /user/:userid'

182```

183

184−In the second case, `DeleteNoContent` specifies a 204 response code,

184+In the second case, `DeleteNoContent` specifies a 204 response code

185−`JSON` specifies the content types on which the handler will match,

186−and `NoContent` says that the response will always be empty.

185+and that the response will always be empty.

187

186

188### `QueryParam`, `QueryParams`, `QueryFlag`

187### `QueryParam`, `QueryParams`, `QueryFlag`

189

188

@@ -390,3 +389,30 @@ One example for this is if you want to serve a directory of static files along

390with the rest of your API. But you can plug in everything that is an

389with the rest of your API. But you can plug in everything that is an

391`Application`, e.g. a whole web application written in any of the web

390`Application`, e.g. a whole web application written in any of the web

392frameworks that support `wai`.

391frameworks that support `wai`.

392+

393+Be mindful! The `servant-server`'s router works by pattern-matching the

394+different routes that are composed using `:<|>`. `Raw`, as an escape hatch,

395+matches any route that hasn't been matched by previous patterns. Therefore,

396+any subsequent route will be silently ignored.

397+

398+``` haskell

399+type UserAPI14 = Raw

400+ :<|> "users" :> Get '[JSON] [User]

401+ -- In this situation, the /users endpoint

402+ -- will not be reachable because the Raw

403+ -- endpoint matches requests before

404+```

405+A simple way to avoid this pitfall is to either use `Raw` as the last

406+definition, or to always have it under a static path.

407+

408+``` haskell

409+type UserAPI15 = "files" :> Raw

410+ -- The raw endpoint is under the /files

411+ -- static path, so it won't match /users.

412+ :<|> "users" :> Get '[JSON] [User]

413+

414+type UserAPI16 = "users" :> Get '[JSON] [User]

415+ :<|> Raw

416+ -- The Raw endpoint is matched last, so

417+ -- it won't overlap another endpoint.

418+```

doc/tutorial/Authentication.lhs+10−11

@@ -47,7 +47,6 @@ module Authentication where

47import Data.Aeson (ToJSON)

48import Data.ByteString (ByteString)

49import Data.Map (Map, fromList)

50−import Data.Monoid ((<>))

51import qualified Data.Map as Map

50import qualified Data.Map as Map

52import Data.Proxy (Proxy (Proxy))

51import Data.Proxy (Proxy (Proxy))

53import Data.Text (Text)

52import Data.Text (Text)

@@ -108,7 +107,7 @@ API with "private." Additionally, the private parts of our API use the

108realm for this authentication is `"foo-realm"`).

107realm for this authentication is `"foo-realm"`).

109

108

110Unfortunately we're not done. When someone makes a request to our `"private"`

109Unfortunately we're not done. When someone makes a request to our `"private"`

111−API, we're going to need to provide to servant the logic for validifying

110+API, we're going to need to provide to servant the logic for validating

112usernames and passwords. This adds a certain conceptual wrinkle in servant's

111usernames and passwords. This adds a certain conceptual wrinkle in servant's

113design that we'll briefly discuss. If you want the **TL;DR**: we supply a lookup

112design that we'll briefly discuss. If you want the **TL;DR**: we supply a lookup

114function to servant's new `Context` primitive.

113function to servant's new `Context` primitive.

@@ -133,7 +132,7 @@ combinator. Using `Context`, we can supply a function of type

133handler. This will allow the handler to check authentication and return a `User`

132handler. This will allow the handler to check authentication and return a `User`

134to downstream handlers if successful.

133to downstream handlers if successful.

135

134

136−In practice we wrap `BasicAuthData -> Handler` into a slightly

135+In practice we wrap `BasicAuthData -> Handler User` into a slightly

137different function to better capture the semantics of basic authentication:

136different function to better capture the semantics of basic authentication:

138

137

139``` haskell ignore

138``` haskell ignore

@@ -260,7 +259,7 @@ this.

260

259

261Let's implement a trivial authentication scheme. We will protect our API by

260Let's implement a trivial authentication scheme. We will protect our API by

262looking for a cookie named `"servant-auth-cookie"`. This cookie's value will

261looking for a cookie named `"servant-auth-cookie"`. This cookie's value will

263−contain a key from which we can lookup a `Account`.

262+contain a key from which we can lookup an `Account`.

264

263

265```haskell

264```haskell

266-- | An account type that we "fetch from the database" after

265-- | An account type that we "fetch from the database" after

@@ -274,7 +273,7 @@ database = fromList [ ("key1", Account "Anne Briggs")

274 , ("key3", Account "Ghédalia Tazartès")

273 , ("key3", Account "Ghédalia Tazartès")

275 ]

274 ]

276

275

277−-- | A method that, when given a password, will return a Account.

276+-- | A method that, when given a password, will return an Account.

278-- This is our bespoke (and bad) authentication logic.

277-- This is our bespoke (and bad) authentication logic.

279lookupAccount :: ByteString -> Handler Account

278lookupAccount :: ByteString -> Handler Account

280lookupAccount key = case Map.lookup key database of

279lookupAccount key = case Map.lookup key database of

@@ -318,7 +317,7 @@ genAuthAPI = Proxy

318

317

319Now we need to bring everything together for the server. We have the

318Now we need to bring everything together for the server. We have the

320`AuthHandler Request Account` value and an `AuthProtected` endpoint. To bind these

319`AuthHandler Request Account` value and an `AuthProtected` endpoint. To bind these

321−together, we need to provide a [Type Family](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/type-families.html)

320+together, we need to provide a [Type Family](https://downloads.haskell.org/~ghc/8.8.1/docs/html/users_guide/glasgow_exts.html#type-families)

322instance that tells the `HasServer` instance that our `Context` will supply a

321instance that tells the `HasServer` instance that our `Context` will supply a

323`Account` (via `AuthHandler Request Account`) and that downstream combinators will

322`Account` (via `AuthHandler Request Account`) and that downstream combinators will

324have access to this `Account` value (or an error will be thrown if authentication

323have access to this `Account` value (or an error will be thrown if authentication

@@ -346,7 +345,7 @@ genAuthServerContext = authHandler :. EmptyContext

346

345

347-- | Our API, where we provide all the author-supplied handlers for each end

346-- | Our API, where we provide all the author-supplied handlers for each end

348-- point. Note that 'privateDataFunc' is a function that takes 'Account' as an

347-- point. Note that 'privateDataFunc' is a function that takes 'Account' as an

349−-- argument. We dont' worry about the authentication instrumentation here,

348+-- argument. We don't worry about the authentication instrumentation here,

350-- that is taken care of by supplying context

349-- that is taken care of by supplying context

351genAuthServer :: Server AuthGenAPI

350genAuthServer :: Server AuthGenAPI

352genAuthServer =

351genAuthServer =

@@ -368,10 +367,10 @@ genAuthMain = run 8080 (serveWithContext genAuthAPI genAuthServerContext genAuth

368$ curl -XGET localhost:8080/private

367$ curl -XGET localhost:8080/private

369Missing auth header

368Missing auth header

370

369

371−$ curl -XGET localhost:8080/private -H "servant-auth-cookie: key3"

370+$ curl -XGET localhost:8080/private -H "Cookie: servant-auth-cookie=key3"

372[{"ssshhh":"this is a secret: Ghédalia Tazartès"}]

371[{"ssshhh":"this is a secret: Ghédalia Tazartès"}]

373

372

374−$ curl -XGET localhost:8080/private -H "servant-auth-cookie: bad-key"

373+$ curl -XGET localhost:8080/private -H "Cookie: servant-auth-cookie=bad-key"

375Invalid Cookie

374Invalid Cookie

376

375

377$ curl -XGET localhost:8080/public

376$ curl -XGET localhost:8080/public

@@ -385,11 +384,11 @@ Creating a generalized, ad-hoc authentication scheme was fairly straight

385forward:

384forward:

386

385

3871. use the `AuthProtect` combinator to protect your API.

3861. use the `AuthProtect` combinator to protect your API.

388−2. choose a application-specific data type used by your server when

387+2. choose an application-specific data type used by your server when

389authentication is successful (in our case this was `Account`).

388authentication is successful (in our case this was `Account`).

3903. Create a value of `AuthHandler Request Account` which encapsulates the

3893. Create a value of `AuthHandler Request Account` which encapsulates the

391authentication logic (`Request -> Handler Account`). This function

390authentication logic (`Request -> Handler Account`). This function

392−will be executed everytime a request matches a protected route.

391+will be executed every time a request matches a protected route.

3934. Provide an instance of the `AuthServerData` type family, specifying your

3924. Provide an instance of the `AuthServerData` type family, specifying your

394application-specific data type returned when authentication is successful (in

393application-specific data type returned when authentication is successful (in

395our case this was `Account`).

394our case this was `Account`).

doc/tutorial/Client.lhs+4−4

@@ -1,9 +1,9 @@

1# Querying an API

2

3−While defining handlers that [serve an API](Server.lhs) has a lot to it, querying an API is simpler: we do not care about what happens inside the webserver, we just need to know how to talk to it and get a response back. That said, we usually have to write the querying functions by hand because the structure of the API isn't a first class citizen and can't be inspected to generate the client-side functions.

3+While defining handlers that [serve an API](Server.html) has a lot to it, querying an API is simpler: we do not care about what happens inside the webserver, we just need to know how to talk to it and get a response back. That said, we usually have to write the querying functions by hand because the structure of the API isn't a first class citizen and can't be inspected to generate the client-side functions.

4

5**servant** however has a way to inspect APIs, because APIs are just Haskell types and (GHC) Haskell lets us do quite a few things with types. In the same way that we look at an API type to deduce the types the handlers should have, we can inspect the structure of the API to *derive* Haskell functions that take one argument for each occurrence of `Capture`, `ReqBody`, `QueryParam`

6−and friends (see [the tutorial introduction](ApiType.lhs) for an overview). By *derive*, we mean that there's no code generation involved - the functions are defined just by the structure of the API type.

6+and friends (see [the tutorial introduction](ApiType.html) for an overview). By *derive*, we mean that there's no code generation involved - the functions are defined just by the structure of the API type.

7

8The source for this tutorial section is a literate Haskell file, so first we need to have some language extensions and imports:

9

@@ -161,7 +161,7 @@ The types of the arguments for the functions are the same as for (server-side) r

161## Changing the monad the client functions live in

162

163Just like `hoistServer` allows us to change the monad in which request handlers

164−of a web application live in, we also have `hoistClient` for changing the monad

164+of a web application live, we also have `hoistClient` for changing the monad

165in which _client functions_ live. Consider the following trivial API:

166

167``` haskell

@@ -173,7 +173,7 @@ hoistClientAPI = Proxy

173

174We already know how to derive client functions for this API, and as we have

175seen above they all return results in the `ClientM` monad when using `servant-client`.

176−However, `ClientM` rarely (or never) is the actual monad we need to use the client

176+However, `ClientM` is rarely (or never) the actual monad we need to use the client

177functions in. Sometimes we need to run them in IO, sometimes in a custom monad

178stack. `hoistClient` is a very simple solution to the problem of "changing" the monad

179the clients run in.

doc/tutorial/Docs.lhs+2−2

@@ -77,7 +77,7 @@ instance ToSample HelloMessage where

77 [ ("When a value is provided for 'name'", HelloMessage "Hello, Alp")

78 , ("When 'name' is not specified", HelloMessage "Hello, anonymous coward")

79 ]

80− -- mutliple examples to display this time

80+ -- multiple examples to display this time

81

82ci :: ClientInfo

83ci = ClientInfo "Alp" "alp@foo.com" 26 ["haskell", "mathematics"]

@@ -108,7 +108,7 @@ apiDocs = docs exampleAPI

108markdown :: API -> String

109```

110

111−That lets us see what our API docs look down in markdown, by looking at `markdown apiDocs`.

111+That lets us see what our API docs look like in markdown, by looking at `markdown apiDocs`.

112

113````````` text

114## GET /hello

doc/tutorial/Javascript.lhs+2−2

@@ -228,13 +228,13 @@ data CommonGeneratorOptions = CommonGeneratorOptions

228 {

229 -- | function generating function names

230 functionNameBuilder :: FunctionName -> Text

231− -- | name used when a user want to send the request body (to let you redefine it)

231+ -- | name used when a user wants to send the request body (to let you redefine it)

232 , requestBody :: Text

233 -- | name of the callback parameter when the request was successful

234 , successCallback :: Text

235 -- | name of the callback parameter when the request reported an error

236 , errorCallback :: Text

237− -- | namespace on which we define the js function (empty mean local var)

237+ -- | namespace on which we define the js function (empty means local var)

238 , moduleName :: Text

239 -- | a prefix that should be prepended to the URL in the generated JS

240 , urlPrefix :: Text

doc/tutorial/Server.lhs+22−22

@@ -183,7 +183,7 @@ users2 = [isaac, albert]

183

184Now, just like we separate the various endpoints in `UserAPI` with `:<|>`, we

185are going to separate the handlers with `:<|>` too! They must be provided in

186−the same order as in in the API type.

186+the same order as in the API type.

187

188``` haskell

189server2 :: Server UserAPI2

@@ -313,8 +313,8 @@ For reference, here's a list of some combinators from **servant**:

313## The `FromHttpApiData`/`ToHttpApiData` classes

314

315Wait... How does **servant** know how to decode the `Int`s from the URL? Or how

316−to decode a `ClientInfo` value from the request body? This is what this and the

316+to decode a `ClientInfo` value from the request body? The following three sections will

317−following two sections address.

317+help us answer these questions.

318

319`Capture`s and `QueryParam`s are represented by some textual value in URLs.

320`Header`s are similarly represented by a pair of a header name and a

@@ -620,7 +620,7 @@ In short, this means that a handler of type `Handler a` is simply

620equivalent to a computation of type `IO (Either ServerError a)`, that is, an IO

621action that either returns an error or a result.

622

623−The module [`Control.Monad.Except`](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Except.html#t:ExceptT)

623+The module [`Control.Monad.Except`](https://hackage.haskell.org/package/mtl/docs/Control-Monad-Except.html#t:ExceptT)

624from which `ExceptT` comes is worth looking at.

625Perhaps most importantly, `ExceptT` and `Handler` are instances of `MonadError`, so

626`throwError` can be used to return an error from your handler (whereas `return`

@@ -634,7 +634,7 @@ kind and abort early. The next two sections cover how to do just that.

634

635Other important instances from the list above are `MonadIO m => MonadIO

636(ExceptT e m)`, and therefore also `MonadIO Handler` as there is a `MonadIO IO` instance.

637−[`MonadIO`](http://hackage.haskell.org/package/transformers-0.4.3.0/docs/Control-Monad-IO-Class.html)

637+[`MonadIO`](http://hackage.haskell.org/package/base/docs/Control-Monad-IO-Class.html#t:MonadIO)

638is a class from the **transformers** package defined as:

639

640``` haskell ignore

@@ -716,7 +716,7 @@ $ curl --verbose http://localhost:8081/myfile.txt

716>

717< HTTP/1.1 404 Not Found

718[snip]

719−myfile.txt just isnt there, please leave this server alone.

719+myfile.txt just isn't there, please leave this server alone.

720

721$ echo Hello > myfile.txt

722

@@ -818,7 +818,7 @@ If it doesn't exist, the handler will fail with a `404` status code.

818

819`serveDirectoryWebApp` uses some standard settings that fit the use case of

820serving static files for most web apps. You can find out about the other

821−options in the documentation of the `Servant.Utils.StaticFiles` module.

821+options in the documentation of the `Servant.Server.StaticFiles` module.

822

823## Nested APIs

824

@@ -830,7 +830,7 @@ type UserAPI3 = -- view the user with given userid, in JSON

830 Capture "userid" Int :> Get '[JSON] User

831

832 :<|> -- delete the user with given userid. empty response

833− Capture "userid" Int :> DeleteNoContent '[JSON] NoContent

833+ Capture "userid" Int :> DeleteNoContent

834```

835

836We can instead factor out the `userid`:

@@ -838,7 +838,7 @@ We can instead factor out the `userid`:

838``` haskell

839type UserAPI4 = Capture "userid" Int :>

840 ( Get '[JSON] User

841− :<|> DeleteNoContent '[JSON] NoContent

841+ :<|> DeleteNoContent

842 )

843```

844

@@ -896,13 +896,13 @@ type API1 = "users" :>

896-- we factor out the Request Body

897type API2 = ReqBody '[JSON] User :>

898 ( Get '[JSON] User -- just display the same user back, don't register it

899− :<|> PostNoContent '[JSON] NoContent -- register the user. empty response

899+ :<|> PostNoContent -- register the user. empty response

900 )

901

902-- we factor out a Header

903type API3 = Header "Authorization" Token :>

904 ( Get '[JSON] SecretData -- get some secret data, if authorized

905− :<|> ReqBody '[JSON] SecretData :> PostNoContent '[JSON] NoContent -- add some secret data, if authorized

905+ :<|> ReqBody '[JSON] SecretData :> PostNoContent -- add some secret data, if authorized

906 )

907

908newtype Token = Token ByteString

@@ -915,11 +915,11 @@ API type only at the end.

915``` haskell

916type UsersAPI =

917 Get '[JSON] [User] -- list users

918− :<|> ReqBody '[JSON] User :> PostNoContent '[JSON] NoContent -- add a user

918+ :<|> ReqBody '[JSON] User :> PostNoContent -- add a user

919 :<|> Capture "userid" Int :>

920 ( Get '[JSON] User -- view a user

921− :<|> ReqBody '[JSON] User :> PutNoContent '[JSON] NoContent -- update a user

921+ :<|> ReqBody '[JSON] User :> PutNoContent -- update a user

922− :<|> DeleteNoContent '[JSON] NoContent -- delete a user

922+ :<|> DeleteNoContent -- delete a user

923 )

924

925usersServer :: Server UsersAPI

@@ -948,11 +948,11 @@ usersServer = getUsers :<|> newUser :<|> userOperations

948``` haskell

949type ProductsAPI =

950 Get '[JSON] [Product] -- list products

951− :<|> ReqBody '[JSON] Product :> PostNoContent '[JSON] NoContent -- add a product

951+ :<|> ReqBody '[JSON] Product :> PostNoContent -- add a product

952 :<|> Capture "productid" Int :>

953 ( Get '[JSON] Product -- view a product

954− :<|> ReqBody '[JSON] Product :> PutNoContent '[JSON] NoContent -- update a product

954+ :<|> ReqBody '[JSON] Product :> PutNoContent -- update a product

955− :<|> DeleteNoContent '[JSON] NoContent -- delete a product

955+ :<|> DeleteNoContent -- delete a product

956 )

957

958data Product = Product { productId :: Int }

@@ -996,11 +996,11 @@ abstract that away:

996-- indexed by values of type 'i'

997type APIFor a i =

998 Get '[JSON] [a] -- list 'a's

999− :<|> ReqBody '[JSON] a :> PostNoContent '[JSON] NoContent -- add an 'a'

999+ :<|> ReqBody '[JSON] a :> PostNoContent -- add an 'a'

1000 :<|> Capture "id" i :>

1001 ( Get '[JSON] a -- view an 'a' given its "identifier" of type 'i'

1002− :<|> ReqBody '[JSON] a :> PutNoContent '[JSON] NoContent -- update an 'a'

1002+ :<|> ReqBody '[JSON] a :> PutNoContent -- update an 'a'

1003− :<|> DeleteNoContent '[JSON] NoContent -- delete an 'a'

1003+ :<|> DeleteNoContent -- delete an 'a'

1004 )

1005

1006-- Build the appropriate 'Server'

@@ -1135,7 +1135,7 @@ true

1135### An arrow is a reader too.

1136

1137In previous versions of `servant` we had an `enter` to do what `hoistServer`

1138−does now. `enter` had a ambitious design goals, but was problematic in practice.

1138+does now. `enter` had an ambitious design goals, but was problematic in practice.

1139

1140One problematic situation was when the source monad was `(->) r`, yet it's

1141handy in practice, because `(->) r` is isomorphic to `Reader r`.

@@ -1166,7 +1166,7 @@ back a *stream* of results, served one at a time. Stream endpoints only provide

1166a single content type, and also specify what framing strategy is used to

1167delineate the results. To serve these results, we need to give back a stream

1168producer. Adapters can be written to *Pipes*, *Conduit* and the like, or

1169−written directly as `SourceIO`s. SourceIO builts upon servant's own `SourceT`

1169+written directly as `SourceIO`s. SourceIO builds upon servant's own `SourceT`

1170stream type (it's simpler than *Pipes* or *Conduit*).

1171The API of a streaming endpoint needs to explicitly specify which sort of

1172generator it produces. Note that the generator itself is returned by a

doc/tutorial/index.rst+1−37

@@ -6,46 +6,10 @@ This is an introductory tutorial to **servant**. Whilst browsing is fine, it mak

6Any comments, issues or feedback about the tutorial can be submitted

7to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.

8

9−cabal-install

10−--------

11−

12−The whole tutorial is a `cabal <https://cabal.readthedocs.io/en/latest/>`_

13−project and can be built locally as follows:

14−

15−.. code-block:: bash

16−

17− $ git clone https://github.com/haskell-servant/servant.git

18− $ cd servant

19− # build

20− $ cabal new-build tutorial

21− # load in ghci to play with it

22− $ cabal new-repl tutorial

23−

24−stack

25−--------

26−

27−The servant `stack <https://docs.haskellstack.org/en/stable/README/>`_ template includes the working tutorial. To initialize this template, run:

28−

29−.. code-block:: bash

30−

31− $ stack new myproj servant

32− $ cd myproj

33− # build

34− $ stack build

35− # start server

36− $ stack exec myproj-exe

37−

38−The code can be found in the `*.lhs` files under `doc/tutorial/` in the

39−repository. Feel free to edit it while you're reading this documentation and

40−see the effect of your changes.

41−

42−`Nix <https://nixos.org/nix/>`_ users should feel free to take a look at

43−the `nix/shell.nix` file in the repository and use it to provision a suitable

44−environment to build and run the examples.

45−

46.. toctree::

9.. toctree::

47 :maxdepth: 1

10 :maxdepth: 1

48

11

12+ install.rst

49 ApiType.lhs

13 ApiType.lhs

50 Server.lhs

14 Server.lhs

51 Client.lhs

15 Client.lhs

doc/tutorial/install.rstnew file+68

@@ -0,0 +1,68 @@

1+Install

2+========

3+

4+cabal-install

5+--------

6+

7+The whole tutorial is a `cabal <https://cabal.readthedocs.io/en/latest/>`_

8+project and can be built locally as follows:

9+

10+.. code-block:: bash

11+

12+ $ git clone https://github.com/haskell-servant/servant.git

13+ $ cd servant

14+ # build

15+ $ cabal new-build tutorial

16+ # load in ghci to play with it

17+ $ cabal new-repl tutorial

18+

19+stack

20+--------

21+

22+The servant `stack <https://docs.haskellstack.org/en/stable/README/>`_ template includes the working tutorial. To initialize this template, run:

23+

24+.. code-block:: bash

25+

26+ $ stack new myproj servant

27+ $ cd myproj

28+ # build

29+ $ stack build

30+ # start server

31+ $ stack exec myproj-exe

32+

33+The code can be found in the `*.lhs` files under `doc/tutorial/` in the

34+repository. Feel free to edit it while you're reading this documentation and

35+see the effect of your changes.

36+

37+nix

38+--------

39+

40+`Nix <https://nixos.org/nix/>`_ users should feel free to take a look at

41+the `nix/shell.nix` file in the repository and use it to provision a suitable

42+environment to build and run the examples.

43+

44+Note for Ubuntu users

45+--------

46+

47+Ubuntu's packages for `ghc`, `cabal`, and `stack` are years out of date.

48+If the instructions above fail for you,

49+try replacing the Ubuntu packages with up-to-date versions.

50+First remove the installed versions:

51+

52+.. code-block:: bash

53+

54+ # remove the obsolete versions

55+ $ sudo apt remove ghc haskell-stack cabal-install

56+

57+Then install fresh versions of the Haskell toolchain

58+using the `ghcup <https://www.haskell.org/ghcup/install/>`_ installer.

59+

60+As of February 2022, one easy way to do this is by running a bootstrap script:

61+

62+.. code-block:: bash

63+

64+ $ curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

65+

66+The script is interactive and will prompt you for details about what

67+you want installed and where. To install manually,

68+see `the detailed instructions <https://www.haskell.org/ghcup/install/#manual-install>`_.

doc/tutorial/test/Spec.hs+11−1

@@ -1 +1,11 @@

1−{-# OPTIONS_GHC -F -pgmF hspec-discover #-}

1+module Main where

2+

3+import qualified JavascriptSpec

4+

5+import Test.Hspec (Spec, hspec, describe)

6+

7+main :: IO ()

8+main = hspec spec

9+

10+spec :: Spec

11+spec = describe "Javascript" JavascriptSpec.spec

doc/tutorial/tutorial.cabal+8−12

@@ -1,3 +1,4 @@

1+cabal-version: 2.2

1name: tutorial

2name: tutorial

2version: 0.10

3version: 0.10

3synopsis: The servant tutorial

4synopsis: The servant tutorial

@@ -6,17 +7,14 @@ description:

6 <http://docs.servant.dev/>

7 <http://docs.servant.dev/>

7homepage: http://docs.servant.dev/

8homepage: http://docs.servant.dev/

8category: Servant, Documentation

9category: Servant, Documentation

9−license: BSD3

10+license: BSD-3-Clause

10license-file: LICENSE

11license-file: LICENSE

11author: Servant Contributors

12author: Servant Contributors

12maintainer: haskell-servant-maintainers@googlegroups.com

13maintainer: haskell-servant-maintainers@googlegroups.com

13build-type: Simple

14build-type: Simple

14−cabal-version: >=1.10

15tested-with:

16− GHC==8.0.2

17− GHC==8.2.2

18− GHC==8.4.4

19 GHC==8.6.5

16 GHC==8.6.5

17+ GHC==8.8.3, GHC ==8.10.7

20extra-source-files:

18extra-source-files:

21 static/index.html

19 static/index.html

22 static/ui.js

20 static/ui.js

@@ -34,7 +32,7 @@ library

34 -- Packages `servant` depends on.

32 -- Packages `servant` depends on.

35 -- We don't need to specify bounds here as this package is never released.

33 -- We don't need to specify bounds here as this package is never released.

36 build-depends:

34 build-depends:

37− base >= 4.7 && <4.13

35+ base >= 4.7 && <5

38 , aeson

36 , aeson

39 , attoparsec

37 , attoparsec

40 , base-compat

38 , base-compat

@@ -65,11 +63,11 @@ library

65 blaze-html >= 0.9.0.1 && < 0.10

63 blaze-html >= 0.9.0.1 && < 0.10

66 , blaze-markup >= 0.8.0.0 && < 0.9

64 , blaze-markup >= 0.8.0.0 && < 0.9

67 , cookie >= 0.4.3 && < 0.5

65 , cookie >= 0.4.3 && < 0.5

68− , js-jquery >= 3.2.1 && < 3.3

66+ , js-jquery >= 3.3.1 && < 3.4

69− , lucid >= 2.9.11 && < 2.10

67+ , lucid >= 2.9.11 && < 2.12

70− , random >= 1.1 && < 1.2

68+ , random >= 1.1 && < 1.3

71 , servant-js >= 0.9 && < 0.10

69 , servant-js >= 0.9 && < 0.10

72− , time >= 1.6.0.1 && < 1.9

70+ , time >= 1.6.0.1 && < 1.13

73

71

74 -- For legacy tools, we need to specify build-depends too

72 -- For legacy tools, we need to specify build-depends too

75 build-depends: markdown-unlit >= 0.5.0 && <0.6

73 build-depends: markdown-unlit >= 0.5.0 && <0.6

@@ -82,8 +80,6 @@ test-suite spec

82 hs-source-dirs: test

80 hs-source-dirs: test

83 main-is: Spec.hs

81 main-is: Spec.hs

84 other-modules: JavascriptSpec

82 other-modules: JavascriptSpec

85− build-tool-depends:

86− hspec-discover:hspec-discover

87 build-depends: base

83 build-depends: base

88 , tutorial

84 , tutorial

89 , hspec

85 , hspec

ghcjs.nixnew file+22

@@ -0,0 +1,22 @@

1+let reflex-platform = import (builtins.fetchTarball

2+ { name = "reflex-platform";

3+ url = "https://github.com/reflex-frp/reflex-platform/archive/1aba6f367982bd6dd78ec2fda75ab246a62d32c5.tar.gz";

4+ }) {};

5+ pkgs = import ./nix/nixpkgs.nix; in

6+

7+pkgs.stdenv.mkDerivation {

8+ name = "ghcjs-shell";

9+ buildInputs =

10+ [ (reflex-platform.ghcjs.ghcWithPackages (p: with p; [

11+ attoparsec

12+ hashable

13+ ]))

14+ pkgs.cabal-install

15+ pkgs.gmp

16+ pkgs.haskellPackages.cabal-plan

17+ pkgs.haskellPackages.hspec-discover

18+ pkgs.nodejs

19+ pkgs.perl

20+ pkgs.zlib

21+ ];

22+}

nix/README.md+18

@@ -21,3 +21,21 @@ a particular ghc version, e.g:

21``` sh

22$ nix-shell nix/shell.nix --argstr compiler ghcHEAD

23```

24+

25+**Possible GHC versions**

26+- `ghc865Binary`

27+- `ghc884`

28+- `ghc8104` - default

29+- `ghc901`

30+

31+### Cabal users

32+

33+GHC version can be chosen via the nix-shell parameter

34+

35+`cabal build all`

36+

37+### Stack version

38+

39+Since the ghc version is set by the LTS version, it is preferable to use the `ghc8104` version parameter for the nix-shell.

40+

41+`stack --no-nix --system-ghc <command>`

nix/nixpkgs.jsonnew file+4

@@ -0,0 +1,4 @@

1+{

2+ "rev" : "05f0934825c2a0750d4888c4735f9420c906b388",

3+ "sha256" : "1g8c2w0661qn89ajp44znmwfmghbbiygvdzq0rzlvlpdiz28v6gy"

4+}

nix/nixpkgs.nixnew file+4

@@ -0,0 +1,4 @@

1+import (builtins.fetchTarball {

2+ url = "https://github.com/NixOS/nixpkgs/archive/refs/tags/21.05.tar.gz";

3+ sha256 = "sha256:1ckzhh24mgz6jd1xhfgx0i9mijk6xjqxwsshnvq789xsavrmsc36";

4+}) {}

nix/shell.nix+17−18

@@ -1,21 +1,20 @@

1−{ pkgs ? import <nixpkgs> {}

2−, compiler ? "ghc822"

1+{ compiler ? "ghc8104"

3, tutorial ? false

2, tutorial ? false

3+, pkgs ? import ./nixpkgs.nix

4}:

5+

6+ with pkgs;

5

7

6−with pkgs;

7−

8−let

8+ let

9− ghc = haskell.packages.${compiler}.ghcWithPackages (_: []);

9+ ghc = haskell.packages.${compiler}.ghcWithPackages (_: []);

10− docstuffs = python3.withPackages (ps: with ps; [ recommonmark sphinx sphinx_rtd_theme ]);

10+ docstuffs = python3.withPackages (ps: with ps; [ recommonmark sphinx sphinx_rtd_theme ]);

11−in

11+ in

12−

13−stdenv.mkDerivation {

12+ stdenv.mkDerivation {

14− name = "servant-dev";

13+ name = "servant-dev";

15− buildInputs = [ ghc zlib python3 wget ]

14+ buildInputs = [ ghc zlib python3 wget cabal-install postgresql openssl stack haskellPackages.hspec-discover ]

16− ++ (if tutorial then [docstuffs postgresql] else []);

15+ ++ (if tutorial then [docstuffs postgresql] else []);

17− shellHook = ''

16+ shellHook = ''

18− eval $(grep export ${ghc}/bin/ghc)

17+ eval $(grep export ${ghc}/bin/ghc)

19− export LD_LIBRARY_PATH="${zlib}/lib";

18+ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"${zlib}/lib";

20− '';

19+ '';

21−}

20+ }

servant-auth/README.mdnew file+1

@@ -0,0 +1 @@

1+servant-auth-server/README.lhs

servant-auth/servant-auth-client/.ghcinew file+1

@@ -0,0 +1 @@

1+:set -isrc -itest -idoctest/ghci-wrapper/src

servant-auth/servant-auth-client/CHANGELOG.mdnew file+26

@@ -0,0 +1,26 @@

1+# Changelog

2+

3+All notable changes to this project will be documented in this file.

4+

5+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)

6+and this project adheres to [PVP Versioning](https://pvp.haskell.org/).

7+

8+## [Unreleased]

9+

10+## [0.4.1.0] - 2020-10-06

11+

12+- Support generic Bearer token auth

13+

14+## [0.4.0.0] - 2019-03-08

15+

16+## Changed

17+

18+- #145 Support servant-0.16 in tests @domenkozar

19+- #145 Drop GHC 7.10 support @domenkozar

20+

21+## [0.3.3.0] - 2018-06-18

22+

23+### Added

24+- Support for GHC 8.4 by @phadej

25+- Support for servant-0.14 by @phadej

26+- Changelog by @domenkozar

servant-auth/servant-auth-client/LICENSEnew file+31

@@ -0,0 +1,31 @@

2+

4+

5+Redistribution and use in source and binary forms, with or without

6+modification, are permitted provided that the following conditions are met:

7+

8+ * Redistributions of source code must retain the above copyright

9+ notice, this list of conditions and the following disclaimer.

10+

11+ * Redistributions in binary form must reproduce the above

12+ copyright notice, this list of conditions and the following

13+ disclaimer in the documentation and/or other materials provided

14+ with the distribution.

15+

16+ * Neither the name of Julian K. Arni nor the names of other

17+ contributors may be used to endorse or promote products derived

18+ from this software without specific prior written permission.

19+

20+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

21+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

22+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

23+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

24+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

25+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

26+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

27+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

28+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

29+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

30+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

31+

servant-auth/servant-auth-client/Setup.hsnew file+2

@@ -0,0 +1,2 @@

1+import Distribution.Simple

2+main = defaultMain

servant-auth/servant-auth-client/servant-auth-client.cabalnew file+80

@@ -0,0 +1,80 @@

1+cabal-version: 2.2

2+name: servant-auth-client

3+version: 0.4.1.0

4+synopsis: servant-client/servant-auth compatibility

5+description: This package provides instances that allow generating clients from

6+ <https://hackage.haskell.org/package/servant servant>

7+ APIs that use

8+ <https://hackage.haskell.org/package/servant-auth servant-auth's> @Auth@ combinator.

9+ .

10+ For a quick overview of the usage, see the <https://github.com/haskell-servant/servant/tree/master/servant-auth#readme README>.

11+category: Web, Servant, Authentication

12+homepage: https://github.com/haskell-servant/servant/tree/master/servant-auth#readme

13+bug-reports: https://github.com/haskell-servant/servant/issues

14+author: Julian K. Arni

15+maintainer: jkarni@gmail.com

16+copyright: (c) Julian K. Arni

17+license: BSD-3-Clause

18+license-file: LICENSE

19+tested-with: GHC ==8.6.5 || ==8.8.4 || ==8.10.4 || ==9.0.1

20+build-type: Simple

21+extra-source-files:

22+ CHANGELOG.md

23+

24+source-repository head

25+ type: git

26+ location: https://github.com/haskell-servant/servant

27+

28+library

29+ hs-source-dirs:

30+ src

31+ default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

32+ ghc-options: -Wall

33+ build-depends:

34+ base >= 4.10 && < 4.17

35+ , bytestring >= 0.10.6.0 && < 0.12

36+ , containers >= 0.5.6.2 && < 0.7

37+ , servant-auth == 0.4.*

38+ , servant >= 0.13 && < 0.20

39+ , servant-client-core >= 0.13 && < 0.20

40+

41+ exposed-modules:

42+ Servant.Auth.Client

43+ Servant.Auth.Client.Internal

44+ default-language: Haskell2010

45+

46+test-suite spec

47+ type: exitcode-stdio-1.0

48+ main-is: Spec.hs

49+ hs-source-dirs:

50+ test

51+ default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

52+ ghc-options: -Wall

53+ build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.10

54+

55+ -- dependencies with bounds inherited from the library stanza

56+ build-depends:

57+ base

58+ , servant-client

59+ , servant-auth

60+ , servant

61+ , servant-auth-client

62+

63+ -- test dependencies

64+ build-depends:

65+ hspec >= 2.5.5 && < 2.10

66+ , QuickCheck >= 2.11.3 && < 2.15

67+ , aeson >= 1.3.1.1 && < 3

68+ , bytestring >= 0.10.6.0 && < 0.12

69+ , http-client >= 0.5.13.1 && < 0.8

70+ , http-types >= 0.12.2 && < 0.13

71+ , servant-auth-server >= 0.4.2.0 && < 0.5

72+ , servant-server >= 0.13 && < 0.20

73+ , time >= 1.5.0.1 && < 1.13

74+ , transformers >= 0.4.2.0 && < 0.6

75+ , wai >= 3.2.1.2 && < 3.3

76+ , warp >= 3.2.25 && < 3.4

77+ , jose >= 0.7.0.0 && < 0.10

78+ other-modules:

79+ Servant.Auth.ClientSpec

80+ default-language: Haskell2010

servant-auth/servant-auth-client/src/Servant/Auth/Client.hsnew file+3

@@ -0,0 +1,3 @@

1+module Servant.Auth.Client (Token(..), Bearer) where

2+

3+import Servant.Auth.Client.Internal (Bearer, Token(..))

servant-auth/servant-auth-client/src/Servant/Auth/Client/Internal.hsnew file+64

@@ -0,0 +1,64 @@

1+{-# LANGUAGE CPP #-}

2+{-# LANGUAGE GeneralizedNewtypeDeriving #-}

3+{-# LANGUAGE UndecidableInstances #-}

4+{-# OPTIONS_GHC -fno-warn-orphans #-}

5+#if __GLASGOW_HASKELL__ == 800

6+{-# OPTIONS_GHC -fno-warn-redundant-constraints #-}

7+#endif

8+module Servant.Auth.Client.Internal where

9+

10+import qualified Data.ByteString as BS

11+import Data.Monoid

12+import Data.Proxy (Proxy (..))

13+import Data.String (IsString)

14+import GHC.Exts (Constraint)

15+import GHC.Generics (Generic)

16+import Servant.API ((:>))

17+import Servant.Auth

18+

19+import Servant.Client.Core

20+import Data.Sequence ((<|))

21+

22+-- | A simple bearer token.

23+newtype Token = Token { getToken :: BS.ByteString }

24+ deriving (Eq, Show, Read, Generic, IsString)

25+

26+type family HasBearer xs :: Constraint where

27+ HasBearer (Bearer ': xs) = ()

28+ HasBearer (JWT ': xs) = ()

29+ HasBearer (x ': xs) = HasBearer xs

30+ HasBearer '[] = BearerAuthNotEnabled

31+

32+class BearerAuthNotEnabled

33+

34+-- | @'HasBearer' auths@ is nominally a redundant constraint, but ensures we're not

35+-- trying to send a token to an API that doesn't accept them.

36+instance (HasBearer auths, HasClient m api) => HasClient m (Auth auths a :> api) where

37+ type Client m (Auth auths a :> api) = Token -> Client m api

38+

39+ clientWithRoute m _ req (Token token)

40+ = clientWithRoute m (Proxy :: Proxy api)

41+ $ req { requestHeaders = ("Authorization", headerVal) <| requestHeaders req }

42+ where

43+ headerVal = "Bearer " <> token

44+

45+#if MIN_VERSION_servant_client_core(0,14,0)

46+ hoistClientMonad pm _ nt cl = hoistClientMonad pm (Proxy :: Proxy api) nt . cl

47+#endif

48+

49+

50+-- * Authentication combinators

51+

52+-- | A Bearer token in the Authorization header:

53+--

54+-- @Authorization: Bearer <token>@

55+--

56+-- This can be any token recognized by the server, for example,

57+-- a JSON Web Token (JWT).

58+--

59+-- Note that, since the exact way the token is validated is not specified,

60+-- this combinator can only be used in the client. The server would not know

61+-- how to validate it, while the client does not care.

62+-- If you want to implement Bearer authentication in your server, you have to

63+-- choose a specific combinator, such as 'JWT'.

64+data Bearer

servant-auth/servant-auth-client/test/Servant/Auth/ClientSpec.hsnew file+161

@@ -0,0 +1,161 @@

1+{-# LANGUAGE CPP #-}

2+{-# LANGUAGE DeriveAnyClass #-}

3+module Servant.Auth.ClientSpec (spec) where

4+

5+import Crypto.JOSE (JWK,

6+ KeyMaterialGenParam (OctGenParam),

7+ genJWK)

8+import Data.Aeson (FromJSON (..), ToJSON (..))

9+import qualified Data.ByteString.Lazy as BSL

10+import Data.Time (UTCTime, defaultTimeLocale,

11+ parseTimeOrError)

12+import GHC.Generics (Generic)

13+import Network.HTTP.Client (Manager, defaultManagerSettings,

14+ newManager)

15+import Network.HTTP.Types (status401)

16+import Network.Wai.Handler.Warp (testWithApplication)

17+import Servant

18+import Servant.Client (BaseUrl (..), Scheme (Http),

19+ ClientError (FailureResponse),

20+#if MIN_VERSION_servant_client(0,16,0)

21+ ResponseF(..),

22+#elif MIN_VERSION_servant_client(0,13,0)

23+ GenResponse(..),

24+#elif MIN_VERSION_servant_client(0,12,0)

25+ Response(..),

26+#endif

27+ client)

28+import System.IO.Unsafe (unsafePerformIO)

29+import Test.Hspec

30+import Test.QuickCheck

31+

32+#if MIN_VERSION_servant_client(0,13,0)

33+import Servant.Client (mkClientEnv, runClientM)

34+#elif MIN_VERSION_servant_client(0,9,0)

35+import Servant.Client (ClientEnv (..), runClientM)

36+#else

37+import Control.Monad.Trans.Except (runExceptT)

38+#endif

39+#if !MIN_VERSION_servant_server(0,16,0)

40+#define ClientError ServantError

41+#endif

42+

43+import Servant.Auth.Client

44+import Servant.Auth.Server

45+import Servant.Auth.Server.SetCookieOrphan ()

46+

47+spec :: Spec

48+spec = describe "The JWT combinator" $ do

49+ hasClientSpec

50+

51+

52+------------------------------------------------------------------------------

53+-- * HasClient {{{

54+

55+hasClientSpec :: Spec

56+hasClientSpec = describe "HasClient" $ around (testWithApplication $ return app) $ do

57+

58+ let mkTok :: User -> Maybe UTCTime -> IO Token

59+ mkTok user mexp = do

60+ Right tok <- makeJWT user jwtCfg mexp

61+ return $ Token $ BSL.toStrict tok

62+

63+ it "succeeds when the token does not have expiry" $ \port -> property $ \user -> do

64+ tok <- mkTok user Nothing

65+ v <- getIntClient tok mgr (BaseUrl Http "localhost" port "")

66+ v `shouldBe` Right (length $ name user)

67+

68+ it "succeeds when the token is not expired" $ \port -> property $ \user -> do

69+ tok <- mkTok user (Just future)

70+ v <- getIntClient tok mgr (BaseUrl Http "localhost" port "")

71+ v `shouldBe` Right (length $ name user)

72+

73+ it "fails when token is expired" $ \port -> property $ \user -> do

74+ tok <- mkTok user (Just past)

75+#if MIN_VERSION_servant_client(0,16,0)

76+ Left (FailureResponse _ (Response stat _ _ _))

77+#elif MIN_VERSION_servant_client(0,12,0)

78+ Left (FailureResponse (Response stat _ _ _))

79+#elif MIN_VERSION_servant_client(0,11,0)

80+ Left (FailureResponse _ stat _ _)

81+#else

82+ Left (FailureResponse stat _ _)

83+#endif

84+ <- getIntClient tok mgr (BaseUrl Http "localhost" port "")

85+ stat `shouldBe` status401

86+

87+

88+getIntClient :: Token -> Manager -> BaseUrl -> IO (Either ClientError Int)

89+#if MIN_VERSION_servant(0,13,0)

90+getIntClient tok m burl = runClientM (client api tok) (mkClientEnv m burl)

91+#elif MIN_VERSION_servant(0,9,0)

92+getIntClient tok m burl = runClientM (client api tok) (ClientEnv m burl)

93+#else

94+getIntClient tok m burl = runExceptT $ client api tok m burl

95+#endif

96+-- }}}

97+------------------------------------------------------------------------------

98+-- * API and Server {{{

99+

100+type API = Auth '[JWT] User :> Get '[JSON] Int

101+

102+api :: Proxy API

103+api = Proxy

104+

105+theKey :: JWK

106+theKey = unsafePerformIO . genJWK $ OctGenParam 256

107+{-# NOINLINE theKey #-}

108+

109+mgr :: Manager

110+mgr = unsafePerformIO $ newManager defaultManagerSettings

111+{-# NOINLINE mgr #-}

112+

113+app :: Application

114+app = serveWithContext api ctx server

115+ where

116+ ctx = cookieCfg :. jwtCfg :. EmptyContext

117+

118+jwtCfg :: JWTSettings

119+jwtCfg = defaultJWTSettings theKey

120+

121+cookieCfg :: CookieSettings

122+cookieCfg = defaultCookieSettings

123+

124+

125+server :: Server API

126+server = getInt

127+ where

128+ getInt :: AuthResult User -> Handler Int

129+ getInt (Authenticated u) = return . length $ name u

130+ getInt _ = throwAll err401

131+

132+

133+-- }}}

134+------------------------------------------------------------------------------

135+-- * Utils {{{

136+

137+past :: UTCTime

138+past = parseTimeOrError True defaultTimeLocale "%Y-%m-%d" "1970-01-01"

139+

140+future :: UTCTime

141+future = parseTimeOrError True defaultTimeLocale "%Y-%m-%d" "2070-01-01"

142+

143+

144+-- }}}

145+------------------------------------------------------------------------------

146+-- * Types {{{

147+

148+data User = User

149+ { name :: String

150+ , _id :: String

151+ } deriving (Eq, Show, Read, Generic)

152+

153+instance FromJWT User

154+instance ToJWT User

155+instance FromJSON User

156+instance ToJSON User

157+

158+instance Arbitrary User where

159+ arbitrary = User <$> arbitrary <*> arbitrary

160+

161+-- }}}

servant-auth/servant-auth-client/test/Spec.hsnew file+1

@@ -0,0 +1 @@

1+{-# OPTIONS_GHC -F -pgmF hspec-discover #-}

servant-auth/servant-auth-docs/.ghcinew file+1

@@ -0,0 +1 @@

1+:set -isrc -itest -idoctest/ghci-wrapper/src

servant-auth/servant-auth-docs/CHANGELOG.mdnew file+14

@@ -0,0 +1,14 @@

1+# Changelog

2+

3+All notable changes to this project will be documented in this file.

4+

5+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)

6+and this project adheres to [PVP Versioning](https://pvp.haskell.org/).

7+

8+## [Unreleased]

9+

10+## [0.2.10.0] - 2018-06-18

11+

12+### Added

13+- Support for GHC 8.4 by @phadej

14+- Changelog by @domenkozar

servant-auth/servant-auth-docs/LICENSEnew file+31