protocol-http2 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3ec4ba460a65fcf1aa11e9c3ce4d0f46fde1cb0e7fa9cc33667b9142eb3dc4
-  data.tar.gz: 0afd95c0651daf938a1b6e472376d38274dc7df70fdd38e9f28cfe6c657bc81f
+  metadata.gz: d4df424d3c1c97120be6031179d3febd9b6bcbbaeb163b24d53b03f05ae28696
+  data.tar.gz: baf0e59d7998a934d35eb1d33fa6205ccbae7bb6c5d352721b1d5d1ba0880131
 SHA512:
-  metadata.gz: 205b7683de9faee706dead27493c76b247c0d06c489778f670e4c49f0ecde263ad8b3b7ac1f86312681f83aee8bfaf4f82390f5d43c6a2d79dabdbe3f7d06b6a
-  data.tar.gz: c72cfe3041d0c4edc6e0510a8dc04f88dd547ebff1e96b9322f7ac35a64850fe516677a7e3df8b26258d7f089f10a2a4504211da8871678920ef65aa32b8a76b
+  metadata.gz: 4c7f24cd932068ecdcdf604bd9a9e3757c0fe40167844dfd351340f088507b6975a18288991c34342c15ad4217bf111a6e4dfa620c68c1bb7c83c149f0a5d21d
+  data.tar.gz: 404eff6b4e7a395cdcd44fd366564dbd67edc292857685d6294144b66892eda4dbdc60518cd0e2f58e034d001b45c0aeeffb389fccf49ad54464b97332bcc398

data/context/getting-started.md

@@ -0,0 +1,82 @@
+# Getting Started
+
+This guide explains how to use the `protocol-http2` gem to implement a basic HTTP/2 client.
+
+## Installation
+
+Add the gem to your project:
+
+``` bash
+$ bundle add protocol-http2
+```
+
+## Usage
+
+This gem provides a low-level implementation of the HTTP/2 protocol. It is designed to be used in conjunction with other libraries to provide a complete HTTP/2 client or server. However, it is straight forward to give examples of how to use the library directly.
+
+### Client
+
+Here is a basic HTTP/2 client:
+
+``` ruby
+require 'async'
+require 'async/io/stream'
+require 'async/http/endpoint'
+require 'protocol/http2/client'
+
+Async do
+	endpoint = Async::HTTP::Endpoint.parse("https://www.google.com/search?q=kittens")
+	
+	peer = endpoint.connect
+	
+	puts "Connected to #{peer.inspect}"
+	
+	# IO Buffering:
+	stream = Async::IO::Stream.new(peer)
+	
+	framer = Protocol::HTTP2::Framer.new(stream)
+	client = Protocol::HTTP2::Client.new(framer)
+	
+	puts "Sending connection preface..."
+	client.send_connection_preface
+	
+	puts "Creating stream..."
+	stream = client.create_stream
+	
+	headers = [
+		[":scheme", endpoint.scheme],
+		[":method", "GET"],
+		[":authority", "www.google.com"],
+		[":path", endpoint.path],
+		["accept", "*/*"],
+	]
+	
+	puts "Sending request on stream id=#{stream.id} state=#{stream.state}..."
+	stream.send_headers(headers, Protocol::HTTP2::END_STREAM)
+	
+	puts "Waiting for response..."
+	$count = 0
+	
+	def stream.process_headers(frame)
+		headers = super
+		puts "Got response headers: #{headers} (#{frame.end_stream?})"
+	end
+	
+	def stream.receive_data(frame)
+		data = super
+		
+		$count += data.scan(/kittens/).count
+		
+		puts "Got response data: #{data.bytesize}"
+	end
+	
+	until stream.closed?
+		frame = client.read_frame
+	end
+	
+	puts "Got #{$count} kittens!"
+	
+	puts "Closing client..."
+	client.close
+end
+```

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A low level implementation of the HTTP/2 protocol.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-http2/
+  source_code_uri: https://github.com/socketry/protocol-http2.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use the `protocol-http2` gem to implement
+    a basic HTTP/2 client.

data/lib/protocol/http2/client.rb

@@ -1,29 +1,51 @@
 # 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 client connection.
+		# Manages client-side protocol semantics including stream ID allocation,
+		# connection preface handling, and push promise processing.
 		class Client < Connection
+			# Initialize a new HTTP/2 client connection.
+			# @parameter framer [Framer] The frame handler for reading/writing HTTP/2 frames.
 			def initialize(framer)
 				super(framer, 1)
 			end
 			
+			# Check if the given stream ID represents a locally-initiated stream.
+			# Client streams have odd numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [bool] True if the stream ID is locally-initiated.
 			def local_stream_id?(id)
 				id.odd?
 			end
 			
+			# Check if the given stream ID represents a remotely-initiated stream.
+			# Server streams have even numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [bool] True if the stream ID is remotely-initiated.
 			def remote_stream_id?(id)
 				id.even?
 			end
 			
+			# Check if the given stream ID is valid for remote initiation.
+			# Server-initiated streams must have even numbered IDs.
+			# @parameter stream_id [Integer] The stream ID to validate.
+			# @returns [bool] True if the stream ID is valid for remote initiation.
 			def valid_remote_stream_id?(stream_id)
 				stream_id.even?
 			end
 			
+			# Send the HTTP/2 connection preface and initial settings.
+			# This must be called once when the connection is first established.
+			# @parameter settings [Array] Optional settings to send with the connection preface.
+			# @raises [ProtocolError] If called when not in the new state.
+			# @yields Allows custom processing during preface exchange.
 			def send_connection_preface(settings = [])
 				if @state == :new
 					@framer.write_connection_preface
@@ -42,10 +64,15 @@ module Protocol
 				end
 			end
 			
+			# Clients cannot create push promise streams.
+			# @raises [ProtocolError] Always, as clients cannot initiate push promises.
 			def create_push_promise_stream
 				raise ProtocolError, "Cannot create push promises from client!"
 			end
 			
+			# Process a push promise frame received from the server.
+			# @parameter frame [PushPromiseFrame] The push promise frame to process.
+			# @returns [Array(Stream, Hash) | Nil] The promised stream and request headers, or nil if no associated stream.
 			def receive_push_promise(frame)
 				if frame.stream_id == 0
 					raise ProtocolError, "Cannot receive headers for stream 0!"

data/lib/protocol/http2/connection.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, 2023, by Marco Concetto Rudilosso.
 
 require_relative "framer"
@@ -12,9 +12,14 @@ require "protocol/http/header/priority"
 
 module Protocol
 	module HTTP2
+		# This is the core connection class that handles HTTP/2 protocol semantics including
+		# stream management, settings negotiation, and frame processing.
 		class Connection
 			include FlowControlled
 			
+			# Initialize a new HTTP/2 connection.
+			# @parameter framer [Framer] The frame handler for reading/writing HTTP/2 frames.
+			# @parameter local_stream_id [Integer] The starting stream ID for locally-initiated streams.
 			def initialize(framer, local_stream_id)
 				super()
 				
@@ -41,10 +46,15 @@ module Protocol
 				@remote_window = Window.new
 			end
 			
+			# The connection stream ID (always 0 for connection-level operations).
+			# @returns [Integer] Always returns 0 for the connection itself.
 			def id
 				0
 			end
 			
+			# Access streams by ID, with 0 returning the connection itself.
+			# @parameter id [Integer] The stream ID to look up.
+			# @returns [Connection | Stream | Nil] The connection (if id=0), stream, or nil.
 			def [] id
 				if id.zero?
 					self
@@ -89,6 +99,9 @@ module Protocol
 				@state == :closed || @framer.nil?
 			end
 			
+			# Remove a stream from the active streams collection.
+			# @parameter id [Integer] The stream ID to remove.
+			# @returns [Stream | Nil] The removed stream, or nil if not found.
 			def delete(id)
 				@streams.delete(id)
 			end
@@ -106,10 +119,17 @@ module Protocol
 				end
 			end
 			
+			# Encode headers using HPACK compression.
+			# @parameter headers [Array] The headers to encode.
+			# @parameter buffer [String] Optional buffer for encoding output.
+			# @returns [String] The encoded header block.
 			def encode_headers(headers, buffer = String.new.b)
 				HPACK::Compressor.new(buffer, @encoder, table_size_limit: @remote_settings.header_table_size).encode(headers)
 			end
 			
+			# Decode headers using HPACK decompression.
+			# @parameter data [String] The encoded header block data.
+			# @returns [Array] The decoded headers.
 			def decode_headers(data)
 				HPACK::Decompressor.new(data, @decoder, table_size_limit: @local_settings.header_table_size).decode
 			end
@@ -141,6 +161,9 @@ module Protocol
 				end
 			end
 			
+			# Execute a block within a synchronized context.
+			# This method provides a synchronization primitive for thread safety.
+			# @yields The block to execute within the synchronized context.
 			def synchronize
 				yield
 			end
@@ -171,6 +194,8 @@ module Protocol
 				raise
 			end
 			
+			# Send updated settings to the remote peer.
+			# @parameter changes [Hash] The settings changes to send.
 			def send_settings(changes)
 				@local_settings.append(changes)
 				
@@ -197,6 +222,9 @@ module Protocol
 				self.close!
 			end
 			
+			# Process a GOAWAY frame from the remote peer.
+			# @parameter frame [GoawayFrame] The GOAWAY frame to process.
+			# @raises [GoawayError] If the frame indicates a connection error.
 			def receive_goaway(frame)
 				# We capture the last stream that was processed.
 				@remote_stream_id, error_code, message = frame.unpack
@@ -209,6 +237,8 @@ module Protocol
 				end
 			end
 			
+			# Write a single frame to the connection.
+			# @parameter frame [Frame] The frame to write.
 			def write_frame(frame)
 				synchronize do
 					@framer.write_frame(frame)
@@ -217,6 +247,10 @@ module Protocol
 				@framer.flush
 			end
 			
+			# Write multiple frames within a synchronized block.
+			# @yields {|framer| ...} The framer for writing multiple frames.
+			#   @parameter framer [Framer] The framer instance.
+			# @raises [EOFError] If the connection is closed.
 			def write_frames
 				if @framer
 					synchronize do
@@ -229,6 +263,8 @@ module Protocol
 				end
 			end
 			
+			# Update local settings and adjust stream window capacities.
+			# @parameter changes [Hash] The settings changes to apply locally.
 			def update_local_settings(changes)
 				capacity = @local_settings.initial_window_size
 				
@@ -239,6 +275,8 @@ module Protocol
 				@local_window.desired = capacity
 			end
 			
+			# Update remote settings and adjust stream window capacities.
+			# @parameter changes [Hash] The settings changes to apply to remote peer.
 			def update_remote_settings(changes)
 				capacity = @remote_settings.initial_window_size
 				
@@ -273,12 +311,17 @@ module Protocol
 				end
 			end
 			
+			# Transition the connection to the open state.
+			# @returns [Connection] Self for method chaining.
 			def open!
 				@state = :open
 				
 				return self
 			end
 			
+			# Receive and process a SETTINGS frame from the remote peer.
+			# @parameter frame [SettingsFrame] The settings frame to process.
+			# @raises [ProtocolError] If the connection is in an invalid state.
 			def receive_settings(frame)
 				if @state == :new
 					# We transition to :open when we receive acknowledgement of first settings frame:
@@ -290,6 +333,8 @@ module Protocol
 				end
 			end
 			
+			# Send a PING frame to the remote peer.
+			# @parameter data [String] The 8-byte ping payload data.
 			def send_ping(data)
 				if @state != :closed
 					frame = PingFrame.new
@@ -301,6 +346,9 @@ module Protocol
 				end
 			end
 			
+			# Process a PING frame from the remote peer.
+			# @parameter frame [PingFrame] The ping frame to process.
+			# @raises [ProtocolError] If ping is received in invalid state.
 			def receive_ping(frame)
 				if @state != :closed
 					# This is handled in `read_payload`:
@@ -318,6 +366,9 @@ module Protocol
 				end
 			end
 			
+			# Process a DATA frame from the remote peer.
+			# @parameter frame [DataFrame] The data frame to process.
+			# @raises [ProtocolError] If data is received for invalid stream.
 			def receive_data(frame)
 				update_local_window(frame)
 				
@@ -330,6 +381,10 @@ module Protocol
 				end
 			end
 			
+			# Check if the given stream ID is valid for remote initiation.
+			# This method should be overridden by client/server implementations.
+			# @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)
 				false
 			end
@@ -366,6 +421,10 @@ module Protocol
 				end
 			end
 			
+			# Create a push promise stream.
+			# This method should be overridden by client/server implementations.
+			# @yields {|stream| ...} Optional block to configure the created stream.
+			# @returns [Stream] The created push promise stream.
 			def create_push_promise_stream(&block)
 				create_stream(&block)
 			end
@@ -397,10 +456,16 @@ module Protocol
 				end
 			end
 			
+			# Receive and process a PUSH_PROMISE frame.
+			# @parameter frame [PushPromiseFrame] The push promise frame.
+			# @raises [ProtocolError] Always raises as push promises are not supported.
 			def receive_push_promise(frame)
 				raise ProtocolError, "Unable to receive push promise!"
 			end
 			
+			# Receive and process a PRIORITY_UPDATE frame.
+			# @parameter frame [PriorityUpdateFrame] The priority update frame.
+			# @raises [ProtocolError] If the stream ID is invalid.
 			def receive_priority_update(frame)
 				if frame.stream_id != 0
 					raise ProtocolError, "Invalid stream id: #{frame.stream_id}"
@@ -414,14 +479,25 @@ module Protocol
 				end
 			end
 			
+			# Check if the given stream ID represents a client-initiated stream.
+			# Client streams always have odd numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [Boolean] True if the stream ID is client-initiated.
 			def client_stream_id?(id)
 				id.odd?
 			end
 			
+			# Check if the given stream ID represents a server-initiated stream.
+			# Server streams always have even numbered IDs.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [Boolean] True if the stream ID is server-initiated.
 			def server_stream_id?(id)
 				id.even?
 			end
 			
+			# Check if the given stream ID represents an idle stream.
+			# @parameter id [Integer] The stream ID to check.
+			# @returns [Boolean] True if the stream ID is idle (not yet used).
 			def idle_stream_id?(id)
 				if id.even?
 					# Server-initiated streams are even.
@@ -450,6 +526,9 @@ module Protocol
 				end
 			end
 			
+			# Receive and process a RST_STREAM frame.
+			# @parameter frame [ResetStreamFrame] The reset stream frame.
+			# @raises [ProtocolError] If the frame is invalid for connection context.
 			def receive_reset_stream(frame)
 				if frame.connection?
 					raise ProtocolError, "Cannot reset connection!"
@@ -475,6 +554,8 @@ module Protocol
 				end
 			end
 			
+			# Receive and process a WINDOW_UPDATE frame.
+			# @parameter frame [WindowUpdateFrame] The window update frame.
 			def receive_window_update(frame)
 				if frame.connection?
 					super
@@ -494,10 +575,15 @@ module Protocol
 				end
 			end
 			
+			# Receive and process a CONTINUATION frame.
+			# @parameter frame [ContinuationFrame] The continuation frame.
+			# @raises [ProtocolError] Always raises as unexpected continuation frames are not supported.
 			def receive_continuation(frame)
 				raise ProtocolError, "Received unexpected continuation: #{frame.class}"
 			end
 			
+			# Receive and process a generic frame (default handler).
+			# @parameter frame [Frame] The frame to receive.
 			def receive_frame(frame)
 				# ignore.
 			end

data/lib/protocol/http2/continuation_frame.rb

@@ -1,31 +1,52 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "frame"
 
 module Protocol
 	module HTTP2
+		# Module for frames that can be continued with CONTINUATION frames.
 		module Continued
+			# @constant [Integer] The maximum number of continuation frames to read to prevent resource exhaustion.
+			LIMIT = 8
+			
+			# Initialize a continuable frame.
+			# @parameter arguments [Array] Arguments passed to parent constructor.
 			def initialize(*)
 				super
 				
 				@continuation = nil
 			end
 			
+			# Check if this frame has continuation frames.
+			# @returns [Boolean] True if there are continuation frames.
 			def continued?
 				!!@continuation
 			end
 			
+			# Check if this is the last header block fragment.
+			# @returns [Boolean] True if the END_HEADERS flag is set.
 			def end_headers?
 				flag_set?(END_HEADERS)
 			end
 			
-			def read(stream, maximum_frame_size)
-				super
+			# Read the frame and any continuation frames from the stream.
+			#
+			# There is an upper limit to the number of continuation frames that can be read to prevent resource exhaustion. If the limit is 0, only one frame will be read (the initial frame). Otherwise, the limit decrements with each continuation frame read.
+			#
+			# @parameter stream [IO] The stream to read from.
+			# @parameter maximum_frame_size [Integer] Maximum allowed frame size.
+			# @parameter limit [Integer] The maximum number of continuation frames to read.
+			def read(stream, maximum_frame_size, limit = LIMIT)
+				super(stream, maximum_frame_size)
 				
 				unless end_headers?
+					if limit.zero?
+						raise ProtocolError, "Too many continuation frames!"
+					end
+					
 					continuation = ContinuationFrame.new
 					continuation.read_header(stream)
 					
@@ -38,12 +59,14 @@ module Protocol
 						raise ProtocolError, "Invalid stream id: #{continuation.stream_id} for continuation of stream id: #{@stream_id}!"
 					end
 					
-					continuation.read(stream, maximum_frame_size)
+					continuation.read(stream, maximum_frame_size, limit - 1)
 					
 					@continuation = continuation
 				end
 			end
 			
+			# Write the frame and any continuation frames to the stream.
+			# @parameter stream [IO] The stream to write to.
 			def write(stream)
 				super
 				
@@ -54,6 +77,9 @@ module Protocol
 			
 			attr_accessor :continuation
 			
+			# Pack data into this frame, creating continuation frames if needed.
+			# @parameter data [String] The data to pack.
+			# @parameter options [Hash] Options including maximum_size.
 			def pack(data, **options)
 				maximum_size = options[:maximum_size]
 				
@@ -75,6 +101,8 @@ module Protocol
 				end
 			end
 			
+			# Unpack data from this frame and any continuation frames.
+			# @returns [String] The complete unpacked data.
 			def unpack
 				if @continuation.nil?
 					super
@@ -95,11 +123,21 @@ module Protocol
 			
 			TYPE = 0x9
 			
+			# Read the frame and any continuation frames from the stream.
+			# @parameter stream [IO] The stream to read from.
+			# @parameter maximum_frame_size [Integer] Maximum allowed frame size.
+			# @parameter limit [Integer] The maximum number of continuation frames to read.
+			def read(stream, maximum_frame_size, limit = 8)
+				super
+			end
+			
 			# This is only invoked if the continuation is received out of the normal flow.
 			def apply(connection)
 				connection.receive_continuation(self)
 			end
 			
+			# Get a string representation of the continuation frame.
+			# @returns [String] Human-readable frame information.
 			def inspect
 				"\#<#{self.class} stream_id=#{@stream_id} flags=#{@flags} length=#{@length || 0}b>"
 			end

data/lib/protocol/http2/data_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"
@@ -25,10 +25,16 @@ module Protocol
 			
 			TYPE = 0x0
 			
+			# Check if this frame marks the end of the stream.
+			# @returns [Boolean] True if the END_STREAM flag is set.
 			def end_stream?
 				flag_set?(END_STREAM)
 			end
 			
+			# Pack data into the frame, handling empty data as stream end.
+			# @parameter data [String | Nil] The data to pack into the frame.
+			# @parameter arguments [Array] Additional arguments passed to super.
+			# @parameter options [Hash] Additional options passed to super.
 			def pack(data, *arguments, **options)
 				if data
 					super
@@ -38,10 +44,14 @@ module Protocol
 				end
 			end
 			
+			# Apply this DATA frame to a connection for processing.
+			# @parameter connection [Connection] The connection to apply the frame to.
 			def apply(connection)
 				connection.receive_data(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} #{@length || 0}b>"
 			end

data/lib/protocol/http2/error.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 "protocol/http/error"
 
@@ -57,11 +57,14 @@ module Protocol
 		# connection must be aborted.
 		class HandshakeError < Error
 		end
-
+		
 		# Raised by stream or connection handlers, results in GOAWAY frame
 		# which signals termination of the current connection. You *cannot*
 		# recover from this exception, or any exceptions subclassed from it.
 		class ProtocolError < Error
+			# Initialize a protocol error with message and error code.
+			# @parameter message [String] The error message.
+			# @parameter code [Integer] The HTTP/2 error code.
 			def initialize(message, code = PROTOCOL_ERROR)
 				super(message)
 				
@@ -71,26 +74,36 @@ module Protocol
 			attr :code
 		end
 		
+		# Represents an error specific to stream operations.
 		class StreamError < ProtocolError
 		end
 		
+		# Represents an error for operations on closed streams.
 		class StreamClosed < StreamError
+			# Initialize a stream closed error.
+			# @parameter message [String] The error message.
 			def initialize(message)
 				super message, STREAM_CLOSED
 			end
 		end
 		
+		# Represents a GOAWAY-related protocol error.
 		class GoawayError < ProtocolError
 		end
 		
 		# When the frame payload does not match expectations.
 		class FrameSizeError < ProtocolError
+			# Initialize a frame size error.
+			# @parameter message [String] The error message.
 			def initialize(message)
 				super message, FRAME_SIZE_ERROR
 			end
 		end
 		
+		# Represents a header processing error.
 		class HeaderError < StreamClosed
+			# Initialize a header error.
+			# @parameter message [String] The error message.
 			def initialize(message)
 				super(message)
 			end
@@ -98,6 +111,8 @@ module Protocol
 		
 		# Raised on invalid flow control frame or command.
 		class FlowControlError < ProtocolError
+			# Initialize a flow control error.
+			# @parameter message [String] The error message.
 			def initialize(message)
 				super message, FLOW_CONTROL_ERROR
 			end