exchange

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package exchange is the transport-neutral model of an HTTP exchange: the request that was sent and the response that was received, with the helpers evaluation needs (decoded body, text, cookies).

Headers are kept in the order the transport delivered them; lookups by name are case-insensitive.

Index

Constants

View Source
const DefaultMaxDecodedBody = 512 << 20

DefaultMaxDecodedBody is the decoded (decompressed) body size limit used when Response.MaxDecodedBody is zero.

Variables

This section is empty.

Functions

This section is empty.

Types

type BodyError

type BodyError struct {
	Kind  BodyErrorKind
	Name  string
	Limit int64
}

BodyError is an error decoding a response body. Name is the content coding or charset involved; Limit is the size limit for BodyTooLarge.

func (*BodyError) Description

func (e *BodyError) Description() string

Description is a short title for the error.

func (*BodyError) Error

func (e *BodyError) Error() string

func (*BodyError) Message

func (e *BodyError) Message() string

Message explains the error.

type BodyErrorKind

type BodyErrorKind int

BodyErrorKind classifies body decoding errors.

const (
	// UnsupportedEncoding: a content coding sonde cannot decode.
	UnsupportedEncoding BodyErrorKind = iota
	// DecompressFailed: the body is not valid for its content coding.
	DecompressFailed
	// BodyTooLarge: the decoded body exceeds the size limit.
	BodyTooLarge
	// InvalidCharset: the Content-Type charset is unknown.
	InvalidCharset
	// InvalidDecoding: the body is not valid text in its charset.
	InvalidDecoding
)

Body decoding error kinds.

type CertInfo

type CertInfo struct {
	Subject        string
	Issuer         string
	StartDate      time.Time
	ExpireDate     time.Time
	SerialNumber   string
	SubjectAltName string
	// Value is the certificate in PEM format.
	Value string
}

CertInfo describes a server certificate. Empty strings and zero times mean the attribute is not available.

type Cookie struct {
	Name       string
	Value      string
	Attributes []CookieAttribute
}

Cookie is a cookie set by a response (a Set-Cookie header), with its attributes as written.

func (Cookie) Attr

func (c Cookie) Attr(name string) (value string, ok bool)

Attr returns the value of the first attribute named name (case-insensitive); ok is false when there is none or it has no value.

func (Cookie) Flag

func (c Cookie) Flag(name string) bool

Flag reports whether a value-less attribute named name is present.

func (Cookie) MaxAge

func (c Cookie) MaxAge() (int64, bool)

MaxAge returns the first Max-Age attribute that is a valid integer.

type CookieAttribute

type CookieAttribute struct {
	Name     string
	Value    string
	HasValue bool
}

CookieAttribute is a Set-Cookie attribute; flags such as Secure have no value.

type Direction added in v1.2.0

type Direction int

Direction tells whether a message was sent or received.

const (
	Received Direction = iota
	Sent
)

Message directions.

func (Direction) String added in v1.2.0

func (d Direction) String() string

type GRPCStatus added in v1.2.0

type GRPCStatus struct {
	// Code is the status code: 0 is OK.
	Code int
	// Status is the name of the code: "OK", "NOT_FOUND"…; "UNKNOWN" for a
	// code gRPC does not define.
	Status string
	// Message is the status message, percent-decoded.
	Message string
}

GRPCStatus is the status of a gRPC call.

type Header struct {
	Name  string
	Value string
}

Header is a header field.

type Headers

type Headers []Header

Headers is a list of header fields in received order.

func (Headers) Get

func (h Headers) Get(name string) (string, bool)

Get returns the value of the first field named name (case-insensitive).

func (Headers) Values

func (h Headers) Values(name string) []string

Values returns the values of every field named name (case-insensitive).

type Message added in v1.2.0

type Message struct {
	Direction Direction
	// Binary is set for a WebSocket binary message.
	Binary bool
	Data   []byte
	// Event is the SSE event type ("message" when the event has none);
	// ID the last event ID; Retry the event's retry field, when valid.
	Event string
	ID    string
	Retry *int
	// At is the time since the response headers arrived.
	At time.Duration
}

Message is one SSE event, WebSocket message or gRPC reply (its JSON).

type Protocol added in v1.2.0

type Protocol string

Protocol is the protocol of a stream. More may be added in a minor release: switch on it with a default case.

const (
	ProtocolSSE       Protocol = "sse"
	ProtocolWebSocket Protocol = "websocket"
	ProtocolGRPC      Protocol = "grpc" // a server-streaming gRPC call
)

Stream protocols.

type Request

type Request struct {
	Method  string
	URL     string
	Headers Headers
	Body    []byte
}

Request is a request as sent.

type Response

type Response struct {
	// Version is "HTTP/1.0", "HTTP/1.1", "HTTP/2" or "HTTP/3".
	Version string
	Status  int
	// Reason is the reason phrase of the status line ("OK"); empty for
	// HTTP/2 and HTTP/3.
	Reason  string
	Headers Headers
	Body    []byte
	// URL is the URL this response was received from.
	URL string
	// IP is the address of the server.
	IP string
	// Duration is the transfer time of this response.
	Duration time.Duration
	Timings  Timings
	// Certificate is the server certificate of an HTTPS response.
	Certificate *CertInfo
	// MaxDecodedBody limits the size of the decoded body in bytes; zero
	// means DefaultMaxDecodedBody.
	MaxDecodedBody int64
	// Stream is set for a streamed entry (Server-Sent Events read with a
	// sonde-stream-* option, a WebSocket exchange or a server-streaming
	// gRPC call); nil otherwise.
	Stream *Stream
	// GRPC is the status of a gRPC call; nil for any other entry, and for
	// a gRPC stream stopped before the server sent its status.
	GRPC *GRPCStatus
}

Response is a response as received. Body holds the bytes as transferred, before any content decoding.

func (*Response) Charset

func (r *Response) Charset() (string, bool)

Charset returns the charset parameter of the Content-Type header.

func (*Response) ContentEncodings

func (r *Response) ContentEncodings() []string

ContentEncodings returns the codings listed by the first Content-Encoding header, in header order.

func (*Response) ContentType

func (r *Response) ContentType() (string, bool)

ContentType returns the first Content-Type header value.

func (*Response) Cookie

func (r *Response) Cookie(name string) (Cookie, bool)

Cookie returns the first cookie named name.

func (*Response) Cookies

func (r *Response) Cookies() []Cookie

Cookies returns the cookies of every Set-Cookie header, in order.

func (*Response) DecodedBody

func (r *Response) DecodedBody() ([]byte, error)

DecodedBody returns the body with every content coding removed (br, gzip, deflate, zstd, identity), undoing the last applied coding first.

func (*Response) IsHTML

func (r *Response) IsHTML() bool

IsHTML reports whether the content type is text/html.

func (*Response) Text

func (r *Response) Text() (string, error)

Text returns the decoded body as a string, using the charset of the Content-Type header (UTF-8 by default). Malformed input is an error.

type StopReason added in v1.2.0

type StopReason string

StopReason tells why a stream ended normally. More may be added in a minor release.

const (
	StopCount    StopReason = "count"     // sonde-stream-count events were read
	StopTimeout  StopReason = "timeout"   // sonde-stream-timeout elapsed
	StopMaxBytes StopReason = "max-bytes" // sonde-stream-max-bytes bytes were read
	StopClosed   StopReason = "closed"    // the server ended the stream
	StopScript   StopReason = "script"    // every [SondeMessages] step ran
)

Reasons a stream stopped.

type Stream added in v1.2.0

type Stream struct {
	Protocol Protocol
	// StopReason is empty when the stream failed: the messages are then
	// those exchanged before the failure.
	StopReason StopReason
	// Messages are the SSE events, or the WebSocket messages sent and
	// received, in order.
	Messages []Message
}

Stream is what a streamed entry exchanged after the response headers: Server-Sent Events, WebSocket messages, or the replies of a server-streaming gRPC call.

func (*Stream) ReceivedMessages added in v1.2.0

func (s *Stream) ReceivedMessages() []Message

ReceivedMessages returns the messages received, in order.

type Timings

type Timings struct {
	Begin         time.Time
	End           time.Time
	NameLookup    time.Duration
	Connect       time.Duration
	AppConnect    time.Duration
	PreTransfer   time.Duration
	StartTransfer time.Duration
	Total         time.Duration
}

Timings are the phases of a transfer, measured from its start.

Jump to

Keyboard shortcuts

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