protocol-http 0.71.0 → 0.72.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e4555d4a7ae53c17ce8bd6ccf545bd01d6eeafdf4ee288ddfb3f2aae76a3327
-  data.tar.gz: 7808028142ff2afc20f5fd7a5a1476e74c17fa7a847effaf924253d77858f1d3
+  metadata.gz: 65ff75ab6759c365978c021f9f35150b4d5fa7a7b2bba8783041afda704607bf
+  data.tar.gz: b234c9cce9f99d7c4313fde4d2b4b15bf10a074875efc358d4b5fb2bad19e27d
 SHA512:
-  metadata.gz: c724bfa82172160c4982791c20c707e6b75fdef0bef4155da339ec092e2b86c16d92da18e540ee8254844766750fe7c2b7896a2cae4fb2da155385102ff8d9b7
-  data.tar.gz: 7b965c45ef273d6dac8df08ead9282bc9f35a70d0dc3100739b2bc331ef690d5b532f7c1a8c74d547ba628e89a9291e945f3fd8a2a6ce42aab81e94454f8fff7
+  metadata.gz: 16529f44e3cfde0d49afa69d08d64570fe165af759ea2d0d74aef74363768569d8af7ec2008c1a67ac8ceadae655b719d4d6aa9a28c628633d31a1197b186cdd
+  data.tar.gz: a7858b7d471e34772eb722d03af12fa7ec077deff39c9ce94bd9fff3146e0453fe1cab0823479a0ff56dfd662c10fdf856906e37ce5892bc2843ee002a79f27c

data/context/message-body.md

@@ -259,6 +259,23 @@ content = uppercase.join  # => "HELLO WORLD"
 
 ## Life-cycle
 
+Bodies model application-facing streams. Their close operations describe what the application will do next; protocol implementations are responsible for mapping those operations to the wire protocol safely.
+
+### Directional Closure
+
+Request and response bodies are independent, so a bidirectional {ruby Protocol::HTTP::Body::Stream} can close either direction without implicitly closing the other:
+
+| Operation | Application-level meaning | Typical protocol consequence |
+| --- | --- | --- |
+| `read` returns `nil` | The peer or producer completed the input normally. | The inbound body has reached end-of-stream. |
+| `close_read` before end-of-stream | The application will not consume the remaining input, but may continue writing. | Discard unread data, terminate the exchange, or make the connection non-reusable. |
+| `close_write` without an error | The application has finished producing output, but may continue reading. | Preserve previously written data and send a normal end-of-stream. |
+| `close` without an error | The application has finished with both directions. | Complete or terminate the exchange without reporting an application error. |
+| `close` with an error | The application cannot continue the exchange successfully. | Propagate the error or terminate the exchange using an appropriate protocol error. |
+| `discard` | Consume input without processing it. | Prefer preserving the exchange or connection for reuse. |
+
+These operations update local application-facing state. Returning from a close operation does not guarantee that the peer has observed it or that the underlying transport has been closed synchronously. Those details depend on the protocol and may be completed later.
+
 ### Initialization
 
 Bodies are typically initialized with the data they need to process. For example:

data/lib/protocol/http/body/readable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2023, by Bruno Sutic.
 
 require_relative "stream"
@@ -22,7 +22,11 @@ module Protocol
 			class Readable
 				# Close the stream immediately. After invoking this method, the stream should be considered closed, and all internal resources should be released.
 				#
-				# If an error occured while handling the output, it can be passed as an argument. This may be propagated to the client, for example the client may be informed that the stream was not fully read correctly.
+				# Closing the stream before it reaches end-of-file abandons any remaining input. The protocol implementation must account for that unread data before the associated exchange or connection can be reused. Depending on the protocol, it may discard the remaining data, terminate the exchange, or make the connection non-reusable. Use {discard} when preserving the exchange or connection is preferred.
+				#
+				# When closing before end-of-file, omitting the error represents deliberate application-level abandonment, not a protocol failure.
+				#
+				# If an error occurred while handling the output, it can be passed as an argument. This may be propagated to the client, for example the client may be informed that the stream was not fully read correctly.
 				#
 				# Invoking {read} after {close} will return `nil`.
 				#

data/lib/protocol/http/body/stream.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2023, by Genki Takiuchi.
 # Copyright, 2025, by William T. Nelson.
 
@@ -347,7 +347,13 @@ module Protocol
 				def flush
 				end
 				
-				# Close the input body.
+				# Close the application-facing input body. This does not close the output body, which may continue to be written independently.
+				#
+				# If the input has not reached end-of-file, any remaining data is abandoned. The protocol implementation must ensure that unread data cannot interfere with subsequent exchanges. Depending on the protocol, it may discard the remaining data, terminate the current exchange, or make the connection non-reusable.
+				#
+				# Closing without an error represents orderly application-level abandonment, not a protocol failure.
+				#
+				# This method is idempotent. After the first call, subsequent calls have no effect.
 				#
 				# If, while processing the data that was read from this stream, an error is encountered, it should be passed to this method.
 				#
@@ -362,7 +368,11 @@ module Protocol
 					end
 				end
 				
-				# Close the output body.
+				# Close the application-facing output body. This does not close the input body, which may continue to be read independently.
+				#
+				# Closing without an error indicates that no more output will be produced. Previously written data remains part of the output and should be followed by a normal end-of-stream from the protocol implementation. If an error is provided, the protocol implementation may terminate the exchange instead.
+				#
+				# This method is idempotent. After the first call, subsequent calls have no effect.
 				#
 				# If, while generating the data that is written to this stream, an error is encountered, it should be passed to this method.
 				#
@@ -377,6 +387,10 @@ module Protocol
 				
 				# Close the input and output bodies.
 				#
+				# Closing without an error represents orderly completion or abandonment of both application-facing directions, not cancellation. If the peer has not completed the exchange, the protocol implementation may need to terminate it without reporting an application error.
+				#
+				# Repeated calls are safe; each underlying direction will be closed at most once.
+				#
 				# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 				def close(error = nil)
 					self.close_read(error)

data/lib/protocol/http/body/streamable.rb

@@ -15,7 +15,7 @@ module Protocol
 			#
 			# In some cases, it's advantageous to directly read and write to the underlying stream if possible. For example, HTTP/1 upgrade requests, WebSockets, and similar. To handle that case, response bodies can implement {stream?} and return `true`. When {stream?} returns true, the body **should** be consumed by calling `call(stream)`. Server implementations may choose to always invoke `call(stream)` if it's efficient to do so. Bodies that don't support it will fall back to using {each}.
 			#
-			# When invoking `call(stream)`, the stream can be read from and written to, and closed. However, the stream is only guaranteed to be open for the duration of the `call(stream)` call. Once the method returns, the stream **should** be closed by the server.
+			# Invoking `call(stream)` transfers ownership of the stream to the called body. The body may read from and write to the stream, and **must** close it before returning. The caller must consider the stream closed and unusable after `call(stream)` returns.
 			module Streamable
 				# Generate a new streaming request body using the given block to generate the body.
 				#
@@ -113,7 +113,7 @@ module Protocol
 						@output.read
 					end
 					
-					# Invoke the block with the given stream. The block can read and write to the stream, and must close the stream when finishing.
+					# Invoke the block with the given stream. The block owns the stream for the duration of the call and must close it before returning.
 					#
 					# @parameter stream [Stream] The stream to read and write to.
 					def call(stream)

data/lib/protocol/http/error.rb

@@ -22,15 +22,17 @@ module Protocol
 		# @deprecated Use {RefusedError} instead.
 		RequestRefusedError = RefusedError
 		
-		# Represents a bad request error (as opposed to a server error).
-		# This is used to indicate that the request was malformed or invalid.
+		# Marks errors which may indicate a malformed or invalid request when raised while processing an incoming request.
 		module BadRequest
 		end
 		
-		# Raised when a singleton (e.g. `content-length`) header is duplicated in a request or response.
-		class DuplicateHeaderError < Error
+		# Raised when an HTTP header is malformed or invalid. When raised while processing an incoming request, it may be treated as a bad request.
+		class InvalidHeaderError < Error
 			include BadRequest
-			
+		end
+		
+		# Raised when a singleton (e.g. `content-length`) header is duplicated in a request or response.
+		class DuplicateHeaderError < InvalidHeaderError
 			# @parameter key [String] The header key that was duplicated.
 			def initialize(key, existing_value, new_value)
 				super("Duplicate singleton header key: #{key.inspect}")
@@ -62,9 +64,7 @@ module Protocol
 		end
 		
 		# Raised when an invalid trailer header is encountered in headers.
-		class InvalidTrailerError < Error
-			include BadRequest
-			
+		class InvalidTrailerError < InvalidHeaderError
 			# @parameter key [String] The trailer key that is invalid.
 			def initialize(key)
 				super("Invalid trailer key: #{key.inspect}")

data/lib/protocol/http/header/accept.rb

@@ -23,7 +23,7 @@ module Protocol
 					(?=,|\z)                  # Match until a comma or end of string
 				/x
 				
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				MEDIA_RANGE = /\A(?<type>#{TOKEN})\/(?<subtype>#{TOKEN})(?<parameters>.*)\z/
 				

data/lib/protocol/http/header/accept_charset.rb

@@ -12,7 +12,7 @@ module Protocol
 		module Header
 			# The `accept-charset` header represents a list of character sets that the client can accept.
 			class AcceptCharset < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# https://tools.ietf.org/html/rfc7231#section-5.3.3
 				CHARSET = /\A(?<name>#{TOKEN})(;q=(?<q>#{QVALUE}))?\z/

data/lib/protocol/http/header/accept_encoding.rb

@@ -12,7 +12,7 @@ module Protocol
 		module Header
 			# The `accept-encoding` header represents a list of encodings that the client can accept.
 			class AcceptEncoding < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# https://tools.ietf.org/html/rfc7231#section-5.3.1
 				QVALUE = /0(\.[0-9]{0,3})?|1(\.[0]{0,3})?/

data/lib/protocol/http/header/accept_language.rb

@@ -12,7 +12,7 @@ module Protocol
 		module Header
 			# The `accept-language` header represents a list of languages that the client can accept.
 			class AcceptLanguage < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# https://tools.ietf.org/html/rfc3066#section-2.1
 				NAME = /\*|[A-Z]{1,8}(-[A-Z0-9]{1,8})*/i

data/lib/protocol/http/header/digest.rb

@@ -23,7 +23,7 @@ module Protocol
 			# # => "sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, md5=9bb58f26192e4ba00f01e2e7b136bbd8"
 			# ```
 			class Digest < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# https://tools.ietf.org/html/rfc3230#section-4.3.2
 				ENTRY = /\A(?<algorithm>[a-zA-Z0-9][a-zA-Z0-9\-]*)\s*=\s*(?<value>.*)\z/

data/lib/protocol/http/header/range.rb

@@ -10,7 +10,7 @@ module Protocol
 		module Header
 			# Represents a `range` request header.
 			class Range
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				TOKEN = /[!#$%&'*+\-.0-9A-Z^_`a-z|~]+/
 				HEADER = /\A(?<unit>#{TOKEN})=(?<ranges>.*)\z/

data/lib/protocol/http/header/server_timing.rb

@@ -23,7 +23,7 @@ module Protocol
 			# # => "db;dur=53.2, cache;dur=12.1;desc=\"Redis lookup\""
 			# ```
 			class ServerTiming < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# https://www.w3.org/TR/server-timing/
 				METRIC = /\A(?<name>[a-zA-Z0-9][a-zA-Z0-9_\-]*)(;(?<parameters>.*))?\z/

data/lib/protocol/http/header/te.rb

@@ -14,7 +14,7 @@ module Protocol
 			#
 			# The `te` header allows a client to indicate which transfer encodings it can handle, and in what order of preference using quality factors.
 			class TE < Split
-				ParseError = Class.new(Error)
+				ParseError = Class.new(InvalidHeaderError)
 				
 				# Transfer encoding token pattern
 				TOKEN = /[!#$%&'*+\-.0-9A-Z^_`a-z|~]+/

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.71.0"
+		VERSION = "0.72.0"
 	end
 end

data/readme.md

@@ -30,6 +30,16 @@ Please see the [project documentation](https://socketry.github.io/protocol-http/
 
 Please see the [project releases](https://socketry.github.io/protocol-http/releases/index) for all releases.
 
+### v0.72.0
+
+  - Clarified body stream lifecycle and ownership, including the directional semantics of `Protocol::HTTP::Body::Stream#close_read`, `#close_write`, and `#close`, how premature input closure affects the associated HTTP exchange, and ownership of streams passed to `Streamable#call`.
+  - Introduce `Protocol::HTTP::InvalidHeaderError` for malformed or invalid headers, which can be treated as bad requests.
+
+### v0.71.0
+
+  - Parse all cookie pairs from `Cookie` header fields, including multiple semicolon-separated pairs within each field.
+  - Preserve `Set-Cookie` parsing as one cookie plus attributes/directives per header field.
+
 ### v0.70.0
 
   - Add stable preference ordering for weighted `Accept`, `Accept-Charset`, `Accept-Encoding`, `Accept-Language`, and `TE` values.
@@ -64,14 +74,6 @@ Please see the [project releases](https://socketry.github.io/protocol-http/relea
 
   - Add support for the HTTP `QUERY` method.
 
-### v0.62.1
-
-  - Fix handling of `Stream#read(0)`, it must return a mutable string (or clear the given buffer).
-
-### v0.61.0
-
-  - Introduce `Protocol::HTTP::RefusedError` for indicating a stream or request was refused before processing and can be safely retried. `RequestRefusedError` is provided as an alias for backwards compatibility.
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v0.72.0
+
+  - Clarified body stream lifecycle and ownership, including the directional semantics of `Protocol::HTTP::Body::Stream#close_read`, `#close_write`, and `#close`, how premature input closure affects the associated HTTP exchange, and ownership of streams passed to `Streamable#call`.
+  - Introduce `Protocol::HTTP::InvalidHeaderError` for malformed or invalid headers, which can be treated as bad requests.
+
+## v0.71.0
+
+  - Parse all cookie pairs from `Cookie` header fields, including multiple semicolon-separated pairs within each field.
+  - Preserve `Set-Cookie` parsing as one cookie plus attributes/directives per header field.
+
 ## v0.70.0
 
   - Add stable preference ordering for weighted `Accept`, `Accept-Charset`, `Accept-Encoding`, `Accept-Language`, and `TE` values.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.71.0
+  version: 0.72.0
 platform: ruby
 authors:
 - Samuel Williams