1Protocol::HTTP2::ClientU(s3eprm)Contributed Perl DocumenPtraottioocnol::HTTP2::Client(3pm)
2
3
4

NAME

6       Protocol::HTTP2::Client - HTTP/2 client
7

SYNOPSIS

9           use Protocol::HTTP2::Client;
10
11           # Create client object
12           my $client = Protocol::HTTP2::Client->new;
13
14           # Prepare first request
15           $client->request(
16
17               # HTTP/2 headers
18               ':scheme'    => 'http',
19               ':authority' => 'localhost:8000',
20               ':path'      => '/',
21               ':method'    => 'GET',
22
23               # HTTP/1.1 headers
24               headers      => [
25                   'accept'     => '*/*',
26                   'user-agent' => 'perl-Protocol-HTTP2/0.13',
27               ],
28
29               # Callback when receive server's response
30               on_done => sub {
31                   my ( $headers, $data ) = @_;
32                   ...
33               },
34           );
35
36           # Protocol::HTTP2 is just HTTP/2 protocol decoder/encoder
37           # so you must create connection yourself
38
39           use AnyEvent;
40           use AnyEvent::Socket;
41           use AnyEvent::Handle;
42           my $w = AnyEvent->condvar;
43
44           # Plain-text HTTP/2 connection
45           tcp_connect 'localhost', 8000, sub {
46               my ($fh) = @_ or die "connection failed: $!\n";
47
48               my $handle;
49               $handle = AnyEvent::Handle->new(
50                   fh       => $fh,
51                   autocork => 1,
52                   on_error => sub {
53                       $_[0]->destroy;
54                       print "connection error\n";
55                       $w->send;
56                   },
57                   on_eof => sub {
58                       $handle->destroy;
59                       $w->send;
60                   }
61               );
62
63               # First write preface to peer
64               while ( my $frame = $client->next_frame ) {
65                   $handle->push_write($frame);
66               }
67
68               # Receive servers frames
69               # Reply to server
70               $handle->on_read(
71                   sub {
72                       my $handle = shift;
73
74                       $client->feed( $handle->{rbuf} );
75
76                       $handle->{rbuf} = undef;
77                       while ( my $frame = $client->next_frame ) {
78                           $handle->push_write($frame);
79                       }
80
81                       # Terminate connection if all done
82                       $handle->push_shutdown if $client->shutdown;
83                   }
84               );
85           };
86
87           $w->recv;
88

DESCRIPTION

90       Protocol::HTTP2::Client is HTTP/2 client library. It's intended to make
91       http2-client implementations on top of your favorite event-loop.
92
93   METHODS
94       new
95
96       Initialize new client object
97
98           my $client = Procotol::HTTP2::Client->new( %options );
99
100       Available options:
101
102       on_push => sub {...}
103           If server send push promise this callback will be invoked
104
105               on_push => sub {
106                   # received PUSH PROMISE headers
107                   my $pp_header = shift;
108                   ...
109
110                   # if we want reject this push
111                   # return undef
112
113                   # if we want to accept pushed resource
114                   # return callback to receive data
115                   return sub {
116                       my ( $headers, $data ) = @_;
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. Default value
124           is 0.
125
126           See Starting HTTP/2 for "http" URIs
127           <https://tools.ietf.org/html/rfc7540#section-3.2>
128
129       keepalive => 0|1
130           Keep connection alive after requests. Default value is 0. Don't
131           forget to explicitly call close method if set this to true.
132
133       on_error => sub {...}
134           Callback invoked on protocol errors
135
136               on_error => sub {
137                   my $error = shift;
138                   ...
139               },
140
141       on_change_state => sub {...}
142           Callback invoked every time when http/2 streams change their state.
143           See Stream States <https://tools.ietf.org/html/rfc7540#section-5.1>
144
145               on_change_state => sub {
146                   my ( $stream_id, $previous_state, $current_state ) = @_;
147                   ...
148               },
149
150       request
151
152       Prepare HTTP/2 request.
153
154           $client->request(
155
156               # HTTP/2 headers
157               ':scheme'    => 'http',
158               ':authority' => 'localhost:8000',
159               ':path'      => '/items',
160               ':method'    => 'POST',
161
162               # HTTP/1.1 headers
163               headers      => [
164                   'content-type' => 'application/x-www-form-urlencoded',
165                   'user-agent' => 'perl-Protocol-HTTP2/0.06',
166               ],
167
168               # Callback when receive server's response
169               on_done => sub {
170                   my ( $headers, $data ) = @_;
171                   ...
172               },
173
174               # Callback when receive stream reset
175               on_error => sub {
176                   my $error_code = shift;
177               },
178
179               # Body of POST request
180               data => "hello=world&test=done",
181           );
182
183       You can chaining request one by one:
184
185           $client->request( 1-st request )->request( 2-nd request );
186
187       Available callbacks:
188
189       on_done => sub {...}
190           Invoked when full servers response is available
191
192               on_done => sub {
193                   my ( $headers, $data ) = @_;
194                   ...
195               },
196
197       on_headers => sub {...}
198           Invoked as soon as headers have been successfully received from the
199           server
200
201               on_headers => sub {
202                   my $headers = shift;
203                   ...
204
205                   # if we want reject any data
206                   # return undef
207
208                   # continue
209                   return 1
210               }
211
212       on_data => sub {...}
213           If specified all data will be passed to this callback instead if
214           on_done.  on_done will receive empty string.
215
216               on_data => sub {
217                   my ( $partial_data, $headers ) = @_;
218                   ...
219
220                   # if we want cancel download
221                   # return undef
222
223                   # continue downloading
224                   return 1
225               }
226
227       on_error => sub {...}
228           Callback invoked on stream errors
229
230               on_error => sub {
231                   my $error = shift;
232                   ...
233               }
234
235       keepalive
236
237       Keep connection alive after requests
238
239           my $bool = $client->keepalive;
240           $client = $client->keepalive($bool);
241
242       shutdown
243
244       Get connection status:
245
246       0 - active
247       1 - closed (you can terminate connection)
248
249       close
250
251       Explicitly close connection (send GOAWAY frame). This is required if
252       client has keepalive option enabled.
253
254       next_frame
255
256       get next frame to send over connection to server.  Returns:
257
258       undef - on error
259       0 - nothing to send
260       binary string - encoded frame
261
262           # Example
263           while ( my $frame = $client->next_frame ) {
264               syswrite $fh, $frame;
265           }
266
267       feed
268
269       Feed decoder with chunks of server's response
270
271           sysread $fh, $binary_data, 4096;
272           $client->feed($binary_data);
273
274       ping
275
276       Send ping frame to server (to keep connection alive)
277
278           $client->ping
279
280       or
281
282           $client->ping($payload);
283
284       Payload can be arbitrary binary string and must contain 8 octets. If
285       payload argument is omitted client will send random data.
286
287
288
289perl v5.36.0                      2023-01-20      Protocol::HTTP2::Client(3pm)
Impressum