dcf307d..master · servant

.github/FUNDING.yml+1−1

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

11# These are supported funding model platforms

22

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

3+github: [arianvp]

44patreon: # Replace with a single Patreon username

55open_collective: # Replace with a single Open Collective username

66ko_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+148

@@ -0,0 +1,148 @@

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+ - "9.4.2"

24+

25+ steps:

26+ - uses: actions/checkout@v2

27+

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

29+ id: setup-haskell-cabal

30+ name: Setup Haskell

31+ with:

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

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

34+

35+ - name: Freeze

36+ run: |

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

38+ cabal freeze

39+

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

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

42+ with:

43+ path: |

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

45+ dist-newstyle

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

47+ restore-keys: |

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

49+

50+ - name: Configure

51+ run: |

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

53+

54+ - name: Build

55+ run: |

56+ cabal build all

57+

58+ - name: Test

59+ run: |

60+ cabal test all

61+

62+ - name: Run doctests

63+ run: |

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

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

66+

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

68+ (cd servant && eval $DOCTEST)

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

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

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

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

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

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

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

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

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

78+

79+ # stack:

80+ # name: stack / ghc ${{ matrix.ghc }}

81+ # runs-on: ubuntu-latest

82+ # strategy:

83+ # matrix:

84+ # stack: ["2.7.5"]

85+ # ghc: ["8.10.7"]

86+

87+ # steps:

88+ # - uses: actions/checkout@v2

89+

90+ # - uses: haskell/actions/setup@v1

91+ # name: Setup Haskell Stack

92+ # with:

93+ # ghc-version: ${{ matrix.ghc }}

94+ # stack-version: ${{ matrix.stack }}

95+

96+ # - uses: actions/cache@v2.1.3

97+ # name: Cache ~/.stack

98+ # with:

99+ # path: ~/.stack

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

101+

102+ # - name: Install dependencies

103+ # run: |

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

105+

106+ # - name: Build

107+ # run: |

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

109+

110+ # - name: Test

111+ # run: |

112+ # stack test --system-ghc

113+

114+ ghcjs:

115+ name: ubuntu-latest / ghcjs 8.6

116+ runs-on: "ubuntu-latest"

117+

118+ steps:

119+ - uses: actions/checkout@v2

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

121+ with:

122+ extra_nix_config: |

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

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

125+ - name: Setup

126+ run: |

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

128+ cp cabal.ghcjs.project cabal.project

129+ cat cabal.project

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

131+

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

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

134+ with:

135+ path: |

136+ ~/.cabal/store

137+ dist-newstyle

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

139+ restore-keys: |

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

141+

142+ - name: Build

143+ run: |

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

145+

146+ - name: Tests

147+ run: |

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

.gitignore+6

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

11**/*/dist

2+*~

23dist-*

34.ghc.environment.*

45/bin

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

2930doc/venv

3031doc/tutorial/static/api.js

3132doc/tutorial/static/jq.js

33+shell.nix

34+.hspec-failures

35+

36+# nix

37+result*

3238

3339# local versions of things

3440servant-multipart

.travis.ymldeleted−321

@@ -1,321 +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.20190916

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−addons:

18− google: stable

19−cache:

20− directories:

21− - $HOME/.cabal/packages

22− - $HOME/.cabal/store

23−before_cache:

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

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

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

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

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

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

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

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

32−matrix:

33− include:

34− - compiler: ghcjs-8.4

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

36− - compiler: ghc-8.8.1

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

38− - compiler: ghc-8.6.5

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

40− - compiler: ghc-8.4.4

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

42− - compiler: ghc-8.2.2

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

44− - compiler: ghc-8.0.2

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

46−before_install:

47− - |

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

49− GHCJS=true;

50− else

51− GHCJS=false;

52− fi

53− - |

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

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

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

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

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

59− sudo apt-get install $CC;

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

61− fi

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

63− - WITHCOMPILER="-w $HC"

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

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

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

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

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

69− - HCPKG="$HC-pkg"

70− - unset CC

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

72− - CABALHOME=$HOME/.cabal

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

74− - TOP=$(pwd)

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

76− - echo $HCNUMVER

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

78− - set -o pipefail

79− - |

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

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

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

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

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

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

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

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

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

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

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

91− - cat .colorful.awk

92− - |

93− color_cabal_output () {

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

95− }

96− - echo text | color_cabal_output

97−install:

98− - ${CABAL} --version

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

100− - node --version

101− - echo $GHCJS

102− - TEST=--enable-tests

103− - BENCH=--enable-benchmarks

104− - HEADHACKAGE=false

105− - rm -f $CABALHOME/config

106− - |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

122− - GHCJOBS=-j2

123− - |

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

125− echo " ghc-options: $GHCJOBS +RTS -M6G -RTS" >> $CABALHOME/config

126− - cat $CABALHOME/config

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

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

129− - if $GHCJS ; then (cd /tmp && ${CABAL} v2-install -w ghc-8.4.4 cabal-plan --constraint='cabal-plan ^>=0.6.0.0' --constraint='cabal-plan +exe' | color_cabal_output) ; fi

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

131− # Generate cabal.project

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

133− - touch cabal.project

134− - |

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

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

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

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

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

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

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

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

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

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

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

146− if $GHCJS || ! $GHCJS && [ $HCNUMVER -lt 80800 ] ; then echo "packages: servant-jsaddle" >> cabal.project ; fi

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

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

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

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

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

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

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

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

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

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

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

158− - |

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

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

161− echo "constraints: sqlite-simple < 0" >> cabal.project

162− echo "allow-newer: aeson-pretty-0.8.7:base-compat" >> cabal.project

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

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

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

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

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

168− echo "allow-newer: io-streams-1.5.1.0:primitive" >> cabal.project

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

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

171− - "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-file-upload|cookbook-generic|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-jsaddle|servant-machines|servant-pipes|servant-server|tutorial)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"

172− - cat cabal.project || true

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

199− - rm cabal.project.freeze

200−script:

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

202− # Packaging...

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

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

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

206− # Unpacking...

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

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

209− - cd ${DISTDIR} || false

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

235− # Generate cabal.project

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

237− - touch cabal.project

238− - |

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

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

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

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

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

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

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

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

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

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

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

250− if $GHCJS || ! $GHCJS && [ $HCNUMVER -lt 80800 ] ; then echo "packages: ${PKGDIR_servant_jsaddle}" >> cabal.project ; fi

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

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

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

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

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

256− if ! $GHCJS && [ $HCNUMVER -ge 80400 ] ; then echo "packages: ${PKGDIR_cookbook_generic}" >> 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 "constraints: sqlite-simple < 0" >> cabal.project

266− echo "allow-newer: aeson-pretty-0.8.7:base-compat" >> cabal.project

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

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

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

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

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

272− echo "allow-newer: io-streams-1.5.1.0:primitive" >> cabal.project

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

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

275− - "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-file-upload|cookbook-generic|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-jsaddle|servant-machines|servant-pipes|servant-server|tutorial)$' || true) | sed 's/^/constraints: /' | sed 's/$/ installed/' >> cabal.project.local; done"

276− - cat cabal.project || true

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

278− - |

279− pkgdir() {

280− case $1 in

281− servant) echo ${PKGDIR_servant} ;;

282− servant-client) echo ${PKGDIR_servant_client} ;;

283− servant-client-core) echo ${PKGDIR_servant_client_core} ;;

284− servant-http-streams) echo ${PKGDIR_servant_http_streams} ;;

285− servant-docs) echo ${PKGDIR_servant_docs} ;;

286− servant-foreign) echo ${PKGDIR_servant_foreign} ;;

287− servant-server) echo ${PKGDIR_servant_server} ;;

288− tutorial) echo ${PKGDIR_tutorial} ;;

289− servant-machines) echo ${PKGDIR_servant_machines} ;;

290− servant-conduit) echo ${PKGDIR_servant_conduit} ;;

291− servant-pipes) echo ${PKGDIR_servant_pipes} ;;

292− servant-jsaddle) echo ${PKGDIR_servant_jsaddle} ;;

293− cookbook-basic-auth) echo ${PKGDIR_cookbook_basic_auth} ;;

294− cookbook-curl-mock) echo ${PKGDIR_cookbook_curl_mock} ;;

295− cookbook-basic-streaming) echo ${PKGDIR_cookbook_basic_streaming} ;;

296− cookbook-db-postgres-pool) echo ${PKGDIR_cookbook_db_postgres_pool} ;;

297− cookbook-file-upload) echo ${PKGDIR_cookbook_file_upload} ;;

298− cookbook-generic) echo ${PKGDIR_cookbook_generic} ;;

299− cookbook-pagination) echo ${PKGDIR_cookbook_pagination} ;;

300− cookbook-testing) echo ${PKGDIR_cookbook_testing} ;;

301− cookbook-structuring-apis) echo ${PKGDIR_cookbook_structuring_apis} ;;

302− cookbook-using-custom-monad) echo ${PKGDIR_cookbook_using_custom_monad} ;;

303− cookbook-using-free-client) echo ${PKGDIR_cookbook_using_free_client} ;;

304− esac

305− }

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

307− # Building with tests and benchmarks...

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

309− # build & run tests, build benchmarks

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

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

312− # Testing...

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

314− - if $GHCJS ; then cabal-plan list-bins '*:test:*' | while read -r line; do testpkg=$(echo "$line" | perl -pe 's/:.*//'); testexe=$(echo "$line" | awk '{ print $2 }'); echo "testing $textexe in package $textpkg"; (cd "$(pkgdir $testpkg)" && nodejs "$testexe".jsexe/all.js); done ; fi

315− # haddock...

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

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

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

319−

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

321−# EOF

CONTRIBUTING.md+33−4

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

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

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

3737

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+```

3966

4067## PR process

4168

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

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

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

5481getting 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

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

82+know about it! Either hop on

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

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

85+read it).

5786

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

5988since 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!

76105

77106## Release policy

78107

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

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

81110releases it may take some time in between releases.

82111

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.5

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

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

1010examples.

1111

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

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

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

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

1515

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

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

1818

1919## Contributing

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

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

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

3434 - 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.

3636 - Temporarily comment out broken package

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

3838- When ripples are cleared out:

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

4040 - `git push --tags`

4141 - `cabal sdist` and `cabal upload`

4242

43−## travis

43+## TechEmpower framework benchmarks

4444

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

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

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

4746

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)

4948

50−```

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

49+```sh

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

5251```

5352

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

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:

53+To compare with `warp`

5754

55+```sh

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

5857```

59−constraints:

60− troublemaker <13.37 && > 13.37

58+

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

6163```

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+5−1

@@ -2,9 +2,13 @@

22

33packages:

44 servant/

5+ servant-client/

56 servant-client-core/

6− servant-jsaddle/

77

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

99compiler: ghcjs

1010tests: 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−21

@@ -1,21 +0,0 @@

1−folds: all-but-test

2−branches: master

3−jobs-selection: any

4−google-chrome: True

5−ghcjs-tests: True

6−

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

8−ghcjs-tools: hspec-discover

9−

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

11−install-dependencies: False

12−

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

14−no-tests-no-benchmarks: False

15−unconstrained: False

16−

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

18−cabal-check: False

19−

20−-- ghc-options: -j2

21−jobs: :2

cabal.project+18−28

@@ -1,11 +1,18 @@

11packages:

22 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+

39 servant-client/

410 servant-client-core/

511 servant-http-streams/

612 servant-docs/

713 servant-foreign/

814 servant-server/

15+ servant-swagger/

916 doc/tutorial/

1017

1118-- servant streaming

@@ -15,50 +22,33 @@ packages:

1522 servant-pipes/

1623

1724-- servant GHCJS

18−packages:

19− servant-jsaddle/

25+-- packages:

26+-- servant-jsaddle/

2027

2128-- Cookbooks

2229packages:

2330 doc/cookbook/basic-auth

2431 doc/cookbook/curl-mock

32+ doc/cookbook/custom-errors

2533 doc/cookbook/basic-streaming

2634 doc/cookbook/db-postgres-pool

27−-- doc/cookbook/db-sqlite-simple

35+ doc/cookbook/db-sqlite-simple

2836 doc/cookbook/file-upload

2937 doc/cookbook/generic

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

31−-- doc/cookbook/https

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

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

39+ doc/cookbook/https

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

3341 doc/cookbook/pagination

3442 -- doc/cookbook/sentry

35− doc/cookbook/testing

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

44+ -- doc/cookbook/testing

45+ doc/cookbook/uverb

3646 doc/cookbook/structuring-apis

3747 doc/cookbook/using-custom-monad

3848 doc/cookbook/using-free-client

3949 -- doc/cookbook/open-id-connect

40−

41−

50+ doc/cookbook/managed-resource

4251

4352tests: True

4453optimization: False

4554-- reorder-goals: True

46−

47−constraints:

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

49− foundation >=0.0.14,

50− memory <0.14.12 || >0.14.12

51−

52−allow-newer: aeson-pretty-0.8.7:base-compat

53−

54−allow-newer: vault-0.3.1.2:hashable

55−allow-newer: psqueues-0.2.7.1:hashable

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

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

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

59−allow-newer: io-streams-1.5.1.0:primitive

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

61−

62−-- MonadFail

63−-- https://github.com/nurpax/sqlite-simple/issues/74

64−constraints: sqlite-simple < 0

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/1571new file+10

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

1+synopsis: Support UVerb in servant-auth-server

2+prs: #1571

3+issues: #1570

4+description: {

5+UVerb endpoints are now supported by servant-auth-server and can be used under the

6+Auth combinator when writing servers. It is still unsupported by

7+servant-auth-client.

8+

9+This PR also brings Headers support in UVerb responses

10+}

changelog.d/1573new file+2

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

1+synopsis: Add API docs for ServerT

2+prs: #1573

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/1606new file+10

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

1+synopsis: Handle Cookies correctly for RunStreamingClient

2+prs: #1606

3+issues: #1605

4+

5+description: {

6+

7+Makes performWithStreamingRequest take into consideration the

8+CookieJar, which it previously didn't.

9+

10+}

changelog.d/1638new file+2

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

1+synopsis: Add Functor instance to AuthHandler.

2+prs: #1638

changelog.d/1649new file+8

@@ -0,0 +1,8 @@

1+synopsis: Add HasStatus instance for Headers (that defers StatusOf to underlying value)

2+prs: #1649

3+

4+description: {

5+

6+Adds a new HasStatus (Headers hs a) instance (StatusOf (Headers hs a) = StatusOf a)

7+

8+}

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

1010

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

1212help:

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

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

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

1616

doc/conf.py+1−2

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

4646

4747# General information about the project.

4848project = u'Servant'

49−copyright = u'2018, Servant Contributors'

49+copyright = u'2022, Servant Contributors'

5050author = u'Servant Contributors'

5151

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

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

169169source_parsers = {

170170 '.lhs': CommonMarkParser,

171171}

172−

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

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

1+cabal-version: 2.2

12name: cookbook-basic-auth

23version: 0.1

34synopsis: Basic Authentication cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-basic-auth

1414 main-is: BasicAuth.lhs

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

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

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

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

1010 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))

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

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

1417

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

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

1+cabal-version: 2.2

12name: cookbook-basic-streaming

23version: 2.1

34synopsis: Streaming in servant without streaming libs

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-basic-streaming

1414 main-is: Streaming.lhs

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

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

11# Generating mock curl calls

22

33In 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.

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

66

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

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

2424import Control.Lens ((^.))

2525import Data.Aeson

2626import Data.Aeson.Text

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

2827import Data.Proxy (Proxy (Proxy))

2928import Data.Text (Text)

3029import Data.Text.Encoding (decodeUtf8)

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

8685```

8786

8887This 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.

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

9190

9291In 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

130129generateCurl p host =

131130 fmap T.unlines body

132131 where

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

132+ body = mapM (generateEndpoint host)

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

135134```

136135

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

138−

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:

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

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

151138

152139``` haskell

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

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

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

170157

171158`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).

173160

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

175162

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

201188``` haskell

202189main :: IO ()

203190main =

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

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

205192```

206193

207194Done:

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

213200```

214201

215202This 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.

217204

218205Also, 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

12name: cookbook-curl-mock

23version: 0.1

34synopsis: Generate curl mock requests cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbock-curl-mock

14+ if impl(ghc >= 9.2)

15+ -- generic-arbitrary is incompatible

16+ buildable: False

1417 main-is: CurlMock.lhs

1518 build-depends: base == 4.*

1619 , 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 @@

22

33This 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.

44

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.

66

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

88

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

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

1+cabal-version: 2.2

12name: mysql-basics

23version: 0.1.0.0

34synopsis: Simple MySQL API cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

1111

1212executable run

1313 hs-source-dirs: .

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

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

1+cabal-version: 2.2

12name: cookbook-db-postgres-pool

23version: 0.1

34synopsis: Simple PostgreSQL connection pool cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-db-postgres-pool

1414 main-is: PostgresPool.lhs

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

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

1+cabal-version: 2.2

12name: cookbook-db-sqlite-simple

23version: 0.1

34synopsis: Simple SQLite DB cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-db-sqlite-simple

1414 main-is: DBConnection.lhs

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

2323 , http-types >= 0.12

2424 , markdown-unlit >= 0.4

2525 , http-client >= 0.5

26− , sqlite-simple >= 0.4

26+ , sqlite-simple >= 0.4.5.0

2727 , transformers

2828 default-language: Haskell2010

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

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

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

9090

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

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

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

94−yet have support for client generation.

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

94+yet have support for client generation).

9595

9696``` haskell

9797main :: IO ()

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

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

1+cabal-version: 2.2

12name: cookbook-file-upload

23version: 0.1

34synopsis: File upload cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-file-upload

1414 main-is: FileUpload.lhs

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

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

4343api = genericApi (Proxy :: Proxy Routes)

4444```

4545

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

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

4848

4949## Links

5050

5151The 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,

5353as field accessors work as proxies:

5454

5555```haskell

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

6767## Client

6868

6969Even 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

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

7272

7373```haskell

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

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

1+cabal-version: 2.2

12name: cookbook-generic

23version: 0.1

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

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-using-custom-monad

1414 main-is: Generic.lhs

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

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

254254 liftIO $ pushLogStrLn logset $ toLogStr logMsg

255255 throwError err401

256256 Just applyCookies -> do

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

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

258258 liftIO $ pushLogStrLn logset $ toLogStr successMsg

259259 pure $ applyCookies successMsg

260260loginHandler _ _ _ = throwError err401

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

287287 (flip runReaderT ctx) (adminServer cs jwts)

288288```

289289

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

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

292292

293293```haskell

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

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

1+cabal-version: 2.2

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

23version: 0.0.1

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

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

56 authentication.

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

7−license: BSD3

8+license: BSD-3-Clause

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

910author: Servant Contributors

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

1112category: Servant

1213build-type: Simple

13−cabal-version: >=1.10

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

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

1515

1616executable cookbook-hoist-server-with-context

1717 main-is: HoistServerWithContext.lhs

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

2424 , servant

2525 , servant-server

2626 , servant-auth >= 0.3.2

27− , servant-auth-server

27+ , servant-auth-server >= 0.4.4.0

2828 , time

2929 , warp >= 3.2

3030 , wai >= 3.2

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

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

3434```

3535

3636It'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)

3838package 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)

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

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/docs/Network-Wai-Handler-WarpTLS.html#v:runTLSSocket).

4141We will be using the first one.

4242

4343It 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)

4545(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)

4747(port, logger, etc).

4848

4949We 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

12name: cookbook-https

23version: 0.1

34synopsis: HTTPS cookbook example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-https

1414 main-is: Https.lhs

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

1717 , servant-server

1818 , wai >= 3.2

1919 , warp >= 3.2

20− , warp-tls >= 3.2

20+ , warp-tls >= 3.2.9

2121 , markdown-unlit >= 0.4

2222 default-language: Haskell2010

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

doc/cookbook/index.rst+5−2

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

66interested in contributing examples of your own, feel free

77to open an issue or a pull request on

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

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

10−on freenode or on

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

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

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

1212

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

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

2525 db-postgres-pool/PostgresPool.lhs

2626 using-custom-monad/UsingCustomMonad.lhs

2727 using-free-client/UsingFreeClient.lhs

28+ custom-errors/CustomErrors.lhs

29+ uverb/UVerb.lhs

2830 basic-auth/BasicAuth.lhs

2931 basic-streaming/Streaming.lhs

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

@@ -35,3 +37,4 @@ you name it!

3537 sentry/Sentry.lhs

3638 testing/Testing.lhs

3739 open-id-connect/OpenIdConnect.lhs

40+ managed-resource/ManagedResource.lhs

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

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

1+cabal-version: 2.2

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

23version: 0.0.1

34synopsis: JWT and basic access authentication cookbook example

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

56 authentication.

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

7−license: BSD3

8+license: BSD-3-Clause

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

910author: Servant Contributors

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

1112category: Servant

1213build-type: Simple

13−cabal-version: >=1.10

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

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

1515

1616executable cookbook-jwt-and-basic-auth

1717 main-is: JWTAndBasicAuth.lhs

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

2222 , servant

2323 , servant-client

2424 , servant-server

25− , servant-auth ==0.3.*

25+ , servant-auth == 0.4.*

2626 , servant-auth-server >= 0.3.1.0

2727 , warp >= 3.2

2828 , wai >= 3.2

doc/cookbook/managed-resource/ManagedResource.lhsnew file+114

@@ -0,0 +1,114 @@

1+# Request-lifetime Managed Resources

2+

3+Let's see how we can write a handle that uses a resource managed by Servant. The resource is created automatically by Servant when the server recieves a request, and the resource is automatically destroyed when the server is finished handling a request.

4+

5+As usual, we start with a little bit of throat clearing.

6+

7+

8+``` haskell

9+{-# LANGUAGE DataKinds #-}

10+{-# LANGUAGE TypeOperators #-}

11+import Control.Concurrent

12+import Control.Exception (bracket, throwIO)

13+import Control.Monad.IO.Class

14+import Control.Monad.Trans.Resource

15+import Data.Acquire

16+import Network.HTTP.Client (newManager, defaultManagerSettings)

17+import Network.Wai.Handler.Warp

18+import Servant

19+import Servant.Client

20+import System.IO

21+```

22+

23+Here we define an API type that uses the `WithResource` combinator. The server handler for an endpoint with a `WithResource res` component will receive a value of that type as an argument.

24+

25+``` haskell

26+type API = WithResource Handle :> ReqBody '[PlainText] String :> Post '[JSON] NoContent

27+

28+api :: Proxy API

29+api = Proxy

30+```

31+

32+But this resource value has to come from somewhere. Servant obtains the value using an Acquire provided in the context. The Acquire knows how to both create and destroy resources of a particular type.

33+

34+``` haskell

35+appContext :: Context '[Acquire Handle]

36+appContext = acquireHandle :. EmptyContext

37+

38+acquireHandle :: Acquire Handle

39+acquireHandle = mkAcquire newHandle closeHandle

40+

41+newHandle :: IO Handle

42+newHandle = do

43+ putStrLn "opening file"

44+ h <- openFile "test.txt" AppendMode

45+ putStrLn "opened file"

46+ return h

47+

48+closeHandle :: Handle -> IO ()

49+closeHandle h = do

50+ putStrLn "closing file"

51+ hClose h

52+ putStrLn "closed file"

53+```

54+

55+Now we create the handler which will use this resource. This handler will write the request message to the System.IO.Handle which was provided to us. In some situations the handler will succeed, but in some in will fail. In either case, Servant will clean up the resource for us.

56+

57+``` haskell

58+server :: Server API

59+server = writeToFile

60+

61+ where writeToFile :: (ReleaseKey, Handle) -> String -> Handler NoContent

62+ writeToFile (_, h) msg = case msg of

63+ "illegal" -> error "wait, that's illegal!"

64+ legalMsg -> liftIO $ do

65+ putStrLn "writing file"

66+ hPutStrLn h legalMsg

67+ putStrLn "wrote file"

68+ return NoContent

69+```

70+

71+Finally we run the server in the background while we post messages to it.

72+

73+``` haskell

74+runApp :: IO ()

75+runApp = run 8080 (serveWithContext api appContext $ server)

76+

77+postMsg :: String -> ClientM NoContent

78+postMsg = client api

79+

80+main :: IO ()

81+main = do

82+ mgr <- newManager defaultManagerSettings

83+ bracket (forkIO $ runApp) killThread $ \_ -> do

84+ ms <- flip runClientM (mkClientEnv mgr (BaseUrl Http "localhost" 8080 "")) $ do

85+ liftIO $ putStrLn "sending hello message"

86+ _ <- postMsg "hello"

87+ liftIO $ putStrLn "sending illegal message"

88+ _ <- postMsg "illegal"

89+ liftIO $ putStrLn "done"

90+ print ms

91+```

92+

93+This program prints

94+

95+```

96+sending hello message

97+opening file

98+opened file

99+writing file

100+wrote file

101+closing file

102+closed file

103+sending illegal message

104+opening file

105+opened file

106+closing file

107+closed file

108+wait, that's illegal!

109+CallStack (from HasCallStack):

110+ error, called at ManagedResource.lhs:63:24 in main:Main

111+Left (FailureResponse (Request {requestPath = (BaseUrl {baseUrlScheme = Http, baseUrlHost = "localhost", baseUrlPort = 8080, baseUrlPath = ""},""), requestQueryString = fromList [], requestBody = Just ((),text/plain;charset=utf-8), requestAccept = fromList [], requestHeaders = fromList [], requestHttpVersion = HTTP/1.1, requestMethod = "POST"}) (Response {responseStatusCode = Status {statusCode = 500, statusMessage = "Internal Server Error"}, responseHeaders = fromList [("Transfer-Encoding","chunked"),("Date","Thu, 24 Nov 2022 21:04:47 GMT"),("Server","Warp/3.3.23"),("Content-Type","text/plain; charset=utf-8")], responseHttpVersion = HTTP/1.1, responseBody = "Something went wrong"}))

112+```

113+

114+and appends to a file called `test.txt`. We can see from the output that when a legal message is sent, the file is opened, written to, and closed. We can also see that when an illegal message is sent, the file is opened but not written to. Crucially, it is still closed even though the handler threw an exception.

doc/cookbook/managed-resource/managed-resource.cabalnew file+30

@@ -0,0 +1,30 @@

1+cabal-version: 2.2

2+name: cookbook-managed-resource

3+version: 0.1

4+synopsis: Simple managed resource cookbook example

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==9.4.2

12+

13+executable cookbook-managed-resource

14+ main-is: ManagedResource.lhs

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

16+ , text >= 1.2

17+ , aeson >= 1.2

18+ , servant

19+ , servant-client

20+ , servant-server

21+ , warp >= 3.2

22+ , wai >= 3.2

23+ , http-types >= 0.12

24+ , markdown-unlit >= 0.4

25+ , http-client >= 0.5

26+ , transformers

27+ , resourcet

28+ default-language: Haskell2010

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

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

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

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

1+cabal-version: 2.2

12name: open-id-connect

23version: 0.1

34synopsis: OpenId Connect with Servant example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-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

1212

1313executable cookbook-openidconnect

1414 main-is: OpenIdConnect.lhs

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

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

88

99Workflow:

1010

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

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

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

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

1313 provider,

14143. the user login in the OIDC provider,

15154. 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.

221221

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

223223POSTing 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

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

226−asked we might get more informations.

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

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

226+asked we might get more information.

227227

228228``` haskell

229229-- | @AuthInfo@

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

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

249249```

250250

251−The `handleLoggedIn` is that part that will retrieve the informations from

251+The `handleLoggedIn` is that part that will retrieve the information from

252252the user once he is redirected from the OIDC Provider after login.

253253

254254If 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.

256256If 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

258−endpoint of the OIDC provider. Its a POST that should contains the code

259−as well as the client id & secret.

260−This is the role of the `requestTokens` to make this HTTP POST.

257+successfully logged in. From there we need to make a request to the token

258+endpoint of the OIDC provider. It's a POST that should contain the code

259+as well as the client id and secret.

260+Making this HTTP POST is the responsibility of `requestTokens`.

261261

262262From there we extract the `claims` of the JWT contained in one of the value

263263of the JSON returned by the POST HTTP Request.

@@ -329,12 +329,12 @@ data Customer = Customer {

329329 }

330330```

331331

332−Here is the code that display the homepage.

333−It 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

335−with some generated informations.

332+Here is the code that displays the homepage.

333+It should contain a link to the `/login` URL.

334+When the user clicks on this link it will be redirected to Google login page

335+with some generated information.

336336

337−The page also display the content of the local storage.

337+The page also displays the content of the local storage.

338338And in particular the items `api-key` and `user-id`.

339339Those items should be set after a successful login when the user is redirected to

340340`/login/cb`.

@@ -366,7 +366,7 @@ instance ToMarkup Homepage where

366366We need some helpers to generate random string for generating state and API Keys.

367367

368368``` haskell

369−-- | generate a random Bystestring, not necessarily extremely good randomness

369+-- | generate a random ByteString, not necessarily extremely good randomness

370370-- still the password will be long enough to be very difficult to crack

371371genRandomBS :: IO ByteString

372372genRandomBS = 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

1818the client is willing to retrieve the next batch of document in descending order that were

1919created after the fifteenth of January, skipping the first 5.

2020

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

2222response with 3 headers:

2323

2424- `Accept-Ranges`: A comma-separated list of fields upon which a range can be defined

@@ -127,7 +127,7 @@ defaultRange =

127127 getDefaultRange (Proxy @Color)

128128```

129129

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

131131of the class. Yet, you can define `getRangeOptions` to provide different parsing options (see

132132the last section of this guide). In the meantime, we've also defined a `defaultRange` as it will

133133come in handy when defining our handler.

@@ -148,7 +148,7 @@ type MyHeaders =

148148```

149149

150150`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:

152152

153153``` haskell

154154-- type MyHeaders =

@@ -165,7 +165,7 @@ not, _servant-pagination_ provides an easy way to lift a collection of resources

165165#### Server

166166

167167Time 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`

169169header, looking for the format defined in introduction with fields and target types we have just declared.

170170If no such header is provided, we will end up receiving `Nothing`. Otherwise, it will be possible

171171to _extract_ a `Range` from our `Ranges`.

@@ -192,7 +192,7 @@ the format we defined, where `<field>` here can only be `name` and `<value>` mus

192192- `Range: <field> [<value>][; offset <o>][; limit <l>][; order <asc|desc>]`

193193

194194Beside 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

196196following examples are valid requests to send to our server:

197197

198198- 1 - `curl http://localhost:1442/colors -vH 'Range: name'`

@@ -219,7 +219,7 @@ The previous ranges reads as follows:

219219Note that in the simple above scenario, there's no ambiguity with `extractRange` and `returnRange`

220220because there's only one possible `Range` defined on our resource. Yet, as you've most probably

221221noticed, 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

223223highly likely to be needed.

224224

225225

@@ -235,8 +235,8 @@ instance HasPagination Color "hex" where

235235#### Parsing Options

236236

237237By default, `servant-pagination` provides an implementation of `getRangeOptions` for each

238−`HasPagination` instance. However, this can be overwritten 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

238+`HasPagination` instance. However, this can be overridden when defining the instance to provide

239+your own options. These options come into play when a `Range` header is received and isn't fully

240240specified (`limit`, `offset`, `order` are all optional) to provide default fallback values for those.

241241

242242For instance, let's say we wanted to change the default limit to `5` in a new range on

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

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

1+cabal-version: 2.2

12name: cookbook-pagination

23version: 2.1

34synopsis: Pagination with Servant example

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-pagination

1414 main-is: Pagination.lhs

doc/cookbook/sentry/Sentry.lhs+2−2

@@ -79,14 +79,14 @@ It does three things. First it initializes the service which will communicate wi

7979

8080- the Sentry `DSN`, which is obtained when creating a new project on Sentry

8181- 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

8383- a fallback handler, which we choose to be `silentFallback` since later we are logging to the console anyway.

8484

8585In the second step it actually sends our message to Sentry with the `register` function. Its arguments are:

8686

8787- the configured Sentry service which we just created

8888- 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)

9090- the message we want to send

9191- an update function to handle the specific `SentryRecord`

9292

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

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

1+cabal-version: 2.2

12name: cookbook-sentry

23version: 0.1

34synopsis: Collecting runtime exceptions using Sentry

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-sentry

1414 main-is: Sentry.lhs

doc/cookbook/structuring-apis/StructuringApis.lhs+1−1

@@ -144,7 +144,7 @@ simpleAPIServer

144144 :: m [a]

145145 -> (i -> m a)

146146 -> (a -> m NoContent)

147− -> Server (SimpleAPI name a i) m

147+ -> ServerT (SimpleAPI name a i) m

148148simpleAPIServer listAs getA postA =

149149 listAs :<|> getA :<|> postA

150150

doc/cookbook/structuring-apis/structuring-apis.cabal+3−3

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

1+cabal-version: 2.2

12name: cookbook-structuring-apis

23version: 0.1

34synopsis: Example that shows how APIs can be structured

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-structuring-apis

1414 main-is: StructuringApis.lhs

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

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

1+cabal-version: 2.2

12name: cookbook-testing

23version: 0.0.1

34synopsis: Common testing patterns in Servant apps

45description: This recipe includes various strategies for writing tests for Servant.

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

6−license: BSD3

7+license: BSD-3-Clause

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

89author: Servant Contributors

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

1011category: Servant

1112build-type: Simple

12−cabal-version: >=1.10

13−tested-with: GHC==8.4.4, GHC==8.6.5, GHC==8.8.1

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

1414

1515executable cookbook-testing

1616 main-is: Testing.lhs

@@ -23,7 +23,7 @@ executable cookbook-testing

2323 , servant

2424 , servant-client

2525 , servant-server

26− , servant-quickcheck

26+ , servant-quickcheck >= 0.0.10

2727 , http-client

2828 , http-types >= 0.12

2929 , hspec

doc/cookbook/using-custom-monad/UsingCustomMonad.lhs+1−1

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

11# Using a custom monad

22

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.

44We will keep state in memory and share it between requests using `Reader` monad and `STM`.

55

66We 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

12name: cookbook-using-custom-monad

23version: 0.1

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

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-using-custom-monad

1414 main-is: UsingCustomMonad.lhs

doc/cookbook/using-free-client/UsingFreeClient.lhs+6−6

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

22

33or simply put: _a practical introduction to `Servant.Client.Free`_.

44

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)

66produced (resp. received) by client functions derived using servant-client.

77My response to such inquiries is: to extend `servant-client` in an ad-hoc way (e.g for testing or debugging

88purposes), 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`

119119to http-client's `Request`, and we can inspect it:

120120

121121```haskell

122− let req' = I.requestToClientRequest burl req

122+ req' <- I.defaultMakeClientRequest burl req

123123 putStrLn $ "Making request: " ++ show req'

124124```

125125

@@ -136,12 +136,12 @@ and calling the continuation. We should get a `Pure` value.

136136

137137```haskell

138138 let res = I.clientResponseToResponse id res'

139−

139+

140140 case k res of

141141 Pure n ->

142142 putStrLn $ "Expected 1764, got " ++ show n

143− _ ->

144− putStrLn "ERROR: didn't got a response"

143+ _ ->

144+ putStrLn "ERROR: didn't get a response"

145145```

146146

147147So 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

153153access to one `Request` or `Response` at a time.

154154

155155On 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

157157by using a `Writer [(Request, Response)]` monad.

158158

159159Here 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

12name: cookbook-using-free-client

23version: 0.1

34synopsis: Using Free client

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

5−license: BSD3

6+license: BSD-3-Clause

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

78author: Servant Contributors

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

910build-type: Simple

10−cabal-version: >=1.10

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

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

1212

1313executable cookbook-using-free-client

1414 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 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

1212 `https://github.com/haskell-servant/servant/issues <https://github.com/haskell-servant/servant/issues>`_

1313

1414- the irc channel:

15− ``#servant`` on freenode

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

1616

1717- the mailing list:

1818 `groups.google.com/forum/#!forum/haskell-servant <https://groups.google.com/forum/#!forum/haskell-servant>`_

doc/requirements.txt+1

@@ -1,3 +1,4 @@

11recommonmark==0.5.0

22Sphinx==1.8.4

33sphinx_rtd_theme>=0.4.2

4+jinja2<3.1.0

doc/tutorial/ApiType.lhs+30−4

@@ -177,13 +177,12 @@ type UserAPI5 = "user" :> Capture "userid" Integer :> Get '[JSON] User

177177 -- except that we explicitly say that "userid"

178178 -- must be an integer

179179

180− :<|> "user" :> Capture "userid" Integer :> DeleteNoContent '[JSON] NoContent

180+ :<|> "user" :> Capture "userid" Integer :> DeleteNoContent

181181 -- equivalent to 'DELETE /user/:userid'

182182```

183183

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.

184+In the second case, `DeleteNoContent` specifies a 204 response code

185+and that the response will always be empty.

187186

188187### `QueryParam`, `QueryParams`, `QueryFlag`

189188

@@ -390,3 +389,30 @@ One example for this is if you want to serve a directory of static files along

390389with the rest of your API. But you can plug in everything that is an

391390`Application`, e.g. a whole web application written in any of the web

392391frameworks 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

4747import Data.Aeson (ToJSON)

4848import Data.ByteString (ByteString)

4949import Data.Map (Map, fromList)

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

5150import qualified Data.Map as Map

5251import Data.Proxy (Proxy (Proxy))

5352import Data.Text (Text)

@@ -108,7 +107,7 @@ API with "private." Additionally, the private parts of our API use the

108107realm for this authentication is `"foo-realm"`).

109108

110109Unfortunately 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

112111usernames and passwords. This adds a certain conceptual wrinkle in servant's

113112design that we'll briefly discuss. If you want the **TL;DR**: we supply a lookup

114113function to servant's new `Context` primitive.

@@ -133,7 +132,7 @@ combinator. Using `Context`, we can supply a function of type

133132handler. This will allow the handler to check authentication and return a `User`

134133to downstream handlers if successful.

135134

136−In practice we wrap `BasicAuthData -> Handler` into a slightly

135+In practice we wrap `BasicAuthData -> Handler User` into a slightly

137136different function to better capture the semantics of basic authentication:

138137

139138``` haskell ignore

@@ -260,7 +259,7 @@ this.

260259

261260Let's implement a trivial authentication scheme. We will protect our API by

262261looking 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`.

264263

265264```haskell

266265-- | An account type that we "fetch from the database" after

@@ -274,7 +273,7 @@ database = fromList [ ("key1", Account "Anne Briggs")

274273 , ("key3", Account "Ghédalia Tazartès")

275274 ]

276275

277−-- | A method that, when given a password, will return a Account.

276+-- | A method that, when given a password, will return an Account.

278277-- This is our bespoke (and bad) authentication logic.

279278lookupAccount :: ByteString -> Handler Account

280279lookupAccount key = case Map.lookup key database of

@@ -318,7 +317,7 @@ genAuthAPI = Proxy

318317

319318Now we need to bring everything together for the server. We have the

320319`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)

322321instance that tells the `HasServer` instance that our `Context` will supply a

323322`Account` (via `AuthHandler Request Account`) and that downstream combinators will

324323have access to this `Account` value (or an error will be thrown if authentication

@@ -346,7 +345,7 @@ genAuthServerContext = authHandler :. EmptyContext

346345

347346-- | Our API, where we provide all the author-supplied handlers for each end

348347-- 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,

350349-- that is taken care of by supplying context

351350genAuthServer :: Server AuthGenAPI

352351genAuthServer =

@@ -368,10 +367,10 @@ genAuthMain = run 8080 (serveWithContext genAuthAPI genAuthServerContext genAuth

368367$ curl -XGET localhost:8080/private

369368Missing auth header

370369

371−$ curl -XGET localhost:8080/private -H "servant-auth-cookie: key3"

370+$ curl -XGET localhost:8080/private -H "Cookie: servant-auth-cookie=key3"

372371[{"ssshhh":"this is a secret: Ghédalia Tazartès"}]

373372

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"

375374Invalid Cookie

376375

377376$ curl -XGET localhost:8080/public

@@ -385,11 +384,11 @@ Creating a generalized, ad-hoc authentication scheme was fairly straight

385384forward:

386385

3873861. 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

389388authentication is successful (in our case this was `Account`).

3903893. Create a value of `AuthHandler Request Account` which encapsulates the

391390authentication 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.

3933924. Provide an instance of the `AuthServerData` type family, specifying your

394393application-specific data type returned when authentication is successful (in

395394our case this was `Account`).

doc/tutorial/Client.lhs+4−4

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

11# Querying an API

22

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.

44

55**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.

77

88The source for this tutorial section is a literate Haskell file, so first we need to have some language extensions and imports:

99

@@ -161,7 +161,7 @@ The types of the arguments for the functions are the same as for (server-side) r

161161## Changing the monad the client functions live in

162162

163163Just 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

165165in which _client functions_ live. Consider the following trivial API:

166166

167167``` haskell

@@ -173,7 +173,7 @@ hoistClientAPI = Proxy

173173

174174We already know how to derive client functions for this API, and as we have

175175seen 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

177177functions in. Sometimes we need to run them in IO, sometimes in a custom monad

178178stack. `hoistClient` is a very simple solution to the problem of "changing" the monad

179179the clients run in.

doc/tutorial/Docs.lhs+2−2

@@ -77,7 +77,7 @@ instance ToSample HelloMessage where

7777 [ ("When a value is provided for 'name'", HelloMessage "Hello, Alp")

7878 , ("When 'name' is not specified", HelloMessage "Hello, anonymous coward")

7979 ]

80− -- mutliple examples to display this time

80+ -- multiple examples to display this time

8181

8282ci :: ClientInfo

8383ci = ClientInfo "Alp" "alp@foo.com" 26 ["haskell", "mathematics"]

@@ -108,7 +108,7 @@ apiDocs = docs exampleAPI

108108markdown :: API -> String

109109```

110110

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`.

112112

113113````````` text

114114## GET /hello

doc/tutorial/Javascript.lhs+2−2

@@ -228,13 +228,13 @@ data CommonGeneratorOptions = CommonGeneratorOptions

228228 {

229229 -- | function generating function names

230230 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)

232232 , requestBody :: Text

233233 -- | name of the callback parameter when the request was successful

234234 , successCallback :: Text

235235 -- | name of the callback parameter when the request reported an error

236236 , 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)

238238 , moduleName :: Text

239239 -- | a prefix that should be prepended to the URL in the generated JS

240240 , urlPrefix :: Text

doc/tutorial/Server.lhs+22−22

@@ -183,7 +183,7 @@ users2 = [isaac, albert]

183183

184184Now, just like we separate the various endpoints in `UserAPI` with `:<|>`, we

185185are 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.

187187

188188``` haskell

189189server2 :: Server UserAPI2

@@ -313,8 +313,8 @@ For reference, here's a list of some combinators from **servant**:

313313## The `FromHttpApiData`/`ToHttpApiData` classes

314314

315315Wait... 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

317−following two sections address.

316+to decode a `ClientInfo` value from the request body? The following three sections will

317+help us answer these questions.

318318

319319`Capture`s and `QueryParam`s are represented by some textual value in URLs.

320320`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

620620equivalent to a computation of type `IO (Either ServerError a)`, that is, an IO

621621action that either returns an error or a result.

622622

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)

624624from which `ExceptT` comes is worth looking at.

625625Perhaps most importantly, `ExceptT` and `Handler` are instances of `MonadError`, so

626626`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.

634634

635635Other important instances from the list above are `MonadIO m => MonadIO

636636(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)

638638is a class from the **transformers** package defined as:

639639

640640``` haskell ignore

@@ -716,7 +716,7 @@ $ curl --verbose http://localhost:8081/myfile.txt

716716>

717717< HTTP/1.1 404 Not Found

718718[snip]

719−myfile.txt just isnt there, please leave this server alone.

719+myfile.txt just isn't there, please leave this server alone.

720720

721721$ echo Hello > myfile.txt

722722

@@ -818,7 +818,7 @@ If it doesn't exist, the handler will fail with a `404` status code.

818818

819819`serveDirectoryWebApp` uses some standard settings that fit the use case of

820820serving 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.

822822

823823## Nested APIs

824824

@@ -830,7 +830,7 @@ type UserAPI3 = -- view the user with given userid, in JSON

830830 Capture "userid" Int :> Get '[JSON] User

831831

832832 :<|> -- delete the user with given userid. empty response

833− Capture "userid" Int :> DeleteNoContent '[JSON] NoContent

833+ Capture "userid" Int :> DeleteNoContent

834834```

835835

836836We can instead factor out the `userid`:

@@ -838,7 +838,7 @@ We can instead factor out the `userid`:

838838``` haskell

839839type UserAPI4 = Capture "userid" Int :>

840840 ( Get '[JSON] User

841− :<|> DeleteNoContent '[JSON] NoContent

841+ :<|> DeleteNoContent

842842 )

843843```

844844

@@ -896,13 +896,13 @@ type API1 = "users" :>

896896-- we factor out the Request Body

897897type API2 = ReqBody '[JSON] User :>

898898 ( 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

900900 )

901901

902902-- we factor out a Header

903903type API3 = Header "Authorization" Token :>

904904 ( 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

906906 )

907907

908908newtype Token = Token ByteString

@@ -915,11 +915,11 @@ API type only at the end.

915915``` haskell

916916type UsersAPI =

917917 Get '[JSON] [User] -- list users

918− :<|> ReqBody '[JSON] User :> PostNoContent '[JSON] NoContent -- add a user

918+ :<|> ReqBody '[JSON] User :> PostNoContent -- add a user

919919 :<|> Capture "userid" Int :>

920920 ( Get '[JSON] User -- view a user

921− :<|> ReqBody '[JSON] User :> PutNoContent '[JSON] NoContent -- update a user

922− :<|> DeleteNoContent '[JSON] NoContent -- delete a user

921+ :<|> ReqBody '[JSON] User :> PutNoContent -- update a user

922+ :<|> DeleteNoContent -- delete a user

923923 )

924924

925925usersServer :: Server UsersAPI

@@ -948,11 +948,11 @@ usersServer = getUsers :<|> newUser :<|> userOperations

948948``` haskell

949949type ProductsAPI =

950950 Get '[JSON] [Product] -- list products

951− :<|> ReqBody '[JSON] Product :> PostNoContent '[JSON] NoContent -- add a product

951+ :<|> ReqBody '[JSON] Product :> PostNoContent -- add a product

952952 :<|> Capture "productid" Int :>

953953 ( Get '[JSON] Product -- view a product

954− :<|> ReqBody '[JSON] Product :> PutNoContent '[JSON] NoContent -- update a product

955− :<|> DeleteNoContent '[JSON] NoContent -- delete a product

954+ :<|> ReqBody '[JSON] Product :> PutNoContent -- update a product

955+ :<|> DeleteNoContent -- delete a product

956956 )

957957

958958data Product = Product { productId :: Int }

@@ -996,11 +996,11 @@ abstract that away:

996996-- indexed by values of type 'i'

997997type APIFor a i =

998998 Get '[JSON] [a] -- list 'a's

999− :<|> ReqBody '[JSON] a :> PostNoContent '[JSON] NoContent -- add an 'a'

999+ :<|> ReqBody '[JSON] a :> PostNoContent -- add an 'a'

10001000 :<|> Capture "id" i :>

10011001 ( Get '[JSON] a -- view an 'a' given its "identifier" of type 'i'

1002− :<|> ReqBody '[JSON] a :> PutNoContent '[JSON] NoContent -- update an 'a'

1003− :<|> DeleteNoContent '[JSON] NoContent -- delete an 'a'

1002+ :<|> ReqBody '[JSON] a :> PutNoContent -- update an 'a'

1003+ :<|> DeleteNoContent -- delete an 'a'

10041004 )

10051005

10061006-- Build the appropriate 'Server'

@@ -1135,7 +1135,7 @@ true

11351135### An arrow is a reader too.

11361136

11371137In 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.

11391139

11401140One problematic situation was when the source monad was `(->) r`, yet it's

11411141handy 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

11661166a single content type, and also specify what framing strategy is used to

11671167delineate the results. To serve these results, we need to give back a stream

11681168producer. 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`

11701170stream type (it's simpler than *Pipes* or *Conduit*).

11711171The API of a streaming endpoint needs to explicitly specify which sort of

11721172generator 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

66Any comments, issues or feedback about the tutorial can be submitted

77to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.

88

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−

469.. toctree::

4710 :maxdepth: 1

4811

12+ install.rst

4913 ApiType.lhs

5014 Server.lhs

5115 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+7−12

@@ -1,3 +1,4 @@

1+cabal-version: 2.2

12name: tutorial

23version: 0.10

34synopsis: The servant tutorial

@@ -6,18 +7,14 @@ description:

67 <http://docs.servant.dev/>

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

89category: Servant, Documentation

9−license: BSD3

10+license: BSD-3-Clause

1011license-file: LICENSE

1112author: Servant Contributors

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

1314build-type: Simple

14−cabal-version: >=1.10

1515tested-with:

16− GHC==8.0.2

17− GHC==8.2.2

18− GHC==8.4.4

1916 GHC==8.6.5

20− GHC==8.8.1

17+ GHC==8.8.3, GHC ==8.10.7

2118extra-source-files:

2219 static/index.html

2320 static/ui.js

@@ -66,11 +63,11 @@ library

6663 blaze-html >= 0.9.0.1 && < 0.10

6764 , blaze-markup >= 0.8.0.0 && < 0.9

6865 , cookie >= 0.4.3 && < 0.5

69− , js-jquery >= 3.2.1 && < 3.3

70− , lucid >= 2.9.11 && < 2.10

71− , random >= 1.1 && < 1.2

66+ , js-jquery >= 3.3.1 && < 3.4

67+ , lucid >= 2.9.11 && < 2.12

68+ , random >= 1.1 && < 1.3

7269 , servant-js >= 0.9 && < 0.10

73− , time >= 1.6.0.1 && < 1.10

70+ , time >= 1.6.0.1 && < 1.13

7471

7572 -- For legacy tools, we need to specify build-depends too

7673 build-depends: markdown-unlit >= 0.5.0 && <0.6

@@ -83,8 +80,6 @@ test-suite spec

8380 hs-source-dirs: test

8481 main-is: Spec.hs

8582 other-modules: JavascriptSpec

86− build-tool-depends:

87− hspec-discover:hspec-discover

8883 build-depends: base

8984 , tutorial

9085 , 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:

2121``` sh

2222$ nix-shell nix/shell.nix --argstr compiler ghcHEAD

2323```

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"

32, tutorial ? false

3+, pkgs ? import ./nixpkgs.nix

44}:

5+

6+ with pkgs;

57

6−with pkgs;

7−

8−let

9− ghc = haskell.packages.${compiler}.ghcWithPackages (_: []);

10− docstuffs = python3.withPackages (ps: with ps; [ recommonmark sphinx sphinx_rtd_theme ]);

11−in

12−

13−stdenv.mkDerivation {

14− name = "servant-dev";

15− buildInputs = [ ghc zlib python3 wget ]

16− ++ (if tutorial then [docstuffs postgresql] else []);

17− shellHook = ''

18− eval $(grep export ${ghc}/bin/ghc)

19− export LD_LIBRARY_PATH="${zlib}/lib";

20− '';

21−}

8+ let

9+ ghc = haskell.packages.${compiler}.ghcWithPackages (_: []);

10+ docstuffs = python3.withPackages (ps: with ps; [ recommonmark sphinx sphinx_rtd_theme ]);

11+ in

12+ stdenv.mkDerivation {

13+ name = "servant-dev";

14+ buildInputs = [ ghc zlib python3 wget cabal-install postgresql openssl stack haskellPackages.hspec-discover ]

15+ ++ (if tutorial then [docstuffs postgresql] else []);

16+ shellHook = ''

17+ eval $(grep export ${ghc}/bin/ghc)

18+ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"${zlib}/lib";

19+ '';

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-jsaddle/LICENSE → servant-auth/servant-auth-client/LICENSErenamed+3−2

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

22

33All rights reserved.

44

@@ -13,7 +13,7 @@ modification, are permitted provided that the following conditions are met:

1313 disclaimer in the documentation and/or other materials provided

1414 with the distribution.

1515

16− * Neither the name of Zalora South East Asia Pte Ltd nor the names of other

16+ * Neither the name of Julian K. Arni nor the names of other

1717 contributors may be used to endorse or promote products derived

1818 from this software without specific prior written permission.

1919

@@ -28,3 +28,4 @@ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

2828THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

2929(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

3030OF 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.18

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.10 && < 0.11

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

@@ -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-docs/Setup.hsnew file+33

@@ -0,0 +1,33 @@

1+{-# LANGUAGE CPP #-}

2+{-# OPTIONS_GHC -Wall #-}

3+module Main (main) where

4+

5+#ifndef MIN_VERSION_cabal_doctest

6+#define MIN_VERSION_cabal_doctest(x,y,z) 0

7+#endif

8+

9+#if MIN_VERSION_cabal_doctest(1,0,0)

10+

11+import Distribution.Extra.Doctest ( defaultMainWithDoctests )

12+main :: IO ()

13+main = defaultMainWithDoctests "doctests"

14+

15+#else

16+

17+#ifdef MIN_VERSION_Cabal

18+-- If the macro is defined, we have new cabal-install,

19+-- but for some reason we don't have cabal-doctest in package-db

20+--

21+-- Probably we are running cabal sdist, when otherwise using new-build

22+-- workflow

23+#warning You are configuring this package without cabal-doctest installed. \

24+ The doctests test-suite will not work as a result. \

25+ To fix this, install cabal-doctest before configuring.

26+#endif

27+

28+import Distribution.Simple

29+

30+main :: IO ()

31+main = defaultMain

32+

33+#endif

servant-auth/servant-auth-docs/servant-auth-docs.cabalnew file+84

@@ -0,0 +1,84 @@

1+cabal-version: 2.2

2+name: servant-auth-docs

3+version: 0.2.10.0

4+synopsis: servant-docs/servant-auth compatibility

5+description: This package provides instances that allow generating docs 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: Custom

21+extra-source-files:

22+ CHANGELOG.md

23+

24+custom-setup

25+ setup-depends:

26+ base, Cabal, cabal-doctest >=1.0.6 && <1.1

27+

28+source-repository head

29+ type: git

30+ location: https://github.com/haskell-servant/servant

31+

32+library

33+ hs-source-dirs:

34+ src

35+ default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

36+ ghc-options: -Wall

37+ build-depends:

38+ base >= 4.10 && < 4.18

39+ , servant-docs >= 0.11.2 && < 0.13

40+ , servant >= 0.13 && < 0.20

41+ , servant-auth == 0.4.*

42+ , lens >= 4.16.1 && <5.3

43+ exposed-modules:

44+ Servant.Auth.Docs

45+ default-language: Haskell2010

46+

47+test-suite doctests

48+ type: exitcode-stdio-1.0

49+ main-is: doctests.hs

50+ build-depends:

51+ base,

52+ servant-auth-docs,

53+ doctest >= 0.16 && < 0.21,

54+ QuickCheck >= 2.11.3 && < 2.15,

55+ template-haskell

56+ ghc-options: -Wall -threaded

57+ hs-source-dirs: test

58+ default-language: Haskell2010

59+

60+test-suite spec

61+ type: exitcode-stdio-1.0

62+ main-is: Spec.hs

63+ hs-source-dirs:

64+ test

65+ default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

66+ ghc-options: -Wall

67+ build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.10

68+

69+ -- dependencies with bounds inherited from the library stanza

70+ build-depends:

71+ base

72+ , text

73+ , servant-docs

74+ , servant

75+ , servant-auth

76+ , lens

77+

78+ -- test dependencies

79+ build-depends:

80+ servant-auth-docs

81+ , hspec >= 2.5.5 && < 2.10

82+ , QuickCheck >= 2.11.3 && < 2.15

83+

84+ default-language: Haskell2010

servant-auth/servant-auth-docs/src/Servant/Auth/Docs.hsnew file+96

@@ -0,0 +1,96 @@

1+{-# OPTIONS_GHC -fno-warn-orphans #-}

2+module Servant.Auth.Docs

3+ (

4+ -- | The purpose of this package is provide the instance for 'servant-auth'

5+ -- combinators needed for 'servant-docs' documentation generation.

6+ --

7+ -- >>> type API = Auth '[JWT, Cookie, BasicAuth] Int :> Get '[JSON] Int

8+ -- >>> putStr $ markdown $ docs (Proxy :: Proxy API)

9+ -- ## GET /

10+ -- ...

11+ -- ... Authentication

12+ -- ...

13+ -- This part of the API is protected by the following authentication mechanisms:

14+ -- ...

15+ -- * JSON Web Tokens ([JWTs](https://en.wikipedia.org/wiki/JSON_Web_Token))

16+ -- * [Cookies](https://en.wikipedia.org/wiki/HTTP_cookie)

17+ -- * [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)

18+ -- ...

19+ -- Clients must supply the following data

20+ -- ...

21+ -- One of the following:

22+ -- ...

23+ -- * A JWT Token signed with this server's key

24+ -- * Cookies automatically set by browsers, plus a header

25+ -- * Cookies automatically set by browsers, plus a header

26+ -- ...

27+

28+ -- * Re-export

29+ JWT

30+ , BasicAuth

31+ , Cookie

32+ , Auth

33+ ) where

34+

35+import Control.Lens ((%~), (&), (|>))

36+import Data.List (intercalate)

37+import Data.Monoid

38+import Data.Proxy (Proxy (Proxy))

39+import Servant.API hiding (BasicAuth)

40+import Servant.Auth

41+import Servant.Docs hiding (pretty)

42+import Servant.Docs.Internal (DocAuthentication (..), authInfo)

43+

44+instance (AllDocs auths, HasDocs api) => HasDocs (Auth auths r :> api) where

45+ docsFor _ (endpoint, action) =

46+ docsFor (Proxy :: Proxy api) (endpoint, action & authInfo %~ (|> info))

47+ where

48+ (intro, reqData) = pretty $ allDocs (Proxy :: Proxy auths)

49+ info = DocAuthentication intro reqData

50+

51+

52+pretty :: [(String, String)] -> (String, String)

53+pretty [] = error "shouldn't happen"

54+pretty [(i, d)] =

55+ ( "This part of the API is protected by " <> i

56+ , d

57+ )

58+pretty rs =

59+ ( "This part of the API is protected by the following authentication mechanisms:\n\n"

60+ ++ " * " <> intercalate "\n * " (fst <$> rs)

61+ , "\nOne of the following:\n\n"

62+ ++ " * " <> intercalate "\n * " (snd <$> rs)

63+ )

64+

65+

66+class AllDocs (x :: [*]) where

67+ allDocs :: proxy x

68+ -- intro, req

69+ -> [(String, String)]

70+

71+instance (OneDoc a, AllDocs as) => AllDocs (a ': as) where

72+ allDocs _ = oneDoc (Proxy :: Proxy a) : allDocs (Proxy :: Proxy as)

73+

74+instance AllDocs '[] where

75+ allDocs _ = []

76+

77+class OneDoc a where

78+ oneDoc :: proxy a -> (String, String)

79+

80+instance OneDoc JWT where

81+ oneDoc _ =

82+ ("JSON Web Tokens ([JWTs](https://en.wikipedia.org/wiki/JSON_Web_Token))"

83+ , "A JWT Token signed with this server's key")

84+

85+instance OneDoc Cookie where

86+ oneDoc _ =

87+ ("[Cookies](https://en.wikipedia.org/wiki/HTTP_cookie)"

88+ , "Cookies automatically set by browsers, plus a header")

89+

90+instance OneDoc BasicAuth where

91+ oneDoc _ =

92+ ( "[Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)"

93+ , "Cookies automatically set by browsers, plus a header")

94+

95+-- $setup

96+-- >>> instance ToSample Int where toSamples _ = singleSample 1729

servant-auth/servant-auth-docs/test/Spec.hsnew file+1

@@ -0,0 +1 @@

1+{-# OPTIONS_GHC -F -pgmF hspec-discover #-}

servant-auth/servant-auth-docs/test/doctests.hsnew file+12

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

1+module Main where

2+

3+import Build_doctests (flags, pkgs, module_sources)

4+import Data.Foldable (traverse_)

5+import Test.DocTest

6+

7+main :: IO ()

8+main = do

9+ traverse_ putStrLn args

10+ doctest args

11+ where

12+ args = flags ++ pkgs ++ module_sources

servant-auth/servant-auth-server/.ghcinew file+1

@@ -0,0 +1 @@

1+:set -isrc -itest -idoctest/ghci-wrapper/src

servant-auth/servant-auth-server/CHANGELOG.mdnew file+130

@@ -0,0 +1,130 @@

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.6.0] - 2020-10-06

11+

12+## Changed

13+

14+- expose verifyJWT and use it in two places [@domenkozar]

15+- support GHC 8.10 [@domenkozar]

16+- move ToJWT/FromJWT to servant-auth [@erewok]

17+- #165 fix AnySite with Cookie 3.5.0 [@odr]

18+

19+## [0.4.5.1] - 2020-02-06

20+

21+## Changed

22+

23+- #158 servant 0.17 support [@phadej]

24+

25+## [0.4.5.0] - 2019-12-28

26+

27+## Changed

28+- #144 servant 0.16 support and drop GHC 7.10 support [@domenkozar]

29+- #148 removed unused constaint in HasServer instance for Auth

30+- #154 GHC 8.8 support [@phadej]

31+

32+### Added

33+- #141 Support Stream combinator [@domenkozar]

34+- #143 Allow servant-0.16 [@phadej]

35+

36+## [0.4.4.0] - 2019-03-02

37+

38+### Added

39+- #141 Support Stream combinator [@domenkozar]

40+- #143 Allow servant-0.16 [@phadej]

41+

42+## [0.4.3.0] - 2019-01-17

43+

44+## Changed

45+- #117 Avoid running auth checks unnecessarily [@sopvop]

46+- #110 Get rid of crypto-api dependency [@domenkozar]

47+- #130 clearSession: improve cross-browser compatibility [@domenkozar]

48+- #136 weed out bytestring-conversion [@stephenirl]

49+

50+## [0.4.2.0] - 2018-11-05

51+

52+### Added

53+- `Headers hs a` instance for AddSetCookieApi [@domenkozar]

54+- GHC 8.6.x support [@domenkozar]

55+

56+## [0.4.1.0] - 2018-10-05

57+

58+### Added

59+- #125 Allow setting domain name for a cookie [@domenkozar]

60+

61+## Changed

62+- bump http-api-data to 0.3.10 that includes Cookie orphan instances previously located in servant-auth-server [@phadej]

63+- #114 Export `HasSecurity` typeclass [@rockbmb]

64+

65+## [0.4.0.1] - 2018-09-23

66+

67+### Security

68+- #123 Session cookie did not apply SameSite attribute [@domenkozar]

69+

70+### Added

71+- #112 HasLink instance for Auth combinator [@adetokunbo]

72+- #111 Documentation for using hoistServer [@mschristiansen]

73+- #107 Add utility functions for reading and writing a key to a file [@mschristiansen]

74+

75+## [0.4.0.0] - 2018-06-17

76+

77+### Added

78+- Support GHC 8.4 by @phadej and @domenkozar

79+- Support for servant-0.14 by @phadej

80+- #96 Support for jose-0.7 by @xaviershay

81+- #92 add `clearSession` for logout by @plredmond and @3noch

82+- #95 makeJWT: allow setting Alg via defaultJWTSettings by @domenkozar

83+- #89 Validate JWT against a JWKSet instead of JWK by @sopvop

84+

85+### Changed

86+- #92 Rename CSRF to XSRF by @plredmond and @3noch

87+- #92 extract 'XsrfCookieSettings' from 'CookieSettings' and make XSRF checking optional

88+ by @plredmond and @3noch

89+- #69 export SameSite by @domenkozar

90+- #102 Reuse Servant.Api.IsSecure instead of duplicating ADT by @domenkozar

91+

92+### Deprecated

93+- #92 Renamed 'makeCsrfCookie' to 'makeXsrfCookie' and marked the former as deprecated

94+ by @plredmond and @3noc

95+- #92 Made several changes to the structure of 'CookieSettings' which will require

96+ attention by users who have modified the XSRF settings by @plredmond and @3noch

97+

98+### Security

99+- #94 Force cookie expiration on serverside by @karshan

100+

101+## [0.3.2.0] - 2018-02-21

102+

103+### Added

104+- #76 Export wwwAuthenticatedErr and elaborate its annotation by @defanor

105+- Support for servant-0.14 by @phadej

106+

107+### Changed

108+- Disable the readme executable for ghcjs builds by @hamishmack

109+- #84 Make AddSetCookieApi type family open by @qnikst

110+- #79 Make CSRF checks optional for GET requests by @harendra-kumar

111+

112+## [0.3.1.0] - 2017-11-08

113+

114+### Added

115+- Support for servant-0.12 by @phadej

116+

117+## [0.3.0.0] - 2017-11-07

118+

119+### Changed

120+- #47 'cookiePath' and 'xsrfCookiePath' added to 'CookieSettings' by @mchaver

121+

122+## [0.2.8.0] - 2017-05-26

123+

124+### Added

125+- #45 Support for servant-0.11 by @phadej

126+

127+## [0.2.7.0] - 2017-02-11

128+

129+### Changed

130+- #27 #41 'acceptLogin' and 'makeCsrfCookie' functions by @bts

servant-auth/servant-auth-server/LICENSEnew file+31