docs/constraints: filter/fault.proto and filter/network/mongo_proxy.p… (#241)

This should provide an example of how to do the .proto doc linking,
refactoring and constraint addition for the full API.

Signed-off-by: Harvey Tuch <htuch@google.com>

api/BUILD

@@ -193,5 +193,6 @@ proto_library(
         ":eds",
         ":lds",
         ":rds",
+        "//api/filter/network:mongo_proxy",
     ],
 )

api/filter/BUILD

@@ -17,6 +17,7 @@ proto_library(
         "@com_google_protobuf//:struct_proto",
         "@com_google_protobuf//:timestamp_proto",
         "@com_google_protobuf//:wrappers_proto",
+        "@com_lyft_protoc_gen_validate//validate:validate_proto",
     ],
 )
 
@@ -31,6 +32,7 @@ go_proto_library(
         "@com_github_golang_protobuf//ptypes/struct:go_default_library",
         "@com_github_golang_protobuf//ptypes/timestamp:go_default_library",
         "@com_github_golang_protobuf//ptypes/wrappers:go_default_library",
+        "@com_lyft_protoc_gen_validate//validate:go_default_library",
     ],
 )
 

api/filter/fault.proto

@@ -5,6 +5,10 @@ option go_package = "filter";
 
 import "google/protobuf/duration.proto";
 
+import "validate/validate.proto";
+
+// [#protodoc-title: Common fault injection types]
+
 // Delay specification is used to inject latency into the
 // HTTP/gRPC/Mongo/Redis operation or delay proxying of TCP connections.
 message FaultDelay {
@@ -18,7 +22,7 @@ message FaultDelay {
 
   // An integer between 0-100 indicating the percentage of operations/connection requests
   // on which the delay will be injected.
-  uint32 percent = 2;
+  uint32 percent = 2 [(validate.rules).uint32.lte = 100];
 
   oneof fault_delay_type {
     // Add a fixed delay before forwarding the operation upstream. See
@@ -26,7 +30,7 @@ message FaultDelay {
     // the JSON/YAML Duration mapping. For HTTP/Mongo/Redis, the specified
     // delay will be injected before a new request/operation. For TCP
     // connections, the proxying of the connection upstream will be delayed
-    // for the specified period. REQUIRED.
-    google.protobuf.Duration fixed_delay = 3;
+    // for the specified period. This is required if type is FIXED.
+    google.protobuf.Duration fixed_delay = 3 [(validate.rules).duration.gt = {}];
   }
 }

api/filter/network/BUILD

@@ -23,6 +23,7 @@ proto_library(
         "@com_google_protobuf//:struct_proto",
         "@com_google_protobuf//:timestamp_proto",
         "@com_google_protobuf//:wrappers_proto",
+        "@com_lyft_protoc_gen_validate//validate:validate_proto",
         "@googleapis//:http_api_protos_lib",
     ],
 )
@@ -40,6 +41,7 @@ go_proto_library(
         "@com_github_golang_protobuf//ptypes/struct:go_default_library",
         "@com_github_golang_protobuf//ptypes/timestamp:go_default_library",
         "@com_github_golang_protobuf//ptypes/wrappers:go_default_library",
+        "@com_lyft_protoc_gen_validate//validate:go_default_library",
         "@org_golang_google_genproto//googleapis/api/annotations:go_default_library",
     ],
 )

api/filter/network/mongo_proxy.proto

@@ -4,14 +4,19 @@ package envoy.api.v2.filter.network;
 
 import "api/filter/fault.proto";
 
+import "validate/validate.proto";
+
+// [#protodoc-title: Mongo proxy]
+// MongoDB :ref:`configuration overview <config_network_filters_mongo_proxy>`.
+
 message MongoProxy {
-  // The human readable prefix to use when emitting statistics for the
-  // MongoDB proxy filter. See the statistics documentation for more information.
-  string stat_prefix = 1;
+  // The human readable prefix to use when emitting :ref:`statistics
+  // <config_network_filters_mongo_proxy_stats>`.
+  string stat_prefix = 1 [(validate.rules).string.min_len = 1];
 
   // The optional path to use for writing Mongo access logs. If not access log
   // path is specified no access logs will be written. Note that access log is
-  // also gated by runtime.
+  // also gated :ref:`runtime <config_network_filters_mongo_proxy_runtime>`.
   string access_log = 2;
 
   // Inject a fixed delay before proxying a Mongo operation. Delays are

docs/build.sh

@@ -12,7 +12,6 @@ mkdir -p "${DOCS_OUTPUT_DIR}"
 
 rm -rf "${GENERATED_RST_DIR}"
 mkdir -p "${GENERATED_RST_DIR}"
-rsync -av "${SCRIPT_DIR}"/root/ "${SCRIPT_DIR}"/conf.py "${GENERATED_RST_DIR}"
 
 if [ ! -d "${BUILD_DIR}"/venv ]; then
   virtualenv "${BUILD_DIR}"/venv --no-site-packages
@@ -29,15 +28,23 @@ bazel --batch build ${BAZEL_BUILD_OPTIONS} //api --aspects \
 PROTO_RST="
   /api/address/api/address.proto.rst
   /api/base/api/base.proto.rst
+  /api/filter/fault/api/filter/fault.proto.rst
+  /api/filter/network/mongo_proxy/api/filter/network/mongo_proxy.proto.rst
 "
 
+# Dump all the generated RST so they can be added to PROTO_RST easily.
+find -L bazel-bin -name "*.proto.rst"
+
 # Only copy in the protos we care about and know how to deal with in protodoc.
 for p in $PROTO_RST
 do
-  mkdir -p "$(dirname "${GENERATED_RST_DIR}/$p")"
-  cp -f bazel-bin/"${p}" "${GENERATED_RST_DIR}/$p"
+  DEST="${GENERATED_RST_DIR}/api-v2/$(sed -e 's#/api.*/api/##' <<< "$p")"
+  mkdir -p "$(dirname "${DEST}")"
+  cp -f bazel-bin/"${p}" "${DEST}"
 done
 
+rsync -av "${SCRIPT_DIR}"/root/ "${SCRIPT_DIR}"/conf.py "${GENERATED_RST_DIR}"
+
 BUILD_SHA=$(git rev-parse HEAD)
 [[ -z "${ENVOY_DOCS_VERSION_STRING}" ]] && ENVOY_DOCS_VERSION_STRING=data-plane-api-"${BUILD_SHA:0:6}"
 [[ -z "${ENVOY_DOCS_RELEASE_LEVEL}" ]] && ENVOY_DOCS_RELEASE_LEVEL=pre-release

docs/root/api-v1/api.rst

@@ -0,0 +1,8 @@
+Envoy v1 API reference
+======================
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  network_filters/network_filters

docs/root/api-v1/network_filters/mongo_proxy_filter.rst

@@ -0,0 +1,53 @@
+.. _config_network_filters_mongo_proxy_v1:
+
+Mongo proxy
+===========
+
+MongoDB :ref:`configuration overview <config_network_filters_mongo_proxy>`.
+
+.. code-block:: json
+
+  {
+    "name": "mongo_proxy",
+    "config": {
+      "stat_prefix": "...",
+      "access_log": "...",
+      "fault": {}
+    }
+  }
+
+stat_prefix
+  *(required, string)* The prefix to use when emitting :ref:`statistics
+  <config_network_filters_mongo_proxy_stats>`.
+
+access_log
+  *(optional, string)* The optional path to use for writing Mongo access logs. If not access log
+  path is specified no access logs will be written. Note that access log is also gated by
+  :ref:`runtime <config_network_filters_mongo_proxy_runtime>`.
+
+fault
+  *(optional, object)* If specified, the filter will inject faults based on the values in the object.
+
+Fault configuration
+-------------------
+
+Configuration for MongoDB fixed duration delays. Delays are applied to the following MongoDB
+operations: Query, Insert, GetMore, and KillCursors. Once an active delay is in progress, all
+incoming data up until the timer event fires will be a part of the delay.
+
+.. code-block:: json
+
+  {
+    "fixed_delay": {
+      "percent": "...",
+      "duration_ms": "..."
+    }
+  }
+
+percent
+  *(required, integer)* Probability of an eligible MongoDB operation to be affected by the
+  injected fault when there is no active fault. Valid values are integers in a range of [0, 100].
+
+duration_ms
+  *(required, integer)* Non-negative delay duration in milliseconds.
+

docs/root/api-v1/network_filters/network_filters.rst

@@ -0,0 +1,8 @@
+Network filters
+===============
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  *

docs/root/api-v2/api.rst

@@ -9,4 +9,5 @@ Envoy v2 API reference
   :glob:
   :maxdepth: 2
 
-  **
+  *
+  filter/filter

docs/root/api-v2/filter/filter.rst

@@ -0,0 +1,13 @@
+Filters
+=======
+
+.. CAUTION::
+  This documentation subtree is a work-in-progress and does not yet contain
+  complete documentation for the v2 API. Stay tuned for updates.
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  *
+  network/network

docs/root/api-v2/filter/network/network.rst

@@ -0,0 +1,12 @@
+Network filters
+===============
+
+.. CAUTION::
+  This documentation subtree is a work-in-progress and does not yet contain
+  complete documentation for the v2 API. Stay tuned for updates.
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  *

docs/root/configuration/network_filters/mongo_proxy_filter.rst

@@ -5,51 +5,8 @@ Mongo proxy
 
 MongoDB :ref:`architecture overview <arch_overview_mongo>`.
 
-.. code-block:: json
-
-  {
-    "name": "mongo_proxy",
-    "config": {
-      "stat_prefix": "...",
-      "access_log": "...",
-      "fault": {}
-    }
-  }
-
-stat_prefix
-  *(required, string)* The prefix to use when emitting :ref:`statistics
-  <config_network_filters_mongo_proxy_stats>`.
-
-access_log
-  *(optional, string)* The optional path to use for writing Mongo access logs. If not access log
-  path is specified no access logs will be written. Note that access log is also gated by
-  :ref:`runtime <config_network_filters_mongo_proxy_runtime>`.
-
-fault
-  *(optional, object)* If specified, the filter will inject faults based on the values in the object.
-
-Fault configuration
--------------------
-
-Configuration for MongoDB fixed duration delays. Delays are applied to the following MongoDB
-operations: Query, Insert, GetMore, and KillCursors. Once an active delay is in progress, all
-incoming data up until the timer event fires will be a part of the delay.
-
-.. code-block:: json
-
-  {
-    "fixed_delay": {
-      "percent": "...",
-      "duration_ms": "..."
-    }
-  }
-
-percent
-  *(required, integer)* Probability of an eligible MongoDB operation to be affected by the
-  injected fault when there is no active fault. Valid values are integers in a range of [0, 100].
-
-duration_ms
-  *(required, integer)* Non-negative delay duration in milliseconds.
+- :ref:`v1 API reference <config_network_filters_mongo_proxy_v1>`
+- :ref:`v2 API reference <envoy_api_msg_filter.network.MongoProxy>`
 
 .. _config_network_filters_mongo_proxy_stats:
 

docs/root/index.rst

@@ -19,4 +19,5 @@ Envoy documentation
   configuration/configuration
   operations/operations
   extending/extending
-  api/api
+  api-v1/api
+  api-v2/api

tools/protodoc/protodoc.py

@@ -506,12 +506,15 @@ def GenerateRst(proto_file):
   # Also extract file level titles if any.
   header, comment = FormatHeaderFromFile(
       '=', source_code_info.file_level_comment, proto_file.name)
+  package_prefix = NormalizeFQN('.' + proto_file.package + '.')
   msgs = '\n'.join(
-      FormatMessage(TypeContext(source_code_info, [4, index], msg.name), msg)
-      for index, msg in enumerate(proto_file.message_type))
+      FormatMessage(
+          TypeContext(source_code_info, [4, index], package_prefix + msg.name),
+          msg) for index, msg in enumerate(proto_file.message_type))
   enums = '\n'.join(
-      FormatEnum(TypeContext(source_code_info, [5, index], enum.name), enum)
-      for index, enum in enumerate(proto_file.enum_type))
+      FormatEnum(
+          TypeContext(source_code_info, [5, index], package_prefix + enum.name),
+          enum) for index, enum in enumerate(proto_file.enum_type))
   debug_proto = FormatProtoAsBlockComment(proto_file)
   return header + comment + msgs + enums  #+ debug_proto