io-stream 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 259533ca29c9be8e0476777d9060a4aa6928fa856848396110b3f668628db636
+  data.tar.gz: ed074a9ff19c5f0f74223228d1bb9929ff7534f921c11e4adf34fe88c5f2824b
+SHA512:
+  metadata.gz: f90e4bca685926a8cc28b21b65ddceea17fd8d3ba25ccefd6daf9095403ef7446c71b9afdfe57367faccf2ee46635bcf939e14f8ac36e9ebc6b9ee55bdafaada
+  data.tar.gz: f7aaa56fb744df8cd057412083ad63c707165e3e1c404397dfa447f2135f7d11fef6d0b855cf88c23d28346ba96c320bc9566e7395520889d89ea7b63ea4fd1c

data/lib/io/buffered.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+unless IO.method_defined?(:buffered?)
+	class IO
+		def buffered?
+			return !self.sync
+		end
+		
+		def buffered=(value)
+			self.sync = !value
+		end
+	end
+end
+
+require 'socket'
+
+unless BasicSocket.method_defined?(:buffered?)
+	class BasicSocket
+		# Is it likely that the socket is still connected?
+		# May return false positive, but won't return false negative.
+		def buffered?
+			return false unless super
+			
+			case self.local_address.protocol
+			when IPPROTO_TCP
+				return !self.getsockopt(IPPROTO_TCP, TCP_NODELAY).bool
+			else
+				return true
+			end
+		end
+		
+		def buffered=(value)
+			super
+			
+			case self.local_address.socktype
+			when SOCK_STREAM
+				# When buffered is set to true, TCP_NODELAY shold be disabled.
+				self.setsockopt(IPPROTO_TCP, TCP_NODELAY, value ? 0 : 1)
+			end
+		rescue Errno::EINVAL
+			# On Darwin, sometimes occurs when the connection is not yet fully formed. Empirically, TCP_NODELAY is enabled despite this result.
+		rescue Errno::EOPNOTSUPP
+			# Some platforms may simply not support the operation.
+		end
+	end
+end
+
+require 'stringio'
+
+unless StringIO.method_defined?(:buffered?)
+	class StringIO
+		def buffered?
+			return !self.sync
+		end
+		
+		def buffered=(value)
+			self.sync = !value
+		end
+	end
+end

data/lib/io/readable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+class IO
+	unless method_defined?(:readable?)
+		def readable?
+			# Do not call `eof?` here as it is not concurrency-safe and it can block.
+			!closed?
+		end
+	end
+end
+
+require 'socket'
+
+class BasicSocket
+	unless method_defined?(:readable?)
+		def readable?
+			# If we can wait for the socket to become readable, we know that the socket may still be open.
+			result = self.recv_nonblock(1, MSG_PEEK, exception: false)
+			
+			# No data was available - newer Ruby can return nil instead of empty string:
+			return false if result.nil?
+			
+			# Either there was some data available, or we can wait to see if there is data avaialble.
+			return !result.empty? || result == :wait_readable
+		rescue Errno::ECONNRESET, IOError
+			# This might be thrown by recv_nonblock.
+			return false
+		end
+	end
+end
+
+require 'stringio'
+
+class StringIO
+	unless method_defined?(:readable?)
+		def readable?
+			!eof?
+		end
+	end
+end
+
+require 'openssl'
+
+class OpenSSL::SSL::SSLSocket
+	unless method_defined?(:readable?)
+		def readable?
+			to_io.readable?
+		end
+	end
+end

data/lib/io/stream/buffered_stream.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+require_relative 'string_buffer'
+
+require_relative '../buffered'
+require_relative '../readable'
+
+module IO::Stream
+	# The default block size for IO buffers. Defaults to 64KB (typical pipe buffer size).
+	BLOCK_SIZE = ENV.fetch('IO_STREAM_BLOCK_SIZE', 1024*64).to_i
+
+	# The maximum read size when appending to IO buffers. Defaults to 8MB.
+	MAXIMUM_READ_SIZE = ENV.fetch('IO_STREAM_MAXIMUM_READ_SIZE', BLOCK_SIZE * 128).to_i
+	
+	class BufferedStream
+		def self.open(path, mode = "r+", **options)
+			stream = self.new(File.open(path, mode), **options)
+			
+			return stream unless block_given?
+			
+			begin
+				yield stream
+			ensure
+				stream.close
+			end
+		end
+		
+		def self.wrap(io, **options)
+			if io.respond_to?(:buffered=)
+				io.buffered = false
+			end
+			
+			self.new(io, **options)
+		end
+		
+		def initialize(io, block_size: BLOCK_SIZE, maximum_read_size: MAXIMUM_READ_SIZE)
+			@io = io
+			@eof = false
+			
+			@writing = Thread::Mutex.new
+			
+			@block_size = block_size
+			@maximum_read_size = maximum_read_size
+			
+			@read_buffer = StringBuffer.new
+			@write_buffer = StringBuffer.new
+			@drain_buffer = StringBuffer.new
+			
+			# Used as destination buffer for underlying reads.
+			@input_buffer = StringBuffer.new
+		end
+		
+		attr :io
+		
+		attr :block_size
+		
+		# Reads `size` bytes from the stream. If size is not specified, read until end of file.
+		def read(size = nil)
+			return String.new(encoding: Encoding::BINARY) if size == 0
+			
+			if size
+				until @eof or @read_buffer.bytesize >= size
+					# Compute the amount of data we need to read from the underlying stream:
+					read_size = size - @read_buffer.bytesize
+					
+					# Don't read less than @block_size to avoid lots of small reads:
+					fill_read_buffer(read_size > @block_size ? read_size : @block_size)
+				end
+			else
+				until @eof
+					fill_read_buffer
+				end
+			end
+			
+			return consume_read_buffer(size)
+		end
+		
+		# Read at most `size` bytes from the stream. Will avoid reading from the underlying stream if possible.
+		def read_partial(size = nil)
+			return String.new(encoding: Encoding::BINARY) if size == 0
+		
+			if !@eof and @read_buffer.empty?
+				fill_read_buffer
+			end
+			
+			return consume_read_buffer(size)
+		end
+		
+		def read_exactly(size, exception: EOFError)
+			if buffer = read(size)
+				if buffer.bytesize != size
+					raise exception, "could not read enough data"
+				end
+				
+				return buffer
+			end
+			
+			raise exception, "encountered eof while reading data"
+		end
+		
+		# This is a compatibility shim for existing code:
+		def readpartial(size = nil)
+			read_partial(size) or raise EOFError, "Encountered eof while reading data!"
+		end
+		
+		# Efficiently read data from the stream until encountering pattern.
+		# @param pattern [String] The pattern to match.
+		# @return [String] The contents of the stream up until the pattern, which is consumed but not returned.
+		def read_until(pattern, offset = 0, chomp: true)
+			# We don't want to split on the pattern, so we subtract the size of the pattern.
+			split_offset = pattern.bytesize - 1
+			
+			until index = @read_buffer.index(pattern, offset)
+				offset = @read_buffer.bytesize - split_offset
+				
+				offset = 0 if offset < 0
+				
+				return unless fill_read_buffer
+			end
+			
+			@read_buffer.freeze
+			matched = @read_buffer.byteslice(0, index+(chomp ? 0 : pattern.bytesize))
+			@read_buffer = @read_buffer.byteslice(index+pattern.bytesize, @read_buffer.bytesize)
+			
+			return matched
+		end
+		
+		def peek(size = nil)
+			if size
+				until @eof or @read_buffer.bytesize >= size
+					# Compute the amount of data we need to read from the underlying stream:
+					read_size = size - @read_buffer.bytesize
+					
+					# Don't read less than @block_size to avoid lots of small reads:
+					fill_read_buffer(read_size > @block_size ? read_size : @block_size)
+				end
+				return @read_buffer[..([size, @read_buffer.size].min - 1)]
+			end
+			until (block_given? && yield(@read_buffer)) or @eof
+				fill_read_buffer
+			end
+			return @read_buffer
+		end
+		
+		def gets(separator = $/, **options)
+			read_until(separator, **options)
+		end
+		
+		# Flushes buffered data to the stream.
+		def flush
+			return if @write_buffer.empty?
+			
+			@writing.synchronize do
+				# Flip the write buffer and drain buffer:
+				@write_buffer, @drain_buffer = @drain_buffer, @write_buffer
+				
+				begin
+					@io.syswrite(@drain_buffer)
+				ensure
+					# If the write operation fails, we still need to clear this buffer, and the data is essentially lost.
+					@drain_buffer.clear
+				end
+			end
+		end
+		
+		# Writes `string` to the buffer. When the buffer is full or #sync is true the
+		# buffer is flushed to the underlying `io`.
+		# @param string the string to write to the buffer.
+		# @return the number of bytes appended to the buffer.
+		def write(string)
+			@write_buffer << string
+			
+			if @write_buffer.bytesize >= @block_size
+				flush
+			end
+			
+			return string.bytesize
+		end
+		
+		# Writes `string` to the stream and returns self.
+		def <<(string)
+			write(string)
+			
+			return self
+		end
+		
+		def puts(*arguments, separator: $/)
+			arguments.each do |argument|
+				@write_buffer << argument << separator
+			end
+			
+			flush
+		end
+		
+		def connected?
+			@io.connected?
+		end
+		
+		def closed?
+			@io.closed?
+		end
+		
+		def close_read
+			@io.close_read
+		end
+		
+		def close_write
+			flush
+		ensure
+			@io.close_write
+		end
+		
+		# Best effort to flush any unwritten data, and then close the underling IO.
+		def close
+			return if @io.closed?
+			
+			begin
+				flush
+			rescue
+				# We really can't do anything here unless we want #close to raise exceptions.
+			ensure
+				@io.close
+			end
+		end
+		
+		# Determins if the stream has consumed all available data. May block if the stream is not readable.
+		# See {readable?} for a non-blocking alternative.
+		#
+		# @returns [Boolean] If the stream is at file which means there is no more data to be read.
+		def eof?
+			if !@read_buffer.empty?
+				return false
+			elsif @eof
+				return true
+			else
+				return !self.fill_read_buffer
+			end
+		end
+		
+		def eof!
+			@read_buffer.clear
+			@eof = true
+			
+			raise EOFError
+		end
+		
+		# Whether there is a chance that a read operation will succeed or not.
+		# @returns [Boolean] If the stream is readable, i.e. a `read` operation has a chance of success.
+		def readable?
+			# If we are at the end of the file, we can't read any more data:
+			if @eof
+				return false
+			end
+			
+			# If the read buffer is not empty, we can read more data:
+			if !@read_buffer.empty?
+				return true
+			end
+			
+			# If the underlying stream is readable, we can read more data:
+			return @io.readable?
+		end
+		
+		private
+		
+		# 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.
+			@io.sysread(size, buffer)
+		rescue EOFError
+			return false
+		end
+		
+		# Fills the buffer from the underlying stream.
+		def fill_read_buffer(size = @block_size)
+			# We impose a limit because the underlying `read` system call can fail if we request too much data in one go.
+			if size > @maximum_read_size
+				size = @maximum_read_size
+			end
+			
+			# This effectively ties the input and output stream together.
+			flush
+			
+			if @read_buffer.empty?
+				if sysread(size, @read_buffer)
+					# Console.logger.debug(self, name: "read") {@read_buffer.inspect}
+					return true
+				end
+			else
+				if chunk = sysread(size, @input_buffer)
+					@read_buffer << chunk
+					# Console.logger.debug(self, name: "read") {@read_buffer.inspect}
+					
+					return true
+				end
+			end
+			
+			# else for both cases above:
+			@eof = true
+			return false
+		end
+		
+		# Consumes at most `size` bytes from the buffer.
+		# @param size [Integer|nil] The amount of data to consume. If nil, consume entire buffer.
+		def consume_read_buffer(size = nil)
+			# If we are at eof, and the read buffer is empty, we can't consume anything.
+			return nil if @eof && @read_buffer.empty?
+			
+			result = nil
+			
+			if size.nil? or size >= @read_buffer.bytesize
+				# Consume the entire read buffer:
+				result = @read_buffer
+				@read_buffer = StringBuffer.new
+			else
+				# This approach uses more memory.
+				# result = @read_buffer.slice!(0, size)
+				
+				# We know that we are not going to reuse the original buffer.
+				# But byteslice will generate a hidden copy. So let's freeze it first:
+				@read_buffer.freeze
+				
+				result = @read_buffer.byteslice(0, size)
+				@read_buffer = @read_buffer.byteslice(size, @read_buffer.bytesize)
+			end
+			
+			return result
+		end
+	end
+end

data/lib/io/stream/string_buffer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+module IO::Stream
+	class StringBuffer < String
+		BINARY = Encoding::BINARY
+		
+		def initialize
+			super
+			
+			force_encoding(BINARY)
+		end
+		
+		def << string
+			if string.encoding == BINARY
+				super(string)
+			else
+				super(string.b)
+			end
+			
+			return self
+		end
+		
+		alias concat <<
+	end
+end

data/lib/io/stream/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+module IO::Stream
+	VERSION = "0.0.1"
+end

data/lib/io/stream.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023-2024, by Samuel Williams.
+
+require_relative 'stream/version'
+require_relative 'stream/buffered_stream'
+
+class IO
+	module Stream
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2023-2024, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,31 @@
+# IO::Stream
+
+Provide a buffered stream implementation for Ruby, independent of the underlying IO.
+
+[![Development Status](https://github.com/socketry/io-stream/workflows/Test/badge.svg)](https://github.com/socketry/io-stream/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/io-stream) for more details.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+
+### Contributor Covenant
+
+This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+
+## See Also
+
+  - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: io-stream
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+autorequire:
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 2024-04-22 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/io/buffered.rb
+- lib/io/readable.rb
+- lib/io/stream.rb
+- lib/io/stream/buffered_stream.rb
+- lib/io/stream/string_buffer.rb
+- lib/io/stream/version.rb
+- license.md
+- readme.md
+homepage: https://github.com/socketry/io-stream
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/io-stream
+  source_code_uri: https://github.com/socketry/io-stream.git
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Provides a generic stream wrapper for IO instances.
+test_files: []

metadata.gz.sig

@@ -0,0 +1 @@
+��f֩�����P�E�-z˶�oQ%�/*$(��Id��߄3$Jx�V�(;�$ewJ�x:��x�?︊w�����h����E���8�(��[�^}�u�ΙL�HZ1���!�g�t��z`�n��"�z�C��g��j=�4��L^/�NF�����pD�f�!���Y\�"٢q�s�ڀ4v[�|؂�~�m��[�0�+�`Y����هiV�V]ҽ
�nT1�ۻ��e���ɓNX��C�P��&��nYJ�`q��b���	U��{6�ӳ'*=�}� =��5[��\�NGHΦ�f>���y2y�U�c���X�:��%2Zχ���e�
݅���N������ĪΨ3�+��˥6R˽p�Oܸ,•�t����