Documentation
¶
Overview ¶
Package transport builds the one HTTP client every part of the CLI uses: generated API clients, the auth client, the token exchange and artifact downloads. It owns timeouts, retries, proxy and CA settings and the User-Agent, so no command has to think about them.
Index ¶
Constants ¶
const ( DefaultConnectTimeout = 10 * time.Second DefaultReadTimeout = 60 * time.Second DefaultMaxAttempts = 3 // DefaultIdleTimeout is how long a streaming download may go without // receiving a single byte before it is abandoned. DefaultIdleTimeout = 60 * time.Second )
Defaults. ReadTimeout bounds one attempt of an API request, from sending it to reading the last byte of the response.
const ( EnvConnectTimeout = "NORCUBE_CONNECT_TIMEOUT" EnvReadTimeout = "NORCUBE_READ_TIMEOUT" EnvMaxAttempts = "NORCUBE_MAX_ATTEMPTS" EnvCABundle = "NORCUBE_CA_BUNDLE" )
Environment variables read by FromEnv.
const IdempotencyKeyHeader = "Idempotency-Key"
IdempotencyKeyHeader marks a POST as safe to retry.
Variables ¶
var ErrIdleTimeout = errors.New("connection stalled: no data received within the idle timeout")
ErrIdleTimeout is returned while reading a download body that received no data for the configured idle timeout.
Functions ¶
func Default ¶
Default returns an API client with the built-in settings, for code that runs without command-line context (tests, library defaults).
func New ¶
New returns the client for API requests: per-attempt ReadTimeout and retries on throttling and transient server or network failures.
func NewDownload ¶
NewDownload returns the client for streaming large bodies (backup artifacts). A download may take as long as it needs, but the server must answer within ReadTimeout and then keep bytes flowing: a body that stalls for IdleTimeout fails with ErrIdleTimeout. Retries apply until the response headers arrive.
func ParseTimeout ¶
ParseTimeout reads a timeout given as whole seconds or as a Go duration. "0" means no timeout.
Types ¶
type Config ¶
type Config struct {
// ConnectTimeout bounds the TCP dial. Zero means no limit.
ConnectTimeout time.Duration
// ReadTimeout bounds one attempt of an API request including reading
// its body. Zero means no limit. Downloads use IdleTimeout instead.
ReadTimeout time.Duration
// IdleTimeout bounds the silence between two reads of a streaming
// download. Zero means no limit.
IdleTimeout time.Duration
// MaxAttempts is the total number of tries for a retryable request,
// including the first one. Values below 1 are treated as 1.
MaxAttempts int
// CABundle is a PEM file whose certificates are trusted in addition
// to the system roots (corporate TLS-inspecting proxies).
CABundle string
// UserAgent is sent on requests that don't set their own.
UserAgent string
}
Config describes the client. The zero value is not useful; start from Defaults() or FromEnv().
func FromEnv ¶
FromEnv returns Defaults() overridden by the NORCUBE_* environment variables. Timeouts accept whole seconds ("30") or Go durations ("1m30s").
func FromEnvOver ¶
FromEnvOver applies the NORCUBE_* variables that are set on top of cfg.
type TimeoutError ¶
TimeoutError reports an attempt that ran past the read timeout.
func (*TimeoutError) Error ¶
func (e *TimeoutError) Error() string
func (*TimeoutError) Timeout ¶
func (e *TimeoutError) Timeout() bool
Timeout lets net.Error-style checks recognize it.
func (*TimeoutError) Unwrap ¶
func (e *TimeoutError) Unwrap() error
Unwrap makes errors.Is(err, context.DeadlineExceeded) hold.