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.

Methods

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

RFilter::Deliver

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:

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

exitcode(exception)

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(*command)

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=

logging_level()

Return the current logging level.

See also: #logging_level=, #log

logging_level=(level)

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

See also: #logging_level, #log

message()

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

See also: #header, #body

message=(message)

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

header()

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

See also: #message, #body

body()

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

See also: #message, #header