1Protocol::HTTP2::ClientU(s3eprm)Contributed Perl DocumenPtraottioocnol::HTTP2::Client(3pm)
2
6 Protocol::HTTP2::Client - HTTP/2 client
7
9 use Protocol::HTTP2::Client;
10 # Create client object
12 my $client = Protocol::HTTP2::Client->new;
13 # Prepare first request
15 $client->request(
16 # HTTP/2 headers
18 ':scheme' => 'http',
19 ':authority' => 'localhost:8000',
20 ':path' => '/',
21 ':method' => 'GET',
22 # HTTP/1.1 headers
24 headers => [
25 'accept' => '*/*',
26 'user-agent' => 'perl-Protocol-HTTP2/0.13',
27 ],
28 # Callback when receive server's response
30 on_done => sub {
31 my ( $headers, $data ) = @_;
32 ...
33 },
34 );
35 # Protocol::HTTP2 is just HTTP/2 protocol decoder/encoder
37 # so you must create connection yourself
38 use AnyEvent;
40 use AnyEvent::Socket;
41 use AnyEvent::Handle;
42 my $w = AnyEvent->condvar;
43 # Plain-text HTTP/2 connection
45 tcp_connect 'localhost', 8000, sub {
46 my ($fh) = @_ or die "connection failed: $!\n";
47 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 # First write preface to peer
64 while ( my $frame = $client->next_frame ) {
65 $handle->push_write($frame);
66 }
67 # Receive servers frames
69 # Reply to server
70 $handle->on_read(
71 sub {
72 my $handle = shift;
73 $client->feed( $handle->{rbuf} );
75 $handle->{rbuf} = undef;
77 while ( my $frame = $client->next_frame ) {
78 $handle->push_write($frame);
79 }
80 # Terminate connection if all done
82 $handle->push_shutdown if $client->shutdown;
83 }
84 );
85 };
86 $w->recv;
88
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 METHODS
94 new
95 Initialize new client object
97 my $client = Procotol::HTTP2::Client->new( %options );
99 Available options:
101 on_push => sub {...}
103 If server send push promise this callback will be invoked
104 on_push => sub {
106 # received PUSH PROMISE headers
107 my $pp_header = shift;
108 ...
109 # if we want reject this push
111 # return undef
112 # if we want to accept pushed resource
114 # return callback to receive data
115 return sub {
116 my ( $headers, $data ) = @_;
117 ...
118 }
119 },
120 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 See Starting HTTP/2 for "http" URIs
127 <https://tools.ietf.org/html/rfc7540#section-3.2>
128 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 on_error => sub {...}
134 Callback invoked on protocol errors
135 on_error => sub {
137 my $error = shift;
138 ...
139 },
140 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 on_change_state => sub {
146 my ( $stream_id, $previous_state, $current_state ) = @_;
147 ...
148 },
149 request
151 Prepare HTTP/2 request.
153 $client->request(
155 # HTTP/2 headers
157 ':scheme' => 'http',
158 ':authority' => 'localhost:8000',
159 ':path' => '/items',
160 ':method' => 'POST',
161 # HTTP/1.1 headers
163 headers => [
164 'content-type' => 'application/x-www-form-urlencoded',
165 'user-agent' => 'perl-Protocol-HTTP2/0.06',
166 ],
167 # Callback when receive server's response
169 on_done => sub {
170 my ( $headers, $data ) = @_;
171 ...
172 },
173 # Callback when receive stream reset
175 on_error => sub {
176 my $error_code = shift;
177 },
178 # Body of POST request
180 data => "hello=world&test=done",
181 );
182 You can chaining request one by one:
184 $client->request( 1-st request )->request( 2-nd request );
186 Available callbacks:
188 on_done => sub {...}
190 Invoked when full servers response is available
191 on_done => sub {
193 my ( $headers, $data ) = @_;
194 ...
195 },
196 on_headers => sub {...}
198 Invoked as soon as headers have been successfully received from the
199 server
200 on_headers => sub {
202 my $headers = shift;
203 ...
204 # if we want reject any data
206 # return undef
207 # continue
209 return 1
210 }
211 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 on_data => sub {
217 my ( $partial_data, $headers ) = @_;
218 ...
219 # if we want cancel download
221 # return undef
222 # continue downloading
224 return 1
225 }
226 on_error => sub {...}
228 Callback invoked on stream errors
229 on_error => sub {
231 my $error = shift;
232 ...
233 }
234 keepalive
236 Keep connection alive after requests
238 my $bool = $client->keepalive;
240 $client = $client->keepalive($bool);
241 shutdown
243 Get connection status:
245 0 - active
247 1 - closed (you can terminate connection)
248 close
250 Explicitly close connection (send GOAWAY frame). This is required if
252 client has keepalive option enabled.
253 next_frame
255 get next frame to send over connection to server. Returns:
257 undef - on error
259 0 - nothing to send
260 binary string - encoded frame
261 # Example
263 while ( my $frame = $client->next_frame ) {
264 syswrite $fh, $frame;
265 }
266 feed
268 Feed decoder with chunks of server's response
270 sysread $fh, $binary_data, 4096;
272 $client->feed($binary_data);
273 ping
275 Send ping frame to server (to keep connection alive)
277 $client->ping
279 or
281 $client->ping($payload);
283 Payload can be arbitrary binary string and must contain 8 octets. If
285 payload argument is omitted client will send random data.
286perl v5.36.0 2023-01-20 Protocol::HTTP2::Client(3pm)