docs: Add some documentation and a README

docs/flow.md

@@ -0,0 +1,48 @@
+
+# Message flows
+
+This document explains at a high level some parts of chasquid's message
+processing, in particular how messages flow through the system.
+
+
+## Message reception
+
+- Client connects to chasquid on the smtp or submission ports, and issues
+  HELO/EHLO.
+- Client optionally performs STARTTLS.
+- Client optionally performs AUTH.
+    - Check that this is done over TLS.
+- Client sends MAIL FROM.
+    - Check SPF.
+    - Check connection security level.
+- Client sends one or more RCPT TO.
+    - If the destination is remote, then the user must have authenticated.
+    - If the destination is local, check that the user exists.
+- Client sends DATA.
+- Client sends actual data, and ends it with '.'
+    - Run the post-data hook. If the hook fails, return an error.
+    - Parse the data contents to perform loop detection.
+    - Add the required headers (Received, SPF results, post-data hook output).
+    - Put it in the queue and reply success.
+
+
+## Queue processing
+
+Before accepting a message:
+
+- Create a (pseudo) random internal ID for it.
+- For each recipient, use the alias database to expand it, add the results to
+  the list of final recipients (which may not be email).
+- Save the resulting envelope (with the final recipients) to disk.
+
+Queue processing runs asynchronously, there's a goroutine for each message
+which does, in a loop:
+
+- For each recipient which we have not delivered yet:
+    - Attempt delivery.
+    - Write to disk the results.
+- If there are mails still pending, wait for some time (incrementally).
+- When all the recipients have completed delivery, or enough time has passed:
+    - If all were successful, remove from the queue.
+    - If some failed, send a delivery status notification back to the sender.
+

docs/hooks.md

@@ -0,0 +1,45 @@
+
+# Post-DATA hook
+
+After completion of DATA, but before accepting the mail for queueing, chasquid
+will run the command at `$config_dir/hooks/post-data`.
+
+The contents of the mail will be written to the command's stdin, and the
+environment is detailed below.
+
+If the exit status is 0, chasquid will move forward processing the command,
+and its stdout should contain headers which will be added to contents of
+the email (at the top).
+
+Otherwise, chasquid will respond with an error, and the last line of stdout
+will be passed back to the client as the error message.
+If the exit status is 20 the error code will be permanent, otherwise it will
+be temporary.
+
+
+This hook can be used to block based on contents, for example to check for
+spam or virus.  See `etc/hooks/post-data` for an example.
+
+
+## Environment
+
+This hook will run as the chasquid user, so be careful about permissions and
+privileges.
+
+The environment will contain the following variables:
+
+ - USER
+ - SHELL
+ - PATH
+ - PWD
+ - REMOTE_ADDR
+ - MAIL_FROM
+ - RCPT_TO (space separated)
+ - AUTH_AS (empty if not completed AUTH)
+ - ON_TLS (0 if not, 1 if yes)
+ - FROM_LOCAL_DOMAIN (0 if not, 1 if yes)
+ - SPF_PASS (0 if not, 1 if yes)
+
+There is a 1 minute timeout for hook execution.
+It will be run at the config directory.
+