http-2-next 0.1.0

data/lib/http/2/next/emitter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HTTP2Next
+  # Basic event emitter implementation with support for persistent and
+  # one-time event callbacks.
+  #
+  module Emitter
+    # Subscribe to all future events for specified type.
+    #
+    # @param event [Symbol]
+    # @param block [Proc] callback function
+    def add_listener(event, &block)
+      raise ArgumentError, "must provide callback" unless block_given?
+
+      listeners(event.to_sym).push block
+    end
+    alias on add_listener
+
+    # Subscribe to next event (at most once) for specified type.
+    #
+    # @param event [Symbol]
+    # @param block [Proc] callback function
+    def once(event, &block)
+      add_listener(event) do |*args, &callback|
+        block.call(*args, &callback)
+        :delete
+      end
+    end
+
+    # Emit event with provided arguments.
+    #
+    # @param event [Symbol]
+    # @param args [Array] arguments to be passed to the callbacks
+    # @param block [Proc] callback function
+    def emit(event, *args, &block)
+      listeners(event).delete_if do |cb|
+        cb.call(*args, &block) == :delete
+      end
+    end
+
+    private
+
+    def listeners(event)
+      @listeners ||= Hash.new { |hash, key| hash[key] = [] }
+      @listeners[event]
+    end
+  end
+end

data/lib/http/2/next/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module HTTP2Next
+  # Stream, connection, and compressor exceptions.
+  module Error
+    @types = {}
+    class << self
+      attr_reader :types
+    end
+
+    class Error < StandardError
+      def self.inherited(klass)
+        type = klass.name.split("::").last
+        type = type.gsub(/([^\^])([A-Z])/, '\1_\2').downcase.to_sym
+        HTTP2Next::Error.types[type] = klass
+      end
+    end
+
+    # Raised if connection header is missing or invalid indicating that
+    # this is an invalid HTTP 2.0 request - no frames are emitted and the
+    # connection must be aborted.
+    class HandshakeError < Error; end
+
+    # Raised by stream or connection handlers, results in GOAWAY frame
+    # which signals termination of the current connection. You *cannot*
+    # recover from this exception, or any exceptions subclassed from it.
+    class ProtocolError < Error; end
+
+    # Raised on any header encoding / decoding exception.
+    #
+    # @see ProtocolError
+    class CompressionError < ProtocolError; end
+
+    # Raised on invalid flow control frame or command.
+    #
+    # @see ProtocolError
+    class FlowControlError < ProtocolError; end
+
+    # Raised on invalid stream processing: invalid frame type received or
+    # sent, or invalid command issued.
+    class InternalError < ProtocolError; end
+
+    #
+    # -- Recoverable errors -------------------------------------------------
+    #
+
+    # Raised if stream has been closed and new frames cannot be sent.
+    class StreamClosed < Error; end
+
+    # Raised if connection has been closed (or draining) and new stream
+    # cannot be opened.
+    class ConnectionClosed < Error; end
+
+    # Raised if stream limit has been reached and new stream cannot be opened.
+    class StreamLimitExceeded < Error; end
+
+    class FrameSizeError < Error; end
+  end
+end

data/lib/http/2/next/flow_buffer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module HTTP2Next
+  # Implementation of stream and connection DATA flow control: frames may
+  # be split and / or may be buffered based on current flow control window.
+  #
+  module FlowBuffer
+    include Error
+
+    MAX_WINDOW_SIZE = 2**31 - 1
+
+    # Amount of buffered data. Only DATA payloads are subject to flow stream
+    # and connection flow control.
+    #
+    # @return [Integer]
+    def buffered_amount
+      @send_buffer.map { |f| f[:length] }.reduce(0, :+)
+    end
+
+    def flush
+      send_data
+    end
+
+    private
+
+    def update_local_window(frame)
+      frame_size = frame[:payload].bytesize
+      frame_size += frame[:padding] || 0
+      @local_window -= frame_size
+    end
+
+    def calculate_window_update(window_max_size)
+      # If DATA frame is received with length > 0 and
+      # current received window size + delta length is strictly larger than
+      # local window size, it throws a flow control error.
+      #
+      error(:flow_control_error) if @local_window < 0
+
+      # Send WINDOW_UPDATE if the received window size goes over
+      # the local window size / 2.
+      #
+      # The HTTP/2 spec mandates that every DATA frame received
+      # generates a WINDOW_UPDATE to send. In some cases however,
+      # (ex: DATA frames with short payloads),
+      # the noise generated by flow control frames creates enough
+      # congestion for this to be deemed very inefficient.
+      #
+      # This heuristic was inherited from nghttp, which delays the
+      # WINDOW_UPDATE until at least half the window is exhausted.
+      # This works because the sender doesn't need those increments
+      # until the receiver window is exhausted, after which he'll be
+      # waiting for the WINDOW_UPDATE frame.
+      return unless @local_window <= (window_max_size / 2)
+
+      window_update(window_max_size - @local_window)
+    end
+
+    # Buffers outgoing DATA frames and applies flow control logic to split
+    # and emit DATA frames based on current flow control window. If the
+    # window is large enough, the data is sent immediately. Otherwise, the
+    # data is buffered until the flow control window is updated.
+    #
+    # Buffered DATA frames are emitted in FIFO order.
+    #
+    # @param frame [Hash]
+    # @param encode [Boolean] set to true by co
+    def send_data(frame = nil, encode = false)
+      @send_buffer.push frame unless frame.nil?
+
+      # FIXME: Frames with zero length with the END_STREAM flag set (that
+      # is, an empty DATA frame) MAY be sent if there is no available space
+      # in either flow control window.
+      while @remote_window > 0 && !@send_buffer.empty?
+        frame = @send_buffer.shift
+
+        sent = 0
+        frame_size = frame[:payload].bytesize
+
+        if frame_size > @remote_window
+          payload = frame.delete(:payload)
+          chunk   = frame.dup
+
+          # Split frame so that it fits in the window
+          # TODO: consider padding!
+          frame[:payload] = payload.slice!(0, @remote_window)
+          frame[:length] = frame[:payload].bytesize
+          chunk[:length]  = payload.bytesize
+          chunk[:payload] = payload
+
+          # if no longer last frame in sequence...
+          frame[:flags] -= [:end_stream] if frame[:flags].include? :end_stream
+
+          @send_buffer.unshift chunk
+          sent = @remote_window
+        else
+          sent = frame_size
+        end
+
+        manage_state(frame) do
+          frames = encode ? encode(frame) : [frame]
+          frames.each { |f| emit(:frame, f) }
+          @remote_window -= sent
+        end
+      end
+    end
+
+    def process_window_update(frame:, encode: false)
+      return if frame[:ignore]
+
+      if frame[:increment]
+        raise ProtocolError, "increment MUST be higher than zero" if frame[:increment].zero?
+
+        @remote_window += frame[:increment]
+        error(:flow_control_error, msg: "window size too large") if @remote_window > MAX_WINDOW_SIZE
+      end
+      send_data(nil, encode)
+    end
+  end
+end

data/lib/http/2/next/framer.rb

@@ -0,0 +1,445 @@
+# frozen_string_literal: true
+
+module HTTP2Next
+  # Performs encoding, decoding, and validation of binary HTTP/2 frames.
+  #
+  class Framer
+    include Error
+
+    # Default value of max frame size (16384 bytes)
+    DEFAULT_MAX_FRAME_SIZE = 2**14
+
+    # maximum frame size
+    attr_accessor :local_max_frame_size, :remote_max_frame_size
+
+    # Maximum stream ID (2^31)
+    MAX_STREAM_ID = 0x7fffffff
+
+    # Maximum window increment value (2^31)
+    MAX_WINDOWINC = 0x7fffffff
+
+    # HTTP/2 frame type mapping as defined by the spec
+    FRAME_TYPES = {
+      data: 0x0,
+      headers: 0x1,
+      priority: 0x2,
+      rst_stream: 0x3,
+      settings: 0x4,
+      push_promise: 0x5,
+      ping: 0x6,
+      goaway: 0x7,
+      window_update: 0x8,
+      continuation: 0x9,
+      altsvc: 0xa
+    }.freeze
+
+    FRAME_TYPES_WITH_PADDING = %i[data headers push_promise].freeze
+
+    # Per frame flags as defined by the spec
+    FRAME_FLAGS = {
+      data: {
+        end_stream: 0,
+        padded: 3,
+        compressed: 5
+      },
+      headers: {
+        end_stream: 0,
+        end_headers: 2,
+        padded: 3,
+        priority: 5
+      },
+      priority: {},
+      rst_stream: {},
+      settings: { ack: 0 },
+      push_promise: {
+        end_headers: 2,
+        padded: 3
+      },
+      ping: { ack: 0 },
+      goaway: {},
+      window_update: {},
+      continuation: { end_headers: 2 },
+      altsvc: {}
+    }.each_value(&:freeze).freeze
+
+    # Default settings as defined by the spec
+    DEFINED_SETTINGS = {
+      settings_header_table_size: 1,
+      settings_enable_push: 2,
+      settings_max_concurrent_streams: 3,
+      settings_initial_window_size: 4,
+      settings_max_frame_size: 5,
+      settings_max_header_list_size: 6
+    }.freeze
+
+    # Default error types as defined by the spec
+    DEFINED_ERRORS = {
+      no_error: 0,
+      protocol_error: 1,
+      internal_error: 2,
+      flow_control_error: 3,
+      settings_timeout: 4,
+      stream_closed: 5,
+      frame_size_error: 6,
+      refused_stream: 7,
+      cancel: 8,
+      compression_error: 9,
+      connect_error: 10,
+      enhance_your_calm: 11,
+      inadequate_security: 12,
+      http_1_1_required: 13
+    }.freeze
+
+    RBIT  = 0x7fffffff
+    RBYTE = 0x0fffffff
+    EBIT  = 0x80000000
+    UINT32 = "N"
+    UINT16 = "n"
+    UINT8  = "C"
+    HEADERPACK = (UINT8 + UINT16 + UINT8 + UINT8 + UINT32).freeze
+    FRAME_LENGTH_HISHIFT = 16
+    FRAME_LENGTH_LOMASK  = 0xFFFF
+
+    private_constant :RBIT, :RBYTE, :EBIT, :HEADERPACK, :UINT32, :UINT16, :UINT8
+
+    # Initializes new framer object.
+    #
+    def initialize(local_max_frame_size = DEFAULT_MAX_FRAME_SIZE,
+                   remote_max_frame_size = DEFAULT_MAX_FRAME_SIZE)
+      @local_max_frame_size = local_max_frame_size
+      @remote_max_frame_size = remote_max_frame_size
+    end
+
+    # Generates common 9-byte frame header.
+    # - http://tools.ietf.org/html/draft-ietf-httpbis-http2-16#section-4.1
+    #
+    # @param frame [Hash]
+    # @return [String]
+    def common_header(frame)
+      header = []
+
+      raise CompressionError, "Invalid frame type (#{frame[:type]})" unless FRAME_TYPES[frame[:type]]
+
+      raise CompressionError, "Frame size is too large: #{frame[:length]}" if frame[:length] > @remote_max_frame_size
+
+      raise CompressionError, "Frame size is invalid: #{frame[:length]}" if frame[:length] < 0
+
+      raise CompressionError, "Stream ID (#{frame[:stream]}) is too large" if frame[:stream] > MAX_STREAM_ID
+
+      if frame[:type] == :window_update && frame[:increment] > MAX_WINDOWINC
+        raise CompressionError, "Window increment (#{frame[:increment]}) is too large"
+      end
+
+      header << (frame[:length] >> FRAME_LENGTH_HISHIFT)
+      header << (frame[:length] & FRAME_LENGTH_LOMASK)
+      header << FRAME_TYPES[frame[:type]]
+      header << frame[:flags].reduce(0) do |acc, f|
+        position = FRAME_FLAGS[frame[:type]][f]
+        raise CompressionError, "Invalid frame flag (#{f}) for #{frame[:type]}" unless position
+
+        acc | (1 << position)
+      end
+
+      header << frame[:stream]
+      header.pack(HEADERPACK) # 8+16,8,8,32
+    end
+
+    # Decodes common 9-byte header.
+    #
+    # @param buf [Buffer]
+    def read_common_header(buf)
+      frame = {}
+      len_hi, len_lo, type, flags, stream = buf.slice(0, 9).unpack(HEADERPACK)
+
+      frame[:length] = (len_hi << FRAME_LENGTH_HISHIFT) | len_lo
+      frame[:type], = FRAME_TYPES.find { |_t, pos| type == pos }
+      if frame[:type]
+        frame[:flags] = FRAME_FLAGS[frame[:type]].each_with_object([]) do |(name, pos), acc|
+          acc << name if (flags & (1 << pos)) > 0
+        end
+      end
+
+      frame[:stream] = stream & RBIT
+      frame
+    end
+
+    # Generates encoded HTTP/2 frame.
+    # - http://tools.ietf.org/html/draft-ietf-httpbis-http2
+    #
+    # @param frame [Hash]
+    def generate(frame)
+      bytes  = Buffer.new
+      length = 0
+
+      frame[:flags] ||= []
+      frame[:stream] ||= 0
+
+      case frame[:type]
+      when :data
+        bytes << frame[:payload]
+        length += frame[:payload].bytesize
+
+      when :headers
+        if frame[:weight] || frame[:dependency] || !frame[:exclusive].nil?
+          unless frame[:weight] && frame[:dependency] && !frame[:exclusive].nil?
+            raise CompressionError, "Must specify all of priority parameters for #{frame[:type]}"
+          end
+
+          frame[:flags] += [:priority] unless frame[:flags].include? :priority
+        end
+
+        if frame[:flags].include? :priority
+          bytes << [(frame[:exclusive] ? EBIT : 0) | (frame[:dependency] & RBIT)].pack(UINT32)
+          bytes << [frame[:weight] - 1].pack(UINT8)
+          length += 5
+        end
+
+        bytes << frame[:payload]
+        length += frame[:payload].bytesize
+
+      when :priority
+        unless frame[:weight] && frame[:dependency] && !frame[:exclusive].nil?
+          raise CompressionError, "Must specify all of priority parameters for #{frame[:type]}"
+        end
+
+        bytes << [(frame[:exclusive] ? EBIT : 0) | (frame[:dependency] & RBIT)].pack(UINT32)
+        bytes << [frame[:weight] - 1].pack(UINT8)
+        length += 5
+
+      when :rst_stream
+        bytes << pack_error(frame[:error])
+        length += 4
+
+      when :settings
+        raise CompressionError, "Invalid stream ID (#{frame[:stream]})" if (frame[:stream]).nonzero?
+
+        frame[:payload].each do |(k, v)|
+          if k.is_a? Integer
+            DEFINED_SETTINGS.value?(k) || next
+          else
+            k = DEFINED_SETTINGS[k]
+
+            raise CompressionError, "Unknown settings ID for #{k}" if k.nil?
+          end
+
+          bytes << [k].pack(UINT16)
+          bytes << [v].pack(UINT32)
+          length += 6
+        end
+
+      when :push_promise
+        bytes << [frame[:promise_stream] & RBIT].pack(UINT32)
+        bytes << frame[:payload]
+        length += 4 + frame[:payload].bytesize
+
+      when :ping
+        if frame[:payload].bytesize != 8
+          raise CompressionError, "Invalid payload size (#{frame[:payload].size} != 8 bytes)"
+        end
+
+        bytes << frame[:payload]
+        length += 8
+
+      when :goaway
+        bytes << [frame[:last_stream] & RBIT].pack(UINT32)
+        bytes << pack_error(frame[:error])
+        length += 8
+
+        if frame[:payload]
+          bytes << frame[:payload]
+          length += frame[:payload].bytesize
+        end
+
+      when :window_update
+        bytes << [frame[:increment] & RBIT].pack(UINT32)
+        length += 4
+
+      when :continuation
+        bytes << frame[:payload]
+        length += frame[:payload].bytesize
+
+      when :altsvc
+        bytes << [frame[:max_age], frame[:port]].pack(UINT32 + UINT16)
+        length += 6
+        if frame[:proto]
+          raise CompressionError, "Proto too long" if frame[:proto].bytesize > 255
+
+          bytes << [frame[:proto].bytesize].pack(UINT8)
+          bytes << frame[:proto]
+          length += 1 + frame[:proto].bytesize
+        else
+          bytes << [0].pack(UINT8)
+          length += 1
+        end
+        if frame[:host]
+          raise CompressionError, "Host too long" if frame[:host].bytesize > 255
+
+          bytes << [frame[:host].bytesize].pack(UINT8)
+          bytes << frame[:host]
+          length += 1 + frame[:host].bytesize
+        else
+          bytes << [0].pack(UINT8)
+          length += 1
+        end
+        if frame[:origin]
+          bytes << frame[:origin]
+          length += frame[:origin].bytesize
+        end
+      end
+
+      # Process padding.
+      #  frame[:padding] gives number of extra octets to be added.
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-http2-16#section-6.1
+      if frame[:padding]
+        unless FRAME_TYPES_WITH_PADDING.include?(frame[:type])
+          raise CompressionError, "Invalid padding flag for #{frame[:type]}"
+        end
+
+        padlen = frame[:padding]
+
+        if padlen <= 0 || padlen > 256 || padlen + length > @remote_max_frame_size
+          raise CompressionError, "Invalid padding #{padlen}"
+        end
+
+        length += padlen
+        bytes.prepend([padlen -= 1].pack(UINT8))
+        frame[:flags] << :padded
+
+        # Padding:  Padding octets that contain no application semantic value.
+        # Padding octets MUST be set to zero when sending and ignored when
+        # receiving.
+        bytes << "\0" * padlen
+      end
+
+      frame[:length] = length
+      bytes.prepend(common_header(frame))
+    end
+
+    # Decodes complete HTTP/2 frame from provided buffer. If the buffer
+    # does not contain enough data, no further work is performed.
+    #
+    # @param buf [Buffer]
+    def parse(buf)
+      return nil if buf.size < 9
+
+      frame = read_common_header(buf)
+      return nil if buf.size < 9 + frame[:length]
+
+      raise ProtocolError, "payload too large" if frame[:length] > @local_max_frame_size
+
+      buf.read(9)
+      payload = buf.read(frame[:length])
+
+      # Implementations MUST discard frames
+      # that have unknown or unsupported types.
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-http2-16#section-5.5
+      return frame if frame[:type].nil?
+
+      # Process padding
+      padlen = 0
+      if FRAME_TYPES_WITH_PADDING.include?(frame[:type])
+        padded = frame[:flags].include?(:padded)
+        if padded
+          padlen = payload.read(1).unpack(UINT8).first
+          frame[:padding] = padlen + 1
+          raise ProtocolError, "padding too long" if padlen > payload.bytesize
+
+          payload.slice!(-padlen, padlen) if padlen > 0
+          frame[:length] -= frame[:padding]
+          frame[:flags].delete(:padded)
+        end
+      end
+
+      case frame[:type]
+      when :data
+        frame[:payload] = payload.read(frame[:length])
+      when :headers
+        if frame[:flags].include? :priority
+          e_sd = payload.read_uint32
+          frame[:dependency] = e_sd & RBIT
+          frame[:exclusive] = (e_sd & EBIT) != 0
+          frame[:weight] = payload.getbyte + 1
+        end
+        frame[:payload] = payload.read(frame[:length])
+      when :priority
+        raise FrameSizeError, "Invalid length for PRIORITY_STREAM (#{frame[:length]} != 5)" if frame[:length] != 5
+
+        e_sd = payload.read_uint32
+        frame[:dependency] = e_sd & RBIT
+        frame[:exclusive] = (e_sd & EBIT) != 0
+        frame[:weight] = payload.getbyte + 1
+      when :rst_stream
+        raise FrameSizeError, "Invalid length for RST_STREAM (#{frame[:length]} != 4)" if frame[:length] != 4
+
+        frame[:error] = unpack_error payload.read_uint32
+
+      when :settings
+        # NOTE: frame[:length] might not match the number of frame[:payload]
+        # because unknown extensions are ignored.
+        frame[:payload] = []
+        raise ProtocolError, "Invalid settings payload length" unless (frame[:length] % 6).zero?
+
+        raise ProtocolError, "Invalid stream ID (#{frame[:stream]})" if (frame[:stream]).nonzero?
+
+        (frame[:length] / 6).times do
+          id  = payload.read(2).unpack(UINT16).first
+          val = payload.read_uint32
+
+          # Unsupported or unrecognized settings MUST be ignored.
+          # Here we send it along.
+          name, = DEFINED_SETTINGS.find { |_name, v| v == id }
+          frame[:payload] << [name, val] if name
+        end
+      when :push_promise
+        frame[:promise_stream] = payload.read_uint32 & RBIT
+        frame[:payload] = payload.read(frame[:length])
+      when :ping
+        frame[:payload] = payload.read(frame[:length])
+      when :goaway
+        frame[:last_stream] = payload.read_uint32 & RBIT
+        frame[:error] = unpack_error payload.read_uint32
+
+        size = frame[:length] - 8 # for last_stream and error
+        frame[:payload] = payload.read(size) if size > 0
+      when :window_update
+        if frame[:length] % 4 != 0
+          raise FrameSizeError, "Invalid length for WINDOW_UPDATE (#{frame[:length]} not multiple of 4)"
+        end
+
+        frame[:increment] = payload.read_uint32 & RBIT
+      when :continuation
+        frame[:payload] = payload.read(frame[:length])
+      when :altsvc
+        frame[:max_age], frame[:port] = payload.read(6).unpack(UINT32 + UINT16)
+
+        len = payload.getbyte
+        frame[:proto] = payload.read(len) if len > 0
+
+        len = payload.getbyte
+        frame[:host] = payload.read(len) if len > 0
+
+        frame[:origin] = payload.read(payload.size) unless payload.empty?
+        # else # Unknown frame type is explicitly allowed
+      end
+
+      frame
+    end
+
+    private
+
+    def pack_error(e)
+      unless e.is_a? Integer
+        raise CompressionError, "Unknown error ID for #{e}" if DEFINED_ERRORS[e].nil?
+
+        e = DEFINED_ERRORS[e]
+      end
+
+      [e].pack(UINT32)
+    end
+
+    def unpack_error(error)
+      name, = DEFINED_ERRORS.find { |_name, v| v == error }
+      name || error
+    end
+  end
+end