Chapter 9. Post Filtering
The -postprog command-line option can be used to keep tight control over locally generated articles by using a POST filter. By using this option, all POST'ed articles are sent to the specified program for approval and/or modification before being considered for acceptance.
The system communicates with the POST filter by writing data to its "stdin" and reading data from its "stdout".
A transaction begins by sending "Field: value\r\n" information from the feed object to the standard input of the POST filter followed by a blank line ("\r\n"), the header of the article to be considered, a blank line ("\r\n"), and finally the body of the article terminated by ".\r\n". The system waits for 1 of 8 possible responses.
A "435\r\n.\r\n" response indicates that the POST filter wishes the system to discard the article immediately. A "435 reason\r\n.\r\n" response indicates that the POST filter wishes the system to discard the article, returning the reason following the numeric code to the user as a reason for the rejection. A "235\r\n.\r\n" response indicates that the system should accept the article "as is". The last response option is a "235\r\n" response followed by an article header, a blank line ("\r\n"), and an article body, terminated by a ".\r\n". In this last response option, the returned article is substituted for the original article sent to the POST filter.
 | Backoff Post Filtering |
|---|---|
In addition to the 4 response codes listed above, "236 delay-time\r\n" and "436 delay-time\r\n" can be substituted for "235\r\n" and "435\r\n" in order to introduce a delay of "delay-time" seconds before responding to the user. This feature is VERY powerful as it allows you to implement a simple content neutral "Back-Off" filter for users that might be abusing your system |
By using the "235\r\n" followed by a header and body response, the POST filter can add additional headers or modify existing headers of an article.
It is important to remember that the filtering program should NOT exit. In addition, since the connection waits for the POST filter to make a decision about each article, speed is important.
For programmers, when writing a POST filter, be SURE to unbuffer and/or flush your "stdin" and "stdout" file descriptors. Otherwise, you will find it difficult to get your filter to work correctly.
Before being sent to the POST filter, the article will be syntax-checked and have its headers rewritten as necessary; the same checking is performed again if the POST filter rewrites an article. Although the POST filter will never see a Path line in an incoming article, if the POST filter creates a Path line in the article that Path line will be included (with necessary editing) when the article is sent upstream. Also, any Organization header set by the POST filter will be trusted, without regard to the Organization and ForceOrganization directives for the feed.
The "pipeline" through which local posts are sent:
Article syntax-checking and header enforcement
(when POST filter is present) POST filter
(when POST filter is present) Article syntax-checking and header enforcement
Upstream or moderator transmission and/or local saving
Data sent to the "stdin" of the POST filter:
IncomingFeedName: value\r\n Subscription: value\r\n FilterSubscription: value\r\n AllowReading: value\r\n AllowFeeding: value\r\n AllowPosting: value\r\n AllowNewNews: value\r\n SendXrefInOverviews: value\r\n WelcomeMessage: value\r\n Organization: value\r\n TimeOut: value\r\n HostConnectionLimit: value\r\n MaxIncomingNumberOfStreams: value\r\n Interface: value\r\n Cookie: value\r\n ConnectionTag: value\r\n IPAddress: value\r\n SessionID: session\r\n Hostname: value\r\n Username: value\r\n \r\n From: value\r\n Subject: value\r\n ... additional header fields (lines terminated with "\r\n") ... \r\n ... body of the article (lines terminated with "\r\n")... .\r\n |
The string value will be replaced by the appropriate value from the appropriate feed object or the header of the article. The SessionID is a unique string used to identify a particular connection. The same value will be sent by all posts origination from the connection, and it will also be sent to any authentication program being used.
As mentioned earlier, the system expects 1 of 4 responses on the "stdout" of the POST filter:
Table 9-1. Post Filter Response Codes
| Code | Description | |
|---|---|---|
| Indicates that the article should be discarded. (You could instead use a "436 10\r\n" on the first line to delay the response by 10 seconds.) | |
| indicates that the article should be discarded with "rejection reason" being returned to the client. (You could instead use a "436 10 rejection-reason\r\n" on the first line to delay the response by 10 seconds.) | |
| Indicates that the article should be accepted unmodified. (You could instead use a "236 10\r\n" on the first line to delay the response by 10 seconds.) | |
| Indicates that the returned article should be substituted and accepted instead of the original article. (You could instead use a "236 10\r\n" on the first line to delay the response by 10 seconds.) |