add https recipe, add (future) github links at the end of all recipes

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
 

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.

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

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

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

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

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

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

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

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

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