Documentation
¶
Overview ¶
Package client provides the stable service-discovery runtime API consumed by generated SDKs: it resolves a service name (e.g. "edu.course.student-api") to a concrete gRPC/HTTP backend through a registry and selector.
Index ¶
- Constants
- func DefaultRegistry() (string, any)
- func Dial(ctx context.Context, serviceName string, opts ...DialOption) (*grpc.ClientConn, error)
- func RequestHeadersFrom(ctx context.Context) http.Header
- func SetDefaultRegistry(name string, opts any)
- func WithRequestHeaders(ctx context.Context, headers http.Header) context.Context
- type DialOption
- func WithBreaker(window, probeInterval time.Duration) DialOption
- func WithBulkhead(maxConcurrent int) DialOption
- func WithDiscovery(d registry.Discovery) DialOption
- func WithDiscoveryCache(ttl time.Duration, opts ...cache.Option) DialOption
- func WithGrpcDialOptions(opts ...grpc.DialOption) DialOption
- func WithRegistry(name string, opts any) DialOption
- func WithResiliency(p resiliency.Provider) DialOption
- func WithRetry(maxAttempts int, base, max time.Duration) DialOption
- func WithRetryable(f func(error) bool) DialOption
- func WithSelector(strategy string) DialOption
- func WithTLS(t *tls.Config) DialOption
- func WithTimeout(d time.Duration) DialOption
- func WithUnaryInterceptor(i grpc.UnaryClientInterceptor) DialOption
- type HTTPClient
- type HTTPOption
- func WithHTTPBreaker(window, probeInterval time.Duration) HTTPOption
- func WithHTTPBulkhead(maxConcurrent int) HTTPOption
- func WithHTTPClient(c *http.Client) HTTPOption
- func WithHTTPCodec(c codec.Marshaler) HTTPOption
- func WithHTTPDiscovery(d registry.Discovery) HTTPOption
- func WithHTTPDiscoveryCache(ttl time.Duration, opts ...cache.Option) HTTPOption
- func WithHTTPRegistry(name string, opts any) HTTPOption
- func WithHTTPRetry(maxAttempts int, base, max time.Duration) HTTPOption
- func WithHTTPRetryable(f func(error) bool) HTTPOption
- func WithHTTPSelector(s selector.Selector) HTTPOption
- func WithHTTPTimeout(d time.Duration) HTTPOption
Constants ¶
const Scheme = "onexmesh"
Scheme is the gRPC resolver scheme for service discovery targets:
onexmesh:///edu.course.student-api
Variables ¶
This section is empty.
Functions ¶
func DefaultRegistry ¶
DefaultRegistry returns the current process-wide default registry name and its Options value.
func Dial ¶
func Dial(ctx context.Context, serviceName string, opts ...DialOption) (*grpc.ClientConn, error)
Dial resolves serviceName through the configured registry and returns a gRPC ClientConn. Connection is lazy: discovery happens on first RPC via the onexmesh resolver, and load balancing is handled by grpc's balancer.
func RequestHeadersFrom ¶
RequestHeadersFrom returns the outgoing headers carried by ctx, or nil.
The returned header is the one stored, not a copy: a caller that wants to change it should build a new one and call WithRequestHeaders again, which is also what makes the mutation visible to a request already in flight.
func SetDefaultRegistry ¶
SetDefaultRegistry sets the process-wide default registry used by service discovery when a client is constructed without an explicit WithRegistry or WithDiscovery. opts must be the backend's Options **value** (not a pointer), e.g. polaris.Options{Addr: "127.0.0.1:8091"} or etcd.Options{Endpoints: []string{"127.0.0.1:2379"}}.
func WithRequestHeaders ¶
WithRequestHeaders returns a context that carries headers to be set on every mesh request made with it.
Why the context rather than a client option ¶
A client option configures the client; these headers vary per call. The one that matters most is Authorization: a service calling another on the caller's behalf presents the caller's own credential, which is different for every request and must not be shared between them — a client-level header would make two concurrent requests race to send each other's tokens.
What is not forwarded ¶
Only the headers given here are set. An incoming request's headers are not copied, so hop-by-hop and transport headers (Host, Content-Length, Connection, ...) cannot be relayed by accident, and a caller has to name each header it means to pass on. Content-Type is set separately by the codec and overwrites anything given here, because a body encoded by one codec and labelled as another is worse than a missing header.
Types ¶
type DialOption ¶
type DialOption func(*dialOptions)
DialOption configures a Dial call.
func WithBreaker ¶
func WithBreaker(window, probeInterval time.Duration) DialOption
WithBreaker enables a Google SRE sliding-window circuit breaker around calls. window is the sliding window duration; probeInterval is how often a request is force-passed while throttling so the breaker can recover.
func WithBulkhead ¶
func WithBulkhead(maxConcurrent int) DialOption
WithBulkhead isolates the downstream service by bounding the number of concurrent in-flight requests. When the budget is exhausted, calls fail fast with errno.ErrBulkheadFull instead of queueing. A value <= 0 disables the bulkhead.
func WithDiscovery ¶
func WithDiscovery(d registry.Discovery) DialOption
WithDiscovery injects a pre-built registry.Discovery, taking precedence over WithRegistry. It lets callers supply a discovery already constructed from configuration (e.g. options.RegistryOptions.NewDiscovery) without going through the name/opts factory lookup.
func WithDiscoveryCache ¶
func WithDiscoveryCache(ttl time.Duration, opts ...cache.Option) DialOption
WithDiscoveryCache wraps the discovery backend in a read-through cache with the given service TTL. It enables singleflight deduplication, stale-while-error degradation and refresh throttling. When ttl <= 0 the cache is disabled.
func WithGrpcDialOptions ¶
func WithGrpcDialOptions(opts ...grpc.DialOption) DialOption
WithGrpcDialOptions appends raw grpc dial options.
func WithRegistry ¶
func WithRegistry(name string, opts any) DialOption
WithRegistry selects the registry backend (e.g. "polaris", "etcd", "kubernetes") and its backend-specific options.
func WithResiliency ¶
func WithResiliency(p resiliency.Provider) DialOption
WithResiliency enables declarative, configuration-driven resilience (from a resiliency.Provider) in place of the imperative WithRetry/WithBreaker/ WithTimeout options. The provider supplies per-endpoint policies resolved at call time; when no policy matches, the call is passed through unmodified.
func WithRetry ¶
func WithRetry(maxAttempts int, base, max time.Duration) DialOption
WithRetry enables retry with exponential backoff and jitter. base and max are the base and maximum backoff durations.
func WithRetryable ¶
func WithRetryable(f func(error) bool) DialOption
WithRetryable sets the predicate deciding which errors are retried. When nil, a default classification that only retries transient/server-side errors is used.
func WithSelector ¶
func WithSelector(strategy string) DialOption
WithSelector selects the load-balancing strategy used by the gRPC client (e.g. "round_robin", "random", "weighted", "p2c"). Defaults to "round_robin".
func WithTimeout ¶
func WithTimeout(d time.Duration) DialOption
WithTimeout imposes a per-call deadline via the client-side timeout resilience middleware.
func WithUnaryInterceptor ¶
func WithUnaryInterceptor(i grpc.UnaryClientInterceptor) DialOption
WithUnaryInterceptor adds a unary client interceptor.
type HTTPClient ¶
type HTTPClient struct {
// contains filtered or unexported fields
}
HTTPClient performs HTTP calls against a service resolved via the registry. It maintains a local cache of discovered nodes, refreshed by a background watch, so per-request calls do not hit the registry directly.
func NewHTTPClient ¶
func NewHTTPClient(serviceName string, opts ...HTTPOption) (*HTTPClient, error)
NewHTTPClient creates an HTTP service-discovery client.
func (*HTTPClient) Close ¶
func (c *HTTPClient) Close()
Close stops the background watch and releases its resources (including the underlying discovery). It is idempotent.
func (*HTTPClient) Do ¶
func (c *HTTPClient) Do(ctx context.Context, method, path string, req, resp interface{}) error
Do resolves a backend from the cached nodes, encodes req with the configured codec, performs the request and decodes the response into resp. When resilience is configured the select+request step is wrapped with retry/breaker/timeout.
type HTTPOption ¶
type HTTPOption func(*httpOptions)
HTTPOption configures an HTTPClient.
func WithHTTPBreaker ¶
func WithHTTPBreaker(window, probeInterval time.Duration) HTTPOption
WithHTTPBreaker enables a Google SRE sliding-window circuit breaker around HTTP calls.
func WithHTTPBulkhead ¶
func WithHTTPBulkhead(maxConcurrent int) HTTPOption
WithHTTPBulkhead isolates the downstream service by bounding the number of concurrent in-flight HTTP requests, mirroring WithBulkhead for the gRPC client. A value <= 0 disables the bulkhead.
func WithHTTPClient ¶
func WithHTTPClient(c *http.Client) HTTPOption
WithHTTPClient injects a pre-configured *http.Client.
func WithHTTPCodec ¶
func WithHTTPCodec(c codec.Marshaler) HTTPOption
WithHTTPCodec sets the request/response body codec, defaulting to JSON.
func WithHTTPDiscovery ¶
func WithHTTPDiscovery(d registry.Discovery) HTTPOption
WithHTTPDiscovery injects a pre-built registry.Discovery, taking precedence over WithHTTPRegistry, mirroring WithDiscovery for the gRPC client.
func WithHTTPDiscoveryCache ¶
func WithHTTPDiscoveryCache(ttl time.Duration, opts ...cache.Option) HTTPOption
WithHTTPDiscoveryCache wraps the discovery backend in a read-through cache with the given service TTL, mirroring WithDiscoveryCache for the gRPC client. It enables singleflight deduplication and stale-while-error degradation. When ttl <= 0 the cache is disabled.
func WithHTTPRegistry ¶
func WithHTTPRegistry(name string, opts any) HTTPOption
WithHTTPRegistry selects the registry backend and its options.
func WithHTTPRetry ¶
func WithHTTPRetry(maxAttempts int, base, max time.Duration) HTTPOption
WithHTTPRetry enables retry with exponential backoff and jitter.
func WithHTTPRetryable ¶
func WithHTTPRetryable(f func(error) bool) HTTPOption
WithHTTPRetryable sets the predicate deciding which errors are retried.
func WithHTTPSelector ¶
func WithHTTPSelector(s selector.Selector) HTTPOption
WithHTTPSelector overrides the default round-robin selector.
func WithHTTPTimeout ¶
func WithHTTPTimeout(d time.Duration) HTTPOption
WithHTTPTimeout sets the HTTP client timeout.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package balancer adapts onexmesh's selector to a gRPC balancer so the framework's load-balancing strategies (round_robin, weighted, p2c, ...) are used by the gRPC client instead of grpc's built-in balancers.
|
Package balancer adapts onexmesh's selector to a gRPC balancer so the framework's load-balancing strategies (round_robin, weighted, p2c, ...) are used by the gRPC client instead of grpc's built-in balancers. |
|
Package rest provides a mesh-aware transport for client-go's rest.Config.
|
Package rest provides a mesh-aware transport for client-go's rest.Config. |