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
- type BodyError
- type BodyErrorKind
- type CertInfo
- type Cookie
- type CookieAttribute
- type Direction
- type GRPCStatus
- type Header
- type Headers
- type Message
- type Protocol
- type Request
- type Response
- func (r *Response) Charset() (string, bool)
- func (r *Response) ContentEncodings() []string
- func (r *Response) ContentType() (string, bool)
- func (r *Response) Cookie(name string) (Cookie, bool)
- func (r *Response) Cookies() []Cookie
- func (r *Response) DecodedBody() ([]byte, error)
- func (r *Response) IsHTML() bool
- func (r *Response) Text() (string, error)
- type StopReason
- type Stream
- type Timings
Constants ¶
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 ¶
Description is a short title for 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 ¶
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 ¶
Attr returns the value of the first attribute named name (case-insensitive); ok is false when there is none or it has no value.
type CookieAttribute ¶
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.
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 Headers ¶
type Headers []Header
Headers is a list of header fields in received order.
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.
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) ContentEncodings ¶
ContentEncodings returns the codings listed by the first Content-Encoding header, in header order.
func (*Response) ContentType ¶
ContentType returns the first Content-Type header value.
func (*Response) DecodedBody ¶
DecodedBody returns the body with every content coding removed (br, gzip, deflate, zstd, identity), undoing the last applied coding first.
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
ReceivedMessages returns the messages received, in order.