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
|
# Plum: An HTTP/2 Library for Ruby
A pure Ruby HTTP/2 server and client implementation.
WARNING: Plum is currently under heavy development. You *will* encounter bugs when using it.
[](https://circleci.com/gh/rhenium/plum) [](https://travis-ci.org/rhenium/plum) [](https://codeclimate.com/github/rhenium/plum) [](https://codeclimate.com/github/rhenium/plum/coverage)
## Requirements
* Ruby 2.3
* OpenSSL 1.0.2 or newer
* [http_parser.rb gem](https://rubygems.org/gems/http_parser.rb) - if you need HTTP/2 without TLS or HTTP/1.1 support
* [rack gem](https://rubygems.org/gems/rack) - if you use plum as a Rack server
## Installation
You can install via rubygems:
~~~sh
gem install plum
~~~
then require it:
~~~ruby
require "plum"
~~~
## Usage
* Documentation: http://www.rubydoc.info/gems/plum
* Some examples are in `examples/`
### As a Rack-compatible server
Most existing Rack-based applications should work without modification.
~~~ruby
# config.ru
App = -> env {
[
200,
{ "Content-Type" => "text/plain" },
["request: #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"]
]
}
run App
~~~
You can run it:
~~~sh
% plum -e production -p 8080 --https --cert server.crt --key server.key config.ru
~~~
NOTE: If `--cert` and `--key` are omitted, a temporary dummy certificate will be generated.
My website [https://rhe.jp](https://rhe.jp) is using plum as a Rack server.
### As a HTTP/2 (HTTP/1.x) client library
If the server doesn't support HTTP/2, it falls back to HTTP/1.1 seamlessly.
~~~
+-----------------+
|:https option | false
|(default: true) |-------> Try Upgrade from HTTP/1.1
+-----------------+
| true
v
+-----------------+
| ALPN | failed
| negotiation |-------> HTTP/1.x
+-----------------+
| "h2"
v
HTTP/2
~~~
##### Sequential request
~~~ruby
client = Plum::Client.start("http2.rhe.jp", user_agent: "nyaan")
res1 = client.get("/", headers: { "accept" => "*/*" }).join
puts res1.body # => "..."
res2 = client.post("/post", "data").join
puts res2.body # => "..."
client.get("/clockstream").on_headers { |res|
puts "status: #{res.status}, headers: #{res.headers}"
}.on_chunk { |chunk|
puts chunk
}.on_finish {
puts "finish!"
}.join
client.close
~~~
##### Parallel request
~~~ruby
res1 = res2 = nil
Plum::Client.start("rhe.jp", 443, http2_settings: { max_frame_size: 32768 }) { |client|
res1 = client.get("/")
res2 = client.post("/post", "data")
# res1.status == nil ; because it's async request
} # wait for response(s) and close
p res1.status # => "200"
~~~
##### Download a large file
~~~ruby
# the value of hostname option will be used in SNI and :authority header
Plum::Client.start("http2.rhe.jp", 443, hostname: "assets.rhe.jp") { |client|
client.get("/large") do |res| # called when received response headers
p res.status # => "200"
File.open("/tmp/large.file", "wb") { |file|
res.on_chunk do |chunk| # called when each chunk of response body arrived
file << chunk
end
}
end
}
~~~
## TODO
* Better API design
* Better server push support
* Stream priority support
Of course ideas and pull requests are welcome.
## Hacking
Clone this Git repository and run `bundle install` to install development dependencies. You can run test with `rake test`. The tests are written with Minitest.
## License
MIT License
|
