Razor2::Client::Core(3)

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.