plum 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4fae3d5fc60fdcda63be201fe0349e497ed0c4a2
-  data.tar.gz: e9a1ac852f57acfef9d1eb9585c5b5cca427ce3c
+  metadata.gz: a3f442db964b9973db192c37a12de8bb3bc496aa
+  data.tar.gz: 9281279f7c35289c91222329ac09efcd6cfcf4b4
 SHA512:
-  metadata.gz: 0f66ed1a0dda7c39d14b0126d871b0c9978069c2b1a27bcb541d9dc9e0e5c0654d86439ff5c27a650d877f827a3a924ee20028f38245d5a9ceb09f3f69a1998c
-  data.tar.gz: 95a3eb71873bb321e4ee683820b4057205a2fde167d38b1e09f605f0dd70e606f0ba6f67e1b3fd6d9a6a08e12c77167d1aee32cd7bec034278892f33651c682f
+  metadata.gz: 1d11fb0f5189dc3b6e33b24aa92a4c6325ac4e58104f44acfa4ec5ba900a14eea58cd6cca6f0c3e4de31e406aac88a9be64eeceae7901a175819b9637b5f28fb
+  data.tar.gz: 97d592aee10b6a329791c25a388e329957deaac1178f40258adc5f907ab00ee44a0c2c8e924b5197167acacc4b4f5842369cf2640112f00fcac8a24582d20483

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in plum.gemspec
 gemspec

data/README.md

@@ -1,16 +1,45 @@
 # 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)
-A minimal implementation of HTTP/2 server.
-
-## Examples
-* examples/ - Minimal usage.
-* [rhenium/plum-server](https://github.com/rhenium/plum-server) - A example server for https://rhe.jp and http://rhe.jp.
+A minimal pure Ruby implementation of HTTP/2 library / server.
 
 ## Requirements
 * Ruby
   * Ruby 2.2 with [ALPN support patch](https://gist.github.com/rhenium/b1711edcc903e8887a51) and [ECDH support patch (r51348)](https://bugs.ruby-lang.org/projects/ruby-trunk/repository/revisions/51348/diff?format=diff)
   * or latest Ruby 2.3.0-dev
 * OpenSSL 1.0.2 or newer (HTTP/2 requires ALPN)
-* [http-parser.rb gem](https://rubygems.org/gems/http_parser.rb) (HTTP/1.1 parser; if you use "http" URI scheme)
+* Optional:
+  * [http-parser.rb gem](https://rubygems.org/gems/http_parser.rb) (HTTP/1.1 parser; if you use "http" URI scheme)
+  * [rack gem](https://rubygems.org/gems/rack) if you use Plum as Rack server.
+
+## Usage
+### As a library
+* See documentation: http://www.rubydoc.info/gems/plum
+* See examples in `examples/`
+* [rhenium/plum-server](https://github.com/rhenium/plum-server) - A static-file server for https://rhe.jp and http://rhe.jp.
+
+### As a Rack-compatible server
+Insert `require "plum/rack"` to your `config.ru`
+
+```ruby
+require "plum/rack"
+
+App = -> env {
+  [
+    200,
+    { "Content-Type" => "text/plain" },
+    [" request: #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"]
+  ]
+}
+
+run App
+```
+
+Then run it with:
+
+```sh
+% plum -e production -p 8080 --https config.ru
+```
+
+By default, Plum generates a dummy server certificate if `--cert` and `--key` options are not specified.
 
 ## TODO
 * **Better API**

data/bin/plum

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << File.expand_path("../../lib", __FILE__)
+require "plum/rack"
+require "plum/rack/cli"
+
+cli = Plum::Rack::CLI.new(ARGV)
+cli.run

data/examples/rack.ru

@@ -0,0 +1,22 @@
+$LOAD_PATH << File.expand_path("../../lib", __FILE__)
+require "plum/rack"
+
+class App2
+  def call(env)
+    if env["REQUEST_METHOD"] == "GET" && env["PATH_INFO"] == "/"
+      [
+        200,
+        { "Content-Type" => "text/html" },
+        ["*10 bytes*"*400]
+      ]
+    else
+      [
+        404,
+        { "Content-Type" => "text/html" },
+        [""]
+      ]
+    end
+  end
+end
+
+run App2.new

data/lib/plum/binary_string.rb

@@ -4,7 +4,7 @@ module Plum
       # Reads a 8-bit unsigned integer.
       # @param pos [Integer] The start position to read.
       def uint8(pos = 0)
-        byteslice(pos, 1).unpack("C")[0]
+        getbyte(pos)
       end
 
       # Reads a 16-bit unsigned integer.
@@ -16,7 +16,8 @@ module Plum
       # Reads a 24-bit unsigned integer.
       # @param pos [Integer] The start position to read.
       def uint24(pos = 0)
-        (uint16(pos) << 8) | uint8(pos + 2)
+        a, b = byteslice(pos, 3).unpack("nC")
+        (a * 0x100) + b
       end
 
       # Reads a 32-bit unsigned integer.
@@ -27,7 +28,7 @@ module Plum
 
       # Appends a 8-bit unsigned integer to this string.
       def push_uint8(val)
-        self << [val].pack("C")
+        self << val.chr
       end
 
       # Appends a 16-bit unsigned integer to this string.
@@ -37,8 +38,7 @@ module Plum
 
       # Appends a 24-bit unsigned integer to this string.
       def push_uint24(val)
-        push_uint16(val >> 8)
-        push_uint8(val & ((1 << 8) - 1))
+        self << [val / 0x100, val % 0x100].pack("nC")
       end
 
       # Appends a 32-bit unsigned integer to this string.

data/lib/plum/connection.rb

@@ -6,7 +6,7 @@ module Plum
     include FlowControl
     include ConnectionUtils
 
-    CLIENT_CONNECTION_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
+    CLIENT_CONNECTION_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".freeze
 
     DEFAULT_SETTINGS = {
       header_table_size:      4096,     # octets
@@ -15,14 +15,14 @@ module Plum
       initial_window_size:    65535,    # octets; <= 2 ** 31 - 1
       max_frame_size:         16384,    # octets; <= 2 ** 24 - 1
       max_header_list_size:   (1 << 32) - 1 # Fixnum
-    }
+    }.freeze
 
     attr_reader :hpack_encoder, :hpack_decoder
     attr_reader :local_settings, :remote_settings
-    attr_reader :state, :streams, :io
+    attr_reader :state, :streams
 
-    def initialize(io, local_settings = {})
-      @io = io
+    def initialize(writer, local_settings = {})
+      @writer = writer
       @local_settings = Hash.new {|hash, key| DEFAULT_SETTINGS[key] }.merge!(local_settings)
       @remote_settings = Hash.new {|hash, key| DEFAULT_SETTINGS[key] }
       @buffer = "".force_encoding(Encoding::BINARY)
@@ -32,24 +32,18 @@ module Plum
       @hpack_encoder = HPACK::Encoder.new(@remote_settings[:header_table_size])
       initialize_flow_control(send: @remote_settings[:initial_window_size],
                               recv: @local_settings[:initial_window_size])
+      @max_odd_stream_id = 0
+      @max_even_stream_id = 0
     end
     private :initialize
 
-    # Starts communication with the peer. It blocks until the io is closed, or reaches EOF.
-    def run
-      while !@io.closed? && !@io.eof?
-        receive @io.readpartial(1024)
-      end
-    end
-
-    # Closes the io.
+    # Emits :close event. Doesn't actually close socket.
     def close
       # TODO: server MAY wait streams
-      @io.close
+      callback(:close)
     end
 
     # Receives the specified data and process.
-    #
     # @param new_data [String] The data received from the peer.
     def receive(new_data)
       return if new_data.empty?
@@ -71,10 +65,9 @@ module Plum
     alias << receive
 
     # Reserves a new stream to server push.
-    #
     # @param args [Hash] The argument to pass to Stram.new.
     def reserve_stream(**args)
-      next_id = (@streams.keys.select(&:even?).max || 0) + 2
+      next_id = @max_even_stream_id + 2
       stream = new_stream(next_id, state: :reserved_local, **args)
       stream
     end
@@ -82,7 +75,7 @@ module Plum
     private
     def send_immediately(frame)
       callback(:send_frame, frame)
-      @io.write(frame.assemble)
+      @writer.call(frame.assemble)
     end
 
     def negotiate!
@@ -98,9 +91,15 @@ module Plum
     end
 
     def new_stream(stream_id, **args)
+      if stream_id.even?
+        @max_even_stream_id = stream_id
+      else
+        @max_odd_stream_id = stream_id
+      end
+
       stream = Stream.new(self, stream_id, **args)
-      callback(:stream, stream)
       @streams[stream_id] = stream
+      callback(:stream, stream)
       stream
     end
 
@@ -114,14 +113,14 @@ module Plum
           raise ConnectionError.new(:protocol_error)
         end
 
-        if frame.flags.include?(:end_headers)
+        if frame.end_headers?
           @state = :open
           @continuation_id = nil
         end
       end
 
-      if [:headers].include?(frame.type)
-        if !frame.flags.include?(:end_headers)
+      if frame.type == :headers
+        if !frame.end_headers?
           @state = :waiting_continuation
           @continuation_id = frame.stream_id
         end
@@ -138,7 +137,7 @@ module Plum
         if @streams.key?(frame.stream_id)
           stream = @streams[frame.stream_id]
         else
-          if frame.stream_id.even? || (@streams.size > 0 && @streams.keys.select(&:odd?).max >= frame.stream_id)
+          if frame.stream_id.even? || @max_odd_stream_id >= frame.stream_id
             raise Plum::ConnectionError.new(:protocol_error)
           end
 
@@ -172,7 +171,7 @@ module Plum
     end
 
     def receive_settings(frame, send_ack: true)
-      if frame.flags.include?(:ack)
+      if frame.ack?
         raise ConnectionError.new(:frame_size_error) if frame.length != 0
         callback(:settings_ack)
         return
@@ -202,7 +201,7 @@ module Plum
     def receive_ping(frame)
       raise Plum::ConnectionError.new(:frame_size_error) if frame.length != 8
 
-      if frame.flags.include?(:ack)
+      if frame.ack?
         callback(:ping_ack)
       else
         opaque_data = frame.payload

data/lib/plum/connection_utils.rb

@@ -3,7 +3,6 @@ using Plum::BinaryString
 module Plum
   module ConnectionUtils
     # Sends local settings to the peer.
-    #
     # @param kwargs [Hash<Symbol, Integer>]
     def settings(**kwargs)
       send_immediately Frame.settings(**kwargs)
@@ -11,7 +10,6 @@ module Plum
     end
 
     # Sends a PING frame to the peer.
-    #
     # @param data [String] Must be 8 octets.
     # @raise [ArgumentError] If the data is not 8 octets.
     def ping(data = "plum\x00\x00\x00\x00")
@@ -19,10 +17,9 @@ module Plum
     end
 
     # Sends GOAWAY frame to the peer and closes the connection.
-    #
     # @param error_type [Symbol] The error type to be contained in the GOAWAY frame.
     def goaway(error_type = :no_error)
-      last_id = @streams.keys.max || 0
+      last_id = @max_odd_stream_id > @max_even_stream_id ? @max_odd_stream_id : @max_even_stream_id
       send_immediately Frame.goaway(last_id, error_type)
     end
 

data/lib/plum/errors.rb

@@ -17,7 +17,7 @@ module Plum
       enhance_your_calm:   0x0b,
       inadequate_security: 0x0c,
       http_1_1_required:   0x0d
-    }
+    }.freeze
 
     attr_reader :http2_error_type
 

data/lib/plum/event_emitter.rb

@@ -1,19 +1,21 @@
 module Plum
   module EventEmitter
     # Registers an event handler to specified event. An event can have multiple handlers.
-    # @param name [String] The name of event.
+    # @param name [Symbol] The name of event.
     # @yield Gives event-specific parameters.
     def on(name, &blk)
-      callbacks[name] << blk
+      (callbacks[name] ||= []) << blk
     end
 
-    private
+    # Invokes an event and call handlers with args.
+    # @param name [Symbol] The identifier of event.
     def callback(name, *args)
-      callbacks[name].each {|cb| cb.call(*args) }
+      (cbs = callbacks[name]) && cbs.each {|cb| cb.call(*args) }
     end
 
+    private
     def callbacks
-      @callbacks ||= Hash.new {|hash, key| hash[key] = [] }
+      @callbacks ||= {}
     end
   end
 end

data/lib/plum/flow_control.rb

@@ -5,25 +5,29 @@ module Plum
     attr_reader :send_remaining_window, :recv_remaining_window
 
     # Sends frame respecting inner-stream flow control.
-    #
     # @param frame [Frame] The frame to be sent.
     def send(frame)
-      case frame.type
-      when :data
+      if frame.type == :data
         @send_buffer << frame
-        callback(:send_deferred, frame) if @send_remaining_window < frame.length
-        consume_send_buffer
+        if @send_remaining_window < frame.length
+          if Stream === self
+            connection.callback(:send_deferred, self, frame)
+          else
+            callback(:send_deferred, self, frame)
+          end
+        else
+          consume_send_buffer
+        end
       else
         send_immediately frame
       end
     end
 
     # Increases receiving window size. Sends WINDOW_UPDATE frame to the peer.
-    #
     # @param wsi [Integer] The amount to increase receiving window size. The legal range is 1 to 2^32-1.
     def window_update(wsi)
       @recv_remaining_window += wsi
-      payload = "".push_uint32(wsi & ~(1 << 31))
+      payload = "".push_uint32(wsi)
       sid = (Stream === self) ? self.id : 0
       send_immediately Frame.new(type: :window_update, stream_id: sid, payload: payload)
     end
@@ -57,8 +61,7 @@ module Plum
     end
 
     def consume_recv_window(frame)
-      case frame.type
-      when :data
+      if frame.type == :data
         @recv_remaining_window -= frame.length
         if @recv_remaining_window < 0
           local_error = (Connection === self) ? ConnectionError : StreamError
@@ -82,15 +85,19 @@ module Plum
       end
 
       r_wsi = frame.payload.uint32
-      r = r_wsi >> 31
-      wsi = r_wsi & ~(1 << 31)
+      # r = r_wsi >> 31 # currently not used
+      wsi = r_wsi # & ~(1 << 31)
 
       if wsi == 0
         local_error = (Connection === self) ? ConnectionError : StreamError
         raise local_error.new(:protocol_error)
       end
 
-      callback(:window_update, wsi)
+      if Stream === self
+        connection.callback(:window_update, self, wsi)
+      else
+        callback(:window_update, self, wsi)
+      end
 
       @send_remaining_window += wsi
       consume_send_buffer

data/lib/plum/frame.rb

@@ -16,37 +16,43 @@ module Plum
       goaway:         0x07,
       window_update:  0x08,
       continuation:   0x09
-    }
+    }.freeze
+
+    # @!visibility private
+    FRAME_TYPES_INVERSE = FRAME_TYPES.invert.freeze
 
     FRAME_FLAGS = {
       data: {
         end_stream:   0x01,
         padded:       0x08
-      },
+      }.freeze,
       headers: {
         end_stream:   0x01,
         end_headers:  0x04,
         padded:       0x08,
         priority:     0x20
-      },
-      priority: {},
-      rst_stream: {},
+      }.freeze,
+      priority: {}.freeze,
+      rst_stream: {}.freeze,
       settings: {
         ack:          0x01
-      },
+      }.freeze,
       push_promise: {
         end_headers:  0x04,
         padded:       0x08
-      },
+      }.freeze,
       ping: {
         ack:          0x01
-      },
-      goaway: {},
-      window_update: {},
+      }.freeze,
+      goaway: {}.freeze,
+      window_update: {}.freeze,
       continuation: {
         end_headers:  0x04
-      }
-    }
+      }.freeze
+    }.freeze
+
+    # @!visibility private
+    FRAME_FLAGS_MAP = FRAME_FLAGS.values.inject(:merge).freeze
 
     SETTINGS_TYPE = {
       header_table_size:      0x01,
@@ -55,7 +61,7 @@ module Plum
       initial_window_size:    0x04,
       max_frame_size:         0x05,
       max_header_list_size:   0x06
-    }
+    }.freeze
 
     # RFC7540: 4.1 Frame format
     # +-----------------------------------------------+
@@ -72,34 +78,35 @@ module Plum
     attr_accessor :type_value
     # [Integer] Flags. 8-bit
     attr_accessor :flags_value
-    # [Integer] Stream Identifier. unsigned 31-bit integer
-    attr_accessor :stream_id
-    # [String] The payload.
-    attr_accessor :payload
+    # [Integer] Stream Identifier. Unsigned 31-bit integer
+    attr_reader :stream_id
+    # [String] The payload. Value is frozen.
+    attr_reader :payload
 
     def initialize(type: nil, type_value: nil, flags: nil, flags_value: nil, stream_id: nil, payload: nil)
-      self.payload = (payload || "")
-      self.type_value = type_value or self.type = type
-      self.flags_value = flags_value or self.flags = flags
-      self.stream_id = stream_id or raise ArgumentError.new("stream_id is necessary")
+      @payload = payload || ""
+      @length = @payload.bytesize
+      @type_value = type_value or self.type = type
+      @flags_value = flags_value or self.flags = flags
+      @stream_id = stream_id or raise ArgumentError.new("stream_id is necessary")
     end
 
     # Returns the length of payload.
     # @return [Integer] The length.
     def length
-      @payload.bytesize
+      @length
     end
 
     # Returns the type of the frame in Symbol.
     # @return [Symbol] The type.
     def type
-      FRAME_TYPES.key(type_value) || ("unknown_%02x" % type_value).to_sym
+      FRAME_TYPES_INVERSE[@type_value] || ("unknown_%02x" % @type_value).to_sym
     end
 
     # Sets the frame type.
     # @param value [Symbol] The type.
     def type=(value)
-      self.type_value = FRAME_TYPES[value] or raise ArgumentError.new("unknown frame type: #{value}")
+      @type_value = FRAME_TYPES[value] or raise ArgumentError.new("unknown frame type: #{value}")
     end
 
     # Returns the set flags on the frame.
@@ -107,26 +114,36 @@ module Plum
     def flags
       fs = FRAME_FLAGS[type]
       [0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80]
-        .select {|v| flags_value & v > 0 }
+        .select {|v| @flags_value & v > 0 }
         .map {|val| fs && fs.key(val) || ("unknown_%02x" % val).to_sym }
     end
 
     # Sets the frame flags.
-    # @param value [Array<Symbol>] The flags.
-    def flags=(value)
-      self.flags_value = (value && value.map {|flag| FRAME_FLAGS[self.type][flag] }.inject(:|) || 0)
+    # @param values [Array<Symbol>] The flags.
+    def flags=(values)
+      val = 0
+      FRAME_FLAGS_MAP.values_at(*values).each { |c|
+        val |= c if c
+      }
+      @flags_value = val
     end
 
+    # Frame#flag_name?() == Frame#flags().include?(:flag_name)
+    FRAME_FLAGS_MAP.each { |name, value|
+      class_eval <<-EOS, __FILE__, __LINE__ + 1
+        def #{name}?
+          @flags_value & #{value} > 0
+        end
+      EOS
+    }
+
     # Assembles the frame into binary representation.
     # @return [String] Binary representation of this frame.
     def assemble
-      bytes = "".force_encoding(Encoding::BINARY)
-      bytes.push_uint24(length)
-      bytes.push_uint8(type_value)
-      bytes.push_uint8(flags_value)
-      bytes.push_uint32(stream_id & ~(1 << 31)) # first bit is reserved (MUST be 0)
-      bytes.push(payload)
-      bytes
+      [length / 0x100, length % 0x100,
+       @type_value,
+       @flags_value,
+       @stream_id].pack("nCCCN") << @payload
     end
 
     # @private
@@ -135,29 +152,22 @@ module Plum
     end
 
     # Parses a frame from given buffer. It changes given buffer.
-    #
-    # @param buffer [String] The buffer stored the data received from peer.
+    # @param buffer [String] The buffer stored the data received from peer. Encoding must be Encoding::BINARY.
     # @return [Frame, nil] The parsed frame or nil if the buffer is imcomplete.
     def self.parse!(buffer)
-      buffer.force_encoding(Encoding::BINARY)
-
-      return nil if buffer.size < 9 # header: 9 bytes
+      return nil if buffer.bytesize < 9 # header: 9 bytes
       length = buffer.uint24
-      return nil if buffer.size < 9 + length
-
-      bhead = buffer.byteshift(9)
-      payload = buffer.byteshift(length)
+      return nil if buffer.bytesize < 9 + length
 
-      type_value = bhead.uint8(3)
-      flags_value = bhead.uint8(4)
-      r_sid = bhead.uint32(5)
-      r = r_sid >> 31
-      stream_id = r_sid & ~(1 << 31)
+      cur = buffer.byteshift(9 + length)
+      type_value, flags_value, r_sid = cur.byteslice(3, 6).unpack("CCN")
+      # r = r_sid >> 31 # currently not used
+      stream_id = r_sid # & ~(1 << 31)
 
       self.new(type_value: type_value,
                flags_value: flags_value,
                stream_id: stream_id,
-               payload: payload).freeze
+               payload: cur.byteslice(9, length)).freeze
     end
   end
 end