protocol-http2 0.22.1 → 0.23.0

data/lib/protocol/http2/flow_controlled.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2019, by Yuta Iwama.
 
 require_relative "window_update_frame"
 
 module Protocol
 	module HTTP2
+		# Provides flow control functionality for HTTP/2 connections and streams.
+		# This module implements window-based flow control as defined in RFC 7540.
 		module FlowControlled
+			# Get the available window size for sending data.
+			# @returns [Integer] The number of bytes that can be sent.
 			def available_size
 				@remote_window.available
 			end
@@ -40,17 +44,22 @@ module Protocol
 				end
 			end
 			
+			# Update the local window after receiving data.
+			# @parameter frame [Frame] The frame that was received.
 			def update_local_window(frame)
 				consume_local_window(frame)
 				request_window_update
 			end
 			
+			# Consume local window space for a received frame.
+			# @parameter frame [Frame] The frame that consumed window space.
 			def consume_local_window(frame)
 				# For flow-control calculations, the 9-octet frame header is not counted.
 				amount = frame.length
 				@local_window.consume(amount)
 			end
 			
+			# Request a window update if the local window is limited.
 			def request_window_update
 				if @local_window.limited?
 					self.send_window_update(@local_window.wanted)
@@ -67,6 +76,9 @@ module Protocol
 				@local_window.expand(window_increment)
 			end
 			
+			# Process a received WINDOW_UPDATE frame.
+			# @parameter frame [WindowUpdateFrame] The window update frame to process.
+			# @raises [ProtocolError] If the window increment is invalid.
 			def receive_window_update(frame)
 				amount = frame.unpack
 				

data/lib/protocol/http2/frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2019, by Yuta Iwama.
 
 require_relative "error"
@@ -17,6 +17,9 @@ module Protocol
 		MINIMUM_ALLOWED_FRAME_SIZE = 0x4000
 		MAXIMUM_ALLOWED_FRAME_SIZE = 0xFFFFFF
 		
+		# Represents the base class for all HTTP/2 frames.
+		# This class provides common functionality for frame parsing, serialization,
+		# and manipulation according to RFC 7540.
 		class Frame
 			include Comparable
 			
@@ -43,14 +46,21 @@ module Protocol
 				@payload = payload
 			end
 			
+			# Check if the frame has a valid type identifier.
+			# @returns [Boolean] True if the frame type is valid.
 			def valid_type?
 				@type == self.class::TYPE
 			end
 			
+			# Compare frames based on their essential properties.
+			# @parameter other [Frame] The frame to compare with.
+			# @returns [Integer] -1, 0, or 1 for comparison result.
 			def <=> other
 				to_ary <=> other.to_ary
 			end
 			
+			# Convert frame to array representation for comparison.
+			# @returns [Array] Frame properties as an array.
 			def to_ary
 				[@length, @type, @flags, @stream_id, @payload]
 			end
@@ -73,10 +83,16 @@ module Protocol
 			attr_accessor :stream_id
 			attr_accessor :payload
 			
+			# Unpack the frame payload data.
+			# @returns [String] The frame payload.
 			def unpack
 				@payload
 			end
 			
+			# Pack payload data into the frame.
+			# @parameter payload [String] The payload data to pack.
+			# @parameter maximum_size [Integer | Nil] Optional maximum payload size.
+			# @raises [ProtocolError] If payload exceeds maximum size.
 			def pack(payload, maximum_size: nil)
 				@payload = payload
 				@length = payload.bytesize
@@ -86,14 +102,21 @@ module Protocol
 				end
 			end
 			
+			# Set specific flags on the frame.
+			# @parameter mask [Integer] The flag bits to set.
 			def set_flags(mask)
 				@flags |= mask
 			end
 			
+			# Clear specific flags on the frame.
+			# @parameter mask [Integer] The flag bits to clear.
 			def clear_flags(mask)
 				@flags &= ~mask
 			end
 			
+			# Check if specific flags are set on the frame.
+			# @parameter mask [Integer] The flag bits to check.
+			# @returns [Boolean] True if any of the flags are set.
 			def flag_set?(mask)
 				@flags & mask != 0
 			end
@@ -101,7 +124,7 @@ module Protocol
 			# Check if frame is a connection frame: SETTINGS, PING, GOAWAY, and any
 			# frame addressed to stream ID = 0.
 			#
-			# @return [Boolean]
+			# @return [Boolean] If this is a connection frame.
 			def connection?
 				@stream_id.zero?
 			end
@@ -145,6 +168,9 @@ module Protocol
 				return length, type, flags, stream_id
 			end
 			
+			# Read the frame header from a stream.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [EOFError] If the header cannot be read completely.
 			def read_header(stream)
 				if buffer = stream.read(9) and buffer.bytesize == 9
 					@length, @type, @flags, @stream_id = Frame.parse_header(buffer)
@@ -154,6 +180,9 @@ module Protocol
 				end
 			end
 			
+			# Read the frame payload from a stream.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [EOFError] If the payload cannot be read completely.
 			def read_payload(stream)
 				if payload = stream.read(@length) and payload.bytesize == @length
 					@payload = payload
@@ -162,6 +191,11 @@ module Protocol
 				end
 			end
 			
+			# Read the complete frame (header and payload) from a stream.
+			# @parameter stream [IO] The stream to read from.
+			# @parameter maximum_frame_size [Integer] The maximum allowed frame size.
+			# @raises [FrameSizeError] If the frame exceeds the maximum size.
+			# @returns [Frame] Self for method chaining.
 			def read(stream, maximum_frame_size = MAXIMUM_ALLOWED_FRAME_SIZE)
 				read_header(stream) unless @length
 				
@@ -172,14 +206,21 @@ module Protocol
 				read_payload(stream)
 			end
 			
+			# Write the frame header to a stream.
+			# @parameter stream [IO] The stream to write to.
 			def write_header(stream)
 				stream.write self.header
 			end
 			
+			# Write the frame payload to a stream.
+			# @parameter stream [IO] The stream to write to.
 			def write_payload(stream)
 				stream.write(@payload) if @payload
 			end
 			
+			# Write the complete frame (header and payload) to a stream.
+			# @parameter stream [IO] The stream to write to.
+			# @raises [ProtocolError] If frame validation fails.
 			def write(stream)
 				# Validate the payload size:
 				if @payload.nil?
@@ -196,10 +237,14 @@ module Protocol
 				self.write_payload(stream)
 			end
 			
+			# Apply the frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_frame(self)
 			end
 			
+			# Provide a readable representation of the frame for debugging.
+			# @returns [String] A formatted string representation of the frame.
 			def inspect
 				"\#<#{self.class} stream_id=#{@stream_id} flags=#{@flags} payload=#{self.unpack}>"
 			end

data/lib/protocol/http2/framer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "error"
 
@@ -42,28 +42,40 @@ module Protocol
 		# Default connection "fast-fail" preamble string as defined by the spec.
 		CONNECTION_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n".freeze
 		
+		# Handles frame serialization and deserialization for HTTP/2 connections.
+		# This class manages the reading and writing of HTTP/2 frames to/from a stream.
 		class Framer
+			# Initialize a new framer with a stream and frame definitions.
+			# @parameter stream [IO] The underlying stream for frame I/O.
+			# @parameter frames [Array] Frame type definitions to use.
 			def initialize(stream, frames = FRAMES)
 				@stream = stream
 				@frames = frames
 			end
 			
+			# Flush the underlying stream.
 			def flush
 				@stream.flush
 			end
 			
+			# Close the underlying stream.
 			def close
 				@stream.close
 			end
 			
+			# Check if the underlying stream is closed.
+			# @returns [Boolean] True if the stream is closed.
 			def closed?
 				@stream.closed?
 			end
 			
+			# Write the HTTP/2 connection preface to the stream.
 			def write_connection_preface
 				@stream.write(CONNECTION_PREFACE)
 			end
 			
+			# Read and validate the HTTP/2 connection preface from the stream.
+			# @raises [HandshakeError] If the preface is invalid.
 			def read_connection_preface
 				string = @stream.read(CONNECTION_PREFACE.bytesize)
 				
@@ -105,6 +117,9 @@ module Protocol
 				return frame
 			end
 			
+			# Read a frame header from the stream.
+			# @returns [Array] Parsed frame header components: length, type, flags, stream_id.
+			# @raises [EOFError] If the header cannot be read completely.
 			def read_header
 				if buffer = @stream.read(9)
 					if buffer.bytesize == 9

data/lib/protocol/http2/goaway_frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 
@@ -21,10 +21,14 @@ module Protocol
 			TYPE = 0x7
 			FORMAT = "NN"
 			
+			# Check if this frame applies to the connection level.
+			# @returns [Boolean] Always returns true for GOAWAY frames.
 			def connection?
 				true
 			end
 			
+			# Unpack the GOAWAY frame payload.
+			# @returns [Array] Last stream ID, error code, and debug data.
 			def unpack
 				data = super
 				
@@ -33,10 +37,16 @@ module Protocol
 				return last_stream_id, error_code, data.slice(8, data.bytesize-8)
 			end
 			
+			# Pack GOAWAY frame data into payload.
+			# @parameter last_stream_id [Integer] The last processed stream ID.
+			# @parameter error_code [Integer] The error code for connection termination.
+			# @parameter data [String] Additional debug data.
 			def pack(last_stream_id, error_code, data)
 				super [last_stream_id, error_code].pack(FORMAT) + data
 			end
 			
+			# Apply this GOAWAY frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_goaway(self)
 			end

data/lib/protocol/http2/headers_frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 require_relative "padded"
@@ -28,14 +28,20 @@ module Protocol
 			
 			TYPE = 0x1
 			
+			# Check if this frame contains priority information.
+			# @returns [Boolean] True if the PRIORITY flag is set.
 			def priority?
 				flag_set?(PRIORITY)
 			end
 			
+			# Check if this frame ends the stream.
+			# @returns [Boolean] True if the END_STREAM flag is set.
 			def end_stream?
 				flag_set?(END_STREAM)
 			end
 			
+			# Unpack the header block fragment from the frame.
+			# @returns [String] The unpacked header block data.
 			def unpack
 				data = super
 				
@@ -47,6 +53,10 @@ module Protocol
 				return data
 			end
 			
+			# Pack header block data into the frame.
+			# @parameter data [String] The header block data to pack.
+			# @parameter arguments [Array] Additional arguments.
+			# @parameter options [Hash] Options for packing.
 			def pack(data, *arguments, **options)
 				buffer = String.new.b
 				
@@ -55,10 +65,14 @@ module Protocol
 				super(buffer, *arguments, **options)
 			end
 			
+			# Apply this HEADERS frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_headers(self)
 			end
 			
+			# Get a string representation of the headers frame.
+			# @returns [String] Human-readable frame information.
 			def inspect
 				"\#<#{self.class} stream_id=#{@stream_id} flags=#{@flags} #{@length || 0}b>"
 			end

data/lib/protocol/http2/padded.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 
@@ -18,11 +18,19 @@ module Protocol
 		# |                           Padding (*)                       ...
 		# +---------------------------------------------------------------+
 		#
+		# Provides padding functionality for HTTP/2 frames.
+		# Padding can be used to obscure the actual size of frame payloads.
 		module Padded
+			# Check if the frame has padding enabled.
+			# @returns [Boolean] True if the PADDED flag is set.
 			def padded?
 				flag_set?(PADDED)
 			end
 			
+			# Pack data with optional padding into the frame.
+			# @parameter data [String] The data to pack.
+			# @parameter padding_size [Integer | Nil] Number of padding bytes to add.
+			# @parameter maximum_size [Integer | Nil] Maximum frame size limit.
 			def pack(data, padding_size: nil, maximum_size: nil)
 				if padding_size
 					set_flags(PADDED)
@@ -44,6 +52,9 @@ module Protocol
 				end
 			end
 			
+			# Unpack frame data, removing padding if present.
+			# @returns [String] The unpacked data without padding.
+			# @raises [ProtocolError] If padding length is invalid.
 			def unpack
 				if padded?
 					padding_size = @payload[0].ord

data/lib/protocol/http2/ping_frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 
@@ -9,15 +9,22 @@ module Protocol
 	module HTTP2
 		ACKNOWLEDGEMENT = 0x1
 		
+		# Provides acknowledgement functionality for frames that support it.
+		# This module handles setting and checking acknowledgement flags on frames.
 		module Acknowledgement
+			# Check if the frame is an acknowledgement.
+			# @returns [Boolean] True if the acknowledgement flag is set.
 			def acknowledgement?
 				flag_set?(ACKNOWLEDGEMENT)
 			end
 			
+			# Mark this frame as an acknowledgement.
 			def acknowledgement!
 				set_flags(ACKNOWLEDGEMENT)
 			end
 			
+			# Create an acknowledgement frame for this frame.
+			# @returns [Frame] A new frame marked as an acknowledgement.
 			def acknowledge
 				frame = self.class.new
 				
@@ -41,14 +48,20 @@ module Protocol
 			
 			include Acknowledgement
 			
+			# Check if this frame applies to the connection level.
+			# @returns [Boolean] Always returns true for PING frames.
 			def connection?
 				true
 			end
 			
+			# Apply this PING frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_ping(self)
 			end
 			
+			# Create an acknowledgement PING frame with the same payload.
+			# @returns [PingFrame] A new PING frame marked as an acknowledgement.
 			def acknowledge
 				frame = super
 				
@@ -57,6 +70,9 @@ module Protocol
 				return frame
 			end
 			
+			# Read and validate the PING frame payload.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [ProtocolError] If validation fails.
 			def read_payload(stream)
 				super
 				

data/lib/protocol/http2/priority_update_frame.rb

@@ -21,6 +21,8 @@ module Protocol
 			TYPE = 0x10
 			FORMAT = "N".freeze
 			
+			# Unpack the prioritized stream ID and priority field value.
+			# @returns [Array] An array containing the prioritized stream ID and priority field value.
 			def unpack
 				data = super
 				
@@ -29,10 +31,16 @@ module Protocol
 				return prioritized_stream_id, data.byteslice(4, data.bytesize - 4)
 			end
 			
+			# Pack the prioritized stream ID and priority field value into the frame.
+			# @parameter prioritized_stream_id [Integer] The stream ID to prioritize.
+			# @parameter data [String] The priority field value.
+			# @parameter options [Hash] Options for packing.
 			def pack(prioritized_stream_id, data, **options)
 				super([prioritized_stream_id].pack(FORMAT) + data, **options)
 			end
 			
+			# Apply this PRIORITY_UPDATE frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_priority_update(self)
 			end

data/lib/protocol/http2/push_promise_frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 require_relative "padded"
@@ -27,6 +27,8 @@ module Protocol
 			TYPE = 0x5
 			FORMAT = "N".freeze
 			
+			# Unpack the promised stream ID and header block fragment.
+			# @returns [Array] An array containing the promised stream ID and header block data.
 			def unpack
 				data = super
 				
@@ -35,10 +37,17 @@ module Protocol
 				return stream_id, data.byteslice(4, data.bytesize - 4)
 			end
 			
+			# Pack the promised stream ID and header block data into the frame.
+			# @parameter stream_id [Integer] The promised stream ID.
+			# @parameter data [String] The header block data.
+			# @parameter arguments [Array] Additional arguments.
+			# @parameter options [Hash] Options for packing.
 			def pack(stream_id, data, *arguments, **options)
 				super([stream_id].pack(FORMAT) + data, *arguments, **options)
 			end
 			
+			# Apply this PUSH_PROMISE frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_push_promise(self)
 			end

data/lib/protocol/http2/reset_stream_frame.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 
@@ -32,19 +32,28 @@ module Protocol
 			TYPE = 0x3
 			FORMAT = "N".freeze
 			
+			# Unpack the error code from the frame payload.
+			# @returns [Integer] The error code.
 			def unpack
 				@payload.unpack1(FORMAT)
 			end
 			
+			# Pack an error code into the frame payload.
+			# @parameter error_code [Integer] The error code to pack.
 			def pack(error_code = NO_ERROR)
 				@payload = [error_code].pack(FORMAT)
 				@length = @payload.bytesize
 			end
 			
+			# Apply this RST_STREAM frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_reset_stream(self)
 			end
 			
+			# Read and validate the RST_STREAM frame payload.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [FrameSizeError] If the frame length is invalid.
 			def read_payload(stream)
 				super
 				

data/lib/protocol/http2/server.rb

@@ -1,29 +1,50 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "connection"
 
 module Protocol
 	module HTTP2
+		# Represents an HTTP/2 server connection.
+		# Manages server-side protocol semantics including stream ID allocation,
+		# connection preface handling, and settings negotiation.
 		class Server < Connection
+			# Initialize a new HTTP/2 server connection.
+			# @parameter framer [Framer] The frame handler for reading/writing HTTP/2 frames.
 			def initialize(framer)
 				super(framer, 2)
 			end
 			
+			# Check if the given stream ID represents a locally-initiated stream.
+			# Server streams have even numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [Boolean] True if the stream ID is locally-initiated.
 			def local_stream_id?(id)
 				id.even?
 			end
 			
+			# Check if the given stream ID represents a remotely-initiated stream.
+			# Client streams have odd numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [Boolean] True if the stream ID is remotely-initiated.
 			def remote_stream_id?(id)
 				id.odd?
 			end
 			
+			# Check if the given stream ID is valid for remote initiation.
+			# Client-initiated streams must have odd numbered IDs.
+			# @parameter stream_id [Integer] The stream ID to validate.
+			# @returns [Boolean] True if the stream ID is valid for remote initiation.
 			def valid_remote_stream_id?(stream_id)
 				stream_id.odd?
 			end
 			
+			# Read the HTTP/2 connection preface from the client and send initial settings.
+			# This must be called once when the connection is first established.
+			# @parameter settings [Array] Optional settings to send during preface exchange.
+			# @raises [ProtocolError] If called when not in the new state or preface is invalid.
 			def read_connection_preface(settings = [])
 				if @state == :new
 					@framer.read_connection_preface
@@ -40,10 +61,15 @@ module Protocol
 				end
 			end
 			
+			# Servers cannot accept push promise streams from clients.
+			# @parameter stream_id [Integer] The stream ID (unused).
+			# @raises [ProtocolError] Always, as servers cannot accept push promises.
 			def accept_push_promise_stream(stream_id, &block)
 				raise ProtocolError, "Cannot accept push promises on server!"
 			end
 			
+			# Check if server push is enabled by the client.
+			# @returns [Boolean] True if push promises are enabled.
 			def enable_push?
 				@remote_settings.enable_push?
 			end