protocol-http 0.28.2 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf15de4010337ee2c56c39bf6955ccfc7e6ae623426e31bface95cf15c8ef26
-  data.tar.gz: f8d4d30147c5402ca5003195b5b2d6e1688b47bf1a56ee23131b420952efac68
+  metadata.gz: 5365fcaf109db92e1db6bc6389e881881f7ec19c4f1bcd747b16d72698e89a7c
+  data.tar.gz: 11f68df5f5b9370579764e475a0fe1579c3b4d2f06aaed80efb0cb5fa5c6e392
 SHA512:
-  metadata.gz: 236c830db8716243e3c9d7eec818c4b6a6b83ab399efe131b3475a4a1aac9e57dbe7ad809d7e0b5f4715c40371c8b2adbd7ebb6c16571ef5397fc209f08244d8
-  data.tar.gz: 35574f913cbaaee7f8ce06f8855843dd517f9d29ed898852c53c2ef12003fa0c62308ecd4e4dc3d04a7d34b4171ce64bb87b8d09779cfa69533f0da1c74b1be8
+  metadata.gz: 05f867a38d373f1491630bc5a9bf30401b8ac0fa41cec5392787a1fb916d42fa0f14ff8b80078b89246ab5bbdaae40b2dd67b77302571e3cb0803477e48ead4f
+  data.tar.gz: dbb7ac119a2d46c5150b8a274c89280582d69f64718849a7537d0a4b876f40c0b9a36c47fc3e2d6f27a244e12465d4ba372a3e4c87c7d0e1c738c0757cd672d5

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

@@ -11,25 +11,29 @@ module Protocol
 		module Body
 			# A body which buffers all it's contents.
 			class Buffered < Readable
-				# Wraps an array into a buffered body.
+				# Tries to wrap an object in a {Buffered} instance.
 				#
 				# For compatibility, also accepts anything that behaves like an `Array(String)`.
 				#
 				# @parameter body [String | Array(String) | Readable | nil] the body to wrap.
 				# @returns [Readable | nil] the wrapped body or nil if nil was given.
-				def self.wrap(body)
-					if body.is_a?(Readable)
-						return body
-					elsif body.is_a?(Array)
-						return self.new(body)
-					elsif body.is_a?(String)
-						return self.new([body])
-					elsif body
-						return self.for(body)
+				def self.wrap(object)
+					if object.is_a?(Readable)
+						return object
+					elsif object.is_a?(Array)
+						return self.new(object)
+					elsif object.is_a?(String)
+						return self.new([object])
+					elsif object
+						return self.read(object)
 					end
 				end
 				
-				def self.for(body)
+				# Read the entire body into a buffered representation.
+				#
+				# @parameter body [Readable] the body to read.
+				# @returns [Buffered] the buffered body.
+				def self.read(body)
 					chunks = []
 					
 					body.each do |chunk|
@@ -77,8 +81,14 @@ module Protocol
 					@chunks << chunk
 				end
 				
+				def rewindable?
+					true
+				end
+				
 				def rewind
 					@index = 0
+					
+					return true
 				end
 				
 				def inspect

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

@@ -24,6 +24,14 @@ module Protocol
 					@callback = callback
 				end
 				
+				def rewindable?
+					false
+				end
+				
+				def rewind
+					false
+				end
+				
 				def finish
 					super.tap do
 						if @callback

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

@@ -29,6 +29,14 @@ module Protocol
 					false
 				end
 				
+				def rewindable?
+					false
+				end
+				
+				def rewind
+					false
+				end
+				
 				def length
 					nil
 				end
@@ -58,7 +66,7 @@ module Protocol
 				# @returns [Buffered] The buffered body.
 				def finish
 					# Internally, this invokes `self.each` which then invokes `self.close`.
-					Buffered.for(self)
+					Buffered.read(self)
 				end
 				
 				# Enumerate all chunks until finished, then invoke `#close`.

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

@@ -11,6 +11,16 @@ module Protocol
 		module Body
 			# A body which buffers all it's contents as it is `#read`.
 			class Rewindable < Wrapper
+				def self.wrap(message)
+					if body = message.body
+						if body.rewindable?
+							body
+						else
+							message.body = self.new(body)
+						end
+					end
+				end
+				
 				def initialize(body)
 					super(body)
 					
@@ -26,7 +36,9 @@ module Protocol
 					(@index < @chunks.size) || super
 				end
 				
-				# A rewindable body wraps some other body. Convert it to a buffered body 
+				# A rewindable body wraps some other body. Convert it to a buffered body. The buffered body will share the same chunks as the rewindable body.
+				#
+				# @returns [Buffered] the buffered body. 
 				def buffered
 					Buffered.new(@chunks)
 				end
@@ -54,6 +66,10 @@ module Protocol
 					@index = 0
 				end
 				
+				def rewindable?
+					true
+				end
+				
 				def inspect
 					"\#<#{self.class} #{@index}/#{@chunks.size} chunks read>"
 				end

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

@@ -10,6 +10,10 @@ module Protocol
 		module Body
 			# Wrapping body instance. Typically you'd override `#read`.
 			class Wrapper < Readable
+				# Wrap the body of the given message in a new instance of this class.
+				#
+				# @parameter message [Request | Response] the message to wrap.
+				# @returns [Wrapper | nil] the wrapped body or nil if the body was nil.
 				def self.wrap(message)
 					if body = message.body
 						message.body = self.new(body)
@@ -42,6 +46,14 @@ module Protocol
 					@body.ready?
 				end
 				
+				def rewind
+					@body.rewind
+				end
+				
+				def rewindable?
+					@body.rewindable?
+				end
+				
 				def length
 					@body.length
 				end

data/lib/protocol/http/methods.rb

@@ -70,9 +70,9 @@ module Protocol
 			end
 			
 			self.each do |name, value|
-				define_method(name) do |location, headers = nil, body = nil|
+				define_method(name) do |location, *arguments, **options|
 					self.call(
-						Request[value, location.to_s, Headers[headers], body]
+						Request[value, location.to_s, *arguments, **options]
 					)
 				end
 			end

data/lib/protocol/http/request.rb

@@ -25,7 +25,7 @@ module Protocol
 		class Request
 			prepend Body::Reader
 			
-			def initialize(scheme = nil, authority = nil, method = nil, path = nil, version = nil, headers = Headers.new, body = nil, protocol = nil)
+			def initialize(scheme = nil, authority = nil, method = nil, path = nil, version = nil, headers = Headers.new, body = nil, protocol = nil, interim_response = nil)
 				@scheme = scheme
 				@authority = authority
 				@method = method
@@ -34,6 +34,7 @@ module Protocol
 				@headers = headers
 				@body = body
 				@protocol = protocol
+				@interim_response = interim_response
 			end
 			
 			# @attribute [String] the request scheme, usually `"http"` or `"https"`.
@@ -60,11 +61,30 @@ module Protocol
 			# @attribute [String | Array(String) | Nil] the request protocol, usually empty, but occasionally `"websocket"` or `"webtransport"`. In HTTP/1, it is used to request a connection upgrade, and in HTTP/2 it is used to indicate a specfic protocol for the stream.
 			attr_accessor :protocol
 			
+			# @attribute [Proc] a callback which is called when an interim response is received.
+			attr_accessor :interim_response
+			
 			# Send the request to the given connection.
 			def call(connection)
 				connection.call(self)
 			end
 			
+			# Send an interim response back to the origin of this request, if possible.
+			def send_interim_response(status, headers)
+				@interim_response&.call(status, headers)
+			end
+			
+			def on_interim_response(&block)
+				if interim_response = @interim_response
+					@interim_response = ->(status, headers) do
+						block.call(status, headers)
+						interim_response.call(status, headers)
+					end
+				else
+					@interim_response = block
+				end
+			end
+			
 			# Whether this is a HEAD request: no body is expected in the response.
 			def head?
 				@method == Methods::HEAD
@@ -81,11 +101,11 @@ module Protocol
 			# @parameter path [String] The path, e.g. `"/index.html"`, `"/search?q=hello"`, etc.
 			# @parameter headers [Hash] The headers, e.g. `{"accept" => "text/html"}`, etc.
 			# @parameter body [String | Array(String) | Body::Readable] The body, e.g. `"Hello, World!"`, etc. See {Body::Buffered.wrap} for more information about .
-			def self.[](method, path, headers = nil, body = nil)
+			def self.[](method, path, _headers = nil, _body = nil, scheme: nil, authority: nil, headers: _headers, body: _body, protocol: nil, interim_response: nil)
 				body = Body::Buffered.wrap(body)
-				headers = ::Protocol::HTTP::Headers[headers]
+				headers = Headers[headers]
 				
-				self.new(nil, nil, method, path, nil, headers, body)
+				self.new(scheme, authority, method, path, nil, headers, body, protocol, interim_response)
 			end
 			
 			# Whether the request can be replayed without side-effects.

data/lib/protocol/http/response.rb

@@ -130,9 +130,9 @@ module Protocol
 			# @parameter status [Integer] The HTTP status code, e.g. `200`, `404`, etc.
 			# @parameter headers [Hash] The headers, e.g. `{"content-type" => "text/html"}`, etc.
 			# @parameter body [String | Array(String) | Body::Readable] The body, e.g. `"Hello, World!"`, etc. See {Body::Buffered.wrap} for more information about .
-			def self.[](status, headers = nil, body = nil, protocol = nil)
+			def self.[](status, _headers = nil, _body = nil, headers: _headers, body: _body, protocol: nil)
 				body = Body::Buffered.wrap(body)
-				headers = ::Protocol::HTTP::Headers[headers]
+				headers = Headers[headers]
 				
 				self.new(nil, status, headers, body, protocol)
 			end

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.28.2"
+		VERSION = "0.30.0"
 	end
 end

data/readme.md

@@ -18,6 +18,25 @@ Please see the [project documentation](https://socketry.github.io/protocol-http/
 
   - [Design Overview](https://socketry.github.io/protocol-http/guides/design-overview/index) - This guide explains the high level design of `protocol-http` in the context of wider design patterns that can be used to implement HTTP clients and servers.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-http/releases/index) for all releases.
+
+### Unreleased
+
+  - [`Request[]` and `Response[]` Keyword Arguments](https://socketry.github.io/protocol-http/releases/index#request[]-and-response[]-keyword-arguments)
+  - [Interim Response Handling](https://socketry.github.io/protocol-http/releases/index#interim-response-handling)
+
+## See Also
+
+  - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this
+    interface.
+  - [protocol-http2](https://github.com/socketry/protocol-http2) — HTTP/2 client/server implementation using this
+    interface.
+  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client and server, supporting multiple HTTP
+    protocols & TLS.
+  - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server WebSockets.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -35,13 +54,3 @@ In order to protect users of this project, we require all contributors to comply
 ### Community Guidelines
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
-
-## See Also
-
-  - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this
-    interface.
-  - [protocol-http2](https://github.com/socketry/protocol-http2) — HTTP/2 client/server implementation using this
-    interface.
-  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client and server, supporting multiple HTTP
-    protocols & TLS.
-  - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server WebSockets.

data/releases.md

@@ -0,0 +1,40 @@
+# Releases
+
+## Unreleased
+
+### `Request[]` and `Response[]` Keyword Arguments
+
+The `Request[]` and `Response[]` methods now support keyword arguments as a convenient way to set various positional arguments.
+
+```ruby
+# Request keyword arguments:
+client.get("/", headers: {"accept" => "text/html"}, authority: "example.com")
+
+# Response keyword arguments:
+def call(request)
+	return Response[200, headers: {"content-Type" => "text/html"}, body: "Hello, World!"]
+```
+
+### Interim Response Handling
+
+The `Request` class now exposes a `#interim_response` attribute which can be used to handle interim responses both on the client side and server side.
+
+On the client side, you can pass a callback using the `interim_response` keyword argument which will be invoked whenever an interim response is received:
+
+```ruby
+client = ...
+response = client.get("/index", interim_response: proc{|status, headers| ...})
+```
+
+On the server side, you can send an interim response using the `#send_interim_response` method:
+
+```ruby
+def call(request)
+	if request.headers["expect"] == "100-continue"
+		# Send an interim response:
+		request.send_interim_response(100)
+	end
+	
+	# ...
+end
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.28.2
+  version: 0.30.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -47,7 +47,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2024-08-30 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -93,6 +93,7 @@ files:
 - lib/protocol/http/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/protocol-http
 licenses:
 - MIT