protocol-http 0.32.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0e3d21463ec1b9dc0e08f2215f51135dc40342b5d922d4d827f2e43bbd0cc19
-  data.tar.gz: b6372b9064511569270558da4fc43dc792a5fe11d56caad820ba52cc997bcba1
+  metadata.gz: cb1197435097557cab74b1b61b92fe0a15a938892dd07486ee9f9db06360decd
+  data.tar.gz: 78bcbbd73817b03ce63b55b2bbd4408afeaeaa127e3c19f9dfd5d6ddb120f05d
 SHA512:
-  metadata.gz: 0d26f9ee12048761f8a921f6f9d9b921a3baae9f4d10a00dae7800a4d1549da4b86c51cf9dd7b699e6e862273bd76528ea77401ad92f79367e141d3d45307798
-  data.tar.gz: f8fe391ecdcb104fc5886cf6f2e1ad86a5f9599df6a532218201623188972f0b6249ff75c72663afe172677feb14d111b70a419cced7ad4fe3f6fcd4abf58d3d
+  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/completable.rb

@@ -32,15 +32,6 @@ module Protocol
 					false
 				end
 				
-				def finish
-					super.tap do
-						if @callback
-							@callback.call
-							@callback = nil
-						end
-					end
-				end
-				
 				def close(error = nil)
 					super.tap do
 						if @callback

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'
 
@@ -62,12 +62,6 @@ module Protocol
 					self.new(body, Zlib::Deflate.new(level, window_size))
 				end
 				
-				def stream?
-					# We might want to revisit this design choice.
-					# We could wrap the streaming body in a Deflate stream, but that would require an extra stream wrapper which we don't have right now. See also `Digestable#stream?`.
-					false
-				end
-				
 				def read
 					return if @stream.finished?
 					

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'
 
@@ -38,10 +38,6 @@ module Protocol
 					end
 				end
 				
-				def stream?
-					false
-				end
-				
 				def read
 					if chunk = super
 						@digest.update(chunk)

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'
 
@@ -56,10 +56,6 @@ module Protocol
 					@remaining = @length
 				end
 				
-				def stream?
-					false
-				end
-				
 				def read
 					if @remaining > 0
 						amount = [@remaining, @block_size].min
@@ -72,6 +68,16 @@ module Protocol
 					end
 				end
 				
+				# def stream?
+				# 	true
+				# 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'
 
@@ -15,10 +15,6 @@ module Protocol
 					self.new(body, Zlib::Inflate.new(encoding))
 				end
 				
-				def stream?
-					false
-				end
-				
 				def read
 					return if @stream.finished?
 					

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

@@ -7,11 +7,21 @@
 module Protocol
 	module HTTP
 		module Body
-			# An interface for reading data from a body.
+			# Represents a readable input streams.
 			#
 			# Typically, you'd override `#read` to return chunks of data.
+			#
+			# I n general, you read chunks of data from a body until it is empty and returns `nil`. Upon reading `nil`, the body is considered consumed and should not be read from again.
+			#
+			# Reading can also fail, for example if the body represents a streaming upload, and the connection is lost. In this case, the body will raise some kind of error.
+			#
+			# 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
 				
@@ -29,62 +39,47 @@ module Protocol
 					false
 				end
 				
+				# Whether the stream can be rewound using {rewind}.
 				def rewindable?
 					false
 				end
 				
+				# Rewind the stream to the beginning.
+				# @returns [Boolean] Whether the stream was successfully rewound.
 				def rewind
 					false
 				end
 				
+				# The total length of the body, if known.
+				# @returns [Integer | Nil] The total length of the body, or `nil` if the length is unknown.
 				def length
 					nil
 				end
 				
 				# Read the next available chunk.
 				# @returns [String | Nil] The chunk of data, or `nil` if the stream has finished.
+				# @raises [StandardError] If an error occurs while reading.
 				def read
 					nil
 				end
 				
-				# Should the internal mechanism prefer to use {call}?
-				# @returns [Boolean]
-				def stream?
-					false
-				end
-				
-				# Write the body to the given stream.
-				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
-				end
-				
-				# Read all remaining chunks into a buffered body and close the underlying input.
-				# @returns [Buffered] The buffered body.
-				def finish
-					# Internally, this invokes `self.each` which then invokes `self.close`.
-					Buffered.read(self)
-				end
-				
 				# Enumerate all chunks until finished, then invoke `#close`.
 				#
+				# Closes the stream when finished or if an error occurs.
+				#
 				# @yields {|chunk| ...} The block to call with each chunk of data.
 				# 	@parameter chunk [String | Nil] The chunk of data, or `nil` if the stream has finished.
 				def each
-					return to_enum(:each) unless block_given?
+					return to_enum unless block_given?
 					
 					begin
 						while chunk = self.read
 							yield chunk
 						end
+					rescue => error
+						raise
 					ensure
-						self.close($!)
+						self.close(error)
 					end
 				end
 				
@@ -105,6 +100,39 @@ module Protocol
 					end
 				end
 				
+				def stream?
+					false
+				end
+				
+				# Invoke the body with the given stream.
+				#
+				# 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.
+				#
+				# 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)
+						
+						# Flush the stream unless we are immediately expecting more data:
+						unless self.ready?
+							stream.flush
+						end
+					end
+				ensure
+					stream.close
+				end
+				
+				# Read all remaining chunks into a buffered body and close the underlying input.
+				#
+				# @returns [Buffered] The buffered body.
+				def finish
+					# Internally, this invokes `self.each` which then invokes `self.close`.
+					Buffered.read(self)
+				end
+				
 				def as_json(...)
 					{
 						class: self.class.name,

data/lib/protocol/http/body/rewindable.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'
 require_relative 'buffered'
@@ -43,10 +43,6 @@ module Protocol
 					Buffered.new(@chunks)
 				end
 				
-				def stream?
-					false
-				end
-				
 				def read
 					if @index < @chunks.size
 						chunk = @chunks[@index]

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2019-2024, by Samuel Williams.
+
+require_relative 'readable'
+require_relative 'writable'
+
+require_relative 'stream'
+
+module Protocol
+	module HTTP
+		module Body
+			# A body that invokes a block that can read and write to a stream.
+			#
+			# 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.
+			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 self.response(request, &block)
+					Body.new(block, request.body)
+				end
+				
+				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
+					
+					def read
+						@output.read
+					end
+					
+					def close(error = nil)
+						@output.close_write(error)
+					end
+				end
+				
+				# Raised when a streaming body is consumed more than once.
+				class ConsumedError < StandardError
+				end
+				
+				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
+					
+					# 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
+					
+					# Closing a stream indicates we are no longer interested in reading from it.
+					def close(error = nil)
+						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
+						
+						if input = @input
+							@input = nil
+							input.close(error)
+						end
+					end
+				end
+				
+				# 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
+					
+					# 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
+					
+					# 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
+	end
+end

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

@@ -27,15 +27,11 @@ module Protocol
 				# The wrapped body.
 				attr :body
 				
-				# Buffer any remaining body.
-				def finish
-					@body.finish
-				end
-				
 				def close(error = nil)
 					@body.close(error)
 					
-					super
+					# It's a no-op:
+					# super
 				end
 				
 				def empty?
@@ -77,14 +73,6 @@ module Protocol
 				def inspect
 					@body.inspect
 				end
-				
-				def stream?
-					@body.stream?
-				end
-				
-				def call(stream)
-					@body.call(stream)
-				end
 			end
 		end
 	end

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative 'readable'
+
+module Protocol
+	module HTTP
+		module Body
+			# A dynamic body which you can write to and read from.
+			class Writable < Readable
+				class Closed < StandardError
+				end
+				
+				# @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)
+					@length = length
+					@queue = queue
+					@count = 0
+					@error = nil
+				end
+				
+				def length
+					@length
+				end
+				
+				# 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)
+					@error ||= error
+					
+					@queue.clear
+					@queue.close
+					
+					super
+				end
+				
+				def closed?
+					@queue.closed?
+				end
+				
+				def ready?
+					!@queue.empty? || @queue.closed?
+				end
+				
+				# Has the producer called #finish and has the reader consumed the nil token?
+				def empty?
+					@queue.empty? && @queue.closed?
+				end
+				
+				# 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 @queue.closed?
+						raise(@error || Closed)
+					end
+					
+					@queue.push(chunk)
+					@count += 1
+				end
+				
+				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}>"
+				end
+				
+				private
+				
+				def status
+					if @queue.empty?
+						if @queue.closed?
+							'closed'
+						else
+							'waiting'
+						end
+					else
+						if @queue.closed?
+							'closing'
+						else
+							'ready'
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.32.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.
@@ -22,6 +24,11 @@ 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.33.0
+
+  - Clarify behaviour of streaming bodies and copy `Protocol::Rack::Body::Streaming` to `Protocol::HTTP::Body::Streamable`.
+  - Copy `Async::HTTP::Body::Writable` to `Protocol::HTTP::Body::Writable`.
+
 ### v0.31.0
 
   - Ensure chunks are flushed if required, when streaming.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.33.0
+
+  - Clarify behaviour of streaming bodies and copy `Protocol::Rack::Body::Streaming` to `Protocol::HTTP::Body::Streamable`.
+  - Copy `Async::HTTP::Body::Writable` to `Protocol::HTTP::Body::Writable`.
+
 ## v0.31.0
 
   - Ensure chunks are flushed if required, when streaming.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.32.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-03 00:00:00.000000000 Z
+date: 2024-09-10 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -68,7 +68,9 @@ files:
 - lib/protocol/http/body/reader.rb
 - lib/protocol/http/body/rewindable.rb
 - lib/protocol/http/body/stream.rb
+- lib/protocol/http/body/streamable.rb
 - lib/protocol/http/body/wrapper.rb
+- lib/protocol/http/body/writable.rb
 - lib/protocol/http/content_encoding.rb
 - lib/protocol/http/cookie.rb
 - lib/protocol/http/error.rb

metadata.gz.sig

@@ -1 +1 @@
-��gEEs|��s�ʍ8�@6��*�������`��lo���ï��W~E��E	�|q ��u����(j�o��	r�;��*�A���Yώ�ts��1U_ģ���*��M#�ˊ��)���ČS`�D���<ʱxe�26_��/��C�|\OA��6/oH�����L�h1��������;7������B
��H)�5����Q�o�C�֠�`!a�:��2	�y>$��q��•���;��T�f�wlH^� �n�f�O��E6)3)�ѿƆJ���ˉ�ji���6��/�w�Av\){���%����#�P��R��M�Lݢ�d�|��2���?����H�Pf�Lx�,��������B��d��Vd�y�@��j�(�=
+ik� �ܨ�9"Z�L�����A�NA�J���ƾM��b����|(U�U�Lj�%�c��o�o���j+�V����T@� f2I�w���C�4�a~�ф���1�S�>�_���{��U������Cw��4�+�>�!��g����MK/�h"��H