.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Razor2::Client::Core 3"
.TH Razor2::Client::Core 3 2026-04-06 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Razor2::Client::Core \- Network protocol engine for Vipul\*(Aqs Razor
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    # Typically used via Razor2::Client::Agent, not directly
\&    use Razor2::Client::Agent;
\&
\&    my $agent = Razor2::Client::Agent\->new(\*(Aqrazor\-check\*(Aq);
\&    # Core methods are inherited by Agent
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Razor2::Client::Core implements the Razor v2 network protocol: server
discovery, connection management, signature computation, spam checking,
reporting, revocation, and identity registration/authentication.
.PP
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.
.PP
Core inherits from Razor2::String, Razor2::Logger,
Razor2::Client::Engine, and Razor2::Errorhandler.
.SH METHODS
.IX Header "METHODS"
.SS "Connection Management"
.IX Subsection "Connection Management"
.IP \fBconnect(%params)\fR 4
.IX Item "connect(%params)"
Establishes a TCP connection to a Razor server.  Supports direct
connections, HTTP proxy tunneling (\f(CW\*(C`proxy\*(C'\fR config), and SOCKS proxies
(\f(CW\*(C`socks_server\*(C'\fR config, requires Net::SOCKS).
.Sp
Default port is 2703.  Reads and parses the server greeting on connect.
Automatically tries the next server on failure.
.IP \fBdisconnect()\fR 4
.IX Item "disconnect()"
Sends a quit command and closes the connection.
.IP \fBnextserver()\fR 4
.IX Item "nextserver()"
Selects the next server from the current server list.  If no servers
remain, initiates server discovery.  Loads per\-server configuration
from cached \fIserver.*.conf\fR files.
.SS "Server Discovery"
.IX Subsection "Server Discovery"
.IP \fBbootstrap_discovery()\fR 4
.IX Item "bootstrap_discovery()"
Performs DNS\-based discovery of Razor servers by querying TXT records
for the razordiscovery zone.  Used when no server lists exist.
.IP \fBdiscover($server)\fR 4
.IX Item "discover($server)"
Connects to a discovery server and retrieves current catalogue and
nomination server lists.
.SS "Signature Operations"
.IX Subsection "Signature Operations"
.IP \fBprepare_objects($mails)\fR 4
.IX Item "prepare_objects($mails)"
Takes an array reference of mail scalar references and prepares them
into internal objects with headers, body parts, and preprocessing
applied.
.IP \fBcompute_sigs($objects)\fR 4
.IX Item "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 \f(CWget_server_info()\fR.
.Sp
Returns an array reference of printable signature strings.
.SS "Spam Checking"
.IX Subsection "Spam Checking"
.IP \fBcheck($objects)\fR 4
.IX Item "check($objects)"
Sends computed signatures to the catalogue server and retrieves
confidence values.  Sets \f(CW\*(C`$obj\->{spam}\*(C'\fR on each object based
on the response.
.IP \fBcheck_logic($objects)\fR 4
.IX Item "check_logic($objects)"
Applies the configured logic method to determine the final spam
verdict for each mail object based on per\-engine confidence values.
.SS Reporting
.IX Subsection "Reporting"
.IP \fBreport($objects)\fR 4
.IX Item "report($objects)"
Reports or revokes spam signatures with the nomination server.
Requires prior authentication.  Sends signatures in batched queries.
.IP \fBregister($params)\fR 4
.IX Item "register($params)"
Registers a new identity with the nomination server.  \f(CW$params\fR is a
hash reference with optional \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`pass\*(C'\fR keys.
.Sp
Returns a hash reference with the registered credentials on success.
.IP \fBauthenticate($options)\fR 4
.IX Item "authenticate($options)"
Authenticates with the server using HMAC\-SHA1 challenge\-response.
\&\f(CW$options\fR is a hash reference with \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`pass\*(C'\fR keys.
Attempts automatic re\-registration on unknown user errors.
.SH PROTOCOL
.IX Header "PROTOCOL"
The Razor v2 protocol uses TCP connections (default port 2703) with
SIS\-encoded messages (URI\-escaped key=value pairs separated by \f(CW\*(C`&\*(C'\fR
and terminated by CRLF).  Server discovery uses DNS TXT records.
.PP
The protocol version is defined in Razor2::Client::Version.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Razor2::Client::Agent, Razor2::Client::Config,
Razor2::Client::Engine, Razor2::String
.SH AUTHORS
.IX Header "AUTHORS"
Vipul Ved Prakash, <mail@vipul.net>
.SH LICENSE
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.