From 191436847a55443eaf2b4014f03f41615b19c5b5 Mon Sep 17 00:00:00 2001
From: Sergey Fedorov <sergey.fedorov@datadoghq.com>
Date: Wed, 17 Jun 2026 12:04:27 +0200
Subject: [PATCH] Allow nil output buffers for reader methods

Ruby accepts explicit nil for output buffer arguments and allocates a
new String in that case. Update signatures and stdlib tests to match.

Updated signatures:

* _Reader#read
* _ReaderPartial#readpartial
* IO#{pread,read_nonblock,readpartial,sysread}
* ARGF#{read,read_nonblock,readpartial}
* StringIO#{read,pread,read_nonblock,readpartial,sysread}
* Zlib::GzipReader#read,readpartial
* OpenSSL::Buffering#{read,read_nonblock,readpartial}
* OpenSSL::SSL::SSLSocket#sysread
---
 core/builtin.rbs                    |  4 +--
 core/io.rbs                         | 14 +++++------
 core/rbs/unnamed/argf.rbs           |  6 ++---
 stdlib/openssl/0/openssl.rbs        | 10 ++++----
 stdlib/stringio/0/stringio.rbs      | 10 ++++----
 stdlib/zlib/0/gzip_reader.rbs       |  4 +--
 test/stdlib/ARGF_test.rb            |  8 ++++++
 test/stdlib/IO_test.rb              | 38 +++++++++++++++++++++++++++++
 test/stdlib/OpenSSL_test.rb         | 32 ++++++++++++++++++++++++
 test/stdlib/StringIO_test.rb        | 27 ++++++++++++++++++++
 test/stdlib/zlib/GzipReader_test.rb | 30 +++++++++++++++++++++++
 11 files changed, 159 insertions(+), 24 deletions(-)

diff --git a/core/builtin.rbs b/core/builtin.rbs
index cac44450b0..8bee589d89 100644
--- a/core/builtin.rbs
+++ b/core/builtin.rbs
@@ -179,11 +179,11 @@ interface _EachEntry[out T]
 end
 
 interface _Reader
-  def read: (?int? length, ?string outbuf) -> String?
+  def read: (?int? length, ?string? outbuf) -> String?
 end
 
 interface _ReaderPartial
-  def readpartial: (int maxlen, ?string outbuf) -> String
+  def readpartial: (int maxlen, ?string? outbuf) -> String
 end
 
 interface _Writer
diff --git a/core/io.rbs b/core/io.rbs
index 1b6f79bb95..d31a5b1d83 100644
--- a/core/io.rbs
+++ b/core/io.rbs
@@ -1492,7 +1492,7 @@ class IO < Object
   #
   # Not available on some platforms.
   #
-  def pread: (int maxlen, int offset, ?string out_string) -> String
+  def pread: (int maxlen, int offset, ?string? out_string) -> String
 
   # <!--
   #   rdoc-file=io.c
@@ -1589,8 +1589,8 @@ class IO < Object
   #
   # Related: IO#write.
   #
-  def read: (?nil, ?string outbuf) -> String
-          | (int? length, ?string outbuf) -> String?
+  def read: (?nil, ?string? outbuf) -> String
+          | (int? length, ?string? outbuf) -> String?
 
   # <!--
   #   rdoc-file=io.rb
@@ -1645,8 +1645,8 @@ class IO < Object
   # symbol <code>:wait_readable</code> instead. At EOF, it will return nil instead
   # of raising EOFError.
   #
-  def read_nonblock: (int len, ?string buf, ?exception: true) -> String
-                   | (int len, ?string buf, exception: false) -> (String | :wait_readable | nil)
+  def read_nonblock: (int len, ?string? buf, ?exception: true) -> String
+                   | (int len, ?string? buf, exception: false) -> (String | :wait_readable | nil)
 
   # <!--
   #   rdoc-file=io.c
@@ -1846,7 +1846,7 @@ class IO < Object
   #     r.readpartial(4096)      # => "def\n"    ""                "ghi\n"
   #     r.readpartial(4096)      # => "ghi\n"    ""                ""
   #
-  def readpartial: (int maxlen, ?string outbuf) -> String
+  def readpartial: (int maxlen, ?string? outbuf) -> String
 
   # <!--
   #   rdoc-file=io.c
@@ -2067,7 +2067,7 @@ class IO < Object
   #
   # This method should not be used with other stream-reader methods.
   #
-  def sysread: (Integer maxlen, String outbuf) -> String
+  def sysread: (Integer maxlen, ?String? outbuf) -> String
 
   # <!--
   #   rdoc-file=io.c
diff --git a/core/rbs/unnamed/argf.rbs b/core/rbs/unnamed/argf.rbs
index b44cc38b47..d9cb4e3baa 100644
--- a/core/rbs/unnamed/argf.rbs
+++ b/core/rbs/unnamed/argf.rbs
@@ -959,7 +959,7 @@ module RBS
       # ARGF#readpartial or ARGF#read_nonblock.
       #
       %a{annotate:rdoc:copy:ARGF#read}
-      def read: (?int? length, ?string outbuf) -> String?
+      def read: (?int? length, ?string? outbuf) -> String?
 
       # <!--
       #   rdoc-file=io.c
@@ -969,7 +969,7 @@ module RBS
       # Reads at most *maxlen* bytes from the ARGF stream in non-blocking mode.
       #
       %a{annotate:rdoc:copy:ARGF#read_nonblock}
-      def read_nonblock: (int maxlen, ?string buf, **untyped options) -> String
+      def read_nonblock: (int maxlen, ?string? buf, **untyped options) -> String
 
       # <!--
       #   rdoc-file=io.c
@@ -1070,7 +1070,7 @@ module RBS
       # last one.
       #
       %a{annotate:rdoc:copy:ARGF#readpartial}
-      def readpartial: (int maxlen, ?string outbuf) -> String
+      def readpartial: (int maxlen, ?string? outbuf) -> String
 
       # <!--
       #   rdoc-file=io.c
diff --git a/stdlib/openssl/0/openssl.rbs b/stdlib/openssl/0/openssl.rbs
index ebfde30722..dc04095f13 100644
--- a/stdlib/openssl/0/openssl.rbs
+++ b/stdlib/openssl/0/openssl.rbs
@@ -2100,7 +2100,7 @@ module OpenSSL
     #
     # See IO#read for full details.
     #
-    def read: (?Integer? size, ?String buf) -> String?
+    def read: (?Integer? size, ?String? buf) -> String?
 
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
@@ -2139,8 +2139,8 @@ module OpenSSL
     # symbol <code>:wait_writable</code> or <code>:wait_readable</code> instead. At
     # EOF, it will return `nil` instead of raising EOFError.
     #
-    def read_nonblock: (Integer maxlen, ?String buf, ?exception: true) -> String
-                     | (Integer maxlen, ?String buf, exception: false) -> (String | :wait_writable | :wait_readable | nil)
+    def read_nonblock: (Integer maxlen, ?String? buf, ?exception: true) -> String
+                     | (Integer maxlen, ?String? buf, exception: false) -> (String | :wait_writable | :wait_readable | nil)
 
     # <!--
     #   rdoc-file=ext/openssl/lib/openssl/buffering.rb
@@ -2180,7 +2180,7 @@ module OpenSSL
     #
     # See IO#readpartial for full details.
     #
-    def readpartial: (Integer maxlen, ?String buf) -> String
+    def readpartial: (Integer maxlen, ?String? buf) -> String
 
     # <!-- rdoc-file=ext/openssl/lib/openssl/buffering.rb -->
     # The "sync mode" of the SSLSocket.
@@ -9235,7 +9235,7 @@ module OpenSSL
       # Reads *length* bytes from the SSL connection.  If a pre-allocated *buffer* is
       # provided the data will be written into it.
       #
-      def sysread: (Integer length, ?String buffer) -> String
+      def sysread: (Integer length, ?String? buffer) -> String
 
       # <!--
       #   rdoc-file=ext/openssl/ossl_ssl.c
diff --git a/stdlib/stringio/0/stringio.rbs b/stdlib/stringio/0/stringio.rbs
index c41a7ba3e1..4b08737d50 100644
--- a/stdlib/stringio/0/stringio.rbs
+++ b/stdlib/stringio/0/stringio.rbs
@@ -1282,7 +1282,7 @@ class StringIO
   # -->
   # See IO#read.
   #
-  def read: (?int? length, ?string outbuf) -> String?
+  def read: (?int? length, ?string? outbuf) -> String?
 
   # <!--
   #   rdoc-file=ext/stringio/stringio.c
@@ -1291,9 +1291,9 @@ class StringIO
   # -->
   # See IO#pread.
   #
-  def pread: (Integer maxlen, Integer offset, ?String outbuf) -> String
+  def pread: (Integer maxlen, Integer offset, ?String? outbuf) -> String
 
-  def read_nonblock: (int len, ?string buf, ?exception: bool) -> String?
+  def read_nonblock: (int len, ?string? buf, ?exception: bool) -> String?
 
   def readbyte: () -> Integer
 
@@ -1311,7 +1311,7 @@ class StringIO
   #
   def readlines: (?String sep, ?Integer limit, ?chomp: boolish) -> ::Array[String]
 
-  def readpartial: (int maxlen, ?string outbuf) -> String
+  def readpartial: (int maxlen, ?string? outbuf) -> String
 
   # <!--
   #   rdoc-file=ext/stringio/stringio.c
@@ -1449,7 +1449,7 @@ class StringIO
   #
   def sync=: (boolish) -> bool
 
-  def sysread: (Integer maxlen, ?String outbuf) -> String
+  def sysread: (Integer maxlen, ?String? outbuf) -> String
 
   def syswrite: (String arg0) -> Integer
 
diff --git a/stdlib/zlib/0/gzip_reader.rbs b/stdlib/zlib/0/gzip_reader.rbs
index 1e94cd4b74..68631933d0 100644
--- a/stdlib/zlib/0/gzip_reader.rbs
+++ b/stdlib/zlib/0/gzip_reader.rbs
@@ -187,7 +187,7 @@ module Zlib
     # -->
     # See Zlib::GzipReader documentation for a description.
     #
-    def read: (?int? length, ?string outbuf) -> String?
+    def read: (?int? length, ?string? outbuf) -> String?
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -230,7 +230,7 @@ module Zlib
     # argument is present, it must reference a String, which will receive the data.
     # It raises `EOFError` on end of file.
     #
-    def readpartial: (int maxlen, ?string outbuf) -> String
+    def readpartial: (int maxlen, ?string? outbuf) -> String
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
diff --git a/test/stdlib/ARGF_test.rb b/test/stdlib/ARGF_test.rb
index 3a9cad8f7b..22d0d77422 100644
--- a/test/stdlib/ARGF_test.rb
+++ b/test/stdlib/ARGF_test.rb
@@ -283,8 +283,12 @@ def test_read
                       ARGF.class.new(temp_file), :read
     assert_send_type  "(::int length) -> ::String",
                       ARGF.class.new(temp_file), :read, 1
+    assert_send_type  "(::int length, nil) -> ::String",
+                      ARGF.class.new(temp_file), :read, 1, nil
     assert_send_type  "(::int length, ::string outbuf) -> ::String",
                       ARGF.class.new(temp_file), :read, 1, +""
+    assert_send_type  "(nil, nil) -> ::String",
+                      ARGF.class.new(temp_file), :read, nil, nil
     assert_send_type  "(::int length) -> nil",
                       ARGF.class.new(Tempfile.new), :read, 1
   end
@@ -292,6 +296,8 @@ def test_read
   def test_read_nonblock
     assert_send_type  "(::int maxlen) -> ::String",
                       ARGF.class.new(temp_file), :read_nonblock, 1
+    assert_send_type  "(::int maxlen, nil) -> ::String",
+                      ARGF.class.new(temp_file), :read_nonblock, 1, nil
     assert_send_type  "(::int maxlen, ::string buf) -> ::String",
                       ARGF.class.new(temp_file), :read_nonblock, 1, +""
   end
@@ -309,6 +315,8 @@ def test_readchar
   def test_readpartial
     assert_send_type  "(::int maxlen) -> ::String",
                       ARGF.class.new(temp_file), :readpartial, 1
+    assert_send_type  "(::int maxlen, nil) -> ::String",
+                      ARGF.class.new(temp_file), :readpartial, 1, nil
     assert_send_type  "(::int maxlen, ::string buf) -> ::String",
                       ARGF.class.new(temp_file), :readpartial, 1, +""
   end
diff --git a/test/stdlib/IO_test.rb b/test/stdlib/IO_test.rb
index e2b1971947..65aca6aad7 100644
--- a/test/stdlib/IO_test.rb
+++ b/test/stdlib/IO_test.rb
@@ -327,10 +327,14 @@ def test_read
                        io, :read, 1
       assert_send_type "(nil) -> String",
                        io, :read, nil
+      assert_send_type "(nil, nil) -> String",
+                       io, :read, nil, nil
       assert_send_type "(Integer, String) -> String",
                        io, :read, 0, +"buffer"
       assert_send_type "(Integer, String) -> nil",
                        io, :read, 1, +"buffer"
+      assert_send_type "(Integer, nil) -> String?",
+                       io, :read, 0, nil
       assert_send_type "(nil, String) -> String",
                        io, :read, nil, +"buffer"
     end
@@ -340,11 +344,41 @@ def test_readpartial
     IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
       assert_send_type "(Integer) -> String",
                        io, :readpartial, 10
+      assert_send_type "(Integer, nil) -> String",
+                       io, :readpartial, 10, nil
       assert_send_type "(Integer, String) -> String",
                        io, :readpartial, 10, +"buffer"
     end
   end
 
+  def test_read_nonblock
+    IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
+      assert_send_type "(Integer) -> String",
+                       io, :read_nonblock, 10
+      assert_send_type "(Integer, nil) -> String",
+                       io, :read_nonblock, 10, nil
+      assert_send_type "(Integer, String) -> String",
+                       io, :read_nonblock, 10, +"buffer"
+    end
+  end
+
+  def test_sysread
+    IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
+      assert_send_type "(Integer) -> String",
+                       io, :sysread, 1
+    end
+
+    IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
+      assert_send_type "(Integer, nil) -> String",
+                       io, :sysread, 1, nil
+    end
+
+    IO.open(IO.sysopen(File.expand_path(__FILE__))) do |io|
+      assert_send_type "(Integer, String) -> String",
+                       io, :sysread, 1, +"buffer"
+    end
+  end
+
   def test_timeout
     io, _ = IO.pipe()
 
@@ -506,6 +540,10 @@ def test_pread
             "(int, int) -> String",
             io, :pread, maxlen, offset
           )
+          assert_send_type(
+            "(int, int, nil) -> String",
+            io, :pread, maxlen, offset, nil
+          )
           with_string(+"buffer") do |buffer|
             assert_send_type(
               "(int, int, string) -> String",
diff --git a/test/stdlib/OpenSSL_test.rb b/test/stdlib/OpenSSL_test.rb
index b767aad2ad..e018deb4e3 100644
--- a/test/stdlib/OpenSSL_test.rb
+++ b/test/stdlib/OpenSSL_test.rb
@@ -13,6 +13,38 @@ def openssl?(major = nil, minor = nil, fix = nil, patch = 0)
   end
 end
 
+class OpenSSLBufferingTestIO
+  include OpenSSL::Buffering
+
+  def initialize
+    @eof = true
+    @rbuffer = +"hello"
+  end
+end
+
+class OpenSSLBufferingTest < Test::Unit::TestCase
+  include TestHelper
+  library "openssl"
+  testing "::OpenSSL::Buffering"
+
+  def test_read
+    assert_send_type "(nil, nil) -> String?",
+                     OpenSSLBufferingTestIO.new, :read, nil, nil
+    assert_send_type "(Integer, nil) -> String?",
+                     OpenSSLBufferingTestIO.new, :read, 1, nil
+  end
+
+  def test_read_nonblock
+    assert_send_type "(Integer, nil) -> String",
+                     OpenSSLBufferingTestIO.new, :read_nonblock, 1, nil
+  end
+
+  def test_readpartial
+    assert_send_type "(Integer, nil) -> String",
+                     OpenSSLBufferingTestIO.new, :readpartial, 1, nil
+  end
+end
+
 class OpenSSLSingletonTest < Test::Unit::TestCase
   include TestHelper
   library "openssl"
diff --git a/test/stdlib/StringIO_test.rb b/test/stdlib/StringIO_test.rb
index 62745afc8b..3cd72931f5 100644
--- a/test/stdlib/StringIO_test.rb
+++ b/test/stdlib/StringIO_test.rb
@@ -51,6 +51,33 @@ def test_write
                      io, :write, "a", "b"
   end
 
+  def test_read
+    assert_send_type "(nil, nil) -> ::String?",
+                     StringIO.new("a"), :read, nil, nil
+    assert_send_type "(::Integer, nil) -> ::String?",
+                     StringIO.new("a"), :read, 1, nil
+  end
+
+  def test_pread
+    assert_send_type "(::Integer, ::Integer, nil) -> ::String",
+                     StringIO.new("a"), :pread, 1, 0, nil
+  end
+
+  def test_read_nonblock
+    assert_send_type "(::int, nil) -> ::String?",
+                     StringIO.new("a"), :read_nonblock, 1, nil
+  end
+
+  def test_readpartial
+    assert_send_type "(::int, nil) -> ::String",
+                     StringIO.new("a"), :readpartial, 1, nil
+  end
+
+  def test_sysread
+    assert_send_type "(::Integer, nil) -> ::String",
+                     StringIO.new("a"), :sysread, 1, nil
+  end
+
   def test_truncate
     io = StringIO.new
 
diff --git a/test/stdlib/zlib/GzipReader_test.rb b/test/stdlib/zlib/GzipReader_test.rb
index c4538ab0fb..9eddc24dd3 100644
--- a/test/stdlib/zlib/GzipReader_test.rb
+++ b/test/stdlib/zlib/GzipReader_test.rb
@@ -41,3 +41,33 @@ def test_wrap
     end
   end
 end
+
+class ZlibGzipReaderInstanceTest < Test::Unit::TestCase
+  include TestHelper
+
+  library "zlib"
+  testing "::Zlib::GzipReader"
+
+  def test_read
+    assert_send_type "(nil, nil) -> String?",
+                     gzip_reader, :read, nil, nil
+    assert_send_type "(int length, nil) -> String?",
+                     gzip_reader, :read, 1, nil
+  end
+
+  def test_readpartial
+    assert_send_type "(int maxlen, nil) -> String",
+                     gzip_reader, :readpartial, 1, nil
+  end
+
+  private
+
+  def gzip_reader
+    io = StringIO.new
+    writer = Zlib::GzipWriter.new(io)
+    writer.write("hello")
+    writer.close
+
+    Zlib::GzipReader.new(StringIO.new(io.string))
+  end
+end