Net::D...ception(3pm)

💖 Net::Duo::Exception — the manual page, but make it cute 💖

okay bestie, pull up a chair, because we're talking about Net::Duo::Exception — the rich exception object for Net::Duo failures. yes, errors. yes, they're iconic. let's go. ✨

---

🌸 NAME 🌸

Net::Duo::Exception — a rich exception object for Net::Duo failures. it's giving "your error, but with lore." 👑

---

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

so there's two whole moods here: calling it as a user of the API (first block) and using it internally inside Net::Duo objects (second block). both ate. 💅

---

🎀 REQUIREMENTS 🎀

• Perl 5.14 or later — no ancient perls, we don't do that here.
• the module HTTP::Message, which you can grab from CPAN. 🛒

---

✨ DESCRIPTION ✨

Net::Duo::Exception is a rich representation of errors from any Net::Duo API. like, it's not just a sad little string, it's the whole vibe. 💅

so here's the tea: all Net::Duo APIs throw Net::Duo::Exception objects on any failure — that includes:

• internal errors
• protocol errors
• HTTP errors
• failures returned by the Duo API

this object carries all available details about the failure, and you (the caller) can inspect it to recover additional info. and if you literally don't care about the details? no worries bestie, it provides a stringification that's suitable for simple error messages. it's got range. 🌈

---

💖 CLASS METHODS 💖

okay so. all class methods are constructors</b>. these are primarily for the internal use of Net::Duo classes to generate the exception, so normally you, the user of Net::Duo, will not be calling them. ngl they're kind of the backstage crew. 🎭

each one corresponds to a type of error and tells Net::Duo::Exception what data to extract to flesh out the exception object. (flesh out. like a glow-up but for error data. 💅)

• 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. it's the main character of constructors, periodt. 👑
• http(RESPONSE) — creates an exception from an HTTP::Response object, RESPONSE. use this one for calls that fail at the HTTP protocol level without getting far enough to return JSON. it just never made it to the JSON part of the journey. 😭
• 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 — that's the normal 500 code for an internal server error plus the two additional digits Duo normally adds to the code. math, but make it error handling. 🧮
• propagate(EXCEPTION) — very similar to internal()</b>, 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(). it's like passing the message through a little filter. ✨
• protocol(MESSAGE, REPLY) — creates an exception for a protocol failure. use this 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. (yes, the reply is unparsable and we're being normal about it. 🙈)

---

🦋 INSTANCE METHODS 🦋

these are the methods most commonly called by programs that use the Net::Duo module. they return various information from the exception. the main character methods, if you will. 💅

• 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. so it's like 500 + 00 = mystery solved. 🔍
• 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. it's the director's cut. 🎬
• detail() — any additional (generally short) detail that might clarify the error message. this corresponds to the "message_detail" key in the Duo error response. it's the little footnote that explains everything. 📝
• message() — the error message. that's it. that's the method. short and sweet, we love her. 🫶
• 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.) yes the method is named spaceship. yes it's iconic. 🚀
• 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. your friendly neighborhood stringifier. ✨

---

💜 AUTHOR 💜

Russ Allbery <rra@cpan.org> — thank you for your service, king. 👑

---

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

bestie the ALL CAPS section is not me yelling at you, that's just how the license is written. it's legally required to be dramatic. 💀

---

🌈 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/>. go get it, it's free. 🛒

---

and that's the whole page, bestie!! 🎀 this was documented for perl v5.36.0, dated 2022-12-18, and it lives under the manual page name Net::D...ception(3pm) (the truncated girlies know 💅). mwah, go forth and catch your exceptions with style. 🫶✨