Struct milter::Milter

pub struct Milter { /* fields omitted */ }

A configurable milter runner.

Milter is used to configure and run a milter implementation. It is instantiated with Milter::new and a mandatory listening socket. The milter can then be configured with a name, a selection of callbacks that provide the functionality of the milter, and the actions that the milter wants to take. Finally, a call to run starts the milter.

A limitation to be aware of is that while Milter appears to expose a tidily encapsulated fluent builder API, Milter must essentially be used like a singleton. No more than one milter can be configured and run in a single process. (This limitation is due to the design of the underlying libmilter library, which is based on a paradigm of global state.)

Examples

The following shows the simplest possible, no-op milter.

use milter::Milter;

Milter::new("unix:/run/noopmilter.sock").run().expect("milter execution failed");

More typically, a milter is configured with a name, some callbacks, and the desired actions before being started:

Milter::new("inet:3333@localhost")
    .name("MyMilter")
    .on_eom(eom_callback)
    .actions(Actions::ADD_HEADER)
    .run()
    .expect("milter execution failed");

Implementations

impl Milter

pub fn new(socket: &str) -> Self

Creates a new milter that will listen on the given socket.

The socket specification needs to be in one of the following formats:

• inet:port@host – an IPv4 socket
• inet6:port@host – an IPv6 socket
  where port is a numeric port, and host can be either a hostname or an IP address
• {unix|local}:path – a UNIX domain socket at an absolute file system path

UNIX domain socket files are created using the user and umask of the milter process.

While Milter is responsible for creation and deletion of UNIX domain sockets, it is possible that a socket file survives an abnormal termination. See Milter::remove_socket for an option that may help address this.

Panics

Panics if socket contains a zero byte.

Examples

let mut milter = Milter::new("inet:3000@localhost");

pub fn name(&mut self, name: &str) -> &mut Self

Configures a descriptive name for this milter.

Panics

Panics if name contains a zero byte.

pub fn on_negotiate(&mut self, callback: NegotiateCallback) -> &mut Self

Sets the callback to use for this milter’s negotiate stage.

Use the on_negotiate attribute macro to generate the callback function.

pub fn on_connect(&mut self, callback: ConnectCallback) -> &mut Self

Sets the callback to use for this milter’s connect stage.

Use the on_connect attribute macro to generate the callback function.

pub fn on_helo(&mut self, callback: HeloCallback) -> &mut Self

Sets the callback to use for this milter’s helo stage.

Use the on_helo attribute macro to generate the callback function.

pub fn on_mail(&mut self, callback: MailCallback) -> &mut Self

Sets the callback to use for this milter’s mail stage.

Use the on_mail attribute macro to generate the callback function.

pub fn on_rcpt(&mut self, callback: RcptCallback) -> &mut Self

Sets the callback to use for this milter’s rcpt stage.

Use the on_rcpt attribute macro to generate the callback function.

pub fn on_data(&mut self, callback: DataCallback) -> &mut Self

Sets the callback to use for this milter’s data stage.

Use the on_data attribute macro to generate the callback function.

pub fn on_header(&mut self, callback: HeaderCallback) -> &mut Self

Sets the callback to use for this milter’s header stage.

Use the on_header attribute macro to generate the callback function.

pub fn on_eoh(&mut self, callback: EohCallback) -> &mut Self

Sets the callback to use for this milter’s eoh (end-of-header) stage.

Use the on_eoh attribute macro to generate the callback function.

pub fn on_body(&mut self, callback: BodyCallback) -> &mut Self

Sets the callback to use for this milter’s body stage.

Use the on_body attribute macro to generate the callback function.

pub fn on_eom(&mut self, callback: EomCallback) -> &mut Self

Sets the callback to use for this milter’s eom (end-of-message) stage.

Use the on_eom attribute macro to generate the callback function.

pub fn on_abort(&mut self, callback: AbortCallback) -> &mut Self

Sets the callback to use for this milter’s abort stage.

Use the on_abort attribute macro to generate the callback function.

pub fn on_close(&mut self, callback: CloseCallback) -> &mut Self

Sets the callback to use for this milter’s close stage.

Use the on_close attribute macro to generate the callback function.

pub fn on_unknown(&mut self, callback: UnknownCallback) -> &mut Self

Sets the callback to use for this milter’s unknown stage.

Use the on_unknown attribute macro to generate the callback function.

pub fn actions(&mut self, actions: Actions) -> &mut Self

Enables the given actions for this milter.

Actions represented as methods on ContextApi need to be enabled with this method (or during negotiation) before they can be used.

pub fn timeout(&mut self, duration: Duration) -> &mut Self

Configures the time until the connection to the MTA times out.

Panics

Panics if the duration is outside the acceptable range.

pub fn socket_backlog(&mut self, len: u32) -> &mut Self

Configures the socket backlog, that is, the maximum number of incoming connections to queue up.

Panics

Panics if the given length is outside the acceptable range.

pub fn remove_socket(&mut self, value: bool) -> &mut Self

Configures whether to force removal of any existing UNIX domain socket at the location given in Milter::new during startup.

While a Milter normally manages creation and deletion of socket files itself, a socket file may survive an abnormal termination; enabling this option may help clear out leftover files when (re-)starting.

pub fn run(&self) -> Result<()>

Registers this milter’s configuration with the libmilter library and starts the milter. This is a blocking call, run only returns when the milter is shut down.

Important: Not more than one milter may be configured and run at a time.

Errors

Only when calling run is this milter’s configuration applied. This can fail for a variety of reasons encoded in the error result.

Trait Implementations

impl Clone for Milter

fn clone(&self) -> Milter

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Milter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.