NAME

Mail::DKIM2::HeaderParser - Streaming message parser base for Signer and Verifier

SYNOPSIS

# As a user of a Signer or Verifier:
$obj->PRINT($chunk) for @chunks;    # CRLF line endings
$obj->CLOSE;

$obj->load($message);               # one shot; LF is normalised

tie *FH, 'Mail::DKIM2::Verifier', SkipTimestampCheck => 1;
print FH $message;
close FH;
my $verifier = tied *FH;

# As a subclass:
package My::Parser;
use parent 'Mail::DKIM2::HeaderParser';
sub known_options { qw(Thing) }
sub handle_header { my ($self, $name, $value, $raw) = @_; ... }
sub finish_header { my $self = shift; ... }
sub finish_body   { my $self = shift; ... }

DESCRIPTION

Collects a message fed in pieces, splits it into header fields and body, and calls the subclass at each stage. Mail::DKIM2::Signer and Mail::DKIM2::Verifier are built on it; the conventions it implements are described in "CONVENTIONS" in Mail::DKIM2.

CONSTRUCTOR

new(%options)

Croaks on an option the class's known_options does not list, then calls init.

TIEHANDLE

tie *FH, $class, %options constructs an object; tie *FH, $class, $object uses an existing one. print FH, printf FH, syswrite FH and close FH then call PRINT, PRINTF, WRITE and CLOSE.

METHODS

PRINT(@bytes)

Feeds message data, in chunks of any size, with CRLF line endings exactly as the message has them; several arguments are concatenated. When the blank line ending the headers has been seen, the header fields are parsed and finish_header is called. Body data is kept until CLOSE unless the subclass has called stop.

malformed_header()

True once the header section has held a line that is not a header field: one with no colon, with nothing or white space before its colon, or a first line that starts with white space. Such a line is in no header hash, so a verifier must not pass the message and a signer must not sign it.

CLOSE()

Ends the message. Parses the headers if no blank line was seen, then calls finish_body unless stop was called.

load($input)

PRINT and CLOSE in one call. $input is the message as a string, a reference to one, a filehandle (read a piece at a time, to the end or until the parser has stopped), or an Email::MIME; any other reference croaks. Bare LF line endings are normalised to CRLF first, since every DKIM2 hash is defined over CRLF. Returns the object.

stop()

For a subclass that has reached its result from the headers alone, called from finish_header: the rest of the message is discarded unread and CLOSE does not call finish_body.

stopped()

True after stop.

SUBCLASS INTERFACE

known_options()

The list of CamelCase option names new accepts. Default none.

init()

Called by new after the options are stored in the object hash. Sets up the buffer and $self->{headers}, the arrayref of raw header lines in message order. A subclass that overrides it calls $self->SUPER::init.

handle_header($name, $value, $raw)

Called for each header field: its name, its value without the trailing line ending, and its complete raw text including any continuation lines.

finish_header()

Called once all header fields have been parsed.

finish_body()

Called from CLOSE, with the body in $self->{_buf}.

AUTHOR

Bron Gondwana <brong@fastmailteam.com>

COPYRIGHT AND LICENSE

Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.