protocol-http 0.31.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 924ae96ed9d907e15583c52df242c08481c7740a677e6c3a594f9d76ce2aad6e
-  data.tar.gz: b7f82710d54ba3e2bb2ffb974a2e46d82c734f53d909ea391986bfde260ea16d
+  metadata.gz: 1bf929d8d011f9c79cf7b92bdf8f5eaefcd4faab288b555a7889f33a995daf2e
+  data.tar.gz: 4de5349ae1e3cee6fb4857dbac1c78ef7e44249e1adc4526674803d0524af8f1
 SHA512:
-  metadata.gz: 0ea73874b0712492e11a18d8b4d3339cf70604cf60c3b2da62d3cbd437a5af083dacee44dc222be71373abd726051ecf8cd6a063914cb96ad42ef54f35446ed5
-  data.tar.gz: 10f2982481609e45edd91c5b9a71bc7cac26957849151455359eb0ba9e55cff79688564f39b4611ea57de622296b1474e8c2d5190c7bbb1a9ea1a559366f6fa0
+  metadata.gz: b2214c233b4543e929f23ef59e8ffaed14f597c9762596ffd8afc8d9a1657fc6c50ace4dc1859a10033e2bba68e36d8f10a8486a056444676939d73352ed374f
+  data.tar.gz: 27d9318755a9a2027e21d144a361287adf9cc6f2990bcae4ce93cbd9767c125e6811a1d19c20cf2da5ec67f729132271c9e1744c6ea1c82a88c3fff795e71502

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

@@ -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

@@ -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

@@ -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,14 @@ module Protocol
 					end
 				end
 				
+				def stream?
+					true
+				end
+				
+				def call(stream)
+					IO.copy_stream(@file, stream, @remaining)
+				end
+				
 				def join
 					return "" if @remaining == 0
 					

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

@@ -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,9 +7,15 @@
 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.
 				def close(error = nil)
@@ -29,65 +35,46 @@ 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
-				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
-				
 				# 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
-					ensure
-						self.close($!)
+					while chunk = self.read
+						yield chunk
 					end
+				rescue => error
+					raise
+				ensure
+					self.close(error)
 				end
 				
 				# Read all remaining chunks into a single binary string using `#each`.
@@ -107,6 +94,35 @@ module Protocol
 					end
 				end
 				
+				def stream?
+					false
+				end
+				
+				# Write the body to 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.
+				#
+				# If the stream is not ready, it will be flushed after each chunk. Closes the stream when finished or if an error occurs.
+				#
+				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
+				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/streamable.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+require_relative 'readable'
+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.
+			class Streamable < Readable
+				class Closed < StandardError
+				end
+				
+				def initialize(block, input = nil)
+					@block = block
+					@input = input
+					@output = nil
+				end
+				
+				# Closing a stream indicates we are no longer interested in reading from it.
+				def close(error = nil)
+					if @input
+						@input.close
+						@input = nil
+					end
+					
+					if @output
+						@output.close(error)
+					end
+				end
+				
+				attr :block
+				
+				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)
+							end
+						end
+					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!"
+						end
+					end
+					
+					# Can be invoked by the block to close the stream.
+					def close(error = nil)
+						if from = @from
+							@from = nil
+							from.transfer(nil)
+						elsif @fiber
+							@fiber.raise(error || Closed)
+						end
+					end
+					
+					def read
+						raise RuntimeError, "Stream is already being read!" if @from
+						
+						@fiber&.transfer(Fiber.current)
+					end
+				end
+				
+				# Invokes the block in a fiber which yields chunks when they are available.
+				def read
+					@output ||= Output.new(@input, @block)
+					
+					return @output.read
+				end
+				
+				def stream?
+					true
+				end
+				
+				def call(stream)
+					raise "Streaming body has already been read!" if @output
+					
+					@block.call(stream)
+				rescue => error
+					raise
+				ensure
+					self.close(error)
+				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,103 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2018-2023, 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)
+					@queue = queue
+					
+					@length = length
+					
+					@count = 0
+					
+					@finished = false
+					
+					@closed = false
+					@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)
+					unless @closed
+						@queue.close
+						
+						@closed = true
+						@error = error
+					end
+					
+					super
+				end
+				
+				def closed?
+					@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
+					@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
+						raise(@error || Closed)
+					end
+					
+					@count += 1
+					@queue.push(chunk)
+				end
+				
+				alias << write
+				
+				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.31.0"
+		VERSION = "0.33.0"
 	end
 end

data/readme.md

@@ -22,6 +22,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.31.0
+  version: 0.33.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-05 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