async-grpc-xds 0.0.1

data/plan.md

@@ -0,0 +1,156 @@
+# Envoy Monitor Plan
+
+## Goal
+
+Add support for `async-service-supervisor` to publish worker health and endpoint information to Envoy using xDS.
+
+The implementation should keep generic xDS protocol machinery in `async-grpc-xds`, and put supervisor-specific behavior in a separate monitor gem.
+
+## Proposed Gems
+
+### `async-grpc-xds`
+
+Owns generic Ruby xDS client and control-plane support.
+
+Existing client-side xDS support remains here. New server-side support should also live here so it can be reused by integrations beyond `async-service-supervisor`.
+
+Responsibilities:
+
+- ADS gRPC service implementation for Envoy.
+- Snapshot/resource state management.
+- Resource versioning.
+- ACK/NACK handling.
+- Stream reconnect support.
+- Resource builders for common Envoy xDS resources.
+- Tests and Docker compose fixtures for xDS behavior.
+
+Initial server-side resource coverage:
+
+- CDS: `envoy.config.cluster.v3.Cluster`.
+- EDS: `envoy.config.endpoint.v3.ClusterLoadAssignment`.
+- Endpoint health via `LbEndpoint#health_status`.
+
+Possible API shape:
+
+```ruby
+control_plane = Async::GRPC::XDS::ControlPlane.new
+
+control_plane.update_cluster("myservice")
+control_plane.update_endpoints("myservice", endpoints)
+
+server = Async::GRPC::XDS::Server.new(control_plane)
+server.run(endpoint)
+```
+
+### `async-service-supervisor-envoy`
+
+Owns the integration between `async-service-supervisor` and Envoy.
+
+Proposed public monitor:
+
+```ruby
+Async::Service::Supervisor::Envoy::Monitor
+```
+
+Require path:
+
+```ruby
+require "async/service/supervisor/envoy/monitor"
+```
+
+Responsibilities:
+
+- Run an embedded xDS control plane for Envoy.
+- Translate supervisor worker registration/removal into xDS endpoint updates.
+- Publish endpoint health to Envoy.
+- Expose monitor status through the normal supervisor monitor status API.
+- Keep Envoy-specific dependencies out of `async-service-supervisor` core.
+
+Example usage:
+
+```ruby
+Async::Service::Supervisor::Envoy::Monitor.new(
+	bind: "http://0.0.0.0:18000",
+	clusters: true
+)
+```
+
+Worker state should provide the endpoint metadata:
+
+```ruby
+state = {
+	name: "myservice",
+	endpoint: {
+		address: "127.0.0.1",
+		port: 50051
+	}
+}
+```
+
+The monitor should map that state to Envoy EDS endpoints.
+
+Workers without `state[:endpoint]` should be ignored by the Envoy monitor. This allows non-network workers, control processes, or workers managed by other routing systems to still participate in supervisor monitoring without being published to Envoy.
+
+The first version should support multiple clusters. By default, workers are grouped by `state[:name]`. The grouping should be configurable so applications can select, rename, or filter clusters:
+
+```ruby
+Async::Service::Supervisor::Envoy::Monitor.new(
+	cluster: -> controller{controller.state[:name]},
+	include: -> controller{controller.state[:endpoint]}
+)
+```
+
+## Health Model
+
+Start with a conservative default:
+
+- A registered supervisor worker is healthy.
+- A removed/disconnected worker is dead and must disappear from EDS.
+- A registered worker that fails an explicit health policy can remain in EDS with an unhealthy endpoint status.
+
+Add optional health policy hooks:
+
+```ruby
+Async::Service::Supervisor::Envoy::Monitor.new(
+	cluster: -> controller{controller.state[:name]},
+	health: -> controller{true}
+)
+```
+
+The monitor should not actively probe worker HTTP/gRPC health. Health should be derived from supervisor state and optional hooks, because the supervisor is already responsible for monitoring workers.
+
+Later health inputs can include:
+
+- Supervisor connection liveness.
+- Process monitor state.
+- Memory monitor state.
+- Utilization monitor state.
+- Custom worker RPCs.
+
+## Implementation Plan
+
+1. Add reusable Ruby xDS control-plane support to `async-grpc-xds`.
+2. Keep the current Docker compose xDS test suite, but introduce Ruby control-plane coverage alongside the Go fixture.
+3. Implement a minimal ADS server with CDS and EDS support.
+4. Add resource builders for clusters, cluster load assignments, and endpoints.
+5. Add tests for snapshot versioning, endpoint updates, endpoint removal, and ADS reconnect.
+6. Scaffold `~/Developer/socketry/async-service-supervisor-envoy`.
+7. Implement `Async::Service::Supervisor::Envoy::Monitor`.
+8. Add monitor unit tests using existing supervisor monitor patterns.
+9. Add Docker compose e2e tests with Envoy, the supervisor monitor, and multiple backend workers.
+10. Document the worker state contract and Envoy bootstrap/config examples.
+11. Keep generic Envoy xDS bootstrap examples in `async-grpc-xds`.
+12. Keep supervisor-specific runnable examples and Docker compose fixtures in `async-service-supervisor-envoy`.
+
+## E2E Coverage
+
+The Docker compose e2e suite for the monitor gem should cover:
+
+- Worker registration adds an Envoy endpoint.
+- Workers without `state[:endpoint]` are ignored.
+- Multiple workers are exposed as load-balanced endpoints.
+- Multiple service names are exposed as separate configurable clusters.
+- Worker removal removes the endpoint from EDS.
+- Worker recovery restores the endpoint.
+- ADS stream reconnect receives the current snapshot.
+- Envoy can route traffic through endpoints discovered from the monitor.

data/proto/envoy/annotations/deprecation.proto

@@ -0,0 +1,34 @@
+syntax = "proto3";
+
+package envoy.annotations;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/annotations";
+
+import "google/protobuf/descriptor.proto";
+
+// [#protodoc-title: Deprecation]
+// Adds annotations for deprecated fields and enums to allow tagging proto
+// fields as fatal by default and the minor version on which the field was
+// deprecated. One Envoy release after deprecation, deprecated fields will be
+// disallowed by default, a state which is reversible with
+// :ref:`runtime overrides <config_runtime_deprecation>`.
+
+// Magic number in this file derived from top 28bit of SHA256 digest of
+// "envoy.annotation.disallowed_by_default" and "envoy.annotation.deprecated_at_minor_version"
+extend google.protobuf.FieldOptions {
+  bool disallowed_by_default = 189503207;
+
+  // The API major and minor version on which the field was deprecated
+  // (e.g., "3.5" for major version 3 and minor version 5).
+  string deprecated_at_minor_version = 157299826;
+}
+
+// Magic number in this file derived from top 28bit of SHA256 digest of
+// "envoy.annotation.disallowed_by_default_enum" and
+// "envoy.annotation.deprecated_at_minor_version_eum"
+extend google.protobuf.EnumValueOptions {
+  bool disallowed_by_default_enum = 70100853;
+
+  // The API major and minor version on which the enum value was deprecated
+  // (e.g., "3.5" for major version 3 and minor version 5).
+  string deprecated_at_minor_version_enum = 181198657;
+}

data/proto/envoy/annotations/resource.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package envoy.annotations;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/annotations";
+
+import "google/protobuf/descriptor.proto";
+
+// [#protodoc-title: Resource]
+
+// Magic number in this file derived from top 28bit of SHA256 digest of "envoy.annotation.resource".
+extend google.protobuf.ServiceOptions {
+  ResourceAnnotation resource = 265073217;
+}
+
+message ResourceAnnotation {
+  // Annotation for xDS services that indicates the fully-qualified Protobuf type for the resource
+  // type.
+  string type = 1;
+}

data/proto/envoy/config/README.md

@@ -0,0 +1,3 @@
+Protocol buffer definitions for Envoy's bootstrap, filter, and service configuration.
+
+Visibility should be constrained to none or `//envoy/config/bootstrap/v2` by default.

data/proto/envoy/config/cluster/v3/BUILD

@@ -0,0 +1,18 @@
+# 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 = [
+        "//envoy/annotations:pkg",
+        "//envoy/config/core/v3:pkg",
+        "//envoy/config/endpoint/v3:pkg",
+        "//envoy/type/metadata/v3:pkg",
+        "//envoy/type/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/core/v3:pkg",
+        "@com_github_cncf_xds//xds/type/matcher/v3:pkg",
+    ],
+)

data/proto/envoy/config/cluster/v3/circuit_breaker.proto

@@ -0,0 +1,121 @@
+syntax = "proto3";
+
+package envoy.config.cluster.v3;
+
+import "envoy/config/core/v3/base.proto";
+import "envoy/type/v3/percent.proto";
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.cluster.v3";
+option java_outer_classname = "CircuitBreakerProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3;clusterv3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Circuit breakers]
+
+// :ref:`Circuit breaking<arch_overview_circuit_break>` settings can be
+// specified individually for each defined priority.
+message CircuitBreakers {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.api.v2.cluster.CircuitBreakers";
+
+  // A Thresholds defines CircuitBreaker settings for a
+  // :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`.
+  // [#next-free-field: 9]
+  message Thresholds {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.api.v2.cluster.CircuitBreakers.Thresholds";
+
+    message RetryBudget {
+      option (udpa.annotations.versioning).previous_message_type =
+          "envoy.api.v2.cluster.CircuitBreakers.Thresholds.RetryBudget";
+
+      // Specifies the limit on concurrent retries as a percentage of the sum of active requests and
+      // active pending requests. For example, if there are 100 active requests and the
+      // budget_percent is set to 25, there may be 25 active retries.
+      //
+      // This parameter is optional. Defaults to 20%.
+      type.v3.Percent budget_percent = 1;
+
+      // Specifies the minimum retry concurrency allowed for the retry budget. The limit on the
+      // number of active retries may never go below this number.
+      //
+      // This parameter is optional. Defaults to 3.
+      google.protobuf.UInt32Value min_retry_concurrency = 2;
+    }
+
+    // The :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`
+    // the specified CircuitBreaker settings apply to.
+    core.v3.RoutingPriority priority = 1 [(validate.rules).enum = {defined_only: true}];
+
+    // The maximum number of connections that Envoy will make to the upstream
+    // cluster. If not specified, the default is 1024.
+    google.protobuf.UInt32Value max_connections = 2;
+
+    // The maximum number of pending requests that Envoy will allow to the
+    // upstream cluster. If not specified, the default is 1024.
+    // This limit is applied as a connection limit for non-HTTP traffic.
+    google.protobuf.UInt32Value max_pending_requests = 3;
+
+    // The maximum number of parallel requests that Envoy will make to the
+    // upstream cluster. If not specified, the default is 1024.
+    // This limit does not apply to non-HTTP traffic.
+    google.protobuf.UInt32Value max_requests = 4;
+
+    // The maximum number of parallel retries that Envoy will allow to the
+    // upstream cluster. If not specified, the default is 3.
+    google.protobuf.UInt32Value max_retries = 5;
+
+    // Specifies a limit on concurrent retries in relation to the number of active requests. This
+    // parameter is optional.
+    //
+    // .. note::
+    //
+    //    If this field is set, the retry budget will override any configured retry circuit
+    //    breaker.
+    RetryBudget retry_budget = 8;
+
+    // If track_remaining is true, then stats will be published that expose
+    // the number of resources remaining until the circuit breakers open. If
+    // not specified, the default is false.
+    //
+    // .. note::
+    //
+    //    If a retry budget is used in lieu of the max_retries circuit breaker,
+    //    the remaining retry resources remaining will not be tracked.
+    bool track_remaining = 6;
+
+    // The maximum number of connection pools per cluster that Envoy will concurrently support at
+    // once. If not specified, the default is unlimited. Set this for clusters which create a
+    // large number of connection pools. See
+    // :ref:`Circuit Breaking <arch_overview_circuit_break_cluster_maximum_connection_pools>` for
+    // more details.
+    google.protobuf.UInt32Value max_connection_pools = 7;
+  }
+
+  // If multiple :ref:`Thresholds<envoy_v3_api_msg_config.cluster.v3.CircuitBreakers.Thresholds>`
+  // are defined with the same :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`,
+  // the first one in the list is used. If no Thresholds is defined for a given
+  // :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`, the default values
+  // are used.
+  repeated Thresholds thresholds = 1;
+
+  // Optional per-host limits which apply to each individual host in a cluster.
+  //
+  // .. note::
+  //  currently only the :ref:`max_connections
+  //  <envoy_v3_api_field_config.cluster.v3.CircuitBreakers.Thresholds.max_connections>` field is supported for per-host limits.
+  //
+  // If multiple per-host :ref:`Thresholds<envoy_v3_api_msg_config.cluster.v3.CircuitBreakers.Thresholds>`
+  // are defined with the same :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`,
+  // the first one in the list is used. If no per-host Thresholds are defined for a given
+  // :ref:`RoutingPriority<envoy_v3_api_enum_config.core.v3.RoutingPriority>`,
+  // the cluster will not have per-host limits.
+  repeated Thresholds per_host_thresholds = 2;
+}