src/net/quic/quic_packet_creator.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // Accumulates frames for the next packet until more frames no longer fit or
   6 // it's time to create a packet from them.  Also provides packet creation of
   7 // FEC packets based on previously created packets.
   8
   9 #ifndef NET_QUIC_QUIC_PACKET_CREATOR_H_
  10 #define NET_QUIC_QUIC_PACKET_CREATOR_H_
  11
  12 #include <utility>
  13 #include <vector>
  14
  15 #include "base/memory/scoped_ptr.h"
  16 #include "base/strings/string_piece.h"
  17 #include "net/quic/quic_fec_group.h"
  18 #include "net/quic/quic_framer.h"
  19 #include "net/quic/quic_protocol.h"
  20
  21 namespace net {
  22 namespace test {
  23 class QuicPacketCreatorPeer;
  24 }
  25
  26 class QuicAckNotifier;
  27 class QuicRandom;
  28 class QuicRandomBoolSource;
  29
  30 class NET_EXPORT_PRIVATE QuicPacketCreator : public QuicFecBuilderInterface {
  31  public:
  32   // QuicRandom* required for packet entropy.
  33   QuicPacketCreator(QuicConnectionId connection_id,
  34                     QuicFramer* framer,
  35                     QuicRandom* random_generator);
  36
  37   ~QuicPacketCreator() override;
  38
  39   // QuicFecBuilderInterface
  40   void OnBuiltFecProtectedPayload(const QuicPacketHeader& header,
  41                                   base::StringPiece payload) override;
  42
  43   // Turn on FEC protection for subsequently created packets. FEC should be
  44   // enabled first (max_packets_per_fec_group should be non-zero) for FEC
  45   // protection to start.
  46   void StartFecProtectingPackets();
  47
  48   // Turn off FEC protection for subsequently created packets. If the creator
  49   // has any open FEC group, call will fail. It is the caller's responsibility
  50   // to flush out FEC packets in generation, and to verify with ShouldSendFec()
  51   // that there is no open FEC group.
  52   void StopFecProtectingPackets();
  53
  54   // Checks if it's time to send an FEC packet.  |force_close| forces this to
  55   // return true if an FEC group is open.
  56   bool ShouldSendFec(bool force_close) const;
  57
  58   // Returns true if an FEC packet is under construction.
  59   bool IsFecGroupOpen() const;
  60
  61   // Makes the framer not serialize the protocol version in sent packets.
  62   void StopSendingVersion();
  63
  64   // Update the sequence number length to use in future packets as soon as it
  65   // can be safely changed.
  66   void UpdateSequenceNumberLength(
  67       QuicPacketSequenceNumber least_packet_awaited_by_peer,
  68       QuicPacketCount max_packets_in_flight);
  69
  70   // The overhead the framing will add for a packet with one frame.
  71   static size_t StreamFramePacketOverhead(
  72       QuicConnectionIdLength connection_id_length,
  73       bool include_version,
  74       QuicSequenceNumberLength sequence_number_length,
  75       QuicStreamOffset offset,
  76       InFecGroup is_in_fec_group);
  77
  78   bool HasRoomForStreamFrame(QuicStreamId id, QuicStreamOffset offset) const;
  79
  80   // Converts a raw payload to a frame which fits into the currently open
  81   // packet if there is one.  Returns the number of bytes consumed from data.
  82   // If data is empty and fin is true, the expected behavior is to consume the
  83   // fin but return 0.
  84   size_t CreateStreamFrame(QuicStreamId id,
  85                            const IOVector& data,
  86                            QuicStreamOffset offset,
  87                            bool fin,
  88                            QuicFrame* frame);
  89
  90   // As above, but keeps track of an QuicAckNotifier that should be called when
  91   // the packet that contains this stream frame is ACKed.
  92   // The |notifier| is not owned by the QuicPacketGenerator and must outlive the
  93   // generated packet.
  94   size_t CreateStreamFrameWithNotifier(QuicStreamId id,
  95                                        const IOVector& data,
  96                                        QuicStreamOffset offset,
  97                                        bool fin,
  98                                        QuicAckNotifier* notifier,
  99                                        QuicFrame* frame);
 100
 101   // Serializes all frames into a single packet. All frames must fit into a
 102   // single packet. Also, sets the entropy hash of the serialized packet to a
 103   // random bool and returns that value as a member of SerializedPacket.
 104   // Never returns a RetransmittableFrames in SerializedPacket.
 105   SerializedPacket SerializeAllFrames(const QuicFrames& frames);
 106
 107   // Re-serializes frames with the original packet's sequence number length.
 108   // Used for retransmitting packets to ensure they aren't too long.
 109   // Caller must ensure that any open FEC group is closed before calling this
 110   // method.
 111   SerializedPacket ReserializeAllFrames(
 112       const QuicFrames& frames,
 113       QuicSequenceNumberLength original_length);
 114
 115   // Returns true if there are frames pending to be serialized.
 116   bool HasPendingFrames() const;
 117
 118   // Returns true if there are retransmittable frames pending to be serialized.
 119   bool HasPendingRetransmittableFrames() const;
 120
 121   // Returns whether FEC protection is currently enabled. Note: Enabled does not
 122   // mean that an FEC group is currently active; i.e., IsFecProtected() may
 123   // still return false.
 124   bool IsFecEnabled() const;
 125
 126   // Returns true if subsequent packets will be FEC protected. Note: True does
 127   // not mean that an FEC packet is currently under construction; i.e.,
 128   // fec_group_.get() may still be nullptr, until MaybeStartFec() is called.
 129   bool IsFecProtected() const;
 130
 131   // Returns the number of bytes which are available to be used by additional
 132   // frames in the packet.  Since stream frames are slightly smaller when they
 133   // are the last frame in a packet, this method will return a different
 134   // value than max_packet_size - PacketSize(), in this case.
 135   size_t BytesFree() const;
 136
 137   // Returns the number of bytes that the packet will expand by if a new frame
 138   // is added to the packet. If the last frame was a stream frame, it will
 139   // expand slightly when a new frame is added, and this method returns the
 140   // amount of expected expansion. If the packet is in an FEC group, no
 141   // expansion happens and this method always returns zero.
 142   size_t ExpansionOnNewFrame() const;
 143
 144   // Returns the number of bytes in the current packet, including the header,
 145   // if serialized with the current frames.  Adding a frame to the packet
 146   // may change the serialized length of existing frames, as per the comment
 147   // in BytesFree.
 148   size_t PacketSize() const;
 149
 150   // TODO(jri): AddSavedFrame calls AddFrame, which only saves the frame
 151   // if it is a stream frame, not other types of frames. Fix this API;
 152   // add a AddNonSavedFrame method.
 153   // Adds |frame| to the packet creator's list of frames to be serialized.
 154   // Returns false if the frame doesn't fit into the current packet.
 155   bool AddSavedFrame(const QuicFrame& frame);
 156
 157   // Serializes all frames which have been added and adds any which should be
 158   // retransmitted to |retransmittable_frames| if it's not nullptr. All frames
 159   // must fit into a single packet. Sets the entropy hash of the serialized
 160   // packet to a random bool and returns that value as a member of
 161   // SerializedPacket. Also, sets |serialized_frames| in the SerializedPacket to
 162   // the corresponding RetransmittableFrames if any frames are to be
 163   // retransmitted.
 164   SerializedPacket SerializePacket();
 165
 166   // Packetize FEC data. All frames must fit into a single packet. Also, sets
 167   // the entropy hash of the serialized packet to a random bool and returns
 168   // that value as a member of SerializedPacket.
 169   SerializedPacket SerializeFec();
 170
 171   // Creates a packet with connection close frame. Caller owns the created
 172   // packet. Also, sets the entropy hash of the serialized packet to a random
 173   // bool and returns that value as a member of SerializedPacket.
 174   SerializedPacket SerializeConnectionClose(
 175       QuicConnectionCloseFrame* close_frame);
 176
 177   // Creates a version negotiation packet which supports |supported_versions|.
 178   // Caller owns the created  packet. Also, sets the entropy hash of the
 179   // serialized packet to a random bool and returns that value as a member of
 180   // SerializedPacket.
 181   QuicEncryptedPacket* SerializeVersionNegotiationPacket(
 182       const QuicVersionVector& supported_versions);
 183
 184   // Sets the encryption level that will be applied to new packets.
 185   void set_encryption_level(EncryptionLevel level) {
 186     encryption_level_ = level;
 187   }
 188
 189   // Sequence number of the last created packet, or 0 if no packets have been
 190   // created.
 191   QuicPacketSequenceNumber sequence_number() const {
 192     return sequence_number_;
 193   }
 194
 195   void set_sequence_number(QuicPacketSequenceNumber s) {
 196     sequence_number_ = s;
 197   }
 198
 199   QuicConnectionIdLength connection_id_length() const {
 200     return connection_id_length_;
 201   }
 202
 203   void set_connection_id_length(QuicConnectionIdLength length) {
 204     connection_id_length_ = length;
 205   }
 206
 207   QuicSequenceNumberLength next_sequence_number_length() const {
 208     return next_sequence_number_length_;
 209   }
 210
 211   void set_next_sequence_number_length(QuicSequenceNumberLength length) {
 212     next_sequence_number_length_ = length;
 213   }
 214
 215   size_t max_packet_length() const {
 216     return max_packet_length_;
 217   }
 218
 219   void set_max_packet_length(size_t length) {
 220     // |max_packet_length_| should not be changed mid-packet or mid-FEC group.
 221     DCHECK(fec_group_.get() == nullptr && queued_frames_.empty());
 222     max_packet_length_ = length;
 223   }
 224
 225   // Returns current max number of packets covered by an FEC group.
 226   size_t max_packets_per_fec_group() const {
 227       return max_packets_per_fec_group_;
 228   }
 229
 230   // Sets creator's max number of packets covered by an FEC group.
 231   // Note: While there are no constraints on |max_packets_per_fec_group|,
 232   // this setter enforces a min value of kLowestMaxPacketsPerFecGroup.
 233   // To turn off FEC protection, use StopFecProtectingPackets().
 234   void set_max_packets_per_fec_group(size_t max_packets_per_fec_group);
 235
 236  private:
 237   friend class test::QuicPacketCreatorPeer;
 238
 239   static bool ShouldRetransmit(const QuicFrame& frame);
 240
 241   // Updates sequence number and max packet lengths on a packet or FEC group
 242   // boundary.
 243   void MaybeUpdateLengths();
 244
 245   // Updates lengths and also starts an FEC group if FEC protection is on and
 246   // there is not already an FEC group open.
 247   InFecGroup MaybeUpdateLengthsAndStartFec();
 248
 249   void FillPacketHeader(QuicFecGroupNumber fec_group,
 250                         bool fec_flag,
 251                         QuicPacketHeader* header);
 252
 253   // Allows a frame to be added without creating retransmittable frames.
 254   // Particularly useful for retransmits using SerializeAllFrames().
 255   bool AddFrame(const QuicFrame& frame, bool save_retransmittable_frames);
 256
 257   // Adds a padding frame to the current packet only if the current packet
 258   // contains a handshake message, and there is sufficient room to fit a
 259   // padding frame.
 260   void MaybeAddPadding();
 261
 262   QuicConnectionId connection_id_;
 263   EncryptionLevel encryption_level_;
 264   QuicFramer* framer_;
 265   scoped_ptr<QuicRandomBoolSource> random_bool_source_;
 266   QuicPacketSequenceNumber sequence_number_;
 267   // If true, any created packets will be FEC protected.
 268   bool should_fec_protect_;
 269   QuicFecGroupNumber fec_group_number_;
 270   scoped_ptr<QuicFecGroup> fec_group_;
 271   // Controls whether protocol version should be included while serializing the
 272   // packet.
 273   bool send_version_in_packet_;
 274   // Maximum length including headers and encryption (UDP payload length.)
 275   size_t max_packet_length_;
 276   // 0 indicates FEC is disabled.
 277   size_t max_packets_per_fec_group_;
 278   // Length of connection_id to send over the wire.
 279   QuicConnectionIdLength connection_id_length_;
 280   // Staging variable to hold next packet sequence number length. When sequence
 281   // number length is to be changed, this variable holds the new length until
 282   // a packet or FEC group boundary, when the creator's sequence_number_length_
 283   // can be changed to this new value.
 284   QuicSequenceNumberLength next_sequence_number_length_;
 285   // Sequence number length for the current packet and for the current FEC group
 286   // when FEC is enabled. Mutable so PacketSize() can adjust it when the packet
 287   // is empty.
 288   mutable QuicSequenceNumberLength sequence_number_length_;
 289   // packet_size_ is mutable because it's just a cache of the current size.
 290   // packet_size should never be read directly, use PacketSize() instead.
 291   mutable size_t packet_size_;
 292   QuicFrames queued_frames_;
 293   scoped_ptr<RetransmittableFrames> queued_retransmittable_frames_;
 294
 295   DISALLOW_COPY_AND_ASSIGN(QuicPacketCreator);
 296 };
 297
 298 }  // namespace net
 299
 300 #endif  // NET_QUIC_QUIC_PACKET_CREATOR_H_