1Protocol::HTTP2::ServerU(s3eprm)Contributed Perl DocumenPtraottioocnol::HTTP2::Server(3pm)
2
3
4

NAME

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

SYNOPSIS

9           use Protocol::HTTP2::Server;
10
11           # You must create tcp server yourself
12           use AnyEvent;
13           use AnyEvent::Socket;
14           use AnyEvent::Handle;
15
16           my $w = AnyEvent->condvar;
17
18           # Plain-text HTTP/2 connection
19           tcp_server 'localhost', 8000, sub {
20               my ( $fh, $peer_host, $peer_port ) = @_;
21               my $handle;
22               $handle = AnyEvent::Handle->new(
23                   fh       => $fh,
24                   autocork => 1,
25                   on_error => sub {
26                       $_[0]->destroy;
27                       print "connection error\n";
28                   },
29                   on_eof => sub {
30                       $handle->destroy;
31                   }
32               );
33
34               # Create Protocol::HTTP2::Server object
35               my $server;
36               $server = Protocol::HTTP2::Server->new(
37                   on_request => sub {
38                       my ( $stream_id, $headers, $data ) = @_;
39                       my $message = "hello, world!";
40
41                       # Response to client
42                       $server->response(
43                           ':status' => 200,
44                           stream_id => $stream_id,
45
46                           # HTTP/1.1 Headers
47                           headers   => [
48                               'server'         => 'perl-Protocol-HTTP2/0.13',
49                               'content-length' => length($message),
50                               'cache-control'  => 'max-age=3600',
51                               'date'           => 'Fri, 18 Apr 2014 07:27:11 GMT',
52                               'last-modified'  => 'Thu, 27 Feb 2014 10:30:37 GMT',
53                           ],
54
55                           # Content
56                           data => $message,
57                       );
58                   },
59               );
60
61               # First send settings to peer
62               while ( my $frame = $server->next_frame ) {
63                   $handle->push_write($frame);
64               }
65
66               # Receive clients frames
67               # Reply to client
68               $handle->on_read(
69                   sub {
70                       my $handle = shift;
71
72                       $server->feed( $handle->{rbuf} );
73
74                       $handle->{rbuf} = undef;
75                       while ( my $frame = $server->next_frame ) {
76                           $handle->push_write($frame);
77                       }
78                       $handle->push_shutdown if $server->shutdown;
79                   }
80               );
81           };
82
83           $w->recv;
84

DESCRIPTION

86       Protocol::HTTP2::Server is HTTP/2 server library. It's intended to make
87       http2-server implementations on top of your favorite event loop.
88
89       See also Shuvgey <https://github.com/vlet/Shuvgey> - AnyEvent HTTP/2
90       Server for PSGI based on Protocol::HTTP2::Server.
91
92   METHODS
93       new
94
95       Initialize new server object
96
97           my $server = Procotol::HTTP2::Client->new( %options );
98
99       Available options:
100
101       on_request => sub {...}
102           Callback invoked when receiving client's requests
103
104               on_request => sub {
105                   # Stream ID, headers array reference and body of request
106                   my ( $stream_id, $headers, $data ) = @_;
107
108                   my $message = "hello, world!";
109                   $server->response(
110                       ':status' => 200,
111                       stream_id => $stream_id,
112                       headers   => [
113                           'server'         => 'perl-Protocol-HTTP2/0.13',
114                           'content-length' => length($message),
115                       ],
116                       data => $message,
117                   );
118                   ...
119               },
120
121       upgrade => 0|1
122           Use HTTP/1.1 Upgrade to upgrade protocol from HTTP/1.1 to HTTP/2.
123           Upgrade possible only on plain (non-tls) connection.
124
125           See Starting HTTP/2 for "http" URIs
126           <https://tools.ietf.org/html/rfc7540#section-3.2>
127
128       on_error => sub {...}
129           Callback invoked on protocol errors
130
131               on_error => sub {
132                   my $error = shift;
133                   ...
134               },
135
136       on_change_state => sub {...}
137           Callback invoked every time when http/2 streams change their state.
138           See Stream States <https://tools.ietf.org/html/rfc7540#section-5.1>
139
140               on_change_state => sub {
141                   my ( $stream_id, $previous_state, $current_state ) = @_;
142                   ...
143               },
144
145       response
146
147       Prepare response
148
149           my $message = "hello, world!";
150           $server->response(
151
152               # HTTP/2 status
153               ':status' => 200,
154
155               # Stream ID
156               stream_id => $stream_id,
157
158               # HTTP/1.1 headers
159               headers   => [
160                   'server'         => 'perl-Protocol-HTTP2/0.01',
161                   'content-length' => length($message),
162               ],
163
164               # Body of response
165               data => $message,
166           );
167
168       response_stream
169
170       If body of response is not yet ready or server will stream data
171
172           # P::H::Server::Stream object
173           my $server_stream;
174           $server_stream = $server->response_stream(
175
176               # HTTP/2 status
177               ':status' => 200,
178
179               # Stream ID
180               stream_id => $stream_id,
181
182               # HTTP/1.1 headers
183               headers   => [
184                   'server'         => 'perl-Protocol-HTTP2/0.01',
185               ],
186
187               # Callback if client abort this stream
188               on_cancel => sub {
189                   ...
190               }
191           );
192
193           # Send partial data
194           $server_stream->send($chunk_of_data);
195           $server_stream->send($chunk_of_data);
196
197           ## 3 ways to finish stream:
198           #
199           # The best: send last chunk and close stream in one action
200           $server_stream->last($chunk_of_data);
201
202           # Close the stream (will send empty frame)
203           $server_stream->close();
204
205           # Destroy object (will send empty frame)
206           undef $server_stream
207
208       push
209
210       Prepare Push Promise. See Server Push
211       <https://tools.ietf.org/html/rfc7540#section-8.2>
212
213           # Example of push inside of on_request callback
214           on_request => sub {
215               my ( $stream_id, $headers, $data ) = @_;
216               my %h = (@$headers);
217
218               # Push promise (must be before response)
219               if ( $h{':path'} eq '/index.html' ) {
220
221                   # index.html contain styles.css resource, so server can push
222                   # "/style.css" to client before it request it to increase speed
223                   # of loading of whole page
224                   $server->push(
225                       ':authority' => 'locahost:8000',
226                       ':method'    => 'GET',
227                       ':path'      => '/style.css',
228                       ':scheme'    => 'http',
229                       stream_id    => $stream_id,
230                   );
231               }
232
233               $server->response(...);
234               ...
235           }
236
237       shutdown
238
239       Get connection status:
240
241       0 - active
242       1 - closed (you can terminate connection)
243
244       next_frame
245
246       get next frame to send over connection to client.  Returns:
247
248       undef - on error
249       0 - nothing to send
250       binary string - encoded frame
251
252           # Example
253           while ( my $frame = $server->next_frame ) {
254               syswrite $fh, $frame;
255           }
256
257       feed
258
259       Feed decoder with chunks of client's request
260
261           sysread $fh, $binary_data, 4096;
262           $server->feed($binary_data);
263
264       ping
265
266       Send ping frame to client (to keep connection alive)
267
268           $server->ping
269
270       or
271
272           $server->ping($payload);
273
274       Payload can be arbitrary binary string and must contain 8 octets. If
275       payload argument is omitted server will send random data.
276
277
278
279perl v5.38.0                      2023-08-08      Protocol::HTTP2::Server(3pm)
Impressum