mxhop

Architecture

What happens between the connection and the 250.

The whole program is one decision repeated: answer the sender truthfully while they are still holding the connection. Everything below follows from that, including the parts that look like over-engineering.

The path of one message

  1. Connection

    A listener accepts, or takes the socket systemd handed over. One task per connection; a session that misbehaves affects nothing else. A shutdown signal reaches every session through a watch channel, so a stop is a state change rather than a kill.

  2. Envelope

    MAIL FROM is parsed and kept. Each RCPT TO is resolved through the router right there — literal alias, then catch-all, then nothing — so an address that does not exist gets 550 at RCPT time and the sender never transmits the body. An alias with a reject gets your own words.

  3. DATA

    The body is read with dot-unstuffing and a size cap. Headers are split from the body because the two are treated differently from here on: mxhop prepends its Received: trace and leaves every original byte untouched, which is the only way the sender's DKIM signature survives the hop.

  4. Authentication, on a budget

    SPF, DKIM and DMARC run against the message, each with its own clock: 8 seconds, 6 seconds, the rest. A stage that runs out is a temporary failure, not a pass. Then the verdict is stamped into an Authentication-Results header and, with [arc], sealed so the next hop can see what this one saw.

  5. The reply

    Here is the decision the whole design exists for. mxhop tries delivery before answering end-of-DATA, so the destination's own verdict is what the sender gets: their 250, their 550, their 4xx. No bounce invented later, no message accepted and then quietly dropped.

  6. The spool, if needed

    If the destination defers, the message goes to disk and the sender gets 250 — mxhop has taken responsibility, so it must not lose it. Two files per message: <id>.eml and <id>.json. Written to .tmp and renamed, so a crash mid-write leaves a file that is ignored rather than half a message.

  7. Retries, then a DSN

    A runner walks the queue on the configured schedule. When a message finally dies, mxhop sends an RFC 3464 report — but only if it can prove who the sender was, by SPF pass or an aligned DKIM pass. Unprovable sender, no DSN. A bounce to a forged address is backscatter, and sending it makes you the spammer.

Decisions worth arguing about

Delivery before the reply

It makes accepting mail slower and ties a session's fate to a third party. It is still right: a forwarder that accepts first has to invent a bounce later, and a bounce to a forged sender is backscatter. Honesty at the door beats throughput.

Duplicates over loss

A message delivered but not removable from the queue is sent again on the next pass. Deliberate: nothing on disk distinguishes that from an attempt that never happened, and a reader can delete a second copy. Nobody can read a message that is gone.

Per-stage budgets, not one total

One shared timeout is an attack: forty DKIM signatures on slow nameservers eat it all, DMARC never runs, and the check fails open. Splitting it means the expensive stage can starve only itself.

A test that reads the source

The privacy promise is only as good as the next logging call somebody adds. So a test parses every tracing invocation and fails the build if one could print message content. A length has to be named before it is logged.

No plugins, no scripting

Every extension point in a mail server is a way to make it behave unlike a mail server. Behaviour lives in a config file that check can prove things about, or it does not exist.

Files, not a database

The queue is two files per message in a directory. You can read it with ls and cat, back it up with cp, and understand it at three in the morning. A database would need a schema, a migration path and a reason.

The shape of the code

ModuleHolds
smtp/The server side of the protocol — command parsing, the session state machine, dot-unstuffing — and the client side that delivers onward.
routing.rspolicy.rsAn address in, a list of targets out. Pure functions over the alias table, and every SMTP reply mxhop can give, in one place where they can be read together.
auth.rsarc.rsSPF, DKIM and DMARC with the per-stage budgets, and the ARC seal over the result.
srs.rsEnvelope-sender rewriting and the signature that makes a rewritten address verifiable rather than merely different.
spool.rsqueue.rsThe on-disk format, and the runner that walks it on the retry schedule.
dsn.rsDelivery status notifications, and the rules about when sending one would be backscatter.
config.rsParsing, and the diagnostics that carry a line number — most of the file is the error messages.
observe.rsmetrics.rs/metrics and /healthz, served by a hand-rolled responder rather than a web framework, because two routes do not justify one.
shutdown.rsactivation.rsGraceful stop, and taking a socket from systemd.

There are no comments in the source. Reasoning lives in commit messages, where it is attached to the change that needed it and cannot drift out of date; names and tests carry the rest. Test names are full sentences — a_forged_srs_recipient_is_550_not_relayed — so a failure reads as the broken claim.