protocol-http2 0.1.0

data/lib/protocol/http2/settings_frame.rb

@@ -0,0 +1,237 @@
+# 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 'ping_frame'
+
+module Protocol
+	module HTTP2
+		class Settings
+			HEADER_TABLE_SIZE = 0x1
+			ENABLE_PUSH = 0x2
+			MAXIMUM_CONCURRENT_STREAMS = 0x3
+			INITIAL_WINDOW_SIZE = 0x4
+			MAXIMUM_FRAME_SIZE = 0x5
+			MAXIMUM_HEADER_LIST_SIZE = 0x6
+			
+			# Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets.
+			attr_accessor :header_table_size
+			
+			# This setting can be used to disable server push. An endpoint MUST NOT send a PUSH_PROMISE frame if it receives this parameter set to a value of 0.
+			attr :enable_push
+			
+			def enable_push= value
+				if @enable_push == 0 || @enable_push == 1
+					@enable_push = value
+				else
+					raise ProtocolError, "Invalid value for enable_push: #{value}"
+				end
+			end
+			
+			def enable_push?
+				@enable_push != 0
+			end
+			
+			# Indicates the maximum number of concurrent streams that the sender will allow.
+			attr_accessor :maximum_concurrent_streams
+			
+			# Indicates the sender's initial window size (in octets) for stream-level flow control.
+			attr :initial_window_size
+			
+			def initial_window_size= value
+				if value <= MAXIMUM_ALLOWED_WINDOW_SIZE
+					@initial_window_size = value
+				else
+					raise FlowControlError, "Invalid value for initial_window_size: #{value} > #{MAXIMUM_ALLOWED_WINDOW_SIZE}"
+				end
+			end
+			
+			# Indicates the size of the largest frame payload that the sender is willing to receive, in octets.
+			attr :maximum_frame_size
+			
+			def maximum_frame_size= value
+				if value <= MAXIMUM_ALLOWED_FRAME_SIZE
+					@maximum_frame_size = value
+				else
+					raise ProtocolError, "Invalid value for maximum_frame_size: #{value} > #{MAXIMUM_ALLOWED_FRAME_SIZE}"
+				end
+			end
+			
+			# This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets.
+			attr_accessor :maximum_header_list_size
+			
+			def initialize
+				# These limits are taken from the RFC:
+				# https://tools.ietf.org/html/rfc7540#section-6.5.2
+				@header_table_size = 4096
+				@enable_push = 1
+				@maximum_concurrent_streams = 0xFFFFFFFF
+				@initial_window_size = 0xFFFF # 2**16 - 1
+				@maximum_frame_size = 0x4000 # 2**14
+				@maximum_header_list_size = 0xFFFFFFFF
+			end
+			
+			ASSIGN = [
+				nil,
+				:header_table_size=,
+				:enable_push=,
+				:maximum_concurrent_streams=,
+				:initial_window_size=,
+				:maximum_frame_size=,
+				:maximum_header_list_size=,
+			]
+			
+			def update(changes)
+				changes.each do |key, value|
+					if name = ASSIGN[key]
+						self.send(name, value)
+					end
+				end
+			end
+			
+			def difference(other)
+				changes = []
+				
+				if @header_table_size != other.header_table_size
+					changes << [HEADER_TABLE_SIZE, @header_table_size]
+				end
+				
+				if @enable_push != other.enable_push
+					changes << [ENABLE_PUSH, @enable_push ? 1 : 0]
+				end
+				
+				if @maximum_concurrent_streams != other.maximum_concurrent_streams
+					changes << [MAXIMUM_CONCURRENT_STREAMS, @maximum_concurrent_streams]
+				end
+				
+				if @initial_window_size != other.initial_window_size
+					changes << [INITIAL_WINDOW_SIZE, @initial_window_size]
+				end
+				
+				if @maximum_frame_size != other.maximum_frame_size
+					changes << [MAXIMUM_FRAME_SIZE, @maximum_frame_size]
+				end
+				
+				if @maximum_header_list_size != other.maximum_header_list_size
+					changes << [MAXIMUM_HEADER_LIST_SIZE, @maximum_header_list_size]
+				end
+				
+				return changes
+			end
+		end
+		
+		class PendingSettings
+			def initialize(current = Settings.new)
+				@current = current
+				@pending = current.dup
+				
+				@queue = []
+			end
+			
+			attr :current
+			attr :pending
+			
+			def append(changes)
+				@queue << changes
+				@pending.update(changes)
+			end
+			
+			def acknowledge
+				if changes = @queue.shift
+					@current.update(changes)
+					
+					return changes
+				else
+					raise ProtocolError.new("Cannot acknowledge settings, no changes pending")
+				end
+			end
+			
+			def header_table_size
+				@current.header_table_size
+			end
+			
+			def enable_push
+				@current.enable_push
+			end
+			
+			def maximum_concurrent_streams
+				@current.maximum_concurrent_streams
+			end
+			
+			def initial_window_size
+				@current.initial_window_size
+			end
+			
+			def maximum_frame_size
+				@current.maximum_frame_size
+			end
+			
+			def maximum_header_list_size
+				@current.maximum_header_list_size
+			end
+		end
+		
+		# The SETTINGS frame conveys configuration parameters that affect how endpoints communicate, such as preferences and constraints on peer behavior. The SETTINGS frame is also used to acknowledge the receipt of those parameters. Individually, a SETTINGS parameter can also be referred to as a "setting".
+		# 
+		# +-------------------------------+
+		# |       Identifier (16)         |
+		# +-------------------------------+-------------------------------+
+		# |                        Value (32)                             |
+		# +---------------------------------------------------------------+
+		#
+		class SettingsFrame < Frame
+			TYPE = 0x4
+			FORMAT = "nN".freeze
+			
+			include Acknowledgement
+			
+			def connection?
+				true
+			end
+			
+			def unpack
+				super.scan(/....../).map{|s| s.unpack(FORMAT)}
+			end
+			
+			def pack(settings = [])
+				super settings.map{|s| s.pack(FORMAT)}.join
+			end
+			
+			def apply(connection)
+				connection.receive_settings(self)
+			end
+			
+			def read_payload(stream)
+				super
+				
+				if @stream_id != 0
+					raise ProtocolError, "Settings apply to connection only, but stream_id was given"
+				end
+				
+				if acknowledgement? and @length != 0
+					raise FrameSizeError, "Settings acknowledgement must not contain payload: #{@payload.inspect}"
+				end
+				
+				if (@length % 6) != 0
+					raise FrameSizeError, "Invalid frame length"
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http2/stream.rb

@@ -0,0 +1,372 @@
+# 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 'connection'
+require_relative 'flow_control'
+
+module Protocol
+	module HTTP2
+		# A single HTTP 2.0 connection can multiplex multiple streams in parallel:
+		# multiple requests and responses can be in flight simultaneously and stream
+		# data can be interleaved and prioritized.
+		#
+		# This class encapsulates all of the state, transition, flow-control, and
+		# error management as defined by the HTTP 2.0 specification. All you have
+		# to do is subscribe to appropriate events (marked with ":" prefix in
+		# diagram below) and provide your application logic to handle request
+		# and response processing.
+		#
+		#                          +--------+
+		#                  send PP |        | recv PP
+		#                 ,--------|  idle  |--------.
+		#                /         |        |         \
+		#               v          +--------+          v
+		#        +----------+          |           +----------+
+		#        |          |          | send H /  |          |
+		# ,------| reserved |          | recv H    | reserved |------.
+		# |      | (local)  |          |           | (remote) |      |
+		# |      +----------+          v           +----------+      |
+		# |          |             +--------+             |          |
+		# |          |     recv ES |        | send ES     |          |
+		# |   send H |     ,-------|  open  |-------.     | recv H   |
+		# |          |    /        |        |        \    |          |
+		# |          v   v         +--------+         v   v          |
+		# |      +----------+          |           +----------+      |
+		# |      |   half   |          |           |   half   |      |
+		# |      |  closed  |          | send R /  |  closed  |      |
+		# |      | (remote) |          | recv R    | (local)  |      |
+		# |      +----------+          |           +----------+      |
+		# |           |                |                 |           |
+		# |           | send ES /      |       recv ES / |           |
+		# |           | send R /       v        send R / |           |
+		# |           | recv R     +--------+   recv R   |           |
+		# | send R /  `----------->|        |<-----------'  send R / |
+		# | recv R                 | closed |               recv R   |
+		# `----------------------->|        |<----------------------'
+		#                          +--------+
+		# 
+		#    send:   endpoint sends this frame
+		#    recv:   endpoint receives this frame
+		# 
+		#    H:  HEADERS frame (with implied CONTINUATIONs)
+		#    PP: PUSH_PROMISE frame (with implied CONTINUATIONs)
+		#    ES: END_STREAM flag
+		#    R:  RST_STREAM frame
+		#
+		class Stream
+			include FlowControl
+			
+			def initialize(connection, id = connection.next_stream_id)
+				@connection = connection
+				@id = id
+				
+				@connection.streams[@id] = self
+				
+				@state = :idle
+				
+				@priority = nil
+				@local_window = Window.new(connection.local_settings.initial_window_size)
+				@remote_window = Window.new(connection.remote_settings.initial_window_size)
+				
+				@headers = nil
+				@data = nil
+			end
+			
+			# Stream ID (odd for client initiated streams, even otherwise).
+			attr :id
+
+			# Stream state as defined by HTTP 2.0.
+			attr :state
+			
+			attr :headers
+			attr :data
+			
+			attr :local_window
+			attr :remote_window
+			
+			def maximum_frame_size
+				@connection.available_frame_size
+			end
+			
+			def write_frame(frame)
+				@connection.write_frame(frame)
+			end
+			
+			def closed?
+				@state == :closed or @state == :reset
+			end
+			
+			def send_headers?
+				@state == :idle or @state == :reserved_local or @state == :open or @state == :half_closed_remote
+			end
+			
+			def send_failure(status, reason)
+				if send_headers?
+					send_headers(nil, [
+						[':status', status.to_s],
+						['reason', reason]
+					], END_STREAM)
+				else
+					send_reset_stream(PROTOCOL_ERROR)
+				end
+				
+				return nil
+			end
+			
+			private def write_headers(priority, headers, flags = 0)
+				data = @connection.encode_headers(headers)
+				
+				frame = HeadersFrame.new(@id, flags)
+				frame.pack(priority, data, maximum_size: @connection.maximum_frame_size)
+				
+				write_frame(frame)
+				
+				return frame
+			end
+			
+			#The HEADERS frame is used to open a stream, and additionally carries a header block fragment.  HEADERS frames can be sent on a stream in the "idle", "reserved (local)", "open", or "half-closed (remote)" state.
+			def send_headers(*args)
+				if @state == :idle
+					frame = write_headers(*args)
+					
+					if frame.end_stream?
+						@state = :half_closed_local
+					else
+						@state = :open
+					end
+				elsif @state == :reserved_local
+					frame = write_headers(*args)
+					
+					@state = :half_closed_remote
+				elsif @state == :open
+					frame = write_headers(*args)
+					
+					if frame.end_stream?
+						@state = :half_closed_local
+					end
+				elsif @state == :half_closed_remote
+					frame = write_headers(*args)
+					
+					if frame.end_stream?
+						close!
+					end
+				else
+					raise ProtocolError, "Cannot send headers in state: #{@state}"
+				end
+			end
+			
+			def consume_remote_window(frame)
+				super
+				
+				@connection.consume_remote_window(frame)
+			end
+			
+			private def write_data(data, flags = 0, **options)
+				frame = DataFrame.new(@id, flags)
+				frame.pack(data, **options)
+				
+				# This might fail if the data payload was too big:
+				consume_remote_window(frame)
+				
+				write_frame(frame)
+				
+				return frame
+			end
+			
+			def send_data(*args)
+				if @state == :open
+					frame = write_data(*args)
+					
+					if frame.end_stream?
+						@state = :half_closed_local
+					end
+				elsif @state == :half_closed_remote
+					frame = write_data(*args)
+					
+					if frame.end_stream?
+						close!
+					end
+				else
+					raise ProtocolError, "Cannot send data in state: #{@state}"
+				end
+			end
+			
+			def close!(state = :closed)
+				@state = state
+				
+				@connection.streams.delete(@id)
+			end
+			
+			def send_reset_stream(error_code = 0)
+				if @state != :idle and @state != :closed
+					frame = ResetStreamFrame.new(@id)
+					frame.pack(error_code)
+					
+					write_frame(frame)
+					
+					close!(:reset)
+				else
+					raise ProtocolError, "Cannot reset stream in state: #{@state}"
+				end
+			end
+			
+			private def process_headers(frame)
+				# Receiving request headers:
+				priority, data = frame.unpack
+				
+				if priority
+					@priority = priority
+				end
+				
+				@connection.decode_headers(data)
+			end
+			
+			def receive_headers(frame)
+				if @state == :idle
+					if frame.end_stream?
+						@state = :half_closed_remote
+					else
+						@state = :open
+					end
+					
+					@headers = process_headers(frame)
+				elsif @state == :reserved_remote
+					@state = :half_closed_local
+					
+					@headers = process_headers(frame)
+				elsif @state == :open
+					if frame.end_stream?
+						@state = :half_closed_remote
+					end
+					
+					@headers = process_headers(frame)
+				elsif @state == :half_closed_local
+					if frame.end_stream?
+						close!
+					end
+					
+					@headers = process_headers(frame)
+				elsif @state == :reset
+					# ignore...
+				else
+					raise ProtocolError, "Cannot receive headers in state: #{@state}"
+				end
+			end
+			
+			# DATA frames are subject to flow control and can only be sent when a stream is in the "open" or "half-closed (remote)" state.  The entire DATA frame payload is included in flow control, including the Pad Length and Padding fields if present.  If a DATA frame is received whose stream is not in "open" or "half-closed (local)" state, the recipient MUST respond with a stream error of type STREAM_CLOSED.
+			def receive_data(frame)
+				if @state == :open
+					consume_local_window(frame)
+					
+					if frame.end_stream?
+						@state = :half_closed_remote
+					end
+					
+					@data = frame.unpack
+				elsif @state == :half_closed_local
+					consume_local_window(frame)
+					
+					if frame.end_stream?
+						close!
+					end
+					
+					@data = frame.unpack
+				elsif @state == :reset
+					# ignore...
+				else
+					raise ProtocolError, "Cannot receive data in state: #{@state}"
+				end
+			end
+			
+			def receive_priority(frame)
+				@priority = frame.unpack
+			end
+			
+			def receive_reset_stream(frame)
+				if @state != :idle and @state != :closed
+					close!
+					
+					return frame.unpack
+				else
+					raise ProtocolError, "Cannot reset stream in state: #{@state}"
+				end
+			end
+			
+			# A normal request is client request -> server response -> client.
+			# A push promise is server request -> client -> server response -> client.
+			# The server generates the same set of headers as if the client was sending a request, and sends these to the client. The client can reject the request by resetting the (new) stream. Otherwise, the server will start sending a response as if the client had send the request.
+			private def write_push_promise(stream_id, headers, flags = 0, **options)
+				data = @connection.encode_headers(headers)
+				
+				frame = PushPromiseFrame.new(@id, flags)
+				frame.pack(stream_id, data, maximum_size: @connection.maximum_frame_size)
+				
+				write_frame(frame)
+				
+				return frame
+			end
+			
+			def reserved_local!
+				if @state == :idle
+					@state = :reserved_local
+				else
+					raise ProtocolError, "Cannot reserve stream in state: #{@state}"
+				end
+			end
+			
+			def reserved_remote!
+				if @state == :idle
+					@state = :reserved_remote
+				else
+					raise ProtocolError, "Cannot reserve stream in state: #{@state}"
+				end
+			end
+			
+			def create_promise_stream(headers, stream_id)
+				@connection.create_stream(stream_id)
+			end
+			
+			# Server push is semantically equivalent to a server responding to a request; however, in this case, that request is also sent by the server, as a PUSH_PROMISE frame.
+			# @param headers [Hash] contains a complete set of request header fields that the server attributes to the request.
+			def send_push_promise(headers, stream_id = @connection.next_stream_id)
+				if @state == :open or @state == :half_closed_remote
+					promised_stream = self.create_promise_stream(headers, stream_id)
+					promised_stream.reserved_local!
+					
+					write_push_promise(promised_stream.id, headers)
+					
+					return promised_stream
+				else
+					raise ProtocolError, "Cannot send push promise in state: #{@state}"
+				end
+			end
+			
+			def receive_push_promise(frame)
+				promised_stream_id, data = frame.unpack
+				headers = @connection.decode_headers(data)
+				
+				stream = self.create_promise_stream(headers, promised_stream_id)
+				stream.reserved_remote!
+				
+				return stream, headers
+			end
+		end
+	end
+end

data/lib/protocol/http2/version.rb

@@ -0,0 +1,25 @@
+# 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.
+
+module Protocol
+	module HTTP2
+		VERSION = "0.1.0"
+	end
+end