Skip to content

doc: update doc for SetUpstreamOverrideHost in Envoy Golang. #41369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 10, 2025
Merged

doc: update doc for SetUpstreamOverrideHost in Envoy Golang. #41369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
27a2b97
doc: update doc for SetUpstreamOverrideHost in Envoy Golang.
doujiang24 Oct 5, 2025
c5de891
fix format
doujiang24 Oct 5, 2025
50d31d1
more fix
doujiang24 Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 10 additions & 17 deletions contrib/golang/common/go/api/filter.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,29 +210,22 @@ type FilterProcessCallbacks interface {

type DecoderFilterCallbacks interface {
FilterProcessCallbacks
// Sets an upstream address override for the request. When the overridden host exists in the host list of the routed cluster
// and can be selected directly, the load balancer bypasses its algorithm and routes traffic directly to the specified host.
//
// Here are some cases:
// 1. Set a valid host(no matter in or not in the cluster), will route to the specified host directly and return 200.
// 2. Set a non-IP host, C++ side will return error and not route to cluster.
// 3. Set a unavaiable host, and the host is not in the cluster, will req the valid host in the cluster and rerurn 200.
// 4. Set a unavaiable host, and the host is in the cluster, but not available(can not connect to the host), will req the unavaiable hoat and rerurn 503.
// 5. Set a unavaiable host, and the host is in the cluster, but not available(can not connect to the host), and with retry. when first request with unavaiable host failed 503, the second request will retry with the valid host, then the second request will succeed and finally return 200.
// 6. Set a unavaiable host with strict mode, and the host is in the cluster, will req the unavaiable host and rerurn 503.
// 7. Set a unavaiable host with strict mode, and the host is not in the cluster, will req the unavaiable host and rerurn 503.
// 8. Set a unavaiable host with strict mode and retry. when first request with unavaiable host failed 503, the second request will retry with the valid host, then the second request will succeed and finally return 200.
// 9. Set a unavaiable host with strict mode and retry, and the host is not in the cluster, will req the unavaiable host and rerurn 503.

// SetUpstreamOverrideHost sets an upstream address override for the request.
// When the overridden host is available and can be selected directly, the load balancer bypasses its algorithm
// and routes traffic directly to the specified host. The strict flag determines whether the HTTP request must
// strictly use the overridden destination. If the destination is unavailable and strict is set to true, Envoy
// responds with a 503 Service Unavailable error.
//
// The function takes two arguments:
//
// host (string): The upstream host address to use for the request. This must be a valid IP address(with port); otherwise, the
// C++ side will throw an error.
// host (string): The upstream host address to use for the request. This must be a valid IP address(with port);
// otherwise, it will return an error.
//
// strict (boolean): Determines whether the HTTP request must be strictly routed to the requested
// host. When set to ``true``, if the requested host is invalid, Envoy will return a 503 status code.
// host. When set to ``true``, if the requested host is unavailable, Envoy will return a 503 status code.
// The default value is ``false``, which allows Envoy to fall back to its load balancing mechanism. In this case, if the
// requested host is invalid, the request will be routed according to the load balancing algorithm and choose other hosts.
// requested host is not found, the request will be routed according to the load balancing algorithm.
SetUpstreamOverrideHost(host string, strict bool) error
}

Expand Down
28 changes: 14 additions & 14 deletions contrib/golang/filters/http/test/golang_integration_test.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1847,8 +1847,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_BadHost) {
testUpstreamOverrideHost("403", "", "/test?upstreamOverrideHost=badhost", true);
}

// Set a unavaiable host, and the host is not in the cluster, will req the valid host in the cluster
// and rerurn 200.
// Set an unavailable host, and the host is not in the cluster, will req the valid host in the
// cluster and return 200.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_NotFound) {
const std::string expected_host =
GetParam() == Network::Address::IpVersion::v4 ? "127.0.0.1" : "[::1]";
Expand All @@ -1857,8 +1857,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_NotFound) {
testUpstreamOverrideHost("200", expected_host, "/test?upstreamOverrideHost=" + url_host, false);
}

// Set a unavaiable host, and the host is in the cluster, but not available(can not connect to the
// host), will req the unavaiable hoat and rerurn 503.
// Set an unavailable host, and the host is in the cluster, but not available(can not connect to the
// host), will req the unavailable hoat and return 503.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Unavaliable) {
const std::string expected_host =
GetParam() == Network::Address::IpVersion::v4 ? "127.0.0.1" : "[::1]";
Expand All @@ -1870,8 +1870,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Unavaliable) {
add_endpoint);
}

// Set a unavaiable host, and the host is in the cluster, but not available(can not connect to the
// host), and with retry. when first request with unavaiable host failed 503, the second request
// Set an unavailable host, and the host is in the cluster, but not available(can not connect to the
// host), and with retry. when first request with unavailable host failed 503, the second request
// will retry with the valid host, then the second request will succeed and finally return 200.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Unavaliable_Retry) {
const std::string expected_host =
Expand All @@ -1884,8 +1884,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Unavaliable_Re
add_endpoint, true);
}

// Set a unavaiable host with strict mode, and the host is in the cluster, will req the unavaiable
// host and rerurn 503.
// Set an unavailable host with strict mode, and the host is in the cluster, will req the
// unavailable host and return 503.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict) {
const std::string expected_host =
GetParam() == Network::Address::IpVersion::v4 ? "127.0.0.1" : "[::1]";
Expand All @@ -1899,8 +1899,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict) {
false, add_endpoint);
}

// Set a unavaiable host with strict mode, and the host is not in the cluster, will req the
// unavaiable host and rerurn 503.
// Set an unavailable host with strict mode, and the host is not in the cluster, will req the
// unavailable host and return 503.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict_NotFound) {
const std::string expected_host =
GetParam() == Network::Address::IpVersion::v4 ? "127.0.0.1" : "[::1]";
Expand All @@ -1912,8 +1912,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict_NotFoun
false);
}

// Set a unavaiable host with strict mode and retry, and the host is in the cluster.
// when first request with unavaiable host failed 503, the second request will retry with the valid
// Set an unavailable host with strict mode and retry, and the host is in the cluster.
// when first request with unavailable host failed 503, the second request will retry with the valid
// host, then the second request will succeed and finally return 200.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict_Retry) {
const std::string expected_host =
Expand All @@ -1928,8 +1928,8 @@ TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict_Retry)
false, add_endpoint, true);
}

// Set a unavaiable host with strict mode and retry, and the host is not in the cluster, will req
// the unavaiable host and rerurn 503.
// Set an unavailable host with strict mode and retry, and the host is not in the cluster, will req
// the unavailable host and return 503.
TEST_P(GolangIntegrationTest, SetUpstreamOverrideHost_InvalidHost_Strict_NotFound_Retry) {
const std::string expected_host =
GetParam() == Network::Address::IpVersion::v4 ? "127.0.0.1" : "[::1]";
Expand Down