Protocol::HTTP2::Server - HTTP/2 server

NAME  SYNOPSIS  DESCRIPTION  METHODS 

---

NAME

Protocol::HTTP2::Server − HTTP/2 server

SYNOPSIS

use Protocol::HTTP2::Server;
# You must create tcp server yourself
use AnyEvent;
use AnyEvent::Socket;
use AnyEvent::Handle;
my $w = AnyEvent−>condvar;
# Plain−text HTTP/2 connection
tcp_server 'localhost', 8000, sub {
my ( $fh, $peer_host, $peer_port ) = @_;
my $handle;
$handle = AnyEvent::Handle−>new(
fh => $fh,
autocork => 1,
on_error => sub {
$_[0]−>destroy;
print "connection error\n";
},
on_eof => sub {
$handle−>destroy;
}
);
# Create Protocol::HTTP2::Server object
my $server;
$server = Protocol::HTTP2::Server−>new(
on_request => sub {
my ( $stream_id, $headers, $data ) = @_;
my $message = "hello, world!";
# Response to client
$server−>response(
':status' => 200,
stream_id => $stream_id,
# HTTP/1.1 Headers
headers => [
'server' => 'perl−Protocol−HTTP2/0.13',
'content−length' => length($message),
'cache−control' => 'max−age=3600',
'date' => 'Fri, 18 Apr 2014 07:27:11 GMT',
'last−modified' => 'Thu, 27 Feb 2014 10:30:37 GMT',
],
# Content
data => $message,
);
},
);
# First send settings to peer
while ( my $frame = $server−>next_frame ) {
$handle−>push_write($frame);
}
# Receive clients frames
# Reply to client
$handle−>on_read(
sub {
my $handle = shift;
$server−>feed( $handle−>{rbuf} );
$handle−>{rbuf} = undef;
while ( my $frame = $server−>next_frame ) {
$handle−>push_write($frame);
}
$handle−>push_shutdown if $server−>shutdown;
}
);
};
$w−>recv;

DESCRIPTION

Protocol::HTTP2::Server is HTTP/2 server library. It’s intended to make http2−server implementations on top of your favorite event loop.

See also Shuvgey <https://github.com/vlet/Shuvgey> − AnyEvent HTTP/2 Server for PSGI based on Protocol::HTTP2::Server.

METHODS

new

Initialize new server object

my $server = Procotol::HTTP2::Client−>new( %options );

Available options:
on_request => sub {...}

Callback invoked when receiving client’s requests

on_request => sub {
# Stream ID, headers array reference and body of request
my ( $stream_id, $headers, $data ) = @_;
my $message = "hello, world!";
$server−>response(
':status' => 200,
stream_id => $stream_id,
headers => [
'server' => 'perl−Protocol−HTTP2/0.13',
'content−length' => length($message),
],
data => $message,
);
...
},

upgrade => 0|1

Use HTTP/1.1 Upgrade to upgrade protocol from HTTP/1.1 to HTTP/2. Upgrade possible only on plain (non-tls) connection.

See Starting HTTP/2 for "http" URIs <https://tools.ietf.org/html/rfc7540#section-3.2>

on_error => sub {...}

Callback invoked on protocol errors

on_error => sub {
my $error = shift;
...
},

on_change_state => sub {...}

Callback invoked every time when http/2 streams change their state. See Stream States <https://tools.ietf.org/html/rfc7540#section-5.1>

on_change_state => sub {
my ( $stream_id, $previous_state, $current_state ) = @_;
...
},

response

Prepare response

my $message = "hello, world!";
$server−>response(
# HTTP/2 status
':status' => 200,
# Stream ID
stream_id => $stream_id,
# HTTP/1.1 headers
headers => [
'server' => 'perl−Protocol−HTTP2/0.01',
'content−length' => length($message),
],
# Body of response
data => $message,
);

response_stream

If body of response is not yet ready or server will stream data

# P::H::Server::Stream object
my $server_stream;
$server_stream = $server−>response_stream(
# HTTP/2 status
':status' => 200,
# Stream ID
stream_id => $stream_id,
# HTTP/1.1 headers
headers => [
'server' => 'perl−Protocol−HTTP2/0.01',
],
# Callback if client abort this stream
on_cancel => sub {
...
}
);
# Send partial data
$server_stream−>send($chunk_of_data);
$server_stream−>send($chunk_of_data);
## 3 ways to finish stream:
#
# The best: send last chunk and close stream in one action
$server_stream−>last($chunk_of_data);
# Close the stream (will send empty frame)
$server_stream−>close();
# Destroy object (will send empty frame)
undef $server_stream

push

Prepare Push Promise. See Server Push <https://tools.ietf.org/html/rfc7540#section-8.2>

# Example of push inside of on_request callback
on_request => sub {
my ( $stream_id, $headers, $data ) = @_;
my %h = (@$headers);
# Push promise (must be before response)
if ( $h{':path'} eq '/index.html' ) {
# index.html contain styles.css resource, so server can push
# "/style.css" to client before it request it to increase speed
# of loading of whole page
$server−>push(
':authority' => 'locahost:8000',
':method' => 'GET',
':path' => '/style.css',
':scheme' => 'http',
stream_id => $stream_id,
);
}
$server−>response(...);
...
}

shutdown

Get connection status:
0 − active
1 − closed (you can terminate connection)

next_frame

get next frame to send over connection to client. Returns:
undef − on error
0 − nothing to send
binary string − encoded frame

# Example
while ( my $frame = $server−>next_frame ) {
syswrite $fh, $frame;
}

feed

Feed decoder with chunks of client’s request

sysread $fh, $binary_data, 4096;
$server−>feed($binary_data);

ping

Send ping frame to client (to keep connection alive)

$server−>ping

or

$server−>ping($payload);

Payload can be arbitrary binary string and must contain 8 octets. If payload argument is omitted server will send random data.

---