httpclient

package
v2.75.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 22, 2024 License: Apache-2.0 Imports: 27 Imported by: 22

Documentation

Overview

Package httpclient provides round trippers/transport wrappers for http clients.

Index

Constants

View Source 
const (
	MetricTagServiceName = "service-name"

	MetricTLSHandshakeAttempt = "tls.handshake.attempt"
	MetricTLSHandshakeFailure = "tls.handshake.failure"
	MetricTLSHandshake        = "tls.handshake"
	CipherTagKey              = "cipher"
	NextProtocolTagKey        = "next_protocol"
	TLSVersionTagKey          = "tls_version"

	MetricConnCreate      = "client.connection.create" // monotonic counter of each new request, tagged with reused:true or reused:false
	MetricRequestInFlight = "client.request.in-flight"
)

Variables

View Source 
var (
	MetricTagConnectionNew    = metrics.MustNewTag("reused", "false")
	MetricTagConnectionReused = metrics.MustNewTag("reused", "true")
)

Functions

func ContextWithRPCMethodName 

func ContextWithRPCMethodName(ctx context.Context, name string) context.Context

ContextWithRPCMethodName returns a copy of ctx with the rpcMethodName key set. This enables instrumentation (metrics, tracing, etc) to better identify metrics.

func LocationFromError added in v2.13.0 

func LocationFromError(err error) (location string, ok bool)

LocationFromError wraps the internal LocationFromError func. For behavior details, see its docs.

func NewHTTPClient 

func NewHTTPClient(params ...HTTPClientParam) (*http.Client, error)

NewHTTPClient returns a configured http client ready for use. We apply "sane defaults" before applying the provided params.

func StatusCodeFromError 

func StatusCodeFromError(err error) (statusCode int, ok bool)

StatusCodeFromError wraps the internal StatusCodeFromError func. For behavior details, see its docs.

Types

type BasicAuth added in v2.49.0 

type BasicAuth struct {
	// User is a string representing the user
	User string `json:"user,omitempty" yaml:"user,omitempty"`
	// Password is a string representing the password
	Password string `json:"password,omitempty" yaml:"password,omitempty"`
}

BasicAuth represents the configuration for HTTP Basic Authorization

type BasicAuthProvider added in v2.49.0 

type BasicAuthProvider func(context.Context) (BasicAuth, error)

BasicAuthProvider accepts a context and returns either:

(1) a nonempty BasicAuth and a nil error, or

(2) an empty BasicAuth and a non-nil error.

type Client 

type Client interface {
	// Do executes a full request. Any input or output should be specified via params.
	// By the time it is returned, the response's body will be fully read and closed.
	// Use the WithResponse* params to unmarshal the body before Do() returns.
	//
	// In the case of a response with StatusCode >= 400, Do() will return a nil response and a non-nil error.
	// Use StatusCodeFromError(err) to retrieve the code from the error.
	// Use WithDisableRestErrors() to disable this middleware on your client.
	// Use WithErrorDecoder(errorDecoder) to replace this default behavior with custom error decoding behavior.
	Do(ctx context.Context, params ...RequestParam) (*http.Response, error)

	Get(ctx context.Context, params ...RequestParam) (*http.Response, error)
	Head(ctx context.Context, params ...RequestParam) (*http.Response, error)
	Post(ctx context.Context, params ...RequestParam) (*http.Response, error)
	Put(ctx context.Context, params ...RequestParam) (*http.Response, error)
	Delete(ctx context.Context, params ...RequestParam) (*http.Response, error)
}

A Client executes requests to a configured service.

The Get/Head/Post/Put/Delete methods are for conveniently setting the method type and calling Do()

func NewClient 

func NewClient(params ...ClientParam) (Client, error)

NewClient returns a configured client ready for use. We apply "sane defaults" before applying the provided params.

func NewClientFromRefreshableConfig added in v2.22.0 

func NewClientFromRefreshableConfig(ctx context.Context, config RefreshableClientConfig, params ...ClientParam) (Client, error)

NewClientFromRefreshableConfig returns a configured client ready for use. We apply "sane defaults" before applying the provided params.

type ClientConfig 

type ClientConfig struct {
	ServiceName string `json:"-" yaml:"-"`
	// URIs is a list of fully specified base URIs for the service. These can optionally include a path
	// which will be prepended to the request path specified when invoking the client.
	URIs []string `json:"uris,omitempty" yaml:"uris,omitempty"`
	// APIToken is a string which, if provided, will be used as a Bearer token in the Authorization header.
	// This takes precedence over APITokenFile.
	APIToken *string `json:"api-token,omitempty" yaml:"api-token,omitempty"`
	// APITokenFile is an on-disk location containing a Bearer token. If APITokenFile is provided and APIToken
	// is not, the content of the file will be used as the APIToken.
	APITokenFile *string `json:"api-token-file,omitempty" yaml:"api-token-file,omitempty"`
	// BasicAuth is a user/password combination which, if provided, will be used as the credentials in the
	// Authorization header. APIToken and APITokenFile will take precedent over BasicAuth if specified
	BasicAuth *BasicAuth `json:"basic-auth,omitempty" yaml:"basic-auth,omitempty"`
	// DisableHTTP2, if true, will prevent the client from modifying the *tls.Config object to support H2 connections.
	DisableHTTP2 *bool `json:"disable-http2,omitempty" yaml:"disable-http2,omitempty"`
	// ProxyFromEnvironment enables reading HTTP proxy information from environment variables.
	// See 'http.ProxyFromEnvironment' documentation for specific behavior.
	ProxyFromEnvironment *bool `json:"proxy-from-environment,omitempty" yaml:"proxy-from-environment,omitempty"`
	// ProxyURL uses the provided URL for proxying the request. Schemes http, https, and socks5 are supported.
	ProxyURL *string `json:"proxy-url,omitempty" yaml:"proxy-url,omitempty"`

	// MaxNumRetries controls the number of times the client will retry retryable failures.
	// If unset, this defaults to twice the number of URIs provided.
	MaxNumRetries *int `json:"max-num-retries,omitempty" yaml:"max-num-retries,omitempty"`
	// InitialBackoff controls the duration of the first backoff interval. This delay will double for each subsequent backoff, capped at the MaxBackoff value.
	InitialBackoff *time.Duration `json:"initial-backoff,omitempty" yaml:"initial-backoff,omitempty"`
	// MaxBackoff controls the maximum duration the client will sleep before retrying a request.
	MaxBackoff *time.Duration `json:"max-backoff,omitempty" yaml:"max-backoff,omitempty"`

	// ConnectTimeout is the maximum time for the net.Dialer to connect to the remote host.
	ConnectTimeout *time.Duration `json:"connect-timeout,omitempty" yaml:"connect-timeout,omitempty"`
	// ReadTimeout is the maximum timeout for non-mutating requests.
	// NOTE: The current implementation uses the max(ReadTimeout, WriteTimeout) to set the http.Client timeout value.
	ReadTimeout *time.Duration `json:"read-timeout,omitempty" yaml:"read-timeout,omitempty"`
	// WriteTimeout is the maximum timeout for mutating requests.
	// NOTE: The current implementation uses the max(ReadTimeout, WriteTimeout) to set the http.Client timeout value.
	WriteTimeout *time.Duration `json:"write-timeout,omitempty" yaml:"write-timeout,omitempty"`
	// IdleConnTimeout sets the timeout for idle connections.
	IdleConnTimeout *time.Duration `json:"idle-conn-timeout,omitempty" yaml:"idle-conn-timeout,omitempty"`
	// TLSHandshakeTimeout sets the timeout for TLS handshakes
	TLSHandshakeTimeout *time.Duration `json:"tls-handshake-timeout,omitempty" yaml:"tls-handshake-timeout,omitempty"`
	// IdleConnTimeout sets the timeout to receive the server's first response headers after
	// fully writing the request headers if the request has an "Expect: 100-continue" header.
	ExpectContinueTimeout *time.Duration `json:"expect-continue-timeout,omitempty" yaml:"expect-continue-timeout,omitempty"`

	// HTTP2ReadIdleTimeout sets the maximum time to wait before sending periodic health checks (pings) for an HTTP/2 connection.
	// If unset, the client defaults to 30s for HTTP/2 clients.
	HTTP2ReadIdleTimeout *time.Duration `json:"http2-read-idle-timeout,omitempty" yaml:"http2-read-idle-timeout,omitempty"`
	// HTTP2PingTimeout is the maximum time to wait for a ping response in an HTTP/2 connection,
	// when health checking is enabled which is done by setting the HTTP2ReadIdleTimeout > 0.
	// If unset, the client defaults to 15s if the HTTP2ReadIdleTimeout is > 0.
	HTTP2PingTimeout *time.Duration `json:"http2-ping-timeout,omitempty" yaml:"http2-ping-timeout,omitempty"`

	// MaxIdleConns sets the number of reusable TCP connections the client will maintain.
	// If unset, the client defaults to 200.
	MaxIdleConns *int `json:"max-idle-conns,omitempty" yaml:"max-idle-conns,omitempty"`
	// MaxIdleConnsPerHost sets the number of reusable TCP connections the client will maintain per destination.
	// If unset, the client defaults to 100.
	MaxIdleConnsPerHost *int `json:"max-idle-conns-per-host,omitempty" yaml:"max-idle-conns-per-host,omitempty"`

	// Metrics allows disabling metric emission or adding additional static tags to the client metrics.
	Metrics MetricsConfig `json:"metrics,omitempty" yaml:"metrics,omitempty"`
	// Security configures the TLS configuration for the client. It accepts file paths which should be
	// absolute paths or relative to the process's current working directory.
	Security SecurityConfig `json:"security,omitempty" yaml:"security,omitempty"`
}

ClientConfig represents the configuration for a single REST client.

func MergeClientConfig added in v2.19.0 

func MergeClientConfig(conf, defaults ClientConfig) ClientConfig

MergeClientConfig merges two instances of ClientConfig, preferring values from conf over defaults. The ServiceName field is not affected, and is expected to be set in the config before building a Client.

type ClientOrHTTPClientParam 

type ClientOrHTTPClientParam interface {
	ClientParam
	HTTPClientParam
}

ClientOrHTTPClientParam is a param that can be used to build a Client or an http.Client

func WithAddHeader 

func WithAddHeader(key, value string) ClientOrHTTPClientParam

func WithAuthToken 

func WithAuthToken(bearerToken string) ClientOrHTTPClientParam

WithAuthToken sets the Authorization header to a static bearerToken.

func WithAuthTokenProvider 

func WithAuthTokenProvider(provideToken TokenProvider) ClientOrHTTPClientParam

WithAuthTokenProvider calls provideToken() and sets the Authorization header.

func WithBasicAuth 

func WithBasicAuth(user, password string) ClientOrHTTPClientParam

WithBasicAuth sets the request's Authorization header to use HTTP Basic Authentication with the provided username and password.

func WithBasicAuthProvider added in v2.71.0 

func WithBasicAuthProvider(provider BasicAuthProvider) ClientOrHTTPClientParam

func WithDialTimeout 

func WithDialTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithDialTimeout sets the timeout on the Dialer. If unset, the client defaults to 90 seconds.

func WithDisableHTTP2 

func WithDisableHTTP2() ClientOrHTTPClientParam

WithDisableHTTP2 skips the default behavior of configuring the transport with http2.ConfigureTransport.

func WithDisableKeepAlives added in v2.2.0 

func WithDisableKeepAlives() ClientOrHTTPClientParam

WithDisableKeepAlives disables keep alives on the http transport

func WithDisablePanicRecovery 

func WithDisablePanicRecovery() ClientOrHTTPClientParam

WithDisablePanicRecovery disables the enabled-by-default panic recovery middleware. If the request was otherwise succeeding (err == nil), we return a new werror with the recovered object as an unsafe param. If there's an error, we werror.Wrap it. If errMiddleware is not nil, it is invoked on the recovered object.

func WithDisableTraceHeaderPropagation 

func WithDisableTraceHeaderPropagation() ClientOrHTTPClientParam

WithDisableTraceHeaderPropagation disables the enabled-by-default traceId header propagation By default, if witchcraft-logging has attached a traceId to the context of the request (for service and request logging), then the client will attach this traceId as a header for future services to do the same if desired

func WithDisableTracing 

func WithDisableTracing() ClientOrHTTPClientParam

WithDisableTracing disables the enabled-by-default tracing middleware which instructs the client to propagate trace information using the go-zipkin libraries method of attaching traces to requests. The server at the other end of such a request should be instrumented to read zipkin-style headers

If a trace is already attached to a request context, then the trace is continued. Otherwise, no trace information is propagate. This will not create a span if one does not exist.

func WithExpectContinueTimeout 

func WithExpectContinueTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithExpectContinueTimeout sets the timeout to receive the server's first response headers after fully writing the request headers if the request has an "Expect: 100-continue" header. If unset, the client defaults to 1 second.

func WithHTTP2PingTimeout added in v2.15.0 

func WithHTTP2PingTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithHTTP2PingTimeout configures the amount of time to wait for a ping response before closing an HTTP/2 connection. The PingTimeout is only valid when the ReadIdleTimeout is > 0 otherwise pings (health checks) are not enabled. If unset, the client defaults to 15 seconds, if HTTP/2 is enabled and the ReadIdleTimeout is > 0.

func WithHTTP2ReadIdleTimeout added in v2.15.0 

func WithHTTP2ReadIdleTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithHTTP2ReadIdleTimeout configures the HTTP/2 ReadIdleTimeout. A ReadIdleTimeout > 0 will enable health checks and allows broken/idle connections to be pruned more quickly, preventing the client from attempting to re-use connections that will no longer work. If the HTTP/2 connection has not received any frames after the ReadIdleTimeout period, then periodic pings (health checks) will be sent to the server before attempting to close the connection. The amount of time to wait for the ping response can be configured by the WithHTTP2PingTimeout param. If unset, the client defaults to 30 seconds, if HTTP2 is enabled.

func WithHTTPTimeout 

func WithHTTPTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithHTTPTimeout sets the timeout on the http client. If unset, the client defaults to 1 minute.

func WithIdleConnTimeout 

func WithIdleConnTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithIdleConnTimeout sets the timeout for idle connections. If unset, the client defaults to 90 seconds.

func WithKeepAlive 

func WithKeepAlive(keepAlive time.Duration) ClientOrHTTPClientParam

WithKeepAlive sets the keep alive frequency on the Dialer. If unset, the client defaults to 30 seconds.

func WithMaxIdleConns 

func WithMaxIdleConns(conns int) ClientOrHTTPClientParam

WithMaxIdleConns sets the number of reusable TCP connections the client will maintain. If unset, the client defaults to 200.

func WithMaxIdleConnsPerHost 

func WithMaxIdleConnsPerHost(conns int) ClientOrHTTPClientParam

WithMaxIdleConnsPerHost sets the number of reusable TCP connections the client will maintain per destination. If unset, the client defaults to 100.

func WithMetrics 

func WithMetrics(tagProviders ...TagsProvider) ClientOrHTTPClientParam

WithMetrics enables the "client.response" metric. See MetricsMiddleware for details. The serviceName will appear as the "service-name" tag.

func WithMiddleware 

func WithMiddleware(h Middleware) ClientOrHTTPClientParam

WithMiddleware will be invoked for custom HTTP behavior after the underlying transport is initialized. Each handler added "wraps" the previous round trip, so it will see the request first and the response last.

func WithNoProxy 

func WithNoProxy() ClientOrHTTPClientParam

WithNoProxy nils out the Proxy field of the http.Transport, ignoring any proxy set in the process's environment. If unset, the default is http.ProxyFromEnvironment.

func WithOverrideRequestHost added in v2.58.0 

func WithOverrideRequestHost(host string) ClientOrHTTPClientParam

WithOverrideRequestHost overrides the request Host from the default URL.Host

func WithProxyFromEnvironment 

func WithProxyFromEnvironment() ClientOrHTTPClientParam

WithProxyFromEnvironment can be used to set the HTTP(s) proxy to use the Go standard library's http.ProxyFromEnvironment.

func WithProxyURL 

func WithProxyURL(proxyURLString string) ClientOrHTTPClientParam

WithProxyURL can be used to set a socks5 or HTTP(s) proxy.

func WithResponseHeaderTimeout 

func WithResponseHeaderTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithResponseHeaderTimeout specifies the amount of time to wait for a server's response headers after fully writing the request (including its body, if any). This time does not include the time to read the response body. If unset, the client defaults to having no response header timeout.

func WithServiceName 

func WithServiceName(serviceName string) ClientOrHTTPClientParam

func WithSetHeader 

func WithSetHeader(key, value string) ClientOrHTTPClientParam

func WithTLSConfig 

func WithTLSConfig(conf *tls.Config) ClientOrHTTPClientParam

WithTLSConfig sets the SSL/TLS configuration for the HTTP client's Transport using a copy of the provided config. The palantir/pkg/tlsconfig package is recommended to build a tls.Config from sane defaults.

func WithTLSHandshakeTimeout 

func WithTLSHandshakeTimeout(timeout time.Duration) ClientOrHTTPClientParam

WithTLSHandshakeTimeout sets the timeout for TLS handshakes. If unset, the client defaults to 10 seconds.

func WithTLSInsecureSkipVerify added in v2.10.0 

func WithTLSInsecureSkipVerify() ClientOrHTTPClientParam

WithTLSInsecureSkipVerify sets the InsecureSkipVerify field for the HTTP client's tls config. This option should only be used in clients that have way to establish trust with servers.

func WithUserAgent 

func WithUserAgent(userAgent string) ClientOrHTTPClientParam

WithUserAgent sets the User-Agent header.

type ClientParam 

type ClientParam interface {
	// contains filtered or unexported methods
}

ClientParam is a param that can be used to build

func WithBalancedURIScoring added in v2.19.0 

func WithBalancedURIScoring() ClientParam

WithBalancedURIScoring adds middleware that prioritizes sending requests to URIs with the fewest in-flight requests and least recent errors. Deprecated: This param is a no-op as balanced URI scoring is the default behavior.

func WithBaseURLs 

func WithBaseURLs(urls []string) ClientParam

WithBaseURLs sets the base URLs for every request. This is meant to be used in conjunction with WithPath.

func WithBytesBufferPool 

func WithBytesBufferPool(pool bytesbuffers.Pool) ClientParam

WithBytesBufferPool stores a bytes buffer pool on the client for use in encoding request bodies. This prevents allocating a new byte buffer for every request.

func WithConfig 

func WithConfig(c ClientConfig) ClientParam

func WithDisableRestErrors 

func WithDisableRestErrors() ClientParam

WithDisableRestErrors disables the middleware which sets Do()'s returned error to a non-nil value in the case of >= 400 HTTP response.

func WithErrorDecoder 

func WithErrorDecoder(errorDecoder ErrorDecoder) ClientParam

func WithInitialBackoff 

func WithInitialBackoff(initialBackoff time.Duration) ClientParam

WithInitialBackoff sets the initial backoff between retried calls to the same URI. Defaults to 250ms.

func WithMaxBackoff 

func WithMaxBackoff(maxBackoff time.Duration) ClientParam

WithMaxBackoff sets the maximum backoff between retried calls to the same URI. Defaults to 2 seconds. <= 0 indicates no limit.

func WithMaxRetries 

func WithMaxRetries(maxTransportRetries int) ClientParam

WithMaxRetries sets the maximum number of retries on transport errors for every request. Backoffs are also capped at this. If unset, the client defaults to 2 * size of URIs TODO (#151): Rename to WithMaxAttempts and set maxAttempts directly using the argument provided to the function.

func WithRandomURIScoring added in v2.39.0 

func WithRandomURIScoring() ClientParam

WithRandomURIScoring adds middleware that randomizes the order URIs are prioritized in for each request.

func WithRefreshableBaseURLs added in v2.64.0 

func WithRefreshableBaseURLs(urls refreshable.StringSlice) ClientParam

WithRefreshableBaseURLs sets the base URLs for every request. This is meant to be used in conjunction with WithPath.

func WithUnlimitedRetries added in v2.9.0 

func WithUnlimitedRetries() ClientParam

WithUnlimitedRetries sets an unlimited number of retries on transport errors for every request. If set, this supersedes any retry limits set with WithMaxRetries.

type ErrorDecoder 

type ErrorDecoder interface {
	// Handles returns whether or not the decoder considers the response an error.
	Handles(resp *http.Response) bool
	// DecodeError returns a decoded error, or an error encountered while trying to decode.
	// DecodeError should never return nil.
	DecodeError(resp *http.Response) error
}

ErrorDecoder implementations declare whether or not they should be used to handle certain http responses, and return decoded errors when invoked. Custom implementations can be used when consumers expect structured errors in response bodies.

type HTTPClientParam 

type HTTPClientParam interface {
	// contains filtered or unexported methods
}

func WithConfigForHTTPClient 

func WithConfigForHTTPClient(c ClientConfig) HTTPClientParam

type MetricsConfig 

type MetricsConfig struct {
	// Enabled can be used to disable metrics with an explicit 'false'. Metrics are enabled if this is unset.
	Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	// Tags allows setting arbitrary additional tags on the metrics emitted by the client.
	Tags map[string]string `json:"tags,omitempty" yaml:"tags,omitempty"`
}

type Middleware 

type Middleware interface {
	// RoundTrip mimics the API of http.RoundTripper, but adds a 'next' argument.
	// RoundTrip is responsible for invoking next.RoundTrip(req) and returning the response.
	RoundTrip(req *http.Request, next http.RoundTripper) (*http.Response, error)
}

A Middleware wraps an http client's request and is able to read or modify the request and response.

func MetricsMiddleware 

func MetricsMiddleware(serviceName string, tagProviders ...TagsProvider) (Middleware, error)

MetricsMiddleware updates the "client.response" timer metric on every request. By default, metrics are tagged with 'service-name', 'method', and 'family' (of the status code). This metric name and tag set matches http-remoting's DefaultHostMetrics: https://github.com/palantir/http-remoting/blob/develop/okhttp-clients/src/main/java/com/palantir/remoting3/okhttp/DefaultHostMetrics.java

type MiddlewareFunc 

type MiddlewareFunc func(req *http.Request, next http.RoundTripper) (*http.Response, error)

MiddlewareFunc is a convenience type alias that implements Middleware.

func (MiddlewareFunc) RoundTrip 

func (f MiddlewareFunc) RoundTrip(req *http.Request, next http.RoundTripper) (*http.Response, error)

type RefreshableBasicAuth added in v2.49.0 

type RefreshableBasicAuth interface {
	refreshable.Refreshable
	CurrentBasicAuth() BasicAuth
	MapBasicAuth(func(BasicAuth) interface{}) refreshable.Refreshable
	SubscribeToBasicAuth(func(BasicAuth)) (unsubscribe func())

	User() refreshable.String
	Password() refreshable.String
}

type RefreshableBasicAuthPtr added in v2.49.0 

type RefreshableBasicAuthPtr interface {
	refreshable.Refreshable
	CurrentBasicAuthPtr() *BasicAuth
	MapBasicAuthPtr(func(*BasicAuth) interface{}) refreshable.Refreshable
	SubscribeToBasicAuthPtr(func(*BasicAuth)) (unsubscribe func())

	User() refreshable.String
	Password() refreshable.String
}

type RefreshableClientConfig added in v2.22.0 

type RefreshableClientConfig interface {
	refreshable.Refreshable
	CurrentClientConfig() ClientConfig
	MapClientConfig(func(ClientConfig) interface{}) refreshable.Refreshable
	SubscribeToClientConfig(func(ClientConfig)) (unsubscribe func())

	ServiceName() refreshable.String
	URIs() refreshable.StringSlice
	APIToken() refreshable.StringPtr
	APITokenFile() refreshable.StringPtr
	BasicAuth() RefreshableBasicAuthPtr
	DisableHTTP2() refreshable.BoolPtr
	ProxyFromEnvironment() refreshable.BoolPtr
	ProxyURL() refreshable.StringPtr
	MaxNumRetries() refreshable.IntPtr
	InitialBackoff() refreshable.DurationPtr
	MaxBackoff() refreshable.DurationPtr
	ConnectTimeout() refreshable.DurationPtr
	ReadTimeout() refreshable.DurationPtr
	WriteTimeout() refreshable.DurationPtr
	IdleConnTimeout() refreshable.DurationPtr
	TLSHandshakeTimeout() refreshable.DurationPtr
	ExpectContinueTimeout() refreshable.DurationPtr
	HTTP2ReadIdleTimeout() refreshable.DurationPtr
	HTTP2PingTimeout() refreshable.DurationPtr
	MaxIdleConns() refreshable.IntPtr
	MaxIdleConnsPerHost() refreshable.IntPtr
	Metrics() RefreshableMetricsConfig
	Security() RefreshableSecurityConfig
}

func RefreshableClientConfigFromServiceConfig added in v2.22.0 

func RefreshableClientConfigFromServiceConfig(servicesConfig RefreshableServicesConfig, serviceName string) RefreshableClientConfig

type RefreshableHTTPClient added in v2.22.0 

type RefreshableHTTPClient = refreshingclient.RefreshableHTTPClient

RefreshableHTTPClient exposes the internal interface

func NewHTTPClientFromRefreshableConfig added in v2.22.0 

func NewHTTPClientFromRefreshableConfig(ctx context.Context, config RefreshableClientConfig, params ...HTTPClientParam) (RefreshableHTTPClient, error)

NewHTTPClientFromRefreshableConfig returns a configured http client ready for use. We apply "sane defaults" before applying the provided params.

type RefreshableMetricsConfig added in v2.22.0 

type RefreshableMetricsConfig interface {
	refreshable.Refreshable
	CurrentMetricsConfig() MetricsConfig
	MapMetricsConfig(func(MetricsConfig) interface{}) refreshable.Refreshable
	SubscribeToMetricsConfig(func(MetricsConfig)) (unsubscribe func())

	Enabled() refreshable.BoolPtr
	Tags() RefreshableStringToString
}

type RefreshableSecurityConfig added in v2.22.0 

type RefreshableSecurityConfig interface {
	refreshable.Refreshable
	CurrentSecurityConfig() SecurityConfig
	MapSecurityConfig(func(SecurityConfig) interface{}) refreshable.Refreshable
	SubscribeToSecurityConfig(func(SecurityConfig)) (unsubscribe func())

	CAFiles() refreshable.StringSlice
	CertFile() refreshable.String
	KeyFile() refreshable.String
}

type RefreshableServicesConfig added in v2.22.0 

type RefreshableServicesConfig interface {
	refreshable.Refreshable
	CurrentServicesConfig() ServicesConfig
	MapServicesConfig(func(ServicesConfig) interface{}) refreshable.Refreshable
	SubscribeToServicesConfig(func(ServicesConfig)) (unsubscribe func())

	Default() RefreshableClientConfig
	Services() RefreshableStringToClientConfig
}

type RefreshableStringToClientConfig added in v2.22.0 

type RefreshableStringToClientConfig interface {
	refreshable.Refreshable
	CurrentStringToClientConfig() map[string]ClientConfig
	MapStringToClientConfig(func(map[string]ClientConfig) interface{}) refreshable.Refreshable
	SubscribeToStringToClientConfig(func(map[string]ClientConfig)) (unsubscribe func())
}

type RefreshableStringToString added in v2.22.0 

type RefreshableStringToString interface {
	refreshable.Refreshable
	CurrentStringToString() map[string]string
	MapStringToString(func(map[string]string) interface{}) refreshable.Refreshable
	SubscribeToStringToString(func(map[string]string)) (unsubscribe func())
}

type RefreshingBasicAuth added in v2.49.0 

type RefreshingBasicAuth struct {
	refreshable.Refreshable
}

func NewRefreshingBasicAuth added in v2.49.0 

func NewRefreshingBasicAuth(in refreshable.Refreshable) RefreshingBasicAuth

func (RefreshingBasicAuth) CurrentBasicAuth added in v2.49.0 

func (r RefreshingBasicAuth) CurrentBasicAuth() BasicAuth

func (RefreshingBasicAuth) MapBasicAuth added in v2.49.0 

func (r RefreshingBasicAuth) MapBasicAuth(mapFn func(BasicAuth) interface{}) refreshable.Refreshable

func (RefreshingBasicAuth) Password added in v2.49.0 

func (r RefreshingBasicAuth) Password() refreshable.String

func (RefreshingBasicAuth) SubscribeToBasicAuth added in v2.49.0 

func (r RefreshingBasicAuth) SubscribeToBasicAuth(consumer func(BasicAuth)) (unsubscribe func())

func (RefreshingBasicAuth) User added in v2.49.0 

func (r RefreshingBasicAuth) User() refreshable.String

type RefreshingBasicAuthPtr added in v2.49.0 

type RefreshingBasicAuthPtr struct {
	refreshable.Refreshable
}

func NewRefreshingBasicAuthPtr added in v2.49.0 

func NewRefreshingBasicAuthPtr(in refreshable.Refreshable) RefreshingBasicAuthPtr

func (RefreshingBasicAuthPtr) CurrentBasicAuthPtr added in v2.49.0 

func (r RefreshingBasicAuthPtr) CurrentBasicAuthPtr() *BasicAuth

func (RefreshingBasicAuthPtr) MapBasicAuthPtr added in v2.49.0 

func (r RefreshingBasicAuthPtr) MapBasicAuthPtr(mapFn func(*BasicAuth) interface{}) refreshable.Refreshable

func (RefreshingBasicAuthPtr) Password added in v2.49.0 

func (r RefreshingBasicAuthPtr) Password() refreshable.String

func (RefreshingBasicAuthPtr) SubscribeToBasicAuthPtr added in v2.49.0 

func (r RefreshingBasicAuthPtr) SubscribeToBasicAuthPtr(consumer func(*BasicAuth)) (unsubscribe func())

func (RefreshingBasicAuthPtr) User added in v2.49.0 

func (r RefreshingBasicAuthPtr) User() refreshable.String

type RefreshingClientConfig added in v2.22.0 

type RefreshingClientConfig struct {
	refreshable.Refreshable
}

func NewRefreshingClientConfig added in v2.22.0 

func NewRefreshingClientConfig(in refreshable.Refreshable) RefreshingClientConfig

func (RefreshingClientConfig) APIToken added in v2.22.0 

func (r RefreshingClientConfig) APIToken() refreshable.StringPtr

func (RefreshingClientConfig) APITokenFile added in v2.22.0 

func (r RefreshingClientConfig) APITokenFile() refreshable.StringPtr

func (RefreshingClientConfig) BasicAuth added in v2.49.0 

func (r RefreshingClientConfig) BasicAuth() RefreshableBasicAuthPtr

func (RefreshingClientConfig) ConnectTimeout added in v2.22.0 

func (r RefreshingClientConfig) ConnectTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) CurrentClientConfig added in v2.22.0 

func (r RefreshingClientConfig) CurrentClientConfig() ClientConfig

func (RefreshingClientConfig) DisableHTTP2 added in v2.22.0 

func (r RefreshingClientConfig) DisableHTTP2() refreshable.BoolPtr

func (RefreshingClientConfig) ExpectContinueTimeout added in v2.22.0 

func (r RefreshingClientConfig) ExpectContinueTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) HTTP2PingTimeout added in v2.22.0 

func (r RefreshingClientConfig) HTTP2PingTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) HTTP2ReadIdleTimeout added in v2.22.0 

func (r RefreshingClientConfig) HTTP2ReadIdleTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) IdleConnTimeout added in v2.22.0 

func (r RefreshingClientConfig) IdleConnTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) InitialBackoff added in v2.22.0 

func (r RefreshingClientConfig) InitialBackoff() refreshable.DurationPtr

func (RefreshingClientConfig) MapClientConfig added in v2.22.0 

func (r RefreshingClientConfig) MapClientConfig(mapFn func(ClientConfig) interface{}) refreshable.Refreshable

func (RefreshingClientConfig) MaxBackoff added in v2.22.0 

func (r RefreshingClientConfig) MaxBackoff() refreshable.DurationPtr

func (RefreshingClientConfig) MaxIdleConns added in v2.22.0 

func (r RefreshingClientConfig) MaxIdleConns() refreshable.IntPtr

func (RefreshingClientConfig) MaxIdleConnsPerHost added in v2.22.0 

func (r RefreshingClientConfig) MaxIdleConnsPerHost() refreshable.IntPtr

func (RefreshingClientConfig) MaxNumRetries added in v2.22.0 

func (r RefreshingClientConfig) MaxNumRetries() refreshable.IntPtr

func (RefreshingClientConfig) Metrics added in v2.22.0 

func (r RefreshingClientConfig) Metrics() RefreshableMetricsConfig

func (RefreshingClientConfig) ProxyFromEnvironment added in v2.22.0 

func (r RefreshingClientConfig) ProxyFromEnvironment() refreshable.BoolPtr

func (RefreshingClientConfig) ProxyURL added in v2.22.0 

func (r RefreshingClientConfig) ProxyURL() refreshable.StringPtr

func (RefreshingClientConfig) ReadTimeout added in v2.22.0 

func (r RefreshingClientConfig) ReadTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) Security added in v2.22.0 

func (r RefreshingClientConfig) Security() RefreshableSecurityConfig

func (RefreshingClientConfig) ServiceName added in v2.22.0 

func (r RefreshingClientConfig) ServiceName() refreshable.String

func (RefreshingClientConfig) SubscribeToClientConfig added in v2.22.0 

func (r RefreshingClientConfig) SubscribeToClientConfig(consumer func(ClientConfig)) (unsubscribe func())

func (RefreshingClientConfig) TLSHandshakeTimeout added in v2.22.0 

func (r RefreshingClientConfig) TLSHandshakeTimeout() refreshable.DurationPtr

func (RefreshingClientConfig) URIs added in v2.22.0 

func (r RefreshingClientConfig) URIs() refreshable.StringSlice

func (RefreshingClientConfig) WriteTimeout added in v2.22.0 

func (r RefreshingClientConfig) WriteTimeout() refreshable.DurationPtr

type RefreshingMetricsConfig added in v2.22.0 

type RefreshingMetricsConfig struct {
	refreshable.Refreshable
}

func NewRefreshingMetricsConfig added in v2.22.0 

func NewRefreshingMetricsConfig(in refreshable.Refreshable) RefreshingMetricsConfig

func (RefreshingMetricsConfig) CurrentMetricsConfig added in v2.22.0 

func (r RefreshingMetricsConfig) CurrentMetricsConfig() MetricsConfig

func (RefreshingMetricsConfig) Enabled added in v2.22.0 

func (r RefreshingMetricsConfig) Enabled() refreshable.BoolPtr

func (RefreshingMetricsConfig) MapMetricsConfig added in v2.22.0 

func (r RefreshingMetricsConfig) MapMetricsConfig(mapFn func(MetricsConfig) interface{}) refreshable.Refreshable

func (RefreshingMetricsConfig) SubscribeToMetricsConfig added in v2.22.0 

func (r RefreshingMetricsConfig) SubscribeToMetricsConfig(consumer func(MetricsConfig)) (unsubscribe func())

func (RefreshingMetricsConfig) Tags added in v2.22.0 

func (r RefreshingMetricsConfig) Tags() RefreshableStringToString

type RefreshingSecurityConfig added in v2.22.0 

type RefreshingSecurityConfig struct {
	refreshable.Refreshable
}

func NewRefreshingSecurityConfig added in v2.22.0 

func NewRefreshingSecurityConfig(in refreshable.Refreshable) RefreshingSecurityConfig

func (RefreshingSecurityConfig) CAFiles added in v2.22.0 

func (r RefreshingSecurityConfig) CAFiles() refreshable.StringSlice

func (RefreshingSecurityConfig) CertFile added in v2.22.0 

func (r RefreshingSecurityConfig) CertFile() refreshable.String

func (RefreshingSecurityConfig) CurrentSecurityConfig added in v2.22.0 

func (r RefreshingSecurityConfig) CurrentSecurityConfig() SecurityConfig

func (RefreshingSecurityConfig) KeyFile added in v2.22.0 

func (r RefreshingSecurityConfig) KeyFile() refreshable.String

func (RefreshingSecurityConfig) MapSecurityConfig added in v2.22.0 

func (r RefreshingSecurityConfig) MapSecurityConfig(mapFn func(SecurityConfig) interface{}) refreshable.Refreshable

func (RefreshingSecurityConfig) SubscribeToSecurityConfig added in v2.22.0 

func (r RefreshingSecurityConfig) SubscribeToSecurityConfig(consumer func(SecurityConfig)) (unsubscribe func())

type RefreshingServicesConfig added in v2.22.0 

type RefreshingServicesConfig struct {
	refreshable.Refreshable
}

func NewRefreshingServicesConfig added in v2.22.0 

func NewRefreshingServicesConfig(in refreshable.Refreshable) RefreshingServicesConfig

func (RefreshingServicesConfig) CurrentServicesConfig added in v2.22.0 

func (r RefreshingServicesConfig) CurrentServicesConfig() ServicesConfig

func (RefreshingServicesConfig) Default added in v2.22.0 

func (r RefreshingServicesConfig) Default() RefreshableClientConfig

func (RefreshingServicesConfig) MapServicesConfig added in v2.22.0 

func (r RefreshingServicesConfig) MapServicesConfig(mapFn func(ServicesConfig) interface{}) refreshable.Refreshable

func (RefreshingServicesConfig) Services added in v2.22.0 

func (r RefreshingServicesConfig) Services() RefreshableStringToClientConfig

func (RefreshingServicesConfig) SubscribeToServicesConfig added in v2.22.0 

func (r RefreshingServicesConfig) SubscribeToServicesConfig(consumer func(ServicesConfig)) (unsubscribe func())

type RefreshingStringToClientConfig added in v2.22.0 

type RefreshingStringToClientConfig struct {
	refreshable.Refreshable
}

func NewRefreshingStringToClientConfig added in v2.22.0 

func NewRefreshingStringToClientConfig(in refreshable.Refreshable) RefreshingStringToClientConfig

func (RefreshingStringToClientConfig) CurrentStringToClientConfig added in v2.22.0 

func (r RefreshingStringToClientConfig) CurrentStringToClientConfig() map[string]ClientConfig

func (RefreshingStringToClientConfig) MapStringToClientConfig added in v2.22.0 

func (r RefreshingStringToClientConfig) MapStringToClientConfig(mapFn func(map[string]ClientConfig) interface{}) refreshable.Refreshable

func (RefreshingStringToClientConfig) SubscribeToStringToClientConfig added in v2.22.0 

func (r RefreshingStringToClientConfig) SubscribeToStringToClientConfig(consumer func(map[string]ClientConfig)) (unsubscribe func())

type RefreshingStringToString added in v2.22.0 

type RefreshingStringToString struct {
	refreshable.Refreshable
}

func NewRefreshingStringToString added in v2.22.0 

func NewRefreshingStringToString(in refreshable.Refreshable) RefreshingStringToString

func (RefreshingStringToString) CurrentStringToString added in v2.22.0 

func (r RefreshingStringToString) CurrentStringToString() map[string]string

func (RefreshingStringToString) MapStringToString added in v2.22.0 

func (r RefreshingStringToString) MapStringToString(mapFn func(map[string]string) interface{}) refreshable.Refreshable

func (RefreshingStringToString) SubscribeToStringToString added in v2.22.0 

func (r RefreshingStringToString) SubscribeToStringToString(consumer func(map[string]string)) (unsubscribe func())

type RequestParam 

type RequestParam interface {
	// contains filtered or unexported methods
}

func WithCompressedRequest 

func WithCompressedRequest(input interface{}, codec codecs.Codec) RequestParam

WithCompressedRequest wraps the 'codec'-encoded request body in zlib compression.

func WithHeader 

func WithHeader(key, value string) RequestParam

WithHeader sets a header on a request.

func WithJSONRequest 

func WithJSONRequest(input interface{}) RequestParam

WithJSONRequest sets the request body to the input marshaled using the JSON codec.

func WithJSONResponse 

func WithJSONResponse(output interface{}) RequestParam

WithJSONResponse unmarshals the response body using the JSON codec. The request will return an error if decoding fails.

func WithPath 

func WithPath(path string) RequestParam

WithPath sets the path for the request. This will be joined with one of the BaseURLs set on the client

func WithPathf 

func WithPathf(format string, args ...interface{}) RequestParam

WithPathf sets the path for the request. This will be joined with one of the BaseURLs set on the client

func WithQueryValues 

func WithQueryValues(query url.Values) RequestParam

WithQueryValues sets a header on a request.

func WithRPCMethodName 

func WithRPCMethodName(name string) RequestParam

WithRPCMethodName configures the requests's context with the RPC method name, like "GetServiceRevision". This is read by the tracing and metrics middlewares.

func WithRawRequestBody deprecated 

func WithRawRequestBody(input io.ReadCloser) RequestParam

WithRawRequestBody uses the provided io.ReadCloser as the request body. Example: 

input, _ := os.Open("file.txt")
resp, err := client.Do(..., WithRawRequestBody(input), ...)

Deprecated: Retries don't include the body for WithRawRequestBody. Use WithRawRequestBodyProvider for full retry support.

func WithRawRequestBodyProvider 

func WithRawRequestBodyProvider(getBody func() io.ReadCloser) RequestParam

WithRawRequestBodyProvider uses the io.ReadCloser provided by getBody as the request body. The getBody parameter must not be nil. Example: 

provider := func() io.ReadCloser {
    input, _ := os.Open("file.txt")
    return input
}
resp, err := client.Do(..., WithRawRequestBodyProvider(provider), ...)

func WithRawResponseBody 

func WithRawResponseBody() RequestParam

WithRawResponseBody configures the request such that the response body will not be read or drained after the request is executed. In this case, it is the responsibility of the caller to read and close the returned reader. Example: 

resp, err := client.Do(..., WithRawResponseBody(), ...)
defer resp.Body.Close()
bytes, err := ioutil.ReadAll(resp.Body)

In the case of an empty response, output will be unmodified (left nil).

func WithRequestBasicAuth 

func WithRequestBasicAuth(username, password string) RequestParam

WithRequestBasicAuth sets the request's Authorization header to use HTTP Basic Authentication with the provided username and password for this request only and takes precedence over any client-scoped authorization.

func WithRequestBody 

func WithRequestBody(input interface{}, encoder codecs.Encoder) RequestParam

WithRequestBody provides a struct to marshal and use as the request body. Encoding is handled by the impl passed to WithRequestBody. Example: 

input := api.RequestInput{Foo: "bar"}
resp, err := client.Do(..., WithRequestBody(input, codecs.JSON), ...)

func WithRequestErrorDecoder 

func WithRequestErrorDecoder(errorDecoder ErrorDecoder) RequestParam

WithRequestErrorDecoder sets an ErrorDecoder to use for this request only. It will take precedence over any ErrorDecoder set on the client. If this request-scoped ErrorDecoder does not handle the response, the client-scoped ErrorDecoder will be consulted in the usual way.

func WithRequestMethod 

func WithRequestMethod(method string) RequestParam

WithRequestMethod sets the HTTP method of the request, e.g. GET or POST.

func WithRequestTimeout added in v2.67.0 

func WithRequestTimeout(timeout time.Duration) RequestParam

WithRequestTimeout uses the provided value instead of the client's configured timeout.

func WithResponseBody 

func WithResponseBody(output interface{}, decoder codecs.Decoder) RequestParam

WithResponseBody provides a struct into which the body middleware will decode as the response body. Decoding is handled by the impl passed to WithResponseBody. Example: 

var output api.RequestOutput
resp, err := client.Do(..., WithResponseBody(&output, codecs.JSON), ...)
return output, nil

In the case of an empty response, output will be unmodified (left nil).

func WithSnappyCompressedRequest added in v2.47.0 

func WithSnappyCompressedRequest(input interface{}, codec codecs.Codec) RequestParam

WithSnappyCompressedRequest wraps the 'codec'-encoded request body in snappy compression.

type SecurityConfig 

type SecurityConfig struct {
	CAFiles  []string `json:"ca-files,omitempty" yaml:"ca-files,omitempty"`
	CertFile string   `json:"cert-file,omitempty" yaml:"cert-file,omitempty"`
	KeyFile  string   `json:"key-file,omitempty" yaml:"key-file,omitempty"`
}

type ServicesConfig 

type ServicesConfig struct {
	// Default values will be used for any field which is not set for a specific client.
	Default ClientConfig `json:",inline" yaml:",inline"`
	// Services is a map of serviceName (e.g. "my-api") to service-specific configuration.
	Services map[string]ClientConfig `json:"services,omitempty" yaml:"services,omitempty"`
}

ServicesConfig is the top-level configuration struct for all HTTP clients. It supports setting default values and overriding those values per-service. Use ClientConfig(serviceName) to retrieve a specific service's configuration, and the httpclient.WithConfig() param to construct a Client using that configuration. The fields of this struct should generally not be read directly by application code.

func (ServicesConfig) ClientConfig 

func (c ServicesConfig) ClientConfig(serviceName string) ClientConfig

ClientConfig returns the default configuration merged with service-specific configuration. If the serviceName is not in the service map, an empty configuration (plus defaults) is used.

func (ServicesConfig) MustClientConfig 

func (c ServicesConfig) MustClientConfig(serviceName string) (ClientConfig, error)

MustClientConfig returns an error if the service name is not configured.

type StaticTagsProvider added in v2.14.0 

type StaticTagsProvider metrics.Tags

func (StaticTagsProvider) Tags added in v2.14.0 

func (s StaticTagsProvider) Tags(_ *http.Request, _ *http.Response, _ error) metrics.Tags

type TagsProvider 

type TagsProvider interface {
	Tags(*http.Request, *http.Response, error) metrics.Tags
}

A TagsProvider returns metrics tags based on an http round trip. The 'error' argument is that returned from the request (if any).

type TagsProviderFunc 

type TagsProviderFunc func(*http.Request, *http.Response, error) metrics.Tags

TagsProviderFunc is a convenience type that implements TagsProvider.

func (TagsProviderFunc) Tags 

func (f TagsProviderFunc) Tags(req *http.Request, resp *http.Response, respErr error) metrics.Tags

type TokenProvider 

type TokenProvider func(context.Context) (string, error)

TokenProvider accepts a context and returns either:

(1) a nonempty token and a nil error, or

(2) an empty string and a non-nil error.

A good implementation will request and cache an ephemeral client token.

Source Files

View all Source files

Directories

Path Synopsis
refreshingclient

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.