HTTPurple 🪁
A
Coming from HTTPure? You might want to have a look at the differences to HTTPure.
ToC
Installation
spago install httpurpleQuick start
module Main where
import Prelude hiding ((/))
import Data.Generic.Rep (class Generic)
import HTTPurple (ServerM, ok, serve)
import Routing.Duplex (RouteDuplex', root, segment)
import Routing.Duplex.Generic (sum)
import Routing.Duplex.Generic.Syntax ((/))
data Route = Hello String
derive instance Generic Route _
route :: RouteDuplex' Route
route = root $ sum
{ "Hello": "hello" / segment
}
main :: ServerM
main =
serve { port: 8080 } { route, router }
where
router { route: Hello name } = ok $ "hello " <> namethen start the server
➜ spago run
Src Lib All
Warnings 0 0 0
Errors 0 0 0
[info] Build succeeded.
HTTPurple 🪁 up and running on http://0.0.0.0:8080query your server, e.g. using httpie
➜ http http://localhost:8080/hello/🗺
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 10
Date: Sun, 22 May 2022 16:50:52 GMT
Keep-Alive: timeout=5
hello 🗺Documentation
See the docs folder for more in-depth guides.
Examples
HTTPurple ships with a number of examples. To run an example, in the project root, run:
spago -x test.dhall run --main Examples.<Example Name>.MainEach example's startup banner will include information on routes available on the example server.
Testing
To run the test suite, in the project root run:
spago -x test.dhall testDifferences to HTTPure
HTTPurple
If you have used HTTPure before, you'll probably want to go through the following changes to get started using HTTPurple
Routing-duplex
The most notable difference to HTTPure is that HTTPurple routing-duplex library for routing. I found the previous lookup-based routing tedious to work with, especially when having more complex routes, and quite error-prone, especially if you need reverse-routing for redirects.
routing-duplex offers an elegant bidirectional routing which was initially designed for SPAs. Have a look at the really extensive documentation. The benefits of using routing-duplex are
- Much simpler and less tedious definition of routes
- Roundtrip printing/parsing of routes, so no more invalid redirects
- Exhaustive pattern matching so you are sure to match all defined routes
- Option to separate routes into logical groups
Here is a bit more elaborated examples:
module Main where
import Prelude hiding ((/))
import Data.Either (Either(..))
import Data.Generic.Rep (class Generic)
import Data.Maybe (Maybe(..))
import Data.Tuple (Tuple(..))
import HTTPurple (ServerM, found', headers, ok, serve)
import Routing.Duplex (RouteDuplex', as, optional, print, root, segment, string)
import Routing.Duplex.Generic as G
import Routing.Duplex.Generic.Syntax ((/), (?))
data Route
= Home
| Profile String
| Account String
| Search { q :: String, sorting :: Maybe Sort }
derive instance Generic Route _
data Sort = Asc | Desc
derive instance Generic Sort _
sortToString :: Sort -> String
sortToString = case _ of
Asc -> "asc"
Desc -> "desc"
sortFromString :: String -> Either String Sort
sortFromString = case _ of
"asc" -> Right Asc
"desc" -> Right Desc
val -> Left $ "Not a sort: " <> val
sort :: RouteDuplex' String -> RouteDuplex' Sort
sort = as sortToString sortFromString
api :: RouteDuplex' Route
api = root $ G.sum
{ "Home": G.noArgs
, "Profile": "profile" / string segment
, "Account": "account" / string segment
, "Search": "search" ? { q: string, sorting: optional <<< sort }
}
main :: ServerM
main = serve { port: 8080 } { route: api, router: apiRouter }
where
apiRouter { route: Home } = ok "hello world!"
apiRouter { route: (Profile profile) } = ok $ "hello " <> profile <> "!"
apiRouter { route: (Account account) } = found' redirect ""
where
redirect = headers [ Tuple "Location" $ print api $ Profile account ]
apiRouter { route: (Search { q, sorting }) } = ok $ "searching for query " <> q <> " " <> case sorting of
Just Asc -> "ascending"
Just Desc -> "descending"
Nothing -> "defaulting to ascending"Startup options
HTTPurple serve, serve', serveSecure and serveSecure' have been merged into a single function serve that accepts listen options as the first parameter and uses sane defaults if you don't provide any.
The easiest way to start a server is to provide just the route and a router:
main :: ServerM
main =
serve {} { route, router }This will spin up the http server with sane defaults.
HTTPurple 🪁 up and running on http://0.0.0.0:8080But you can overwrite any of the optional properties like this
main :: ServerM
main =
serve {
hostname: "localhost"
, port: 9000
, certFile: "./Certificate.cer"
, keyFile: "./Key.key"
, notFoundHandler
, onStarted: log "Server started 🚀"
, closingHandler: NoClosingHandler
} { route, router }
where
notFoundHandler :: Request Unit -> ResponseM
notFoundHandler = const $ ok "Nothing to see here"Other improvmenets
- Default closing handler - A default closing handler is provided so you can just stop your server using
ctrl+xwithout having to worry about anything. You can deactivate it by settingclosingHandler: NoClosingHandlerin the listen options.
Hot module reloading
With HTTPurple
Create an index.js with the content:
import * as Main from './output/Main/index.js'
Main.main()Add to package.json:
...
"scripts": {
"hot": "spago build -w & nodemon \"node index.js\""
},
"type": "module",
...Spin up:
npm run hotDevelop:
HTTPurple 🪁 up and running on http://0.0.0.0:8080
[nodemon] restarting due to changes...
[nodemon] restarting due to changes...
[nodemon] starting `node "node index.js" index.js`
HTTPurple 🪁 up and running on http://0.0.0.0:8080
[nodemon] restarting due to changes...
[nodemon] restarting due to changes...
[nodemon] starting `node "node index.js" index.js`
HTTPurple 🪁 up and running on http://0.0.0.0:8080License
This is a fork of HTTPure, which is licensed under MIT. See the original license. This work is similarly licensed under MIT.
