Complete protocol and service documentation

docs/queue.md

@@ -0,0 +1,51 @@
+# Queue, routing, and delivery
+
+`bongoqueue` durably owns messages after SMTP or the external collector has
+accepted them and before every recipient has reached a final destination. It
+coordinates filtering, local Store delivery, remote SMTP, and LMTP; it is not
+a public submission protocol.
+
+## Message flow and durability
+
+Queue data lives below `/var/lib/bongo/spool`. An accepted message remains
+there while a temporary scanner, Store, DNS, SMTP, LMTP, or quota-dependent
+delivery condition is retried. Permanent failures produce the configured
+delivery-status response or bounce. The Queue must not acknowledge a message
+to its upstream path before the payload and recipient state are durable.
+
+Enabled filtering agents register for Queue stages. Antivirus,
+SpamAssassin, rules/Sieve, and final local or remote delivery therefore see a
+common envelope and message rather than independent copies. External POP3 or
+IMAP collection enters this same path and may delete a source message only
+after Bongo has committed it successfully.
+
+The internal Queue protocol defaults to TCP 8670. Bind and firewall it as a
+private service interface. It does not authenticate arbitrary Internet
+clients and must never be exposed as an SMTP alternative.
+
+## Limits and failure handling
+
+The suffixless `queue` document controls spool free-space reservation,
+message lifetime, retry interval, worker concurrency, trusted/hosted domains,
+and bounce policy. `minimumfreespace` prevents normal acceptance from
+consuming the filesystem's final space. Per-user Store quota is separate: a
+full mailbox defers or rejects that recipient without corrupting other
+recipient state.
+
+A scanner outage is a delivery-policy decision, not permission to silently
+bypass inspection. ClamAV and SpamAssassin failures leave the message queued
+for the configured retry path. Likewise, a per-recipient LMTP temporary error
+must preserve only that recipient for retry and must not redeliver recipients
+which already returned a final success.
+
+## Administration and shutdown
+
+Use `bongo-queuetool` to inspect and perform documented queue operations; do
+not edit spool files manually. A service stop first prevents new work and asks
+the managed agents to finish or abandon their current transaction safely.
+Queue and Store state must be included in a consistent backup.
+
+The 0.7 release matrix exercises byte preservation, disk exhaustion, retry,
+expiry, bounce, hold/release, concurrency, invalid commands, quota mapping,
+and collector floods under STQ-02 through STQ-12. SMTP and LMTP rows add their
+protocol-specific recipient and retry cases.