Module: OpenSSL::Buffering

Includes:
Enumerable
Included in:
SSL::SSLSocket
Defined in:
lib/extensions/openssl/openssl/buffering.rb,
lib/framework/autocomplete/OpenSSL.rb

Overview

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.

Constant Summary collapse

BLOCK_SIZE =

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

1024*16

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#to_set

Instance Attribute Details

#sync ⇒ Object

The “sync mode” of the SSLSocket.

See IO#sync for full details.



30
31
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 30

def sync
end

Instance Method Details

#<<(s) ⇒ Object

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



393
394
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 393

def <<(s)
end

#close ⇒ Object

Closes the SSLSocket and flushes any unwritten data.



456
457
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 456

def close
end

#each(eol = $/) ⇒ Object Also known as: each_line

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

See also #gets



227
228
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 227

def each(eol)
end

#each_byte ⇒ Object

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



268
269
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 268

def each_byte
end

#eof? ⇒ Boolean Also known as: eof

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

Returns:

  • (Boolean) 


299
300
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 299

def eof?
end

#flush ⇒ Object

Flushes buffered data to the SSLSocket.



444
445
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 444

def flush
end

#getc ⇒ Object

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



261
262
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 261

def getc
end

#gets(eol = $/, limit = nil) ⇒ Object

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.



203
204
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 203

def gets(eol,limit)
end

#initialize ⇒ Object

Creates an instance of OpenSSL’s buffering IO module.



40
41
42
43
44
45
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 40

def initialize(*)
  super
  @eof = false
  @rbuffer = ""
  @sync = @io.sync
end

#print(*args) ⇒ Object

Writes args to the stream.

See IO#print for full details.



423
424
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 423

def print(args)
end

#printf(s, *args) ⇒ Object

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

See Kernel#sprintf for format string details.



436
437
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 436

def printf(s,args)
end

#puts(*args) ⇒ Object

Writes args to the stream along with a record separator.

See IO#puts for full details.



403
404
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 403

def puts(args)
end

#read(size = nil, buf = nil) ⇒ Object

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.



87
88
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 87

def read(size,buf)
end

#read_nonblock(maxlen, buf = nil, exception: true) ⇒ Object

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.



172
173
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 172

def read_nonblock(maxlen,buf)
end

#readchar ⇒ Object

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

Raises:

  • (EOFError) 


278
279
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 278

def readchar
end

#readline(eol = $/) ⇒ Object

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

Raises EOFError if at end of file.

Raises:

  • (EOFError) 


252
253
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 252

def readline(eol)
end

#readlines(eol = $/) ⇒ Object

Reads lines from the stream which are separated by eol.

See also #gets



239
240
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 239

def readlines(eol)
end

#readpartial(maxlen, buf = nil) ⇒ Object

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.



114
115
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 114

def readpartial(maxlen,buf)
end

#ungetc(c) ⇒ Object

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).



291
292
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 291

def ungetc(c)
end

#write(s) ⇒ Object

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



342
343
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 342

def write(s)
end

#write_nonblock(s, exception: true) ⇒ Object

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.



384
385
 
# File 'lib/extensions/openssl/openssl/buffering.rb', line 384

def write_nonblock(s)
end