io-stream 0.13.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef7273d29f71bdc5f4bcc11b9ae175b6f77e8e554a950c298b646499bfc0b595
-  data.tar.gz: f3c65d0b5507081da4e7e5b9c5ef2a2fe70dcee885495116249ed5b9921dd407
+  metadata.gz: 62f5684554e47e754ddc99d25d193a8ef69b369dc8acc49ec75b0995d58e6720
+  data.tar.gz: 0f66daa91f71b6dfd98008eea2cd820d52ae4a87845b888e1eaffdfd45b28955
 SHA512:
-  metadata.gz: e3bc5163f033021ce9580a9c45d8d711a12558017bfd68118149838eef8807aadcf8d5e0b980479f6af7ef741b6034e85d118e08c73f832f19a1ea6b2313e22f
-  data.tar.gz: aab392c94675167955776438debb0f3439dcb87403e9ff75c688722be94b7e78be84e57b5eb32bfae3328a4ec66b3d122e8a4547018c5899b14328bf85fd3d99
+  metadata.gz: 0501cc4d95af72fc42dcd55c7a121c3070630f34ff922f3e65aaad2cb22c02c6d78150e82d277dfca6295354746c67663c200bc340341400677a6323321b7819
+  data.tar.gz: 6d6084eddbe9717ce8e899b5af4db52fdb377535341b0096fc340bf96116eed5a7a412c7409ba8849a92dd05c758166b2b1d4a05952aa99428b1daa5bc49cd38

data/lib/io/stream/buffered.rb

@@ -6,6 +6,7 @@
 require_relative "generic"
 require_relative "connection_reset_error"
 
+# Provides buffered IO streams with consistent read, write, and transport semantics.
 module IO::Stream
 	# A buffered stream implementation that wraps an underlying IO object to provide efficient buffered reading and writing.
 	class Buffered < Generic
@@ -104,6 +105,11 @@ module IO::Stream
 			return @io.write(buffer)
 		end
 		
+		# Attempts to read data from the underlying stream without blocking.
+		def sysread_nonblock(size, buffer)
+			return @io.read_nonblock(size, buffer, exception: false)
+		end
+		
 		# Reads data from the underlying stream as efficiently as possible.
 		def sysread(size, buffer)
 			# Come on Ruby, why couldn't this just return `nil`? EOF is not exceptional. Every file has one.

data/lib/io/stream/readable.rb

@@ -23,7 +23,7 @@ module IO::Stream
 	
 	# A module providing readable stream functionality.
 	#
-	# You must implement the `sysread` method to read data from the underlying IO.
+	# You must implement the `sysread` method to read data from the underlying IO. You may implement `sysread_nonblock` to support non-blocking partial peeks.
 	module Readable
 		ASYNC_SAFE = {
 			read: :readable,
@@ -31,6 +31,7 @@ module IO::Stream
 			read_exactly: :readable,
 			read_until: :readable,
 			peek: :readable,
+			peek_partial: :readable,
 			gets: :readable,
 			getc: :readable,
 			getbyte: :readable,
@@ -246,6 +247,10 @@ module IO::Stream
 		# @parameter size [Integer | Nil] The number of bytes to peek at. If nil, peek at all available data.
 		# @returns [String] The data in the buffer without consuming it.
 		def peek(size = nil)
+			if size == 0
+				return String.new(encoding: Encoding::BINARY)
+			end
+			
 			if size
 				until @finished or @read_buffer.bytesize >= size
 					# Compute the amount of data we need to read from the underlying stream:
@@ -265,6 +270,41 @@ module IO::Stream
 			return @read_buffer
 		end
 		
+		# Peek at data without consuming it, making at most one non-blocking read attempt.
+		#
+		# Any data read from the underlying stream is preserved in the read buffer. If
+		# the read would block or the stream is at EOF, this method returns `nil`.
+		#
+		# After this method returns `nil`, {readable?} indicates whether the read would
+		# block or EOF was observed.
+		#
+		# @parameter size [Integer] The maximum number of bytes to peek at.
+		# @returns [String | Nil] The immediately available data, or nil if no data can be read without blocking.
+		def peek_partial(size = @minimum_read_size)
+			if size == 0
+				return String.new(encoding: Encoding::BINARY)
+			end
+			
+			if @read_buffer.empty?
+				if @finished
+					return nil
+				end
+				
+				read_size = [size, @maximum_read_size].min
+				
+				result = sysread_nonblock(read_size, @read_buffer)
+				case result
+				when :wait_readable, :wait_writable
+					return nil
+				when nil
+					@finished = true
+					return nil
+				end
+			end
+			
+			return @read_buffer.byteslice(0, [size, @read_buffer.bytesize].min)
+		end
+		
 		# Read a line from the stream, similar to IO#gets.
 		# @parameter separator [String] The line separator to search for.
 		# @parameter limit [Integer | Nil] The maximum number of bytes to read.
@@ -360,6 +400,12 @@ module IO::Stream
 		
 		private
 		
+		# Attempts to read data from the underlying stream without blocking.
+		# Implementations may override this method when non-blocking reads are supported.
+		def sysread_nonblock(size, buffer)
+			return :wait_readable
+		end
+		
 		# Fills the buffer from the underlying stream.
 		def fill_read_buffer(size = @minimum_read_size)
 			# Limit the read size to avoid exceeding SSIZE_MAX and to manage memory usage.

data/lib/io/stream/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2023-2026, by Samuel Williams.
 
 module IO::Stream
-	VERSION = "0.13.2"
+	VERSION = "0.14.0"
 end

data/readme.md

@@ -22,6 +22,10 @@ Please see the [project documentation](https://socketry.github.io/io-stream/) fo
 
 Please see the [project releases](https://socketry.github.io/io-stream/releases/index) for all releases.
 
+### v0.14.0
+
+  - Add `IO::Stream::Readable#peek_partial` to peek through layered transports without blocking or consuming application data.
+
 ### v0.13.1
 
   - Set minimum Ruby verison to 3.3.6 to avoid hanging `close` issue in older Ruby versions.
@@ -65,10 +69,6 @@ Please see the [project releases](https://socketry.github.io/io-stream/releases/
   - Remove unused timeout shim functionality.
   - 100% documentation coverage.
 
-### v0.6.1
-
-  - Fix compatibility with Ruby v3.3.0 - v3.3.6 where broken `@io.close` could hang.
-
 ## See Also
 
   - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.14.0
+
+  - Add `IO::Stream::Readable#peek_partial` to peek through layered transports without blocking or consuming application data.
+
 ## v0.13.1
 
   - Set minimum Ruby verison to 3.3.6 to avoid hanging `close` issue in older Ruby versions.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-stream
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams