From c5f2b9e17534484a486299d0d721e162b9fa6bd0 Mon Sep 17 00:00:00 2001 From: Alp Mestanogullari Date: Fri, 8 Dec 2017 23:21:00 +0100 Subject: [PATCH] add https recipe, add (future) github links at the end of all recipes --- cabal.project | 1 + doc/cookbook/basic-auth/BasicAuth.lhs | 3 +- .../db-postgres-pool/PostgresPool.lhs | 3 +- .../db-sqlite-simple/DBConnection.lhs | 3 +- doc/cookbook/file-upload/FileUpload.lhs | 4 +- doc/cookbook/https/Https.lhs | 62 +++++++++++++++++++ doc/cookbook/https/https.cabal | 25 ++++++++ doc/cookbook/index.rst | 3 +- .../jwt-and-basic-auth/JWTAndBasicAuth.lhs | 3 + .../structuring-apis/StructuringApis.lhs | 5 +- .../structuring-apis/structuring-apis.cabal | 24 +++++++ 11 files changed, 128 insertions(+), 8 deletions(-) create mode 100644 doc/cookbook/https/Https.lhs create mode 100644 doc/cookbook/https/https.cabal create mode 100644 doc/cookbook/structuring-apis/structuring-apis.cabal diff --git a/cabal.project b/cabal.project index c5859865..dca91894 100644 --- a/cabal.project +++ b/cabal.project @@ -11,6 +11,7 @@ packages: servant/ doc/cookbook/jwt-and-basic-auth/ doc/cookbook/file-upload/ doc/cookbook/structuring-apis/ + doc/cookbook/https/ allow-newer: servant-js:servant-foreign diff --git a/doc/cookbook/basic-auth/BasicAuth.lhs b/doc/cookbook/basic-auth/BasicAuth.lhs index 436a784b..68b7bfd5 100644 --- a/doc/cookbook/basic-auth/BasicAuth.lhs +++ b/doc/cookbook/basic-auth/BasicAuth.lhs @@ -175,4 +175,5 @@ code and see what happens when you specify credentials that are not in the database. The entire program covered here is available as a literate Haskell file -[here](...), along with a `cabal` project. +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/basic-auth), +along with a `cabal` project. diff --git a/doc/cookbook/db-postgres-pool/PostgresPool.lhs b/doc/cookbook/db-postgres-pool/PostgresPool.lhs index 1464d60b..f5ac7d1f 100644 --- a/doc/cookbook/db-postgres-pool/PostgresPool.lhs +++ b/doc/cookbook/db-postgres-pool/PostgresPool.lhs @@ -139,4 +139,5 @@ You could alternatively have the handlers live in `ReaderT (Pool Connection)` and access the pool using e.g `ask`, but this would be more complicated than simply taking the pool as argument. -The entire source for this example is available [here](...). +The entire source for this example is available as a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/db-postgres-pool). diff --git a/doc/cookbook/db-sqlite-simple/DBConnection.lhs b/doc/cookbook/db-sqlite-simple/DBConnection.lhs index 5f0e25b4..2ae108eb 100644 --- a/doc/cookbook/db-sqlite-simple/DBConnection.lhs +++ b/doc/cookbook/db-sqlite-simple/DBConnection.lhs @@ -96,4 +96,5 @@ main = do This program prints `Right ["hello","world"]` the first time it is executed, `Right ["hello","world","hello","world"]` the second time and so on. -The entire source for this example is available [here](...). +The entire source for this example is available as a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/db-sqlite-simple). diff --git a/doc/cookbook/file-upload/FileUpload.lhs b/doc/cookbook/file-upload/FileUpload.lhs index 353803ef..13bf7f4b 100644 --- a/doc/cookbook/file-upload/FileUpload.lhs +++ b/doc/cookbook/file-upload/FileUpload.lhs @@ -183,5 +183,5 @@ See `CONTRIBUTING.md` Response {responseStatus = Status {statusCode = 200, statusMessage = "OK"}, responseVersion = HTTP/1.1, responseHeaders = [("Transfer-Encoding","chunked"),("Date","Fri, 08 Dec 2017 16:50:14 GMT"),("Server","Warp/3.2.13"),("Content-Type","application/json;charset=utf-8")], responseBody = "0", responseCookieJar = CJ {expose = []}, responseClose' = ResponseClose} ``` -As usual, the code for this recipe is available in a cabal -project [here](). +As usual, the code for this recipe is available in a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/file-upload). diff --git a/doc/cookbook/https/Https.lhs b/doc/cookbook/https/Https.lhs new file mode 100644 index 00000000..de188463 --- /dev/null +++ b/doc/cookbook/https/Https.lhs @@ -0,0 +1,62 @@ +# Serving web applications over HTTPS + +This short recipe shows how one can serve a servant application +over HTTPS, by simply using `warp-tls` instead of `warp` to provide +us a `run` function for running the `Application` that we get by +calling `serve`. + +As usual, we start by clearing our throat of a few language extensions +and imports. + +``` haskell +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE TypeOperators #-} +import Network.Wai +import Network.Wai.Handler.Warp +import Network.Wai.Handler.WarpTLS +import Servant +``` + +No need to work with a complicated API here, let's +make it as simple as it gets: + +``` haskell +type API = Get '[JSON] Int + +api :: Proxy API +api = Proxy + +server :: Server API +server = return 10 + +app :: Application +app = serve api server +``` + +It's now time to actually run the `Application`. +The [`warp-tls`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html) +package provides two functions for running an `Application`, called +[`runTLS`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLS) +and [`runTLSSocket`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLSSocket). +We will be using the first one. + +It takes two arguments, +[the TLS settings](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#t:TLSSettings) +(certificates, keys, ciphers, etc) +and [the warp settings](https://hackage.haskell.org/package/warp-3.2.12/docs/Network-Wai-Handler-Warp-Internal.html#t:Settings) +(port, logger, etc). + +We will be using very simple settings for this example but you are of +course invited to read the documentation for those types to find out +about all the knobs that you can play with. + +``` haskell +main :: IO () +main = runTLS tlsOpts warpOpts app + + where tlsOpts = tlsSettings "cert.pem" "secret-key.pem" + warpOpts = setPort 8080 defaultSettings +``` + +This program is available as a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/https). diff --git a/doc/cookbook/https/https.cabal b/doc/cookbook/https/https.cabal new file mode 100644 index 00000000..eb505c12 --- /dev/null +++ b/doc/cookbook/https/https.cabal @@ -0,0 +1,25 @@ +name: cookbook-https +version: 0.1 +synopsis: HTTPS cookbook example +homepage: http://haskell-servant.readthedocs.org/ +license: BSD3 +license-file: ../../../servant/LICENSE +author: Servant Contributors +maintainer: haskell-servant-maintainers@googlegroups.com +build-type: Simple +cabal-version: >=1.10 + +executable cookbook-https + if impl(ghc < 7.10.1) + buildable: False + main-is: Https.lhs + build-depends: base == 4.* + , servant + , servant-server + , wai + , warp + , warp-tls + , markdown-unlit >= 0.4 + default-language: Haskell2010 + ghc-options: -Wall -pgmL markdown-unlit + build-tool-depends: markdown-unlit:markdown-unlit diff --git a/doc/cookbook/index.rst b/doc/cookbook/index.rst index e9e469ad..d58e4842 100644 --- a/doc/cookbook/index.rst +++ b/doc/cookbook/index.rst @@ -17,9 +17,10 @@ you name it! .. toctree:: :maxdepth: 1 + structuring-apis/StructuringApis.lhs + https/Https.lhs db-sqlite-simple/DBConnection.lhs db-postgres-pool/PostgresPool.lhs basic-auth/BasicAuth.lhs jwt-and-basic-auth/JWTAndBasicAuth.lhs file-upload/FileUpload.lhs - structuring-apis/StructuringApis.lhs diff --git a/doc/cookbook/jwt-and-basic-auth/JWTAndBasicAuth.lhs b/doc/cookbook/jwt-and-basic-auth/JWTAndBasicAuth.lhs index 4a7841ac..92c0ec0b 100644 --- a/doc/cookbook/jwt-and-basic-auth/JWTAndBasicAuth.lhs +++ b/doc/cookbook/jwt-and-basic-auth/JWTAndBasicAuth.lhs @@ -247,3 +247,6 @@ curl -v -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJkYXQiOnsiYXVPcmdJRCI6M … < HTTP/1.1 200 OK ``` + +This program is available as a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/jwt-and-basic-auth). diff --git a/doc/cookbook/structuring-apis/StructuringApis.lhs b/doc/cookbook/structuring-apis/StructuringApis.lhs index 0a260bb3..da8c9278 100644 --- a/doc/cookbook/structuring-apis/StructuringApis.lhs +++ b/doc/cookbook/structuring-apis/StructuringApis.lhs @@ -60,7 +60,7 @@ an effect on the server for such an API, and its type in particular. While the server for `FactoringAPI'` would be made of a function of type `Int -> Maybe Int -> Handler Int` and a function of type `Int -> Handler Int` glued with `:<|>`, -a server for `Factoring` (without the `'`) reflects the +a server for `FactoringAPI` (without the `'`) reflects the "factorisation" and therefore, `Server FactoringAPI` is `Int -> (Maybe Int -> Handler Int :<|> Handler Int)`. That is, the server must be a function that takes an `Int` (the `Capture`) and @@ -191,4 +191,5 @@ main = run 8080 . serve api $ factoringServer :<|> userServer :<|> productServer ``` -This program is available as a cabal project [here](). +This program is available as a cabal project +[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/structuring-apis). diff --git a/doc/cookbook/structuring-apis/structuring-apis.cabal b/doc/cookbook/structuring-apis/structuring-apis.cabal new file mode 100644 index 00000000..4e35aa98 --- /dev/null +++ b/doc/cookbook/structuring-apis/structuring-apis.cabal @@ -0,0 +1,24 @@ +name: cookbook-structuring-apis +version: 0.1 +synopsis: Example that shows how APIs can be structured +homepage: http://haskell-servant.readthedocs.org/ +license: BSD3 +license-file: ../../../servant/LICENSE +author: Servant Contributors +maintainer: haskell-servant-maintainers@googlegroups.com +build-type: Simple +cabal-version: >=1.10 + +executable cookbook-structuring-apis + if impl(ghc < 7.10.1) + buildable: False + main-is: StructuringApis.lhs + build-depends: base == 4.* + , aeson + , servant + , servant-server + , warp + , markdown-unlit >= 0.4 + default-language: Haskell2010 + ghc-options: -Wall -pgmL markdown-unlit + build-tool-depends: markdown-unlit:markdown-unlit