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

       Copyright 2014 The Board of Trustees of the Leland Stanford Junior University

       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.

SEE ALSO

       Net::Duo

       This module is part of the Net::Duo distribution.  The current version of Net::Duo is
       available from CPAN, or directly from its web site at
       <https://www.eyrie.org/~eagle/software/net-duo/>.