Naust JMAP: a runtime for Go, not just a mail server

boom — Tue, 04 Aug 2026 02:20:12 +0000

A cut-down version of the full write-up. As of writing Naust JMAP is still in pre-release and is subject to breaking changes.

What if you could build a complete JMAP server without implementing the protocol yourself? Naust JMAP owns protocol correctness, your datatypes own what the objects mean, and your backend owns where they live.

Naust JMAP (repo) is a Go framework for building JMAP servers. It provides the protocol runtime required by RFC 8620 (Core), RFC 8621 (Mail), and related extensions, while leaving storage, authentication, search, delivery, and application-specific data models to the user.

The distinction that matters is runtime rather than server. Most JMAP implementations are complete mail servers, where the protocol sits on top of storage, delivery and authentication decisions that were made for you. Here those decisions stay with whoever embeds it. When I started there was also no server-side JMAP engine in Go at all, only client libraries.

JMAP was written for mail and calendaring, but the core specification never mentions email. It describes typed objects, method calls against them, and a synchronisation model. Mail is the first datatype built on that, not the point of it.

Architecture

The core runtime manages JMAP concepts such as sessions, method dispatch, standard method semantics, state strings, change tracking, blobs, and push notifications. Applications provide implementations through small interfaces: authentication, storage, blob persistence, search, notifications, and custom datatypes.

A datatype starts as a declaration rather than a set of handlers. Describe a type once and the runtime derives its /get, /changes, /set, /copy, /query and /queryChanges methods. No method code:

// Define a type with two properties, one indexed and one with a default value
todo := &descriptor.Type{
    Name:       "Todo",
    Capability: "urn:example:todo",
    Properties: map[string]descriptor.Property{
        "title": {Kind: descriptor.KindString, Indexed: true},
        "done":  {Kind: descriptor.KindBool, Indexed: true, Default: json.RawMessage(`false`)},
    },
}

// Register it with the runtime, which derives the standard methods
proc := runtime.NewProcessor()
core := runtime.DefaultCoreCapabilities()
runtime.RegisterStandardType(proc, db, todo, core)

A mail plugin declares a Mailbox the same way, with a name, a role and four counters, marking each property as client-writable, server-owned, or worth indexing.

Because the runtime generates those methods for any type it is given, it will also generate ones the specification never defined. Letting a type restrict which of them it wants caught a bug I had already shipped: RFC 8621 defines copy for Email alone, and Mailbox and Thread were both advertising it to clients.

Storage sits behind ordered key-value operations with an atomic batch, which keeps a new backend small. The two that ship are SQLite and Postgres, so this is not a storage engine: the indexes, change tracking and query planner are bookkeeping built once above someone else's engine, and they serve every datatype.

Change tracking is the part that has to be exactly right, so a change log entry is written in the same atomic batch as the mutation that caused it, rather than derived from it afterwards; a log that subscribes to writes loses data the first time the subscriber falls over. Concurrent writers are handled by a single-writer lease per account, claimed with a compare-and-swap rather than a database lock, whose token is also the fence checked at commit. A holder that stalls and comes back has its writes rejected, so consistency comes from the lease and the batch rather than from any backend's transaction isolation, and never from a timeout being tuned correctly.

The claim that correctness can live in the framework only holds if something checks it. Every backend runs one shared contract suite, and the object store is checked against a naive in-memory model with property-based tests. The WebSocket codec is hand-rolled, so it runs against the Autobahn suite, which is how I found out that validating UTF-8 per message is not the same as validating it incrementally.

Design decisions

Building this as a library rather than a server is only possible because of what JMAP is. IMAP is a long-lived session, so an implementation owns connection state and effectively has to be the process. JMAP is stateless request and response, so there is nothing to own between calls, an embedder can hold as many instances as they like, and a restart is invisible to clients rather than something they recover from.

The core module depends on nothing but the Go standard library, enforced by a test rather than a convention. This is a supply chain decision. Go resolves dependencies per module, so anything carrying one becomes its own module, otherwise it shows up in the audit output of everyone importing the runtime whether they use that part or not. A vulnerability in the charset library still forced a Go version floor rearrangement across three modules. Quarantine decides which module has the problem, not whether you have one.

Most of the design work was deciding what not to build. The core has no opinion about anything the RFCs are silent on. There is no search index, only a two-method interface with a substring scan behind it, since a scan answers a text filter correctly and everything past that fragments into ranking, tokenisation, stemming and incremental reindexing.

Challenges

Mail. Every mail feature would be easier with a table, an index or a state string that only mail is allowed to have.

Threading is server-defined, so there is no correct answer to check against. Messages join on a shared message-id and an equal base subject, with no merge, so a late linking message joins the first matching thread and threads that have split stay split. Merging would mean destroying and reinserting, because thread ids are immutable.

The first threading implementation was O(N squared). A 1600-message thread took 140 seconds to ingest, because each arrival loaded every candidate record to compare subjects. It now hashes the message-id and base subject together into a single composite index, so an arrival does one lookup per referenced id.

Scaling. Most of what I initially read off the graphs was wrong. My harness took the maximum rather than the sum of per-process memory, so forking servers looked about six times leaner than they were, and it reused a single message for every delivery in a run, which turned a throughput column I had been reading for weeks into a measure of duplicate-message contention. One of the gaps I had been trying to close turned out to be a competitor storing one copy of forty identical messages rather than storing them faster.

What survived the corrections was a storage model difference rather than a code problem. Dovecot and Cyrus spool messages to files, so the bytes sit in page cache the kernel can reclaim, whereas a transactional key-value store generally has to materialise a value in the process before it can commit it. That is the price of a blob committing in the same transaction as the objects referencing it. A file-backed store ships too and measures better on both throughput and memory, and what it gives up is exactly that property, which is not something you can add back afterwards.

Within that constraint there was still a factor of four available, found by changing how blobs are written, with the same binary, the same parser and the same messages. The chunked store only streamed blobs larger than a single piece, so ordinary mail was buffered whole, and it reserved a full piece per concurrent writer regardless of message size. Pieces now start at 256 KiB and double up to the cap. That was only legal because the manifest records a piece count and not a piece size, so nothing downstream can observe where the boundaries fell.

Lessons

The hardest part of implementing a protocol is not parsing requests, but defining the boundary between what the protocol owns and what the application owns.

Conformance and performance are separate claims. A substring scan answers a text query correctly, just slowly, so a real index buys speed and closes no compliance gap. That removed an entire milestone from the roadmap.

The rules only held once they were executable. Two design drifts happened by reasoning forward from a plausible premise past a rule I had already written down, and both were caught by review rather than by anything automatic.

What's next

S/MIME verification and quotas as further RFC 8621-family modules, streaming writes on the backend interface if the atomicity survives it, and more breaking changes pre-1.0 :))

The full write-up has the parts I cut here: the transport boundary, the web push crypto, and what each of them cost. Quickstart, guides and the method-by-method RFC matrices live in the docs, and the code is on GitHub.

Chafa Frontend

boom — Wed, 11 Jun 2025 19:49:39 +0000

I Built a Web UI for Chafa So You Don’t Have to Touch the Terminal (Unless You Want To)

A few months ago, I came across Chafa — a command-line tool that turns images into ANSI/ASCII art. If you’ve never tried it, it’s kind of brilliant. You point it at a PNG or JPEG, and it spits out a wall of colored text that looks eerily close to the original image — all using braille, Unicode blocks, or ASCII characters.

Naturally, I did what any curious dev would do:

I fed it a few pictures, sat back, and watched my terminal become an art gallery.

But then I had a thought:

What if you didn’t have to install anything? What if you could just drop an image into your browser and get the same result — instantly?

That’s how this started.

Introducing: Chafa Frontend

This is a minimal web app that wraps the Chafa CLI in a Flask server and adds a browser-based UI on top.

No terminal. No CLI flags. Just upload → configure → render.

👉 GitHub Repo

I didn’t write the magic — Chafa does all the heavy lifting in the project. Ironally, most of the code in this repo is for getting material design working, or even just validation. All-in-all, this project just tries to make Chafa more accessible.

Why Build a Web UI for a CLI Tool?

Honestly? Because I wanted to use Chafa on a phone.

And I wanted to share ASCII with my friends who have never opened a terminal in their lives.

Also: I think good CLI tools deserve good UIs. Not because the CLI is lacking, but because a tool can be powerful and approachable at the same time.

How It Works

The frontend is a simple single-page app using Material Design 3 components — just enough UI to pick a file, select some Chafa options, and display the result. No frameworks, no build steps — just HTML/CSS/JS.

The backend is a lightweight Flask server. When you upload an image, here’s what happens:

The image and selected options are sent to the backend.
The backend validates the inputs, saves the image temporarily.
It invokes chafa with the requested options.
The ANSI output is returned to the frontend and rendered in the browser using ansi_up.

Why Material Design 3?

No big reason — I just liked the idea of giving a CLI tool a polished, mobile-friendly interface. Material Web Components made it easy to prototype quickly and still look decent across devices. Mainly, I wanted to play around with some of the latest standards for material design - as most of my current projects have been using Material Design 2 components of some kind.

Lessons Learned

Building for “non-technical users” forces you to think carefully about defaults and feedback.
Even tools designed for terminals can benefit from a little UX thinking.
Chafa is extremely fast. I never had to optimize anything — it just works.
Material Design 3 (at least when working purely in DOM), feels like it has a long way to go. I read through the documentation looking for formatting, and was puzzled when the components wouldn't style properly. Once I read through the source code there were frequent mismatches which was a shame.

Final Thoughts

This isn’t a reinvention of image-to-ASCII conversion — that credit goes entirely to Chafa and Hans Petter Jansson. This is just a small wrapper to make it more usable in a browser context.

If you’re into terminal aesthetics, retro graphics, or building useful frontends around powerful backends — check it out! If you have any suggestions or extensions, feel free to let me know or fork it 🙂

👉 Check it out

DEV Community: boom