xDS Protocol

Communication between the Nantian Gateway control plane and data plane occurs over gRPC bidirectional streaming. The protocol is defined in proto/gateway/control/v1/control.proto. It is based on Envoy’s xDS model, but the message structures are designed specifically for Nantian Gateway’s internal representation (IR).

Protocol Overview

There are two gRPC services between the control plane and data plane:

Service	RPC	Type	Purpose
`ConfigurationDiscoveryService`	`StreamConfiguration`	Bidirectional stream	Push configuration snapshots and acknowledge receipt status
`ConfigurationDiscoveryService`	`ReportStatus`	Unary RPC	Data plane reports health status

Data Flow Model

Data Plane                              Control Plane

  |                                       |
  |-- DiscoveryRequest (subscribe) ------>|  Data plane initiates subscription
  |                                       |
  |<---- DiscoveryResponse (snapshot) --- |  Control plane pushes config snapshot
  |                                       |
  |-- DiscoveryRequest (ACK/NACK) ------>|  Data plane acknowledges receipt
  |                                       |
  |  ... config change ...                |
  |                                       |
  |<---- DiscoveryResponse (new ver) ---- |  Control plane pushes new snapshot
  |                                       |
  |-- DiscoveryRequest (ACK/NACK) ------>|  Data plane acknowledges
  |                                       |
  |-- StatusReport --------------------->|  Data plane reports health status
  |<---- StatusAck --------------------- |  Control plane acknowledges receipt

Key Concepts

Version tracking: Each configuration snapshot has a version field. The control plane increments the version number on every configuration change. The data plane carries its current version in the DiscoveryRequest, and the control plane uses this to determine whether a new configuration needs to be pushed.

Nonce mechanism: Each DiscoveryResponse carries a random nonce. The data plane must return this nonce unchanged in its acknowledgment. This prevents stale acknowledgments from interfering with the configuration stream.

Subscription model: The data plane declares which resource types it cares about in its initial DiscoveryRequest (the subscriptions field). The control plane only pushes resources the data plane has subscribed to.

ACK/NACK: After receiving a configuration, the data plane must reply with an acknowledgment status. ACK means the configuration was successfully applied. NACK means the configuration is invalid, with error information carried in the error_detail field.

Message Definitions

DiscoveryRequest

A request message sent by the data plane to the control plane.

Field	Type	Description
`node_id`	`string`	Data plane node identifier, typically the Pod name
`cluster`	`string`	Name of the cluster the data plane belongs to
`version`	`string`	Currently applied configuration version
`nonce`	`string`	The nonce from the last received response (used for ACK/NACK)
`subscriptions`	`repeated string`	List of subscribed resource types
`result_status`	`DiscoveryResultStatus`	Configuration application result: `ACK` or `NACK`
`error_detail`	`string`	Error details when NACK

DiscoveryResponse

A response message from the control plane to the data plane.

Field	Type	Description
`version`	`string`	Current configuration snapshot version
`nonce`	`string`	Unique identifier for this response; the data plane must return this in its acknowledgment
`snapshot`	`ConfigSnapshot`	Configuration snapshot content

ConfigSnapshot

The configuration snapshot, containing all configuration information needed by the data plane.

Field	Type	Description
`id`	`string`	Snapshot unique identifier
`generated_at`	`Timestamp`	Snapshot generation time
`listeners`	`repeated Listener`	Listener list
`http_routes`	`repeated HttpRoute`	HTTP route list
`grpc_routes`	`repeated GrpcRoute`	gRPC route list
`stream_routes`	`repeated StreamRoute`	TCP/UDP/TLS route list
`backends`	`repeated BackendCluster`	Backend cluster list
`secrets`	`repeated SecretMaterial`	TLS certificates and keys
`extensions`	`Struct`	Extension configuration (Wasm plugins, etc.)

StatusReport

A health status message periodically reported by the data plane.

Field	Type	Description
`node_id`	`string`	Data plane node identifier
`version`	`string`	Current data plane version
`ready`	`bool`	Whether ready to accept traffic
`message`	`string`	Status message
`observed_at`	`Timestamp`	Observation time

StatusAck

The control plane’s acknowledgment of a status report.

Field	Type	Description
`accepted`	`bool`	Whether the status report was accepted

Listener Definition

Listener defines the network ports and protocols the data plane should listen on.

Field	Type	Description
`name`	`string`	Listener name
`address`	`string`	Listen address
`port`	`uint32`	Listen port
`protocol`	`ListenerProtocol`	Protocol type
`hostnames`	`repeated string`	Allowed hostname list
`attached_routes`	`repeated string`	Names of routes bound to this listener
`tls`	`TlsConfig`	TLS configuration
`metadata`	`map<string, string>`	Metadata
`backend_tls`	`BackendTlsConfig`	Backend TLS configuration
`addresses`	`repeated string`	Multi-address listeners

ListenerProtocol Enum

Value	Description
`LISTENER_PROTOCOL_HTTP`	HTTP/1.1 and HTTP/2 (h2c)
`LISTENER_PROTOCOL_HTTPS`	TLS termination + HTTP
`LISTENER_PROTOCOL_GRPC`	gRPC
`LISTENER_PROTOCOL_HTTP3`	HTTP/3 (QUIC)
`LISTENER_PROTOCOL_TCP`	TCP stream proxy
`LISTENER_PROTOCOL_UDP`	UDP stream proxy
`LISTENER_PROTOCOL_TLS_PASSTHROUGH`	TLS passthrough
`LISTENER_PROTOCOL_TLS`	TLS termination

TlsConfig

Field	Type	Description
`enabled`	`bool`	Whether TLS is enabled
`passthrough`	`bool`	Whether in passthrough mode
`secret_refs`	`repeated string`	Referenced Secret names
`sni_hosts`	`repeated string`	SNI hostname list
`min_version`	`string`	Minimum TLS version
`max_version`	`string`	Maximum TLS version
`frontend_validation`	`FrontendValidation`	Client certificate validation

FrontendValidation

Field	Type	Description
`ca_pems`	`repeated string`	CA certificate PEM list
`mode`	`string`	Validation mode

HttpRoute Definition

HttpRoute corresponds to the HTTPRoute resource in the Gateway API and defines HTTP traffic routing rules.

Field	Type	Description
`name`	`string`	Route name
`namespace`	`string`	Namespace
`hostnames`	`repeated string`	Hostname list
`parent_refs`	`repeated ParentRef`	Parent resource references
`rules`	`repeated HttpRule`	Routing rule list
`labels`	`map<string, string>`	Labels
`annotations`	`map<string, string>`	Annotations

HttpRule

Field	Type	Description
`matches`	`repeated HttpMatch`	Match conditions
`filters`	`repeated Filter`	Filter chain
`backend_refs`	`repeated BackendRef`	Backend reference list
`timeouts`	`HttpRouteTimeouts`	Timeout configuration
`retry`	`HttpRouteRetry`	Retry configuration
`session_persistence`	`SessionPersistence`	Session persistence
`name`	`string`	Rule name

HttpMatch

Field	Type	Description
`path`	`string`	Path match value
`path_type`	`string`	Path match type: `Exact`, `PathPrefix`, `RegularExpression`
`method`	`string`	HTTP method
`headers`	`repeated HeaderMatch`	Request header match conditions
`query_params`	`repeated QueryMatch`	Query parameter match conditions

HttpRouteTimeouts

Field	Type	Description
`request`	`Duration`	Request timeout
`backend_request`	`Duration`	Backend request timeout

HttpRouteRetry

Field	Type	Description
`codes`	`repeated uint32`	HTTP status codes that trigger retry
`attempts`	`uint32`	Maximum retry attempts
`backoff`	`Duration`	Retry backoff time

GrpcRoute Definition

GrpcRoute corresponds to the GRPCRoute resource in the Gateway API.

Field	Type	Description
`name`	`string`	Route name
`namespace`	`string`	Namespace
`hostnames`	`repeated string`	Hostname list
`parent_refs`	`repeated ParentRef`	Parent resource references
`rules`	`repeated GrpcRule`	gRPC routing rules

GrpcRule

Field	Type	Description
`matches`	`repeated GrpcMatch`	Match conditions
`filters`	`repeated Filter`	Filter chain
`backend_refs`	`repeated BackendRef`	Backend reference list
`session_persistence`	`SessionPersistence`	Session persistence
`name`	`string`	Rule name

GrpcMatch

Field	Type	Description
`service`	`string`	gRPC service name
`method`	`string`	gRPC method name
`headers`	`repeated HeaderMatch`	Metadata matching
`match_type`	`string`	Match type

StreamRoute Definition

StreamRoute uniformly represents TCP, UDP, and TLS routes.

Field	Type	Description
`name`	`string`	Route name
`namespace`	`string`	Namespace
`kind`	`RouteKind`	Route type: `TCP`, `UDP`, `TLS`
`parent_refs`	`repeated ParentRef`	Parent resource references
`rules`	`repeated StreamRule`	Stream routing rules

StreamMatch

Field	Type	Description
`port`	`uint32`	Match port
`sni_hostname`	`string`	SNI hostname (TLS routes)
`mode`	`TlsRouteMode`	TLS route mode: `PASSTHROUGH` or `TERMINATE`

BackendCluster Definition

BackendCluster represents a backend service cluster.

Field	Type	Description
`name`	`string`	Cluster name
`namespace`	`string`	Namespace
`protocol`	`string`	Backend protocol
`endpoints`	`repeated BackendEndpoint`	Endpoint list
`connect_timeout`	`Duration`	Connection timeout
`request_timeout`	`Duration`	Request timeout
`tls_validation`	`BackendTlsValidation`	Backend TLS verification
`session_persistence`	`SessionPersistence`	Session persistence
`load_balancing`	`LoadBalancingPolicy`	Load balancing strategy
`ai_service`	`AIServiceConfig`	AI service configuration
`token_policy`	`TokenPolicyConfig`	Token policy configuration
`wasm_plugin`	`WasmPluginConfig`	Wasm plugin configuration

BackendEndpoint

Field	Type	Description
`address`	`string`	Endpoint IP address
`port`	`uint32`	Endpoint port
`healthy`	`bool`	Health status
`zone`	`string`	Availability zone

Extension Configuration

AIServiceConfig

Field	Type	Description
`provider`	`string`	Provider type: `openai`, `anthropic`, `ollama`
`format`	`string`	Request/response format
`model`	`string`	Model name
`auth`	`AIServiceAuthConfig`	Authentication configuration
`timeout`	`Duration`	Request timeout

TokenPolicyConfig

Field	Type	Description
`tokens_per_minute`	`uint64`	Maximum tokens per minute
`tokens_per_hour`	`uint64`	Maximum tokens per hour
`requests_per_minute`	`uint64`	Maximum requests per minute
`scope`	`string`	Rate limiting scope
`burst`	`double`	Burst multiplier
`on_limit`	`string`	Action on limit

WasmPluginConfig

Field	Type	Description
`name`	`string`	Plugin name
`namespace`	`string`	Namespace
`wasm_bytes`	`bytes`	Wasm module byte content
`sha256`	`string`	SHA256 checksum
`hooks`	`repeated string`	Execution hook list
`config_json`	`string`	Plugin configuration (JSON)
`sandbox`	`WasmSandboxConfig`	Sandbox configuration

WasmSandboxConfig

Field	Type	Description
`max_memory_bytes`	`uint64`	Maximum memory limit
`max_execution_time_ms`	`uint64`	Maximum execution time
`allow_network`	`bool`	Whether network access is allowed
`allow_file_system`	`bool`	Whether filesystem access is allowed

SecretMaterial

Field	Type	Description
`namespace`	`string`	Secret namespace
`name`	`string`	Secret name
`cert_pem`	`string`	Certificate PEM
`key_pem`	`string`	Private key PEM

Protocol Source

The complete protocol definition is located at:

proto/gateway/control/v1/control.proto

The current protobuf package name is gateway.control.v1. The Go generated code import path is github.com/nantian-gw/proto/gateway/control/v1;controlv1.

Next Steps

See Admin API for runtime diagnostics endpoints
See Architecture Overview for the overall control plane and data plane design
See gRPC xDS Configuration for xDS deployment configuration options