Protobuf for Traffic Annotation and first use by a URLFetcher.

net/traffic_annotation/network_traffic_annotation.h

Index: net/traffic_annotation/network_traffic_annotation.h
diff --git a/net/traffic_annotation/network_traffic_annotation.h b/net/traffic_annotation/network_traffic_annotation.h
new file mode 100644
index 0000000000000000000000000000000000000000..f4314f0ec3c2fb4a320ec29f19122de308067bef
--- /dev/null
+++ b/net/traffic_annotation/network_traffic_annotation.h
@@ -0,0 +1,75 @@
+// Copyright (c) 2016 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_TRAFFIC_ANNOTATION_NETWORK_TRAFFIC_ANNOTATION_H_
+#define NET_TRAFFIC_ANNOTATION_NETWORK_TRAFFIC_ANNOTATION_H_
+
+namespace {
+
+// Recuresively compute hash code of the given string as a constant expression.
+template <int N>
+static constexpr unsigned int recursive_hash(const char* str) {
+  return (unsigned int)(recursive_hash<N - 1>(str) * 31 + str[N]) % 138003713;
+}
+
+// Recursion stopper for the above function.
+template <>
+constexpr unsigned int recursive_hash<-1>(const char* str) {
+  return 7;
+}
+
+// Entry point to function that computes hash as constant expression.
+#define COMPUTE_STRING_HASH(S) recursive_hash<sizeof(S)>(S)
+
+}  //  namespace
+
+namespace net {
+
+// Defined type for network traffic annotation tags.
+typedef const unsigned int NetworkTrafficAnnotationTag;

[asanka, 2017/01/26 20:59:28]

using NetworkTrafficAnnotationTag = ...

Also, use a fixed sized type if you want this tag to be comparable across
platforms.

[Ramin Halavati, 2017/01/27 07:48:58]

Done.

+
+// Function to convert a network traffic annotation's unique id and protobuf
+// text into a NetworkTrafficAnnotationTag.
+//
+// This function serves as a tag that can be discovered and extracted via
+// clang tools. This allows reviewing all network traffic that is generated
+// and annotated by Chrome.
+//
+// |unique_id| should be a string that uniquely identifies this annotation
+// across all of Chromium source code.
+// |proto| is a text-encoded NetworkTrafficAnnotation protobuf (see
+// tools/traffic_annotaiton/traffic_annotation.proto)
+//
+// This function should be called with inlined parameters like
+//    NetworkTrafficAnnotationTag tag = DefineNetworkTrafficAnnotation(
+//        "unique_tag_id",
+//        R"(semantics: {...}
+//           policy: {...}
+//        )");
+// This allows the compiler to calculate and extract the hashed |unique_id|
+// at compile time without copying the entire protobuf into the text segment
+// of the binary or creating any runtime performance impact.
+//
+// Please do NOT use the following syntax:
+//   const char* proto = R("...");
+//   NetworkTrafficAnnotationTag tag = DefineNetworkTrafficAnnotation(
+//       "unique_tag_id", proto);
+constexpr NetworkTrafficAnnotationTag DefineNetworkTrafficAnnotation(
+    const char* unique_id,

[asanka, 2017/01/26 20:59:28]

Actually, if the intention is to introduce a parameter that can:
 * Be passed around by value.
 * Can only be created by DefineNetworkTrafficAnnotation()
 * Doesn't depend on |proto| so that the compiler can optimize out the proto

then why not just introduce some class with a private constexpr constructor
that's a friend of DefineNetworkTrafficAnnotation()? It doesn't need to contain
anything unique or significant.

[Ramin Halavati, 2017/01/27 07:48:58]

|unique_id|s have two purposes here:
1- They stay in the binary and can be used for auditing purposes and reporting.
2- They remain constant even if the content of proto changes in later revisions
and make reviews and tracking changes easier.

In this respect, I don't see why defining a class would be a better choice.

[asanka, 2017/01/27 16:58:00]

Using typed ints (a.la enum NetworkTrafficAnnotationTag : uint32_t {}) or a POD
class with a single uint32_t member would make it less possible to pass in, say,
0 as the tag.

[Ramin Halavati, 2017/01/30 08:43:25]

I am not sure if I got your concern clearly. Now that annotation tag is changed
to "const char *", is it still an issue?

+    const char* proto) {
+  return (NetworkTrafficAnnotationTag)COMPUTE_STRING_HASH(unique_id);

[asanka, 2017/01/26 20:59:28]

sizeof(unique_id) == sizeof(const char*) here.

[Ramin Halavati, 2017/01/27 07:48:58]

Yes, but we want the |unique_id| to be kept in the binary and the text to be
removed by the optimizer.

[asanka, 2017/01/27 16:58:00]

Sure, but what I was pointing out was that you are only hashing size(const
char*) bytes of the |unique_id|. sizeof(unique_id) doesn't get you the length of
the string.

[Ramin Halavati, 2017/01/30 08:43:25]

Acknowledged.

+}
+
+// Placeholder for unannotated usages.
+#define NO_TRAFFIC_ANNOTATION_YET \
+  net::DefineNetworkTrafficAnnotation("Undefined", "Nothing here yet.")
+
+// Macro for unit tests traffic annotations.
+#define TRAFFIC_ANNOTATION_FOR_TESTS   \
+  net::DefineNetworkTrafficAnnotation( \
+      "UnitTest", "Traffic annotation for unit, browser and other tests")
+
+}  // namespace net
+
+#endif  // NET_TRAFFIC_ANNOTATION_NETWORK_TRAFFIC_ANNOTATION_H_