Wording

CHANGELOG.md

@@ -1,7 +1,5 @@
 # SpamAssassin Milter changelog
 
-**UNRELEASED**
-
-## 0.1.0 (2020-??-??)
+## 0.1.0 (2020-02-23)
 
 Initial release.

README.md

@@ -45,7 +45,7 @@ As a milter, this package requires the libmilter C library to be available. Be
 sure to install the libmilter shared library and header files.
 
 If your distribution does not install a pkg-config metadata file for libmilter,
-you can use the provided `milter.pc` file. Put it on the pkg-config path as
+try using the provided `milter.pc` file. Put it on the pkg-config path as
 follows:
 
 ```
@@ -67,7 +67,7 @@ Once installed, SpamAssassin Milter can be by invoked as `spamassassin-milter`.
 `spamassassin-milter` takes one mandatory argument, namely the listening socket
 of the milter (the socket to which the MTA will connect). The socket spec can be
 in one of the formats <code>inet:<em>port</em>@<em>host</em></code> or
-<code>inet6:<em>port</em>@<em>host</em></code> (IPv6), or
+<code>inet6:<em>port</em>@<em>host</em></code> (for IPv6), or
 <code>unix:<em>path</em></code>, for a TCP or UNIX domain socket, respectively.
 
 For example, the following invocation starts SpamAssassin Milter on port 3000:
@@ -93,14 +93,14 @@ service.
 ## Configuration
 
 SpamAssassin Milter is designed as a light-weight ‘glue’ application with just a
-few configuration options; this is intentional, as the SpamAssassin components
+few configuration switches; this is intentional, as the SpamAssassin components
 are themselves already highly configurable.
 
 SpamAssassin Milter is configured by setting command-line options. All options
-have reasonable defaults that work well with a stock installation of
-SpamAssassin server (`spamd`) and client (`spamc`). You can get started with
-just picking a socket and things should just work. Some integration options are
-discussed in subsequent sections.
+use sensible defaults that work well with a stock installation of SpamAssassin
+server (`spamd`) and client (`spamc`). You can get started with just picking a
+socket and things should just work. Some integration options are discussed in
+subsequent sections.
 
 New users may wish to run SpamAssassin Milter with the `--dry-run` option before
 going live. Combined with `--verbose`, this gives accurate insight into the
@@ -114,8 +114,8 @@ spamassassin-milter --dry-run --verbose inet:3000@localhost
 
 SpamAssassin Milter must be integrated with two SpamAssassin components: the
 SpamAssassin server itself, called `spamd`, which does the actual work, and the
-SpamAssassin client `spamc`, which serves as an intermediary between the milter
-and the server.
+SpamAssassin client `spamc`, which serves as the communication channel between
+the milter and the server.
 
 ### SpamAssassin configuration
 
@@ -147,9 +147,9 @@ report_safe 0
 In addition, body rewriting can also be suppressed on the SpamAssassin Milter
 side with the `--preserve-body` option.
 
-SpamAssassin may also rewrite the Subject and other headers, for example, adding
-a prefix ‘\*\*\*Spam\*\*\*’. This is not done by default, but may be enabled
-with a setting like the following:
+SpamAssassin may also rewrite the Subject and other headers, for example, by
+adding a prefix ‘\*\*\*Spam\*\*\*’. This is not done by default, but may be
+enabled with a setting like the following:
 
 ```
 rewrite_header Subject ***SPAM***
@@ -160,8 +160,8 @@ suppressed on the SpamAssassin Milter side with the `--preserve-headers` option.
 
 ### `spamc` configuration
 
-`spamc` can be configured by passing it command-line options, or preferably, by
-setting the command-line options in the configuration file
+The client program `spamc` can be configured by passing it command-line options,
+or preferably, by setting the command-line options in the configuration file
 `/etc/spamassassin/spamc.conf`.
 
 By default, `spamc` will try to reach SpamAssassin server on the dedicated port
@@ -175,7 +175,8 @@ instead, set the `--port` or `--socket` option as appropriate in `spamc.conf`:
 --socket=/run/spamassassin/spamd.sock
 ```
 
-When reports are disabled, it is recommended to use the `--headers` option.
+When SpamAssassin reports are disabled, it is recommended to use the `--headers`
+option:
 
 ```
 --headers
@@ -183,14 +184,14 @@ When reports are disabled, it is recommended to use the `--headers` option.
 
 This option is just a shortcut that causes `spamd` not to transmit the message
 body back to `spamc`. (This option obviously only makes sense and should only be
-used when SpamAssassin reports are disabled.)
+used when reports are disabled.)
 
 Finally, a pitfall of `spamc` deserves highlighting: `spamc` by default tries to
 resist failure to an extent that it will not indicate failure even if it cannot
 connect to SpamAssassin server at all (apart from warnings logged to syslog)! If
 it cannot connect to the server, it simply echoes what it received, and so masks
 the error condition. This behaviour is labelled ‘safe fallback’ and is perhaps
-best disabled once the system is set up. Set the following option:
+best disabled once the system is set up. Disable safe fallback as follows:
 
 ```
 --no-safe-fallback
@@ -223,8 +224,8 @@ the `X-Spam-` SpamAssassin headers of the incoming message, and take action
 based on those.
 
 As an example, in case [Dovecot] does mail delivery using [LMTP], enable the
-Sieve plugin for the LMTP protocol, then set up a global Sieve script that files
-messages flagged as spam into the ‘Junk’ folder:
+Sieve plugin for the LMTP protocol, and then set up a global Sieve script that
+files messages flagged as spam into the ‘Junk’ folder:
 
 ```
 require "fileinto";

spamassassin-milter.8

@@ -47,7 +47,7 @@ are gathered as arguments to pass to the
 .B spamc
 invocation.
 .B spamassassin-milter
-uses reasonable defaults and if run with no options, will apply modifications
+uses sensible defaults and if run with no options, will apply modifications
 received from SpamAssassin server.
 .PP
 .B spamassassin-milter
@@ -132,7 +132,7 @@ is, printed to standard error).
 .BR \-V ", " \-\-version
 Print version information.
 .SH SEE ALSO
+.BR spamassassin (1),
 .BR spamc (1),
-.BR spamassassin (1p),
-.BR Mail::SpamAssassin::Conf (3pm),
-.BR spamd (8p)
+.BR Mail::SpamAssassin::Conf (3),
+.BR spamd (8)

src/lib.rs

@@ -25,7 +25,7 @@ mod error;
 
 use crate::callbacks::*;
 pub use crate::config::{Config, ConfigBuilder};
-use milter::Milter;
+use milter::{Milter, Result};
 
 /// The name of the SpamAssassin Milter application.
 pub const MILTER_NAME: &str = "SpamAssassin Milter";
@@ -57,7 +57,7 @@ pub const VERSION: &str = "0.0.3";
 ///     process::exit(1);
 /// }
 /// ```
-pub fn run(socket: &str, config: Config) -> milter::Result<()> {
+pub fn run(socket: &str, config: Config) -> Result<()> {
     milter::set_debug_level(config.milter_debug_level());
 
     config::init(config);

tests/common/mod.rs

@@ -12,7 +12,7 @@ pub const SPAMD_PORT: u16 = 3783;  // mock port
 
 pub type HamOrSpam = Result<String, String>;
 
-/// A mock `spamd` server that echoes what it is sent after applying
+/// Spawns a mock `spamd` server that echoes what it is sent after applying
 /// transformation `f` to the message content and mock-classifying it as ham or
 /// spam.
 pub fn spawn_mock_spamd_server<F>(port: u16, f: F) -> JoinHandle<()>
@@ -91,7 +91,7 @@ where
     }
 }
 
-const MILTERTEST: &str = "miltertest";
+const MILTERTEST_PROGRAM: &str = "miltertest";
 
 pub fn spawn_miltertest_runner(test_file_name: &str) -> JoinHandle<ExitStatus> {
     // This thread is just for safety, in case the miltertest runner thread
@@ -107,10 +107,10 @@ pub fn spawn_miltertest_runner(test_file_name: &str) -> JoinHandle<ExitStatus> {
     let file_name = to_miltertest_file_name(test_file_name);
 
     thread::spawn(move || {
-        // Wait just a little to give the milter time to start up.
+        // Wait just a little while to give the milter time to start up.
         thread::sleep(Duration::from_millis(100));
 
-        let output = Command::new(MILTERTEST)
+        let output = Command::new(MILTERTEST_PROGRAM)
             .arg("-s")
             .arg(&file_name)
             .output()

tests/ham_message.rs

@@ -4,7 +4,7 @@ pub use common::*;  // `pub` only to silence unused code warnings
 use spamassassin_milter::*;
 
 #[test]
-fn ham_flow() {
+fn ham_message() {
     let mut builder = Config::builder();
     builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]);
     let config = builder.build();

tests/live.lua

@@ -60,6 +60,9 @@ local err = mt.bodystring(conn, "XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-ANTI
 assert(err == nil, err)
 assert(mt.getreply(conn) == SMFIR_CONTINUE)
 
+-- TODO `miltertest` bug: Replacing the message body can crash `miltertest`. An
+-- internal buffer size (1024) easily overflows when using SpamAssassin reports.
+
 local err = mt.eom(conn)
 assert(err == nil, err)
 assert(mt.getreply(conn) == SMFIR_ACCEPT)

tests/skip_oversized.rs

@@ -4,7 +4,7 @@ pub use common::*;  // `pub` only to silence unused code warnings
 use spamassassin_milter::*;
 
 #[test]
-fn skip_large_message() {
+fn skip_oversized() {
     let mut builder = Config::builder();
     builder.max_message_size(512);
     builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]);

tests/spam_message.rs

@@ -4,7 +4,7 @@ pub use common::*;  // `pub` only to silence unused code warnings
 use spamassassin_milter::*;
 
 #[test]
-fn spam_flow() {
+fn spam_message() {
     let mut builder = Config::builder();
     builder.spamc_args(vec![format!("--port={}", SPAMD_PORT)]);
     let config = builder.build();