This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/dubbo-go.git
The following commit(s) were added to refs/heads/develop by this push:
new fc7a3ca99 docs: improve functional option API comments (#3642)
fc7a3ca99 is described below
commit fc7a3ca99d8b2a0fd0a8b6149740da01b020f7bc
Author: xiaobaicai66695 <[email protected]>
AuthorDate: Wed Aug 12 15:31:54 2026 +0800
docs: improve functional option API comments (#3642)
* docs: improve functional option API comments
* style: modernize nacos concurrency tests
* docs: clarify functional option behavior and usage
* docs: preserve functional option TODOs
---
client/options.go | 307 ++++++++++++++++++++++++++++++++++++++++++++++-----
protocol/options.go | 57 +++++++---
server/options.go | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 625 insertions(+), 51 deletions(-)
diff --git a/client/options.go b/client/options.go
index 6baa9a96a..6ef539eeb 100644
--- a/client/options.go
+++ b/client/options.go
@@ -152,6 +152,10 @@ type ReferenceOption func(*ReferenceOptions)
// ---------- For user ----------
+// WithCheck requires this reference to pass its availability check during
initialization.
+// Use it to fail early when no usable provider can be resolved instead of
discovering the
+// problem on the first invocation, for example when a mandatory dependency
must be ready
+// before the application starts serving traffic. It overrides
WithClientNoCheck for this reference.
func WithCheck() ReferenceOption {
return func(opts *ReferenceOptions) {
check := true
@@ -159,19 +163,25 @@ func WithCheck() ReferenceOption {
}
}
+// WithURL invokes this service through the supplied direct provider URL and
bypasses registry
+// discovery. It is useful for local testing or fixed endpoints but does not
follow registry
+// instance changes or fail over to providers that are not encoded in the URL.
func WithURL(url string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.URL = url
}
}
+// WithFilter selects the consumer filter chain that wraps invocations for
this reference.
+// The value is a comma-separated list of registered filter names, in
execution order. Use it
+// to add cross-cutting behavior such as tracing, metrics, authentication, or
custom middleware.
func WithFilter(filter string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Filter = filter
}
}
-// WithInterface sets the interface name for the service reference.
+// WithInterface identifies the remote service that this reference discovers
and invokes.
//
// As a functional option, it is passed to a client constructor
// (e.g., NewGreetService) to configure which remote service to connect to.
@@ -191,6 +201,10 @@ func WithInterface(interfaceName string) ReferenceOption {
}
}
+// WithRegistryIDs limits this reference to the named registries. Each ID must
match a
+// registry added with WithRegistry or WithClientRegistry; when omitted, the
reference
+// inherits the client-level selection. Use it when one client connects to
several registries
+// but a service must be discovered from only one environment or region.
func WithRegistryIDs(registryIDs ...string) ReferenceOption {
return func(opts *ReferenceOptions) {
if len(registryIDs) > 0 {
@@ -199,6 +213,10 @@ func WithRegistryIDs(registryIDs ...string)
ReferenceOption {
}
}
+// WithRegistry makes a registry configuration available to this reference for
service
+// discovery. Give each registry a distinct registry.WithID and use
WithRegistryIDs when
+// only a subset should be queried. Use it for service-specific discovery;
shared registries
+// are usually configured once with WithClientRegistry.
func WithRegistry(opts ...registry.Option) ReferenceOption {
regOpts := registry.NewOptions(opts...)
@@ -212,60 +230,89 @@ func WithRegistry(opts ...registry.Option)
ReferenceOption {
// ========== Cluster Strategy ==========
+// WithClusterAvailable invokes the first provider currently reporting itself
available.
+// It performs neither load balancing nor retries and fails when none are
available. Use it
+// only when selecting any healthy endpoint is more important than
distributing traffic.
func WithClusterAvailable() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyAvailable
}
}
+// WithClusterBroadcast invokes every provider sequentially. The call reports
an error if
+// any provider fails, so use it for operations that must reach all instances,
such as
+// refreshing local state on every node. The service operation should tolerate
repeated calls.
func WithClusterBroadcast() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyBroadcast
}
}
+// WithClusterFailBack returns an empty successful result when the initial
invocation fails
+// and schedules background retries with exponential backoff. It suits
notifications where
+// eventual delivery matters more than reporting the first failure to the
caller.
func WithClusterFailBack() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyFailback
}
}
+// WithClusterFailFast selects one provider, invokes it once, and returns its
error without
+// retrying another provider. It suits non-idempotent operations where retries
are unsafe.
func WithClusterFailFast() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyFailfast
}
}
+// WithClusterFailOver retries non-business failures on reselected providers.
WithRetries
+// controls the additional attempts after the initial call; business errors
are returned
+// immediately and are not retried. Use it for idempotent calls that should
survive an
+// unavailable provider, and avoid it when repeating the operation can
duplicate side effects.
func WithClusterFailOver() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyFailover
}
}
+// WithClusterFailSafe logs and suppresses provider or discovery errors,
returning an empty
+// result to the caller. It is intended for best-effort operations such as
audit logging.
func WithClusterFailSafe() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyFailsafe
}
}
+// WithClusterForking invokes multiple selected providers concurrently and
returns the first
+// completed result. Use it for idempotent, latency-sensitive reads; it
reduces tail latency at
+// the cost of duplicate work and extra provider load.
func WithClusterForking() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyForking
}
}
+// WithClusterZoneAware chooses among multiple registries by preferring a
registry marked
+// preferred, then one in the request's zone, and finally a weighted available
registry. Use
+// it for multi-region deployments that should keep traffic local while
retaining fallback.
func WithClusterZoneAware() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyZoneAware
}
}
+// WithClusterAdaptiveService selects providers using adaptive
remaining-capacity metrics.
+// It requires P2C load balancing and participating providers that return
adaptive metrics.
+// Use the pair for workloads whose instance capacity varies significantly at
runtime.
func WithClusterAdaptiveService() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = constant.ClusterKeyAdaptiveService
}
}
+// WithCluster selects a registered cluster extension by name. Reference
creation or
+// invocation fails if no extension has been registered under that name. Use
it when a built-in
+// failure policy does not match the service and the application has
registered a custom one.
func WithCluster(cluster string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Cluster = cluster
@@ -274,84 +321,122 @@ func WithCluster(cluster string) ReferenceOption {
// ========== LoadBalance Strategy ==========
+// WithLoadBalanceConsistentHashing routes calls with the same configured
argument values to
+// the same provider while the provider set is stable. Use it for affinity
workloads such as
+// per-user caches; provider membership changes can remap some keys.
func WithLoadBalanceConsistentHashing() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance =
constant.LoadBalanceKeyConsistentHashing
}
}
+// WithLoadBalanceLeastActive favors providers with the fewest in-flight
requests. Ties are
+// resolved by warm-up-adjusted weight. Use it when request durations vary and
queueing work on
+// a busy instance would hurt latency.
func WithLoadBalanceLeastActive() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance = constant.LoadBalanceKeyLeastActive
}
}
+// WithLoadBalanceRandom chooses providers randomly in proportion to their
effective weight.
+// It is a low-overhead general-purpose choice for statistically even traffic
distribution.
func WithLoadBalanceRandom() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance = constant.LoadBalanceKeyRandom
}
}
+// WithLoadBalanceRoundRobin distributes calls in a smooth weighted
round-robin sequence. Use
+// it when requests have similar cost and predictable per-instance traffic is
desirable.
func WithLoadBalanceRoundRobin() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance = constant.LoadBalanceKeyRoundRobin
}
}
+// WithLoadBalanceP2C samples two providers and chooses the one with more
recorded remaining
+// capacity. Use it with WithClusterAdaptiveService for providers that publish
adaptive metrics.
func WithLoadBalanceP2C() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance = constant.LoadBalanceKeyP2C
}
}
+// WithLoadBalance selects a registered load-balancing extension by name. Use
it when the
+// built-in algorithms do not satisfy a domain-specific placement requirement.
func WithLoadBalance(lb string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Loadbalance = lb
}
}
+// WithRetries sets the number of additional attempts made after an initial
failure by
+// retry-capable cluster strategies such as failover. A value of zero means
one attempt total.
+// Enable retries only for idempotent operations because another provider may
repeat the work.
func WithRetries(retries int) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Retries = strconv.Itoa(retries)
}
}
+// WithGroup restricts discovery to providers exported in the same group,
allowing multiple
+// logical implementations of one interface to coexist. Use groups to separate
environments,
+// tenants, or implementations; a mismatched group yields no provider.
func WithGroup(group string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Group = group
}
}
+// WithVersion restricts discovery to providers exporting the same service
version. A
+// mismatched version yields no provider even when the interface name matches.
func WithVersion(version string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Version = version
}
}
+// WithSerializationJSON encodes request and response payloads with JSON. The
provider and
+// selected protocol must support JSON or the invocation cannot be decoded.
Use it for
+// interoperability when human-readable JSON matters more than compact binary
payloads.
func WithSerializationJSON() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Serialization = constant.JSONSerialization
}
}
+// WithSerialization selects the wire serialization by extension name. The
provider and
+// selected protocol must support the same serialization. Use it when both
sides have installed
+// a non-default serialization extension.
func WithSerialization(serialization string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Serialization = serialization
}
}
+// WithProvidedBy supplies a comma-separated list of provider application
names for
+// application-level service discovery. The registry subscribes to these
applications
+// directly instead of resolving the interface through dynamic service-name
mapping. Use it
+// when the provider applications are known ahead of time or mapping metadata
is unavailable.
func WithProvidedBy(providedBy string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.ProvidedBy = providedBy
}
}
+// WithAsync builds an asynchronous proxy for this reference. When the service
implements
+// common.AsyncCallbackService, completed invocations are delivered to its
callback. Use it
+// when the caller should continue work instead of waiting synchronously for
the response.
func WithAsync() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Async = true
}
}
+// WithParams replaces the custom URL parameters published with this
reference. Filters,
+// routers, protocols, and extensions may consume these keys. Use it to
configure an extension
+// with several related values; use WithParam to change one key without
replacing the map.
func WithParams(params map[string]string) ReferenceOption {
return func(opts *ReferenceOptions) {
if len(params) <= 0 {
@@ -361,14 +446,17 @@ func WithParams(params map[string]string) ReferenceOption
{
}
}
+// WithGeneric enables map-based generic invocation, allowing calls without
generated service
+// stubs by representing business objects as generic maps. Use WithGenericType
for another
+// supported generalization format.
func WithGeneric() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Generic = "true"
}
}
-// WithGenericType sets the generic mode (generalization format), which
decides how
-// business objects are generalized into a generic structure.
+// WithGenericType enables generic invocation and selects how business objects
are represented
+// when generated service types are unavailable.
//
// Valid values: "true" (default, Map), "gson", "protobuf-json", "bean".
// "protobuf" is kept as a legacy compatibility value and is not recommended.
@@ -384,12 +472,17 @@ func WithGenericType(genericType string) ReferenceOption {
}
}
+// WithSticky keeps selecting the previously chosen provider while it remains
available,
+// reducing provider churn but potentially weakening load distribution. Use it
for providers
+// that keep session-local state and prefer consistent hashing when a stable
key is available.
func WithSticky() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Sticky = true
}
}
+// WithIDL sets ReferenceOptions.Reference.IDLMode for legacy clients.
+//
// TODO: remove this function after old triple removed
//
// Deprecated: this option will be removed in the next version. The IDL mode
@@ -402,48 +495,68 @@ func WithIDL(IDLMode string) ReferenceOption {
// ========== Protocol to consume ==========
+// WithProtocolDubbo restricts this reference to providers exported with the
Dubbo protocol.
+// Use it when consuming an existing Dubbo-protocol service rather than the
default Triple endpoint.
func WithProtocolDubbo() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Protocol = constant.DubboProtocol
}
}
+// WithProtocolTriple restricts this reference to providers exported with the
Triple protocol.
+// Use it for Triple or gRPC-compatible services and their HTTP/2 features.
func WithProtocolTriple() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Protocol = constant.TriProtocol
}
}
+// WithProtocolJsonRPC restricts this reference to providers exported with
JSON-RPC. Use it when
+// interoperating with a provider exposed through JSON-RPC rather than Dubbo
or Triple.
func WithProtocolJsonRPC() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Protocol = constant.JSONRPCProtocol
}
}
+// WithProtocol restricts this reference to a protocol registered under the
supplied name. Use
+// it for a custom protocol extension; prefer the named helpers for built-in
protocols.
func WithProtocol(protocol string) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.Protocol = protocol
}
}
+// WithRequestTimeout limits how long each invocation on this reference may
wait before it
+// fails with a timeout. Set it to the service's expected latency budget so
stalled providers do
+// not hold resources indefinitely. A call-level WithCallRequestTimeout takes
precedence.
func WithRequestTimeout(timeout time.Duration) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.RequestTimeout = timeout.String()
}
}
+// WithForceTag prevents tag routing from falling back to untagged providers
when no provider
+// matches the requested tag; the invocation fails instead. Use it for strict
traffic isolation,
+// such as canary or tenant pools that must never spill into the default
provider group.
func WithForceTag() ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.ForceTag = true
}
}
+// WithMeshProviderPort overrides the provider port used to build the direct
Kubernetes DNS
+// address in mesh mode. Use it when the mesh-routed service listens on a
non-default port; it
+// has no effect unless mesh mode is enabled.
func WithMeshProviderPort(port int) ReferenceOption {
return func(opts *ReferenceOptions) {
opts.Reference.MeshProviderPort = port
}
}
+// WithMethod adds method-specific settings such as timeout, retries, or load
balancing.
+// Method settings take precedence over the corresponding reference defaults.
Use it when one
+// method is slower, non-idempotent, or otherwise needs different invocation
behavior.
func WithMethod(method *global.MethodConfig) ReferenceOption {
return func(opts *ReferenceOptions) {
if method == nil {
@@ -456,6 +569,9 @@ func WithMethod(method *global.MethodConfig)
ReferenceOption {
}
}
+// WithParam adds one custom URL parameter consumed by filters, routers,
protocols, or other
+// extensions. Use it for an extension setting that has no typed option. A
later call with the
+// same key replaces the earlier value.
func WithParam(k, v string) ReferenceOption {
return func(opts *ReferenceOptions) {
if opts.Reference.Params == nil {
@@ -465,9 +581,9 @@ func WithParam(k, v string) ReferenceOption {
}
}
-// WithRouter appends router configurations to the reference options.
-// This is a user-facing option for incrementally adding routers.
-// It appends to the current router config slice instead of replacing it.
+// WithRouter adds routing rules that filter or reorder candidate providers
before load
+// balancing. Use it for conditions such as region, tag, or application
routing. Multiple calls
+// append rules and preserve their configured order.
func WithRouter(routers ...*global.RouterConfig) ReferenceOption {
return func(opts *ReferenceOptions) {
if len(routers) > 0 {
@@ -644,18 +760,29 @@ func (cliOpts *ClientOptions) init(opts ...ClientOption)
error {
type ClientOption func(*ClientOptions)
+// WithClientNoCheck allows client references to initialize even when no
provider is currently
+// available, so applications can start before their dependencies. Calls still
fail until a
+// provider appears. Use it for independently deployed or temporarily optional
dependencies;
+// WithCheck can restore fail-fast initialization for one mandatory reference.
func WithClientNoCheck() ClientOption {
return func(opts *ClientOptions) {
opts.Consumer.Check = false
}
}
+// WithClientURL sends client references directly to the supplied URL instead
of discovering
+// providers through a registry. Use it for tests or a client dedicated to one
fixed endpoint;
+// it does not follow registry changes. A reference-level WithURL overrides
this default.
func WithClientURL(url string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.URL = url
}
}
+// WithClientFilter selects the comma-separated consumer filter chain applied
to references
+// by default. Use it for cross-cutting behavior shared by all calls, such as
tracing or
+// authentication. A reference-level WithFilter replaces it for one service.
+//
// todo(DMwangnima): change Filter Option like Cluster and LoadBalance
func WithClientFilter(filter string) ClientOption {
return func(opts *ClientOptions) {
@@ -663,6 +790,10 @@ func WithClientFilter(filter string) ClientOption {
}
}
+// WithClientRegistryIDs limits service discovery to the named client
registries by default.
+// Each ID must match a registry added with WithClientRegistry. Use it to keep
all references
+// on a selected environment or region when several registries are configured.
+//
// todo(DMwangnima): think about a more ideal configuration style
func WithClientRegistryIDs(registryIDs ...string) ClientOption {
return func(opts *ClientOptions) {
@@ -672,6 +803,20 @@ func WithClientRegistryIDs(registryIDs ...string)
ClientOption {
}
}
+// WithClientRegistry adds a registry that client references can use for
service discovery.
+// Assign distinct registry.WithID values when configuring more than one
registry. Configure
+// shared discovery here instead of repeating WithRegistry for every reference.
+//
+// For example, this configures Nacos as the default registry for the client:
+//
+// client.NewClient(
+// client.WithClientRegistry(
+// registry.WithNacos(),
+// registry.WithID("nacos"),
+// registry.WithAddress("127.0.0.1:8848"),
+// ),
+// client.WithClientRegistryIDs("nacos"),
+// )
func WithClientRegistry(opts ...registry.Option) ClientOption {
regOpts := registry.NewOptions(opts...)
@@ -680,6 +825,9 @@ func WithClientRegistry(opts ...registry.Option)
ClientOption {
}
}
+// WithClientShutdown controls how long client shutdown waits for in-flight
calls and cleanup
+// steps before forcing progress to the next shutdown phase. Use it to align
graceful shutdown
+// with the process termination budget and avoid dropping active RPCs during
deployment.
func WithClientShutdown(opts ...graceful_shutdown.Option) ClientOption {
sdOpts := graceful_shutdown.NewOptions(opts...)
@@ -688,6 +836,9 @@ func WithClientShutdown(opts ...graceful_shutdown.Option)
ClientOption {
}
}
+// WithClientTLSOption enables and configures TLS for client connections. The
certificates,
+// server name, and trust roots must be compatible with
server.WithServerTLSOption. Use it when
+// traffic must be encrypted or the client must authenticate the provider or
itself.
func WithClientTLSOption(opts ...tls.Option) ClientOption {
tlsOpts := tls.NewOptions(opts...)
@@ -701,74 +852,103 @@ func WithClientTLSOption(opts ...tls.Option)
ClientOption {
// ========== Cluster Strategy ==========
+// WithClientClusterAvailable makes references invoke the first available
provider without
+// load balancing or retries unless a reference selects another strategy. Use
it only when any
+// healthy endpoint is sufficient and even traffic distribution is not
required.
func WithClientClusterAvailable() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyAvailable
}
}
+// WithClientClusterBroadcast makes references invoke every provider and
report an error if
+// any invocation fails unless a reference selects another strategy. Use it
for operations such
+// as cache invalidation that intentionally run on every provider.
func WithClientClusterBroadcast() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyBroadcast
}
}
+// WithClientClusterFailBack makes references suppress initial failures and
retry them in the
+// background with exponential backoff, which is suitable for eventual
notifications.
func WithClientClusterFailBack() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyFailback
}
}
+// WithClientClusterFailFast makes references invoke one provider once and
return its error
+// immediately, avoiding unsafe retries for non-idempotent operations.
func WithClientClusterFailFast() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyFailfast
}
}
+// WithClientClusterFailOver makes references retry non-business failures on
reselected
+// providers. Use it as the client default only when calls are generally
idempotent;
+// WithClientRetries controls the additional attempts after the first call.
func WithClientClusterFailOver() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyFailover
}
}
+// WithClientClusterFailSafe makes references log and suppress invocation
errors, returning
+// an empty result for best-effort operations.
func WithClientClusterFailSafe() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyFailsafe
}
}
+// WithClientClusterForking makes references invoke multiple providers
concurrently and use
+// the first completed result, trading duplicate work for lower tail latency.
func WithClientClusterForking() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyForking
}
}
+// WithClientClusterZoneAware makes multi-registry references prefer a
configured preferred
+// registry, then the request's zone, before weighted fallback to another
registry. Use it to
+// keep traffic local in multi-region deployments while retaining disaster
fallback.
func WithClientClusterZoneAware() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = constant.ClusterKeyZoneAware
}
}
+// WithClientClusterAdaptiveService makes references select providers from
reported remaining
+// capacity. It requires P2C load balancing and adaptive-service-enabled
providers. Use it when
+// instance capacity changes dynamically and simple static weights are
insufficient.
func WithClientClusterAdaptiveService() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster =
constant.ClusterKeyAdaptiveService
}
}
+// WithClientClusterStrategy selects a registered cluster extension as the
client default. Use
+// it for an application-specific failure policy; a reference-level cluster
option overrides it.
func WithClientClusterStrategy(strategy string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Cluster = strategy
}
}
-// Deprecated: use triple.WithKeepAliveInterval()
+// WithKeepAliveInterval is retained for compatibility and panics when applied.
+//
+// Deprecated: pass triple.WithKeepAliveInterval through protocol.WithTriple
and WithClientProtocol.
func WithKeepAliveInterval(keepAliveInterval time.Duration) ClientOption {
return func(_ *ClientOptions) {
panic("use triple.WithKeepAliveInterval()")
}
}
-// Deprecated: use triple.WithKeepAliveTimeout()
+// WithKeepAliveTimeout is retained for compatibility and panics when applied.
+//
+// Deprecated: pass triple.WithKeepAliveTimeout through protocol.WithTriple
and WithClientProtocol.
func WithKeepAliveTimeout(keepAliveTimeout time.Duration) ClientOption {
return func(_ *ClientOptions) {
panic("use triple.WithKeepAliveTimeout()")
@@ -777,74 +957,108 @@ func WithKeepAliveTimeout(keepAliveTimeout
time.Duration) ClientOption {
// ========== LoadBalance Strategy ==========
+// WithClientLoadBalanceConsistentHashing keeps calls with the same configured
argument values
+// on the same provider while the provider set remains stable. Use it for
cache or session
+// affinity shared by most references on this client.
func WithClientLoadBalanceConsistentHashing() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance =
constant.LoadBalanceKeyConsistentHashing
}
}
+// WithClientLoadBalanceLeastActive favors providers with the fewest in-flight
requests and
+// uses effective weight to resolve ties. Use it when call durations vary and
busy providers
+// should receive less new work.
func WithClientLoadBalanceLeastActive() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance =
constant.LoadBalanceKeyLeastActive
}
}
+// WithClientLoadBalanceRandom chooses providers randomly in proportion to
effective weight.
+// It is a low-overhead general default for statistically even traffic.
func WithClientLoadBalanceRandom() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance =
constant.LoadBalanceKeyRandom
}
}
+// WithClientLoadBalanceRoundRobin distributes calls using smooth weighted
round robin. Use it
+// when request costs are similar and predictable instance shares are useful.
func WithClientLoadBalanceRoundRobin() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance =
constant.LoadBalanceKeyRoundRobin
}
}
+// WithClientLoadBalanceP2C samples two providers and chooses the one with
more recorded
+// remaining capacity. Use it with WithClientClusterAdaptiveService for
adaptive providers.
func WithClientLoadBalanceP2C() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance = constant.LoadBalanceKeyP2C
}
}
+// WithClientLoadBalance selects a registered load-balancing extension as the
client default.
+// Use it for domain-specific placement rules; a reference-level option
overrides it.
func WithClientLoadBalance(lb string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Loadbalance = lb
}
}
+// WithClientRetries sets the default number of additional attempts after the
initial call for
+// retry-capable strategies. Use retries only for idempotent operations
because another provider
+// may repeat the work. A reference-level or call-level value takes precedence.
func WithClientRetries(retries int) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Retries = strconv.Itoa(retries)
}
}
-// is this needed?
+// WithClientGroup restricts references to providers in this group by default.
A mismatched
+// group produces no providers. Use it when this client should consume one
logical deployment,
+// such as a tenant or environment; WithGroup overrides it for one reference.
+//
+// TODO: determine whether this client-level group option is needed.
func WithClientGroup(group string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Group = group
}
}
-// is this needed?
+// WithClientVersion restricts references to this service version by default.
WithVersion
+// overrides it for one reference. Use it during incompatible API migrations
when a client must
+// remain on a specific provider version.
+//
+// TODO: determine whether this client-level version option is needed.
func WithClientVersion(version string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Version = version
}
}
+// WithClientSerializationJSON uses JSON payload encoding for references by
default. Providers
+// and protocols that do not support JSON cannot decode those calls. Use it
for interoperability
+// when human-readable JSON is preferred over compact binary serialization.
func WithClientSerializationJSON() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Serialization = constant.JSONSerialization
}
}
+// WithClientSerialization selects the default wire serialization by extension
name. Providers
+// must advertise a compatible serialization. Use it when both sides install
the same custom
+// serialization extension.
func WithClientSerialization(ser string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Serialization = ser
}
}
+// WithClientProvidedBy supplies the default comma-separated provider
application names for
+// application-level discovery, bypassing dynamic interface-to-application
mapping. Use it when
+// provider applications are known or service-name mapping metadata is
unavailable.
func WithClientProvidedBy(providedBy string) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.ProvidedBy = providedBy
@@ -858,6 +1072,9 @@ func WithClientProvidedBy(providedBy string) ClientOption {
// }
// }
+// WithClientParams replaces the custom URL parameters inherited by client
references. These
+// parameters can configure filters, routers, protocols, and extensions. Use
it for extension
+// settings shared by all references; reference-level params take precedence.
func WithClientParams(params map[string]string) ClientOption {
return func(opts *ClientOptions) {
if len(params) <= 0 {
@@ -867,6 +1084,9 @@ func WithClientParams(params map[string]string)
ClientOption {
}
}
+// WithClientParam adds one custom URL parameter inherited by references. A
later call with
+// the same key replaces its value. Use it for an extension setting shared
across references
+// when no typed client option exists.
func WithClientParam(k, v string) ClientOption {
return func(opts *ClientOptions) {
if opts.overallReference.Params == nil {
@@ -876,9 +1096,9 @@ func WithClientParam(k, v string) ClientOption {
}
}
-// WithClientRouter appends router configurations to the client options.
-// This is a user-facing option for incrementally adding routers.
-// It appends to the current router slice instead of replacing it.
+// WithClientRouter adds routing rules that filter or reorder candidate
providers before load
+// balancing for client references. Use it for routing policies shared by the
client, such as
+// preferring the local region; reference-level routers can add
service-specific rules.
func WithClientRouter(routers ...*global.RouterConfig) ClientOption {
return func(opts *ClientOptions) {
if len(routers) > 0 {
@@ -898,6 +1118,9 @@ func WithClientRouter(routers ...*global.RouterConfig)
ClientOption {
// }
// }
+// WithClientSticky keeps each reference on its previously selected provider
while that
+// provider remains available. Use it for session-local provider state,
accepting less even
+// traffic distribution. WithSticky enables the same behavior for one
reference.
func WithClientSticky() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.Sticky = true
@@ -906,24 +1129,33 @@ func WithClientSticky() ClientOption {
// ========== Protocol to consume ==========
+// WithClientProtocolDubbo discovers and invokes Dubbo-protocol providers by
default. Use it
+// when most services consumed by this client expose the classic Dubbo
protocol.
func WithClientProtocolDubbo() ClientOption {
return func(opts *ClientOptions) {
opts.Consumer.Protocol = constant.DubboProtocol
}
}
+// WithClientProtocolTriple discovers and invokes Triple-protocol providers by
default. Use it
+// for Triple or gRPC-compatible services and their HTTP/2 features.
func WithClientProtocolTriple() ClientOption {
return func(opts *ClientOptions) {
opts.Consumer.Protocol = constant.TriProtocol
}
}
+// WithClientProtocolJsonRPC discovers and invokes JSON-RPC providers by
default. Use it for a
+// client whose services are primarily exposed through JSON-RPC.
func WithClientProtocolJsonRPC() ClientOption {
return func(opts *ClientOptions) {
opts.Consumer.Protocol = constant.JSONRPCProtocol
}
}
+// WithClientProtocol configures transport-specific client behavior such as
Triple keepalive,
+// message limits, or protocol selection. Use it to apply one transport policy
to all references;
+// a reference may supply its own protocol settings.
func WithClientProtocol(opts ...protocol.ClientOption) ClientOption {
proOpts := protocol.NewClientOptions(opts...)
@@ -935,81 +1167,94 @@ func WithClientProtocol(opts ...protocol.ClientOption)
ClientOption {
}
}
+// WithClientRequestTimeout limits how long client calls wait by default
before failing with
+// a timeout. Set it to the application's usual dependency latency budget so
stalled calls do
+// not retain resources indefinitely. Reference and call-level timeouts take
precedence.
func WithClientRequestTimeout(timeout time.Duration) ClientOption {
return func(opts *ClientOptions) {
opts.Consumer.RequestTimeout = timeout.String()
}
}
+// WithClientForceTag prevents tag routing from falling back to untagged
providers when no
+// provider matches the requested tag. Use it when every reference must
preserve strict canary,
+// tenant, or environment isolation.
func WithClientForceTag() ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.ForceTag = true
}
}
+// WithClientMeshProviderPort overrides the provider port used in Kubernetes
service DNS
+// addresses generated in mesh mode; it has no effect when mesh mode is
disabled.
func WithClientMeshProviderPort(port int) ClientOption {
return func(opts *ClientOptions) {
opts.overallReference.MeshProviderPort = port
}
}
+// SetClientRegistries replaces ClientOptions.Registries with framework-loaded
configuration.
+// User code should prefer WithClientRegistry and WithClientRegistryIDs.
func SetClientRegistries(regs map[string]*global.RegistryConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Registries = regs
}
}
+// SetClientApplication assigns framework-loaded application configuration to
ClientOptions.Application.
func SetClientApplication(application *global.ApplicationConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Application = application
}
}
+// SetClientConsumer assigns framework-loaded consumer configuration to
ClientOptions.Consumer.
func SetClientConsumer(consumer *global.ConsumerConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Consumer = consumer
}
}
+// SetClientShutdown assigns framework-loaded shutdown configuration to
ClientOptions.Shutdown.
+// User code should prefer WithClientShutdown.
func SetClientShutdown(shutdown *global.ShutdownConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Shutdown = shutdown
}
}
+// SetClientMetrics assigns framework-loaded metrics configuration to
ClientOptions.Metrics.
func SetClientMetrics(metrics *global.MetricsConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Metrics = metrics
}
}
+// SetClientOtel assigns framework-loaded OpenTelemetry configuration to
ClientOptions.Otel.
func SetClientOtel(otel *global.OtelConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Otel = otel
}
}
+// SetClientTLS assigns framework-loaded TLS configuration to
ClientOptions.TLS.
+// User code should prefer WithClientTLSOption.
func SetClientTLS(tls *global.TLSConfig) ClientOption {
return func(opts *ClientOptions) {
opts.TLS = tls
}
}
-// SetClientProtocols sets the protocols configuration for the client.
-// This function is used by the framework to configure protocol settings from
global configuration.
-// It accepts a map of protocol configurations where the key is the protocol
name
-// and the value is the corresponding protocol configuration.
+// SetClientProtocols replaces ClientOptions.Protocols with framework-loaded
configuration.
+// User code should prefer WithClientProtocol.
func SetClientProtocols(protocols map[string]*global.ProtocolConfig)
ClientOption {
return func(opts *ClientOptions) {
opts.Protocols = protocols
}
}
-// SetClientRouters sets the routers configuration for the client.
-// This is an internal framework function for applying router settings to
-// client options.
-// End users should not use this function for configuration.
-// It replaces the current router slice instead of appending to it.
+// SetClientRouters replaces ClientOptions.Routers with framework-loaded
configuration.
+// User code should prefer WithClientRouter or reference-level WithRouter.
func SetClientRouters(routers []*global.RouterConfig) ClientOption {
return func(opts *ClientOptions) {
opts.Routers = routers
@@ -1030,32 +1275,38 @@ func newDefaultCallOptions() *CallOptions {
return &CallOptions{}
}
-// WithCallRequestTimeout the maximum waiting time for one specific call, only
works for 'tri' and 'dubbo' protocol
+// WithCallRequestTimeout limits one Triple or Dubbo invocation. Use it when
an individual call
+// has a tighter or looser latency budget than the service default. It
overrides WithRequestTimeout
+// and WithClientRequestTimeout for that call.
func WithCallRequestTimeout(timeout time.Duration) CallOption {
return func(opts *CallOptions) {
opts.RequestTimeout = timeout.String()
}
}
-// WithCallRetries the maximum retry times on request failure for one specific
call, only works for 'tri' and 'dubbo' protocol
+// WithCallRetries sets the additional attempts for one Triple or Dubbo
invocation. Use it only
+// when that operation is idempotent and needs a different resilience policy.
It overrides
+// WithRetries and WithClientRetries for that call.
func WithCallRetries(retries int) CallOption {
return func(opts *CallOptions) {
opts.Retries = strconv.Itoa(retries)
}
}
-// WithResponseHeader configures a target to receive response headers.
+// WithResponseHeader sets CallOptions.ResponseHeader as the target for
response headers.
// Currently, only Triple unary calls populate this option (including error
-// responses when metadata is available).
+// responses when metadata is available). Use it to inspect provider metadata
such as tracing
+// or application-specific response attributes after the call returns.
func WithResponseHeader(header *http.Header) CallOption {
return func(opts *CallOptions) {
opts.ResponseHeader = header
}
}
-// WithResponseTrailer configures a target to receive response trailers.
+// WithResponseTrailer sets CallOptions.ResponseTrailer as the target for
response trailers.
// Currently, only Triple unary calls populate this option (including error
-// responses when metadata is available).
+// responses when metadata is available). Use it for metadata emitted after
the response body,
+// such as final status or diagnostic information.
func WithResponseTrailer(trailer *http.Header) CallOption {
return func(opts *CallOptions) {
opts.ResponseTrailer = trailer
diff --git a/protocol/options.go b/protocol/options.go
index 2a0044c11..6f8a4aebb 100644
--- a/protocol/options.go
+++ b/protocol/options.go
@@ -40,7 +40,9 @@ type Option interface {
ServerOption
}
-// WithClientOptions composes multiple ClientOptions into one.
+// WithClientOptions composes ClientOption values for NewClientOptions and
applies
+// each option to the same ClientOptions instance in order. Use it to package
a reusable client
+// transport policy, such as Triple keepalive and message-size settings, into
one option.
func WithClientOptions(options ...ClientOption) ClientOption {
return &clientOptionsOption{options}
}
@@ -55,7 +57,9 @@ func (o *clientOptionsOption) applyToClient(config
*ClientOptions) {
}
}
-// WithServerOptions composes multiple ServerOptions into one.
+// WithServerOptions composes ServerOption values for NewServerOptions and
applies
+// each option to the same ServerOptions instance in order. Use it to package
a reusable server
+// endpoint policy before passing it to server.WithProtocol or
server.WithServerProtocol.
func WithServerOptions(options ...ServerOption) ServerOption {
return &serverOptionsOption{options}
}
@@ -70,7 +74,9 @@ func (o *serverOptionsOption) applyToServer(config
*ServerOptions) {
}
}
-// WithOptions composes multiple Options into one.
+// WithOptions composes options that apply to both ClientOptions and
ServerOptions.
+// Use it when the same transport settings must be shared by clients and
servers, for example
+// common Triple message limits in an application that both consumes and
provides services.
func WithOptions(options ...Option) Option {
return &optionsOption{options}
}
@@ -161,7 +167,10 @@ func (o *tripleOption) applyToServer(config
*ServerOptions) {
config.Protocol.TripleConfig = o.triOpts.Triple
}
-// WithTriple applies Triple protocol options to clients and servers.
+// WithTriple applies Triple transport settings, such as message limits or
keepalive behavior,
+// to both client and server protocol configurations. The default protocol is
Triple; when
+// combining options explicitly, use it with a matching protocol selection.
Choose Triple for
+// HTTP/2, streaming, or gRPC-compatible interoperability.
func WithTriple(opts ...triple.Option) Option {
triSrvOpts := triple.NewOptions(opts...)
@@ -180,7 +189,8 @@ func (o *dubboOption) applyToServer(config *ServerOptions) {
config.Protocol.Name = constant.DubboProtocol
}
-// WithDubbo selects the Dubbo protocol for clients and servers.
+// WithDubbo makes clients create Dubbo transports and servers expose Dubbo
endpoints. Choose it
+// when interoperating with existing services that use the classic Dubbo
protocol.
func WithDubbo() Option {
return &dubboOption{}
}
@@ -195,7 +205,8 @@ func (o *jsonRPCOption) applyToServer(config
*ServerOptions) {
config.Protocol.Name = constant.JSONRPCProtocol
}
-// WithJSONRPC selects the JSON-RPC protocol for clients and servers.
+// WithJSONRPC makes clients create JSON-RPC transports and servers expose
JSON-RPC endpoints.
+// Choose it when integrating with systems that speak JSON-RPC rather than
Dubbo or Triple.
func WithJSONRPC() Option {
return &jsonRPCOption{}
}
@@ -210,7 +221,8 @@ func (o *restOption) applyToServer(config *ServerOptions) {
config.Protocol.Name = constant.RESTProtocol
}
-// WithREST selects the REST protocol for clients and servers.
+// WithREST makes clients create REST transports and servers expose REST
endpoints. Choose it
+// when the service contract is exposed as HTTP resources for REST clients.
func WithREST() Option {
return &restOption{}
}
@@ -227,7 +239,10 @@ func (o *protocolNameOption) applyToServer(config
*ServerOptions) {
config.Protocol.Name = o.Name
}
-// NOTE: This option can't be configured freely.
+// WithProtocol selects a registered transport extension for both clients and
servers. Protocol
+// initialization fails when the supplied name has no matching extension;
prefer the built-in
+// selection helpers when applicable. Use this option only for a custom
protocol registered by
+// the application or another module.
func WithProtocol(p string) Option {
return &protocolNameOption{p}
}
@@ -242,8 +257,9 @@ func (o *idOption) applyToServer(config *ServerOptions) {
config.ID = o.ID
}
-// WithID sets the protocol ID. Use server.WithProtocolIDs or
server.WithServerProtocolIDs
-// to select the protocol in a multi-protocol scenario.
+// WithID names this server protocol configuration so services can select it
with
+// server.WithProtocolIDs or server.WithServerProtocolIDs. IDs must be
distinct when multiple
+// endpoints use the same protocol on different addresses or ports.
func WithID(id string) ServerOption {
return &idOption{id}
}
@@ -256,7 +272,9 @@ func (o *ipOption) applyToServer(config *ServerOptions) {
config.Protocol.Ip = o.Ip
}
-// WithIp sets the IP address for the server protocol.
+// WithIp binds this protocol endpoint to the supplied local IP and publishes
that address to
+// registries. Use it on multi-homed hosts to choose the correct network
interface, and ensure
+// the published address is reachable by consumers.
func WithIp(ip string) ServerOption {
return &ipOption{ip}
}
@@ -269,7 +287,9 @@ func (o *portOption) applyToServer(config *ServerOptions) {
config.Protocol.Port = o.Port
}
-// WithPort sets the port for the server protocol.
+// WithPort binds and publishes this protocol endpoint on the supplied port.
When omitted, the
+// server allocates an available random port during export. Set a stable port
for production,
+// firewall rules, or direct clients; omit it when an ephemeral test port is
acceptable.
func WithPort(port int) ServerOption {
return &portOption{strconv.Itoa(port)}
}
@@ -282,19 +302,26 @@ func (o *paramsOption) applyToServer(config
*ServerOptions) {
config.Protocol.Params = o.Params
}
-// WithParams sets the parameters for the server protocol.
+// WithParams supplies transport-specific server settings consumed by the
selected protocol,
+// such as its underlying remoting configuration. The expected value type
depends on that
+// protocol implementation. Use it only when the protocol documents a concrete
parameter type;
+// prefer typed options such as WithTriple when they are available.
func WithParams(params any) ServerOption {
return ¶msOption{params}
}
// ========== Deprecated options ==========
-// Deprecated: use triple.WithMaxServerSendMsgSize instead.
+// WithMaxServerSendMsgSize is retained for compatibility and panics when
applied.
+//
+// Deprecated: use triple.WithMaxServerSendMsgSize with WithTriple instead.
func WithMaxServerSendMsgSize(size string) ServerOption {
panic("use triple.WithMaxServerSendMsgSize()")
}
-// Deprecated: use triple.WithMaxServerRecvMsgSize instead.
+// WithMaxServerRecvMsgSize is retained for compatibility and panics when
applied.
+//
+// Deprecated: use triple.WithMaxServerRecvMsgSize with WithTriple instead.
func WithMaxServerRecvMsgSize(size string) ServerOption {
panic("use triple.WithMaxServerRecvMsgSize()")
}
diff --git a/server/options.go b/server/options.go
index 93ba8add1..abf4bc081 100644
--- a/server/options.go
+++ b/server/options.go
@@ -126,43 +126,64 @@ type ServerOption func(*ServerOptions)
// ========== LoadBalance Strategy ==========
+// WithServerLoadBalanceConsistentHashing advertises consistent hashing as the
default
+// consumer load balancer for every service. Calls with the same configured
arguments tend
+// to reach the same provider while the provider set is stable. Use it when
most services need
+// cache or session affinity; service-level load-balancing options can
override it.
func WithServerLoadBalanceConsistentHashing() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance =
constant.LoadBalanceKeyConsistentHashing
}
}
+// WithServerLoadBalanceLeastActive advertises least-active load balancing as
the default for
+// consumers, favoring providers with fewer in-flight requests and using
weight to break ties.
+// Use it when request duration varies and busy instances should receive less
work.
func WithServerLoadBalanceLeastActive() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance = constant.LoadBalanceKeyLeastActive
}
}
+// WithServerLoadBalanceRandom advertises weighted-random provider selection
as the default
+// consumer load-balancing policy. It is a low-overhead general default for
statistically even
+// traffic across services.
func WithServerLoadBalanceRandom() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance = constant.LoadBalanceKeyRandom
}
}
+// WithServerLoadBalanceRoundRobin advertises smooth weighted round-robin
provider selection
+// as the default consumer load-balancing policy. Use it when requests have
similar cost and
+// predictable per-instance traffic shares are desirable.
func WithServerLoadBalanceRoundRobin() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance = constant.LoadBalanceKeyRoundRobin
}
}
+// WithServerLoadBalanceP2C advertises P2C as the default consumer load
balancer. Consumers
+// sample two providers and favor the one reporting more remaining capacity.
Use it together
+// with WithServerAdaptiveService for capacity-aware routing.
func WithServerLoadBalanceP2C() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance = constant.LoadBalanceKeyP2C
}
}
+// WithServerLoadBalance advertises a registered load-balancing extension as
the default for
+// consumers. Use it for domain-specific provider placement; a service-level
option overrides it.
func WithServerLoadBalance(lb string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Loadbalance = lb
}
}
-// warmUp is in seconds
+// WithServerWarmUp gradually increases newly started providers' effective
weight over the
+// supplied duration, reducing traffic while caches and other resources warm
up. Durations
+// shorter than one second are truncated. Use it when cold instances cannot
safely receive full
+// traffic immediately; WithServerWarmup preserves sub-second duration strings.
func WithServerWarmUp(warmUp time.Duration) ServerOption {
return func(opts *ServerOptions) {
warmUpSec := int(warmUp / time.Second)
@@ -172,175 +193,264 @@ func WithServerWarmUp(warmUp time.Duration)
ServerOption {
// ========== Cluster Strategy ==========
+// WithServerClusterAvailable tells consumers to invoke the first available
provider without
+// load balancing or retries by default. Use it only when any healthy provider
is sufficient
+// and balanced traffic is not required.
func WithServerClusterAvailable() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyAvailable
}
}
+// WithServerClusterBroadcast tells consumers to invoke every provider
sequentially by
+// default and report an error if any provider fails. Use it for operations
such as cache
+// invalidation that intentionally run on every instance.
func WithServerClusterBroadcast() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyBroadcast
}
}
+// WithServerClusterFailBack tells consumers to hide an initial failure and
retry the call in
+// the background with exponential backoff. Use it for best-effort
notifications where eventual
+// delivery matters more than returning the initial error.
func WithServerClusterFailBack() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyFailback
}
}
+// WithServerClusterFailFast tells consumers to invoke once and return the
error without
+// retrying another provider. Use it for non-idempotent operations where
duplicate execution
+// would be more harmful than an immediate failure.
func WithServerClusterFailFast() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyFailfast
}
}
+// WithServerClusterFailOver tells consumers to retry non-business failures on
reselected
+// providers. Use it for idempotent calls that should survive one unavailable
instance;
+// WithServerRetries controls the additional attempts after the first call.
func WithServerClusterFailOver() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyFailover
}
}
+// WithServerClusterFailSafe tells consumers to log and suppress invocation
failures,
+// returning an empty result. Use it only for optional best-effort work, such
as audit events,
+// because callers cannot distinguish a suppressed failure from an empty
success.
func WithServerClusterFailSafe() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyFailsafe
}
}
+// WithServerClusterForking tells consumers to invoke multiple providers
concurrently and
+// return the first completed result. Use it for idempotent, latency-sensitive
reads and accept
+// the duplicate work and extra provider load it creates.
func WithServerClusterForking() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyForking
}
}
+// WithServerClusterZoneAware tells consumers using multiple registries to
prefer an explicitly
+// preferred registry, then the request's zone, before falling back by
registry weight. Use it
+// for multi-region services that should keep traffic local while retaining
fallback.
func WithServerClusterZoneAware() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyZoneAware
}
}
+// WithServerClusterAdaptiveService advertises adaptive remaining-capacity
routing to consumers.
+// Consumers must also use P2C and providers must publish adaptive capacity
metrics. Use it for
+// services whose effective instance capacity changes significantly under load.
func WithServerClusterAdaptiveService() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = constant.ClusterKeyAdaptiveService
}
}
+// WithServerCluster advertises a registered cluster extension as the default
consumer fault
+// handling policy. Use it for an application-specific failure policy; a
service-level cluster
+// option overrides it.
func WithServerCluster(cluster string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Cluster = cluster
}
}
+// WithServerGroup publishes services in the supplied group by default,
allowing multiple
+// logical implementations of one interface to coexist. Use groups for
environments, tenants,
+// or alternate implementations; consumers must request the same group.
func WithServerGroup(group string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Group = group
}
}
+// WithServerVersion publishes services under the supplied version by default.
Consumers with
+// another version cannot discover them. Use it during incompatible API
migrations; a
+// service-level WithVersion overrides this value.
func WithServerVersion(version string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Version = version
}
}
+// WithServerJSON uses JSON as the default wire serialization for exported
services. Consumers
+// and the selected protocol must support JSON or requests cannot be decoded.
Use it for
+// interoperability when readable payloads matter more than compact binary
encoding.
func WithServerJSON() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Serialization = constant.JSONSerialization
}
}
-// WithToken should be used with WithFilter("token")
+// WithServerToken requires consumers to present the same service token when
the token provider
+// filter is active. Use it for simple shared-secret protection and pair it
with
+// WithServerFilter("token") or a chain containing that filter.
func WithServerToken(token string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Token = token
}
}
+// WithServerNotRegister prevents services from being published to registries
by default while
+// still allowing the server to listen. Use it for local tests or private
fixed endpoints; such
+// services must be reached by a direct URL.
func WithServerNotRegister() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.NotRegister = true
}
}
+// WithServerWarmup gradually increases newly started providers' effective
load-balancing
+// weight over the supplied duration. Use it for cold-start protection when
caches or connection
+// pools need time to fill. It preserves values such as "500ms" in the
provider URL.
func WithServerWarmup(warmupDuration time.Duration) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Warmup = warmupDuration.String()
}
}
+// WithServerRetries advertises how many additional attempts retry-capable
consumers may make
+// after the initial call. Zero means one total attempt. Use retries only for
idempotent services;
+// service-level settings take precedence.
func WithServerRetries(retries int) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Retries = strconv.Itoa(retries)
}
}
+// WithServerSerialization selects the default wire serialization by extension
name. Consumers
+// and the selected protocol must support the same serialization. Use it when
both sides install
+// the same non-default serialization extension.
func WithServerSerialization(ser string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Serialization = ser
}
}
+// WithServerAccesslog enables provider access logging by default. A file path
writes access
+// records there; "true" or "default" sends them to the application logger.
Logging is
+// asynchronous and records may be dropped if its channel is full. Use it for
request auditing
+// or troubleshooting, accounting for payload visibility and storage cost.
func WithServerAccesslog(accesslog string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.AccessLog = accesslog
}
}
+// WithServerTpsLimiter enables the named TPS limiter for services by default.
An empty name
+// disables TPS limiting; an unregistered name causes service validation to
panic. Use it to
+// protect provider capacity from bursts, together with rate, strategy, and
rejection settings.
func WithServerTpsLimiter(limiter string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.TpsLimiter = limiter
}
}
+// WithServerTpsLimitRate sets the default maximum request rate enforced by
the selected TPS
+// limiter. Use it to express the sustainable throughput of services. It has
no effect until
+// WithServerTpsLimiter selects a limiter.
func WithServerTpsLimitRate(rate int) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.TpsLimitRate = strconv.Itoa(rate)
}
}
+// WithServerTpsLimitStrategy selects the registered rate-limiting strategy
used by the default
+// TPS limiter. Use it to choose how bursts are measured, such as a fixed or
sliding window;
+// an unregistered name causes service validation to panic.
func WithServerTpsLimitStrategy(strategy string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.TpsLimitStrategy = strategy
}
}
+// WithServerTpsLimitRejectedHandler selects the handler invoked when the
default TPS limit is
+// exceeded. Use a custom handler to return a domain-specific error or
fallback result;
+// an unregistered name causes service validation to panic.
func WithServerTpsLimitRejectedHandler(rejHandler string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.TpsLimitRejectedHandler = rejHandler
}
}
+// WithServerExecuteLimit caps concurrent in-flight provider invocations by
default. The value
+// must be an integer string; a negative value disables the cap, while an
invalid value returns
+// an empty result without invoking the service. Use it when concurrency,
rather than request
+// rate, is the scarce resource, such as a bounded database connection pool.
func WithServerExecuteLimit(exeLimit string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.ExecuteLimit = exeLimit
}
}
+// WithServerExecuteLimitRejectedHandler selects the registered handler for
calls rejected after
+// the default in-flight limit is reached. Use it to return a specific
overload response. If
+// lookup fails, the call proceeds after a warning.
func WithServerExecuteLimitRejectedHandler(exeRejHandler string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.ExecuteLimitRejectedHandler = exeRejHandler
}
}
+// WithServerAuth enables AK/SK request-signature verification for services by
default when set
+// to "true" and the provider filter chain contains "auth". Missing or invalid
signatures are
+// rejected before service execution. Use it when providers must authenticate
calling applications;
+// configure access-key storage and signing on both provider and consumer.
func WithServerAuth(auth string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Auth = auth
}
}
+// WithServerParamSign includes request parameters in AK/SK signature
verification by default
+// when set to "true". Use it when signatures must detect parameter tampering;
both sides must
+// canonicalize the same values. It requires authentication and the "auth"
filter.
func WithServerParamSign(paramSign string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.ParamSign = paramSign
}
}
+// WithServerTag publishes services with the supplied routing tag by default,
allowing tagged
+// consumers to target this provider group. Use tags for canary, tenant, or
hardware-specific
+// pools without changing the service interface.
func WithServerTag(tag string) ServerOption {
return func(opts *ServerOptions) {
opts.Provider.Tag = tag
}
}
+// WithServerParam publishes one custom provider URL parameter for filters,
routers, protocols,
+// or extensions. Use it to configure an extension not covered by a typed
option. A later call
+// with the same key replaces the earlier value.
func WithServerParam(k, v string) ServerOption {
return func(opts *ServerOptions) {
if opts.Provider.Params == nil {
@@ -350,6 +460,10 @@ func WithServerParam(k, v string) ServerOption {
}
}
+// WithServerFilter selects the comma-separated provider filter chain applied
to incoming calls
+// by default, in execution order. Use it for shared middleware such as
authentication, metrics,
+// or custom validation. A service-level WithFilter replaces this chain.
+//
// todo(DMwangnima): change Filter Option like Cluster and LoadBalance
func WithServerFilter(filter string) ServerOption {
return func(opts *ServerOptions) {
@@ -357,6 +471,10 @@ func WithServerFilter(filter string) ServerOption {
}
}
+// WithServerRegistryIDs limits service publication to the named registries by
default. Each ID
+// must match a registry added with WithServerRegistry or server
initialization fails. Use it to
+// publish all services to selected environments or regions when several
registries exist.
+//
// todo(DMwangnima): think about a more ideal configuration style
func WithServerRegistryIDs(registryIDs []string) ServerOption {
return func(opts *ServerOptions) {
@@ -364,6 +482,9 @@ func WithServerRegistryIDs(registryIDs []string)
ServerOption {
}
}
+// WithServerRegistry makes a registry available for publishing services. Give
each registry a
+// distinct registry.WithID and use WithServerRegistryIDs to publish only to a
subset. Configure
+// shared registries here instead of repeating WithRegistry for every service.
func WithServerRegistry(opts ...registry.Option) ServerOption {
regOpts := registry.NewOptions(opts...)
@@ -375,6 +496,10 @@ func WithServerRegistry(opts ...registry.Option)
ServerOption {
}
}
+// WithServerProtocolIDs limits service export to the named server protocols
by default. Each ID
+// must match a protocol added with WithServerProtocol. Use it when the server
listens on several
+// endpoints but most services should be exposed through only a selected
subset.
+//
// todo(DMwangnima): think about a more ideal configuration style
func WithServerProtocolIDs(protocolIDs []string) ServerOption {
return func(opts *ServerOptions) {
@@ -382,6 +507,20 @@ func WithServerProtocolIDs(protocolIDs []string)
ServerOption {
}
}
+// WithServerProtocol configures a protocol endpoint on which services may be
exported. Give
+// each endpoint a distinct protocol.WithID when serving multiple protocols or
ports. Configure
+// shared listeners here, then choose them globally or per service with
protocol IDs.
+//
+// For example, this exposes services on a named Triple endpoint:
+//
+// server.NewServer(
+// server.WithServerProtocol(
+// protocol.WithTriple(),
+// protocol.WithID("triple"),
+// protocol.WithPort(20000),
+// ),
+// server.WithServerProtocolIDs([]string{"triple"}),
+// )
func WithServerProtocol(opts ...protocol.ServerOption) ServerOption {
proOpts := protocol.NewServerOptions(opts...)
@@ -393,21 +532,27 @@ func WithServerProtocol(opts ...protocol.ServerOption)
ServerOption {
}
}
+// WithServerAdaptiveService enables provider-side capacity measurement and
publishes the
+// remaining-capacity metrics required by adaptive-service consumers. Use it
with consumer-side
+// adaptive cluster and P2C options when static provider weights do not
reflect current load.
func WithServerAdaptiveService() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.AdaptiveService = true
}
}
+// WithServerAdaptiveServiceVerbose enables detailed adaptive limiter
diagnostics. Server
+// initialization fails unless WithServerAdaptiveService is also enabled. Use
it while tuning or
+// diagnosing adaptive limits; verbose output may be too noisy for normal
production operation.
func WithServerAdaptiveServiceVerbose() ServerOption {
return func(opts *ServerOptions) {
opts.Provider.AdaptiveServiceVerbose = true
}
}
-// WithServerTLSOption applies TLS options to the server configuration.
-// It iterates over the provided tls.
-// TLSOption and applies them to the ServerOptions.TLS field.
+// WithServerTLSOption configures credentials and peer verification for
encrypted server
+// connections. Use it for transport encryption and, when configured, mutual
authentication.
+// Clients must use compatible trust and certificate settings.
func WithServerTLSOption(opts ...tls.Option) ServerOption {
tlsOpts := tls.NewOptions(opts...)
@@ -422,48 +567,59 @@ func WithServerTLSOption(opts ...tls.Option) ServerOption
{
// ========== For framework ==========
// These functions should not be invoked by users
+// SetServerApplication assigns framework-loaded application configuration to
ServerOptions.Application.
func SetServerApplication(application *global.ApplicationConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Application = application
}
}
+// SetServerRegistries replaces ServerOptions.Registries with framework-loaded
configuration.
+// User code should prefer WithServerRegistry and WithServerRegistryIDs.
func SetServerRegistries(regs map[string]*global.RegistryConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Registries = regs
}
}
+// SetServerProtocols replaces ServerOptions.Protocols with framework-loaded
configuration.
+// User code should prefer WithServerProtocol and WithServerProtocolIDs.
func SetServerProtocols(pros map[string]*global.ProtocolConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Protocols = pros
}
}
+// SetServerShutdown assigns framework-loaded shutdown configuration to
ServerOptions.Shutdown.
func SetServerShutdown(shutdown *global.ShutdownConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Shutdown = shutdown
}
}
+// SetServerMetrics assigns framework-loaded metrics configuration to
ServerOptions.Metrics.
func SetServerMetrics(metrics *global.MetricsConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Metrics = metrics
}
}
+// SetServerOtel assigns framework-loaded OpenTelemetry configuration to
ServerOptions.Otel.
func SetServerOtel(otel *global.OtelConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Otel = otel
}
}
+// SetServerTLS assigns framework-loaded TLS configuration to
ServerOptions.TLS.
+// User code should prefer WithServerTLSOption.
func SetServerTLS(tls *global.TLSConfig) ServerOption {
return func(opts *ServerOptions) {
opts.TLS = tls
}
}
+// SetServerProvider assigns framework-loaded provider defaults to
ServerOptions.Provider.
func SetServerProvider(provider *global.ProviderConfig) ServerOption {
return func(opts *ServerOptions) {
opts.Provider = provider
@@ -595,7 +751,7 @@ type ServiceOption func(*ServiceOptions)
// ---------- For user ----------
-// WithInterface sets the interface name for the service being exposed.
+// WithInterface publishes this service under the supplied discovery and
routing identifier.
//
// As a functional option, it is passed to a service registration function
// (e.g., RegisterGreetServiceHandler) to configure the service's properties.
@@ -616,6 +772,10 @@ func WithInterface(interfaceName string) ServiceOption {
}
}
+// WithRegistryIDs publishes this service only to the named registries. Each
ID must match a
+// registry added with WithRegistry or inherited from the server, otherwise
registration fails.
+// Use it when one service belongs in a different environment or region from
the server default.
+//
// todo(DMwangnima): think about a more ideal configuration style
func WithRegistryIDs(registryIDs []string) ServiceOption {
return func(cfg *ServiceOptions) {
@@ -625,6 +785,10 @@ func WithRegistryIDs(registryIDs []string) ServiceOption {
}
}
+// WithFilter selects the comma-separated provider filter chain applied to
incoming calls for
+// this service, in execution order. Use it to add service-specific middleware
such as "auth"
+// or a custom validator. It replaces the server-level default filter chain.
+//
// todo(DMwangnima): change Filter Option like Cluster and LoadBalance
func WithFilter(filter string) ServiceOption {
return func(cfg *ServiceOptions) {
@@ -632,6 +796,10 @@ func WithFilter(filter string) ServiceOption {
}
}
+// WithProtocolIDs exports this service only through the named protocol
endpoints. Each ID must
+// match a protocol added with WithProtocol or inherited from the server. Use
it when this
+// service should expose only Triple, Dubbo, or a dedicated listener.
+//
// todo(DMwangnima): think about a more ideal configuration style
func WithProtocolIDs(protocolIDs []string) ServiceOption {
return func(cfg *ServiceOptions) {
@@ -643,43 +811,61 @@ func WithProtocolIDs(protocolIDs []string) ServiceOption {
// ========== LoadBalance Strategy ==========
+// WithLoadBalanceConsistentHashing tells consumers of this service to route
calls with the same
+// configured arguments to the same provider while the provider set is stable.
Use it for
+// per-user caches or session affinity; membership changes can remap some keys.
func WithLoadBalanceConsistentHashing() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance =
constant.LoadBalanceKeyConsistentHashing
}
}
+// WithLoadBalanceLeastActive tells consumers to favor providers with fewer
in-flight requests,
+// using warm-up-adjusted weight when active counts are equal. Use it when
this service has
+// uneven request durations and busy instances should receive less new work.
func WithLoadBalanceLeastActive() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance = constant.LoadBalanceKeyLeastActive
}
}
+// WithLoadBalanceRandom tells consumers to choose providers randomly in
proportion to their
+// effective weight. Use it as a low-overhead general choice for statistically
even traffic.
func WithLoadBalanceRandom() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance = constant.LoadBalanceKeyRandom
}
}
+// WithLoadBalanceRoundRobin tells consumers to distribute calls using smooth
weighted
+// round-robin selection. Use it when calls have similar cost and predictable
instance shares
+// are desirable.
func WithLoadBalanceRoundRobin() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance = constant.LoadBalanceKeyRoundRobin
}
}
+// WithLoadBalanceP2C tells consumers to sample two providers and favor the
one reporting more
+// remaining capacity. Use it with adaptive-service metrics when instance
capacity changes
+// dynamically under load.
func WithLoadBalanceP2C() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance = constant.LoadBalanceKeyP2C
}
}
+// WithLoadBalance advertises a registered load-balancing extension to
consumers of this
+// service. Use it for a domain-specific placement rule; it overrides the
server-level default.
func WithLoadBalance(lb string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Loadbalance = lb
}
}
-// warmUp is in seconds
+// WithWarmUp gradually increases this provider's effective weight over the
supplied duration,
+// reducing traffic after startup. Use it when this service needs to fill
caches or pools before
+// receiving full traffic. Durations shorter than one second are truncated.
func WithWarmUp(warmUp time.Duration) ServiceOption {
return func(opts *ServiceOptions) {
warmUpSec := int(warmUp / time.Second)
@@ -689,175 +875,265 @@ func WithWarmUp(warmUp time.Duration) ServiceOption {
// ========== Cluster Strategy ==========
+// WithClusterAvailable tells consumers to invoke the first available provider
without load
+// balancing or retries. Use it only when any healthy provider is sufficient
and even traffic
+// distribution is not required.
func WithClusterAvailable() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyAvailable
}
}
+// WithClusterBroadcast tells consumers to invoke every provider sequentially
and report an
+// error if any provider fails. Use it for operations such as invalidating a
cache on every
+// instance; the operation should tolerate repeated calls.
func WithClusterBroadcast() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyBroadcast
}
}
+// WithClusterFailBack tells consumers to hide an initial failure and retry in
the background
+// with exponential backoff, which suits eventual-delivery notifications.
func WithClusterFailBack() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyFailback
}
}
+// WithClusterFailFast tells consumers to invoke once and return the error
without retrying
+// another provider. Use it for non-idempotent operations where duplicate
execution would be
+// more harmful than an immediate failure.
func WithClusterFailFast() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyFailfast
}
}
+// WithClusterFailOver tells consumers to retry non-business failures on
reselected providers.
+// Use it for idempotent operations that should survive one unavailable
instance. WithRetries
+// controls the additional attempts after the first call.
func WithClusterFailOver() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyFailover
}
}
+// WithClusterFailSafe tells consumers to log and suppress invocation
failures, returning an
+// empty result. Use it only for optional best-effort work because callers
cannot distinguish a
+// suppressed failure from an empty success.
func WithClusterFailSafe() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyFailsafe
}
}
+// WithClusterForking tells consumers to invoke multiple providers
concurrently and return the
+// first completed result. Use it for idempotent, latency-sensitive reads and
accept the
+// duplicate work and extra provider load.
func WithClusterForking() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyForking
}
}
+// WithClusterZoneAware tells consumers using multiple registries to prefer an
explicitly
+// preferred registry, then the request's zone, before falling back by
registry weight. Use it
+// for multi-region services that should keep traffic local while retaining
fallback.
func WithClusterZoneAware() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyZoneAware
}
}
+// WithClusterAdaptiveService tells consumers to route using
remaining-capacity metrics. It
+// requires P2C load balancing and providers with adaptive-service metrics
enabled. Use it when
+// this service's instance capacity varies significantly at runtime.
func WithClusterAdaptiveService() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = constant.ClusterKeyAdaptiveService
}
}
+// WithCluster advertises a registered cluster extension as the consumer
fault-handling policy
+// for this service. Use it for a domain-specific failure policy; it overrides
the server default.
func WithCluster(cluster string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Cluster = cluster
}
}
+// WithGroup publishes this service in the supplied group, allowing multiple
implementations
+// of one interface to coexist. Use groups for environments, tenants, or
alternate implementations;
+// consumers requesting another group cannot discover it.
func WithGroup(group string) ServiceOption {
return func(cfg *ServiceOptions) {
cfg.Service.Group = group
}
}
+// WithVersion publishes this service under the supplied version. Consumers
requesting another
+// version cannot discover it even when the interface and group match. Use it
during incompatible
+// API migrations so old and new providers can run concurrently.
func WithVersion(version string) ServiceOption {
return func(cfg *ServiceOptions) {
cfg.Service.Version = version
}
}
+// WithJSON encodes this service's request and response payloads with JSON.
Consumers and the
+// selected protocol must support JSON or requests cannot be decoded. Use it
for interoperability
+// when readable payloads matter more than compact binary encoding.
func WithJSON() ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Serialization = constant.JSONSerialization
}
}
-// WithToken should be used with WithFilter("token")
+// WithToken requires consumers to present the same service token when the
token provider filter
+// is active. Use it for simple shared-secret protection and pair it with
WithFilter("token") or
+// a chain containing that filter.
func WithToken(token string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Token = token
}
}
+// WithNotRegister keeps this service out of all registries while still
exporting it on its
+// protocol endpoint. Use it for tests, internal health services, or fixed
private endpoints;
+// consumers must use a direct URL to reach it.
func WithNotRegister() ServiceOption {
return func(cfg *ServiceOptions) {
cfg.Service.NotRegister = true
}
}
+// WithWarmup gradually increases this provider's effective load-balancing
weight over the
+// supplied duration. Use it for cold-start protection while caches or pools
initialize. It
+// preserves values such as "500ms" in the provider URL.
func WithWarmup(warmupDuration time.Duration) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Warmup = warmupDuration.String()
}
}
+// WithRetries advertises how many additional attempts retry-capable consumers
may make after
+// the initial call. Zero means one total attempt. Use retries only for
idempotent service methods.
func WithRetries(retries int) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Retries = strconv.Itoa(retries)
}
}
+// WithSerialization selects this service's wire serialization by extension
name. Consumers
+// and the selected protocol must support the same serialization. Use it when
both sides install
+// the same non-default serialization extension.
func WithSerialization(ser string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Serialization = ser
}
}
+// WithAccesslog enables access logging for this service. A file path writes
records there;
+// "true" or "default" sends them to the application logger. Logging is
asynchronous and
+// records may be dropped if its channel is full. Use it for auditing or
troubleshooting while
+// accounting for payload visibility and storage cost.
func WithAccesslog(accesslog string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.AccessLog = accesslog
}
}
+// WithTpsLimiter enables the named requests-per-second limiter for this
service. An empty name
+// disables TPS limiting; an unregistered name causes service validation to
panic. Use it to
+// protect this provider from request bursts, together with rate and rejection
settings. For
+// example, use WithTpsLimiter("default") and WithTpsLimitRate(100) to allow
100 requests per
+// configured limiter interval before invoking the default rejection handler.
func WithTpsLimiter(limiter string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.TpsLimiter = limiter
}
}
+// WithTpsLimitRate sets the maximum request rate enforced by this service's
selected TPS
+// limiter. Set it to the service's sustainable throughput; it has no effect
until WithTpsLimiter
+// selects a limiter.
func WithTpsLimitRate(rate int) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.TpsLimitRate = strconv.Itoa(rate)
}
}
+// WithTpsLimitStrategy selects the registered rate-limiting strategy used for
this service.
+// Use it to choose how bursts are measured, such as a fixed or sliding
window. An unregistered
+// name causes service validation to panic.
func WithTpsLimitStrategy(strategy string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.TpsLimitStrategy = strategy
}
}
+// WithTpsLimitRejectedHandler selects the handler invoked when this service
exceeds its TPS
+// limit. Use a custom handler to return a domain-specific overload error or
fallback result;
+// an unregistered name causes service validation to panic.
func WithTpsLimitRejectedHandler(rejHandler string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.TpsLimitRejectedHandler = rejHandler
}
}
+// WithExecuteLimit caps concurrent in-flight invocations of this service. The
value must be an
+// integer string; a negative value disables the cap, while an invalid value
returns an empty
+// result without invoking the service. Use it when concurrency is bounded by
resources such as
+// database connections. For example, WithExecuteLimit("32") allows at most 32
simultaneous
+// invocations; method-level execution limits can override it.
func WithExecuteLimit(exeLimit string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.ExecuteLimit = exeLimit
}
}
+// WithExecuteLimitRejectedHandler selects the registered handler for calls
rejected after this
+// service's in-flight limit is reached. Use it to return a specific overload
response. If lookup
+// fails, the call proceeds after a warning.
func WithExecuteLimitRejectedHandler(exeRejHandler string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.ExecuteLimitRejectedHandler = exeRejHandler
}
}
+// WithAuth enables AK/SK request-signature verification when set to "true"
and the provider
+// filter chain contains "auth". Use it when this service must authenticate
calling applications;
+// missing or invalid signatures are rejected before execution. Enable both
parts with
+// WithFilter("auth") and WithAuth("true"), then configure compatible
access-key storage and
+// consumer signing.
func WithAuth(auth string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Auth = auth
}
}
+// WithParamSign includes request parameters in AK/SK signature verification
when set to
+// "true". Use it when the signature must also detect parameter tampering. It
only has an effect
+// when WithAuth and the "auth" provider filter are enabled on both sides.
func WithParamSign(paramSign string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.ParamSign = paramSign
}
}
+// WithTag publishes this service instance with the supplied routing tag,
allowing tagged
+// consumers to select it. Use tags for canary, tenant, or hardware-specific
pools without
+// changing the interface, group, or version.
func WithTag(tag string) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service.Tag = tag
}
}
+// WithProtocol configures a protocol endpoint available to this service. Give
each endpoint a
+// distinct protocol.WithID and use WithProtocolIDs when the service should
use only a subset.
+// Use it for a listener needed only by this service; shared listeners belong
on NewServer.
func WithProtocol(opts ...protocol.ServerOption) ServiceOption {
proOpts := protocol.NewServerOptions(opts...)
@@ -869,6 +1145,9 @@ func WithProtocol(opts ...protocol.ServerOption)
ServiceOption {
}
}
+// WithRegistry makes a registry available for publishing this service. Give
each registry a
+// distinct registry.WithID and use WithRegistryIDs to publish only to a
subset. Use it for a
+// service-specific registry; shared registries are normally configured on
NewServer.
func WithRegistry(opts ...registry.Option) ServiceOption {
regOpts := registry.NewOptions(opts...)
@@ -880,6 +1159,9 @@ func WithRegistry(opts ...registry.Option) ServiceOption {
}
}
+// WithMethod adds method-specific behavior such as timeout, retries, or
execution limits.
+// Method settings take precedence over the corresponding service defaults.
Use it when one
+// method is slower, non-idempotent, or has a different capacity limit from
the rest.
func WithMethod(method *global.MethodConfig) ServiceOption {
return func(opts *ServiceOptions) {
if method == nil {
@@ -892,6 +1174,8 @@ func WithMethod(method *global.MethodConfig) ServiceOption
{
}
}
+// WithParam publishes one custom service URL parameter for filters, routers,
protocols, or
+// extensions. A later call with the same key replaces the earlier value.
func WithParam(k, v string) ServiceOption {
return func(opts *ServiceOptions) {
if opts.Service.Params == nil {
@@ -901,12 +1185,17 @@ func WithParam(k, v string) ServiceOption {
}
}
+// WithOpenAPIGroup places this service's generated operations in the supplied
OpenAPI group,
+// allowing related services to be presented together in generated API
documentation. Use the
+// same group for APIs that should appear as one logical section to
documentation consumers.
func WithOpenAPIGroup(group string) ServiceOption {
return func(opts *ServiceOptions) {
opts.openapiGroup = group
}
}
+// WithIDLMode sets ServiceOptions.IDLMode for legacy services.
+//
// TODO: remove when config package is removed
//
// Deprecated: this option will be removed in the next version. The IDL mode
@@ -920,30 +1209,37 @@ func WithIDLMode(IDLMode string) ServiceOption {
// ----------For framework----------
// These functions should not be invoked by users
+// SetApplication assigns framework-loaded application configuration to
ServiceOptions.Application.
func SetApplication(application *global.ApplicationConfig) ServiceOption {
return func(opts *ServiceOptions) {
opts.Application = application
}
}
+// SetProvider assigns framework-loaded provider configuration to
ServiceOptions.Provider.
func SetProvider(provider *global.ProviderConfig) ServiceOption {
return func(opts *ServiceOptions) {
opts.Provider = provider
}
}
+// SetService assigns framework-loaded service configuration to
ServiceOptions.Service.
func SetService(service *global.ServiceConfig) ServiceOption {
return func(opts *ServiceOptions) {
opts.Service = service
}
}
+// SetRegistries replaces ServiceOptions.Registries with framework-loaded
configuration.
+// User code should prefer WithRegistry and WithRegistryIDs.
func SetRegistries(regs map[string]*global.RegistryConfig) ServiceOption {
return func(opts *ServiceOptions) {
opts.Registries = regs
}
}
+// SetProtocols replaces ServiceOptions.Protocols with framework-loaded
configuration.
+// User code should prefer WithProtocol and WithProtocolIDs.
func SetProtocols(pros map[string]*global.ProtocolConfig) ServiceOption {
return func(opts *ServiceOptions) {
opts.Protocols = pros
