protocol-http2 0.22.1 → 0.23.0

data/lib/protocol/http2/settings_frame.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "ping_frame"
 
 module Protocol
 	module HTTP2
+		# HTTP/2 connection settings container and management.
 		class Settings
 			HEADER_TABLE_SIZE = 0x1
 			ENABLE_PUSH = 0x2
@@ -30,6 +31,7 @@ module Protocol
 				:no_rfc7540_priorities=,
 			]
 			
+			# Initialize settings with default values from HTTP/2 specification.
 			def initialize
 				# These limits are taken from the RFC:
 				# https://tools.ietf.org/html/rfc7540#section-6.5.2
@@ -49,6 +51,9 @@ module Protocol
 			# 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
 			
+			# Set the server push enable flag.
+			# @parameter value [Integer] Must be 0 (disabled) or 1 (enabled).
+			# @raises [ProtocolError] If the value is invalid.
 			def enable_push= value
 				if value == 0 or value == 1
 					@enable_push = value
@@ -57,6 +62,8 @@ module Protocol
 				end
 			end
 			
+			# Check if server push is enabled.
+			# @returns [Boolean] True if server push is enabled.
 			def enable_push?
 				@enable_push == 1
 			end
@@ -67,6 +74,9 @@ module Protocol
 			# Indicates the sender's initial window size (in octets) for stream-level flow control.
 			attr :initial_window_size
 			
+			# Set the initial window size for stream-level flow control.
+			# @parameter value [Integer] The window size in octets.
+			# @raises [ProtocolError] If the value exceeds the maximum allowed.
 			def initial_window_size= value
 				if value <= MAXIMUM_ALLOWED_WINDOW_SIZE
 					@initial_window_size = value
@@ -78,6 +88,9 @@ module Protocol
 			# Indicates the size of the largest frame payload that the sender is willing to receive, in octets.
 			attr :maximum_frame_size
 			
+			# Set the maximum frame size the sender is willing to receive.
+			# @parameter value [Integer] The maximum frame size in octets.
+			# @raises [ProtocolError] If the value is outside the allowed range.
 			def maximum_frame_size= value
 				if value > MAXIMUM_ALLOWED_FRAME_SIZE
 					raise ProtocolError, "Invalid value for maximum_frame_size: #{value} > #{MAXIMUM_ALLOWED_FRAME_SIZE}"
@@ -93,6 +106,9 @@ module Protocol
 			
 			attr :enable_connect_protocol
 			
+			# Set the CONNECT protocol enable flag.
+			# @parameter value [Integer] Must be 0 (disabled) or 1 (enabled).
+			# @raises [ProtocolError] If the value is invalid.
 			def enable_connect_protocol= value
 				if value == 0 or value == 1
 					@enable_connect_protocol = value
@@ -101,12 +117,17 @@ module Protocol
 				end
 			end
 			
+			# Check if CONNECT protocol is enabled.
+			# @returns [Boolean] True if CONNECT protocol is enabled.
 			def enable_connect_protocol?
 				@enable_connect_protocol == 1
 			end
 			
 			attr :no_rfc7540_priorities
 			
+			# Set the RFC 7540 priorities disable flag.
+			# @parameter value [Integer] Must be 0 (enabled) or 1 (disabled).
+			# @raises [ProtocolError] If the value is invalid.
 			def no_rfc7540_priorities= value
 				if value == 0 or value == 1
 					@no_rfc7540_priorities = value
@@ -115,10 +136,14 @@ module Protocol
 				end
 			end
 			
+			# Check if RFC 7540 priorities are disabled.
+			# @returns [Boolean] True if RFC 7540 priorities are disabled.
 			def no_rfc7540_priorities?
 				@no_rfc7540_priorities == 1
 			end
 			
+			# Update settings with a hash of changes.
+			# @parameter changes [Hash] Hash of setting keys and values to update.
 			def update(changes)
 				changes.each do |key, value|
 					if name = ASSIGN[key]
@@ -128,7 +153,10 @@ module Protocol
 			end
 		end
 		
+		# Manages pending settings changes that haven't been acknowledged yet.
 		class PendingSettings
+			# Initialize with current settings.
+			# @parameter current [Settings] The current settings object.
 			def initialize(current = Settings.new)
 				@current = current
 				@pending = current.dup
@@ -139,11 +167,14 @@ module Protocol
 			attr :current
 			attr :pending
 			
+			# Append changes to the pending queue.
+			# @parameter changes [Hash] Hash of setting changes to queue.
 			def append(changes)
 				@queue << changes
 				@pending.update(changes)
 			end
 			
+			# Acknowledge the next set of pending changes.
 			def acknowledge
 				if changes = @queue.shift
 					@current.update(changes)
@@ -154,30 +185,44 @@ module Protocol
 				end
 			end
 			
+			# Get the current header table size setting.
+			# @returns [Integer] The header table size in octets.
 			def header_table_size
 				@current.header_table_size
 			end
 			
+			# Get the current enable push setting.
+			# @returns [Integer] 1 if push is enabled, 0 if disabled.
 			def enable_push
 				@current.enable_push
 			end
 			
+			# Get the current maximum concurrent streams setting.
+			# @returns [Integer] The maximum number of concurrent streams.
 			def maximum_concurrent_streams
 				@current.maximum_concurrent_streams
 			end
 			
+			# Get the current initial window size setting.
+			# @returns [Integer] The initial window size in octets.
 			def initial_window_size
 				@current.initial_window_size
 			end
 			
+			# Get the current maximum frame size setting.
+			# @returns [Integer] The maximum frame size in octets.
 			def maximum_frame_size
 				@current.maximum_frame_size
 			end
 			
+			# Get the current maximum header list size setting.
+			# @returns [Integer] The maximum header list size in octets.
 			def maximum_header_list_size
 				@current.maximum_header_list_size
 			end
 			
+			# Get the current CONNECT protocol enable setting.
+			# @returns [Integer] 1 if CONNECT protocol is enabled, 0 if disabled.
 			def enable_connect_protocol
 				@current.enable_connect_protocol
 			end
@@ -197,10 +242,14 @@ module Protocol
 			
 			include Acknowledgement
 			
+			# Check if this frame applies to the connection level.
+			# @returns [Boolean] Always returns true for SETTINGS frames.
 			def connection?
 				true
 			end
 			
+			# Unpack settings parameters from the frame payload.
+			# @returns [Array] Array of [key, value] pairs representing settings.
 			def unpack
 				if buffer = super
 					# TODO String#each_slice, or #each_unpack would be nice.
@@ -210,14 +259,22 @@ module Protocol
 				end
 			end
 			
+			# Pack settings parameters into the frame payload.
+			# @parameter settings [Array] Array of [key, value] pairs to pack.
 			def pack(settings = [])
 				super(settings.map{|s| s.pack(FORMAT)}.join)
 			end
 			
+			# Apply this SETTINGS frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_settings(self)
 			end
 			
+			# Read and validate the SETTINGS frame payload.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [ProtocolError] If the frame is invalid.
+			# @raises [FrameSizeError] If the frame length is invalid.
 			def read_payload(stream)
 				super
 				

data/lib/protocol/http2/stream.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 "connection"
 
@@ -60,6 +60,10 @@ module Protocol
 		class Stream
 			include FlowControlled
 			
+			# Create a new stream and add it to the connection.
+			# @parameter connection [Connection] The connection this stream belongs to.
+			# @parameter id [Integer] The stream identifier.
+			# @returns [Stream] The newly created stream.
 			def self.create(connection, id)
 				stream = self.new(connection, id)
 				
@@ -68,6 +72,10 @@ module Protocol
 				return stream
 			end
 			
+			# Initialize a new stream.
+			# @parameter connection [Connection] The connection this stream belongs to.
+			# @parameter id [Integer] The stream identifier.
+			# @parameter state [Symbol] The initial stream state.
 			def initialize(connection, id, state = :idle)
 				@connection = connection
 				@id = id
@@ -95,18 +103,26 @@ module Protocol
 			# @attribute [Protocol::HTTP::Header::Priority | Nil] the priority of the stream.
 			attr_accessor :priority
 			
+			# Get the maximum frame size for this stream.
+			# @returns [Integer] The maximum frame size from connection settings.
 			def maximum_frame_size
 				@connection.available_frame_size
 			end
 			
+			# Write a frame to the connection for this stream.
+			# @parameter frame [Frame] The frame to write.
 			def write_frame(frame)
 				@connection.write_frame(frame)
 			end
 			
+			# Check if the stream is active (not idle or closed).
+			# @returns [Boolean] True if the stream is active.
 			def active?
 				@state != :closed && @state != :idle
 			end
 			
+			# Check if the stream is closed.
+			# @returns [Boolean] True if the stream is in closed state.
 			def closed?
 				@state == :closed
 			end
@@ -170,6 +186,8 @@ module Protocol
 				end
 			end
 			
+			# Consume from the remote window for both stream and connection.
+			# @parameter frame [Frame] The frame that consumes window space.
 			def consume_remote_window(frame)
 				super
 				
@@ -187,6 +205,9 @@ module Protocol
 				return frame
 			end
 			
+			# Send data over this stream.
+			# @parameter arguments [Array] Arguments passed to write_data.
+			# @parameter options [Hash] Options passed to write_data.
 			def send_data(*arguments, **options)
 				if @state == :open
 					frame = write_data(*arguments, **options)
@@ -205,6 +226,9 @@ module Protocol
 				end
 			end
 			
+			# Open the stream by transitioning from idle to open state.
+			# @returns [Stream] Returns self for chaining.
+			# @raises [ProtocolError] If the stream cannot be opened from current state.
 			def open!
 				if @state == :idle
 					@state = :open
@@ -234,6 +258,8 @@ module Protocol
 				return self
 			end
 			
+			# Send a RST_STREAM frame to reset this stream.
+			# @parameter error_code [Integer] The error code to send.
 			def send_reset_stream(error_code = 0)
 				if @state != :idle and @state != :closed
 					frame = ResetStreamFrame.new(@id)
@@ -247,6 +273,9 @@ module Protocol
 				end
 			end
 			
+			# Process headers frame and decode the header block.
+			# @parameter frame [HeadersFrame] The headers frame to process.
+			# @returns [Array] The decoded headers.
 			def process_headers(frame)
 				# Receiving request headers:
 				data = frame.unpack
@@ -258,6 +287,8 @@ module Protocol
 				# Console.warn(self) {"Received headers in state: #{@state}!"}
 			end
 			
+			# Receive and process a headers frame on this stream.
+			# @parameter frame [HeadersFrame] The headers frame to receive.
 			def receive_headers(frame)
 				if @state == :idle
 					if frame.end_stream?
@@ -295,6 +326,8 @@ module Protocol
 				frame.unpack
 			end
 			
+			# Ignore data frame when in an invalid state.
+			# @parameter frame [DataFrame] The data frame to ignore.
 			def ignore_data(frame)
 				# Console.warn(self) {"Received headers in state: #{@state}!"}
 			end
@@ -325,6 +358,10 @@ module Protocol
 				end
 			end
 			
+			# Receive and process a RST_STREAM frame on this stream.
+			# @parameter frame [ResetStreamFrame] The reset stream frame to receive.
+			# @returns [Integer] The error code from the reset frame.
+			# @raises [ProtocolError] If reset is received on an idle stream.
 			def receive_reset_stream(frame)
 				if @state == :idle
 					# If a RST_STREAM frame identifying an idle stream is received, the recipient MUST treat this as a connection error (Section 5.4.1) of type PROTOCOL_ERROR.
@@ -355,6 +392,9 @@ module Protocol
 				return frame
 			end
 			
+			# Transition stream to reserved local state.
+			# @returns [Stream] Returns self for chaining.
+			# @raises [ProtocolError] If the stream cannot be reserved from current state.
 			def reserved_local!
 				if @state == :idle
 					@state = :reserved_local
@@ -365,6 +405,9 @@ module Protocol
 				return self
 			end
 			
+			# Transition stream to reserved remote state.
+			# @returns [Stream] Returns self for chaining.
+			# @raises [ProtocolError] If the stream cannot be reserved from current state.
 			def reserved_remote!
 				if @state == :idle
 					@state = :reserved_remote
@@ -402,6 +445,8 @@ module Protocol
 				@connection.accept_push_promise_stream(stream_id)
 			end
 			
+			# Receive and process a PUSH_PROMISE frame on this stream.
+			# @parameter frame [PushPromiseFrame] The push promise frame to receive.
 			def receive_push_promise(frame)
 				promised_stream_id, data = frame.unpack
 				headers = @connection.decode_headers(data)
@@ -412,6 +457,8 @@ module Protocol
 				return stream, headers
 			end
 			
+			# Get a string representation of the stream.
+			# @returns [String] Human-readable stream information.
 			def inspect
 				"\#<#{self.class} id=#{@id} state=#{@state}>"
 			end

data/lib/protocol/http2/version.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
+# @namespace
 module Protocol
+	# @namespace
 	module HTTP2
-		VERSION = "0.22.1"
+		VERSION = "0.23.0"
 	end
 end

data/lib/protocol/http2/window.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 module Protocol
 	module HTTP2
+		# Flow control window for managing HTTP/2 data flow.
 		class Window
 			# When an HTTP/2 connection is first established, new streams are created with an initial flow-control window size of 65,535 octets. The connection flow-control window is also 65,535 octets.
 			DEFAULT_CAPACITY = 0xFFFF
 			
+			# Initialize a new flow control window.
 			# @parameter capacity [Integer] The initial window size, typically from the settings.
 			def initialize(capacity = DEFAULT_CAPACITY)
 				# This is the main field required:
@@ -40,6 +42,8 @@ module Protocol
 				@capacity = value
 			end
 			
+			# Consume a specific amount from the available window.
+			# @parameter amount [Integer] The amount to consume from the window.
 			def consume(amount)
 				@available -= amount
 				@used += amount
@@ -47,10 +51,15 @@ module Protocol
 			
 			attr :available
 			
+			# Check if there is available window capacity.
+			# @returns [Boolean] True if there is available capacity.
 			def available?
 				@available > 0
 			end
 			
+			# Expand the window by a specific amount.
+			# @parameter amount [Integer] The amount to expand the window by.
+			# @raises [FlowControlError] If expansion would cause overflow.
 			def expand(amount)
 				available = @available + amount
 				
@@ -63,14 +72,20 @@ module Protocol
 				@used -= amount
 			end
 			
+			# Get the amount of window that should be reclaimed.
+			# @returns [Integer] The amount of used window space.
 			def wanted
 				@used
 			end
 			
+			# Check if the window is limited and needs updating.
+			# @returns [Boolean] True if available capacity is less than half of total capacity.
 			def limited?
 				@available < (@capacity / 2)
 			end
 			
+			# Get a string representation of the window.
+			# @returns [String] Human-readable window information.
 			def inspect
 				"\#<#{self.class} available=#{@available} used=#{@used} capacity=#{@capacity}#{limited? ? " limited" : nil}>"
 			end
@@ -80,6 +95,9 @@ module Protocol
 		
 		# This is a window which efficiently maintains a desired capacity.
 		class LocalWindow < Window
+			# Initialize a local window with optional desired capacity.
+			# @parameter capacity [Integer] The initial window capacity.
+			# @parameter desired [Integer] The desired window capacity.
 			def initialize(capacity = DEFAULT_CAPACITY, desired: nil)
 				super(capacity)
 				
@@ -91,6 +109,8 @@ module Protocol
 			# The desired capacity of the window.
 			attr_accessor :desired
 			
+			# Get the amount of window that should be reclaimed, considering desired capacity.
+			# @returns [Integer] The amount needed to reach desired capacity or used space.
 			def wanted
 				if @desired
 					# We must send an update which allows at least @desired bytes to be sent.
@@ -100,6 +120,8 @@ module Protocol
 				end
 			end
 			
+			# Check if the window is limited, considering desired capacity.
+			# @returns [Boolean] True if window needs updating based on desired capacity.
 			def limited?
 				if @desired
 					# Do not send window updates until we are less than half the desired capacity:
@@ -109,6 +131,8 @@ module Protocol
 				end
 			end
 			
+			# Get a string representation of the local window.
+			# @returns [String] Human-readable local window information.
 			def inspect
 				"\#<#{self.class} available=#{@available} used=#{@used} capacity=#{@capacity} desired=#{@desired} #{limited? ? "limited" : nil}>"
 			end

data/lib/protocol/http2/window_update_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 "window"
@@ -18,14 +18,21 @@ module Protocol
 			TYPE = 0x8
 			FORMAT = "N"
 			
+			# Pack a window size increment into the frame.
+			# @parameter window_size_increment [Integer] The window size increment value.
 			def pack(window_size_increment)
 				super [window_size_increment].pack(FORMAT)
 			end
 			
+			# Unpack the window size increment from the frame payload.
+			# @returns [Integer] The window size increment value.
 			def unpack
 				super.unpack1(FORMAT)
 			end
 			
+			# Read and validate the WINDOW_UPDATE frame payload.
+			# @parameter stream [IO] The stream to read from.
+			# @raises [FrameSizeError] If the frame length is invalid.
 			def read_payload(stream)
 				super
 				
@@ -34,6 +41,8 @@ module Protocol
 				end
 			end
 			
+			# Apply this WINDOW_UPDATE frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_window_update(self)
 			end

data/readme.md

@@ -10,6 +10,18 @@ Please see the [project documentation](https://socketry.github.io/protocol-http2
 
   - [Getting Started](https://socketry.github.io/protocol-http2/guides/getting-started/index) - This guide explains how to use the `protocol-http2` gem to implement a basic HTTP/2 client.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-http2/releases/index) for all releases.
+
+### v0.23.0
+
+  - Introduce a limit to the number of CONTINUATION frames that can be read to prevent resource exhaustion. The default limit is 8 continuation frames, which means a total of 9 frames (1 initial + 8 continuation). This limit can be adjusted by passing a different value to the `limit` parameter in the `Continued.read` method. Setting the limit to 0 will only read the initial frame without any continuation frames. In order to change the default, you can redefine the `LIMIT` constant in the `Protocol::HTTP2::Continued` module, OR you can pass a different frame class to the framer.
+
+### v0.22.0
+
+  - [Added Priority Update Frame and Stream Priority](https://socketry.github.io/protocol-http2/releases/index#added-priority-update-frame-and-stream-priority)
+
 ## See Also
 
   - [Async::HTTP](https://github.com/socketry/async-http) - A high-level HTTP client and server implementation.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.23.0
+
+  - Introduce a limit to the number of CONTINUATION frames that can be read to prevent resource exhaustion. The default limit is 8 continuation frames, which means a total of 9 frames (1 initial + 8 continuation). This limit can be adjusted by passing a different value to the `limit` parameter in the `Continued.read` method. Setting the limit to 0 will only read the initial frame without any continuation frames. In order to change the default, you can redefine the `LIMIT` constant in the `Protocol::HTTP2::Continued` module, OR you can pass a different frame class to the framer.
+
 ## v0.22.0
 
 ### Added Priority Update Frame and Stream Priority

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http2
 version: !ruby/object:Gem::Version
-  version: 0.22.1
+  version: 0.23.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-hpack
@@ -74,6 +74,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/protocol/http2.rb
 - lib/protocol/http2/client.rb
 - lib/protocol/http2/connection.rb
@@ -114,14 +116,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A low level implementation of the HTTP/2 protocol.
 test_files: []