transport

package
v0.21.4 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

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

View Source
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.

View Source
const (
	EnvConnectTimeout = "NORCUBE_CONNECT_TIMEOUT"
	EnvReadTimeout    = "NORCUBE_READ_TIMEOUT"
	EnvMaxAttempts    = "NORCUBE_MAX_ATTEMPTS"
	EnvCABundle       = "NORCUBE_CA_BUNDLE"
)

Environment variables read by FromEnv.

View Source
const EnvDebug = "NORCUBE_DEBUG"

EnvDebug turns on the HTTP trace, like --debug.

View Source
const IdempotencyKeyHeader = "Idempotency-Key"

IdempotencyKeyHeader marks a POST as safe to retry.

View Source
const Redacted = "[REDACTED]"

Redacted replaces secrets in the trace.

Variables

View Source
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

func Default() *http.Client

Default returns an API client with the built-in settings, for code that runs without command-line context (tests, library defaults).

func New

func New(cfg Config) (*http.Client, error)

New returns the client for API requests: per-attempt ReadTimeout and retries on throttling and transient server or network failures.

func NewDownload

func NewDownload(cfg Config) (*http.Client, error)

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

func ParseTimeout(v string) (time.Duration, error)

ParseTimeout reads a timeout given as whole seconds or as a Go duration. "0" means no timeout.

func RedactBody added in v0.17.0

func RedactBody(contentType string, raw []byte) string

RedactBody renders a JSON or form body with credential fields replaced. Other content types are summarized by size.

func RedactURL added in v0.17.0

func RedactURL(u *url.URL) string

RedactURL returns u as a string with credential query values replaced, e.g. the signature of a presigned storage URL.

func UserAgent

func UserAgent() string

UserAgent identifies the CLI build to the server, e.g. "norcube/0.16.0 (darwin; arm64) go/go1.26.1".

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
	// Debug, when set, receives a trace of every HTTP attempt with
	// credentials redacted (--debug, NORCUBE_DEBUG=1).
	Debug io.Writer
}

Config describes the client. The zero value is not useful; start from Defaults() or FromEnv().

func Defaults

func Defaults() Config

Defaults returns the built-in configuration.

func FromEnv

func FromEnv() (Config, error)

FromEnv returns Defaults() overridden by the NORCUBE_* environment variables. Timeouts accept whole seconds ("30") or Go durations ("1m30s").

func FromEnvOver

func FromEnvOver(cfg Config) (Config, error)

FromEnvOver applies the NORCUBE_* variables that are set on top of cfg.

type TimeoutError

type TimeoutError struct{ After time.Duration }

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL