httpx

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: Apache-2.0 Imports: 41 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.

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)
}

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
)

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
}

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.

Jump to

Keyboard shortcuts

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