Envoy's L7 Go extension API

api/BUILD

@@ -73,6 +73,7 @@ proto_library(
     visibility = ["//visibility:public"],
     deps = [
         "//contrib/envoy/extensions/filters/http/dynamo/v3:pkg",
+        "//contrib/envoy/extensions/filters/http/golang/v3alpha:pkg",
         "//contrib/envoy/extensions/filters/http/language/v3alpha:pkg",
         "//contrib/envoy/extensions/filters/http/squash/v3:pkg",
         "//contrib/envoy/extensions/filters/http/sxg/v3alpha:pkg",

api/contrib/envoy/extensions/filters/http/golang/v3alpha/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+        "@com_github_cncf_udpa//xds/annotations/v3:pkg",
+    ],
+)

api/contrib/envoy/extensions/filters/http/golang/v3alpha/golang.proto

@@ -0,0 +1,195 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.golang.v3alpha;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/struct.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.golang.v3alpha";
+option java_outer_classname = "GolangProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/golang/v3alpha";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: golang extension filter]
+// golang extension filter.
+//
+// In the below example, we configured the go plugin 'auth' and 'limit' dynamic libraries into
+// Envoy, which can avoid rebuilding Envoy.
+//
+// * Develop go-plugin
+//
+// We can implement the interface of :ref:`StreamFilter <contrib.go_plugin_api.plugin.StreamFilter>`
+// API by the GO language to achieve the effects of Envoy native filter.
+//
+// The filter based on the APIs implementation :ref:`StreamFilter <contrib.go_plugin_api.plugin.StreamFilter>`
+// For details, take a look at the :ref:`golang plugin filter sandbox example <install_sandboxes_golang>`.
+//
+// Then put the GO plugin source code into the ${OUTPUT}/src/ directory with the name of the plugin
+// for GO plugin builds.
+// The following examples implement limit and auth GO plugins.
+//
+// .. code-block:: bash
+//
+// $tree /home/admin/envoy/go-plugins/src/
+// |--auth
+// |   |--config.go
+// |   |--filter.go
+// ---limit
+//     |--config.go
+//     |--filter.go
+//
+// * Build go-plugin
+//
+// Build the Go plugin so by `go_plugin_generate.sh` script, below example the `liblimit.so` and
+// `libauth.so` will be generated in the `/home/admin/envoy/go-plugins/` directory.
+//
+// .. code-block:: bash
+//
+//   #!/bin/bash
+//   if [ $# != 2 ]; then
+//      echo "need input the go plugin name"
+//      exit 1
+//   fi
+//
+//   PLUGINNAME=$1
+//   OUTPUT=/home/admin/envoy/go-plugins/
+//   PLUGINSRCDIR=${OUTPUT}/src/${PLUGINNAME}
+//   go build --buildmode=c-shared  -v -o $OUTPUT/lib${PLUGINNAME}.so $PLUGINSRCDIR
+//
+// .. code-block:: bash
+//
+//   $go_plugin_generate.sh limit
+//   $go_plugin_generate.sh auth
+//
+// * Configure go-plugin
+//
+// Use the http filter of :ref: `golang <envoy.filters.http.golang>` to specify
+// :ref: `library` <envoy.filters.http.golang> in ingress and egress to enable the plugin.
+//
+// Example:
+//
+// .. code-block:: yaml
+//
+//   static_resources:
+//     listeners:
+//       - name: ingress
+//         address:
+//           socket_address:
+//             protocol: TCP
+//             address: 0.0.0.0
+//             port_value: 8080
+//         filter_chains:
+//           - filters:
+//               - name: envoy.filters.network.http_connection_manager
+//               ......
+//                   http_filters:
+//                     - name: envoy.filters.http.golang
+//                       typed_config:
+//                         "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
+//                         library: "/home/admin/envoy/go-plugins/liblimit.so"
+//                         plugine_name: limit
+//                         plugin_config:
+//                           "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.limit.v3.Config
+//                           xxx1: xx1
+//                           xxx2: xx2
+//                     - name: envoy.filters.http.header_to_metadata
+//                     - name: envoy.filters.http.golang
+//                       typed_config:
+//                         "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
+//                         library: "/home/admin/envoy/go-plugins/libauth.so"
+//                         plugine_name: auth
+//                         plugin_config:
+//                           "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.auth.v3.Config
+//                           xxx1: xx1
+//                           xxx2: xx2
+//                     - name: envoy.filters.http.router
+//       - name: egress
+//         address:
+//           socket_address:
+//             protocol: TCP
+//             address: 0.0.0.0
+//             port_value: 8081
+//         filter_chains:
+//           - filters:
+//               - name: envoy.filters.network.http_connection_manager
+//                   ......
+//                   http_filters:
+//                     - name: envoy.filters.http.golang
+//                       typed_config:
+//                         "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config
+//                         library: "/home/admin/envoy/go-plugins/libauth.so"
+//                         plugine_name: auth
+//                         plugin_config:
+//                           "@type": type.googleapis.com/envoy.extensions.filters.http.golang.plugins.auth.v3.Config
+//                           xxx1: xx1
+//                           xxx2: xx2
+//                     - name: envoy.filters.http.router
+// [#not-implemented-hide:]
+message Config {
+  enum MergePolicy {
+    MERGE_VIRTUALHOST_ROUTER_FILTER = 0;
+    MERGE_VIRTUALHOST_ROUTER = 1;
+    OVERRIDE = 3;
+  }
+
+  // Dynamic library implementing the interface of
+  // :ref:`StreamFilter <contrib.go_plugin_api.plugin.StreamFilter>`.
+  // [#comment:TODO(wangfakang): Support for downloading libraries from remote repositories.]
+  string library = 1 [(validate.rules).string = {min_len: 1}];
+
+  // plugin_name is the name of the go plugin, which needs to be consistent with the name
+  // registered in StreamFilterFactoryManager::RegisterStreamFactory.
+  string plugin_name = 2 [(validate.rules).string = {min_bytes: 1}];
+
+  // plugin_config is the configuration of the go plugin, note that this configuration is
+  // only parsed in the go plugin.
+  google.protobuf.Any plugin_config = 3;
+
+  // merge_policy is the merge policy configured by the go plugin.
+  // go plugin configuration supports three dimensions: the virtual host’s typed_per_filter_config,
+  // the route’s typed_per_filter_config or filter's config.
+  // The meanings are as follows:
+  // MERGE_VIRTUALHOST_ROUTER_FILTER: pass all configuration into go plugin.
+  // MERGE_VIRTUALHOST_ROUTER: pass Virtual-Host and Router configuration into go plugin.
+  // OVERRIDE: override according to Router > Virtual_host > Filter priority and pass the
+  // configuration to the go plugin.
+  MergePolicy merge_policy = 4 [(validate.rules).enum = {defined_only: true}];
+}
+
+// [#not-implemented-hide:]
+message RouterPlugin {
+  // The extension_plugin_options field is used to provide extension options for plugin.
+  google.protobuf.Struct extension_plugin_options = 1;
+
+  // The config field is used to setting plugin config.
+  google.protobuf.Any config = 2;
+}
+
+// [#not-implemented-hide:]
+message ConfigsPerRoute {
+  // plugins_config is the configuration of the go plugin at the per-router, and
+  // key is the name of the go plugin.
+  // Example
+  // typed_per_filter_config:
+  //   golang:
+  //     "@type": type.googleapis.com/golang.http.ConfigsPerRoute
+  //     plugins_config:
+  //       plugin1:
+  //        extension_plugin_options:
+  //          disabled: true
+  //        config:
+  //          "@type": type.googleapis.com/golang.http.plugin1
+  //          xxx: xxx
+  //       plugin2:
+  //        config:
+  //          "@type": type.googleapis.com/golang.http.plugin2
+  //          xxx: xxx
+  map<string, RouterPlugin> plugins_config = 1;
+}

api/versioning/BUILD

@@ -10,6 +10,7 @@ proto_library(
     visibility = ["//visibility:public"],
     deps = [
         "//contrib/envoy/extensions/filters/http/dynamo/v3:pkg",
+        "//contrib/envoy/extensions/filters/http/golang/v3alpha:pkg",
         "//contrib/envoy/extensions/filters/http/language/v3alpha:pkg",
         "//contrib/envoy/extensions/filters/http/squash/v3:pkg",
         "//contrib/envoy/extensions/filters/http/sxg/v3alpha:pkg",

contrib/go_plugin_api/filter.go

@@ -0,0 +1,70 @@
+package plugin
+
+// Stream Filter
+// refer https://github.com/envoyproxy/envoy/blob/main/envoy/http/filter.h
+type StreamFilter interface {
+	// request stream
+	StreamDecoderFilter
+	// response stream
+	StreamEncoderFilter
+	// stream complete
+	OnStreamComplete()
+	// error log
+	Log(LogType, string)
+	// destroy filter
+	OnDestroy()
+}
+
+// request
+type StreamDecoderFilter interface {
+	DecodeHeaders(RequestHeaderMap, bool) StatusType
+	DecodeData(BufferInstance, bool) StatusType
+	DecodeTrailers(RequestTrailerMap) StatusType
+	DecodeMetadata(MetadataMap) StatusType
+	DecoderCallbacks() DecoderFilterCallbacks
+}
+
+// response
+type StreamEncoderFilter interface {
+	EncodeHeaders(ResponseHeaderMap, bool) StatusType
+	EncodeData(BufferInstance, bool) StatusType
+	EncodeTrailers(ResponseTrailerMap) StatusType
+	EncodeMetadata(MetadataMap) StatusType
+	EncoderCallbacks() EncoderFilterCallbacks
+}
+
+// stream info
+// refer https://github.com/envoyproxy/envoy/blob/main/envoy/stream_info/stream_info.h
+type StreamInfo interface {
+	GetRouteName() string
+	VirtualClusterName() string
+	BytesReceived() int64
+	BytesSent() int64
+	Protocol() string
+	ResponseCode() int
+	GetRequestHeaders() RequestHeaderMap
+	ResponseCodeDetails() string
+}
+
+type StreamFilterCallbacks interface {
+	StreamInfo() StreamInfo
+}
+
+type DecoderFilterCallbacks interface {
+	StreamFilterCallbacks
+	ContinueDecoding()
+	AddDecodedData(buffer BufferInstance, streamingFilter bool)
+	SendLocalReply(response_code int, body_text string, headers map[string]string, details string)
+}
+
+type EncoderFilterCallbacks interface {
+	StreamFilterCallbacks
+	ContinueEncoding()
+	AddEncodedData(buffer BufferInstance, streamingFilter bool)
+	SendLocalReply(response_code int, body_text string, headers map[string]string, details string)
+}
+
+type FilterCallbackHandler interface {
+	DecoderFilterCallbacks
+	EncoderFilterCallbacks
+}

contrib/go_plugin_api/filter_manager.go

@@ -0,0 +1,55 @@
+package plugin
+
+//****************** filter factory start ******************//
+// StreamFilterFactory is used to inherit from callbacks
+// and generate a specific filter.
+type StreamFilterFactory func(callbacks FilterCallbackHandler) StreamFilter
+
+// StreamFilterConfigFactory stream filter config factory interface
+type StreamFilterConfigFactory interface {
+	// CreateFilterConfigFactory is create filter factory and it usually
+	// occurs during the filter config parse phase.
+	// config[] is google.protobuf.Any type and go plugin filter
+	// can parse the detailed configuration according to its own pb.
+	CreateFilterConfigFactory(config [][]byte) (StreamFilterFactory, error)
+}
+
+// StreamFilterConfigFactoryManager is manager stream filter config factory.
+type StreamFilterConfigFactoryManager interface {
+	// RegisterFilterConfigFactory register a config factory via filter name.
+	RegisterFilterConfigFactory(name string, factory StreamFilterConfigFactory) StreamFilterConfigFactory
+	// GetConfigFactory get a stream factory by filter name.
+	GetFilterConfigFactory(name string) StreamFilterConfigFactory
+}
+
+// StreamFilterFactoryManager is manager stream filter factory.
+type StreamFilterFactoryManager interface {
+	// StoreFilterFactory is store a stream  filter factor by uuid
+	// and each stream's filter mapped by a uuid at parse filter config phase.
+	// The uuid is created during filter config parse phase.
+	StoreFilterFactory(uuid uint64, ins StreamFilterFactory)
+	// GetFilterFactory get a stream filter factor by uuid.
+	GetFilterFactory(uuid uint64) StreamFilterFactory
+	// DeleteFilterFactory remove a stream filter factor by uuid
+	// and it usually occurs during the configuration update phase.
+	DeleteFilterFactory(uuid uint64)
+}
+
+//****************** filter factory end ******************//
+
+//***************** filter manager start *****************//
+// StreamFilterManager is manager stream filter.
+type StreamFilterManager interface {
+	// StoreFilter is store a filter by uuid and it usually occurs during the
+	// every new stream filter constructor phase.
+	// The uuid is created during filter constructor phase.
+	StoreFilter(uuid uint64, filter StreamFilter)
+	// GetFilter is get a filter by uuid and use to call the filter's decodeHeader
+	// decodeData etc.
+	GetFilter(uuid uint64) StreamFilter
+	// DeleteFilter remove a stream filter by uuid and it  usually occurs during
+	// the stream filter destructor phase.
+	DeleteFilter(uuid uint64)
+}
+
+//***************** filter manager end  *****************//

contrib/go_plugin_api/go.mod

@@ -0,0 +1,3 @@
+module plugin
+
+go 1.14