protocol-http 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5839d2adb8415083224423beb2d5a3c0a50e22090a75424276e1a0939cc800a
-  data.tar.gz: 0517ecffe3b1f6c486b1cba2b5cbf4b3b7a8daf2cb11469b73d0d61cb5492cb1
+  metadata.gz: 924ae96ed9d907e15583c52df242c08481c7740a677e6c3a594f9d76ce2aad6e
+  data.tar.gz: b7f82710d54ba3e2bb2ffb974a2e46d82c734f53d909ea391986bfde260ea16d
 SHA512:
-  metadata.gz: 5fe865bc6ae53bfbd34ca9e43c6c38d2dcb3874b0655b1960936960b690cfefc0203ecde64ea7ea3af17a8a1093382d98f419e5d88b24708af99ef210a282e7e
-  data.tar.gz: 5c576ba8d79c0c6d21022d224b936f307640e2a785685cb82ec2eb0da588fcc8cbb215d2b7a05572ab91274978acc1f3a39edc0dfb5946fbef32dafa51389296
+  metadata.gz: 0ea73874b0712492e11a18d8b4d3339cf70604cf60c3b2da62d3cbd437a5af083dacee44dc222be71373abd726051ecf8cd6a063914cb96ad42ef54f35446ed5
+  data.tar.gz: 10f2982481609e45edd91c5b9a71bc7cac26957849151455359eb0ba9e55cff79688564f39b4611ea57de622296b1474e8c2d5190c7bbb1a9ea1a559366f6fa0

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

@@ -57,6 +57,11 @@ module Protocol
 				def call(stream)
 					while chunk = self.read
 						stream.write(chunk)
+						
+						# Flush the stream unless we are immediately expecting more data:
+						unless self.ready?
+							stream.flush
+						end
 					end
 				ensure
 					stream.close

data/lib/protocol/http/methods.rb

@@ -69,10 +69,10 @@ module Protocol
 				end
 			end
 			
-			self.each do |name, value|
-				define_method(name) do |location, headers = nil, body = nil|
+			self.each do |name, method|
+				define_method(name) do |location, *arguments, **options|
 					self.call(
-						Request[value, location.to_s, Headers[headers], body]
+						Request[method, 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.31.0"
 	end
 end

data/readme.md

@@ -18,6 +18,29 @@ 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.
+
+### v0.31.0
+
+  - Ensure chunks are flushed if required, when streaming.
+
+### v0.30.0
+
+  - [`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 +58,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,44 @@
+# Releases
+
+## v0.31.0
+
+  - Ensure chunks are flushed if required, when streaming.
+
+## v0.30.0
+
+### `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.31.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-09-03 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