|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package envoy.extensions.reverse_tunnel_reporters.v3alpha.clients.grpc_client; |
| 4 | + |
| 5 | +import "envoy/config/core/v3/base.proto"; |
| 6 | + |
| 7 | +import "google/protobuf/duration.proto"; |
| 8 | +import "google/protobuf/timestamp.proto"; |
| 9 | +import "google/rpc/status.proto"; |
| 10 | + |
| 11 | +import "udpa/annotations/status.proto"; |
| 12 | +import "validate/validate.proto"; |
| 13 | + |
| 14 | +option java_package = "io.envoyproxy.envoy.extensions.reverse_tunnel_reporters.v3alpha.clients.grpc_client"; |
| 15 | +option java_outer_classname = "StreamReverseTunnelsProto"; |
| 16 | +option java_multiple_files = true; |
| 17 | +option go_package = "github.com/envoyproxy/go-control-plane/contrib/envoy/extensions/reverse_tunnel_reporters/v3alpha/clients/grpc_client"; |
| 18 | +option (udpa.annotations.file_status).package_version_status = ACTIVE; |
| 19 | + |
| 20 | +// [#protodoc-title: Reverse Tunnel Reporting Service] |
| 21 | + |
| 22 | +// ReverseTunnelReportingService allows Envoy instances to report reverse tunnel |
| 23 | +// connection state changes to a management server for monitoring and coordination. |
| 24 | +service ReverseTunnelReportingService { |
| 25 | + // Bidirectional stream for reporting reverse tunnel connection state changes. |
| 26 | + // The management server can control reporting intervals and acknowledge received reports. |
| 27 | + rpc StreamReverseTunnels(stream StreamReverseTunnelsRequest) |
| 28 | + returns (stream StreamReverseTunnelsResponse) { |
| 29 | + } |
| 30 | +} |
| 31 | + |
| 32 | +// Request message sent by Envoy to report reverse tunnel state changes. |
| 33 | +// [#next-free-field: 6] |
| 34 | +message StreamReverseTunnelsRequest { |
| 35 | + // Node identifier for the reporting Envoy instance. |
| 36 | + // This identifies which Envoy instance is sending the report. |
| 37 | + config.core.v3.Node node = 1 [(validate.rules).message = {required: true}]; |
| 38 | + |
| 39 | + // List of reverse tunnels that were established since the last report. |
| 40 | + // Each tunnel represents a new connection from a downstream Envoy. |
| 41 | + repeated ReverseTunnel added_tunnels = 2; |
| 42 | + |
| 43 | + // List of tunnel names that were disconnected since the last report. |
| 44 | + // Only the tunnel name is needed for removal notifications. |
| 45 | + repeated string removed_tunnel_names = 3 |
| 46 | + [(validate.rules).repeated = {items {string {min_len: 1}}}]; |
| 47 | + |
| 48 | + // Indicates whether this report contains all active tunnels (true) or |
| 49 | + // only changes since the last report (false). Usually invoked only on server disconnects. |
| 50 | + bool full_push = 4; |
| 51 | + |
| 52 | + // Unique nonce for this request to enable proper ACK/NACK handling. |
| 53 | + // Must be non-negative and should increment for each request. |
| 54 | + // This can also be modified to be used for checksum and tracking in the future. |
| 55 | + int64 nonce = 5 [(validate.rules).int64 = {gte: 0}]; |
| 56 | +} |
| 57 | + |
| 58 | +// Response message sent by the management server to control reporting behavior. |
| 59 | +message StreamReverseTunnelsResponse { |
| 60 | + // Node identifier acknowledging which Envoy instance this response is for. |
| 61 | + // Should match the node from the corresponding request. |
| 62 | + string node_id = 1; |
| 63 | + |
| 64 | + // Interval at which Envoy should send tunnel state reports. |
| 65 | + // This is used to change the reporting_interval -> no need to repeat the same value. |
| 66 | + google.protobuf.Duration report_interval = 2 [(validate.rules).duration = {lte {seconds: 3600}}]; |
| 67 | + |
| 68 | + // Nonce from the request being acknowledged or rejected. |
| 69 | + // Must match the nonce from the corresponding request. |
| 70 | + int64 request_nonce = 3 [(validate.rules).int64 = {gte: 0}]; |
| 71 | + |
| 72 | + // Error details if the previous request failed processing. |
| 73 | + // If populated, indicates the request was rejected (NACK). |
| 74 | + // If empty, indicates successful processing (ACK). |
| 75 | + // NACK will terminate the connection -> useful for logging rather than just some disconnect. |
| 76 | + // So basically -> NACK then terminate. |
| 77 | + google.rpc.Status error_detail = 4; |
| 78 | +} |
| 79 | + |
| 80 | +// Represents a single reverse tunnel connection with its metadata. |
| 81 | +message ReverseTunnel { |
| 82 | + // Unique name to identify this tunnel connection. |
| 83 | + // Must be unique within the reporting Envoy instance. |
| 84 | + // This is also used for the reporting the disconnection with the associated tunnel initiator. |
| 85 | + string name = 1 [(validate.rules).string = {min_len: 1}]; |
| 86 | + |
| 87 | + // Identity information of the tunnel initiator (downstream Envoy). |
| 88 | + // Contains ``node_id``, ``cluster_id``, and ``tenant_id`` for proper identification. |
| 89 | + TunnelInitiatorIdentity identity = 2 [(validate.rules).message = {required: true}]; |
| 90 | + |
| 91 | + // Timestamp when this tunnel connection was created. |
| 92 | + // Used for ordering events and debugging connection timing issues. |
| 93 | + google.protobuf.Timestamp created_at = 3 [(validate.rules).timestamp = {required: true}]; |
| 94 | +} |
| 95 | + |
| 96 | +message TunnelInitiatorIdentity { |
| 97 | + // Required: Tenant identifier of the initiating Envoy instance. |
| 98 | + string tenant_id = 1 [(validate.rules).string = {min_len: 1 max_len: 128}]; |
| 99 | + |
| 100 | + // Required: Cluster identifier of the initiating Envoy instance. |
| 101 | + string cluster_id = 2 [(validate.rules).string = {min_len: 1 max_len: 128}]; |
| 102 | + |
| 103 | + // Required: Node identifier of the initiating Envoy instance. |
| 104 | + string node_id = 3 [(validate.rules).string = {min_len: 1 max_len: 128}]; |
| 105 | +} |
0 commit comments