6 | 10 | Type-safe, statically checked composition of HTTP servers 11 |
12 | 13 |14 | Getting Started 15 | | Documentation 16 | | FAQ 17 | | Examples 18 |
19 | 20 |
30 | 
31 |
32 |
33 |
33 | 35 | The page you are looking for is not here. It might have been relocated, 36 | so please go back to the documentation index, and find 38 | your way from there. 39 |
40 |
91 | 93 | Type-safe, statically checked composition of HTTP servers 94 |
95 |96 | Hyper is an experimental middleware architecture for HTTP servers written in 97 | PureScript. Its main focus is correctness and type-safety, using type-level 98 | information to enforce correct composition and abstraction for web servers. 99 | The Hyper project is also a breeding ground for higher-level web server 100 | constructs, which tend to fall under the “framework” category. 101 |
102 |104 | Choose a version and a format of the documentation below, or just grab the latest. 106 |
107 | 108 || Version | Formats |
|---|
Redirecting to latest release of Hyper, at ${url}...
18 | 21 | 22 | " 23 | -------------------------------------------------------------------------------- /docs/bin/sort_by_semver.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | 3 | import fileinput 4 | import semver 5 | 6 | 7 | def cmp_semver(a, b): 8 | try: 9 | return semver.compare(a, b) 10 | except: 11 | return cmp(a, b) 12 | 13 | 14 | def sort_versions(versions): return sorted(versions, cmp=cmp_semver, 15 | reverse=True) 16 | 17 | 18 | def main(): 19 | versions = map(lambda line: line.strip(), list(fileinput.input())) 20 | sorted_versions = sort_versions(versions) 21 | for version in sorted_versions: 22 | print(version) 23 | 24 | 25 | if __name__ == '__main__': 26 | main() 27 | -------------------------------------------------------------------------------- /docs/make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | REM Command file for Sphinx documentation 4 | 5 | if "%SPHINXBUILD%" == "" ( 6 | set SPHINXBUILD=sphinx-build 7 | ) 8 | set BUILDDIR=build 9 | set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source 10 | set I18NSPHINXOPTS=%SPHINXOPTS% source 11 | if NOT "%PAPER%" == "" ( 12 | set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% 13 | set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% 14 | ) 15 | 16 | if "%1" == "" goto help 17 | 18 | if "%1" == "help" ( 19 | :help 20 | echo.Please use `make ^ }}){kind=small}
52 |
53 | 113 | PDF 114 |
115 |27 | {% trans %}Please activate JavaScript to enable the search 28 | functionality.{% endtrans %} 29 |
30 |32 | {% trans %}From here you can search these documents. Enter your search 33 | words into the box below and click "search". Note that the search 34 | function will automatically search for all of the words. Pages 35 | containing fewer words won't appear in the result list.{% endtrans %} 36 |
37 | 38 | 45 | 46 | {% if search_performed %} 47 |{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}
50 | {% endif %} 51 | {% endif %} 52 |12 | From here you can search these documents. Enter your search 13 | words into the box below and click "search". 14 |
15 | 16 | 21 | 22 | {%- if search_performed %} 23 |Your search did not match any results.
26 | {%- endif %} 27 | {%- endif %} 28 |If this is green, then it is definitely working.
11 | 12 | 13 | -------------------------------------------------------------------------------- /examples/FormParser.purs: -------------------------------------------------------------------------------- 1 | module Examples.FormParser where 2 | 3 | import Prelude 4 | import Text.Smolder.HTML.Attributes as A 5 | import Control.Monad.Indexed.Qualified as Ix 6 | import Control.Monad.Indexed ((:>>=), (:*>)) 7 | import Effect (Effect) 8 | import Effect.Class (liftEffect) 9 | import Effect.Console (log) 10 | import Data.Either (Either(Right, Left)) 11 | import Data.HTTP.Method (Method(..)) 12 | import Data.Maybe (Maybe(Nothing, Just)) 13 | import Data.MediaType.Common (textHTML) 14 | import Data.String (length) 15 | import Hyper.Form (parseForm, required) 16 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer) 17 | import Hyper.Request (getRequestData) 18 | import Hyper.Response (closeHeaders, contentType, respond, writeStatus) 19 | import Hyper.Status (statusBadRequest, statusMethodNotAllowed, statusOK) 20 | import Text.Smolder.HTML (button, form, input, label, p) 21 | import Text.Smolder.Markup (text, (!)) 22 | import Text.Smolder.Renderer.String (render) 23 | 24 | main :: Effect Unit 25 | main = 26 | let 27 | -- A view function that renders the name form. 28 | renderNameForm err = do 29 | form ! A.method "post" $ do 30 | formattedError 31 | formElements 32 | where 33 | formElements = do 34 | label ! A.for "firstName" $ text "Your Name:" 35 | p (input ! A.name "firstName" ! A.id "firstName") 36 | p (button (text "Send")) 37 | 38 | formattedError = 39 | case err of 40 | Just s -> p ! A.style "color: red;" $ text s 41 | Nothing -> pure unit 42 | 43 | htmlWithStatus status x = Ix.do 44 | writeStatus status 45 | contentType textHTML 46 | closeHeaders 47 | respond (render x) 48 | 49 | handlePost = 50 | parseForm :>>= 51 | case _ of 52 | Left err -> do 53 | liftEffect (log err) 54 | :*> htmlWithStatus 55 | statusBadRequest 56 | (p (text "Bad request, invalid form.")) 57 | Right form -> 58 | case required "firstName" form of 59 | Right name 60 | | length name > 0 -> 61 | htmlWithStatus 62 | statusOK 63 | (p (text ("Hi " <> name <> "!"))) 64 | | otherwise -> 65 | htmlWithStatus 66 | statusBadRequest 67 | (renderNameForm (Just "Name cannot be empty.")) 68 | Left err -> 69 | htmlWithStatus 70 | statusBadRequest 71 | (renderNameForm (Just err)) 72 | 73 | -- Our (rather primitive) router. 74 | router = 75 | _.method <$> getRequestData :>>= 76 | case _ of 77 | Left GET -> 78 | htmlWithStatus 79 | statusOK 80 | (renderNameForm Nothing) 81 | Left POST -> 82 | handlePost 83 | method -> 84 | htmlWithStatus 85 | statusMethodNotAllowed 86 | (text ("Method not supported: " <> show method)) 87 | 88 | -- Let's run it. 89 | in runServer defaultOptionsWithLogging {} router 90 | -------------------------------------------------------------------------------- /examples/HelloHyper.purs: -------------------------------------------------------------------------------- 1 | module Examples.HelloHyper where 2 | 3 | import Prelude 4 | import Control.Monad.Indexed.Qualified as Ix 5 | import Effect (Effect) 6 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer) 7 | import Hyper.Response (closeHeaders, respond, writeStatus) 8 | import Hyper.Status (statusOK) 9 | 10 | main :: Effect Unit 11 | main = 12 | let app = Ix.do 13 | writeStatus statusOK 14 | closeHeaders 15 | respond "Hello, Hyper!" 16 | in runServer defaultOptionsWithLogging {} app 17 | -------------------------------------------------------------------------------- /examples/NodeStreamRequest.purs: -------------------------------------------------------------------------------- 1 | -- This example shows how you can stream request body data. It 2 | -- logs the size of each chunk it receives from the POST body. 3 | -- 4 | -- Test it out by first running the server, 5 | -- 6 | -- $ pulp run -I examples -m Examples.NodeStreamRequest 7 | -- 8 | -- and then, POST a large file with something like this command: 9 | -- 10 | -- $ curl -X POST --data-binary @/your/large/file localhost:3000 11 | -- 12 | module Examples.NodeStreamRequest where 13 | 14 | import Prelude 15 | import Node.Buffer as Buffer 16 | import Node.Stream as Stream 17 | import Control.Monad.Indexed.Qualified as Ix 18 | import Control.Monad.Indexed ((:>>=)) 19 | import Effect (Effect) 20 | import Effect.Class (class MonadEffect, liftEffect) 21 | import Effect.Console (log) 22 | import Effect.Exception (catchException, message) 23 | import Data.Either (Either(..), either) 24 | import Data.HTTP.Method (Method(..)) 25 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer) 26 | import Hyper.Request (getRequestData, streamBody) 27 | import Hyper.Response (closeHeaders, respond, writeStatus) 28 | import Hyper.Status (statusMethodNotAllowed, statusOK) 29 | 30 | logRequestBodyChunks 31 | :: forall m 32 | . MonadEffect m 33 | => Stream.Readable () 34 | -> m Unit 35 | logRequestBodyChunks body = 36 | Stream.onData body (Buffer.size >=> (log <<< ("Got chunk of size: " <> _) <<< show)) 37 | # catchException (log <<< ("Error: " <> _) <<< message) 38 | # liftEffect 39 | 40 | main :: Effect Unit 41 | main = 42 | let 43 | app = 44 | getRequestData :>>= 45 | case _ of 46 | 47 | -- Only handle POST requests: 48 | { method: Left POST } -> Ix.do 49 | body <- streamBody 50 | logRequestBodyChunks body 51 | writeStatus statusOK 52 | closeHeaders 53 | respond "OK" 54 | 55 | -- Non-POST requests are not allowed: 56 | { method } -> Ix.do 57 | writeStatus statusMethodNotAllowed 58 | closeHeaders 59 | respond ("Method not allowed: " <> either show show method) 60 | 61 | in runServer defaultOptionsWithLogging {} app 62 | -------------------------------------------------------------------------------- /examples/NodeStreamResponse.purs: -------------------------------------------------------------------------------- 1 | -- This example shows how you can stream responses asynchronously. 2 | -- 3 | -- Test it out like so: 4 | -- $ curl -N http://localhost:3000 5 | module Examples.NodeStreamResponse where 6 | 7 | import Prelude 8 | import Control.Monad.Indexed.Qualified as Ix 9 | import Control.Monad.Indexed ((:*>)) 10 | import Effect.Aff as Aff 11 | import Effect.Aff.Class (class MonadAff, liftAff) 12 | import Effect (Effect) 13 | import Data.Int (toNumber) 14 | import Data.Newtype (wrap) 15 | import Data.Traversable (traverse_) 16 | import Data.Tuple (Tuple(..)) 17 | import Hyper.Middleware (Middleware, lift') 18 | import Hyper.Node.Server (defaultOptions, runServer, writeString) 19 | import Hyper.Response (closeHeaders, end, send, writeStatus) 20 | import Hyper.Status (statusOK) 21 | import Node.Encoding (Encoding(..)) 22 | 23 | delay :: forall m c. MonadAff m => Int -> Middleware m c c Unit 24 | delay n = lift' (liftAff (Aff.delay (wrap <<< toNumber $ n) *> pure unit)) 25 | 26 | main :: Effect Unit 27 | main = 28 | let 29 | -- These messages are streamed one at a time, regardless of their individual 30 | -- delays, i.e. they're sequenced. 31 | streamMessages = 32 | traverse_ 33 | (\(Tuple ms s) -> delay ms :*> send (writeString UTF8 s)) 34 | [ Tuple 2000 "Hello\n" 35 | , Tuple 1000 "Streaming\n" 36 | , Tuple 500 "Hyper\n" 37 | ] 38 | 39 | app = Ix.do 40 | writeStatus statusOK 41 | closeHeaders 42 | streamMessages 43 | end 44 | in runServer defaultOptions {} app 45 | -------------------------------------------------------------------------------- /examples/QualifiedDo.purs: -------------------------------------------------------------------------------- 1 | module Examples.QualifiedDo where 2 | 3 | import Prelude 4 | import Effect (Effect) 5 | import Control.Monad.Indexed.Qualified as Ix 6 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer) 7 | import Hyper.Response (closeHeaders, respond, writeStatus) 8 | import Hyper.Status (statusOK) 9 | 10 | main :: Effect Unit 11 | main = runServer defaultOptionsWithLogging {} Ix.do 12 | writeStatus statusOK 13 | closeHeaders 14 | respond "Hello, Hyper!" 15 | -------------------------------------------------------------------------------- /examples/Sessions.purs: -------------------------------------------------------------------------------- 1 | module Examples.Sessions where 2 | 3 | import Prelude 4 | import Control.Monad.Indexed.Qualified as Ix 5 | import Control.Monad.Indexed ((:>>=)) 6 | import Effect.Aff (launchAff) 7 | import Effect (Effect) 8 | import Effect.Class (liftEffect) 9 | import Effect.Class.Console (log) 10 | import Data.Maybe (Maybe(..)) 11 | import Data.MediaType.Common (textHTML) 12 | import Hyper.Cookies (cookies) 13 | import Hyper.Middleware (lift') 14 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer) 15 | import Hyper.Node.Session.InMemory (newInMemorySessionStore) 16 | import Hyper.Request (getRequestData) 17 | import Hyper.Response (closeHeaders, contentType, end, redirect, respond, writeStatus) 18 | import Hyper.Session (deleteSession, getSession, saveSession) 19 | import Hyper.Status (statusNotFound, statusOK) 20 | 21 | newtype MySession = MySession { userId :: Int } 22 | 23 | main :: Effect Unit 24 | main = void $ launchAff do 25 | store <- liftEffect newInMemorySessionStore 26 | liftEffect (runServer defaultOptionsWithLogging (components store) app) 27 | where 28 | components store = 29 | { sessions: { key: "my-session" 30 | , store: store 31 | } 32 | , cookies: unit 33 | } 34 | 35 | home = Ix.do 36 | writeStatus statusOK 37 | contentType textHTML 38 | closeHeaders 39 | getSession :>>= 40 | case _ of 41 | Just (MySession { userId }) -> Ix.do 42 | lift' (log "Session") 43 | respond ("You are logged in as user " <> show userId <> ". " 44 | <> "Logout if you're anxious.") 45 | Nothing -> Ix.do 46 | lift' (log "No Session") 47 | respond "Login to start a session." 48 | 49 | login = Ix.do 50 | redirect "/" 51 | saveSession (MySession { userId: 1 }) 52 | contentType textHTML 53 | closeHeaders 54 | end 55 | 56 | logout = Ix.do 57 | redirect "/" 58 | deleteSession 59 | closeHeaders 60 | end 61 | 62 | notFound = Ix.do 63 | writeStatus statusNotFound 64 | contentType textHTML 65 | closeHeaders 66 | respond "Not Found" 67 | 68 | -- Simple router for this example. 69 | router = 70 | getRequestData :>>= \{ url } -> 71 | case url of 72 | "/" -> home 73 | "/login" -> login 74 | "/logout" -> logout 75 | _ -> notFound 76 | 77 | app = Ix.do 78 | cookies 79 | router 80 | -------------------------------------------------------------------------------- /examples/StateT.purs: -------------------------------------------------------------------------------- 1 | module Examples.StateT where 2 | 3 | import Prelude 4 | import Control.Monad.Indexed.Qualified as Ix 5 | import Effect.Aff (Aff) 6 | import Effect (Effect) 7 | import Control.Monad.State (evalStateT, get, modify) 8 | import Control.Monad.State.Trans (StateT) 9 | import Data.String (joinWith) 10 | import Hyper.Middleware (lift') 11 | import Hyper.Node.Server (defaultOptionsWithLogging, runServer') 12 | import Hyper.Response (closeHeaders, respond, writeStatus) 13 | import Hyper.Status (statusOK) 14 | 15 | 16 | runAppM ∷ ∀ a. StateT (Array String) Aff a → Aff a 17 | runAppM = flip evalStateT [] 18 | 19 | 20 | main :: Effect Unit 21 | main = 22 | let 23 | -- Our application just appends to the state in between 24 | -- some operations, then responds with the built up state... 25 | app = Ix.do 26 | void $ lift' (modify (flip append ["I"])) 27 | writeStatus statusOK 28 | void $ lift' (modify (flip append ["have"])) 29 | closeHeaders 30 | void $ lift' (modify (flip append ["state."])) 31 | 32 | msgs ← lift' get 33 | respond (joinWith " " msgs) 34 | 35 | in runServer' defaultOptionsWithLogging {} runAppM app 36 | -------------------------------------------------------------------------------- /github.css: -------------------------------------------------------------------------------- 1 | .hljs{display:block;overflow-x:auto;padding:0.5em;color:#333;background:#f8f8f8}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:bold}.hljs-number,.hljs-literal,.hljs-variable,.hljs-template-variable,.hljs-tag .hljs-attr{color:#008080}.hljs-string,.hljs-doctag{color:#d14}.hljs-title,.hljs-section,.hljs-selector-id{color:#900;font-weight:bold}.hljs-subst{font-weight:normal}.hljs-type,.hljs-class .hljs-title{color:#458;font-weight:bold}.hljs-tag,.hljs-name,.hljs-attribute{color:#000080;font-weight:normal}.hljs-regexp,.hljs-link{color:#009926}.hljs-symbol,.hljs-bullet{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:bold}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold} -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "purescript-hyper", 3 | "description": "Type-safe, statically checked composition of HTTP servers", 4 | "main": " ", 5 | "directories": { 6 | "doc": "docs", 7 | "test": "test" 8 | }, 9 | "scripts": { 10 | "test": "pulp test" 11 | }, 12 | "repository": { 13 | "type": "git", 14 | "url": "git+ssh://git@github.com/owickstrom/hyper.git" 15 | }, 16 | "author": "oskar.wickstrom@gmail.com", 17 | "license": "MPL-2.0", 18 | "homepage": "http://hyper.wickstrom.tech", 19 | "dependencies": { 20 | "bower-dependency-tree": "^0.1.2", 21 | "pulp": "^15.0.0" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /packages.dhall: -------------------------------------------------------------------------------- 1 | let upstream = 2 | https://github.com/purescript/package-sets/releases/download/psc-0.13.8-20200615/packages.dhall sha256:5d0cfad9408c84db0a3fdcea2d708f9ed8f64297e164dc57a7cf6328706df93a 3 | 4 | let overrides = {=} 5 | 6 | let additions = {=} 7 | 8 | in upstream // overrides // additions 9 | -------------------------------------------------------------------------------- /spago.dhall: -------------------------------------------------------------------------------- 1 | { sources = 2 | [ "src/**/*.purs", "test/**/*.purs" ] 3 | , name = 4 | "hyper" 5 | , dependencies = 6 | [ "aff" 7 | , "avar" 8 | , "argonaut" 9 | , "arrays" 10 | , "console" 11 | , "control" 12 | , "effect" 13 | , "foldable-traversable" 14 | , "generics-rep" 15 | , "http-methods" 16 | , "indexed-monad" 17 | , "media-types" 18 | , "node-buffer" 19 | , "node-fs-aff" 20 | , "node-http" 21 | , "ordered-collections" 22 | , "proxy" 23 | , "psci-support" 24 | , "random" 25 | , "smolder" 26 | , "spec" 27 | , "spec-discovery" 28 | , "strings" 29 | , "transformers" 30 | , "record-extra" 31 | ] 32 | , packages = 33 | ./packages.dhall 34 | } 35 | -------------------------------------------------------------------------------- /src/Hyper/Authentication.purs: -------------------------------------------------------------------------------- 1 | module Hyper.Authentication where 2 | 3 | import Hyper.Conn (Conn) 4 | 5 | setAuthentication :: forall a b req res c. 6 | b 7 | -> Conn req res { authentication :: a | c } 8 | -> Conn req res { authentication :: b | c } 9 | setAuthentication auth conn = 10 | conn { components { authentication = auth }} 11 | -------------------------------------------------------------------------------- /src/Hyper/Authorization.purs: -------------------------------------------------------------------------------- 1 | module Hyper.Authorization where 2 | 3 | import Control.Monad.Indexed.Qualified as Ix 4 | import Control.Monad (class Monad) 5 | import Data.Maybe (Maybe(Nothing, Just)) 6 | import Data.Unit (unit, Unit) 7 | import Hyper.Conn (Conn) 8 | import Hyper.Middleware (Middleware, lift') 9 | import Hyper.Middleware.Class (getConn, modifyConn) 10 | import Hyper.Response (class ResponseWritable, respond, headers, writeStatus, class Response, ResponseEnded, StatusLineOpen) 11 | import Hyper.Status (statusForbidden) 12 | 13 | withAuthorization :: forall a b req res c. 14 | b 15 | -> Conn req res { authorization :: a | c } 16 | -> Conn req res { authorization :: b | c } 17 | withAuthorization a conn = 18 | conn { components = (conn.components { authorization = a }) } 19 | 20 | 21 | authorized :: forall a m req res b c 22 | . Monad m 23 | => ResponseWritable b m String 24 | => Response res m b 25 | => (Conn req (res StatusLineOpen) { authorization :: Unit | c } -> m (Maybe a)) 26 | -> Middleware 27 | m 28 | (Conn req (res StatusLineOpen) { authorization :: a | c }) 29 | (Conn req (res ResponseEnded) { authorization :: a | c }) 30 | Unit 31 | -> Middleware 32 | m 33 | (Conn req (res StatusLineOpen) { authorization :: Unit | c }) 34 | (Conn req (res ResponseEnded) { authorization :: Unit | c }) 35 | Unit 36 | authorized authorizer mw = Ix.do 37 | conn ← getConn 38 | auth ← lift' (authorizer conn) 39 | case auth of 40 | Just a -> Ix.do 41 | modifyConn (withAuthorization a) 42 | mw 43 | modifyConn (withAuthorization unit) 44 | Nothing -> Ix.do 45 | writeStatus statusForbidden 46 | headers [] 47 | respond "You are not authorized." 48 | -------------------------------------------------------------------------------- /src/Hyper/Conn.purs: -------------------------------------------------------------------------------- 1 | module Hyper.Conn where 2 | 3 | -- | A `Conn` models the entirety of an HTTP connection, containing the fields 4 | -- | `request`, `response`, and the extensibility point `components`. 5 | type Conn req res components = 6 | { request :: req 7 | , response :: res 8 | , components :: components 9 | } 10 | -------------------------------------------------------------------------------- /src/Hyper/ContentNegotiation.purs: -------------------------------------------------------------------------------- 1 | -- This module implements, or aims to implement, Content Negotation, as 2 | -- described in