# module OpenSSL::Buffering

`OpenSSL` `IO` buffering mix-in module.

This module allows an `OpenSSL::SSL::SSLSocket` to behave like an `IO`.

You typically won’t use this module directly, you can see it implemented in `OpenSSL::SSL::SSLSocket`.

### Constants

BLOCK_SIZE

  Default size to read from or write to the SSLSocket for buffer operations.

### Attributes

sync [RW]

The “sync mode” of the SSLSocket.

See `IO#sync` for full details.

### Public Class Methods

new (*)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 63
    def initialize(*)
      super
      @eof = false
      @rbuffer = Buffer.new
      @sync = @io.sync
    end

Creates an instance of OpenSSL’s buffering `IO` module.

Calls superclass method

### Public Instance Methods

<< (s)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 434
    def <<(s)
      do_write(s)
      self
    end

Writes s to the stream. s will be converted to a `String` using `.to_s` method.

close ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 495
    def close
      flush rescue nil
      sysclose
    end

Closes the SSLSocket and flushes any unwritten data.

each (eol=$/) { |line| ... }
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 266
    def each(eol=$/)
      while line = self.gets(eol)
        yield line
      end
    end

Executes the block for every line in the stream where lines are separated by eol.

See also `gets`

Also aliased as: each_line
each_byte () { |byte| ... }
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 307
    def each_byte # :yields: byte
      while c = getc
        yield(c.ord)
      end
    end

Calls the given block once for each byte in the stream.

each_line (eol=$/)
Alias for: each
eof ()
Alias for: eof?
eof? ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 338
    def eof?
      fill_rbuff if !@eof && @rbuffer.empty?
      @eof && @rbuffer.empty?
    end

Returns true if the stream is at file which means there is no more data to be read.

Also aliased as: eof
flush ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 483
    def flush
      osync = @sync
      @sync = true
      do_write ""
      return self
    ensure
      @sync = osync
    end

Flushes buffered data to the SSLSocket.

getbyte → 81
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 106
    def getbyte
      read(1)&.ord
    end

Get the next 8bit byte from ‘ssl`. Returns `nil` on EOF

getc ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 300
    def getc
      read(1)
    end

Reads one character from the stream. Returns nil if called at end of file.

gets (eol=$/, limit=nil, chomp: false)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 238
    def gets(eol=$/, limit=nil, chomp: false)
      idx = @rbuffer.index(eol)
      until @eof
        break if idx
        fill_rbuff
        idx = @rbuffer.index(eol)
      end
      if eol.is_a?(Regexp)
        size = idx ? idx+$&.size : nil
      else
        size = idx ? idx+eol.size : nil
      end
      if size && limit && limit >= 0
        size = [size, limit].min
      end
      line = consume_rbuff(size)
      if chomp && line
        line.chomp!(eol)
      end
      line
    end

Reads the next “line” from the stream. Lines are separated by eol. If limit is provided the result will not be longer than the given number of bytes.

eol may be a `String` or `Regexp`.

Unlike `IO#gets` the line read will not be assigned to +$_+.

Unlike `IO#gets` the separator must be provided if a limit is provided.

print (*args)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 462
    def print(*args)
      s = Buffer.new
      args.each{ |arg| s << arg.to_s }
      do_write(s)
      nil
    end

Writes args to the stream.

See `IO#print` for full details.

printf (s, *args)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 475
    def printf(s, *args)
      do_write(s % args)
      nil
    end

Formats and writes to the stream converting parameters under control of the format string.

See `Kernel#sprintf` for format string details.

puts (*args)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 444
    def puts(*args)
      s = Buffer.new
      if args.empty?
        s << "\n"
      end
      args.each{|arg|
        s << arg.to_s
        s.sub!(/(?<!\n)\z/, "\n")
      }
      do_write(s)
      nil
    end

Writes args to the stream along with a record separator.

See `IO#puts` for full details.

read (size=nil, buf=nil)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 122
    def read(size=nil, buf=nil)
      if size == 0
        if buf
          buf.clear
          return buf
        else
          return ""
        end
      end
      until @eof
        break if size && size <= @rbuffer.size
        fill_rbuff
      end
      ret = consume_rbuff(size) || ""
      if buf
        buf.replace(ret)
        ret = buf
      end
      (size && ret.empty?) ? nil : ret
    end

Reads size bytes from the stream. If buf is provided it must reference a string which will receive the data.

See `IO#read` for full details.

read_nonblock (maxlen, buf=nil, exception: true)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 207
    def read_nonblock(maxlen, buf=nil, exception: true)
      if maxlen == 0
        if buf
          buf.clear
          return buf
        else
          return ""
        end
      end
      if @rbuffer.empty?
        return sysread_nonblock(maxlen, buf, exception: exception)
      end
      ret = consume_rbuff(maxlen)
      if buf
        buf.replace(ret)
        ret = buf
      end
      ret
    end

Reads at most maxlen bytes in the non-blocking manner.

When no data can be read without blocking it raises `OpenSSL::SSL::SSLError` extended by `IO::WaitReadable` or `IO::WaitWritable`.

`IO::WaitReadable` means `SSL` needs to read internally so `read_nonblock` should be called again when the underlying `IO` is readable.

`IO::WaitWritable` means `SSL` needs to write internally so `read_nonblock` should be called again after the underlying `IO` is writable.

`OpenSSL::Buffering#read_nonblock` needs two rescue clause as follows:

    # emulates blocking read (readpartial).
    begin
      result = ssl.read_nonblock(maxlen)
    rescue IO::WaitReadable
      IO.select([io])
      retry
    rescue IO::WaitWritable
      IO.select(nil, [io])
      retry
    end

Note that one reason that `read_nonblock` writes to the underlying `IO` is when the peer requests a new TLS/SSL handshake. See openssl the FAQ for more details. www.openssl.org/support/faq.html

By specifying a keyword argument exception to `false`, you can indicate that `read_nonblock` should not raise an IO::Wait*able exception, but return the symbol `:wait_writable` or `:wait_readable` instead. At EOF, it will return `nil` instead of raising `EOFError`.

readbyte ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 111
    def readbyte
      raise EOFError if eof?
      getbyte
    end

Get the next 8bit byte. Raises `EOFError` on EOF

readchar ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 317
    def readchar
      raise EOFError if eof?
      getc
    end

Reads a one-character string from the stream. Raises an `EOFError` at end of file.

readline (eol=$/)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 291
    def readline(eol=$/)
      raise EOFError if eof?
      gets(eol)
    end

Reads a line from the stream which is separated by eol.

Raises `EOFError` if at end of file.

readlines (eol=$/)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 278
    def readlines(eol=$/)
      ary = []
      while line = self.gets(eol)
        ary << line
      end
      ary
    end

Reads lines from the stream which are separated by eol.

See also `gets`

readpartial (maxlen, buf=nil)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 149
    def readpartial(maxlen, buf=nil)
      if maxlen == 0
        if buf
          buf.clear
          return buf
        else
          return ""
        end
      end
      if @rbuffer.empty?
        begin
          return sysread(maxlen, buf)
        rescue Errno::EAGAIN
          retry
        end
      end
      ret = consume_rbuff(maxlen)
      if buf
        buf.replace(ret)
        ret = buf
      end
      ret
    end

Reads at most maxlen bytes from the stream. If buf is provided it must reference a string which will receive the data.

See `IO#readpartial` for full details.

ungetc (c)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 330
    def ungetc(c)
      @rbuffer[0,0] = c.chr
    end

Pushes character c back onto the stream such that a subsequent buffered character read will return it.

Unlike `IO#getc` multiple bytes may be pushed back onto the stream.

Has no effect on unbuffered reads (such as sysread).

write (*s)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 381
    def write(*s)
      s.inject(0) do |written, str|
        do_write(str)
        written + str.bytesize
      end
    end

Writes s to the stream. If the argument is not a `String` it will be converted using `.to_s` method. Returns the number of bytes written.

write_nonblock (s, exception: true)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 425
    def write_nonblock(s, exception: true)
      flush
      syswrite_nonblock(s, exception: exception)
    end

Writes s in the non-blocking manner.

If there is buffered data, it is flushed first. This may block.

`write_nonblock` returns number of bytes written to the `SSL` connection.

When no data can be written without blocking it raises `OpenSSL::SSL::SSLError` extended by `IO::WaitReadable` or `IO::WaitWritable`.

`IO::WaitReadable` means `SSL` needs to read internally so `write_nonblock` should be called again after the underlying `IO` is readable.

`IO::WaitWritable` means `SSL` needs to write internally so `write_nonblock` should be called again after underlying `IO` is writable.

So `OpenSSL::Buffering#write_nonblock` needs two rescue clause as follows.

    # emulates blocking write.
    begin
      result = ssl.write_nonblock(str)
    rescue IO::WaitReadable
      IO.select([io])
      retry
    rescue IO::WaitWritable
      IO.select(nil, [io])
      retry
    end

Note that one reason that `write_nonblock` reads from the underlying `IO` is when the peer requests a new TLS/SSL handshake. See the openssl FAQ for more details. www.openssl.org/support/faq.html

By specifying a keyword argument exception to `false`, you can indicate that `write_nonblock` should not raise an IO::Wait*able exception, but return the symbol `:wait_writable` or `:wait_readable` instead.

### Private Instance Methods

consume_rbuff (size=nil)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 91
    def consume_rbuff(size=nil)
      if @rbuffer.empty?
        nil
      else
        size = @rbuffer.size unless size
        @rbuffer.slice!(0, size)
      end
    end

Consumes size bytes from the buffer

do_write (s)
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 353
    def do_write(s)
      @wbuffer = Buffer.new unless defined? @wbuffer
      @wbuffer << s
      @wbuffer.force_encoding(Encoding::BINARY)
      @sync ||= false
      buffer_size = @wbuffer.size
      if @sync or buffer_size > BLOCK_SIZE
        nwrote = 0
        begin
          while nwrote < buffer_size do
            begin
              nwrote += syswrite(@wbuffer[nwrote, buffer_size - nwrote])
            rescue Errno::EAGAIN
              retry
            end
          end
        ensure
          @wbuffer[0, nwrote] = ""
        end
      end
    end

Writes s to the buffer. When the buffer is full or `sync` is true the buffer is flushed to the underlying socket.

fill_rbuff ()
Source

    # File ext/openssl/lib/openssl/buffering.rb, line 78
    def fill_rbuff
      begin
        @rbuffer << self.sysread(BLOCK_SIZE)
      rescue Errno::EAGAIN
        retry
      rescue EOFError
        @eof = true
      end
    end

Fills the buffer from the underlying SSLSocket