/ 
Web-Authn-v0.2.2
/ Web::Authn::Exception

NAME

Web::Authn::Exception - Exception object for Web::Authn

SYNOPSIS

use Web::Authn;

# Exceptions are created automatically by the error() method in various modules
my $authn = Web::Authn->new;
if( !defined( $authn ) )
{
    my $err = Web::Authn->error;  # Web::Authn::Exception object

    # Stringify (overloaded):
    warn "$err";

    printf( "Error: %s\n", $err->message );
    printf( "  at %s line %d\n", $err->file, $err->line );

    # Individual fields:
    printf "Message : %s", $err->message;  # some error message
    printf "File    : %s", $err->file;     # "Foo.pm"
    printf "Line    : %d", $err->line;     # 5
    printf "Code    : %s", $err->code // 'n/a';  # optional error code
}

# Exception object propagates through method chains
# When a method fails, it returns a NullObject in chaining (object) context
# so the chain does not die with "Can't call method on undef":
my $result = Web::Authn->new( %bad_args )->other_method ||
    die( Web::Authn->error );

# pass_error: forwarding an existing exception
sub my_helper
{
    my $self = shift( @_ );
    my $authn = Web::Authn->new ||
        return( $self->pass_error( Web::Authn->error ) );  # re-raise exception
    return( $authn );
}

my $obj = My::Class->new->my_helper ||
    die( My::Class->error );

# Fatal mode: turn warnings into exceptions
my $authn2 = Web::Authn->new;
$authn2->fatal(1);  # any subsequent error will die() instead of warn()

VERSION

v0.2.0

DESCRIPTION

Web::Authn::Exception is a lightweight exception class used internally by Web::Authn. It is created automatically by the error() method and stored both on the object and in a package-level $ERROR variable.

Unlike regular modules, Web::Authn never calls die directly (except via throw()). Instead, error conditions set the exception and return undef in scalar context, or an empty list in list context.

CONSTRUCTOR

new

my $ex = Web::Authn::Exception->new( 'something went wrong' );
my $ex = Web::Authn::Exception->new({
    message     => 'something went wrong',
    code        => 400,
    skip_frames => 1,
});
my $ex = Web::Authn::Exception->new(
    message => 'something went wrong',
    code    => 400,
);

Accepts a plain string (used as message) or named parameters as a flat list or a single hash reference with the following keys:

  • code

    This argument is optional. It is a string or an integer: an application error code. It defaults to undef.

  • file

    This argument is optional. It is a string: the source file where the error originated. It is filled in from caller if you omit it.

  • line

    This argument is optional. It is an integer: the line number. It is filled in from caller if you omit it.

  • message

    This argument is optional. It is a string: the human-readable error text. It defaults to the empty string. When new is called with a single non-hash argument, that argument is used as message.

  • package

    This argument is optional. It is a string: the package name. It is filled in from caller if you omit it.

  • skip_frames

    This argument is optional. It is an integer: how many extra caller frames to skip when auto-detecting location. It defaults to 0.

METHODS

as_string

print $ex->as_string;

Returns the stringified form of the exception, including file and line information. This method is also invoked by the "" overload. It takes no arguments.

code

$ex->code(400);
my $code = $ex->code;

Set or get the error code. It returns the current value.

file

my $file = $ex->file;

Returns the source file associated with the exception.

line

my $line = $ex->line;

Returns the line number associated with the exception.

message

my $text = $ex->message;
$ex->messsage( "I found some error:", $some_data );

Set or get the error message. It returns the current value.

It takes a string, or a list of strings which will be concatenated.

package

my $pkg = $ex->package;

Returns the package name associated with the exception.

rethrow

$ex->rethrow;

Calls "die" in perlfunc with the exception object. It must be invoked on an instance; Web::Authn::Exception->rethrow returns undef. It takes no arguments.

This is ok :

$ex->rethrow;

But this is not :

Web::Authn::Exception->rethrow;

throw

Web::Authn::Exception->throw( 'something went wrong' );
Web::Authn::Exception->throw({ message => 'bad', code => 400 });
$ex->throw;

Creates a new exception (same arguments as "new") and immediately calls "die" in perlfunc with it. Called on an instance with no arguments, dies with that instance.

PROPAGATE

This method is called by perl when you call "die" in perlfunc with no parameters and $@ is set to a Web::Authn::Exception object.

This returns a new exception object that perl will use to replace the value in $@

TO_JSON

my $json = encode_json({ error => $ex });

Special method called by JSON to transform this object into a string suitable to be added in a json data.

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

SUBCLASSES

Web::Authn::Exception::InvalidRegistration
Web::Authn::Exception::InvalidAuthentication
Web::Authn::Exception::InvalidStructure
Web::Authn::Exception::UnsupportedAlgorithm
Web::Authn::Exception::InvalidCertificateChain

THREAD & PROCESS SAFETY

This module is designed to be fully thread-safe and process-safe, ensuring data integrity across Perl ithreads and mod_perl’s threaded Multi-Processing Modules (MPMs) such as Worker or Event.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Web::Authn

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

All rights reserved.

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