.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Duo::Exception 3pm" .TH Net::Duo::Exception 3pm "2021-01-09" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Duo::Exception \- Rich exception object for Net::Duo failures .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use 5.010; \& \& # Use by a caller of the Net::Duo API. \& my $duo = Net::Duo\->new({ key_file => \*(Aq/path/to/keys.json\*(Aq }); \& if (!eval { $duo\->check() }) { \& my $e = $@; \& say \*(AqCode: \*(Aq, $e\->code(); \& say \*(AqMessage: \*(Aq, $e\->message(); \& say \*(AqDetail: \*(Aq, $e\->detail(); \& print "\enFull reply content:\en", $e\->content(); \& } \& \& # Use internally by Net::Duo objects. \& die Net::Duo::Exception\->propagate($@); \& die Net::Duo::Exception\->internal(\*(Aqsome error message\*(Aq); \& my $response = some_http_call(); \& die Net::Duo::Exception\->http($response); \& my $reply = some_duo_call(); \& die Net::Duo::Exception\->protocol(\*(Aqerror message\*(Aq, $reply); \& die Net::Duo::Exception\->api($reply); .Ve .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" Perl 5.14 or later and the module HTTP::Message, which is available from \&\s-1CPAN.\s0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::Duo::Exception is a rich representation of errors from any Net::Duo \&\s-1API.\s0 All Net::Duo APIs throw Net::Duo::Exception objects on any failure, including internal errors, protocol errors, \s-1HTTP\s0 errors, and failures returned by the Duo \s-1API.\s0 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. .SH "CLASS METHODS" .IX Header "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. .IP "api(\s-1OBJECT, CONTENT\s0)" 4 .IX Item "api(OBJECT, CONTENT)" Creates an exception for a Duo \s-1API\s0 failure. \s-1OBJECT\s0 should be the \s-1JSON\s0 object (decoded as a hash) returned by the Duo \s-1API\s0 call, and \s-1CONTENT\s0 should be the undecoded text. This exception constructor should be used whenever possible, since it provides the most useful information. .IP "http(\s-1RESPONSE\s0)" 4 .IX Item "http(RESPONSE)" Creates an exception from an HTTP::Response object, \s-1RESPONSE.\s0 This exception constructor should be used for calls that fail at the \s-1HTTP\s0 protocol level without getting far enough to return \s-1JSON.\s0 .IP "internal(\s-1MESSAGE\s0)" 4 .IX Item "internal(MESSAGE)" Creates an exception for some internal failure that doesn't involve an \&\s-1HTTP\s0 request to the Duo \s-1API.\s0 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. .IP "propagate(\s-1EXCEPTION\s0)" 4 .IX Item "propagate(EXCEPTION)" Very similar to \fBinternal()\fR, 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 \fBinternal()\fR. .IP "protocol(\s-1MESSAGE, REPLY\s0)" 4 .IX Item "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 \s-1JSON\s0 or \&\s-1JSON\s0 with missing data fields. \s-1MESSAGE\s0 should be an informative error message, and \s-1REPLY\s0 should be the content of the unparsable reply. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" These are the methods most commonly called by programs that use the Net::Duo module. They return various information from the exception. .IP "\fBcode()\fR" 4 .IX Item "code()" Returns the Duo error code for this error, or 50000 for internally generated errors. The Duo code is conventionally an \s-1HTTP\s0 code followed by two additional digits to create a unique error code. .IP "\fBcontent()\fR" 4 .IX Item "content()" The full content of the reply from the Duo \s-1API\s0 that triggered the error. This is not included in the default string error message, but may be interesting when debugging problems. .IP "\fBdetail()\fR" 4 .IX Item "detail()" Any additional (generally short) detail that might clarify the error message. This corresponds to the \f(CW\*(C`message_detail\*(C'\fR key in the Duo error response. .IP "\fBmessage()\fR" 4 .IX Item "message()" The error message. .IP "spaceship([\s-1STRING\s0], [\s-1SWAP\s0])" 4 .IX Item "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 \s-1SWAP\s0 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 \f(CW\*(C`cmp\*(C'\fR implementation.) .IP "\fBto_string()\fR" 4 .IX Item "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. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2014 The Board of Trustees of the Leland Stanford Junior University .PP Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \*(L"Software\*(R"), 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: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\s0 \s-1IN 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.\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" Net::Duo .PP This module is part of the Net::Duo distribution. The current version of Net::Duo is available from \s-1CPAN,\s0 or directly from its web site at .