aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKazuki Yamaguchi <k@rhe.jp>2016-05-08 15:42:34 +0900
committerKazuki Yamaguchi <k@rhe.jp>2016-05-08 15:42:34 +0900
commitc803f957cd0fed1ae65c2d1108b3e71b1c90fd38 (patch)
treeaac66db2d3e3ad69a38ff7c4c0a5fc4e76ba09a1
parentb528c96bba2f426356c6d960e7c571103471edd6 (diff)
downloadplum-c803f957cd0fed1ae65c2d1108b3e71b1c90fd38.tar.gz
readme: add newlines
Some Markdown parsers requires a new line after header.
-rw-r--r--README.md45
1 files changed, 31 insertions, 14 deletions
diff --git a/README.md b/README.md
index de36a33..9d26607 100644
--- a/README.md
+++ b/README.md
@@ -5,27 +5,34 @@ WARNING: Plum is currently under heavy development. You *will* encounter bugs wh
[![Circle CI](https://circleci.com/gh/rhenium/plum.svg?style=svg)](https://circleci.com/gh/rhenium/plum) [![Build Status](https://travis-ci.org/rhenium/plum.png?branch=master)](https://travis-ci.org/rhenium/plum) [![Code Climate](https://codeclimate.com/github/rhenium/plum/badges/gpa.svg)](https://codeclimate.com/github/rhenium/plum) [![Test Coverage](https://codeclimate.com/github/rhenium/plum/badges/coverage.svg)](https://codeclimate.com/github/rhenium/plum/coverage)
+
## Requirements
+
* Ruby 2.3
* OpenSSL 1.0.2 or newer (HTTP/2 requires ALPN)
* Optional:
* [http_parser.rb gem](https://rubygems.org/gems/http_parser.rb) (HTTP/1.x parser; if you use "http" URI scheme)
* [rack gem](https://rubygems.org/gems/rack) (if you use Plum as Rack server)
+
## Installation
-```sh
+
+~~~sh
gem install 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
+~~~ruby
# config.ru
App = -> env {
[
@@ -36,20 +43,21 @@ App = -> env {
}
run App
-```
+~~~
You can run it:
-```sh
+~~~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.
+
### As a HTTP/2 (HTTP/1.x) client library
If the server does't support HTTP/2, `Plum::Client` tries to use HTTP/1.x instead.
-```
+~~~
+-----------------+
|:https option | false
|(default: true) |-------> Try Upgrade from HTTP/1.1
@@ -63,10 +71,12 @@ If the server does't support HTTP/2, `Plum::Client` tries to use HTTP/1.x instea
| "h2"
v
HTTP/2
-```
+~~~
+
##### Sequential request
-```ruby
+
+~~~ruby
client = Plum::Client.start("http2.rhe.jp", user_agent: "nyaan")
res1 = client.get("/", headers: { "accept" => "*/*" }).join
puts res1.body # => "..."
@@ -74,10 +84,12 @@ res2 = client.post("/post", "data").join
puts res2.body # => "..."
client.close
-```
+~~~
+
##### Parallel request
-```ruby
+
+~~~ruby
res1 = res2 = nil
Plum::Client.start("rhe.jp", 443, http2_settings: { max_frame_size: 32768 }) { |client|
res1 = client.get("/")
@@ -86,10 +98,12 @@ Plum::Client.start("rhe.jp", 443, http2_settings: { max_frame_size: 32768 }) { |
} # wait for response(s) and close
p res1.status # => "200"
-```
+~~~
+
##### Download a large file
-```ruby
+
+~~~ruby
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"
@@ -100,9 +114,11 @@ Plum::Client.start("http2.rhe.jp", 443, hostname: "assets.rhe.jp") { |client|
}
end
}
-```
+~~~
+
## TODO
+
* **Better API**
* Plum::Client
* PING frame handling
@@ -110,5 +126,6 @@ Plum::Client.start("http2.rhe.jp", 443, hostname: "assets.rhe.jp") { |client|
* Stream Priority support
* Better HTTP/1.x support
+
## License
MIT License