protocol-http 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5839d2adb8415083224423beb2d5a3c0a50e22090a75424276e1a0939cc800a
-  data.tar.gz: 0517ecffe3b1f6c486b1cba2b5cbf4b3b7a8daf2cb11469b73d0d61cb5492cb1
+  metadata.gz: 5365fcaf109db92e1db6bc6389e881881f7ec19c4f1bcd747b16d72698e89a7c
+  data.tar.gz: 11f68df5f5b9370579764e475a0fe1579c3b4d2f06aaed80efb0cb5fa5c6e392
 SHA512:
-  metadata.gz: 5fe865bc6ae53bfbd34ca9e43c6c38d2dcb3874b0655b1960936960b690cfefc0203ecde64ea7ea3af17a8a1093382d98f419e5d88b24708af99ef210a282e7e
-  data.tar.gz: 5c576ba8d79c0c6d21022d224b936f307640e2a785685cb82ec2eb0da588fcc8cbb215d2b7a05572ab91274978acc1f3a39edc0dfb5946fbef32dafa51389296
+  metadata.gz: 05f867a38d373f1491630bc5a9bf30401b8ac0fa41cec5392787a1fb916d42fa0f14ff8b80078b89246ab5bbdaae40b2dd67b77302571e3cb0803477e48ead4f
+  data.tar.gz: dbb7ac119a2d46c5150b8a274c89280582d69f64718849a7537d0a4b876f40c0b9a36c47fc3e2d6f27a244e12465d4ba372a3e4c87c7d0e1c738c0757cd672d5

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.29.0"
+		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.29.0
+  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-28 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