Net::HTTPS::NB(3pm)

💖 Net::HTTPS::NB — the non-blocking HTTPS client bestie, aka Net::HTTPS::NB(3pm) 💖

okay so imagine a Perl module that's literally the same vibe as Net::HTTPS but NEVER tries multiple reads when you call read_response_headers() or read_entity_body() — no cap, it's giving patience. and it ALSO lets you do non-blocking connect?? main character energy fr fr. this is that module. welcome to the group chat 🫶

---

✨ SYNOPSIS ✨

bestie, here's how you slide into a request and receive a response:

use strict;
use Net::HTTPS::NB;
use IO::Select;
use Errno qw/EAGAIN EWOULDBLOCK/;

my $s = Net::HTTPS::NB->new(Host => "pause.perl.org") || die $@;
$s->write_request(GET => "/");

my $sel = IO::Select->new($s);

READ_HEADER: {
        die "Header timeout" unless $sel->can_read(10);
        my($code, $mess, %h) = $s->read_response_headers;
        redo READ_HEADER unless $code;
}

# Net::HTTPS::NB uses internal buffer for reading
# so we should check it before socket check by calling read_entity_body()
# it is error to wait data on socket before read_entity_body() will return undef
# with $! set to EAGAIN or EWOULDBLOCK
# make socket non-blocking, so read_entity_body() will not block
$s->blocking(0);

while (1) {
        my $buf;
        my $n;
        # try to read until error or all data received
        while (1) {
                my $tmp_buf;
                $n = $s->read_entity_body($tmp_buf, 1024);
                if ($n == -1 || (!defined($n) && ($! == EWOULDBLOCK || $! == EAGAIN))) {
                        last; # no data available this time
                }
                elsif ($n) {
                        $buf .= $tmp_buf; # data received
                }
                elsif (defined $n) {
                        last; # $n == 0, all readed
                }
                else {
                        die "Read error occured: ", $!; # $n == undef
                }
        }

        print $buf if length $buf;
        last if defined $n && $n == 0; # all readed
        die "Body timeout" unless $sel->can_read(10); # wait for new data
}

and here's the non-blocking connect moment, because sometimes you gotta be all "i'm on my way" before you actually arrive 💅:

use strict;
use Net::HTTPS::NB;
use IO::Select;

my $sock = Net::HTTPS::NB->new(Host => 'encrypted.google.com', Blocking => 0);
my $sele = IO::Select->new($sock);

until ($sock->connected) {
        if ($HTTPS_ERROR == HTTPS_WANT_READ) {
                $sele->can_read();
        }
        elsif($HTTPS_ERROR == HTTPS_WANT_WRITE) {
                $sele->can_write();
        }
        else {
                die 'Unknown error: ', $HTTPS_ERROR;
        }
}

there's literally a whole examples subdirectory if you want more examples — go look, iykyk 🦋

---

🌸 DESCRIPTION 🌸

same interface as Net::HTTPS, but it will NEVER try multiple reads when you invoke the read_response_headers() or read_entity_body() methods. it's lowkey so respectful of your time. highkey also allows non-blocking connect.

if read_response_headers() didn't see enough data to complete the headers, you get back an empty list. that's it. that's the tea.

if read_entity_body() didn't see new entity data in its read, you get -1. periodt. 🔥

---

🎀 PACKAGE CONSTANTS 🎀

imported by default, bestie:

HTTPS_WANT_READ
HTTPS_WANT_WRITE

---

🧚 PACKAGE VARIABLES 🧚

also imported by default (they really said "here, take everything"):

$HTTPS_ERROR

---

👑 METHODS 👑

new(%cfg)

same as Net::HTTPS::new, BUT with a bonus Blocking parameter. set it to 0 and you can do a non-blocking connect — it's giving "i'll be there when i get there." use connected() to find out when the connection actually completed, no guessing needed ✨

connected()

returns a true value when the connection is done (like, https handshake fully done done). otherwise returns false. in that case, check $HTTPS_ERROR to figure out what the handshake needs — read or write. $HTTPS_ERROR is gonna be HTTPS_WANT_READ or HTTPS_WANT_WRITE respectively. peep the SYNOPSIS if you need the visual. 🫶

blocking($flag)

okay so, as opposed to Net::HTTPS where the blocking method is consciously broken (im sorry, it's true), here you CAN set socket blocking. for example, you can return the socket to blocking state after a non-blocking connect. slay for flexibility 💜

---

🌈 SEE ALSO 🌈

• Net::HTTP
• Net::HTTP::NB
• Net::HTTPS

---

💜 COPYRIGHT 💜

Copyright 2011-2015 Oleg G <oleg@cpan.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

a little sign-off from me to you: this page is from perl v5.34.0, dated 2022-06-16 — iconic behavior from the Perl docs team. stay non-blocking, bestie 💅✨💖