Module: OpenSSL::Buffering
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.
Defined Under Namespace
Classes: Buffer
Constant Summary collapse
- BLOCK_SIZE =
Default size to read from or write to the SSLSocket for buffer operations.
1024*16
Instance Attribute Summary collapse
-
#sync ⇒ Object
The “sync mode” of the SSLSocket.
Instance Method Summary collapse
-
#<<(s) ⇒ Object
Writes s to the stream.
-
#close ⇒ Object
Closes the SSLSocket and flushes any unwritten data.
-
#each(eol = $/) ⇒ Object
(also: #each_line)
Executes the block for every line in the stream where lines are separated by eol.
-
#each_byte ⇒ Object
Calls the given block once for each byte in the stream.
-
#eof? ⇒ Boolean
(also: #eof)
Returns true if the stream is at file which means there is no more data to be read.
-
#flush ⇒ Object
Flushes buffered data to the SSLSocket.
-
#getbyte ⇒ Object
call-seq: ssl.getbyte => 81.
-
#getc ⇒ Object
Reads one character from the stream.
-
#gets(eol = $/, limit = nil) ⇒ Object
Reads the next “line” from the stream.
-
#initialize ⇒ Object
Creates an instance of OpenSSL’s buffering IO module.
-
#print(*args) ⇒ Object
Writes args to the stream.
-
#printf(s, *args) ⇒ Object
Formats and writes to the stream converting parameters under control of the format string.
-
#puts(*args) ⇒ Object
Writes args to the stream along with a record separator.
-
#read(size = nil, buf = nil) ⇒ Object
Reads size bytes from the stream.
-
#read_nonblock(maxlen, buf = nil, exception: true) ⇒ Object
Reads at most maxlen bytes in the non-blocking manner.
-
#readchar ⇒ Object
Reads a one-character string from the stream.
-
#readline(eol = $/) ⇒ Object
Reads a line from the stream which is separated by eol.
-
#readlines(eol = $/) ⇒ Object
Reads lines from the stream which are separated by eol.
-
#readpartial(maxlen, buf = nil) ⇒ Object
Reads at most maxlen bytes from the stream.
-
#ungetc(c) ⇒ Object
Pushes character c back onto the stream such that a subsequent buffered character read will return it.
-
#write(*s) ⇒ Object
Writes s to the stream.
-
#write_nonblock(s, exception: true) ⇒ Object
Writes s in the non-blocking manner.
Instance Attribute Details
#sync ⇒ Object
The “sync mode” of the SSLSocket.
See IO#sync for full details.
53 54 55 |
# File 'lib/openssl/buffering.rb', line 53 def sync @sync end |
Instance Method Details
#<<(s) ⇒ Object
Writes s to the stream. s will be converted to a String using .to_s
method.
422 423 424 425 |
# File 'lib/openssl/buffering.rb', line 422 def <<(s) do_write(s) self end |
#close ⇒ Object
Closes the SSLSocket and flushes any unwritten data.
483 484 485 486 |
# File 'lib/openssl/buffering.rb', line 483 def close flush rescue nil sysclose 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
259 260 261 262 263 |
# File 'lib/openssl/buffering.rb', line 259 def each(eol=$/) while line = self.gets(eol) yield line end end |
#each_byte ⇒ Object
Calls the given block once for each byte in the stream.
300 301 302 303 304 |
# File 'lib/openssl/buffering.rb', line 300 def each_byte # :yields: byte while c = getc yield(c.ord) end 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.
331 332 333 334 |
# File 'lib/openssl/buffering.rb', line 331 def eof? fill_rbuff if !@eof && @rbuffer.empty? @eof && @rbuffer.empty? end |
#flush ⇒ Object
Flushes buffered data to the SSLSocket.
471 472 473 474 475 476 477 478 |
# File 'lib/openssl/buffering.rb', line 471 def flush osync = @sync @sync = true do_write "" return self ensure @sync = osync end |
#getbyte ⇒ Object
call-seq:
ssl.getbyte => 81
Get the next 8bit byte from ‘ssl`. Returns `nil` on EOF
108 109 110 111 |
# File 'lib/openssl/buffering.rb', line 108 def getbyte byte = read(1) byte && byte.unpack1("C") end |
#getc ⇒ Object
Reads one character from the stream. Returns nil if called at end of file.
293 294 295 |
# File 'lib/openssl/buffering.rb', line 293 def getc read(1) 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.
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 |
# File 'lib/openssl/buffering.rb', line 235 def gets(eol=$/, limit=nil) 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 consume_rbuff(size) end |
#initialize ⇒ Object
Creates an instance of OpenSSL’s buffering IO module.
63 64 65 66 67 68 |
# File 'lib/openssl/buffering.rb', line 63 def initialize(*) super @eof = false @rbuffer = Buffer.new @sync = @io.sync end |
#print(*args) ⇒ Object
Writes args to the stream.
See IO#print for full details.
450 451 452 453 454 455 |
# File 'lib/openssl/buffering.rb', line 450 def print(*args) s = Buffer.new args.each{ |arg| s << arg.to_s } do_write(s) nil 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.
463 464 465 466 |
# File 'lib/openssl/buffering.rb', line 463 def printf(s, *args) do_write(s % args) nil end |
#puts(*args) ⇒ Object
Writes args to the stream along with a record separator.
See IO#puts for full details.
432 433 434 435 436 437 438 439 440 441 442 443 |
# File 'lib/openssl/buffering.rb', line 432 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 |
#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.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
# File 'lib/openssl/buffering.rb', line 119 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 |
#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.
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 |
# File 'lib/openssl/buffering.rb', line 204 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 |
#readchar ⇒ Object
Reads a one-character string from the stream. Raises an EOFError at end of file.
310 311 312 313 |
# File 'lib/openssl/buffering.rb', line 310 def readchar raise EOFError if eof? getc end |
#readline(eol = $/) ⇒ Object
Reads a line from the stream which is separated by eol.
Raises EOFError if at end of file.
284 285 286 287 |
# File 'lib/openssl/buffering.rb', line 284 def readline(eol=$/) raise EOFError if eof? gets(eol) end |
#readlines(eol = $/) ⇒ Object
Reads lines from the stream which are separated by eol.
See also #gets
271 272 273 274 275 276 277 |
# File 'lib/openssl/buffering.rb', line 271 def readlines(eol=$/) ary = [] while line = self.gets(eol) ary << line end ary 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.
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 |
# File 'lib/openssl/buffering.rb', line 146 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 |
#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).
323 324 325 |
# File 'lib/openssl/buffering.rb', line 323 def ungetc(c) @rbuffer[0,0] = c.chr end |
#write(*s) ⇒ Object
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.
369 370 371 372 373 374 |
# File 'lib/openssl/buffering.rb', line 369 def write(*s) s.inject(0) do |written, str| do_write(str) written + str.bytesize end 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.
413 414 415 416 |
# File 'lib/openssl/buffering.rb', line 413 def write_nonblock(s, exception: true) flush syswrite_nonblock(s, exception: exception) end |