purescript-axon

WIP

HTTP server library inspired by axum, allowing best-in-class expressive routing.

The main difference between this server library compared to others (eg. the wonderful httpurple) is the philosophy around routing.

The core abstraction is a Handler; any function with the type [...Request parts] -> m Response.

This allows each REST action to correspond to a single function, which declares its requirements in its type signature. This allows for a highly refactorable & composable application, as opposed to a hierarchical routing approach like routing-duplex.

For example, an endpoint GET /persons/:id/address would be modeled as:

getPersonAddress :: Get -> Path ("persons" / Int / "address") Int -> Aff Response
getPersonAddress _ (Path id) = ...

POST /persons accepting a json body:

type Person = { firstName :: String, lastName :: String, age :: Maybe Int }

postPerson :: Post -> Path "persons" Unit -> ContentType Json -> Json Person -> Aff Response
postPerson _ _ _ person = ...

Then these can be rolled up into a /persons resource with Handler.or:

persons :: Handler Aff Response
persons = getPerson `Handler.or` postPerson `Handler.or` deletePerson `Handler.or` getPersonAddress ...

Then run with:

Axon.serveNode {port: 10000, hostname: "0.0.0.0"} persons

Example

This example implements this REST interface in 36LoC:

GET /cheeses - Lists all cheeses (strings) known to server
POST /cheeses - Add a cheese to the cheese list
DELETE /cheeses/:cheese - Remove a cheese from the cheese list

module Main where

import Prelude

import Axon as Axon
import Axon.Request.Handler as Handler
import Axon.Request.Parts.Class (Delete, Get, Path(..), Post)
import Axon.Request.Parts.Path (type (/))
import Axon.Response (Response)
import Axon.Response.Construct (Json(..), toResponse)
import Axon.Response.Status as Status
import Data.Filterable (filter)
import Data.Foldable (elem)
import Data.Tuple.Nested ((/\))
import Effect (Effect)
import Effect.Aff (Aff, launchAff_, joinFiber)
import Effect.Aff as Aff
import Effect.Class (liftEffect)
import Effect.Ref (Ref)
import Effect.Ref as Ref

main :: Effect Unit
main = launchAff_ do
  cheeses :: Ref (Array String) <- liftEffect $ Ref.new
    [ "cheddar", "swiss", "gouda" ]

  let
    getCheeses :: Get -> Path "cheeses" _ -> Aff Response
    getCheeses _ _ = liftEffect do
      cheeses' <- Ref.read cheeses
      toResponse $ Status.ok /\ Json cheeses'

    deleteCheese :: Delete -> Path ("cheeses" / String) _ -> Aff Response
    deleteCheese _ (Path id) = liftEffect do
      cheeses' <- Ref.read cheeses
      if not $ elem id cheeses' then
        toResponse Status.notFound
      else
        Ref.modify_ (filter (_ /= id)) cheeses
        *> toResponse Status.accepted

    postCheese :: Post -> Path "cheeses" _ -> String -> Aff Response
    postCheese _ _ cheese =
      let
        tryInsert as
          | elem cheese as = { state: as, value: false }
          | otherwise = { state: as <> [ cheese ], value: true }
      in
        liftEffect
          $ Ref.modify' tryInsert cheeses
          >>= if _ then toResponse Status.accepted else toResponse Status.conflict

  handle <-
    Axon.serveBun
      { port: 8080, hostname: "localhost" }
      (getCheeses `Handler.or` postCheese `Handler.or` deleteCheese)

  joinFiber handle.join

Request Handlers

Request handler functions have any number of parameters that are RequestParts and return an Aff Response (or any MonadAff).

RequestParts

Request
- Always succeeds; provides the entire request
Combinators
- Unit
  - Always succeeds
- a /\ b
  - Tuple of a and b, where a and b are RequestParts.
- Maybe a
  - a must be RequestParts. If a can't be extracted, the handler will still succeed and this will be Nothing. If a was extracted, it's wrapped in Just.
- Either a b
  - a and b must be RequestParts. Succeeds if either a or b succeeds (preferring a). Fails if both fail.
Body
- String
  - succeeds when request has a non-empty body that is valid UTF-8
- Json a
  - succeeds when request has a String body (see above) that can be parsed into a using DecodeJson.
- Buffer
  - succeeds when request has a nonempty body.
- Stream
  - succeeds when request has a nonempty body.
Headers
- Header a
  - a must be TypedHeader from Axon.Header.Typed. Allows statically (ex. ContentType Type.MIME.Json) or dynamically (ex. ContentType String) matching request headers.
- HeaderMap
  - All headers provided in the request
Path
- Path a c
  - Statically match the path of the request, and extract parameters. See Axon.Request.Parts.Path. (TODO: this feels too magical, maybe follow axum's prior art of baking paths into the router declaration?)
Method - Get - Post - Put - Patch - Delete - Options - Connect - Trace

Similarly to the structural extraction of request parts; handlers can use Axon.Response.Construct.ToResponse for easily constructing responses.

ToResponse

Combinators
- Status /\ a
  - Special case to make sure any Status in a tuple will take priority over any default statuses within. TODO: This case (overlapping with a /\ b requires the class to be "sealed" in an instance chain. Want a clean way around this so consumers can implement ToResponse.)
- a /\ b
  - Merges toResponse a and toResponse b, using b on conflicts
Status
- Axon.Response.Status.Status
Body
- Axon.Response.Body.Body
- String
- Node.Buffer.Buffer
- Node.Stream.Readable a (for all a)
- Axon.Response.Construct.Json a
  - a must be EncodeJson. This will set the body to a stringified, and set Content-Type to application/json.
Headers
- ToResponse is implemented for all implementors of TypedHeader
- TODO: Map String String