headers

This module implements some general header rewriting functions, including adding, dropping, and renaming headers and replacing header contents. It takes one configuration directive:

header HEADER FUNCTION [ CONTENT ]

Specify an action on the header HEADER. FUNCTION can be any of the following: drop deletes a header, rename renames the original header to X-Original-HEADER retaining the same value, ifempty adds a header with content CONTENT if and only if the message doesn't already contain a header HEADER, replace replaces all existing HEADER headers with one containing CONTENT, prepend adds CONTENT to the beginning of the first header HEADER or creates a new header HEADER with content CONTENT if none already exists, and reject returns an error if HEADER is present in the incoming message.

CONTENT can contain various special variables: $n will be replaced with the name of the running program, $v will be replaced with the version of News::Gateway, and $i will be replaced with a unique identifier formed from the current time and the process ID. $$ will be replaced with $, so to put a literal dollar sign in a header, you should use $$.

For example, suppose you have a configuration file with the following directives:

    header organization add     SNAP
    header message-id   rename
    header sender       drop
    header comment      replace $n $v
    header subject      ifempty no subject (thread id $i)

and suppose you have an incoming message with the headers:

    Organization: Restaurant Reviews
    Message-ID: <123142@bar.org>
    Sender: foo@bar.org
    Comment: Hello
    Comment: Hello again

After the headers module runs, the message will have a header of:

    Organization: Restaurant Reviews
    Organization: SNAP
    X-Original-Message-ID: <123142@bar.org>
    Comment: PROGRAM VERSION
    Subject: no subject (thread id ID)

where PROGRAM is the name of the running program (ie, $0), VERSION is the version of News::Gateway, and ID is a unique identifier as described above.

This module may fail and call error() with the following message while reading the configuration directives:

Unknown header rewrite action %s

A rewrite action was specified that isn't among those that are supported. This probably indicates a typo.

This module may fail in one way:

Invalid header %s

A header that was associated with a reject action in a configuration directive was present in the incoming message. Note that the header will be given in all lowercase.

As a side note, if you're constructing a robomoderator for a newsgroup, dropping or renaming the Path header in incoming messages is highly recommended. It turns out that some news servers will add a Path header with their hostname before remailing the message to a moderator, and if you keep that Path header when you post, the article will never propagate back to the site of the original poster.