protocol-http1 0.34.1 → 0.35.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71b9e3af2e930f52ebe6594fc1c81c7454328ab55a19b92c349b95d0d8343b6e
-  data.tar.gz: de119685170063e914f8648d84737b520134ca73a4268762b7d935fe45b07fa3
+  metadata.gz: 2726ec9583e06af47b9b37f5cefb493843bb1a5dff749a145bd117193048aa86
+  data.tar.gz: f1c9bd6f71750cf67d038c98926048e3927b69f4efc64a49f92374f9d01b0b31
 SHA512:
-  metadata.gz: 6a0d9ecf4e542e88ff411495e92e3b9cc754b144429232e55acff51b73a5efa767387fa1a7fa299b8319385dab67a747406089bec7e3cb5ea8ab2345645ad20a
-  data.tar.gz: a1c881966df2abc55ba758445f5b17f8664f115ae37d9ff4e7fe8039f7a2a60bf095c7698281954f69b6b4aee99466abbdb13a6af32263ed63d14dc93562b05f
+  metadata.gz: 1d2b40ff72b50573db8975890a1ddd2a3366725407315f16d336aa72153caddd9a7a2d547b05bd12418dafbcc7f8810dde442821e600e4ee13a36c9aae0b7858
+  data.tar.gz: ca70b6a65753b759d933495a8ca034b6fe3c431d869b6b08bd8ebb9a53488057be2c585c7c7b9d7c880a009d3edd341b973bbe8744ad05b5cd6e5df97e72035a

data/context/getting-started.md

@@ -0,0 +1,117 @@
+# Getting Started
+
+This guide explains how to get started with `protocol-http1`, a low-level implementation of the HTTP/1 protocol for building HTTP clients and servers.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add protocol-http1
+```
+
+## Core Concepts
+
+`protocol-http1` provides a low-level implementation of the HTTP/1 protocol with several core concepts:
+
+- A {ruby Protocol::HTTP1::Connection} which represents the main entry point for creating HTTP/1.1 clients and servers.
+- Integration with the `Protocol::HTTP::Body` classes for handling request and response bodies.
+
+## Usage
+
+`protocol-http1` can be used to build both HTTP clients and servers.
+
+### HTTP Server
+
+Here's a simple HTTP/1.1 server that responds to all requests with "Hello World":
+
+```ruby
+#!/usr/bin/env ruby
+
+require "socket"
+require "protocol/http1/connection"
+require "protocol/http/body/buffered"
+
+# Test with: curl http://localhost:8080/
+
+Addrinfo.tcp("0.0.0.0", 8080).listen do |server|
+	loop do
+		client, address = server.accept
+		connection = Protocol::HTTP1::Connection.new(client)
+		
+		# Read request:
+		while request = connection.read_request
+			authority, method, path, version, headers, body = request
+			
+			# Write response:
+			connection.write_response(version, 200, [["content-type", "text/plain"]])
+			connection.write_body(version, Protocol::HTTP::Body::Buffered.wrap(["Hello World"]))
+			
+			break unless connection.persistent
+		end
+	end
+end
+```
+
+The server:
+
+1. Creates a new {ruby Protocol::HTTP1::Connection} for each client connection.
+2. Reads incoming requests using `read_request`.
+3. Sends responses using `write_response` and `write_body`.
+4. Supports persistent connections by checking `connection.persistent`.
+
+### HTTP Client
+
+Here's a simple HTTP/1.1 client that makes multiple requests:
+
+```ruby
+#!/usr/bin/env ruby
+
+require "async"
+require "async/http/endpoint"
+require "protocol/http1/connection"
+
+Async do
+	endpoint = Async::HTTP::Endpoint.parse("http://localhost:8080")
+	
+	peer = endpoint.connect
+	
+	puts "Connected to #{peer} #{peer.remote_address.inspect}"
+	
+	# IO Buffering...
+	client = Protocol::HTTP1::Connection.new(peer)
+	
+	puts "Writing request..."
+	3.times do
+		client.write_request("localhost", "GET", "/", "HTTP/1.1", [["Accept", "*/*"]])
+		client.write_body("HTTP/1.1", nil)
+		
+		puts "Reading response..."
+		response = client.read_response("GET")
+		version, status, reason, headers, body = response
+		
+		puts "Got response: #{response.inspect}"
+		puts body&.read
+	end
+	
+	puts "Closing client..."
+	client.close
+end
+```
+
+The client:
+
+1. Creates a connection to a server using `Async::HTTP::Endpoint`.
+2. Creates a {ruby Protocol::HTTP1::Connection} wrapper around the socket.
+3. Sends requests using `write_request` and `write_body`.
+4. Reads responses using `read_response`.
+5. Properly closes the connection when done.
+
+### Connection Management
+
+The {ruby Protocol::HTTP1::Connection} handles:
+
+- **Request/Response Parsing**: Automatically parses HTTP/1.1 request and response formats.
+- **Persistent Connections**: Supports HTTP/1.1 keep-alive for multiple requests over one connection.
+- **Body Handling**: Integrates with `Protocol::HTTP::Body` classes for streaming and buffered content.
+- **Header Management**: Properly handles HTTP headers as arrays of key-value pairs.

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/1 protocol.
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-http1/
+  source_code_uri: https://github.com/socketry/protocol-http1.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `protocol-http1`, a low-level
+    implementation of the HTTP/1 protocol for building HTTP clients and servers.

data/lib/protocol/http1/body/chunked.rb

@@ -116,7 +116,16 @@ module Protocol
 				
 				# @returns [String] a human-readable representation of the body.
 				def inspect
-					"\#<#{self.class} #{@length} bytes read in #{@count} chunks>"
+					"\#<#{self.class} #{@length} bytes read in #{@count} chunks, #{@finished ? 'finished' : 'reading'}>"
+				end
+				
+				# @returns [Hash] JSON representation for tracing and debugging.
+				def as_json(...)
+					super.merge(
+						count: @count,
+						finished: @finished,
+						state: @connection ? "open" : "closed"
+					)
 				end
 				
 				private

data/lib/protocol/http1/body/fixed.rb

@@ -74,7 +74,15 @@ module Protocol
 				
 				# @returns [String] a human-readable representation of the body.
 				def inspect
-					"\#<#{self.class} length=#{@length} remaining=#{@remaining} state=#{@connection ? 'open' : 'closed'}>"
+					"#<#{self.class} #{@length} bytes, #{@remaining} remaining, #{empty? ? 'finished' : 'reading'}>"
+				end
+				
+				# @returns [Hash] JSON representation for tracing and debugging.
+				def as_json(...)
+					super.merge(
+						remaining: @remaining,
+						state: @connection ? "open" : "closed"
+					)
 				end
 			end
 		end

data/lib/protocol/http1/body/remainder.rb

@@ -60,7 +60,15 @@ module Protocol
 				
 				# @returns [String] a human-readable representation of the body.
 				def inspect
-					"\#<#{self.class} state=#{@connection ? 'open' : 'closed'}>"
+					"#<#{self.class} #{@block_size} byte blocks, #{empty? ? 'finished' : 'reading'}>"
+				end
+				
+				# @returns [Hash] JSON representation for tracing and debugging.
+				def as_json(...)
+					super.merge(
+						block_size: @block_size,
+						state: @connection ? "open" : "closed"
+					)
 				end
 			end
 		end

data/lib/protocol/http1/connection.rb

@@ -274,7 +274,9 @@ module Protocol
 			# @parameter status [Integer] the HTTP status code.
 			# @parameter headers [Hash] the HTTP headers.
 			# @parameter reason [String] the reason phrase, defaults to the standard reason phrase for the status code.
-			def write_response(version, status, headers, reason = Reason::DESCRIPTIONS[status])
+			def write_response(version, status, headers, reason = nil)
+				reason ||= Reason::DESCRIPTIONS[status]
+				
 				unless @state == :open or @state == :half_closed_remote
 					raise ProtocolError, "Cannot write response in state: #{@state}!"
 				end
@@ -292,7 +294,9 @@ module Protocol
 			# @parameter headers [Hash] the HTTP headers.
 			# @parameter reason [String] the reason phrase, defaults to the standard reason phrase for the status code.
 			# @raises [ProtocolError] if the connection is not in the open or half-closed remote state.
-			def write_interim_response(version, status, headers, reason = Reason::DESCRIPTIONS[status])
+			def write_interim_response(version, status, headers, reason = nil)
+				reason ||= Reason::DESCRIPTIONS[status]
+				
 				unless @state == :open or @state == :half_closed_remote
 					raise ProtocolError, "Cannot write interim response in state: #{@state}!"
 				end

data/lib/protocol/http1/reason.rb

@@ -15,7 +15,7 @@ module Protocol
 				101 => "Switching Protocols",
 				102 => "Processing",
 				103 => "Early Hints",
-
+				
 				200 => "OK",
 				201 => "Created",
 				202 => "Accepted",
@@ -26,7 +26,7 @@ module Protocol
 				207 => "Multi-Status",
 				208 => "Already Reported",
 				226 => "IM Used",
-
+				
 				300 => "Multiple Choices",
 				301 => "Moved Permanently",
 				302 => "Found",
@@ -38,7 +38,7 @@ module Protocol
 				306 => "Switch Proxy",
 				307 => "Temporary Redirect",
 				308 => "Permanent Redirect",
-
+				
 				400 => "Bad Request",
 				401 => "Unauthorized",
 				402 => "Payment Required",
@@ -66,7 +66,7 @@ module Protocol
 				429 => "Too Many Requests",
 				431 => "Request Header Fields Too Large",
 				451 => "Unavailable for Legal Reasons",
-
+				
 				500 => "Internal Server Error",
 				501 => "Not Implemented",
 				502 => "Bad Gateway",

data/lib/protocol/http1/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP1
-		VERSION = "0.34.1"
+		VERSION = "0.35.1"
 	end
 end

data/lib/traces/provider/protocol/http1/connection.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "../../../../protocol/http1/connection"
+
+Traces::Provider(Protocol::HTTP1::Connection) do
+	def write_request(authority, method, target, version, headers)
+		attributes = {
+			authority: authority,
+			method: method,
+			target: target,
+			version: version,
+			headers: headers&.to_h,
+		}
+		
+		Traces.trace("protocol.http1.connection.write_request", attributes: attributes) do
+			super
+		end
+	end
+	
+	def write_response(version, status, headers, reason = nil)
+		attributes = {
+			version: version,
+			status: status,
+			headers: headers&.to_h,
+		}
+		
+		Traces.trace("protocol.http1.connection.write_response", attributes: attributes) do
+			super
+		end
+	end
+	
+	def write_interim_response(version, status, headers, reason = nil)
+		attributes = {
+			version: version,
+			status: status,
+			headers: headers&.to_h,
+			reason: reason,
+		}
+		
+		Traces.trace("protocol.http1.connection.write_interim_response", attributes: attributes) do
+			super
+		end
+	end
+	
+	def write_body(version, body, head = false, trailer = nil)
+		attributes = {
+			version: version,
+			head: head,
+			trailer: trailer,
+			body: body&.as_json,
+		}
+		
+		Traces.trace("protocol.http1.connection.write_body", attributes: attributes) do |span|
+			super
+		rescue => error
+			# Capture the body state at the time of the error for EPIPE debugging:
+			span["error.body"] = body&.as_json
+			span["error.connection"] = {
+				state: @state,
+				persistent: @persistent,
+				count: @count,
+				stream_closed: @stream.nil?
+			}
+			
+			raise error
+		end
+	end
+end

data/lib/traces/provider/protocol/http1.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "http1/connection"

data/readme.md

@@ -22,42 +22,55 @@ Or install it yourself as:
 
 ## Usage
 
-Here is a basic HTTP/1.1 client:
+Please see the [project documentation](https://socketry.github.io/protocol-http1/) for more details.
 
-``` ruby
-require 'async'
-require 'async/io/stream'
-require 'async/http/endpoint'
-require 'protocol/http1/connection'
-
-Async do
-	endpoint = Async::HTTP::Endpoint.parse("https://www.google.com/search?q=kittens", alpn_protocols: ["http/1.1"])
-	
-	peer = endpoint.connect
-	
-	puts "Connected to #{peer} #{peer.remote_address.inspect}"
-	
-	# IO Buffering...
-	stream = Async::IO::Stream.new(peer)
-	client = Protocol::HTTP1::Connection.new(stream)
-	
-	def client.read_line
-		@stream.read_until(Protocol::HTTP1::Connection::CRLF) or raise EOFError
-	end
-	
-	puts "Writing request..."
-	client.write_request("www.google.com", "GET", "/search?q=kittens", "HTTP/1.1", [["Accept", "*/*"]])
-	client.write_body(nil)
-	
-	puts "Reading response..."
-	response = client.read_response("GET")
-	
-	puts "Got response: #{response.inspect}"
-	
-	puts "Closing client..."
-	client.close
-end
-```
+  - [Getting Started](https://socketry.github.io/protocol-http1/guides/getting-started/index) - This guide explains how to get started with `protocol-http1`, a low-level implementation of the HTTP/1 protocol for building HTTP clients and servers.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-http1/releases/index) for all releases.
+
+### v0.35.0
+
+  - Add traces provider for `Protocol::HTTP1::Connection`.
+
+### v0.34.1
+
+  - Fix connection state handling to allow idempotent response body closing.
+  - Add `kisaten` fuzzing integration for improved security testing.
+
+### v0.34.0
+
+  - Support empty header values in HTTP parsing for better compatibility.
+
+### v0.33.0
+
+  - Support high-byte characters in HTTP headers for improved international compatibility.
+
+### v0.32.0
+
+  - Fix header parsing to handle tab characters between values correctly.
+  - Complete documentation coverage for all public APIs.
+
+### v0.31.0
+
+  - Enforce one-way transition for persistent connections to prevent invalid state changes.
+
+### v0.30.0
+
+  - Make `authority` header optional in HTTP requests for improved flexibility.
+
+### v0.29.0
+
+  - Add block/yield interface to `read_request` and `read_response` methods.
+
+### v0.28.1
+
+  - Fix handling of `nil` lines in HTTP parsing.
+
+### v0.28.0
+
+  - Add configurable maximum line length to prevent denial of service attacks.
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,246 @@
+# Releases
+
+## v0.35.0
+
+  - Add traces provider for `Protocol::HTTP1::Connection`.
+
+## v0.34.1
+
+  - Fix connection state handling to allow idempotent response body closing.
+  - Add `kisaten` fuzzing integration for improved security testing.
+
+## v0.34.0
+
+  - Support empty header values in HTTP parsing for better compatibility.
+
+## v0.33.0
+
+  - Support high-byte characters in HTTP headers for improved international compatibility.
+
+## v0.32.0
+
+  - Fix header parsing to handle tab characters between values correctly.
+  - Complete documentation coverage for all public APIs.
+
+## v0.31.0
+
+  - Enforce one-way transition for persistent connections to prevent invalid state changes.
+
+## v0.30.0
+
+  - Make `authority` header optional in HTTP requests for improved flexibility.
+
+## v0.29.0
+
+  - Add block/yield interface to `read_request` and `read_response` methods.
+
+## v0.28.1
+
+  - Fix handling of `nil` lines in HTTP parsing.
+
+## v0.28.0
+
+  - Add configurable maximum line length to prevent denial of service attacks.
+
+## v0.27.0
+
+  - Improve error message clarity and debugging information.
+  - Separate state machine logic from connection callbacks for better architecture.
+
+## v0.26.0
+
+  - Improve error handling propagation through connection closure.
+
+## v0.25.0
+
+  - Fix connection stream handling when closing response bodies.
+  - Improve connection state management for better reliability.
+
+## v0.24.0
+
+  - Add connection state tracking for safer connection reuse.
+
+## v0.23.0
+
+  - Add `Body#discard` method support for improved resource management.
+
+## v0.22.0
+
+  - Improve handling of underlying stream objects for better stability.
+
+## v0.21.0
+
+  - Fix connection persistence handling for `1xx` responses and remainder bodies.
+  - Improve debug output readability by using `.inspect` instead of `.dump`.
+  - Enhanced request upgrade body handling.
+
+## v0.20.0
+
+  - Restructure error hierarchy for better error handling consistency.
+
+## v0.19.1
+
+  - Fix stream flushing in `write_body_and_close` for proper connection cleanup.
+
+## v0.19.0
+
+  - Add `#hijacked?` method to check connection hijack status.
+
+## v0.18.0
+
+  - Add persistent connection handling examples.
+  - Improve performance by avoiding blocking operations on `eof?` checks.
+
+## v0.17.0
+
+  - Add `HTTP/1` client and server example implementations.
+
+## v0.16.1
+
+  - Allow external control of persistent connection settings.
+  - Separate request line and response status line parsing for better maintainability.
+
+## v0.16.0
+
+  - Add support for HTTP interim (informational) responses like `103 Early Hints`.
+  - Improve error messages by including `content_length` in debugging output.
+
+## v0.15.1
+
+  - Add strict validation for `content-length` and chunk length values.
+
+## v0.15.0
+
+  - Migrate test suite to `Sus` testing framework with 100% coverage.
+
+## v0.14.6
+
+  - Handle `IOError` for closed streams gracefully.
+  - Improve memory management by removing string ownership model.
+  - Add early hints server example.
+
+## v0.14.4
+
+  - Improve trailer handling when content length is known in advance.
+
+## v0.14.3
+
+  - Enhanced trailer support with comprehensive test coverage.
+
+## v0.14.2
+
+  - Prefer chunked transfer encoding when possible for better streaming performance.
+
+## v0.14.1
+
+  - Improve error handling when reading chunk length lines.
+
+## v0.14.0
+
+  - Rename "trailers" to "trailer" for HTTP specification compliance.
+
+## v0.13.2
+
+  - Enable `HTTP/1.1` connections to write fixed-length message bodies.
+
+## v0.13.1
+
+  - Fix `HTTP/1` request parsing example in documentation.
+
+## v0.13.0
+
+  - Implement pessimistic flushing strategy for better performance.
+  - Add fuzzing infrastructure for security testing.
+
+## v0.12.0
+
+  - Update dependencies to latest compatible versions.
+
+## v0.11.1
+
+  - Improve header and trailer processing logic.
+  - Update behavior to match new `write_body` semantics.
+
+## v0.11.0
+
+  - Add comprehensive HTTP trailer support for chunked transfers.
+  - Simplify chunked encoding implementation.
+
+## v0.10.3
+
+  - Improve handling of `HEAD` requests and responses.
+  - Better error handling for incomplete fixed-length message bodies.
+
+## v0.10.2
+
+  - Add RFC-compliant header validation during read and write operations.
+  - Improve performance with `frozen_string_literals: true`.
+
+## v0.10.1
+
+  - Drop support for Ruby 2.3 (end of life).
+  - Validate that response header values don't contain `CR` or `LF` characters.
+
+## v0.10.0
+
+  - Parse HTTP `connection` header values as case-insensitive per RFC specification.
+
+## v0.9.0
+
+  - Enhanced `Remainder` body implementation with comprehensive test coverage.
+  - Improve HTTP `CONNECT` method handling for both client and server.
+  - Improve performance by removing array allocation in method arguments.
+
+## v0.8.3
+
+  - Restore Ruby 2.3 compatibility using monkey patches.
+  - Enhanced test suite with improved memory and file handling utilities.
+
+## v0.8.2
+
+  - Simplify HTTP request line validation logic.
+
+## v0.8.1
+
+  - Improve error handling and recovery for malformed HTTP requests.
+
+## v0.8.0
+
+  - Add automatic HTTP reason phrase generation based on status codes.
+
+## v0.7.0
+
+  - Enhanced connection hijacking support for pooled connections.
+
+## v0.6.0
+
+  - Adopt `Protocol::HTTP` Body abstractions for better consistency.
+  - Require callers to handle hijacking for `HTTP/1` protocol upgrades.
+  - Add flexible request/response body and upgrade handling.
+  - Fix WebSocket compatibility issues with Safari browser.
+
+## v0.5.0
+
+  - Return `nil` when unable to read HTTP request line (connection closed).
+
+## v0.4.1
+
+  - Ensure output streams are properly closed within accept blocks.
+
+## v0.4.0
+
+  - Improve handling of HTTP upgrade request and response message bodies.
+
+## v0.3.0
+
+  - Enhanced support for partial connection hijacking and protocol upgrades.
+
+## v0.2.0
+
+  - Improve error handling throughout the codebase.
+
+## v0.1.0
+
+  - Initial public release of `Protocol::HTTP1`.
+  - Low-level `HTTP/1.0` and `HTTP/1.1` protocol implementation.
+  - Support for persistent connections, chunked transfer encoding, and connection upgrades.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http1
 version: !ruby/object:Gem::Version
-  version: 0.34.1
+  version: 0.35.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -61,6 +61,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/protocol/http1.rb
 - lib/protocol/http1/body.rb
 - lib/protocol/http1/body/chunked.rb
@@ -70,8 +72,11 @@ files:
 - lib/protocol/http1/error.rb
 - lib/protocol/http1/reason.rb
 - lib/protocol/http1/version.rb
+- lib/traces/provider/protocol/http1.rb
+- lib/traces/provider/protocol/http1/connection.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/protocol-http1
 licenses:
 - MIT
@@ -92,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A low level implementation of the HTTP/1 protocol.
 test_files: []