| :reserved |
fires exactly once when a push stream is initialized |
| :active |
fires exactly once when the stream become active and is counted towards the open stream limit |
| :headers |
fires once for each received header block (multi-frame blocks are reassembled before emitting this event) |
| :data |
fires once for every DATA frame (no buffering) |
| :half_close |
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) |
| :close |
fires exactly once when both peers close the stream, or if the stream is reset |
| :priority |
fires once for each received priority update (server only) |
### Prioritization
Each HTTP/2 [stream has a priority value](https://hpbn.co/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://hpbn.co/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://hpbn.co/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 Ilya Grigorik 