# messua
A collection of convenience types and functions that might amount to a small
web framework sitting atop mist.
[](https://hex.pm/packages/messua)
[](https://hexdocs.pm/messua/)
_Messua_ is a [genus of spider](https://en.wikipedia.org/wiki/Messua_(spider)),
which apparently was itself named after [a character from _The Jungle
Book_](https://en.wikipedia.org/wiki/List_of_The_Jungle_Book_characters#Messua).
Please do not take this as any sort of endorsement of any orientalist or
colonialist themes that may appear in Kipling's work; I just wanted a
name vaguely related to webs that probably wouldn't already be taken.
## Introduction
When a piece of technology focuses on a particular solution or style in
the face of many alternatives, it is in fashion these days to refer to that
piece of technology as being "opinionated", particularly when describing
a programming language, framework, or library. I wouldn't say that Messua
is _opinionated_ so much as I'd say it _sees the point_ of doing things a
certain way, and is willing to give that a go. It is based largely on a
couple of convenient patterns I have found myself using when implementing
backends in Rust and Gleam:
1. A common `Result(Response, Error)` type returned by handlers, for which
the `Error` variant gets automatically converted to a response.
2. A common `Request` type (injected[^injected] with some server state),
passed "down" through layers of middleware, with the aforementioned
`Result` type bubbling back up.
3. Functions that couple this `Result` type with Gleam's `use` sugar to
mimic early returns of `Error` variants that then get handled with a
minimum of ceremony, permitting focus on business logic and an
uncluttered happy path.
[^injected]: I use the term "injected", but really it's more like,
"bundled with". Under the hood, the `MRequest` is just a
wrapper that holds the underlying request (the `gleam_http`
type) and a handle to your server state.
## Approach
Messua provides a sort of `mist` harness into which it hooks your handler
function (and any `Layer`s you might have on top of it). It provides your
stack with an `Incoming` (request + server state handle) and expects it to
return an `Outgoing` (which is just an alias for a `Result` whose `Ok`
variant is a `gleam/http/response.Response`, and whose `Error` variant
is `messua/fail.Failure`, which gets turned into an actual HTTP response
by the harness). It then provides you with a slew of convenience functions
for extracting parts of requests, routing, and generating responses.
Messua also provides wrappers around some key things from `mist` and
`gleam_http`; the idea here is that it's easier and more convenient to
import and use a single package, rather than having to mess around in the
guts of three separate packages, wondering which one has the functionality
you want.
## Examples
There is not an `examples/` directory yet (like Version 1 had), but one is
planned. Here's the simplest possible thing:
```gleam
import messua
import messua/minc.{Incoming}
import messua/mout.{Outgoing}
fn handler(_req: Incoming(Nil)) -> Outgoing {
mout.ok()
|> mout.with_string_body("Hello, Web!\n")
}
pub fn main() {
messua.default()
|> messua.start(handler)
}
```
And now a `gleam run` will have you listening on local port 8080:
```text
$ curl localhost:8080
Hello, Web!
```
