protocol-http2 0.1.0

data/lib/protocol/http2/continuation_frame.rb

@@ -0,0 +1,98 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'frame'
+
+module Protocol
+	module HTTP2
+		module Continued
+			def initialize(*)
+				super
+				
+				@continuation = nil
+			end
+			
+			def end_headers?
+				flag_set?(END_HEADERS)
+			end
+			
+			def read(stream, maximum_frame_size)
+				super
+				
+				unless end_headers?
+					@continuation = ContinuationFrame.new
+					
+					@continuation.read(stream, maximum_frame_size)
+				end
+			end
+			
+			def write(stream)
+				super
+				
+				if continuation = self.continuation
+					continuation.write(stream)
+				end
+			end
+			
+			attr_accessor :continuation
+			
+			def pack(data, **options)
+				maximum_size = options[:maximum_size]
+				
+				if maximum_size and data.bytesize > maximum_size
+					clear_flags(END_HEADERS)
+					
+					super(data.byteslice(0, maximum_size), **options)
+					
+					remainder = data.byteslice(maximum_size, data.bytesize-maximum_size)
+					
+					@continuation = ContinuationFrame.new
+					@continuation.pack(remainder, maximum_size: maximum_size)
+				else
+					set_flags(END_HEADERS)
+					
+					super data, **options
+					
+					@continuation = nil
+				end
+			end
+			
+			def unpack
+				if @continuation.nil?
+					super
+				else
+					super + @continuation.unpack
+				end
+			end
+		end
+		
+		# The CONTINUATION frame is used to continue a sequence of header block fragments. Any number of CONTINUATION frames can be sent, as long as the preceding frame is on the same stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without the END_HEADERS flag set.
+		#
+		# +---------------------------------------------------------------+
+		# |                   Header Block Fragment (*)                 ...
+		# +---------------------------------------------------------------+
+		#
+		class ContinuationFrame < Frame
+			include Continued
+			
+			TYPE = 0x9
+		end
+	end
+end

data/lib/protocol/http2/data_frame.rb

@@ -0,0 +1,62 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2013, by Ilya Grigorik.
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'frame'
+require_relative 'padded'
+
+module Protocol
+	module HTTP2
+		# DATA frames convey arbitrary, variable-length sequences of octets associated with a stream. One or more DATA frames are used, for instance, to carry HTTP request or response payloads.
+		# 
+		# DATA frames MAY also contain padding. Padding can be added to DATA frames to obscure the size of messages.
+		# 
+		# +---------------+
+		# |Pad Length? (8)|
+		# +---------------+-----------------------------------------------+
+		# |                            Data (*)                         ...
+		# +---------------------------------------------------------------+
+		# |                           Padding (*)                       ...
+		# +---------------------------------------------------------------+
+		#
+		class DataFrame < Frame
+			include Padded
+			
+			TYPE = 0x0
+			
+			def end_stream?
+				flag_set?(END_STREAM)
+			end
+			
+			def pack(data, *)
+				if data
+					super
+				else
+					@length = 0
+					set_flags(END_STREAM)
+				end
+			end
+			
+			def apply(connection)
+				connection.receive_data(self)
+			end
+		end
+	end
+end

data/lib/protocol/http2/error.rb

@@ -0,0 +1,36 @@
+# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'protocol/http/error'
+
+module Protocol
+	module HTTP2
+		class ProtocolError < HTTP::ProtocolError
+		end
+		
+		# When the frame payload does not match expectations.
+		class FrameSizeError < ProtocolError
+		end
+		
+		# Raised on invalid flow control frame or command.
+		class FlowControlError < ProtocolError
+		end
+	end
+end

data/lib/protocol/http2/flow_control.rb

@@ -0,0 +1,84 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'window_update_frame'
+
+module Protocol
+	module HTTP2
+		module FlowControl
+			def available_frame_size
+				maximum_frame_size = self.maximum_frame_size
+				available_size = @remote_window.available
+				
+				if available_size < maximum_frame_size
+					return available_size
+				else
+					return maximum_frame_size
+				end
+			end
+			
+			# Keep track of the amount of data sent, and fail if is too much.
+			def consume_remote_window(frame)
+				amount = frame.length
+				
+				# 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.
+				if amount.zero? and frame.end_stream?
+					# It's okay, we can send. No need to consume, it's empty anyway.
+				elsif amount >= 0 and amount <= @remote_window.available
+					@remote_window.consume(amount)
+				else
+					raise FlowControlError, "Trying to send #{frame.length} bytes, exceeded window size: #{@remote_window.available} (#{@remote_window})"
+				end
+			end
+			
+			def consume_local_window(frame)
+				amount = frame.length
+				
+				@local_window.consume(amount)
+				
+				if @local_window.limited?
+					self.send_window_update(@local_window.used)
+				end
+			end
+			
+			# Notify the remote end that we are prepared to receive more data:
+			def send_window_update(window_increment)
+				frame = WindowUpdateFrame.new(self.id)
+				frame.pack window_increment
+				
+				write_frame(frame)
+				
+				@local_window.expand(window_increment)
+			end
+			
+			def receive_window_update(frame)
+				was_full = @remote_window.full?
+				
+				# puts "expand remote_window=#{@remote_window} by #{frame.unpack}"
+				@remote_window.expand(frame.unpack)
+				
+				self.window_updated if was_full
+			end
+			
+			def window_updated
+			end
+		end
+	end
+end

data/lib/protocol/http2/frame.rb

@@ -0,0 +1,193 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2013, by Ilya Grigorik.
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'error'
+
+module Protocol
+	module HTTP2
+		END_STREAM = 0x1
+		END_HEADERS = 0x4
+		PADDED = 0x8
+		PRIORITY = 0x20
+		
+		MAXIMUM_ALLOWED_WINDOW_SIZE = 0x7FFFFFFF
+		MAXIMUM_ALLOWED_FRAME_SIZE = 0xFFFFFF
+		
+		class Frame
+			include Comparable
+			
+			# Stream Identifier cannot be bigger than this:
+			# https://http2.github.stream/http2-spec/#rfc.section.4.1
+			VALID_STREAM_ID = 0..0x7fffffff
+			
+			# The absolute maximum bounds for the length field:
+			VALID_LENGTH = 0..0xffffff
+			
+			# Used for generating 24-bit frame length:
+			LENGTH_HISHIFT = 16
+			LENGTH_LOMASK  = 0xFFFF
+			
+			# @param length [Integer] the length of the payload, or nil if the header has not been read yet.
+			def initialize(stream_id = 0, flags = 0, type = self.class.const_get(:TYPE), length = nil, payload = nil)
+				@length = length
+				@type = type
+				@flags = flags
+				@stream_id = stream_id
+				@payload = payload
+			end
+			
+			def <=> other
+				to_ary <=> other.to_ary
+			end
+			
+			def to_ary
+				[@length, @type, @flags, @stream_id, @payload]
+			end
+			
+			# The generic frame header uses the following binary representation:
+			#
+			# +-----------------------------------------------+
+			# |                 Length (24)                   |
+			# +---------------+---------------+---------------+
+			# |   Type (8)    |   Flags (8)   |
+			# +-+-------------+---------------+-------------------------------+
+			# |R|                 Stream Identifier (31)                      |
+			# +=+=============================================================+
+			# |                   Frame Payload (0...)                      ...
+			# +---------------------------------------------------------------+
+			
+			attr_accessor :length
+			attr_accessor :type
+			attr_accessor :flags
+			attr_accessor :stream_id
+			attr_accessor :payload
+			
+			def unpack
+				@payload
+			end
+			
+			def pack(payload, maximum_size: nil)
+				@payload = payload
+				@length = payload.bytesize
+				
+				if maximum_size and @length > maximum_size
+					raise ProtocolError, "Frame length #{@length} bigger than maximum allowed: #{maximum_size}"
+				end
+			end
+			
+			def set_flags(mask)
+				@flags |= mask
+			end
+			
+			def clear_flags(mask)
+				@flags &= ~mask
+			end
+			
+			def flag_set?(mask)
+				@flags & mask != 0
+			end
+			
+			# Check if frame is a connection frame: SETTINGS, PING, GOAWAY, and any
+			# frame addressed to stream ID = 0.
+			#
+			# @return [Boolean]
+			def connection?
+				@stream_id.zero?
+			end
+			
+			HEADER_FORMAT = 'CnCCN'.freeze
+			STREAM_ID_MASK  = 0x7fffffff
+			
+			# Generates common 9-byte frame header.
+			# - http://tools.ietf.org/html/draft-ietf-httpbis-http2-16#section-4.1
+			#
+			# @return [String]
+			def header
+				unless VALID_LENGTH.include? @length
+					raise ProtocolError, "Invalid frame size: #{@length.inspect}"
+				end
+				
+				unless VALID_STREAM_ID.include? @stream_id
+					raise ProtocolError, "Invalid stream identifier: #{@stream_id.inspect}"
+				end
+				
+				[
+					# These are guaranteed correct due to the length check above.
+					@length >> LENGTH_HISHIFT,
+					@length & LENGTH_LOMASK,
+					@type,
+					@flags,
+					@stream_id
+				].pack(HEADER_FORMAT)
+			end
+			
+			# Decodes common 9-byte header.
+			#
+			# @param buffer [String]
+			def self.parse_header(buffer)
+				length_hi, length_lo, type, flags, stream_id = buffer.unpack(HEADER_FORMAT)
+				length = (length_hi << LENGTH_HISHIFT) | length_lo
+				stream_id = stream_id & STREAM_ID_MASK
+				
+				return length, type, flags, stream_id
+			end
+			
+			def read_header(stream)
+				@length, @type, @flags, @stream_id = Frame.parse_header(stream.read(9))
+			end
+			
+			def read_payload(stream)
+				@payload = stream.read(@length)
+			end
+			
+			def read(stream, maximum_frame_size = MAXIMUM_ALLOWED_FRAME_SIZE)
+				read_header(stream) unless @length
+				
+				if @length > maximum_frame_size
+					raise FrameSizeError, "#{self.class} (type=#{@type}) frame length #{@length} exceeds maximum frame size #{maximum_frame_size}!"
+				end
+				
+				read_payload(stream)
+			end
+			
+			def write_header(stream)
+				stream.write self.header
+			end
+			
+			def write_payload(stream)
+				stream.write(@payload) if @payload
+			end
+			
+			def write(stream)
+				if @payload and @length != @payload.bytesize
+					raise ProtocolError, "Invalid payload size: #{@length} != #{@payload.bytesize}"
+				end
+				
+				self.write_header(stream)
+				self.write_payload(stream)
+			end
+			
+			def apply(connection)
+				connection.receive_frame(self)
+			end
+		end
+	end
+end

data/lib/protocol/http2/framer.rb

@@ -0,0 +1,113 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2013, by Ilya Grigorik.
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'error'
+
+require_relative 'data_frame'
+require_relative 'headers_frame'
+require_relative 'priority_frame'
+require_relative 'reset_stream_frame'
+require_relative 'settings_frame'
+require_relative 'push_promise_frame'
+require_relative 'ping_frame'
+require_relative 'goaway_frame'
+require_relative 'window_update_frame'
+require_relative 'continuation_frame'
+
+module Protocol
+	module HTTP2
+		# HTTP/2 frame type mapping as defined by the spec
+		FRAMES = [
+			DataFrame,
+			HeadersFrame,
+			PriorityFrame,
+			ResetStreamFrame,
+			SettingsFrame,
+			PushPromiseFrame,
+			PingFrame,
+			GoawayFrame,
+			WindowUpdateFrame,
+			ContinuationFrame,
+		].freeze
+		
+		# Default connection "fast-fail" preamble string as defined by the spec.
+		CONNECTION_PREFACE_MAGIC = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".freeze
+		
+		class Framer
+			def initialize(stream, frames = FRAMES)
+				@stream = stream
+				@frames = frames
+			end
+			
+			def close
+				@stream.close
+			end
+			
+			def write_connection_preface
+				@stream.write(CONNECTION_PREFACE_MAGIC)
+			end
+			
+			def read_connection_preface
+				string = @stream.read(CONNECTION_PREFACE_MAGIC.bytesize)
+				
+				unless string == CONNECTION_PREFACE_MAGIC
+					raise ProtocolError, "Invalid connection preface: #{string.inspect}"
+				end
+				
+				return string
+			end
+			
+			def read_frame(maximum_frame_size = MAXIMUM_ALLOWED_FRAME_SIZE)
+				# Read the header:
+				length, type, flags, stream_id = read_header
+				
+				# puts "framer: read_frame #{type} #{length}"
+				
+				# Allocate the frame:
+				klass = @frames[type] || Frame
+				frame = klass.new(stream_id, flags, type, length)
+				
+				# Read the payload:
+				frame.read(@stream, maximum_frame_size)
+				
+				return frame
+			end
+			
+			def write_frame(frame)
+				# puts "framer: write_frame #{frame.inspect}"
+				frame.write(@stream)
+				
+				@stream.flush
+				
+				return frame
+			end
+			
+			def read_header
+				if buffer = @stream.read(9)
+					return Frame.parse_header(buffer)
+				else
+					# TODO: Is this necessary? I thought the IO would throw this.
+					raise EOFError
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http2/goaway_frame.rb

@@ -0,0 +1,60 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'frame'
+
+module Protocol
+	module HTTP2
+		# The GOAWAY frame is used to initiate shutdown of a connection or to signal serious error conditions. GOAWAY allows an endpoint to gracefully stop accepting new streams while still finishing processing of previously established streams. This enables administrative actions, like server maintenance.
+		#
+		# +-+-------------------------------------------------------------+
+		# |R|                  Last-Stream-ID (31)                        |
+		# +-+-------------------------------------------------------------+
+		# |                      Error Code (32)                          |
+		# +---------------------------------------------------------------+
+		# |                  Additional Debug Data (*)                    |
+		# +---------------------------------------------------------------+
+		#
+		class GoawayFrame < Frame
+			TYPE = 0x7
+			FORMAT = "NN"
+			
+			def connection?
+				true
+			end
+			
+			def unpack
+				data = super
+				
+				last_stream_id, error_code = data.unpack(FORMAT)
+				
+				return last_stream_id, error_code, data.slice(8, data.bytesize-8)
+			end
+			
+			def pack(last_stream_id, error_code, data)
+				super [last_stream_id, error_code].pack(FORMAT) + data
+			end
+			
+			def apply(connection)
+				connection.receive_goaway(self)
+			end
+		end
+	end
+end