filters: support new platform ResumeIteration status (#1100)

Description: Adds support for resuming iteration to platform filters via a new *ResumeIteration filter status. The API for platform filters requires all HTTP entities that should be forwarded to be attached to a result status of a filter invocation. When iteration is stopped, previous entities that were not forwarded may now be attached to the special ResumeIteration status, e.g., pending headers might be attached to ResumeIteration returned during an on-data invocation. See code documentation for additional detail. Full API documentation will be included in an upcoming PR.
Risk Level: Moderate
Testing: Unit tests

Signed-off-by: Mike Schore <mike.schore@gmail.com>

library/common/extensions/filters/http/platform_bridge/BUILD

@@ -10,7 +10,7 @@ api_proto_package()
 envoy_cc_library(
     name = "platform_bridge_filter_lib",
     srcs = [
-        "c_types.cc",
+        "c_type_definitions.h",
         "filter.cc",
     ],
     hdrs = [

library/common/extensions/filters/http/platform_bridge/c_types.cc → library/common/extensions/filters/http/platform_bridge/c_type_definitions.h

@@ -1,8 +1,8 @@
 // NOLINT(namespace-envoy)
-#include "library/common/extensions/filters/http/platform_bridge/c_types.h"
-
 #include "envoy/http/filter.h"
 
+#include "library/common/extensions/filters/http/platform_bridge/c_types.h"
+
 const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusContinue =
     static_cast<envoy_filter_headers_status_t>(Envoy::Http::FilterHeadersStatus::Continue);
 const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusStopIteration =
@@ -13,15 +13,34 @@ const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusContinueAndEndStrea
 const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusStopAllIterationAndBuffer =
     static_cast<envoy_filter_headers_status_t>(
         Envoy::Http::FilterHeadersStatus::StopAllIterationAndBuffer);
+// ResumeIteration is not a status supported by Envoy itself, and only has relevance in Envoy
+// Mobile's implementation of platform filters.
+//
+// Regarding enum values, the C++11 standard (7.2/2) states:
+//   If the first enumerator has no initializer, the value of the corresponding constant is zero.
+//   An enumerator-definition without an initializer gives the enumerator the value obtained by
+//   increasing the value of the previous enumerator by one.
+//
+// Creating a new return status like this is brittle, but at least somewhat more resilient to
+// a new status being added in Envoy, since it won't overlap as long as the new status is added
+// rather than prepended.
+const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusResumeIteration =
+    kEnvoyFilterHeadersStatusContinue - 1;
 
 const envoy_filter_data_status_t kEnvoyFilterDataStatusContinue =
     static_cast<envoy_filter_data_status_t>(Envoy::Http::FilterDataStatus::Continue);
 const envoy_filter_data_status_t kEnvoyFilterDataStatusStopIterationAndBuffer =
     static_cast<envoy_filter_data_status_t>(Envoy::Http::FilterDataStatus::StopIterationAndBuffer);
 const envoy_filter_data_status_t kEnvoyFilterDataStatusStopIterationNoBuffer =
     static_cast<envoy_filter_data_status_t>(Envoy::Http::FilterDataStatus::StopIterationNoBuffer);
+// See comment above.
+const envoy_filter_data_status_t kEnvoyFilterDataStatusResumeIteration =
+    kEnvoyFilterDataStatusContinue - 1;
 
 const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusContinue =
     static_cast<envoy_filter_trailers_status_t>(Envoy::Http::FilterTrailersStatus::Continue);
 const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusStopIteration =
     static_cast<envoy_filter_trailers_status_t>(Envoy::Http::FilterTrailersStatus::StopIteration);
+// See comment above.
+const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusResumeIteration =
+    kEnvoyFilterTrailersStatusContinue - 1;

library/common/extensions/filters/http/platform_bridge/c_types.h

@@ -4,6 +4,16 @@
 
 // NOLINT(namespace-envoy)
 
+/**
+ * Convenience constant indicating no changes to data.
+ */
+extern const envoy_data envoy_unaltered_data;
+
+/**
+ * Convenience constant indicating no changes to headers.
+ */
+extern const envoy_headers envoy_unaltered_headers;
+
 /**
  * Return codes for on-headers filter invocations. @see envoy/http/filter.h
  */
@@ -12,6 +22,9 @@ extern const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusContinue;
 extern const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusStopIteration;
 extern const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusContinueAndEndStream;
 extern const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusStopAllIterationAndBuffer;
+// Note this return status is unique to platform filters and used only to resume iteration after
+// it has been previously stopped.
+extern const envoy_filter_headers_status_t kEnvoyFilterHeadersStatusResumeIteration;
 
 /**
  * Compound return type for on-headers filter invocations.
@@ -28,13 +41,17 @@ typedef int envoy_filter_data_status_t;
 extern const envoy_filter_data_status_t kEnvoyFilterDataStatusContinue;
 extern const envoy_filter_data_status_t kEnvoyFilterDataStatusStopIterationAndBuffer;
 extern const envoy_filter_data_status_t kEnvoyFilterDataStatusStopIterationNoBuffer;
+// Note this return status is unique to platform filters and used only to resume iteration after
+// it has been previously stopped.
+extern const envoy_filter_data_status_t kEnvoyFilterDataStatusResumeIteration;
 
 /**
  * Compound return type for on-data filter invocations.
  */
 typedef struct {
   envoy_filter_data_status_t status;
   envoy_data data;
+  envoy_headers* pending_headers;
 } envoy_filter_data_status;
 
 /**
@@ -43,13 +60,18 @@ typedef struct {
 typedef int envoy_filter_trailers_status_t;
 extern const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusContinue;
 extern const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusStopIteration;
+// Note this return status is unique to platform filters and used only to resume iteration after
+// it has been previously stopped.
+extern const envoy_filter_trailers_status_t kEnvoyFilterTrailersStatusResumeIteration;
 
 /**
  * Compound return type for on-trailers filter invocations.
  */
 typedef struct {
   envoy_filter_trailers_status_t status;
   envoy_headers trailers;
+  envoy_headers* pending_headers;
+  envoy_data* pending_data;
 } envoy_filter_trailers_status;
 
 #ifdef __cplusplus