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

       Russ Allbery <rra@cpan.org>

       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.

       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.

       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.

       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.

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

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

       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/>.

perl v5.36.0                                       2022-12-18                           Net::Duo::Exception(3pm)

           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);