messua

A collection of convenience types and functions that might amount to a small web framework sitting atop mist.

Messua is a genus of spider, which apparently was itself named after a character from The Jungle Book. 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¹ 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.

Approach

Messua provides a sort of mist harness into which it hooks your handler function (and any Layers 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:

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:

$ curl localhost:8080
Hello, Web!