httpx

package
v1.4.0 Latest Latest
Warning

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

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

Documentation

Overview

Package httpx executes requests: it builds the HTTP request from a RequestSpec, applies the transport options, follows redirects manually and keeps the cookie store of a run unit.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Body

type Body struct {
	Kind     BodyKind
	Data     []byte
	Filename string // BodyFile only, as written
}

Body is a request body.

type BodyKind

type BodyKind int

BodyKind tells how a body was written.

const (
	BodyBinary BodyKind = iota // base64, hex or no body
	BodyText                   // strings, JSON, XML, multiline
	BodyFile                   // file, ...;
)

Body kinds.

type Call

type Call struct {
	Request  exchange.Request
	Response *exchange.Response
	Timings  exchange.Timings
}

Call is one HTTP exchange of an entry; redirects produce several.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client executes the requests of one run unit and keeps its cookies. It is not safe for concurrent use.

func NewClient

func NewClient(cfg ClientConfig) (*Client, error)

NewClient returns a client; it fails when CookieFile cannot be read.

func (*Client) AddCookie

func (c *Client) AddCookie(netscape string) error

AddCookie adds a cookie written in Netscape format (the `@cookie_storage_set:` comment command).

func (*Client) ClearCookies

func (c *Client) ClearCookies()

ClearCookies empties the cookie store (`@cookie_storage_clear`).

func (*Client) Close

func (c *Client) Close() error

Close releases idle connections.

func (*Client) Cookies

func (c *Client) Cookies() []Cookie

Cookies returns the cookie store content, in insertion order.

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, spec *RequestSpec, opts *Options) ([]Call, error)

Execute sends a request, following redirects when opts ask for it, and returns every call in order (the last one is the final response). A transport failure returns an *Error; calls completed before it are returned too.

func (*Client) Upgrade added in v1.2.0

func (c *Client) Upgrade(ctx context.Context, spec *RequestSpec, opts *Options) (*Upgrade, error)

Upgrade prepares the WebSocket handshake of spec. The http2 and http3 options are ignored, with a warning: an upgrade needs HTTP/1.1.

type ClientConfig

type ClientConfig struct {
	// Sandbox confines the paths of Options and Body files. Required.
	Sandbox *sandbox.Root
	// CookieFile is a Netscape cookie file read at start (--cookie; a
	// command line path, not sandboxed). Empty: none.
	CookieFile string
	// NoCookieStore disables the cookie store.
	NoCookieStore bool
	// Version is the sonde version for the default User-Agent.
	Version string
	// UserAgent replaces the default `sonde/<version>` User-Agent.
	UserAgent string
	// Debug receives connection details (DNS, connect, TLS) as lines
	// without prefix when an entry is verbose. Nil: discarded.
	Debug func(line string)
	// Warn receives warnings (e.g. `insecure` once per client). Nil: discarded.
	Warn func(msg string)
	// Hosts restricts the hosts requests may name and connections may
	// reach (`sonde mcp --allow-host`). Nil: unrestricted.
	Hosts *netpolicy.Policy
}

ClientConfig configures a Client for one run unit.

type Cookie struct {
	Domain           string
	IncludeSubdomain bool
	Path             string
	HTTPS            bool
	Expires          int64 // Unix seconds, 0: session cookie
	Name             string
	Value            string
	HTTPOnly         bool
}

Cookie is a stored cookie, with the fields of the Netscape format.

type Error

type Error struct {
	Kind ErrorKind
	// Description is the title (e.g. "HTTP connection", "Unsupported
	// option"); Msg the explanation.
	Description string
	Msg         string
	Err         error
}

Error is a transport error.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorKind

type ErrorKind int

ErrorKind classifies transport errors.

const (
	ErrConnect          ErrorKind = iota // "(7) Failed to connect to …"
	ErrResolve                           // "(6) Could not resolve host: …"
	ErrTimeout                           // "(28) Operation timed out after …"
	ErrTLS                               // "(35)/(60) SSL …"
	ErrTooManyRedirects                  // "(47) Maximum (N) redirects followed"
	ErrMaxFilesize                       // "(63) Maximum file size exceeded"
	ErrInvalidURL                        // relative/malformed redirect or URL
	ErrUnsupported                       // unsupported option (http1.0, ntlm, …)
	ErrFileAccess                        // sandbox denial or unreadable file
	ErrOther
	ErrHostDenied // a host outside ClientConfig.Hosts
)

Transport error kinds; the message of each follows curl's wording where the command line tools print it.

type FileParam

type FileParam struct {
	Name        string
	Filename    string
	Data        []byte
	ContentType string
}

FileParam is a multipart file part.

type HTTPVersion

type HTTPVersion int

HTTPVersion is the requested protocol version.

const (
	HTTPDefault HTTPVersion = iota
	HTTP10
	HTTP11
	HTTP2
	HTTP3
)

Requested versions. HTTP10 is not supported.

type IPResolve

type IPResolve int

IPResolve restricts name resolution.

const (
	IPAny IPResolve = iota
	IPv4
	IPv6
)

IP families.

type MultipartParam

type MultipartParam struct {
	Param *Param
	File  *FileParam
}

MultipartParam is a multipart part: exactly one of Param and File is set.

type Options

type Options struct {
	AWSSigV4       string // unsupported: a non-empty value is an error
	CACert         string
	ClientCert     string
	ClientKey      string
	Compressed     bool
	ConnectTimeout time.Duration // zero: 300s
	ConnectTo      []string      // HOST1:PORT1:HOST2:PORT2
	Digest         bool          // unsupported
	FollowLocation bool
	// LocationTrusted forwards credentials to every redirect host.
	LocationTrusted bool
	Headers         []exchange.Header // -H/--header, added to every request
	HTTPVersion     HTTPVersion
	Insecure        bool
	IPResolve       IPResolve
	MaxFilesize     int64 // bytes, 0: no limit
	MaxRecvSpeed    int64 // bytes per second, 0: no limit
	MaxSendSpeed    int64 // bytes per second, 0: no limit
	MaxRedirects    int   // -1: unlimited; default 50
	Negotiate       bool  // unsupported
	Netrc           bool
	NetrcFile       string
	NetrcOptional   bool
	// NetrcAllowReroute sends netrc credentials even when resolve,
	// connect-to or a proxy reroutes the host.
	NetrcAllowReroute bool
	NoProxy           string
	NTLM              bool // unsupported
	PathAsIs          bool
	PinnedPublicKey   string
	Proxy             string
	Resolve           []string      // HOST:PORT:ADDR[,ADDR]...
	Timeout           time.Duration // max-time; zero: 300s
	UnixSocket        string
	User              string // user:password
	UserAgent         string // empty: sonde/<version>
	// Verbose enables the debug callback for connection details.
	Verbose bool
	// LocalFiles are the file options given on the command line
	// (cacert, cert, key, pinnedpubkey, unix-socket): they are read
	// relative to the working directory instead of through the sandbox.
	LocalFiles map[string]bool
	// ReadStream, when set, reads the body of the final response instead
	// of reading it whole (a streamed entry). header is the response's;
	// body is decoded (content codings removed); the response keeps the
	// bytes as received. MaxFilesize does not apply. stop cancels the
	// request, so a pending read returns an error. When it fails, Execute
	// returns the call with the error.
	ReadStream func(header exchange.Headers, body io.Reader, stop func()) error
	// GRPC marks a gRPC call: it uses HTTP/2 only (cleartext HTTP/2 with
	// prior knowledge for http://), never follows redirects, and its
	// response headers include the trailers.
	GRPC bool
	// OnSend, when set, receives each request as it is sent (every
	// redirect hop, and a WebSocket handshake), exactly as the Call
	// reporting it records it. It is called on the goroutine of Execute or
	// of the handshake, before the request is written. req shares its
	// slices with the Call: it must not be modified.
	OnSend func(req exchange.Request)
}

Options are the transport options of one entry: command line options overridden by the entry's Options section. Paths come from the request file and are read through ClientConfig.Sandbox, except where noted.

type Param

type Param struct {
	Name  string
	Value string
}

Param is a query string or form parameter.

type RequestCookie

type RequestCookie struct {
	Name  string
	Value string
}

RequestCookie is a cookie from a [Cookies] section.

type RequestSpec

type RequestSpec struct {
	Method    string
	URL       string
	Headers   []exchange.Header
	Query     []Param
	Form      []Param
	Multipart []MultipartParam
	Cookies   []RequestCookie
	Body      Body
	// ImplicitContentType is the Content-Type sent when Headers has none:
	// form, multipart, JSON or XML bodies.
	ImplicitContentType string
}

RequestSpec is a request as described by an entry, after rendering its templates.

type Upgrade added in v1.2.0

type Upgrade struct {
	// URL is the request URL, with ws and wss mapped to http and https.
	URL string
	// Host overrides the Host header when the entry sets one.
	Host string
	// Header holds the entry's headers, cookies, credentials and
	// User-Agent, as Execute would send them.
	Header http.Header
	// Client sends the handshake through the entry's transport options
	// (TLS, proxy, resolve), always with HTTP/1.1, without following
	// redirects.
	Client *http.Client
	// Request is the request as reported in results; Response adds the
	// handshake headers the library sent.
	Request exchange.Request
	// contains filtered or unexported fields
}

Upgrade is a prepared WebSocket opening handshake (RFC 6455): the entry's request and a client to send it with. The WebSocket library adds its own handshake headers to Header and sends the request with Client.

func (*Upgrade) Error added in v1.2.0

func (u *Upgrade) Error(err error) error

Error classifies an error of a handshake that got no response, like a failed Execute.

func (*Upgrade) MaxTime added in v1.2.0

func (u *Upgrade) MaxTime() time.Duration

MaxTime is the entry's max-time: the limit of the whole exchange.

func (*Upgrade) Response added in v1.2.0

func (u *Upgrade) Response(resp *http.Response) *exchange.Response

Response converts the handshake response and stores its cookies. Its body is empty for an accepted upgrade, the whole body otherwise. The response has no IP address and no phase timings.

Jump to

Keyboard shortcuts

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