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.

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.

2026-04-06

perl v5.42.2