protocol-http 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bf929d8d011f9c79cf7b92bdf8f5eaefcd4faab288b555a7889f33a995daf2e
-  data.tar.gz: 4de5349ae1e3cee6fb4857dbac1c78ef7e44249e1adc4526674803d0524af8f1
+  metadata.gz: cb1197435097557cab74b1b61b92fe0a15a938892dd07486ee9f9db06360decd
+  data.tar.gz: 78bcbbd73817b03ce63b55b2bbd4408afeaeaa127e3c19f9dfd5d6ddb120f05d
 SHA512:
-  metadata.gz: b2214c233b4543e929f23ef59e8ffaed14f597c9762596ffd8afc8d9a1657fc6c50ace4dc1859a10033e2bba68e36d8f10a8486a056444676939d73352ed374f
-  data.tar.gz: 27d9318755a9a2027e21d144a361287adf9cc6f2990bcae4ce93cbd9767c125e6811a1d19c20cf2da5ec67f729132271c9e1744c6ea1c82a88c3fff795e71502
+  metadata.gz: 34db4e5940f59773708692bc080706be457f9f41445b6858e01da474f0ba36aba31d8d8c2f3ccd329f2120f412d9c4bcc42c568c057db3e0cef816c83ab34db1
+  data.tar.gz: 23baab35d26b5b367fa556d4a302f81680b944fef07b2ca0a581fab7b36ac8320cb3c4a62cdc50f8cfd21efb408eee01e348c06b4c538a5cfbcf8cd6ce99b28f

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

@@ -56,6 +56,17 @@ module Protocol
 					self
 				end
 				
+				# Ensure that future reads return nil, but allow for rewinding.
+				def close(error = nil)
+					@index = @chunks.length
+				end
+				
+				def clear
+					@chunks.clear
+					@length = 0
+					@index = 0
+				end
+				
 				def length
 					@length ||= @chunks.inject(0) {|sum, chunk| sum + chunk.bytesize}
 				end
@@ -70,6 +81,8 @@ module Protocol
 				end
 				
 				def read
+					return nil unless @chunks
+					
 					if chunk = @chunks[@index]
 						@index += 1
 						
@@ -81,18 +94,26 @@ module Protocol
 					@chunks << chunk
 				end
 				
+				def close_write(error)
+					# Nothing to do.
+				end
+				
 				def rewindable?
-					true
+					@chunks != nil
 				end
 				
 				def rewind
+					return false unless @chunks
+					
 					@index = 0
 					
 					return true
 				end
 				
 				def inspect
-					"\#<#{self.class} #{@chunks.size} chunks, #{self.length} bytes>"
+					if @chunks
+						"\#<#{self.class} #{@chunks.size} chunks, #{self.length} bytes>"
+					end
 				end
 			end
 		end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'wrapper'
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
 require_relative 'wrapper'
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'readable'
 
@@ -68,13 +68,15 @@ module Protocol
 					end
 				end
 				
-				def stream?
-					true
-				end
+				# def stream?
+				# 	true
+				# end
 				
-				def call(stream)
-					IO.copy_stream(@file, stream, @remaining)
-				end
+				# def call(stream)
+				# 	IO.copy_stream(@file, stream, @remaining)
+				# ensure
+				# 	stream.close
+				# end
 				
 				def join
 					return "" if @remaining == 0

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require 'zlib'
 

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

@@ -17,7 +17,11 @@ module Protocol
 			#
 			# If you don't want to read from a stream, and instead want to close it immediately, you can call `close` on the body. If the body is already completely consumed, `close` will do nothing, but if there is still data to be read, it will cause the underlying stream to be reset (and possibly closed).
 			class Readable
-				# Close the stream immediately.
+				# 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.
+				#
+				# Invoking `#read` after `#close` will return `nil`.
 				def close(error = nil)
 				end
 				
@@ -68,13 +72,15 @@ module Protocol
 				def each
 					return to_enum unless block_given?
 					
-					while chunk = self.read
-						yield chunk
+					begin
+						while chunk = self.read
+							yield chunk
+						end
+					rescue => error
+						raise
+					ensure
+						self.close(error)
 					end
-				rescue => error
-					raise
-				ensure
-					self.close(error)
 				end
 				
 				# Read all remaining chunks into a single binary string using `#each`.
@@ -98,12 +104,14 @@ module Protocol
 					false
 				end
 				
-				# Write the body to the given stream.
+				# Invoke the body with the given stream.
 				#
-				# In some cases, the stream may also be readable, such as when hijacking an HTTP/1 connection. In that case, it may be acceptable to read and write to the stream directly.
+				# The default implementation simply writes each chunk to the stream. If the body is not ready, it will be flushed after each chunk. Closes the stream when finished or if an error occurs.
 				#
-				# If the stream is not ready, it will be flushed after each chunk. Closes the stream when finished or if an error occurs.
+				# Write the body to the given stream.
 				#
+				# @parameter stream [IO | Object] An `IO`-like object that responds to `#read`, `#write` and `#flush`.
+				# @returns [Boolean] Whether the ownership of the stream was transferred.
 				def call(stream)
 					self.each do |chunk|
 						stream.write(chunk)
@@ -113,6 +121,8 @@ module Protocol
 							stream.flush
 						end
 					end
+				ensure
+					stream.close
 				end
 				
 				# Read all remaining chunks into a buffered body and close the underlying input.

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

@@ -21,6 +21,7 @@ module Protocol
 					
 					# Will hold remaining data in `#read`.
 					@buffer = nil
+					
 					@closed = false
 					@closed_read = false
 				end
@@ -251,21 +252,22 @@ module Protocol
 				end
 				
 				# Close the input body.
-				def close_read
-					if @input
+				def close_read(error = nil)
+					if input = @input
+						@input = nil
 						@closed_read = true
 						@buffer = nil
 						
-						@input&.close
-						@input = nil
+						input.close(error)
 					end
 				end
 				
 				# Close the output body.
-				def close_write
-					if @output
-						@output&.close
+				def close_write(error = nil)
+					if output = @output
 						@output = nil
+						
+						output.close_write(error)
 					end
 				end
 				

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

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'readable'
+require_relative 'writable'
+
 require_relative 'stream'
 
 module Protocol
@@ -14,98 +16,137 @@ 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.
-			class Streamable < Readable
-				class Closed < StandardError
+			module Streamable
+				def self.new(*arguments)
+					if arguments.size == 1
+						DeferredBody.new(*arguments)
+					else
+						Body.new(*arguments)
+					end
+				end
+				
+				def self.request(&block)
+					DeferredBody.new(block)
 				end
 				
-				def initialize(block, input = nil)
-					@block = block
-					@input = input
-					@output = nil
+				def self.response(request, &block)
+					Body.new(block, request.body)
 				end
 				
-				# Closing a stream indicates we are no longer interested in reading from it.
-				def close(error = nil)
-					if @input
-						@input.close
-						@input = nil
+				class Output
+					def self.schedule(input, block)
+						self.new(input, block).tap(&:schedule)
+					end
+					
+					def initialize(input, block)
+						@output = Writable.new
+						@stream = Stream.new(input, @output)
+						@block = block
+					end
+					
+					def schedule
+						@fiber ||= Fiber.schedule do
+							@block.call(@stream)
+						end
 					end
 					
-					if @output
-						@output.close(error)
+					def read
+						@output.read
+					end
+					
+					def close(error = nil)
+						@output.close_write(error)
 					end
 				end
 				
-				attr :block
+				# Raised when a streaming body is consumed more than once.
+				class ConsumedError < StandardError
+				end
 				
-				class Output
-					def initialize(input, block)
-						stream = Stream.new(input, self)
-						
-						@from = nil
-						
-						@fiber = Fiber.new do |from|
-							@from = from
-							block.call(stream)
-						rescue Closed
-							# Ignore.
-						ensure
-							@fiber = nil
-							
-							# No more chunks will be generated:
-							if from = @from
-								@from = nil
-								from.transfer(nil)
+				class Body < Readable
+					def initialize(block, input = nil)
+						@block = block
+						@input = input
+						@output = nil
+					end
+					
+					def stream?
+						true
+					end
+					
+					# Invokes the block in a fiber which yields chunks when they are available.
+					def read
+						# We are reading chunk by chunk, allocate an output stream and execute the block to generate the chunks:
+						if @output.nil?
+							if @block.nil?
+								raise ConsumedError, "Streaming body has already been consumed!"
 							end
+							
+							@output = Output.schedule(@input, @block)
+							@block = nil
 						end
+						
+						@output.read
 					end
 					
-					# Can be invoked by the block to write to the stream.
-					def write(chunk)
-						if from = @from
-							@from = nil
-							@from = from.transfer(chunk)
-						else
-							raise RuntimeError, "Stream is not being read!"
+					# Invoke the block with the given stream.
+					#
+					# The block can read and write to the stream, and must close the stream when finishing.
+					def call(stream)
+						if @block.nil?
+							raise ConsumedError, "Streaming block has already been consumed!"
 						end
+						
+						block = @block
+						
+						@input = @output = @block = nil
+						
+						# Ownership of the stream is passed into the block, in other words, the block is responsible for closing the stream.
+						block.call(stream)
+					rescue => error
+						# If, for some reason, the block raises an error, we assume it may not have closed the stream, so we close it here:
+						stream.close
+						raise
 					end
 					
-					# Can be invoked by the block to close the stream.
+					# Closing a stream indicates we are no longer interested in reading from it.
 					def close(error = nil)
-						if from = @from
-							@from = nil
-							from.transfer(nil)
-						elsif @fiber
-							@fiber.raise(error || Closed)
+						if output = @output
+							@output = nil
+							# Closing the output here may take some time, as it may need to finish handling the stream:
+							output.close(error)
 						end
-					end
-					
-					def read
-						raise RuntimeError, "Stream is already being read!" if @from
 						
-						@fiber&.transfer(Fiber.current)
+						if input = @input
+							@input = nil
+							input.close(error)
+						end
 					end
 				end
 				
-				# Invokes the block in a fiber which yields chunks when they are available.
-				def read
-					@output ||= Output.new(@input, @block)
+				# A deferred body has an extra `stream` method which can be used to stream data into the body, as the response body won't be available until the request has been sent.
+				class DeferredBody < Body
+					def initialize(block)
+						super(block, Writable.new)
+					end
 					
-					return @output.read
-				end
-				
-				def stream?
-					true
-				end
-				
-				def call(stream)
-					raise "Streaming body has already been read!" if @output
+					# Closing a stream indicates we are no longer interested in reading from it, but in this case that does not mean that the output block is finished generating data.
+					def close(error = nil)
+						if error
+							super
+						end
+					end
 					
-					@block.call(stream)
-				rescue => error
-					raise
-				ensure
-					self.close(error)
+					# Stream the response body into the block's input.
+					def stream(body)
+						body&.each do |chunk|
+							@input.write(chunk)
+						end
+					rescue => error
+						raise
+					ensure
+						@input.close_write(error)
+					end
 				end
 			end
 		end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2024, by Samuel Williams.
 
 require_relative 'readable'
 
@@ -16,15 +16,9 @@ module Protocol
 				# @param [Integer] length The length of the response body if known.
 				# @param [Async::Queue] queue Specify a different queue implementation, e.g. `Async::LimitedQueue.new(8)` to enable back-pressure streaming.
 				def initialize(length = nil, queue: Thread::Queue.new)
-					@queue = queue
-					
 					@length = length
-					
+					@queue = queue
 					@count = 0
-					
-					@finished = false
-					
-					@closed = false
 					@error = nil
 				end
 				
@@ -34,18 +28,16 @@ module Protocol
 				
 				# Stop generating output; cause the next call to write to fail with the given error. Does not prevent existing chunks from being read. In other words, this indicates both that no more data will be or should be written to the body.
 				def close(error = nil)
-					unless @closed
-						@queue.close
-						
-						@closed = true
-						@error = error
-					end
+					@error ||= error
+					
+					@queue.clear
+					@queue.close
 					
 					super
 				end
 				
 				def closed?
-					@closed
+					@queue.closed?
 				end
 				
 				def ready?
@@ -59,22 +51,71 @@ module Protocol
 				
 				# Read the next available chunk.
 				def read
+					if @error
+						raise @error
+					end
+					
 					@queue.pop
 				end
 				
 				# Write a single chunk to the body. Signal completion by calling `#finish`.
 				def write(chunk)
-					# If the reader breaks, the writer will break.
-					# The inverse of this is less obvious (*)
-					if @closed
+					if @queue.closed?
 						raise(@error || Closed)
 					end
 					
-					@count += 1
 					@queue.push(chunk)
+					@count += 1
 				end
 				
-				alias << write
+				def close_write(error = nil)
+					@error ||= error
+					@queue.close
+				end
+				
+				class Output
+					def initialize(writable)
+						@writable = writable
+						@closed = false
+					end
+					
+					def closed?
+						@closed || @writable.closed?
+					end
+					
+					def write(chunk)
+						@writable.write(chunk)
+					end
+					
+					alias << write
+					
+					def close(error = nil)
+						@closed = true
+						
+						if error
+							@writable.close(error)
+						else
+							@writable.close_write
+						end
+					end
+				end
+				
+				# Create an output wrapper which can be used to write chunks to the body.
+				def output
+					output = Output.new(self)
+					
+					unless block_given?
+						return output
+					end
+					
+					begin
+						yield output
+					rescue => error
+						raise error
+					ensure
+						output.close(error)
+					end
+				end
 				
 				def inspect
 					"\#<#{self.class} #{@count} chunks written, #{status}>"

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.33.0"
+		VERSION = "0.34.0"
 	end
 end

data/readme.md

@@ -14,6 +14,8 @@ Provides abstractions for working with the HTTP protocol.
 
 Please see the [project documentation](https://socketry.github.io/protocol-http/) for more details.
 
+  - [Streaming](https://socketry.github.io/protocol-http/guides/streaming/index) - This guide gives an overview of how to implement streaming requests and responses.
+
   - [Getting Started](https://socketry.github.io/protocol-http/guides/getting-started/index) - This guide explains how to use `protocol-http` for building abstract HTTP interfaces.
 
   - [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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.33.0
+  version: 0.34.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -47,7 +47,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-09-05 00:00:00.000000000 Z
+date: 2024-09-10 00:00:00.000000000 Z
 dependencies: []
 description:
 email: