purescript-httpurple/docs/Routing.md

# Routing in HTTPure

Routing in HTTPure is designed on the simple principle of allowing PureScript to
do what PureScript does best. When you create an HTTPure server, you pass it a
router function:

```purescript
main = HTTPure.serve 8080 router $ Console.log "Server up"
```

The router function is called for each inbound request to the HTTPure server.
Its signature is:

```purescript
HTTPure.Request -> HTTPure.ResponseM
```

So in HTTPure, routing is handled simply by the router being a pure function
which is passed a value that contains all information about the current request,
and which returns a response monad. There's no fancy path parsing and matching
algorithm to learn, and everything is pure--you don't get anything or set
anything, you simply define the return value given the input parameters, like
any other pure function.

This is quite powerful, as all routing can be defined using the same PureScript
pattern matching and guard syntax you use everywhere else. It allows you to
break up your router to sub-routers easily, using whatever router grouping makes
sense for your app. It also leads to some powerful patterns for defining and
using middleware. For more details about defining and using middleware, see the
[Middleware guide](./Middleware.md).

For more details about the response monad, see the [Responses
guide](./Responses.md).

## The Request Record

The `HTTPure.Request` type is the input parameter for the router function. It is
a `Record` type that contains the following fields:

- `method` - A member of `HTTPure.Method`.
- `path` - An `Array` of `String` path segments. A path segment is a nonempty
  string separated by a `"/"`. Empty segments are stripped out when HTTPure
  creates the `HTTPure.Request` record.
- `query` - An `Object` of `String` values. Note that if you have any query
  parameters without values (for instance, a URL like `/foo?bar`), then the
  value in the `Object` for that query parameter will be the empty `String`
  (`""`).
- `headers` - A `HTTPure.Headers` object. The `HTTPure.Headers` newtype wraps
  the `Object String` type and provides some typeclass instances that make more
  sense when working with HTTP headers.
- `body` - A `String` containing the contents of the request body, or an empty
  `String` if none was provided.

Following are some more details on working with specific fields, but remember,
you can combine guards and pattern matching for any or all of these fields
however it makes sense for your use case.

## The Lookup Typeclass

You will find that much of HTTPure routing takes advantage of implementations of
the [HTTPure.Lookup](../src/HTTPure/Lookup.purs) typeclass. This typeclass
defines the function `HTTPure.lookup` (or the infix version `!!`), along with a
few auxiliary helpers, for looking up a field out of an object with some key.
There are three instances defined in HTTPure:

1. `Lookup (Array t) Int t` - In this instance, `HTTPure.lookup` is the same as
   `Array.index`. Because the path is represented as an `Array` of `Strings`,
   this can be used to retrieve the nth path segment by doing something like
   `request.path !! n`.
2. `Lookup (Object t) String t` - In this instance, `HTTPure.lookup` is a
   flipped version of `Object.lookup`. Because the query is a `Object String`,
   this instance can be used to retrieve the value of a query parameter by name,
   by doing something like `request.query !! "someparam"`.
3. `Lookup Headers String String` - This is similar to the example in #2, except
   that it works with the `HTTPure.Headers` newtype, and the key is
   case-insensitive (so `request.headers !! "X-Test" == request.headers !!
   "x-test"`).

There are three infix operators defined on the `HTTPure.Lookup` typeclass that
are extremely useful for routing:

1. `!!` - This is an alias to `HTTPure.lookup` itself, and returns a `Maybe`
   containing some type.
2. `!@` - This is the same as `HTTPure.lookup`, but it returns the actual value
   instead of a `Maybe` containing the value. It only operates on instances of
   `HTTPure.Lookup` where the return type is a `Monoid`, and returns `mempty` if
   `HTTPure.lookup` returns `Nothing`. It's especially useful when routing based
   on specific values in query parameters, path segments, or header fields.
3. `!?` - This returns `true` if the key on the right hand side is in the data
   set on the left hand side. In other words, if `HTTPure.lookup` matches
   something, this is `true`, otherwise, this is `false`.

## Matching HTTP Methods

You can use normal pattern matching to route based on the HTTP method:

```purescript
router { method: HTTPure.Post } = HTTPure.ok "received a post"
router { method: HTTPure.Get } = HTTPure.ok "received a get"
router { method } = HTTPure.ok $ "received a " <> show method
```

To see the list of methods that HTTPure understands, see the
[Method](../src/HTTPure/Method.purs) module. To see an example server that
routes based on the HTTP method, see [the Post
example](./Examples/Post/Main.purs).

## Working With Path Segments

Generally, there are two use cases for working with path segments: routing on
them, and using them as variables. When routing on path segments, you can route
on exact path matches:

```purescript
router { path: [ "exact" ] } = HTTPure.ok "matched /exact"
```

You can also route on partial path matches. It's cleanest to use PureScript
guards for this. For instance:

```purescript
router { path }
  | path !@ 0 == "foo" = HTTPure.ok "matched something starting with /foo"
  | path !@ 1 == "bar" = HTTPure.ok "matched something starting with /*/bar"
```

When using a path segment as a variable, simply extract the path segment using
the `HTTPure.Lookup` typeclass:

```purescript
router { path } = HTTPure.ok $ "Path segment 0: " <> path !@ 0
```

To see an example server that works with path segments, see [the Path Segments
example](./Examples/PathSegments/Main.purs).

## Working With Query Parameters

Working with query parameters is very similar to working with path segments. You
can route based on the _existence_ of a query parameter:

```purescript
router { query }
  | query !? "foo" = HTTPure.ok "matched a request containing the 'foo' param"
```

Or you can route based on the _value_ of a query parameter:

```purescript
router { query }
  | query !@ "foo" == "bar" = HTTPure.ok "matched a request with 'foo=bar'"
```

You can of course also use the value of a query parameter to calculate your
response:

```purescript
router { query } = HTTPure.ok $ "The value of 'foo' is " <> query !@ "foo"
```

To see an example server that works with query parameters, see [the Query
Parameters example](./Examples/QueryParameters/Main.purs).

## Working With Request Headers

Headers are again very similar to working with path segments or query
parameters:

```purescript
router { headers }
  | headers !? "X-Foo" = HTTPure.ok "There is an 'X-Foo' header"
  | headers !@ "X-Foo" == "bar" = HTTPure.ok "The header 'X-Foo' is 'bar'"
  | otherwise = HTTPure.ok $ "The value of 'X-Foo' is " <> headers !@ "x-foo"
```

Note that using the `HTTPure.Lookup` typeclass on headers is case-insensitive.

To see an example server that works with headers, see [the Headers
example](./Examples/Headers/Main.purs).