http-2 0.12.0 → 1.0.0

data/lib/http/2/header/compressor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module HTTP2
+  module Header
+    # Responsible for encoding header key-value pairs using HPACK algorithm.
+    class Compressor
+      include PackingExtensions
+
+      # @param options [Hash] encoding options
+      def initialize(options = {})
+        @cc = EncodingContext.new(options)
+      end
+
+      # Set dynamic table size in EncodingContext
+      # @param size [Integer] new dynamic table size
+      def table_size=(size)
+        @cc.table_size = size
+      end
+
+      # Encodes provided value via integer representation.
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-10#section-5.1
+      #
+      #  If I < 2^N - 1, encode I on N bits
+      #  Else
+      #      encode 2^N - 1 on N bits
+      #      I = I - (2^N - 1)
+      #      While I >= 128
+      #           Encode (I % 128 + 128) on 8 bits
+      #           I = I / 128
+      #      encode (I) on 8 bits
+      #
+      # @param i [Integer] value to encode
+      # @param n [Integer] number of available bits
+      # @param buffer [String] buffer to pack bytes into
+      # @param offset [Integer] offset to insert packed bytes in buffer
+      # @return [String] binary string
+      def integer(i, n, buffer:, offset: 0)
+        limit = (2**n) - 1
+        return pack([i], "C", buffer: buffer, offset: offset) if i < limit
+
+        bytes = []
+        bytes.push limit unless n.zero?
+
+        i -= limit
+        while i >= 128
+          bytes.push((i % 128) + 128)
+          i /= 128
+        end
+
+        bytes.push i
+        pack(bytes, "C*", buffer: buffer, offset: offset)
+      end
+
+      # Encodes provided value via string literal representation.
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-10#section-5.2
+      #
+      # * The string length, defined as the number of bytes needed to store
+      #   its UTF-8 representation, is represented as an integer with a seven
+      #   bits prefix. If the string length is strictly less than 127, it is
+      #   represented as one byte.
+      # * If the bit 7 of the first byte is 1, the string value is represented
+      #   as a list of Huffman encoded octets
+      #   (padded with bit 1's until next octet boundary).
+      # * If the bit 7 of the first byte is 0, the string value is
+      #   represented as a list of UTF-8 encoded octets.
+      #
+      # +@options [:huffman]+ controls whether to use Huffman encoding:
+      #  :never   Do not use Huffman encoding
+      #  :always  Always use Huffman encoding
+      #  :shorter Use Huffman when the result is strictly shorter
+      #
+      # @param str [String]
+      # @return [String] binary string
+      def string(str)
+        case @cc.options[:huffman]
+        when :always
+          huffman_string(str)
+        when :never
+          plain_string(str)
+        else
+          huffman = huffman_string(str)
+
+          plain = plain_string(str)
+
+          huffman.bytesize < plain.bytesize ? huffman : plain
+        end
+      end
+
+      # Encodes header command with appropriate header representation.
+      #
+      # @param h [Hash] header command
+      # @param buffer [String]
+      # @return [Buffer]
+      def header(h, buffer = "".b)
+        rep = HEADREP[h[:type]]
+
+        case h[:type]
+        when :indexed
+          integer(h[:name] + 1, rep[:prefix], buffer: buffer)
+        when :changetablesize
+          integer(h[:value], rep[:prefix], buffer: buffer)
+        else
+          if h[:name].is_a? Integer
+            integer(h[:name] + 1, rep[:prefix], buffer: buffer)
+          else
+            integer(0, rep[:prefix], buffer: buffer)
+            buffer << string(h[:name])
+          end
+
+          buffer << string(h[:value])
+        end
+
+        # set header representation pattern on first byte
+        fb = buffer.ord | rep[:pattern]
+        buffer.setbyte(0, fb)
+
+        buffer
+      end
+
+      # Encodes provided list of HTTP headers.
+      #
+      # @param headers [Array] +[[name, value], ...]+
+      # @return [Buffer]
+      def encode(headers)
+        buffer = "".b
+        pseudo_headers, regular_headers = headers.partition { |f, _| f.start_with? ":" }
+        headers = [*pseudo_headers, *regular_headers]
+        commands = @cc.encode(headers)
+        commands.each do |cmd|
+          buffer << header(cmd)
+        end
+
+        buffer
+      end
+
+      private
+
+      # @param str [String]
+      # @return [String] binary string
+      def huffman_string(str)
+        huffman = Huffman.new.encode(str)
+        integer(huffman.bytesize, 7, buffer: huffman, offset: 0)
+        huffman.setbyte(0, huffman.ord | 0x80)
+        huffman
+      end
+
+      # @param str [String]
+      # @return [String] binary string
+      def plain_string(str)
+        plain = "".b
+        integer(str.bytesize, 7, buffer: plain)
+        plain << str.dup.force_encoding(Encoding::BINARY)
+        plain
+      end
+    end
+  end
+end

data/lib/http/2/header/decompressor.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module HTTP2
+  module Header
+    using StringExtensions
+    # Responsible for decoding received headers and maintaining compression
+    # context of the opposing peer. Decompressor must be initialized with
+    # appropriate starting context based on local role: client or server.
+    #
+    # @example
+    #   server_role = Decompressor.new(:request)
+    #   client_role = Decompressor.new(:response)
+    class Decompressor
+      include Error
+
+      # @param options [Hash] decoding options.  Only :table_size is effective.
+      def initialize(options = {})
+        @cc = EncodingContext.new(options)
+      end
+
+      # Set dynamic table size in EncodingContext
+      # @param size [Integer] new dynamic table size
+      def table_size=(size)
+        @cc.table_size = size
+      end
+
+      # Decodes integer value from provided buffer.
+      #
+      # @param buf [String]
+      # @param n [Integer] number of available bits
+      # @return [Integer]
+      def integer(buf, n)
+        limit = (2**n) - 1
+        i = n.zero? ? 0 : (buf.shift_byte & limit)
+
+        m = 0
+        if i == limit
+          while (byte = buf.shift_byte)
+            i += ((byte & 127) << m)
+            m += 7
+
+            break if (byte & 128).zero?
+          end
+        end
+
+        i
+      end
+
+      # Decodes string value from provided buffer.
+      #
+      # @param buf [String]
+      # @return [String] UTF-8 encoded string
+      # @raise [CompressionError] when input is malformed
+      def string(buf)
+        raise CompressionError, "invalid header block fragment" if buf.empty?
+
+        huffman = (buf.getbyte(0) & 0x80) == 0x80
+        len = integer(buf, 7)
+        str = buf.read(len)
+        raise CompressionError, "string too short" unless str.bytesize == len
+
+        str = Huffman.new.decode(str) if huffman
+        str.force_encoding(Encoding::UTF_8)
+      end
+
+      # Decodes header command from provided buffer.
+      #
+      # @param buf [Buffer]
+      # @return [Hash] command
+      def header(buf)
+        peek = buf.getbyte(0)
+
+        header = {}
+        header[:type], type = HEADREP.find do |_t, desc|
+          mask = (peek >> desc[:prefix]) << desc[:prefix]
+          mask == desc[:pattern]
+        end
+
+        raise CompressionError unless header[:type]
+
+        header[:name] = integer(buf, type[:prefix])
+
+        case header[:type]
+        when :indexed
+          raise CompressionError if (header[:name]).zero?
+
+          header[:name] -= 1
+        when :changetablesize
+          header[:value] = header[:name]
+        else
+          if (header[:name]).zero?
+            header[:name] = string(buf)
+          else
+            header[:name] -= 1
+          end
+          header[:value] = string(buf)
+        end
+
+        header
+      end
+
+      FORBIDDEN_HEADERS = %w[connection te].freeze
+
+      # Decodes and processes header commands within provided buffer.
+      #
+      # @param buf [Buffer]
+      # @param frame [HTTP2::Frame, nil]
+      # @return [Array] +[[name, value], ...]
+      def decode(buf, frame = nil)
+        list = []
+        decoding_pseudo_headers = true
+        @cc.listen_on_table do
+          until buf.empty?
+            field, value = @cc.process(header(buf))
+            next if field.nil?
+
+            is_pseudo_header = field.start_with? ":"
+            if !decoding_pseudo_headers && is_pseudo_header
+              raise ProtocolError, "one or more pseudo headers encountered after regular headers"
+            end
+
+            decoding_pseudo_headers = is_pseudo_header
+            raise ProtocolError, "invalid header received: #{field}" if FORBIDDEN_HEADERS.include?(field)
+
+            if frame
+              case field
+              when ":status"
+                frame[:status] = Integer(value)
+              when ":method"
+                frame[:method] = value
+              when "content-length"
+                frame[:content_length] = Integer(value)
+              when "trailer"
+                (frame[:trailer] ||= []) << value
+              end
+            end
+            list << [field, value]
+          end
+        end
+        list
+      end
+    end
+  end
+end

data/lib/http/2/header/encoding_context.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module HTTP2
+  # To decompress header blocks, a decoder only needs to maintain a
+  # dynamic table as a decoding context.
+  # No other state information is needed.
+  module Header
+    class EncodingContext
+      include Error
+
+      UPPER = /[[:upper:]]/.freeze
+
+      # @private
+      # Static table
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-10#appendix-A
+      STATIC_TABLE = [
+        [":authority",                  ""],
+        [":method",                     "GET"],
+        [":method",                     "POST"],
+        [":path",                       "/"],
+        [":path",                       "/index.html"],
+        [":scheme",                     "http"],
+        [":scheme",                     "https"],
+        [":status",                     "200"],
+        [":status",                     "204"],
+        [":status",                     "206"],
+        [":status",                     "304"],
+        [":status",                     "400"],
+        [":status",                     "404"],
+        [":status",                     "500"],
+        ["accept-charset",              ""],
+        ["accept-encoding",             "gzip, deflate"],
+        ["accept-language",             ""],
+        ["accept-ranges",               ""],
+        ["accept",                      ""],
+        ["access-control-allow-origin", ""],
+        ["age",                         ""],
+        ["allow",                       ""],
+        ["authorization",               ""],
+        ["cache-control",               ""],
+        ["content-disposition",         ""],
+        ["content-encoding",            ""],
+        ["content-language",            ""],
+        ["content-length",              ""],
+        ["content-location",            ""],
+        ["content-range",               ""],
+        ["content-type",                ""],
+        ["cookie",                      ""],
+        ["date",                        ""],
+        ["etag",                        ""],
+        ["expect",                      ""],
+        ["expires",                     ""],
+        ["from",                        ""],
+        ["host",                        ""],
+        ["if-match",                    ""],
+        ["if-modified-since",           ""],
+        ["if-none-match",               ""],
+        ["if-range",                    ""],
+        ["if-unmodified-since",         ""],
+        ["last-modified",               ""],
+        ["link",                        ""],
+        ["location",                    ""],
+        ["max-forwards",                ""],
+        ["proxy-authenticate",          ""],
+        ["proxy-authorization",         ""],
+        ["range",                       ""],
+        ["referer",                     ""],
+        ["refresh",                     ""],
+        ["retry-after",                 ""],
+        ["server",                      ""],
+        ["set-cookie",                  ""],
+        ["strict-transport-security",   ""],
+        ["transfer-encoding",           ""],
+        ["user-agent",                  ""],
+        ["vary",                        ""],
+        ["via",                         ""],
+        ["www-authenticate",            ""]
+      ].each { |pair| pair.each(&:freeze).freeze }.freeze
+
+      STATIC_TABLE_BY_FIELD = STATIC_TABLE
+                              .each_with_object({})
+                              .with_index { |((field, value), hs), idx| (hs[field] ||= []) << [idx, value] }
+                              .each { |pair| pair.each(&:freeze).freeze }.freeze
+
+      STATIC_TABLE_SIZE = STATIC_TABLE.size
+
+      # Current table of header key-value pairs.
+      attr_reader :table
+
+      # Current encoding options
+      #
+      #   :table_size  Integer  maximum dynamic table size in bytes
+      #   :huffman     Symbol   :always, :never, :shorter
+      #   :index       Symbol   :all, :static, :never
+      attr_reader :options
+
+      # Initializes compression context with appropriate client/server
+      # defaults and maximum size of the dynamic table.
+      #
+      # @param options [Hash] encoding options
+      #   :table_size  Integer  maximum dynamic table size in bytes
+      #   :huffman     Symbol   :always, :never, :shorter
+      #   :index       Symbol   :all, :static, :never
+      def initialize(options = {})
+        default_options = {
+          huffman: :shorter,
+          index: :all,
+          table_size: 4096
+        }
+        @table = []
+        @options = default_options.merge(options)
+        @limit = @options[:table_size]
+        @_table_updated = false
+      end
+
+      # Duplicates current compression context
+      # @return [EncodingContext]
+      def dup
+        other = EncodingContext.new(@options)
+        t = @table
+        l = @limit
+        other.instance_eval do
+          @table = t.dup # shallow copy
+          @limit = l
+        end
+        other
+      end
+
+      # Finds an entry in current dynamic table by index.
+      # Note that index is zero-based in this module.
+      #
+      # If the index is greater than the last index in the static table,
+      # an entry in the dynamic table is dereferenced.
+      #
+      # If the index is greater than the last header index, an error is raised.
+      #
+      # @param index [Integer] zero-based index in the dynamic table.
+      # @return [Array] +[key, value]+
+      def dereference(index)
+        # NOTE: index is zero-based in this module.
+        value = STATIC_TABLE[index] || @table[index - STATIC_TABLE_SIZE]
+        raise CompressionError, "Index too large" unless value
+
+        value
+      end
+
+      # Header Block Processing
+      # - http://tools.ietf.org/html/draft-ietf-httpbis-header-compression-10#section-4.1
+      #
+      # @param cmd [Hash] { type:, name:, value:, index: }
+      # @return [Array, nil] +[name, value]+ header field that is added to the decoded header list,
+      #                                      or nil if +cmd[:type]+ is +:changetablesize+
+      def process(cmd)
+        emit = nil
+
+        case cmd[:type]
+        when :changetablesize
+          raise CompressionError, "tried to change table size after adding elements to table" if @_table_updated
+
+          # we can receive multiple table size change commands inside a header frame. However,
+          # we should blow up if we receive another frame where the new table size is bigger.
+          table_size_updated = @limit != @options[:table_size]
+
+          raise CompressionError, "dynamic table size update exceed limit" if !table_size_updated && cmd[:value] > @limit
+
+          self.table_size = cmd[:value]
+
+        when :indexed
+          # Indexed Representation
+          # An _indexed representation_ entails the following actions:
+          # o  The header field corresponding to the referenced entry in either
+          # the static table or dynamic table is added to the decoded header
+          # list.
+          idx = cmd[:name]
+
+          k, v = dereference(idx)
+          emit = [k, v]
+
+        when :incremental, :noindex, :neverindexed
+          # A _literal representation_ that is _not added_ to the dynamic table
+          # entails the following action:
+          # o  The header field is added to the decoded header list.
+
+          # A _literal representation_ that is _added_ to the dynamic table
+          # entails the following actions:
+          # o  The header field is added to the decoded header list.
+          # o  The header field is inserted at the beginning of the dynamic table.
+
+          case cmd[:name]
+          when Integer
+            k, v = dereference(cmd[:name])
+
+            cmd = cmd.dup
+            cmd[:index] ||= cmd[:name]
+            cmd[:value] ||= v
+            cmd[:name] = k
+          when UPPER
+            raise ProtocolError, "Invalid uppercase key: #{cmd[:name]}"
+          end
+
+          emit = [cmd[:name], cmd[:value]]
+
+          add_to_table(emit) if cmd[:type] == :incremental
+
+        else
+          raise CompressionError, "Invalid type: #{cmd[:type]}"
+        end
+
+        emit
+      end
+
+      # Plan header compression according to +@options [:index]+
+      #  :never   Do not use dynamic table or static table reference at all.
+      #  :static  Use static table only.
+      #  :all     Use all of them.
+      #
+      # @param headers [Array] +[[name, value], ...]+
+      # @return [Array] array of commands
+      def encode(headers)
+        commands = []
+        # Literals commands are marked with :noindex when index is not used
+        noindex = %i[static never].include?(@options[:index])
+        headers.each do |field, value|
+          # Literal header names MUST be translated to lowercase before
+          # encoding and transmission.
+          field = field.downcase if UPPER.match?(field)
+          value = "/" if field == ":path" && value.empty?
+          cmd = addcmd(field, value)
+          cmd[:type] = :noindex if noindex && cmd[:type] == :incremental
+          commands << cmd
+          process(cmd)
+        end
+        commands
+      end
+
+      # Emits command for a header.
+      # Prefer static table over dynamic table.
+      # Prefer exact match over name-only match.
+      #
+      # +@options [:index]+ controls whether to use the dynamic table,
+      # static table, or both.
+      #  :never   Do not use dynamic table or static table reference at all.
+      #  :static  Use static table only.
+      #  :all     Use all of them.
+      #
+      # @param header [Array] +[name, value]+
+      # @return [Hash] command
+      def addcmd(*header)
+        exact = nil
+        name_only = nil
+
+        if %i[all static].include?(@options[:index])
+          field, value = header
+          if (svalues = STATIC_TABLE_BY_FIELD[field])
+            svalues.each do |i, svalue|
+              name_only ||= i
+              if svalue == value
+                exact = i
+                break
+              end
+            end
+          end
+        end
+        if [:all].include?(@options[:index]) && !exact
+          @table.each_index do |i|
+            if @table[i] == header
+              exact ||= i + STATIC_TABLE_SIZE
+              break
+            elsif @table[i].first == header.first
+              name_only ||= i + STATIC_TABLE_SIZE
+            end
+          end
+        end
+
+        if exact
+          { name: exact, type: :indexed }
+        elsif name_only
+          { name: name_only, value: header.last, type: :incremental }
+        else
+          { name: header.first, value: header.last, type: :incremental }
+        end
+      end
+
+      # Alter dynamic table size.
+      #  When the size is reduced, some headers might be evicted.
+      def table_size=(size)
+        @limit = size
+        size_check(nil)
+      end
+
+      # Returns current table size in octets
+      # @return [Integer]
+      def current_table_size
+        @table.inject(0) { |r, (k, v)| r + k.bytesize + v.bytesize + 32 }
+      end
+
+      def listen_on_table
+        yield
+      ensure
+        @_table_updated = false
+      end
+
+      private
+
+      # Add a name-value pair to the dynamic table.
+      # Older entries might have been evicted so that
+      # the new entry fits in the dynamic table.
+      #
+      # @param cmd [Array] +[name, value]+
+      def add_to_table(cmd)
+        return unless size_check(cmd)
+
+        @table.unshift(cmd)
+        @_table_updated = true
+      end
+
+      # To keep the dynamic table size lower than or equal to @limit,
+      # remove one or more entries at the end of the dynamic table.
+      #
+      # @param cmd [Hash]
+      # @return [Boolean] whether +cmd+ fits in the dynamic table.
+      def size_check(cmd)
+        cursize = current_table_size
+        cmdsize = cmd.nil? ? 0 : cmd[0].bytesize + cmd[1].bytesize + 32
+
+        while cursize + cmdsize > @limit
+          break if @table.empty?
+
+          e = @table.pop
+          cursize -= e[0].bytesize + e[1].bytesize + 32
+        end
+
+        cmdsize <= @limit
+      end
+    end
+  end
+end

data/lib/http/2/{huffman.rb → header/huffman.rb}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'error'
+require_relative "../error"
+require_relative "../extensions"
 
 module HTTP2
   # Implementation of huffman encoding for HPACK
@@ -9,7 +10,10 @@ module HTTP2
   module Header
     # Huffman encoder/decoder
     class Huffman
+      using StringExtensions
+
       include Error
+      include PackingExtensions
 
       BITS_AT_ONCE = 4
       EOS = 256
@@ -22,8 +26,8 @@ module HTTP2
       # @return [String] binary string
       def encode(str)
         bitstring = str.each_byte.map { |chr| ENCODE_TABLE[chr] }.join
-        bitstring << ('1' * ((8 - bitstring.size) % 8))
-        [bitstring].pack('B*')
+        bitstring << ("1" * ((8 - bitstring.size) % 8))
+        [bitstring].pack("B*")
       end
 
       # Decodes provided Huffman coded string.
@@ -32,7 +36,7 @@ module HTTP2
       # @return [String] binary string
       # @raise [CompressionError] when Huffman coded string is malformed
       def decode(buf)
-        emit = String.new
+        emit = "".b
         state = 0 # start state
 
         mask = (1 << BITS_AT_ONCE) - 1
@@ -45,14 +49,14 @@ module HTTP2
             #  [emit] character to be emitted on this transition, empty string, or EOS.
             #  [next] next state number.
             trans = MACHINE[state][branch]
-            raise CompressionError, 'Huffman decode error (EOS found)' if trans.first == EOS
+            raise CompressionError, "Huffman decode error (EOS found)" if trans.first == EOS
 
             emit << trans.first.chr if trans.first
             state = trans.last
           end
         end
         # Check whether partial input is correctly filled
-        raise CompressionError, 'Huffman decode error (EOS invalid)' unless state <= MAX_FINAL_STATE
+        raise CompressionError, "Huffman decode error (EOS invalid)" unless state <= MAX_FINAL_STATE
 
         emit.force_encoding(Encoding::BINARY)
       end
@@ -319,7 +323,7 @@ module HTTP2
         [0x3fffffff, 30]
       ].each(&:freeze).freeze
 
-      ENCODE_TABLE = CODES.map { |c, l| [c].pack('N').unpack1('B*')[-l..-1] }.each(&:freeze).freeze
+      ENCODE_TABLE = CODES.map { |c, l| [c].pack("N").unpack1("B*")[-l..-1] }.each(&:freeze).freeze
     end
   end
 end