/ 
Unblock-HTTP1-0.12
/ Unblock::HTTP1

NAME

Unblock::HTTP1 - Portable non-blocking HTTP/1.0 and HTTP/1.1 engine

SYNOPSIS

Server application:

use Unblock::HTTP1::Server;

my $server = Unblock::HTTP1::Server->new(
    transport => $stream,
    on_request => sub {
        my ($tx, $request) = @_;
        $tx->respond(status => 200, body => "hello\n");
    },
);

Client application:

use Unblock::HTTP1::Client;

my $client = Unblock::HTTP1::Client->new(transport => $stream);
$client->request(
    method => 'GET', target => '/', authority => 'example.test',
    on_response => sub {
        my ($tx, $response) = @_;
        print $response->status, "\n";
    },
);

The $stream shown above is an integration-owned framework connection object implementing three small output methods. For complete, copyable IO::Async and AnyEvent examples, start with Unblock::HTTP1::Integration.

DESCRIPTION

Unblock::HTTP1 parses and serializes HTTP/1.0 and HTTP/1.1. It supports persistent connections, request and response streaming, trailers, informational responses, Upgrade, and CONNECT.

The engine does not create sockets, handle DNS, negotiate TLS, choose an event loop, or manage connection pools.

Each Unblock::HTTP1::Server or Unblock::HTTP1::Client owns HTTP protocol state for one connection. A Unblock::HTTP1::Transaction represents one request and its response.

Canonical messages are Uniform::HTTP::Request and Uniform::HTTP::Response. Normal application code may pass named request or response fields instead of constructing Uniform objects explicitly. Existing Uniform objects continue to work.

HOW TO CONNECT IT

The normal integration style attaches an object from the event framework that implements:

unblock_send($bytes)
unblock_finish()
unblock_abort($reason)

Incoming bytes go to input(), EOF goes to input_eof(), and a transport failure goes to transport_error().

The engine automatically hands off output through unblock_send(), including output generated later by an asynchronous application callback.

Advanced integrations can omit transport and use the original want_write() and output() methods. Native transports can use the borrowed-input C ABI through Unblock::HTTP1::NativeABI.

For the precise host contract, backpressure, shutdown, switching and working framework subclasses, see Unblock::HTTP1::Integration.

PUBLIC CLASSES

Unblock::HTTP1::Server

HTTP/1 server connection, callbacks, response handling and pipelining.

Unblock::HTTP1::Client

HTTP/1 client connection, requests, response callbacks and serial request queueing.

Unblock::HTTP1::Transaction

One exchange, body writing, completion, errors and cancellation.

Unblock::HTTP1::Integration

Start-here guide for applications and framework integration authors.

Unblock::HTTP1::NativeABI

Optional native borrowed-buffer input interface.

LICENSE

MIT License.