Coder Legion - Recent posts tagged nim

A Tiny Nim Microservice, Three Real Bugs, and What They Taught Me About My Own Mummy Fork

Tue, 15 Sep 2026 00:19:50 +0000

I recently needed something small: a POST /api/contact endpoint for my portfolio site at https://www.isaiah.name.ng that takes a name, email, and message, validates it, and emails it to me. The kind of thing you'd normally knock out without thinking twice.

I decided to build it directly on my own Mummy fork — the one with OpenAPI schema generation, typed validation, and composable middleware — partly to actually dogfood it on something real, and partly because I assumed a single-endpoint service would be trivial. It mostly was. But three specific bugs along the way taught me more about the fork's internals than building the fork itself did.

The Shape of the Service

Nothing exotic: a ContactBody type with name, email, and message, all required strings. Validation happens in two layers — parseValidatedBody[ContactBody] checks presence and type against the fork's schemaOf-generated schema, and then explicit checks enforce non-empty fields, a 2000-character cap, and a hand-rolled email format check. Either layer raising the fork's ValidationError gets mapped to a clean 400 {"error": ...} by installDefaultErrorHandler. A send failure is logged server-side and answered with a generic 500 — the caller never sees why an email failed to send, only that it did.

On top of that: CORS middleware that rejects disallowed origins with 403 and answers preflight requests properly, an in-memory rate limiter capping submissions at 5 per IP per 10 minutes, and the fork's loggingMiddleware as the outermost layer so every request logs method, path, and timing. The OpenAPI docs come free from the same schema the validator uses, served at /docs with the spec at /openapi.json — the whole reason I built the fork in the first place.

The Pivot Nobody Plans For: SMTP → Resend

The original plan was plain SMTP via std/smtp. It compiled fine against the fork. Then I deployed to Render's free tier and every send just hung until timeout — Render blocks outbound SMTP ports (25/465/587) on that tier. Resend's REST API runs over HTTPS:443, which isn't blocked, and needs just one API key. As a bonus, its failures come back as ordinary HTTP errors the handler already catches and logs, instead of the occasional AssertionDefect that a raw SMTP library can throw and potentially take a worker down with it.

This is the kind of constraint you only discover by actually deploying, not by reading docs — worth remembering if you're building anything Render-hosted that needs to send mail.

Three Bugs That Taught Me More Than the Feature Did

1. Two HttpHeaders types that look identical and aren't.
Mummy imports std/httpcore aliased internally, and Request.headers is typed against that aliased import. My module also did a plain import std/httpcore for the Resend payload types — and suddenly every header operation threw a "type mismatch" between what looked like the same type. Nim's module system treats the two imports as distinct type identities even though they're structurally the same. The fix was narrow: import std/httpcore except HttpHeaders, so my module only pulled in the pieces it needed for the Resend payload and left the header type alone. This was, by a wide margin, the buggiest hour of the whole build — and a good reminder that "same type, different import path" is a real failure mode in Nim, not a theoretical one.

2. gcsafe doesn't care that your global never actually changes.
The fork's Middleware and RequestHandler types are marked {.gcsafe.}, which means the compiler's data-race checker gets strict about any global state touched inside a handler — because Mummy dispatches requests across a worker-thread pool, not a single event loop. My CORS middleware read a var global holding the allowed-origins list, set once at startup and never touched again — and the compiler didn't care that it was logically immutable after init. It only sees a mutable global read from a gcsafe context. The fix was a {.cast(gcsafe).} block around that specific read, while the genuinely-shared rate-limit table stayed behind a real Lock — the same pattern the fork already uses internally for bearerAuthMiddleware. It's a useful distinction to internalize on a threaded server: "never mutated after startup" and "thread-safe" are not the same claim, and the compiler will only ever check for the second one.

3. An unregistered route means your middleware never runs — including for the request that most needs it.
Browsers send an OPTIONS preflight before certain cross-origin POST requests. Mummy only runs its middleware chain for methods that have a registered route — so with no OPTIONS /api/contact route, Mummy answered preflight with its own 405 before corsMiddleware ever got a chance to run. The browser never saw the Access-Control-Allow-Origin header it needed, so the real POST was blocked client-side despite the server being otherwise correctly configured. The fix was almost comically small: register an OPTIONS /api/contact route whose handler does nothing but exist, which is enough to route the request into the middleware chain where corsMiddleware can actually answer it with a 204. Easy to fix once you know it — genuinely confusing the first time a working-looking CORS setup silently fails only on the preflight leg.

What Actually Got Verified

Before calling it done, I ran it locally and checked the specific paths that tend to hide bugs rather than just the happy path: a disallowed origin (403), a malformed email (400 with the exact field named), a name at the 2000-character boundary (passes) versus one character over (rejected), six rapid submissions from one IP (five succeed, the sixth comes back 429 with Retry-After), and that /health and OPTIONS both stay outside the rate limiter so Render's health checks and CORS preflight never get throttled.

Why This Was Worth Writing Up

None of these three bugs were about the feature — a contact form endpoint is about as unglamorous as backend work gets. They were about the specific intersection of Nim's module aliasing, gcsafe's literal (not logical) read of what's safe, and Mummy's routing-before-middleware order. If you're building anything on Mummy — my fork or the original — that touches CORS, thread-shared state, or has more than one import path into std/httpcore, these three are worth checking for before you hit them the hard way.

The full service, Dockerfile, and a drop-in script.js for wiring this into any static contact form are in the repo if you want to see the whole thing end to end.

Adding OpenAPI Support to Mummy, a Nim HTTP Framework

Sun, 13 Sep 2026 22:28:03 +0000

Adding OpenAPI Support to Mummy: Lessons from Extending Nim's Thread-Per-Request HTTP Server

Mummy is a multi-threaded HTTP 1.1 and WebSocket server for Nim built around a simple, unapologetic idea: skip async/await entirely and let a pool of worker threads handle requests the old-fashioned way — one thread, one request, blocking calls allowed. No Future[T], no colored functions, no async stack traces to untangle. For a systems language with real threads and ARC/ORC to make that cheap, it's a compelling trade.

What Mummy doesn't ship with, though, is any notion of API documentation. There's no built-in way to describe your routes, generate a schema, or hand a frontend team (or your future self) a /docs page. That gap is what got me building.

Why This Gap Matters

Nim's web ecosystem is small enough that most frameworks are optimized for the author's own use case first. Mummy is optimized for raw throughput and simplicity — and it succeeds at both. But once an API has more than a couple of routes, "read the source to find out what a request body looks like" stops scaling. OpenAPI (formerly Swagger) solves this by generating a machine-readable schema of your API directly from your code, which then powers interactive docs, client SDK generation, and request validation.

I forked Mummy and built this in as a layer on top, rather than a separate tool that has to be kept in sync by hand.

What I Built

The fork adds two core modules — openapi_schema.nim and openapi_router.nim — plus an OpenApiRouter that wraps Mummy's normal routing with metadata: summaries, tags, and response schemas generated via schemaOf. Every one of the 12 bundled examples now serves a live /openapi.json and an interactive /docs page, generated from the same route definitions that handle requests — no separate spec file to maintain.

From there I added three more pieces that came up naturally once the schema layer existed:

Typed path params (openapi_params.nim) — pathParam[T](request, "id") pulls a path segment straight out as an int, string, or whatever type you declare, instead of manually parsing strings on every handler.
Request body validation (openapi_validation.nim) — parseValidatedBody[T] checks an incoming JSON body against the same schema that schemaOf generated for your docs, so the validation and the documentation can't drift apart.
Composable middleware (openapi_middleware.nim) — a Middleware type and a use() method on the router, with logging and bearer-auth middleware included out of the box.

Every feature was compiled and exercised with real HTTP requests, not just nim check, before I called it done — including converting a wildcard WebSocket route to a named path param and confirming it fixed a small latent bug where the old code read the raw request URI (query string and all) instead of the decoded path.

What the Wider Nim Community's Experience With Mummy Adds

Reading through discussion around Mummy on the Nim mailing list and forum was useful context while building this. One recurring theme: Mummy's design intentionally keeps some things out of scope in the name of simplicity. A developer comparing thread-per-request servers noted that Mummy's multipart handling, while present, buffers the entire upload into memory rather than streaming it — a deliberate trade-off for simplicity that matters if you're building something like a file-upload service, and pointed to alternatives like Guildenstern for cases needing streaming multipart support.

That trade-off is directly relevant to schema-driven validation work: parseValidatedBody[T] inherits the same "load it all, then check it" model. For typical JSON APIs that's a non-issue, but it's a useful thing to know going in if you're planning a Mummy-based service that also needs large file uploads — you may want to keep that path outside the validated-body flow rather than fight the framework's grain.

It's also worth knowing you're not alone in wanting typed, schema-aware APIs on Mummy — a separate project, Sarcophagus, tackles a similar problem from a different angle: typed request/response encoding across JSON, CBOR, and MessagePack, plus its own Swagger/OpenAPI generation and OAuth2 helpers. Different design choices, same underlying itch in the ecosystem — which suggests this is a real gap worth filling rather than a one-off preference of mine.

Putting It to Use

To validate the fork beyond the bundled examples, I built a small Todo API demo using the typed params, validation, and middleware together, and I'm deploying it live on Render as a working reference — a REST API with real request validation and generated docs, running on a threaded model with no async in sight.

Where This Goes Next

The fork is usable today for anyone building JSON APIs on Mummy who wants documentation and validation that can't silently drift from the actual routes. If you're working in the Nim web space and hit the same "no schema, no docs" wall, I'd genuinely like to hear how you're solving it — feel free to reach out.