Class RFilter::DeliveryAgent
In: lib/rfilter/delivery_agent.rb
Parent: Object

The RFilter::DeliveryAgent class allows flexible delivery of a mail message to a mailbox. It is designed to make mail filtering scripts easy to write, by allowing the filter author to concentrate on the filter logic and not the particulars of the message or folder format.

It is designed primarily to work as an DeliveryAgent (local delivery agent) for an SMTP server. It should work well as the basis for a script run from a .forward or .qmail file.

body    defer    exitcode    filter    header    log    logging_level    logging_level=    message    message=    new    pipe    process    reject    save   
Classes and Modules
Class RFilter::DeliveryAgent::DeliveryCommandFailure
Class RFilter::DeliveryAgent::DeliveryComplete
Class RFilter::DeliveryAgent::DeliveryDefer
Class RFilter::DeliveryAgent::DeliveryReject
Class RFilter::DeliveryAgent::DeliverySuccess
Class RFilter::DeliveryAgent::LoggingError
Included modules
Public Class methods
new(input, logfile)

Create a new RFilter::DeliveryAgent object.

input may be a RMail::Message object (in which case, it is used directly). Otherwise, it is passed to RMail::Message.new and used to create a new RMail::Message object.

log may be nil (to disable logging completely) or a file name to which log messages will be appended.

process(input, logfile) {|lda| ...}

Takes the same input as #new, but passes the created RFilter::DeliveryAgent to the supplied block. The idea is that the entire delivery script is contained within the block.

This function tries to log exceptions that aren't DeliveryComplete exceptions to the lda's log. If it can log them, it defers the delivery. But if it can't, it re-raises the exception so the caller can more properly deal with the exception.

Expected use:

   RFilter::DeliveryAgent.process(stdin, "my-log-file") { |lda|
     # ...code uses lda to deliver mail...
 rescue RFilter::DeliveryAgent::DeliveryComplete => exception
 rescue Exception
   ... perhaps log the exception to a hard coded file ...

This function expects the exception argument to be a RFilter::DeliveryAgent::DeliveryComplete subclass. The function will return the appropriate exitcode that the process should exit with.

Public Instance methods
save(folder, continue = false)

Save this message to mail folder. folder must be the file name of the mailbox. If folder ends in a slash (/) then the mailbox will be considered to be in Maildir format, otherwise it will be a Unix mbox folder.

If continue is false (the default), a RFilter::DeliveryAgent::DeliverySuccess exception is raised upon successful delivery. Otherwise, the method simply returns upon successful delivery.

Upon failure, the function raises an exception as determined by RFilter::Deliver.deliver_mbox or RFilter::Deliver.deliver_maildir.

See also: RFilter::Deliver.deliver_mbox and RFilter::Deliver.deliver_maildir.

reject(reason = nil)

Reject this message. Logs the reason for the rejection and raises a RFilter::DeliveryAgent::DeliveryReject exception.

defer(reason = nil)

Reject this message for now, but request that it be queued for re-delivery in the future. Logs the reason for the rejection and raises a RFilter::DeliveryAgent::DeliveryDefer exception.

pipe(command, continue = false)

Pipe this message to a command. command must be a string specifying a command to pipe the message to.

If continue is false, then a successful delivery to the pipe will raise a RFilter::DeliveryAgent::DeliverySuccess exception. If continue is true, then a successful delivery will simply return. Regardless of continue, a failure to deliver to the pipe will raise a RFilter::DeliveryAgent::DeliveryCommandFailure exception.

See also: RFilter::Deliver.deliver_pipe.


Filter this message through a command. command must be a string or an array of strings specifying a command to filter the message through (it is passed to the Kernel::exec method).

If the command does not exit with a status of 0, a RFilter::DeliveryAgent::DeliveryCommandFailure exception is raised and the current message is not replaced.

See also: RFilter::Deliver.deliver_filter.

log(level, str)

Log a string to the log. If the current log is nil or level is greater than the current logging level, then the string will not be logged.

See also #logging_level, #logging_level=


Return the current logging level.

See also: #logging_level=, #log


Set the current logging level. The level must be a number no less than one.

See also: #logging_level, #log


Return the RMail::Message object associated with this RFilter::DeliveryAgent.

See also: #header, #body


Sets the message (which should be a RMail::Message object) that we're delivering.


Return the header of the message as a RMail::Header object. This is short hand for lda.message.header.

See also: #message, #body


Return the body of the message as an array of strings. This is short hand for lda.message.body.

See also: #message, #header