Class: QuietQUIC::Stream

Inherits:
Object
  • Object
show all
Defined in:
lib/quietquic/stream.rb

Overview

Note:

The native alpha.3 API has split send/receive halves. This Ruby class keeps one facade around those halves: send operations serialize with send operations, receive operations serialize with receive operations, and both still park through the same scheduler-aware bridge.

A bidirectional QUIC stream on a Connection.

Obtained from Connection#open_stream or Connection#accept_stream. Write bytes with #write_all, signal end-of-data with #finish, and read the peer's whole reply with #read_to_end. Each operation parks the fiber (under an Async reactor) until it resolves.

Constant Summary collapse

DEFAULT_READ_LIMIT =

Default upper bound for #read_to_end, chosen to keep the convenience method safe against an authenticated peer sending an unbounded response.

1024 * 1024
DEFAULT_FINISH_TIMEOUT = 
10

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ Stream

Returns a new instance of Stream.

Parameters:

  • native (Native::Stream) —

    the wrapped crate stream.



21
22
23
 
# File 'lib/quietquic/stream.rb', line 21

def initialize(native)
  @native = native
end

Instance Method Details

#finish ⇒ void

This method returns an undefined value.

Finish (send FIN on) the stream, signalling end-of-data to the peer.

Raises:

  • (QuietQUIC::ConnectionLost) —

    if the connection is closed or lost.

  • (QuietQUIC::StreamError) —

    if the stream is reset or stopped.



42
43
44
 
# File 'lib/quietquic/stream.rb', line 42

def finish
  QuietQUIC.await(@native.finish_op)
end

#finish_and_wait(timeout: DEFAULT_FINISH_TIMEOUT) ⇒ void

This method returns an undefined value.

Finish the stream and wait for the peer to acknowledge its FIN.

Use this before immediately closing the connection when delivery of the final stream matters. A plain #finish only queues FIN locally.

Parameters:

  • timeout (Numeric) (defaults to: DEFAULT_FINISH_TIMEOUT) —

    maximum seconds to wait.



53
54
55
56
57
58
59
 
# File 'lib/quietquic/stream.rb', line 53

def finish_and_wait(timeout: DEFAULT_FINISH_TIMEOUT)
  unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
    raise ArgumentError, "timeout must be a positive finite number"
  end

  QuietQUIC.await(@native.finish_and_wait_op(timeout.to_f))
end

#read_to_end(limit: DEFAULT_READ_LIMIT) ⇒ String

Note:

This parks until the peer sends FIN. Avoid issuing multiple concurrent reads on the same Stream; they share one receive half.

Read the stream to end-of-stream, returning up to limit bytes.

Parks until the peer sends FIN. The result is a String with Encoding::BINARY (ASCII-8BIT): exact bytes, never UTF-8-validated.

Parameters:

  • limit (Integer) (defaults to: DEFAULT_READ_LIMIT) —

    maximum response size in bytes.

Returns:

  • (String) —

    the received bytes, BINARY-encoded.

Raises:

  • (QuietQUIC::ConnectionLost) —

    if the connection is closed or lost.

  • (QuietQUIC::StreamError) —

    if the stream is reset before FIN or exceeds limit.



73
74
75
76
77
 
# File 'lib/quietquic/stream.rb', line 73

def read_to_end(limit: DEFAULT_READ_LIMIT)
  raise ArgumentError, "limit must be a non-negative Integer" unless limit.is_a?(Integer) && limit >= 0

  QuietQUIC.await(@native.read_to_end_op(limit))
end

#write_all(bytes) ⇒ void

This method returns an undefined value.

Write all of bytes to the stream, waiting out flow-control back-pressure. The bytes are sent verbatim: bytes is read as a raw byte sequence regardless of its String encoding.

Parameters:

  • bytes (String) —

    the bytes to send.

Raises:

  • (QuietQUIC::ConnectionLost) —

    if the connection is closed or lost.

  • (QuietQUIC::StreamError) —

    if the stream is reset or stopped.



33
34
35
 
# File 'lib/quietquic/stream.rb', line 33

def write_all(bytes)
  QuietQUIC.await(@native.write_all_op(bytes))
end