[ruby-core:126164] [Ruby Feature#20215] Introduce `IO#readable?`

25 Jul 2026

      Issue #20215 has been updated by ioquatix (Samuel Williams).

This issue has come up again in [socketry/async-http#223](https://github.com/socketry/async-http/issues/223).

It is particularly difficult to handle for TLS. The underlying file descriptor of an `SSLSocket` can be readable because it contains an encrypted TLS record, but that record may decode to `close_notify` rather than application data. In that case, `wait_readable(0)` reports readiness even though a subsequent read from the `SSLSocket` will encounter EOF.

Ideally, an implementation for `SSLSocket` would inspect enough of the TLS stream to distinguish application data from `close_notify`, without blocking or consuming application data. If it can identify `close_notify`, `SSLSocket#readable?` should return `false`: the stream is not readable in the sense that no future read can produce application data.

I think the proposed `nonblock_eof?` semantics are compatible with the original `readable?` proposal. They express the same information at different levels:

| State | `nonblock_eof?` | Proposed `readable?` |
|---|---:|---:|
| Data is immediately available | `false` | `true` |
| EOF is immediately known | `true` | `false` |
| The result cannot be determined without blocking | `nil` | `true` |

In other words, the binary API could be defined in terms of the tri-state API:

```ruby
def readable?
	!nonblock_eof?
end
```

This preserves the original property that `readable?` may return a false positive, but should not return a false negative. An indeterminate result is therefore treated as potentially readable.

I don't have a strong opinion about the name, but both `eof?` and `nonblock_eof?` seem a little awkward to me: "end of file" does not naturally describe a socket or a protocol-level shutdown. A positive formulation also seems closer to what callers usually want to know: whether a future read may still produce data.

Whatever the name, I think the important contract is that the operation:

- never blocks;
- does not consume application data;
- returns a definitive negative only when no more application data can be read; and
- allows layered streams such as TLS to interpret their protocol-level EOF correctly.

----------------------------------------
Feature #20215: Introduce `IO#readable?`
https://bugs.ruby-lang.org/issues/20215#change-118229

* Author: ioquatix (Samuel Williams)
* Status: Open
----------------------------------------
There are some cases where, as an optimisation, it's useful to know whether more data is potentially available.

We already have `IO#eof?` but the problem with using `IO#eof?` is that it can block indefinitely for sockets.

Therefore, code which uses `IO#eof?` to determine if there is potentially more data, may hang.

```ruby
def make_request(path = "/")
  client = connect_remote_host
  # HTTP/1.0 request:
  client.write("GET #{path} HTTP/1.0\r\n\r\n")

  # Read response
  client.gets("\r\n") # => "HTTP/1.0 200 OK\r\n"

  # Assuming connection close, there are two things the server can do:
  # 1. peer.close
  # 2. peer.write(...); peer.close

  if client.eof? # <--- Can hang here!
    puts "Connection closed"
    # Avoid yielding as we know there definitely won't be any data.
  else
    puts "Connection open, data may be available..."
    # There might be data available, so yield.
    yield(client)
  end
ensure
  client&.close
end

make_request do |client|
  puts client.read # <--- Prefer to wait here.
end
```

The proposed `IO#readable?` is similar to `IO#eof?` but rather than blocking, would simply return false. The expectation is the user will subsequently call `read` which may then wait.

The proposed implementation would look something like this:

```ruby
class IO
  def readable?
    !self.closed?
  end
end

class BasicSocket
  # Is it likely that the socket is still connected?
  # May return false positive, but won't return false negative.
  def readable?
    return false unless super

    # 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
    # This might be thrown by recv_nonblock.
    return false
  end
end
```

For `IO` itself, when there is buffered data, `readable?` would also return true immediately, similar to `eof?`. This is not shown in the above implementation as I'm not sure if there is any Ruby method which exposes "there is buffered data".

-- 
https://bugs.ruby-lang.org/