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
-
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.
-
Envelope
MAIL FROMis parsed and kept. EachRCPT TOis resolved through the router right there — literal alias, then catch-all, then nothing — so an address that does not exist gets550atRCPTtime and the sender never transmits the body. An alias with arejectgets your own words. -
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. -
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-Resultsheader and, with[arc], sealed so the next hop can see what this one saw. -
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, their550, their4xx. No bounce invented later, no message accepted and then quietly dropped. -
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>.emland<id>.json. Written to.tmpand renamed, so a crash mid-write leaves a file that is ignored rather than half a message. -
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
| Module | Holds |
|---|---|
| smtp/ | The server side of the protocol — command parsing, the session state machine, dot-unstuffing — and the client side that delivers onward. |
| routing.rspolicy.rs | An 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.rs | SPF, DKIM and DMARC with the per-stage budgets, and the ARC seal over the result. |
| srs.rs | Envelope-sender rewriting and the signature that makes a rewritten address verifiable rather than merely different. |
| spool.rsqueue.rs | The on-disk format, and the runner that walks it on the retry schedule. |
| dsn.rs | Delivery status notifications, and the rules about when sending one would be backscatter. |
| config.rs | Parsing, 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.rs | Graceful 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.