Class: HTTP2::Connection

Inherits:
Object
  • Object
show all
Includes:
BufferUtils, Emitter, Error, FlowBuffer
Defined in:
lib/http/2/connection.rb,
sig/connection.rbs

Overview

Connection encapsulates all of the connection, stream, flow-control, error management, and other processing logic required for a well-behaved HTTP 2.0 endpoint.

Note that this class should not be used directly. Instead, you want to use either Client or Server class to drive the HTTP 2.0 exchange.

Direct Known Subclasses

Client, Server

Constant Summary collapse

REQUEST_MANDATORY_HEADERS =

Returns:

  • (Array[String]) 

      
        
RESPONSE_MANDATORY_HEADERS =
          

  

    

  





  

Returns:


    
  
    
  • 
      
      
        (Array[String])
      
      
      
    
    • 
  





        

        

      
        
CONNECTION_FRAME_TYPES =
          

  

    

  





  

Returns:


    
  
    
  • 
      
      
        (Array[Symbol])
      
      
      
    
    • 
  





        

        

      
        
HEADERS_FRAME_TYPES =
          

  

    

  





  

Returns:


    
  
    
  • 
      
      
        (Array[Symbol])
      
      
      
    
    • 
  





        

        

      
        
STREAM_OPEN_STATES =
          

  

    

  





  

Returns:


    
  
    
  • 
      
      
        (Array[Symbol])
      
      
      
    
    • 
  





        

        

      
    

  



  
  
  
Constants included
     from FlowBuffer

  
FlowBuffer::MAX_WINDOW_SIZE



  
Instance Attribute Summary collapse

  



  
  
  
Attributes included from FlowBuffer

  
#send_buffer



  
    

      Instance Method Summary
      collapse
    


    
    
  


  
  
  
  
  
  
  
  
  
  
Methods included from BufferUtils

  
#append_str, #read_str, #read_uint32, #shift_byte


  
  
  
  
  
  
  
  
  
  
Methods included from Error

  
#self?.types


  
  
  
  
  
  
  
  
  
  
Methods included from Emitter

  
#emit, #on, #once


  
  
  
  
  
  
  
  
  
  
Methods included from FlowBuffer

  
#buffered_amount, #calculate_window_update, #flush, #process_window_update, #send_data, #send_frame, #update_local_window



  
Constructor Details

  
    

  

  
    #initialize(settings = {})  ⇒ Connection 
  

  

  


  

    
Initializes new connection object.


  





  
Parameters:


    
  
    
  • 
      
        
      
      
        (connection_opts)
      
      
      
    
    • 
  






  

    
      


82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

    		
    
      
# File 'lib/http/2/connection.rb', line 82

def initialize(settings = {})
  @local_settings  = DEFAULT_CONNECTION_SETTINGS.merge(settings)
  @remote_settings = SPEC_DEFAULT_CONNECTION_SETTINGS.dup

  @compressor   = Header::Compressor.new(settings)
  @decompressor = Header::Decompressor.new(settings)

  @active_stream_count = 0
  @last_stream_id = 0
  @streams = {}
  @streams_recently_closed = {}
  @oldest_stream_recently_closed = nil
  @pending_settings = []

  @framer = Framer.new(@local_settings[:settings_max_frame_size])

  @local_window_limit = @local_settings[:settings_initial_window_size]
  @local_window = @local_window_limit
  @remote_window_limit = @remote_settings[:settings_initial_window_size]
  @remote_window = @remote_window_limit

  @recv_buffer = "".b
  @continuation = []
  @continuation_size = 0
  @error = nil

  @h2c_upgrade = nil
  @closed_since = nil
  @received_frame = false

  # from mixins
  @listeners = Hash.new { |hash, key| hash[key] = [] }
  @send_buffer = FrameBuffer.new
end

    		
  





  



  

    
Instance Attribute Details

    
      
      
      

  

  
    #active_stream_count  ⇒ Integer 
  

  

  


  

    
Number of active streams between client and server (reserved streams
are not counted towards the stream limit).


  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  





  

    
      


78
79
80

    		
    
      
# File 'lib/http/2/connection.rb', line 78

def active_stream_count
  @active_stream_count
end

    		
  





    
      
      
      

  

  
    #local_settings  ⇒ settings_hash  (readonly)
  

  

  


  

    
Current settings value for local and peer


  





  

Returns:


    
  
    
  • 
      
      
        (settings_hash)
      
      
      
    
    • 
  





  

    
      


70
71
72

    		
    
      
# File 'lib/http/2/connection.rb', line 70

def local_settings
  @local_settings
end

    		
  





    
      
      
      

  

  
    #local_window  ⇒ Integer  (readonly)
  

  
    Also known as:
    window
    
  

  


  

    
Size of current connection flow control window (by default, set to
infinity, but is automatically updated on receipt of peer settings).


  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  





  

    
      


65
66
67

    		
    
      
# File 'lib/http/2/connection.rb', line 65

def local_window
  @local_window
end

    		
  





    
      
      
      

  

  
    #pending_settings  ⇒ settings_ary  (readonly)
  

  

  


  

    
Pending settings value
Sent but not ack'ed settings


  





  

Returns:


    
  
    
  • 
      
      
        (settings_ary)
      
      
      
    
    • 
  





  

    
      


74
75
76

    		
    
      
# File 'lib/http/2/connection.rb', line 74

def pending_settings
  @pending_settings
end

    		
  





    
      
      
      

  

  
    #remote_settings  ⇒ settings_hash  (readonly)
  

  

  


  

    
Returns the value of attribute remote_settings.


  





  

Returns:


    
  
    
  • 
      
      
        (settings_hash)
      
      
      
    
    • 
  





  

    
      


66
67
68

    		
    
      
# File 'lib/http/2/connection.rb', line 66

def remote_settings
  @remote_settings
end

    		
  





    
      
      
      

  

  
    #remote_window  ⇒ Integer  (readonly)
  

  

  


  

    
Returns the value of attribute remote_window.


  





  

Returns:


    
  
    
  • 
      
      
        (Integer)
      
      
      
    
    • 
  





  

    
      


66
67
68

    		
    
      
# File 'lib/http/2/connection.rb', line 66

def remote_window
  @remote_window
end

    		
  





    
      
      
      

  

  
    #state  ⇒ Symbol  (readonly)
  

  

  


  

    
Connection state (:waiting_magic, :waiting_connection_preface,
:connected, :closing, :closed).


  





  

Returns:


    
  
    
  • 
      
      
        (Symbol)
      
      
      
    
    • 
  





  

    
      


61
62
63

    		
    
      
# File 'lib/http/2/connection.rb', line 61

def state
  @state
end

    		
  





    
  



  

    
Instance Method Details


    
      

  

  
    #<<(data)  ⇒ Object 
  

  

  


  

    
      


445
446
447

    		
    
      
# File 'lib/http/2/connection.rb', line 445

def <<(data)
  receive(data)
end

    		
  





    
      

  

  
    #_verify_pseudo_headers(frame, mandatory_headers)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.


  





  
Parameters:


    
  
    
  • 
      
        push_promise_frame
      
      
        (headers_frame)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (Array[String])
      
      
      
    
    • 
  






  

    
      


859
860
861
862
863
864
865
866
867
868
869
870
871
872

    		
    
      
# File 'lib/http/2/connection.rb', line 859

def _verify_pseudo_headers(frame, mandatory_headers)
  headers = frame[:payload]
  return if headers.is_a?(String)

  pseudo_headers = headers.take_while do |field, value|
    # use this loop to validate pseudo-headers
    connection_error(:protocol_error, msg: "path is empty") if field == ":path" && value.empty?
    field.start_with?(":")
  end.map(&:first)
  return if mandatory_headers.size == pseudo_headers.size &&
            (mandatory_headers - pseudo_headers).empty?

  connection_error(:protocol_error, msg: "invalid pseudo-headers")
end

    		
  





    
      

  

  
    #activate_stream(id:, max_concurrent_streams: , **args)  ⇒ Stream 
  

  

  


  

    
Activates new incoming or outgoing stream and registers appropriate
connection managemet callbacks.


  





  
Parameters:


    
  
    
  • 
      
        id
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        max_concurrent_streams
      
      
        (Symbol)
      
      
        (defaults to: )
      
      
        —
        
    threshold to cap the number of active streams with.
    
      
    
    • 
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        window
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        parent
      
      
        (Stream)
      
      
      
    
    • 
  
    
  • 
      
        id:
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        max_concurrent_streams:
      
      
        (Integer)
      
      
        (defaults to: )
      
      
    
    • 
  
    
  • 
      
        
      
      
        (Object)
      
      
      
    
    • 
  




Returns:



Raises:





  

    
      


799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845

    		
    
      
# File 'lib/http/2/connection.rb', line 799

def activate_stream(id:, max_concurrent_streams: @local_settings[:settings_max_concurrent_streams], **args)
  connection_error(msg: "Stream ID already exists") if @streams.key?(id)

  # SETTINGS_MAX_CONCURRENT_STREAMS limits the number of concurrent streams that the sender
  # of the setting permits the receiver to create (RFC 9113, section 5.1.2), so the bounding
  # limit is the one advertised by the endpoint that did *not* open the stream.
  raise StreamLimitExceeded if @active_stream_count >= max_concurrent_streams

  stream = Stream.new(connection: self, id: id, **args)

  stream.once(:close) do
    @streams.delete(id)

    # A graceful GOAWAY leaves the connection :closing until the
    # tracked streams complete (Section 6.8); the last one to close
    # moves it to its terminal state.
    close! if @state == :closing && @streams.empty?

    # Store a reference to the closed stream, such that we can respond
    # to any in-flight frames while close is registered on both sides.
    # References to such streams will be purged whenever another stream
    # is closed, with a minimum of 15s RTT time window.
    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)

    # forego recently closed recycling if empty or the first element
    # hasn't expired yet (it's ordered).
    if @oldest_stream_recently_closed && (now - @oldest_stream_recently_closed) > 15
      new_oldest = nil
      # discards all streams which have closed for a while.
      # TODO: use a drop_while! variant whenever there is one.
      @streams_recently_closed.delete_if do |_, since|
        unless (now - since) > 15
          new_oldest ||= since
          break
        end

        true
      end
      @oldest_stream_recently_closed = new_oldest
    end

    @streams_recently_closed[id] = now
  end

  stream.on(:frame, &method(:send))
  @streams[id] = stream
end

    		
  





    
      

  

  
    #close!  ⇒ void 
  

  

  


  

    
This method returns an undefined value.


  





  



  

    
      


847
848
849
850

    		
    
      
# File 'lib/http/2/connection.rb', line 847

def close!
  @state = :closed
  @closed_since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
end

    		
  





    
      

  

  
    #closed?  ⇒ Boolean 
  

  

  


  

    
No new streams may be opened (a GOAWAY was sent or received).


  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  





  

    
      


118
119
120

    		
    
      
# File 'lib/http/2/connection.rb', line 118

def closed?
  @state == :closed || @state == :closing
end

    		
  





    
      

  

  
    #closing?  ⇒ Boolean 
  

  

  


  

    
Graceful GOAWAY received: tracked streams may still complete,
but no new ones can be opened.


  





  

Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  





  

    
      


124
125
126

    		
    
      
# File 'lib/http/2/connection.rb', line 124

def closing?
  @state == :closing
end

    		
  





    
      

  

  
    #connection_error(error = :protocol_error, msg: nil, e: nil)  ⇒ void 
  

  
    Also known as:
    error
    
  

  


  

    
This method returns an undefined value.
Emit GOAWAY error indicating to peer that the connection is being
aborted, and once sent, raise a local exception.


  





  
Parameters:


    
  
    
  • 
      
        error
      
      
        (Symbol)
      
      
        (defaults to: :protocol_error)
      
      
    
    • 
  
    
  • 
      
        msg
      
      
        (String)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        msg:
      
      
        (String, nil)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        e:
      
      
        (StandardError, nil)
      
      
        (defaults to: nil)
      
      
    
    • 
  



  
    
    
    
Options Hash (error):

    
    
      
        
  • 
          :no_error
          (Symbol)
          
            
          
          
        
    • 
      
        
  • 
          :internal_error
          (Symbol)
          
            
          
          
        
    • 
      
        
  • 
          :flow_control_error
          (Symbol)
          
            
          
          
        
    • 
      
        
  • 
          :stream_closed
          (Symbol)
          
            
          
          
        
    • 
      
        
  • 
          :frame_too_large
          (Symbol)
          
            
          
          
        
    • 
      
        
  • 
          :compression_error
          (Symbol)
          
            
          
          
        
    • 
      
    

  
    
    
    
    


Raises:


    
  
    
  • 
      
      
        ()
      
      
      
    
    • 
  





  

    
      


885
886
887
888
889
890
891
892
893

    		
    
      
# File 'lib/http/2/connection.rb', line 885

def connection_error(error = :protocol_error, msg: nil, e: nil)
  goaway(error) unless @state == :closed || @state == :new

  @state = :closed
  @error = error
  msg ||= e ? e.message : "protocol error"
  backtrace = e ? e.backtrace : nil
  raise Error.types[error], msg, backtrace
end

    		
  





    
      

  

  
    #connection_frame?(frame)  ⇒ Boolean 
  

  

  


  

    
Check if frame is a connection frame: SETTINGS, PING, GOAWAY, and any
frame addressed to stream ID = 0.


  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (frame)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  





  

    
      


495
496
497

    		
    
      
# File 'lib/http/2/connection.rb', line 495

def connection_frame?(frame)
  frame[:stream].zero? || CONNECTION_FRAME_TYPES.include?(frame[:type])
end

    		
  





    
      

  

  
    #connection_management(frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Process received connection frame (stream ID = 0).


    

  • Handle SETTINGS updates
    • 

  • Connection flow control (WINDOW_UPDATE)
    • 

  • Emit PONG auto-reply to PING frames
    • 

  • Mark connection as closed on GOAWAY
    • 



  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  






  

    
      


506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570

    		
    
      
# File 'lib/http/2/connection.rb', line 506

def connection_management(frame)
  frame_type = frame[:type]

  case @state
  when :waiting_connection_preface
    # The first frame MUST be a SETTINGS frame at the start of a connection.
    connection_error unless frame[:type] == :settings

    @state = :connected
    connection_settings(frame)

  when :connected, :closing
    case frame_type
    when :settings
      # @type var frame: settings_frame
      connection_settings(frame)
    when :window_update
      # @type var frame: window_update_frame
      process_window_update(frame: frame, encode: true)
    when :ping
      ping_management(frame)
    when :goaway
      # @type var frame: goaway_frame
      # Receivers of a GOAWAY frame MUST NOT open additional streams on
      # the connection, although a new connection can be established
      # for new streams.
      if frame[:error] == :no_error && !@streams.empty?
        # A graceful GOAWAY lets tracked streams complete before the
        # connection closes (Section 6.8).
        @state = :closing
      else
        close!
      end
      emit(:goaway, frame[:last_stream], frame[:error], frame[:payload])
    when :altsvc
      # @type var frame: altsvc_frame
      origin = frame[:origin]
      # 4.  The ALTSVC HTTP/2 Frame
      # An ALTSVC frame on stream 0 with empty (length 0) "Origin"
      # information is invalid and MUST be ignored.
      emit(:altsvc, frame) if origin && !origin.empty?
    when :origin
      # @type var frame: origin_frame
      return if @h2c_upgrade || !frame[:flags].zero?

      frame[:payload].each do |orig|
        emit(:origin, orig)
      end
    else
      connection_error
    end
  when :closed
    case frame_type
    when :goaway
      #  6.8. GOAWAY
      # An endpoint MAY send multiple GOAWAY frames if circumstances change.
    when :ping
      ping_management(frame)
    else
      connection_error if (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @closed_since) > 15
    end
  else
    connection_error
  end
end

    		
  





    
      

  

  
    #connection_settings(frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Update connection settings based on parameters set by the peer.


  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (settings_frame)
      
      
      
    
    • 
  






  

    
      


634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721

    		
    
      
# File 'lib/http/2/connection.rb', line 634

def connection_settings(frame)
  # Apply settings.
  #  side =
  #   local: previously sent and pended our settings should be effective
  #   remote: just received peer settings should immediately be effective
  if frame[:flags].anybits?(ACK)
    # Process pending settings we have sent.
    settings = @pending_settings.shift
    side = :local
  else
    settings = frame[:payload]
    validate_settings(@remote_role, settings)
    side = :remote
  end

  settings.each do |key, v|
    case side
    when :local
      @local_settings[key] = v
    when :remote
      @remote_settings[key] = v
    end

    case key
    when :settings_max_concurrent_streams
      # Do nothing.
      # The value controls at the next attempt of stream creation.

    when :settings_initial_window_size
      # A change to SETTINGS_INITIAL_WINDOW_SIZE could cause the available
      # space in a flow control window to become negative. A sender MUST
      # track the negative flow control window, and MUST NOT send new flow
      # controlled frames until it receives WINDOW_UPDATE frames that cause
      # the flow control window to become positive.
      case side
      when :local
        @local_window = @local_window - @local_window_limit + v
        @streams.each_value do |stream|
          stream.emit(:local_window, stream.local_window - @local_window_limit + v)
        end

        @local_window_limit = v
      when :remote
        # can adjust the initial window size for new streams by including a
        # value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame.
        # The connection flow-control window can only be changed using
        # WINDOW_UPDATE frames.
        @streams.each_value do |stream|
          # Event name is :window, not :remote_window
          stream.emit(:window, stream.remote_window - @remote_window_limit + v)
        end

        @remote_window_limit = v
      end

    when :settings_header_table_size
      # Setting header table size might cause some headers evicted
      case side
      when :local
        @compressor.table_size = v
      when :remote
        @decompressor.table_size = v
      end

    when :settings_enable_push
      # nothing to do

    when :settings_max_frame_size
      @framer.remote_max_frame_size = v

      # else # ignore unknown settings
    end
  end

  case side
  when :local
    # Received a settings_ack.  Notify application layer.
    emit(:settings_ack, frame, @pending_settings.size)
  when :remote
    unless @state == :closed || @h2c_upgrade == :start
      # Send ack to peer
      send(type: :settings, stream: 0, payload: EMPTY, flags: ACK)
      # when initial window size changes, we try to flush any buffered
      # data.
      @streams.each_value(&:flush)
    end
  end
end

    		
  





    
      

  

  
    #decode_headers(frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Decode headers payload and update connection decompressor state.


The receiver endpoint reassembles the header block by concatenating
the individual fragments, then decompresses the block to reconstruct
the header set - aka, header payloads are buffered until END_HEADERS,
or an END_PROMISE flag is seen.


  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  
    
  • 
      
        push_promise_frame
      
      
        (headers_frame)
      
      
      
    
    • 
  






  

    
      


731
732
733
734
735
736
737
738
739

    		
    
      
# File 'lib/http/2/connection.rb', line 731

def decode_headers(frame)
  frame[:payload] = @decompressor.decode(frame[:payload], frame) if frame[:payload].is_a?(String)
rescue CompressionError => e
  connection_error(:compression_error, e: e)
rescue ProtocolError => e
  connection_error(:protocol_error, e: e)
rescue StandardError => e
  connection_error(:internal_error, e: e)
end

    		
  





    
      

  

  
    #encode(frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Applies HTTP 2.0 binary encoding to the frame.


  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  






  

    
      


486
487
488

    		
    
      
# File 'lib/http/2/connection.rb', line 486

def encode(frame)
  emit(:frame, @framer.generate(frame))
end

    		
  





    
      

  

  
    #encode_headers(headers_frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Encode headers payload and update connection compressor state.


  





  
Parameters:


    
  
    
  • 
      
        headers_frame
      
      
        (Hash)
      
      
      
    
    • 
  
    
  • 
      
        push_promise_frame
      
      
        (headers_frame)
      
      
      
    
    • 
  






  

    
      


744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789

    		
    
      
# File 'lib/http/2/connection.rb', line 744

def encode_headers(headers_frame)
  headers_payload = headers_frame[:payload]
  begin
    payload = headers_payload.is_a?(String) ? headers_payload : @compressor.encode(headers_payload)
  rescue StandardError => e
    connection_error(:compression_error, e: e)
  end

  #: @type var payload: String
  headers_frame[:payload] = payload

  max_frame_size = @remote_settings[:settings_max_frame_size]

  # if single frame, return immediately
  if payload.bytesize <= max_frame_size
    encode(headers_frame)
    return
  end

  # split into multiple CONTINUATION frames
  total = payload.bytesize
  headers_frame[:flags] ^= END_HEADERS
  headers_frame[:payload] = payload.byteslice(0, max_frame_size)
  # payload = payload.byteslice(max_frame_size..-1)
  offset = max_frame_size

  # emit first HEADERS frame
  encode(headers_frame)

  stream_id = headers_frame[:stream]

  while offset < total
    chunk_end = offset + max_frame_size
    is_last = chunk_end >= total

    continuation_frame = {
      type: :continuation,
      flags: is_last ? END_HEADERS : 0,
      stream: stream_id,
      payload: payload.byteslice(offset, max_frame_size)
    } #: continuation_frame

    encode(continuation_frame)
    offset = chunk_end
  end
end

    		
  





    
      

  

  
    #goaway(error = :no_error, payload = nil)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Sends a GOAWAY frame indicating that the peer should stop creating
new streams for current connection.


Endpoints MAY append opaque data to the payload of any GOAWAY frame.
Additional debug data is intended for diagnostic purposes only and
carries no semantic value. Debug data MUST NOT be persistently stored,
since it could contain sensitive information.


  





  
Parameters:


    
  
    
  • 
      
        error
      
      
        (Symbol)
      
      
        (defaults to: :no_error)
      
      
    
    • 
  
    
  • 
      
        payload
      
      
        (String)
      
      
        (defaults to: nil)
      
      
    
    • 
  
    
  • 
      
        
      
      
        (Symbol)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (String)
      
      
      
    
    • 
  






  

    
      


169
170
171
172
173

    		
    
      
# File 'lib/http/2/connection.rb', line 169

def goaway(error = :no_error, payload = nil)
  send(type: :goaway, stream: 0, last_stream: @last_stream_id,
       error: error, payload: payload)
  close!
end

    		
  





    
      

  

  
    #new_stream(**args)  ⇒ Stream 
  

  

  


  

    
Allocates new stream for current connection.


  





  
Parameters:


    
  
    
  • 
      
        priority
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        window
      
      
        (Integer)
      
      
      
    
    • 
  
    
  • 
      
        parent
      
      
        (Stream)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (Object)
      
      
      
    
    • 
  




Returns:



Raises:





  

    
      


133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

    		
    
      
# File 'lib/http/2/connection.rb', line 133

def new_stream(**args)
  raise ConnectionClosed if closed?

  connection_error(:protocol_error, msg: "id is smaller than previous") if @stream_id < @last_stream_id

  stream = activate_stream(
    id: @stream_id,
    max_concurrent_streams: @remote_settings[:settings_max_concurrent_streams],
    **args
  )
  @last_stream_id = stream.id

  @stream_id += 2

  stream
end

    		
  





    
      

  

  
    
      #ping(arg0)  ⇒ void 
    
      #ping(arg0)  ⇒ void 
    
  

  

  


  

    
Sends PING frame to the peer.


  





  
  
Overloads:

  
    
    
      
      
  • 
        #ping(arg0)  ⇒ void 
        
    
  
    
    
    This method returns an undefined value.
    

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        arg0
      
      
        (String)
      
      
      
    
      • 
  

    



    
      
    • 
    
      
      
  • 
        #ping(arg0)  ⇒ void 
        
    
  
    
    
    This method returns an undefined value.
    

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        arg0
      
      
        (String)
      
      
      
    
      • 
  

    



    
      
    • 
    
  


Parameters:


    
  
    
  • 
      
        payload
      
      
        (String)
      
      
      
        —
        
    optional payload must be 8 bytes long
    
      
    
    • 
  
    
  • 
      
        blk
      
      
        (Proc)
      
      
      
        —
        
    callback to execute when PONG is received
    
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
    
    • 
  



Yield Returns:


    
  
    
  • 
      
      
        (void)
      
      
      
    
    • 
  





  

    
      


154
155
156
157

    		
    
      
# File 'lib/http/2/connection.rb', line 154

def ping(payload, &blk)
  send(type: :ping, stream: 0, payload: payload)
  once(:ack, &blk) if blk
end

    		
  





    
      

  

  
    #ping_management(frame)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.


  





  
Parameters:


    
  
    
  • 
      
        
      
      
        (frame)
      
      
      
    
    • 
  






  

    
      


572
573
574
575
576
577
578

    		
    
      
# File 'lib/http/2/connection.rb', line 572

def ping_management(frame)
  if frame[:flags].anybits?(ACK)
    emit(:ack, frame[:payload])
  else
    send(type: :ping, stream: 0, flags: ACK, payload: frame[:payload])
  end
end

    		
  





    
      

  

  
    #receive(data)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Decodes incoming bytes into HTTP 2.0 frames and routes them to
appropriate receivers: connection frames are handled directly, and
stream frames are passed to appropriate stream objects.


  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (String)
      
      
      
        —
        
    Binary encoded string
    
      
    
    • 
  






  

    
      


198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443

    		
    
      
# File 'lib/http/2/connection.rb', line 198

def receive(data)
  append_str(@recv_buffer, data)

  # Upon establishment of a TCP connection and determination that
  # HTTP/2.0 will be used by both peers, each endpoint MUST send a
  # connection header as a final confirmation and to establish the
  # initial settings for the HTTP/2.0 connection.
  #
  # Client connection header is 24 byte connection header followed by
  # SETTINGS frame. Server connection header is SETTINGS frame only.
  if @state == :waiting_magic
    if @recv_buffer.size < 24
      raise HandshakeError unless CONNECTION_PREFACE_MAGIC.start_with? @recv_buffer

      return # maybe next time
    elsif read_str(@recv_buffer, 24) == CONNECTION_PREFACE_MAGIC
      # MAGIC is OK.  Send our settings
      @state = :waiting_connection_preface
      payload = @local_settings.reject { |k, v| v == SPEC_DEFAULT_CONNECTION_SETTINGS[k] }
      settings(payload)
    else
      raise HandshakeError
    end
  end

  while (frame = @framer.parse(@recv_buffer))
    stream_id = frame[:stream] #: Integer
    frame_type = frame[:type] #: Symbol?

    if is_a?(Client) && !@received_frame
      connection_error(:protocol_error, msg: "didn't receive settings") if frame_type != :settings
      @received_frame = true
    end

    # Implementations MUST discard frames
    # that have unknown or unsupported types.
    if frame_type.nil?
      # However, extension frames that appear in
      # the middle of a header block (Section 4.3) are not permitted; these
      # MUST be treated as a connection error (Section 5.4.1) of type
      # PROTOCOL_ERROR.
      connection_error(:protocol_error) unless @continuation.empty?
      next
    end

    emit(:frame_received, frame)

    # Header blocks MUST be transmitted as a contiguous sequence of frames
    # with no interleaved frames of any other type, or from any other stream.
    unless @continuation.empty?
      # @type var frame: continuation_frame
      connection_error unless frame_type == :continuation && stream_id == @continuation.first[:stream]

      @continuation << frame
      @continuation_size += frame[:payload].bytesize
      unless frame[:flags].anybits?(END_HEADERS)
        # prevent HTTP/2 CONTINUATION FLOOD
        # same heuristic as the one from HAProxy: https://www.haproxy.com/blog/haproxy-is-resilient-to-the-http-2-continuation-flood
        # different mitigation (connection closed, instead of 400 response)
        unless @continuation_size < @local_settings[:settings_max_frame_size]
          connection_error(:protocol_error,
                           msg: "too many continuations received")
        end

        next
      end

      payload = @continuation.map { |f| f[:payload] }.join

      frame = @continuation.shift
      frame_type = frame[:type]

      @continuation.clear
      @continuation_size = 0

      frame.delete(:length)
      frame[:payload] = payload
      frame[:flags] |= END_HEADERS
    end

    # SETTINGS frames always apply to a connection, never a single stream.
    # The stream identifier for a settings frame MUST be zero.  If an
    # endpoint receives a SETTINGS frame whose stream identifier field is
    # anything other than 0x0, the endpoint MUST respond with a connection
    # error (Section 5.4.1) of type PROTOCOL_ERROR.
    if connection_frame?(frame)
      # @type var frame: connection_frame
      connection_error(:protocol_error) unless stream_id.zero?
      connection_management(frame)
    else
      case frame_type
      when :headers
        # @type var frame: headers_frame
        # When server receives even-numbered stream identifier,
        # the endpoint MUST respond with a connection error of type PROTOCOL_ERROR.
        connection_error if stream_id.even? && is_a?(Server)

        # The last frame in a sequence of HEADERS/CONTINUATION
        # frames MUST have the END_HEADERS flag set.
        unless frame[:flags].anybits?(END_HEADERS)
          @continuation << frame
          next
        end

        # After sending a GOAWAY frame, the sender can discard frames
        # for new streams.  However, any frames that alter connection
        # state cannot be completely ignored.  For instance, HEADERS,
        # PUSH_PROMISE and CONTINUATION frames MUST be minimally
        # processed to ensure a consistent compression state
        decode_headers(frame)
        # After a GOAWAY, HEADERS may only complete a tracked stream at
        # or below the highest id seen (Section 6.8); anything else is
        # discarded - decoded above, so the compression state is intact.
        # Skip only this frame: later ones may serve completing streams.
        next if closed? && (stream_id > @last_stream_id || !@streams.key?(stream_id))

        stream = @streams[stream_id]
        if stream.nil?
          verify_pseudo_headers(frame)

          verify_stream_order(stream_id)
          stream = activate_stream(
            id: stream_id,
            weight: frame[:weight] || DEFAULT_WEIGHT,
            dependency: frame[:dependency] || 0,
            exclusive: frame[:exclusive] || false
          )
          emit(:stream, stream)
        end

        stream << frame

      when :push_promise
        # @type var frame: push_promise_frame
        # The last frame in a sequence of PUSH_PROMISE/CONTINUATION
        # frames MUST have the END_HEADERS flag set
        unless frame[:flags].anybits?(END_HEADERS)
          @continuation << frame
          return
        end

        decode_headers(frame)
        next if closed?

        # PUSH_PROMISE frames MUST be associated with an existing, peer-
        # initiated stream... A receiver MUST treat the receipt of a
        # PUSH_PROMISE on a stream that is neither "open" nor
        # "half-closed (local)" as a connection error (Section 5.4.1) of
        # type PROTOCOL_ERROR. Similarly, a receiver MUST treat the
        # receipt of a PUSH_PROMISE that promises an illegal stream
        # identifier (Section 5.1.1) (that is, an identifier for a stream
        # that is not currently in the "idle" state) as a connection error
        # (Section 5.4.1) of type PROTOCOL_ERROR, unless the receiver
        # recently sent a RST_STREAM frame to cancel the associated stream.
        parent = @streams[stream_id]
        pid = frame[:promise_stream]

        # if PUSH parent is recently closed, RST_STREAM the push
        if @streams_recently_closed[stream_id]
          send(type: :rst_stream, stream: pid, error: :refused_stream)
          return
        end

        connection_error(msg: "missing parent ID") if parent.nil?

        unless STREAM_OPEN_STATES.include?(parent.state)
          # An endpoint might receive a PUSH_PROMISE frame after it sends
          # RST_STREAM.  PUSH_PROMISE causes a stream to become "reserved".
          # The RST_STREAM does not cancel any promised stream.  Therefore, if
          # promised streams are not desired, a RST_STREAM can be used to
          # close any of those streams.
          if parent.closed == :local_rst
            # We can either (a) 'resurrect' the parent, or (b) RST_STREAM
            # ... sticking with (b), might need to revisit later.
            send(type: :rst_stream, stream: pid, error: :refused_stream)
          else
            connection_error
          end
        end

        _verify_pseudo_headers(frame, REQUEST_MANDATORY_HEADERS)
        verify_stream_order(pid)
        stream = activate_stream(id: pid, parent: parent)
        emit(:promise, stream)
        stream << frame
      else
        if (stream = @streams[stream_id])
          stream << frame
          if frame_type == :data
            update_local_window(frame)
            calculate_window_update(@local_window_limit)
          end
        else
          case frame_type
          # Priority signaling is deprecated (RFC 9113 Section 5.3.2), but
          # a PRIORITY frame may still name a stream id not opened yet:
          # activate it, so the priority sticks if the stream opens.
          when :priority
            # After a GOAWAY, a PRIORITY for a stream already used and
            # closed must not resurrect it: reprioritizing a closed
            # parent is a no-op here, and a phantom stream would hold
            # the draining connection open.
            next if closed? && stream_id <= @last_stream_id

            stream = activate_stream(
              id: stream_id,
              weight: frame[:weight] || DEFAULT_WEIGHT,
              dependency: frame[:dependency] || 0,
              exclusive: frame[:exclusive] || false
            )

            emit(:stream, stream)
            stream << frame

          # WINDOW_UPDATE can be sent by a peer that has sent a frame
          # bearing the END_STREAM flag. This means that a receiver could
          # receive a WINDOW_UPDATE frame on a "half-closed (remote)" or
          # "closed" stream. A receiver MUST NOT treat this as an error
          # (see Section 5.1).
          when :window_update
            unless @streams_recently_closed.key?(stream_id)
              connection_error(:protocol_error, msg: "sent window update on idle stream")
            end
            process_window_update(frame: frame, encode: true)
          # Endpoints MUST ignore
          # WINDOW_UPDATE or RST_STREAM frames received in this state (closed), though
          # endpoints MAY choose to treat frames that arrive a significant
          # time after sending END_STREAM as a connection error.
          when :rst_stream
            unless @streams_recently_closed.key?(stream_id)
              connection_error(:protocol_error, msg: "sent window update on idle stream")
            end
          else
            # An endpoint that receives an unexpected stream identifier
            # MUST respond with a connection error of type PROTOCOL_ERROR.
            connection_error(msg: "stream does not exist")
          end
        end
      end
    end
  end
rescue StandardError => e
  raise if e.is_a?(Error::Error)

  connection_error(e: e)
end

    		
  





    
      

  

  
    #send(frame)  ⇒ void 
  

  

  


  

    
  

    Note:
    
all frames are currently delivered in FIFO order.

  



This method returns an undefined value.
Send an outgoing frame. DATA frames are subject to connection flow
control and may be split and / or buffered based on current window size.
All other frames are sent immediately.


  





  
Parameters:


    
  
    
  • 
      
        frame
      
      
        (Hash)
      
      
      
    
    • 
  






  

    
      


457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481

    		
    
      
# File 'lib/http/2/connection.rb', line 457

def send(frame)
  emit(:frame_sent, frame)

  frame_type = frame[:type] #: Symbol

  case frame_type
  when :data
    #: @type var frame: data_frame
    send_data(frame, true)
  when :headers, :push_promise
    # HEADERS and PUSH_PROMISE may generate CONTINUATION. Also send
    # RST_STREAM that are not protocol errors
    #: @type var frame: headers_frame | push_promise_frame
    encode_headers(frame) # HEADERS and PUSH_PROMISE may create more than one frame
  else
    if frame_type == :rst_stream && frame[:error] == :protocol_error
      # An endpoint can end a connection at any time. In particular, an
      # endpoint MAY choose to treat a stream error as a connection error.

      goaway(:protocol_error)
    end
    #: @type var frame: connection_frame
    encode(frame)
  end
end

    		
  





    
      

  

  
    #settings(payload)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Sends a connection SETTINGS frame to the peer.
The values are reflected when the corresponding ACK is received.


  





  
Parameters:


    
  
    
  • 
      
        settings
      
      
        (Array or Hash)
      
      
      
    
    • 
  
    
  • 
      
        payload
      
      
        (settings_enum)
      
      
      
    
    • 
  






  

    
      


187
188
189
190
191

    		
    
      
# File 'lib/http/2/connection.rb', line 187

def settings(payload)
  validate_settings(@local_role, payload)
  @pending_settings << payload
  send(type: :settings, stream: 0, payload: payload)
end

    		
  





    
      

  

  
    #validate_settings(role, settings)  ⇒ Object 
  

  

  


  

    
Validate settings parameters.  See sepc Section 6.5.2.


  





  
Parameters:


    
  
    
  • 
      
        role
      
      
        (Symbol)
      
      
      
        —
        
    The sender's role: :client or :server
    
      
    
    • 
  
    
  • 
      
        
      
      
        (role_type)
      
      
      
    
    • 
  
    
  • 
      
        
      
      
        (settings_enum)
      
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        
      
      
      
        
        
    nil if no error.  Exception object in case of any error.
    
      
    
    • 
  





  

    
      


584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629

    		
    
      
# File 'lib/http/2/connection.rb', line 584

def validate_settings(role, settings)
  settings.each do |key, v|
    case key
    when :settings_enable_push
      case role
      when :server
        # Section 8.2
        # Clients MUST reject any attempt to change the
        # SETTINGS_ENABLE_PUSH setting to a value other than 0 by treating the
        # message as a connection error (Section 5.4.1) of type PROTOCOL_ERROR.
        next if v.zero?

        connection_error(:protocol_error, msg: "invalid #{key} value")
      when :client
        # Any value other than 0 or 1 MUST be treated as a
        # connection error (Section 5.4.1) of type PROTOCOL_ERROR.
        next if v.zero? || v == 1

        connection_error(:protocol_error, msg: "invalid #{key} value")
      end
    when :settings_initial_window_size
      # Values above the maximum flow control window size of 2^31-1 MUST
      # be treated as a connection error (Section 5.4.1) of type
      # FLOW_CONTROL_ERROR.
      next if v <= 0x7fffffff

      connection_error(:flow_control_error, msg: "invalid #{key} value")
    when :settings_max_frame_size
      # The initial value is 2^14 (16,384) octets.  The value advertised
      # by an endpoint MUST be between this initial value and the maximum
      # allowed frame size (2^24-1 or 16,777,215 octets), inclusive.
      # Values outside this range MUST be treated as a connection error
      # (Section 5.4.1) of type PROTOCOL_ERROR.
      next if v.between?(16_384, 16_777_215)

      connection_error(:protocol_error, msg: "invalid #{key} value")
      # when :settings_max_concurrent_streams
      # Any value is valid
      # when :settings_header_table_size
      # Any value is valid
      # when :settings_max_header_list_size
      # Any value is valid
      # else # ignore unknown settings
    end
  end
end

    		
  





    
      

  

  
    #verify_pseudo_headers  ⇒ void 
  

  

  


  

    
This method returns an undefined value.


  





  
Parameters:


    
  
    
  • 
      
        push_promise_frame
      
      
        (headers_frame)
      
      
      
    
    • 
  






  

    
      


106

    		
    
      
# File 'sig/connection.rbs', line 106

def verify_pseudo_headers: (headers_frame | push_promise_frame) -> void

    		
  





    
      

  

  
    #verify_stream_order(id)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.


  





  
Parameters:


    
  
    
  • 
      
        id
      
      
        (Integer)
      
      
      
    
    • 
  






  

    
      


852
853
854
855
856
857

    		
    
      
# File 'lib/http/2/connection.rb', line 852

def verify_stream_order(id)
  return unless id.odd?

  connection_error(msg: "Stream ID smaller than previous") if @last_stream_id >= id
  @last_stream_id = id
end

    		
  





    
      

  

  
    #window_update(increment)  ⇒ void 
  

  

  


  

    
This method returns an undefined value.
Sends a WINDOW_UPDATE frame to the peer.


  





  
Parameters:


    
  
    
  • 
      
        increment
      
      
        (Integer)
      
      
      
    
    • 
  






  

    
      


178
179
180
181

    		
    
      
# File 'lib/http/2/connection.rb', line 178

def window_update(increment)
  @local_window += increment
  send(type: :window_update, stream: 0, increment: increment)
end