io-stream 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa0f71cc4addc72776d1dbc02c14d0edb79fc0ae250aebb7f0d4924f6b251701
-  data.tar.gz: b5f6ec1328debef8a9b9f9d8593f8a929504e5f0cc170cb780fec41a75ac38f2
+  metadata.gz: 19adcce8b9c2b4ab09e119675d2df7f030bb2a25b38774701e120bc8a75e2275
+  data.tar.gz: 942defa1b08a973b860d20d84a411317433f04eb8361c32c9b1b87f7bed16686
 SHA512:
-  metadata.gz: bd297845e8fdcabd8879baa92e46908129d585a378bf982a1e6f051d67748d216aa7435cbd391bebf2ae364838893c372666a1c10d5de36fcef4e91884377cd1
-  data.tar.gz: 857c75d7a920b8f4b6dbcda4746ae41e059eb936cda6f1ea347191843996e00af4a87d4f6e04b0be219c1b4199f59d9ccb3b1114a15619f131186aba68b833e5
+  metadata.gz: 7971599b56a27229f68d57b1907ca008c41041e38eb02285accd9f5d149ed5aa177d2e3eb9a1ea947dc8bab7d72ba8ba83ae59a53790d978d23c082d243d2789
+  data.tar.gz: 43c37664380b989b04183a033184d5b7f2443c83160e88d2edd6628edbbe5192ca3ba2de876560496622be0335882025b86ab9e13722e3eeb0906b541414ec6a

data/context/getting-started.md

@@ -0,0 +1,145 @@
+# Getting Started
+
+This guide explains how to use `io-stream` to add efficient buffering to Ruby IO objects.
+
+## Overview
+
+`io-stream` provides a buffered stream wrapper for any IO-like object in Ruby. It wraps standard Ruby IO instances (files, sockets, pipes) and adds buffering for both reading and writing operations, significantly improving performance for applications that perform many small reads or writes.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add io-stream
+~~~
+
+## Core Concepts
+
+### Buffered Streams
+
+`io-stream` provides buffering through the {IO::Stream::Buffered} class, which wraps any IO object. Buffering reduces the number of system calls by accumulating data in memory before actually reading from or writing to the underlying IO.
+
+### Read and Write Buffers
+
+The stream maintains separate buffers for reading and writing:
+
+- **Read buffer**: Accumulates data from the underlying IO, allowing multiple small reads without system calls
+- **Write buffer**: Accumulates data to write, flushing to the underlying IO only when the buffer is full or explicitly flushed
+
+## Usage
+
+### Wrapping an IO Object
+
+You can wrap any IO-like object using {IO::Stream}:
+
+~~~ ruby
+require 'io/stream'
+
+# Wrap a file
+file = File.open("data.txt", "w+")
+stream = IO::Stream(file)
+
+# Wrap a socket
+require 'socket'
+socket = TCPSocket.new("example.com", 80)
+stream = IO::Stream(socket)
+~~~
+
+### Opening Files Directly
+
+You can also open files directly as buffered streams:
+
+~~~ ruby
+require 'io/stream'
+
+# Open a file for reading
+stream = IO::Stream::Buffered.open("data.txt", "r")
+data = stream.read
+stream.close
+
+# Open with a block (auto-closes)
+IO::Stream::Buffered.open("data.txt", "w") do |stream|
+	stream.write("Hello, World!")
+	stream.flush
+end
+~~~
+
+### Reading Data
+
+The {IO::Stream::Readable} module provides various methods for reading:
+
+~~~ ruby
+require 'io/stream'
+
+IO::Stream::Buffered.open("data.txt", "r") do |stream|
+	# Read entire stream
+	content = stream.read
+	
+	# Read specific number of bytes
+	chunk = stream.read(1024)
+	
+	# Read a line
+	line = stream.gets
+	
+	# Read all lines
+	lines = stream.readlines
+	
+	# Check for end of stream
+	if stream.eof?
+		puts "Reached end of file"
+	end
+end
+~~~
+
+### Writing Data
+
+The {IO::Stream::Writable} module provides methods for writing:
+
+~~~ ruby
+require 'io/stream'
+
+IO::Stream::Buffered.open("output.txt", "w") do |stream|
+	# Write data (buffered)
+	stream.write("Hello, ")
+	stream.write("World!")
+	
+	# Write with automatic newline
+	stream.puts("This is a line")
+	
+	# Flush buffer to ensure data is written
+	stream.flush
+end
+~~~
+
+## Important Behaviors
+
+### Automatic Flushing
+
+The write buffer automatically flushes when:
+
+- The buffer size reaches the minimum write size (default: 64KB).
+- You call {IO::Stream::Writable#puts} (always flushes immediately).
+- You call {IO::Stream::Writable#flush} explicitly.
+- The stream is closed.
+
+### Manual Flushing
+
+For applications that need precise control over when data is written:
+
+~~~ ruby
+stream.write("Important data")
+stream.flush  # Ensure data is written immediately
+~~~
+
+### Buffer Sizes
+
+You can customize buffer sizes when creating streams:
+
+~~~ ruby
+# Smaller buffer for interactive applications
+stream = IO::Stream::Buffered.new(io, minimum_write_size: 4096)
+
+# Larger buffer for bulk operations
+stream = IO::Stream::Buffered.new(io, minimum_write_size: 256 * 1024)
+~~~

data/context/high-performance-io.md

@@ -0,0 +1,225 @@
+# High Performance IO
+
+This guide explains how to achieve optimal performance when using `io-stream` by understanding and controlling flush behavior.
+
+## Overview
+
+The key to high-performance IO with `io-stream` is understanding when and how to flush your write buffer. Improper flush timing can significantly impact throughput, latency, and CPU usage. This guide helps you choose the right buffering strategy for your application.
+
+## Why Buffering Matters
+
+Every write to an underlying IO object (file, socket, pipe) involves a system call, which has overhead:
+
+- **Context switching**: Transferring control between userspace and kernel space.
+- **System call overhead**: The cost of invoking kernel functions.
+- **Network packet overhead**: For sockets, each small write may trigger a separate packet.
+
+Buffering solves this by accumulating data in memory and performing larger, less frequent writes. However, buffering introduces latency - data sits in memory until flushed.
+
+Use buffering when you need:
+- **High throughput**: Maximize data transfer rate for bulk operations.
+- **Reduced CPU usage**: Minimize system call overhead when writing many small pieces.
+- **Efficient network utilization**: Avoid sending many tiny packets.
+
+## The Flush/Throughput Tradeoff
+
+There's a fundamental tradeoff between responsiveness and throughput:
+
+```mermaid
+graph LR
+    A[Immediate Flush] -->|Low Latency| B[Responsive]
+    A -->|Many System Calls| C[Lower Throughput]
+    D[Delayed Flush] -->|Higher Latency| E[Buffered]
+    D -->|Fewer System Calls| F[Higher Throughput]
+```
+
+**Immediate flushing** (after every write):
+- ✅ Data is sent immediately - low latency.
+- ✅ Simple mental model - predictable behavior.
+- ❌ High system call overhead.
+- ❌ Lower maximum throughput.
+- ❌ More CPU usage.
+- ❌ Network inefficiency (many small packets).
+
+**Buffered flushing** (accumulate before sending):
+- ✅ Fewer system calls - higher throughput.
+- ✅ Better CPU efficiency.
+- ✅ More efficient network packet utilization.
+- ❌ Data is delayed - higher latency.
+- ❌ Requires careful flush management.
+
+## Automatic Flush Behavior
+
+`io-stream` automatically flushes in these situations:
+
+~~~ ruby
+# 1. Buffer reaches minimum_write_size (default: 64KB)
+stream.write("x" * 65536)  # Automatically flushes
+
+# 2. Using puts() always flushes
+stream.puts("This is flushed immediately")
+
+# 3. Closing the stream
+stream.close  # Flushes any remaining data
+~~~
+
+## Choosing Your Flush Strategy
+
+### Strategy 1: Let Automatic Flushing Handle It
+
+Best for: Bulk data transfer, file processing, log writing.
+
+~~~ ruby
+require 'io/stream'
+
+# Default behavior - automatic flush at 64KB
+stream = IO::Stream::Buffered.open("large_file.dat", "w")
+
+# Write lots of data
+1000.times do |i|
+	stream.write("Record #{i}\n" * 1000)
+end
+
+stream.close  # Final flush on close
+~~~
+
+**When to use:**
+- Writing large amounts of data continuously.
+- Throughput is more important than latency.
+- You don't need interactive feedback.
+
+### Strategy 2: Manual Flush at Logical Boundaries
+
+Best for: Request/response protocols, transaction processing, structured logging.
+
+~~~ ruby
+require 'io/stream'
+require 'socket'
+
+socket = TCPSocket.new("example.com", 80)
+stream = IO::Stream(socket)
+
+# Build complete HTTP request
+stream.write("GET / HTTP/1.1\r\n")
+stream.write("Host: example.com\r\n")
+stream.write("Connection: close\r\n")
+stream.write("\r\n")
+
+# Flush after complete request
+stream.flush  # Send request as one operation
+~~~
+
+**When to use:**
+- Message-based protocols (HTTP, Redis, etc.)
+- You need to send complete "units" of data
+- Each logical operation should complete atomically
+- Balance between throughput and responsiveness
+
+### Strategy 3: Immediate Flush for Interactive Applications
+
+Best for: Chat applications, streaming responses, real-time dashboards.
+
+~~~ ruby
+require 'io/stream'
+
+# Use smaller buffer for more frequent automatic flushes
+stream = IO::Stream::Buffered.new(
+	socket,
+	minimum_write_size: 512  # Smaller buffer = more responsive
+)
+
+# Or flush after every message
+stream.write(message)
+stream.flush  # Ensure immediate delivery
+~~~
+
+**When to use:**
+- Real-time user interaction required.
+- Low latency is critical.
+- Data arrives in small, discrete chunks.
+
+### Strategy 4: Time-Based Flushing
+
+Best for: Streaming data, progress updates, monitoring
+
+~~~ ruby
+require 'io/stream'
+
+stream = IO::Stream::Buffered.open("stream.log", "w")
+last_flush = Time.now
+
+loop do
+	stream.write(generate_log_entry)
+	
+	# Flush every second or when buffer is large
+	if Time.now - last_flush > 1.0
+		stream.flush
+		last_flush = Time.now
+	end
+end
+~~~
+
+**When to use:**
+- Ensuring regular progress visibility.
+- Protecting against data loss (periodic flush to disk).
+- Streaming applications with real-time monitoring.
+
+### Strategy 5: Readiness based flushing
+
+Best for: interactive protocols, terminal applications, chat servers.
+
+~~~ ruby
+require 'io/stream'
+
+stream = IO::Stream::Buffered.new(socket, minimum_write_size: 1024)
+
+loop do
+	# Blocking read from a queue of messages to send:
+	chunk = queue.pop
+	stream.write(chunk)
+	
+	if queue.empty?
+		# Flush when we are likely to block on the queue:
+		stream.flush
+	end
+end
+~~~
+
+**When to use:**
+- When you have unpredictable message arrival patterns.
+- When you want to ensure the lowest possible latency while still benefiting from buffering when messages arrive in bursts.
+
+## Buffer Size Configuration
+
+The `minimum_write_size` parameter controls when automatic flushing occurs:
+
+~~~ ruby
+# Very small buffer - more responsive, lower throughput
+stream = IO::Stream::Buffered.new(io, minimum_write_size: 1024)
+
+# Default - balanced (64KB)
+stream = IO::Stream::Buffered.new(io)
+
+# Large buffer - maximum throughput, higher latency
+stream = IO::Stream::Buffered.new(io, minimum_write_size: 512 * 1024)
+~~~
+
+### Choosing Buffer Size
+
+**Small buffers (1-8KB):**
+- Interactive protocols (terminal, chat).
+- Real-time data visualization.
+- Acceptable: Lower throughput.
+
+**Medium buffers (8-64KB):**
+- Web servers (default is good).
+- Application servers.
+- Database connections.
+- Balance of throughput and responsiveness.
+
+**Large buffers (64KB-1MB):**
+- File processing.
+- Bulk data transfer.
+- Video encoding.
+- Logging systems.
+- Only latency-insensitive applications.

data/context/index.yaml

@@ -0,0 +1,16 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Provides a generic stream wrapper for IO instances.
+metadata:
+  documentation_uri: https://socketry.github.io/io-stream/
+  source_code_uri: https://github.com/socketry/io-stream.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `io-stream` to add efficient buffering
+    to Ruby IO objects.
+- path: high-performance-io.md
+  title: High Performance IO
+  description: This guide explains how to achieve optimal performance when using `io-stream`
+    by understanding and controlling flush behavior.

data/lib/io/stream/buffered.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "generic"
 require_relative "connection_reset_error"
@@ -96,7 +96,7 @@ module IO::Stream
 		
 		protected
 		
-		if RUBY_VERSION >= "3.3.0" and RUBY_VERSION < "3.3.6"
+		if RUBY_VERSION < "3.3.6"
 			def sysclose
 				# https://bugs.ruby-lang.org/issues/20723
 				Thread.new{@io.close}.join
@@ -107,29 +107,8 @@ module IO::Stream
 			end
 		end
 		
-		if RUBY_VERSION >= "3.3"
-			def syswrite(buffer)
-				return @io.write(buffer)
-			end
-		else
-			def syswrite(buffer)
-				while true
-					result = @io.write_nonblock(buffer, exception: false)
-					
-					case result
-					when :wait_readable
-						@io.wait_readable(@io.timeout) or raise ::IO::TimeoutError, "read timeout"
-					when :wait_writable
-						@io.wait_writable(@io.timeout) or raise ::IO::TimeoutError, "write timeout"
-					else
-						if result == buffer.bytesize
-							return
-						else
-							buffer = buffer.byteslice(result, buffer.bytesize)
-						end
-					end
-				end
-			end
+		def syswrite(buffer)
+			return @io.write(buffer)
 		end
 		
 		# Reads data from the underlying stream as efficiently as possible.

data/lib/io/stream/connection_reset_error.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
 module IO::Stream
 	# Represents a connection reset error in IO streams, usually occurring when the remote side closes the connection unexpectedly.
 	class ConnectionResetError < Errno::ECONNRESET

data/lib/io/stream/duplex.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module IO::Stream
+	# A low-level duplex IO adapter that composes distinct readable and writable endpoints.
+	class Duplex
+		# Initialize a duplex transport from separate readable and writable endpoints.
+		# @parameter input [IO] The readable endpoint.
+		# @parameter output [IO] The writable endpoint.
+		def initialize(input, output = input)
+			@input = input
+			@output = output
+		end
+		
+		attr :input
+		attr :output
+		
+		# Return the underlying IO used to represent this duplex stream.
+		# @returns [IO] The readable endpoint if available, otherwise the writable endpoint.
+		def to_io
+			@input || @output
+		end
+		
+		# Return the maximum timeout across both endpoints.
+		# @returns [Numeric | Nil] The effective timeout, or `nil` if no timeout is configured.
+		def timeout
+			[@input.timeout, @output.timeout].compact.max
+		end
+		
+		# Update the timeout on both endpoints.
+		# @parameter duration [Numeric | Nil] The timeout to assign.
+		def timeout=(duration)
+			@input.timeout = duration
+			@output.timeout = duration
+		end
+		
+		# Check whether both endpoints are closed.
+		# @returns [Boolean] True if the duplex stream can no longer read or write.
+		def closed?
+			@input.closed? && @output.closed?
+		end
+		
+		# Close the readable endpoint.
+		def close_read
+			return if @input.closed?
+			
+			if @input.respond_to?(:close_read)
+				@input.close_read
+			else
+				@input.close
+			end
+		end
+		
+		# Close the writable endpoint.
+		def close_write
+			return if @output.closed?
+			
+			if @output.respond_to?(:close_write)
+				@output.close_write
+			else
+				@output.close
+			end
+		end
+		
+		# Check whether the readable endpoint may still produce data.
+		# @returns [Boolean] True if the readable endpoint reports it is readable.
+		def readable?
+			@input.readable?
+		end
+		
+		# Close both endpoints.
+		def close
+			@output.close unless @output.closed?
+			@input.close unless @input.closed?
+		end
+		
+		# Write data to the writable endpoint.
+		# @parameter buffer [String] The data to write.
+		# @returns [Integer] The number of bytes written.
+		def write(buffer)
+			@output.write(buffer)
+		end
+		
+		# Read data from the readable endpoint without blocking.
+		# @parameter size [Integer] The maximum number of bytes to read.
+		# @parameter buffer [String] The destination buffer.
+		# @parameter exception [Boolean] Whether to raise on `:wait_readable` and EOF conditions.
+		# @returns [String | Symbol | Nil] Data read from the endpoint, or the underlying non-blocking result.
+		def read_nonblock(size, buffer, exception: false)
+			@input.read_nonblock(size, buffer, exception: exception)
+		end
+		
+		# Wait until the readable endpoint can be read.
+		# @parameter duration [Numeric | Nil] The maximum time to wait.
+		# @returns [Boolean] True if the endpoint became readable.
+		def wait_readable(duration = @timeout)
+			@input.wait_readable(duration)
+		end
+		
+		# Wait until the writable endpoint can be written.
+		# @parameter duration [Numeric | Nil] The maximum time to wait.
+		# @returns [Boolean] True if the endpoint became writable.
+		def wait_writable(duration = @timeout)
+			@output.wait_writable(duration)
+		end
+	end
+	
+	# Construct a buffered stream from either one duplex IO-like object or two separate endpoints.
+	# @parameter input [IO] The duplex IO object, or the readable endpoint.
+	# @parameter output [IO | Nil] The writable endpoint, when distinct from the readable endpoint.
+	# @parameter options [Hash] Additional options passed to the buffered stream wrapper.
+	# @returns [IO::Stream::Buffered] A buffered stream wrapping the supplied transport.
+	def self.Duplex(input, output = nil, **options)
+		if output
+			Buffered.wrap(Duplex.new(input, output), **options)
+		else
+			::IO.Stream(input)
+		end
+	end
+end

data/lib/io/stream/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "string_buffer"
 require_relative "readable"
@@ -9,6 +9,7 @@ require_relative "writable"
 
 require_relative "shim/buffered"
 require_relative "shim/readable"
+require_relative "shim/timeout"
 
 require_relative "openssl"
 

data/lib/io/stream/openssl.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require "openssl"
 
@@ -11,50 +11,6 @@ module OpenSSL
 	module SSL
 		# SSL socket extensions for stream compatibility.
 		class SSLSocket
-			unless method_defined?(:close_read)
-				# Close the read end of the SSL socket.
-				def close_read
-					# Ignored.
-				end
-			end
-			
-			unless method_defined?(:close_write)
-				# Close the write end of the SSL socket.
-				def close_write
-					self.stop
-				end
-			end
-			
-			unless method_defined?(:wait_readable)
-				# Wait for the SSL socket to become readable.
-				def wait_readable(...)
-					to_io.wait_readable(...)
-				end
-			end
-			
-			unless method_defined?(:wait_writable)
-				# Wait for the SSL socket to become writable.
-				def wait_writable(...)
-					to_io.wait_writable(...)
-				end
-			end
-			
-			unless method_defined?(:timeout)
-				# Get the timeout for SSL socket operations.
-				# @returns [Numeric | Nil] The timeout value.
-				def timeout
-					to_io.timeout
-				end
-			end
-			
-			unless method_defined?(:timeout=)
-				# Set the timeout for SSL socket operations.
-				# @parameter value [Numeric | Nil] The timeout value.
-				def timeout=(value)
-					to_io.timeout = value
-				end
-			end
-			
 			unless method_defined?(:buffered?)
 				# Check if the SSL socket is buffered.
 				# @returns [Boolean] True if the SSL socket is buffered.

data/lib/io/stream/readable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "string_buffer"
 
@@ -254,11 +254,14 @@ module IO::Stream
 					# Don't read less than @minimum_read_size to avoid lots of small reads:
 					fill_read_buffer(read_size > @minimum_read_size ? read_size : @minimum_read_size)
 				end
+				
 				return @read_buffer[..([size, @read_buffer.size].min - 1)]
 			end
+			
 			until (block_given? && yield(@read_buffer)) or @finished
 				fill_read_buffer
 			end
+			
 			return @read_buffer
 		end
 		
@@ -366,7 +369,7 @@ module IO::Stream
 			end
 			
 			# This effectively ties the input and output stream together.
-			flush
+			self.flush
 			
 			if @read_buffer.empty?
 				if sysread(size, @read_buffer)

data/lib/io/stream/shim/timeout.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2026, by Samuel Williams.
+
+require "stringio"
+
+class StringIO
+	unless method_defined?(:timeout)
+		# Return the configured timeout for this in-memory stream.
+		# @returns [Numeric | Nil] The configured timeout, if any.
+		def timeout
+			@timeout
+		end
+	end
+	
+	unless method_defined?(:timeout=)
+		# Store timeout state for compatibility with IO-like timeout interfaces.
+		# @parameter duration [Numeric | Nil] The timeout to assign.
+		# @returns [Numeric | Nil] The assigned timeout.
+		def timeout=(duration)
+			@timeout = duration
+		end
+	end
+end

data/lib/io/stream/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2023-2025, by Samuel Williams.
 
 module IO::Stream
-	VERSION = "0.11.1"
+	VERSION = "0.13.0"
 end

data/lib/io/stream.rb

@@ -1,17 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require_relative "stream/version"
 require_relative "stream/buffered"
+require_relative "stream/duplex"
 
 # @namespace
 class IO
-	# @namespace
-	module Stream
-	end
-	
 	# Convert any IO-like object into a buffered stream.
 	# @parameter io [IO] The IO object to wrap.
 	# @returns [IO::Stream::Buffered] A buffered stream wrapper.

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2023-2025, by Samuel Williams.  
+Copyright, 2023-2026, 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

data/readme.md

@@ -4,13 +4,34 @@ Provide a buffered stream implementation for Ruby, independent of the underlying
 
 [![Development Status](https://github.com/socketry/io-stream/workflows/Test/badge.svg)](https://github.com/socketry/io-stream/actions?workflow=Test)
 
+## Motivation
+
+I built this gem because working with IO in Ruby can be surprisingly difficult. Ruby provides buffering, but the inconsistencies between different IO types made it impossible to write clean, generic code. `OpenSSL::SSL::SSLSocket` maintains its own buffering implementation that behaves differently from regular IO. Some IO types raise `OpenSSL::SSL::SSLError` on connection reset while others raise `Errno::ECONNRESET`. EOF semantics vary. Close operations can hang (especially with SSL sockets). And if you want to work with non-blocking IO using `read_nonblock` and `write_nonblock`, you're constantly handling `:wait_readable` and `:wait_writable` conditions, managing timeouts, and dealing with edge cases that differ across implementations.
+
+By providing a standard interface for buffered IO, `io-stream` allows you to write code that works the same way regardless of the underlying IO type. You can wrap any IO object and get consistent buffering behavior, unified error handling, and proper management of blocking/non-blocking operations. This makes it much easier to write high-performance IO code without worrying about the quirks of each specific IO implementation. Over time, as we've upstreamed more fixes into Ruby, we've been able to reduce the number of workarounds needed, but the core value of `io-stream` remains: a single, predictable interface for all your IO needs.
+
 ## Usage
 
-Please see the [project documentation](https://socketry.github.io/io-stream) for more details.
+Please see the [project documentation](https://socketry.github.io/io-stream/) for more details.
+
+  - [Getting Started](https://socketry.github.io/io-stream/guides/getting-started/index) - This guide explains how to use `io-stream` to add efficient buffering to Ruby IO objects.
+
+  - [High Performance IO](https://socketry.github.io/io-stream/guides/high-performance-io/index) - This guide explains how to achieve optimal performance when using `io-stream` by understanding and controlling flush behavior.
 
 ## Releases
 
-Please see the [project releases](https://socketry.github.io/io-streamreleases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/io-stream/releases/index) for all releases.
+
+### v0.13.0
+
+  - `IO::Stream::Duplex(io)` is equivalent to `IO::Stream(io)`.
+
+### v0.12.0
+
+  - Introduce `IO::Stream::Duplex` as a low-level duplex transport for composing separate input and output endpoints.
+  - Add `IO::Stream::Duplex(input, output)` as a convenient constructor that returns a buffered stream wrapping a duplex transport.
+  - Add a timeout compatibility shim for `StringIO` so duplex streams composed from in-memory endpoints can participate in the timeout interface consistently.
+  - Remove old OpenSSL method shims.
 
 ### v0.11.0
 
@@ -48,17 +69,6 @@ Please see the [project releases](https://socketry.github.io/io-streamreleases/i
 
   - Improve compatibility of `gets` implementation to better match Ruby's IO\#gets behavior.
 
-### v0.5.0
-
-  - Add support for `read_until(limit:)` parameter to limit the amount of data read.
-  - Minor documentation improvements.
-
-### v0.4.3
-
-  - Add comprehensive tests for `buffered?` method on `SSLSocket`.
-  - Ensure TLS connections have correct buffering behavior.
-  - Improve test suite organization and readability.
-
 ## See Also
 
   - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.
@@ -73,6 +83,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v0.13.0
+
+  - `IO::Stream::Duplex(io)` is equivalent to `IO::Stream(io)`.
+
+## v0.12.0
+
+  - Introduce `IO::Stream::Duplex` as a low-level duplex transport for composing separate input and output endpoints.
+  - Add `IO::Stream::Duplex(input, output)` as a convenient constructor that returns a buffered stream wrapping a duplex transport.
+  - Add a timeout compatibility shim for `StringIO` so duplex streams composed from in-memory endpoints can participate in the timeout interface consistently.
+  - Remove old OpenSSL method shims.
+
 ## v0.11.0
 
   - Introduce `class IO::Stream::ConnectionResetError < Errno::ECONNRESET` to standardize connection reset error handling across different IO types.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-stream
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -42,14 +42,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/high-performance-io.md
+- context/index.yaml
 - lib/io/stream.rb
 - lib/io/stream/buffered.rb
 - lib/io/stream/connection_reset_error.rb
+- lib/io/stream/duplex.rb
 - lib/io/stream/generic.rb
 - lib/io/stream/openssl.rb
 - lib/io/stream/readable.rb
 - lib/io/stream/shim/buffered.rb
 - lib/io/stream/shim/readable.rb
+- lib/io/stream/shim/timeout.rb
 - lib/io/stream/string_buffer.rb
 - lib/io/stream/version.rb
 - lib/io/stream/writable.rb
@@ -60,7 +65,7 @@ homepage: https://github.com/socketry/io-stream
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://socketry.github.io/io-stream
+  documentation_uri: https://socketry.github.io/io-stream/
   source_code_uri: https://github.com/socketry/io-stream.git
 rdoc_options: []
 require_paths:
@@ -69,14 +74,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Provides a generic stream wrapper for IO instances.
 test_files: []