Add QuicFramer and friends.

net/quic/quic_framer.h

Index: net/quic/quic_framer.h
diff --git a/net/quic/quic_framer.h b/net/quic/quic_framer.h
new file mode 100644
index 0000000000000000000000000000000000000000..494cf57739ba0c96cfa63cae41ad4894fe22b3b1
--- /dev/null
+++ b/net/quic/quic_framer.h
@@ -0,0 +1,203 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef NET_QUIC_QUIC_FRAMER_H_
+#define NET_QUIC_QUIC_FRAMER_H_
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/logging.h"
+#include "base/memory/scoped_ptr.h"
+#include "net/quic/crypto/quic_decrypter.h"
+#include "net/quic/crypto/quic_encrypter.h"
+#include "net/base/ip_endpoint.h"
+#include "base/string_piece.h"

[jar (doing other things), 2012/10/14 23:04:38]

nit: alphabetize last two lines

[Ryan Hamilton, 2012/10/15 21:22:08]

Done.

+
+namespace net {
+
+class QuicEncrypter;
+class QuicDecrypter;
+class QuicFramer;
+class QuicDataReader;
+class QuicDataWriter;
+
+class QuicFramerVisitorInterface {
+ public:
+  virtual ~QuicFramerVisitorInterface() {}
+
+  // Called if an error is detected in the QUIC protocol.
+  virtual void OnError(QuicFramer* framer) = 0;
+
+  // Called when a new packet has been recieved.

[jar (doing other things), 2012/10/14 23:04:38]

Clarification: Is this called when the packet is received, but before
authentication etc?  After auth, but before processing? After processing?

[Ryan Hamilton, 2012/10/15 21:22:08]

Commented.

+  virtual void OnPacket(const IPEndPoint& peer_address) = 0;
+
+  // Called when the header of a packet had been parsed.
+  // If OnPacketHeader returns false, framing for this packet will cease.
+  virtual bool OnPacketHeader(const QuicPacketHeader& header) = 0;
+
+  // Called when a data packet is parsed that is part of an FEC group.
+  // |payload| is the non-encrypted FEC protected payload of the packet.

[jar (doing other things), 2012/10/14 23:04:38]

Due to out-of-order receipt, even with FECs only across consecutive packets, it
is possible for participants for more than one FEC group to appear.  How is this
handled?

[Ryan Hamilton, 2012/10/15 21:22:08]

In the code not committed as part of this CL, we maintain a collection of "open"
fec groups.  But this code is not being committed as part of this cl.

+  virtual void OnFecProtectedPayload(base::StringPiece payload) = 0;
+
+  // Called when a StreamFragment has been parsed.
+  virtual void OnStreamFragment(const QuicStreamFragment& fragment) = 0;
+
+  // Called when a AckFragment has been parsed.
+  virtual void OnAckFragment(const QuicAckFragment& fragment) = 0;
+
+  // Called when a RstStreamFragment has been parsed.
+  virtual void OnRstStreamFragment(
+      const QuicRstStreamFragment& fragment) = 0;
+
+  // Called when a ConnectionCloseFragment has been parsed.
+  virtual void OnConnectionCloseFragment(
+      const QuicConnectionCloseFragment& fragment) = 0;
+
+  // Called when FEC data has been parsed.

[jar (doing other things), 2012/10/14 23:04:38]

Same question about which FEC group is being handled.  Is that apparent in the
parameter?

[Ryan Hamilton, 2012/10/15 21:22:08]

It is in the packet header that was passed in during OnPacketHeader().

+  virtual void OnFecData(const QuicFecData& fec) = 0;
+
+  // Called when a packet has been completely processed.
+  virtual void OnPacketComplete() = 0;
+};
+
+class QuicFecBuilderInterface {
+ public:
+  virtual ~QuicFecBuilderInterface() {}
+
+  // Called when a data packet is constructed that is part of an FEC group.
+  // |payload| is the non-encrypted FEC protected payload of the packet.
+  virtual void OnBuiltFecProtectedPayload(const QuicPacketHeader& header,
+                                          base::StringPiece payload) = 0;
+};
+
+class QuicFramer {
+ public:
+  // Constructs a new framer that will own |decrypter| and |encrypter|.
+  QuicFramer(QuicDecrypter* decrypter, QuicEncrypter* encrypter);
+
+  virtual ~QuicFramer();
+
+  // Set callbacks to be called from the framer.  A visitor must be set, or
+  // else the framer will likely crash.  It is acceptable for the visitor
+  // to do nothing.  If this is called multiple times, only the last visitor
+  // will be used.
+  void set_visitor(QuicFramerVisitorInterface* visitor) {

[jar (doing other things), 2012/10/14 23:04:38]

I wasn't familiar with the term visitor.  Is this kindred to an observer?

[Ryan Hamilton, 2012/10/15 21:22:08]

Yes.

+    visitor_ = visitor;
+  }
+
+  // Set a builder to be called from the framer when building FEC protected

[jar (doing other things), 2012/10/14 23:04:38]

It would be helpful to have the terms builder, framer, and visitor discussed in
a top level comment, so as to provide context. Is this actually done in some
other file?

[Ryan Hamilton, 2012/10/15 21:22:08]

Added a comment.

+  // packets.  If this is called multiple times, only the last builder
+  // will be used.  The builder need not be set.
+  void set_fec_builder(QuicFecBuilderInterface* builder) {
+    fec_builder_ = builder;
+  }
+
+  QuicErrorCode error() const {
+    return error_;
+  }
+
+  // Pass a UDP packet into the framer for parsing.
+  // Return true if the packet was processed succesfully. |packet| must be a
+  // single, complete UDP packet (not a fragment of a packet).  This packet
+  // might be null padded past the end of the payload, which will be correctly
+  // ignored.
+  bool ProcessPacket(const IPEndPoint& client_address,
+                     const QuicEncryptedPacket& packet);
+
+  // Pass a revived data packet into the framer for parsing.

[jar (doing other things), 2012/10/14 23:04:38]

I'm guessing that "revived" means "result of FEC based reconstruction," but it
would be good to clarify this.

[Ryan Hamilton, 2012/10/15 21:22:08]

Done.

+  // Return true if the packet was processed succesfully. |payload| must be
+  // the complete DECRYPTED payload of the revived packet.
+  bool ProcessRevivedPacket(const IPEndPoint& client_address,

[jar (doing other things), 2012/10/14 23:04:38]

I understood why the regular packet included IPEndPoints, but was not clear as
to how a reconstructed packet would also have such.  Note that it is possible
for the FEC contributors to have distinct IPEndPoints.

[Ryan Hamilton, 2012/10/15 21:22:08]

If the FEC packet were the first packet received from a new IP address we need
to make sure that we take account of the new IP.

[jar (doing other things), 2012/10/16 19:24:00]

hmm....

You're suggesting that the revived packet should have the IP address of the last
packet in an FEC group?  That might (for example) mean that a lost 2nd packet
among an FEC group of 6 would have a "new IP address" even if packets numbered
3-5 don't.  I'd expect this to cause confusion in the return address algorithm.

What am I missing? 

[Ryan Hamilton, 2012/10/16 19:43:23]

In my example, I was suggesting that the last received packet in the group was
the FEC packet.  In this example, I was also suggesting that it was the first
packet from the new IP.  In the case, I wanted to make sure that that Visitor
got the new IP along with the revived packet.

Am I misunderstanding your question?

+                            const QuicPacketHeader& header,
+                            base::StringPiece payload);
+
+  // Creates a new QuicPacket populated with the fields in |header| and
+  // |fragments|.  Assigns |*packet| to the address of the new object.
+  // Returns true upon success.

[jar (doing other things), 2012/10/14 23:04:38]

Is it assumed that the input is sized perfectly to fit into this next next
packet?  What happens if the the input is too small, or too large?

[Ryan Hamilton, 2012/10/15 21:22:08]

If the packet can not be constructed as requested, this method will return
false.

+  bool ConstructFragementDataPacket(const QuicPacketHeader& header,
+                                    const QuicFragments& fragments,
+                                    QuicPacket** packet);
+
+  // Creates a new QuicPacket populated with the fields in |header| and
+  // |fec|.  Assigns |*packet| to the address of the new object.
+  // Returns true upon success.
+  bool ConstructFecPacket(const QuicPacketHeader& header,
+                          const QuicFecData& fec,
+                          QuicPacket** packet);
+
+  // Increments the retransmission count by one, and updates the authentication
+  // hash accordingly.
+  void IncrementRetransmitCount(QuicPacket* packet);
+
+  uint8 GetRetransmitCount(QuicPacket* packet);
+
+  void WriteTransmissionTime(QuicTransmissionTime time, QuicPacket* packet);
+
+  // Returns a new encrypted packet, owned by the caller.
+  QuicEncryptedPacket* EncryptPacket(const QuicPacket& packet);
+
+  // Returns the maximum length of plaintext that can be encrypted
+  // to ciphertext no larger than |ciphertext_size|.

[jar (doing other things), 2012/10/14 23:04:38]

Is this for a single UDP packet?

[Ryan Hamilton, 2012/10/15 21:22:08]

That is how this will be used, but this method does not explicitly encode that
knowledge.

+  size_t GetMaxPlaintextSize(size_t ciphertext_size);
+
+  const std::string& detailed_error() { return detailed_error_; }
+
+ private:
+  bool WritePacketHeader(const QuicPacketHeader& header,
+                         QuicDataWriter* builder);
+
+  bool ProcessPacketHeader(QuicPacketHeader* header,
+                           const QuicEncryptedPacket& packet);
+
+  bool ProcessFragmentData();
+  bool ProcessStreamFragment();
+  bool ProcessPDUFragment();
+  bool ProcessAckFragment(QuicAckFragment* fragment);
+  bool ProcessRstStreamFragment();
+  bool ProcessConnectionCloseFragment();
+
+  bool DecryptPayload(const QuicEncryptedPacket& packet);
+
+  // Computes the wire size in bytes of the payload of |fragment|.
+  size_t ComputeFragmentPayloadLength(const QuicFragment& fragment);
+
+  bool AppendStreamFragmentPayload(
+      const QuicStreamFragment& fragment,
+      QuicDataWriter* builder);
+  bool AppendAckFragmentPayload(
+      const QuicAckFragment& fragment,
+      QuicDataWriter* builder);
+  bool AppendRstStreamFragmentPayload(
+      const QuicRstStreamFragment& fragment,
+      QuicDataWriter* builder);
+  bool AppendConnectionCloseFragmentPayload(
+      const QuicConnectionCloseFragment& fragment,
+      QuicDataWriter* builder);
+  bool RaiseError(QuicErrorCode error);
+
+  void set_error(QuicErrorCode error) {
+    error_ = error;
+  }
+
+  void set_detailed_error(const char* error) {
+    detailed_error_ = error;
+  }
+
+  std::string detailed_error_;
+  scoped_ptr<QuicDataReader> reader_;
+  QuicFramerVisitorInterface* visitor_;
+  QuicFecBuilderInterface* fec_builder_;
+  QuicErrorCode error_;
+  // Buffer containing decrypted payload data during parsing.
+  scoped_ptr<QuicData> decrypted_;
+  // Decrypter used to decrypt packets during parsing.
+  scoped_ptr<QuicDecrypter> decrypter_;
+  // Encrypter used to encrypt packets via EncryptPacket().
+  scoped_ptr<QuicEncrypter> encrypter_;
+};

[jar (doing other things), 2012/10/14 23:04:38]

Should you have the macro to prevent copy constructors etc. from being
created?... or does this need to be handled by STL containers?

[Ryan Hamilton, 2012/10/15 21:22:08]

Done.

+
+}  // namespace net
+
+#endif  // NET_QUIC_QUIC_FRAMER_H_