NAME

Net::Duo::Exception - Rich exception object for Net::Duo failures

SYNOPSIS

    use 5.010;
    # Use by a caller of the Net::Duo API.
    my $duo = Net::Duo->new({ key_file => '/path/to/keys.json' });
    if (!eval { $duo->check() }) {
        my $e = $@;
        say 'Code: ', $e->code();
        say 'Message: ', $e->message();
        say 'Detail: ', $e->detail();
        print "\nFull reply content:\n", $e->content();
    }
    # Use internally by Net::Duo objects.
    die Net::Duo::Exception->propagate($@);
    die Net::Duo::Exception->internal('some error message');
    my $response = some_http_call();
    die Net::Duo::Exception->http($response);
    my $reply = some_duo_call();
    die Net::Duo::Exception->protocol('error message', $reply);
    die Net::Duo::Exception->api($reply);

REQUIREMENTS

Perl 5.14 or later and the module HTTP::Message, which is available from CPAN.

DESCRIPTION

Net::Duo::Exception is a rich representation of errors from any Net::Duo API. All Net::Duo APIs throw Net::Duo::Exception objects on any failure, including internal errors, protocol errors, HTTP errors, and failures returned by the Duo API. This object carries all available details about the failure and can be inspected by the caller to recover additional information. If the caller doesn't care about the details, it provides a stringification that is suitable for simple error messages.

CLASS METHODS

All class methods are constructors. These are primarily for the internal use of Net::Duo classes to generate the exception and will normally not be called by users of Net::Duo. Each correspond to a type of error and tell Net::Duo::Exception what data to extract to flesh out the exception object.

api(OBJECT, CONTENT): Creates an exception for a Duo API failure. OBJECT should be the JSON object (decoded as a hash) returned by the Duo API call, and CONTENT should be the undecoded text. This exception constructor should be used whenever possible, since it provides the most useful information.
http(RESPONSE): Creates an exception from an HTTP::Response object, RESPONSE. This exception constructor should be used for calls that fail at the HTTP protocol level without getting far enough to return JSON.
internal(MESSAGE): Creates an exception for some internal failure that doesn't involve an HTTP request to the Duo API. In this case, the code will always be set to 50000: the normal 500 code for an internal server error plus the two additional digits Duo normally adds to the code.
propagate(EXCEPTION): Very similar to internal(), except that the argument is assumed to be another exception. The resulting error message will be cleaned of uninteresting location information before being passed to internal().
protocol(MESSAGE, REPLY): Creates an exception for a protocol failure. This should be used when a call returns unexpected or malformated data, such as invalid JSON or JSON with missing data fields. MESSAGE should be an informative error message, and REPLY should be the content of the unparsable reply.

INSTANCE METHODS

These are the methods most commonly called by programs that use the Net::Duo module. They return various information from the exception.

code(): Returns the Duo error code for this error, or 50000 for internally generated errors. The Duo code is conventionally an HTTP code followed by two additional digits to create a unique error code.
content(): The full content of the reply from the Duo API that triggered the error. This is not included in the default string error message, but may be interesting when debugging problems.
detail(): Any additional (generally short) detail that might clarify the error message. This corresponds to the "message_detail" key in the Duo error response.
message(): The error message.
spaceship([STRING], [SWAP]): This method is called if the exception object is compared to a string via cmp. It will compare the given string to the verbose error message and return the result. If SWAP is set, it will reverse the order to compare the given string to the verbose error. (This is the normal interface contract for an overloaded "cmp" implementation.)
to_string(): This method is called if the exception is interpolated into a string. It can also be called directly to retrieve the default string form of the exception.

AUTHOR

Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.