Add functions used for building WebSocket frame data.

net/websockets/websocket_frame_builder.h

+// 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_WEBSOCKETS_WEBSOCKET_FRAME_BUILDER_H_
+#define NET_WEBSOCKETS_WEBSOCKET_FRAME_BUILDER_H_
+#pragma once
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/scoped_vector.h"
+#include "net/base/net_export.h"
+#include "net/websockets/websocket_frame.h"
+
+namespace net {
+
+// Builds byte-stream data from WebSocket frame chunks.
+
+class NET_EXPORT_PRIVATE WebSocketFrameBuilder {
+ public:
+  WebSocketFrameBuilder();
+  ~WebSocketFrameBuilder();
+
+  // Encodes the given frame chunks into byte stream.
+  //
+  // If the builder finds an error in |frame_chunks|, Encode() returns false
+  // and the builder goes into "failed" state. Once the builder fails, it will
+  // no longer accept any new frame chunks and Encode() will always fail.
+  //
+  // Note that a logical error in |frame_chunks| (like payload length mismatch)
+  // causes a DCHECK failure, so users of this class need to make sure
+  // |frame_chunks| follow the restrictions documented in websocket_frame.h.
+  //
+  // For each new frame, Encode() will pick a random masking key in
+  // a cryptographically secure manner (unless PinMaskingKeyForTesting() was
+  // not called before).
+  bool Encode(ScopedVector<WebSocketFrameChunk> frame_chunks,

[willchan no longer on Chromium, 2012/05/16 03:12:54]

I'd prefer not to use .Pass() stuff here. I'd like to keep that only for use for
base::Bind() stuff. When I read this function signature, it's not obvious to me
that ScopedVector isn't just being copied. That's indeed what it looks like.

Can you just pass this in as a ScopedVector<WebSocketFrameChunk>*?

Also, it's not obvious to me why this isn't a const member function. I don't see
why there's any state. Actually, perhaps this is better as a class static
function.

+              std::vector<char>* output);

[mmenke, 2012/05/15 18:36:31]

I think it makes sense to basically redocument some of WebsocketFrame here,
because it's not terribly obvious.  Namely:

1)  Must take all chunks from a single frame before receiving chunks from any
other frame.
2)  Only first chunk may have a header (And it must have a header).
3)  Final frame must have final bit set (This is pretty obvious, given the other
two, I suppose).

+
+  // Returns true if the builder has ever failed to encode frame data.
+  bool failed() const { return failed_; }

[willchan no longer on Chromium, 2012/05/16 03:12:54]

Is this only for testing? If so, I don't really see why it's useful since
Encode() already has a return value for this.

+
+  // Pins the masking key for future frames to a specific value.
+  //
+  // |masking_key| must be 4-byte data. As the name suggests, this function is
+  // exposed only for testing purposes.
+  void PinMaskingKeyForTesting(const char masking_key[]);

[mmenke, 2012/05/15 18:36:31]

Call me paranoid, but I'd rather this be private, and the necessary test classes
friended.

+
+ private:
+  // Encodes the frame header and writes the result to |output|.
+  //
+  // This function returns true if it has encoded the header successfully.
+  bool EncodeFrameHeader(WebSocketFrameHeader* header,
+                         std::vector<char>* output) const;
+
+  // Generates a new masking key and sets it in masking_key_. If
+  // has_pinned_masking_key_for_testing_ is true, the function uses the pinned
+  // key instead of generating a random one.
+  void GenerateNewMaskingKey();
+
+  // Masks the payload with masking_key_. |payload| must be the payload data
+  // starting at |frame_offset_|.
+  void MaskPayload(std::vector<char>* payload);
+
+  // Clears the information of the current frame and turns the |failed_| bit on.
+  void Fail();
+
+  scoped_ptr<WebSocketFrameHeader> current_frame_header_;
+  char masking_key_[WebSocketFrameHeader::kMaskingKeyLength];
+
+  uint64 frame_offset_;
+
+  char pinned_masking_key_for_testing_[WebSocketFrameHeader::kMaskingKeyLength];
+  bool has_pinned_masking_key_for_testing_;
+
+  bool failed_;
+
+  DISALLOW_COPY_AND_ASSIGN(WebSocketFrameBuilder);
+};
+
+}  // namespace net
+
+#endif  // NET_WEBSOCKETS_WEBSOCKET_FRAME_BUILDER_H_