NAME

Razor2::Client::Core - Network protocol engine for Vipul's Razor

SYNOPSIS

# Typically used via Razor2::Client::Agent, not directly
use Razor2::Client::Agent;

my $agent = Razor2::Client::Agent->new('razor-check');
# Core methods are inherited by Agent

DESCRIPTION

Razor2::Client::Core implements the Razor v2 network protocol: server discovery, connection management, signature computation, spam checking, reporting, revocation, and identity registration/authentication.

This module communicates with Razor catalogue servers (for checking) and nomination servers (for reporting/revoking) using a TCP-based protocol with SIS-encoded (Server Information String) messages.

Core inherits from Razor2::String, Razor2::Logger, Razor2::Client::Engine, and Razor2::Errorhandler.

METHODS

Connection Management

connect(%params)

Establishes a TCP connection to a Razor server. Supports direct connections, HTTP proxy tunneling (proxy config), and SOCKS proxies (socks_server config, requires Net::SOCKS).

Default port is 2703. Reads and parses the server greeting on connect. Automatically tries the next server on failure.

disconnect()

Sends a quit command and closes the connection.

nextserver()

Selects the next server from the current server list. If no servers remain, initiates server discovery. Loads per-server configuration from cached server.*.conf files.

Server Discovery

bootstrap_discovery()

Performs DNS-based discovery of Razor servers by querying TXT records for the razordiscovery zone. Used when no server lists exist.

discover($server)

Connects to a discovery server and retrieves current catalogue and nomination server lists.

Signature Operations

prepare_objects($mails)

Takes an array reference of mail scalar references and prepares them into internal objects with headers, body parts, and preprocessing applied.

compute_sigs($objects)

Computes spam signatures for each mail object using the configured engines. Requires server info (for engine parameters like ep4) to be loaded first via get_server_info().

Returns an array reference of printable signature strings.

Spam Checking

check($objects)

Sends computed signatures to the catalogue server and retrieves confidence values. Sets $obj->{spam} on each object based on the response.

check_logic($objects)

Applies the configured logic method to determine the final spam verdict for each mail object based on per-engine confidence values.

Reporting

report($objects)

Reports or revokes spam signatures with the nomination server. Requires prior authentication. Sends signatures in batched queries.

register($params)

Registers a new identity with the nomination server. $params is a hash reference with optional user and pass keys.

Returns a hash reference with the registered credentials on success.

authenticate($options)

Authenticates with the server using HMAC-SHA1 challenge-response. $options is a hash reference with user and pass keys. Attempts automatic re-registration on unknown user errors.

PROTOCOL

The Razor v2 protocol uses TCP connections (default port 2703) with SIS-encoded messages (URI-escaped key=value pairs separated by & and terminated by CRLF). Server discovery uses DNS TXT records.

The protocol version is defined in Razor2::Client::Version.

SEE ALSO

Razor2::Client::Agent, Razor2::Client::Config, Razor2::Client::Engine, Razor2::String

AUTHORS

Vipul Ved Prakash, <mail@vipul.net>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.