Documentation
¶
Overview ¶
Package fsthttp provides HTTP functionality for Fastly's Compute environment.
A Compute program can be thought of as an HTTP request handler. Each execution is triggered by an incoming request from a client, and is expected to respond to that request before terminating. The Serve function provides a Handler-style interface to that Request and its ResponseWriter.
The types in this package are similar to, but not the same as, corresponding types in the standard library's package net/http. Refer to the documentation for important caveats about usage.
Index ¶
- Constants
- Variables
- func CanonicalHeaderKey(s string) string
- func Error(w ResponseWriter, error string, code int)
- func NotFound(w ResponseWriter, r *Request)
- func Serve(h Handler)
- func ServeFunc(f HandlerFunc)
- func SetCookie(h Header, cookie *Cookie)
- func StatusText(code int) string
- type Backend
- func (b *Backend) BetweenBytesTimeout() time.Duration
- func (b *Backend) ConnectTimeout() time.Duration
- func (b *Backend) FirstByteTimeout() time.Duration
- func (b *Backend) Health() (BackendHealth, error)
- func (b *Backend) HostOverride() string
- func (b *Backend) IsDynamic() bool
- func (b *Backend) IsSSL() bool
- func (b *Backend) Name() string
- func (b *Backend) SSLMaxVersion() TLSVersion
- func (b *Backend) SSLMinVersion() TLSVersion
- func (b *Backend) Target() string
- type BackendHealth
- type BackendOptions
- func (b *BackendOptions) BetweenBytesTimeout(t time.Duration) *BackendOptions
- func (b *BackendOptions) CACert(cert string) *BackendOptions
- func (b *BackendOptions) CertHostname(host string) *BackendOptions
- func (b *BackendOptions) Ciphers(ciphers string) *BackendOptions
- func (b *BackendOptions) ClientCertificate(certificate string, key secretstore.Secret) *BackendOptions
- func (b *BackendOptions) ConnectTimeout(t time.Duration) *BackendOptions
- func (b *BackendOptions) FirstByteTimeout(t time.Duration) *BackendOptions
- func (b *BackendOptions) HTTPKeepaliveTime(time time.Duration) *BackendOptions
- func (b *BackendOptions) HostOverride(host string) *BackendOptions
- func (b *BackendOptions) PoolConnections(poolingOn bool) *BackendOptions
- func (b *BackendOptions) SNIHostname(host string) *BackendOptions
- func (b *BackendOptions) SSLMaxVersion(max TLSVersion) *BackendOptions
- func (b *BackendOptions) SSLMinVersion(min TLSVersion) *BackendOptions
- func (b *BackendOptions) TCPKeepaliveEnable(enable bool) *BackendOptions
- func (b *BackendOptions) TCPKeepaliveInterval(interval time.Duration) *BackendOptions
- func (b *BackendOptions) TCPKeepaliveProbes(count uint32) *BackendOptions
- func (b *BackendOptions) TCPKeepaliveTime(interval time.Duration) *BackendOptions
- func (b *BackendOptions) UseGRPC(v bool) *BackendOptions
- func (b *BackendOptions) UseSSL(v bool) *BackendOptions
- type CacheOptions
- type Cookie
- type DecompressResponseOptions
- type Handler
- type HandlerFunc
- type Header
- func (h Header) Add(key, value string)
- func (h Header) Apply(hs Header)
- func (h Header) Clone() Header
- func (h Header) Del(key string)
- func (h Header) Get(key string) string
- func (h Header) Keys() []string
- func (h Header) Reset(hs Header)
- func (h Header) Set(key, value string)
- func (h Header) Values(key string) []string
- type Limits
- func (limits *Limits) MaxHeaderNameLen() int
- func (limits *Limits) MaxHeaderValueLen() int
- func (limits *Limits) MaxMethodLen() int
- func (limits *Limits) MaxURLLen() int
- func (limits *Limits) SetMaxHeaderNameLen(len int)
- func (limits *Limits) SetMaxHeaderValueLen(len int)
- func (limits *Limits) SetMaxMethodLen(_ int)
- func (limits *Limits) SetMaxURLLen(_ int)
- type Request
- func (req *Request) AddCookie(c *Cookie)
- func (req *Request) Clone() *Request
- func (req *Request) CloneWithBody(body io.Reader) *Request
- func (req *Request) Cookie(name string) (*Cookie, error)
- func (req *Request) Cookies() []*Cookie
- func (req *Request) Send(ctx context.Context, backend string) (*Response, error)
- func (req *Request) SetBody(body io.Reader)
- type Response
- type ResponseWriter
- type SameSite
- type TLSInfo
- type TLSVersion
- type Transport
Constants ¶
const ( MethodGet = "GET" MethodHead = "HEAD" MethodPost = "POST" MethodPut = "PUT" MethodPatch = "PATCH" // RFC 5789 MethodDelete = "DELETE" MethodConnect = "CONNECT" MethodOptions = "OPTIONS" MethodTrace = "TRACE" )
Common HTTP methods.
Unless otherwise noted, these are defined in RFC 7231 section 4.3.
const ( StatusContinue = 100 // RFC 7231, 6.2.1 StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2 StatusProcessing = 102 // RFC 2518, 10.1 StatusEarlyHints = 103 // RFC 8297 StatusOK = 200 // RFC 7231, 6.3.1 StatusCreated = 201 // RFC 7231, 6.3.2 StatusAccepted = 202 // RFC 7231, 6.3.3 StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4 StatusNoContent = 204 // RFC 7231, 6.3.5 StatusResetContent = 205 // RFC 7231, 6.3.6 StatusPartialContent = 206 // RFC 7233, 4.1 StatusMultiStatus = 207 // RFC 4918, 11.1 StatusAlreadyReported = 208 // RFC 5842, 7.1 StatusIMUsed = 226 // RFC 3229, 10.4.1 StatusMultipleChoices = 300 // RFC 7231, 6.4.1 StatusMovedPermanently = 301 // RFC 7231, 6.4.2 StatusFound = 302 // RFC 7231, 6.4.3 StatusSeeOther = 303 // RFC 7231, 6.4.4 StatusNotModified = 304 // RFC 7232, 4.1 StatusUseProxy = 305 // RFC 7231, 6.4.5 StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7 StatusPermanentRedirect = 308 // RFC 7538, 3 StatusBadRequest = 400 // RFC 7231, 6.5.1 StatusPaymentRequired = 402 // RFC 7231, 6.5.2 StatusForbidden = 403 // RFC 7231, 6.5.3 StatusNotFound = 404 // RFC 7231, 6.5.4 StatusMethodNotAllowed = 405 // RFC 7231, 6.5.5 StatusNotAcceptable = 406 // RFC 7231, 6.5.6 StatusProxyAuthRequired = 407 // RFC 7235, 3.2 StatusRequestTimeout = 408 // RFC 7231, 6.5.7 StatusConflict = 409 // RFC 7231, 6.5.8 StatusGone = 410 // RFC 7231, 6.5.9 StatusLengthRequired = 411 // RFC 7231, 6.5.10 StatusPreconditionFailed = 412 // RFC 7232, 4.2 StatusRequestEntityTooLarge = 413 // RFC 7231, 6.5.11 StatusRequestURITooLong = 414 // RFC 7231, 6.5.12 StatusUnsupportedMediaType = 415 // RFC 7231, 6.5.13 StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4 StatusExpectationFailed = 417 // RFC 7231, 6.5.14 StatusTeapot = 418 // RFC 7168, 2.3.3 StatusMisdirectedRequest = 421 // RFC 7540, 9.1.2 StatusUnprocessableEntity = 422 // RFC 4918, 11.2 StatusLocked = 423 // RFC 4918, 11.3 StatusFailedDependency = 424 // RFC 4918, 11.4 StatusTooEarly = 425 // RFC 8470, 5.2. StatusUpgradeRequired = 426 // RFC 7231, 6.5.15 StatusPreconditionRequired = 428 // RFC 6585, 3 StatusTooManyRequests = 429 // RFC 6585, 4 StatusRequestHeaderFieldsTooLarge = 431 // RFC 6585, 5 StatusInternalServerError = 500 // RFC 7231, 6.6.1 StatusNotImplemented = 501 // RFC 7231, 6.6.2 StatusBadGateway = 502 // RFC 7231, 6.6.3 StatusGatewayTimeout = 504 // RFC 7231, 6.6.5 StatusHTTPVersionNotSupported = 505 // RFC 7231, 6.6.6 StatusVariantAlsoNegotiates = 506 // RFC 2295, 8.1 StatusInsufficientStorage = 507 // RFC 4918, 11.5 StatusLoopDetected = 508 // RFC 5842, 7.2 StatusNotExtended = 510 // RFC 2774, 7 StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6 )
HTTP status codes as registered with IANA. See: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
const TimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"
TimeFormat is the time format to use when generating times in HTTP headers. It is like time.RFC1123 but hard-codes GMT as the time zone. The time being formatted must be in UTC for Format to generate the correct format.
For parsing this time format, see ParseTime.
Variables ¶
var ( // ErrDynamicBackendDisallowed indicates the service is not allowed to // create dynamic backends. ErrDynamicBackendDisallowed = errors.New("dynamic backends not supported for this service") // ErrBackendNameInUse indicates the backend name is already in use. ErrBackendNameInUse = errors.New("backend name already in use") // ErrBackendNotFound indicates the provided backend was not found. ErrBackendNotFound = errors.New("backend not found") // ErrUnexpected indicates an unexpected error occurred. ErrUnexpected = errors.New("unexpected error") )
var ErrNoCookie = errors.New("fsthttp: named cookie not present")
ErrNoCookie is returned by Request's Cookie method when a cookie is not found.
var RequestLimits = Limits{ // contains filtered or unexported fields }
RequestLimits are the limits for the components of an HTTP request.
var ResponseLimits = Limits{ // contains filtered or unexported fields }
ResponseLimits are the limits for the components of an HTTP response.
Functions ¶
func CanonicalHeaderKey ¶
CanonicalHeaderKey returns the canonical format of the header key s. The canonicalization converts the first letter and any letter following a hyphen to upper case; the rest are converted to lowercase. For example, the canonical key for "accept-encoding" is "Accept-Encoding". If s contains a space or invalid header field bytes, it is returned without modifications.
func Error ¶ added in v0.1.2
func Error(w ResponseWriter, error string, code int)
Error replies to the request with the specified error message and HTTP code. It does not otherwise end the request; the caller should ensure no further writes are done to w. The error message should be plain text.
func NotFound ¶ added in v0.1.2
func NotFound(w ResponseWriter, r *Request)
NotFound replies to the request with an HTTP 404 not found error.
func Serve ¶
func Serve(h Handler)
Serve calls h, providing it with a context that will be canceled when Serve returns, a Request representing the incoming client request that initiated this execution, and a ResponseWriter that can be used to respond to that request. Serve will ensure the ResponseWriter has been closed before returning, and so should only be called once per execution.
func SetCookie ¶
SetCookie adds a Set-Cookie header to the provided ResponseWriter's headers. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.
func StatusText ¶
StatusText returns a text for the HTTP status code. It returns the empty string if the code is unknown.
Types ¶
type Backend ¶ added in v0.1.5
type Backend struct {
// contains filtered or unexported fields
}
Backend is a fastly backend
func BackendFromName ¶ added in v0.1.7
func RegisterDynamicBackend ¶ added in v0.1.5
func RegisterDynamicBackend(name string, target string, options *BackendOptions) (*Backend, error)
Register a new dynamic backend.
func (*Backend) BetweenBytesTimeout ¶ added in v0.1.7
func (*Backend) ConnectTimeout ¶ added in v0.1.7
func (*Backend) FirstByteTimeout ¶ added in v0.1.7
func (*Backend) Health ¶ added in v0.1.7
func (b *Backend) Health() (BackendHealth, error)
Health dynamically checks the backend's health status.
func (*Backend) HostOverride ¶ added in v0.1.7
func (*Backend) SSLMaxVersion ¶ added in v0.1.7
func (b *Backend) SSLMaxVersion() TLSVersion
func (*Backend) SSLMinVersion ¶ added in v0.1.7
func (b *Backend) SSLMinVersion() TLSVersion
type BackendHealth ¶ added in v0.1.7
type BackendHealth uint32
const ( BackendHealthUnknown BackendHealth = 0 BackendHealthHealthy BackendHealth = 1 BackendHealthUnhealthy BackendHealth = 2 )
Constants for dynamic backend health status
type BackendOptions ¶ added in v0.1.5
type BackendOptions struct {
// contains filtered or unexported fields
}
BackendOption is a builder for the configuration of a dynamic backend.
func NewBackendOptions ¶ added in v0.1.7
func NewBackendOptions() *BackendOptions
func (*BackendOptions) BetweenBytesTimeout ¶ added in v0.1.5
func (b *BackendOptions) BetweenBytesTimeout(t time.Duration) *BackendOptions
BetweenBytesTimeout sets the maximum duration that Fastly will wait while receiving no data on a download from a backend.
func (*BackendOptions) CACert ¶ added in v0.1.5
func (b *BackendOptions) CACert(cert string) *BackendOptions
CACert sets the CA certificate to use when checking the validity of the backend. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) CertHostname ¶ added in v0.1.5
func (b *BackendOptions) CertHostname(host string) *BackendOptions
CertHostname sets the hostname that the server certificate should declare. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) Ciphers ¶ added in v0.1.5
func (b *BackendOptions) Ciphers(ciphers string) *BackendOptions
Ciphers sets the list of OpenSSL ciphers to support for connections to this origin. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) ClientCertificate ¶ added in v1.3.3
func (b *BackendOptions) ClientCertificate(certificate string, key secretstore.Secret) *BackendOptions
ClientCertificate sets the client certificate to be provided to the server as part of the SSL handshake. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) ConnectTimeout ¶ added in v0.1.5
func (b *BackendOptions) ConnectTimeout(t time.Duration) *BackendOptions
ConnectTimeout sets the maximum duration to wait for a connection to this backend to be established.
func (*BackendOptions) FirstByteTimeout ¶ added in v0.1.5
func (b *BackendOptions) FirstByteTimeout(t time.Duration) *BackendOptions
FirstByteTimeout sets the maximum duration to wait for the server response to begin after a TCP connection is established and the request has been sent.
func (*BackendOptions) HTTPKeepaliveTime ¶ added in v1.3.3
func (b *BackendOptions) HTTPKeepaliveTime(time time.Duration) *BackendOptions
HTTPKeepaliveTime configures how long to allow HTTP connections to remain idle in a connection pool before it should be considered closed.
func (*BackendOptions) HostOverride ¶ added in v0.1.5
func (b *BackendOptions) HostOverride(host string) *BackendOptions
HostOverride sets the HTTP Host header on connections to this backend.
func (*BackendOptions) PoolConnections ¶ added in v1.3.3
func (b *BackendOptions) PoolConnections(poolingOn bool) *BackendOptions
PoolConnections allows users to turn connection pooling on or off for the backend. Pooling allows the Compute platform to reuse connections across multiple sessions, resulting in lower resource use at the server (because it does not need to reperform the TCP handhsake and TLS authentication when the connection is reused). The default is to pool connections. Set this to false to create a new connection to the backend for every incoming session.
func (*BackendOptions) SNIHostname ¶ added in v0.1.5
func (b *BackendOptions) SNIHostname(host string) *BackendOptions
SNIHostname sets the SNI hostname to use on connections to this backend. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) SSLMaxVersion ¶ added in v0.1.5
func (b *BackendOptions) SSLMaxVersion(max TLSVersion) *BackendOptions
SSLMaxVersion sets the maximum allowed TLS version on SSL connections to this backend. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) SSLMinVersion ¶ added in v0.1.5
func (b *BackendOptions) SSLMinVersion(min TLSVersion) *BackendOptions
SSLMinVersion sets the minimum allowed TLS version on SSL connections to this backend. Setting this will enable SSL for the connection as a side effect.
func (*BackendOptions) TCPKeepaliveEnable ¶ added in v1.3.3
func (b *BackendOptions) TCPKeepaliveEnable(enable bool) *BackendOptions
TCPKeepaliveEnable sets whether or not to use TCP keepalives to try to maintain the connetion to the backend.
func (*BackendOptions) TCPKeepaliveInterval ¶ added in v1.3.3
func (b *BackendOptions) TCPKeepaliveInterval(interval time.Duration) *BackendOptions
TCPKeepaliveInterval sets the interval to use when sending TCP keepalive probes. Intervals of less than 1 second will be rounded up to 1 second.
Setting this value implicitly enables TCP keepalives. If you are calling both this method and `TCPKeepAliveEnable` with dynamically loaded or generated values, make sure to call `TCPKeepAliveEnable` last.
func (*BackendOptions) TCPKeepaliveProbes ¶ added in v1.3.3
func (b *BackendOptions) TCPKeepaliveProbes(count uint32) *BackendOptions
TCPKeepaliveProbes sets how many unanswered TCP probes we should send to the backend before we consider the connection dead. Setting this value implicitly enables TCP keepalives.
func (*BackendOptions) TCPKeepaliveTime ¶ added in v1.3.3
func (b *BackendOptions) TCPKeepaliveTime(interval time.Duration) *BackendOptions
TCPKeepaliveTime sets how long to wait after the last data was sent before starting to send keepalive probes. Setting this value implicitly enables TCP keepalives.
func (*BackendOptions) UseGRPC ¶ added in v1.3.3
func (b *BackendOptions) UseGRPC(v bool) *BackendOptions
UseGRPC sets whether or not to connect to the backend via gRPC
func (*BackendOptions) UseSSL ¶ added in v0.1.5
func (b *BackendOptions) UseSSL(v bool) *BackendOptions
UseSSL sets whether or not to require TLS for connections to this backend.
type CacheOptions ¶
type CacheOptions struct { // Pass controls whether or not to force a request to bypass the cache. // By default this is false, which means the request will only reach the // backend if the request is not normally cacheable (such as a POST), or // if a cached response is not available. If pass is set to true, the // request will always be sent directly to the backend. // // Setting Pass to false does not guarantee that a response will be // cached for this request, it only allows a caching attempt to be made. // For example, a `GET` request may appear cacheable, but if the backend // response contains `cache-control: no-store`, the response will not be // cached. // // Pass is mutually exclusive with all other cache options. Setting any // other option will change Pass to false. Pass bool // PCI controls the PCI/HIPAA compliant, non-volatile caching of the // request. PCI is false by default, which means the request may not be // PCI/HIPAA compliant. If PCI is set to true, caching will be made // compliant, and the request will not be forced to bypass the cache. // // https://docs.fastly.com/products/pci-compliant-caching-and-delivery PCI bool // TTL represents a Time-to-Live for cached responses to the request, in // seconds. If greater than zero, it overrides any behavior specified in the // response headers, and the request will not be forced to bypass the cache. TTL uint32 // StaleWhileRevalidate represents a stale-while-revalidate time for the // request, in seconds. If greater than zero, it overrides any behavior // specified in the response headers, and the request will not be forced to // bypass the cache. StaleWhileRevalidate uint32 // SurrogateKey represents an explicit surrogate key for the request, which // will be added to any `Surrogate-Key` response headers received from the // backend. If nonempty, the request will not be forced to bypass the cache. // // https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys SurrogateKey string }
CacheOptions control caching behavior for outgoing requests.
type Cookie ¶
type Cookie struct { Name string Value string Path string // optional Domain string // optional Expires time.Time // optional RawExpires string // for reading cookies only // MaxAge=0 means no 'Max-Age' attribute specified. // MaxAge<0 means delete cookie now, equivalently 'Max-Age: 0' // MaxAge>0 means Max-Age attribute present and given in seconds MaxAge int Secure bool //revive:disable:var-naming HttpOnly bool //revive:enable:var-naming SameSite SameSite Raw string Unparsed []string // Raw text of unparsed attribute-value pairs }
A Cookie represents an HTTP cookie as sent in the Set-Cookie header of an HTTP response or the Cookie header of an HTTP request.
See https://tools.ietf.org/html/rfc6265 for details.
type DecompressResponseOptions ¶
type DecompressResponseOptions struct { // Gzip controls whether a gzip-encoded response to the request will be // automatically decompressed. // // If the response to the request is gzip-encoded, it will be presented in // decompressed form, and the Content-Encoding and Content-Length headers // will be removed. Gzip bool }
DecompressResponseOptions control the auto decompress response behaviour.
type Handler ¶
type Handler interface {
ServeHTTP(ctx context.Context, w ResponseWriter, r *Request)
}
Handler describes anything which can handle, or respond to, an HTTP request. It has the same semantics as net/http.Handler, but operates on the Request and ResponseWriter types defined in this package.
type HandlerFunc ¶
type HandlerFunc func(ctx context.Context, w ResponseWriter, r *Request)
HandlerFunc adapts a function to a Handler.
func (HandlerFunc) ServeHTTP ¶
func (f HandlerFunc) ServeHTTP(ctx context.Context, w ResponseWriter, r *Request)
ServeHTTP implements Handler by calling f(ctx, w, r).
type Header ¶
Header represents the key-value pairs in a set of HTTP headers. Unlike net/http, keys are canonicalized to their lowercase form.
func (Header) Add ¶
Add adds the key, value pair to the headers. It appends to any existing values associated with key. The key is case insensitive; it is canonicalized by CanonicalHeaderKey.
func (Header) Apply ¶
Apply adds all of the headers in hs. In the case of key conflict, values from hs totally overwrite existing values in h.
func (Header) Del ¶
Del deletes the values associated with key. The key is case insensitive; it is canonicalized by CanonicalHeaderKey.
func (Header) Get ¶
Get gets the first value associated with the given key. It is case insensitive; CanonicalHeaderKey is used to canonicalize the provided key. If there are no values associated with the key, Get returns "".
type Limits ¶ added in v0.1.2
type Limits struct {
// contains filtered or unexported fields
}
Limits handles HTTP limits
func (*Limits) MaxHeaderNameLen ¶ added in v0.1.3
MaxHeaderNameLen gets the header name limit
func (*Limits) MaxHeaderValueLen ¶ added in v0.1.3
MaxHeaderValueLen gets the header value limit
func (*Limits) MaxMethodLen ¶ added in v0.1.3
MaxMethodLen gets the request method limit Deprecated: the limit is not enforced, buffer sizing is adaptive.
func (*Limits) MaxURLLen ¶ added in v0.1.3
MaxURLLen gets the request URL limit Deprecated: the limit is not enforced, buffer sizing is adaptive.
func (*Limits) SetMaxHeaderNameLen ¶ added in v0.1.3
SetMaxHeaderNameLen sets the header name limit
func (*Limits) SetMaxHeaderValueLen ¶ added in v0.1.3
SetMaxHeaderValueLen sets the header value limit
func (*Limits) SetMaxMethodLen ¶ added in v0.1.3
SetMaxMethodLen sets the request method limit Deprecated: the limit is not reset, buffer sizing is adaptive.
func (*Limits) SetMaxURLLen ¶ added in v0.1.3
SetMaxURLLen sets the request URL limit Deprecated: the limit is not reset, buffer sizing is adaptive.
type Request ¶
type Request struct { // Method specifies the HTTP method: GET, POST, PUT, HEAD, etc. Method string // URL is the parsed and validated URL of the request. // // Outgoing requests are always sent to the preconfigured backend provided // to the send method. The URL is used for the request resource, Host // header, etc. URL *url.URL // Proto contains the HTTP protocol version used for incoming requests. // // These fields are ignored for outgoing requests. Proto string // "HTTP/1.0" ProtoMajor int // 1 ProtoMinor int // 0 // Header contains the request header fields either received in the // incoming request, or to be sent with the outgoing request. Header Header // CacheOptions control caching behavior for outgoing requests. CacheOptions CacheOptions // Body is the request's body. // // For the incoming client request, the body will always be non-nil, but // reads may return immediately with EOF. For outgoing requests, the body is // optional. A body may only be read once. // // Prefer using the SetBody method over assigning to this value directly, // as it enables optimizations when sending outgoing requests. See the // SetBody documentation for more information. Body io.ReadCloser // Host is the hostname parsed from the incoming request URL. Host string // RemoteAddr contains the IP address of the requesting client. // // This field is ignored for outgoing requests. RemoteAddr string // ServerAddr contains the IP address of the server that received the // HTTP request. // // This field is ignored for outgoing requests. ServerAddr string // TLSInfo collects TLS metadata for incoming requests received over HTTPS. TLSInfo TLSInfo // SendPollInterval determines how often the Send method will check for // completed requests. While polling, the Go runtime is suspended, and all // user code stops execution. A shorter interval will make Send more // responsive, but provide less CPU time to user code. A longer poll // interval will make Send less responsive, but provide more CPU time to // user code. // // If SendPollInterval is zero, a default value of 1ms is used. The minimum // value is 1ms, and the maximum value is 1s. SendPollInterval time.Duration // DecompressResponseOptions control the auto decompress response behaviour. DecompressResponseOptions DecompressResponseOptions // ManualFramingMode controls how the framing headers // (Content-Length/Transfer-Encoding) are set for a request. // // If ManualFramingMode is true, the request uses the exact framing headers // set in the message. If ManualFramingMode is false, or ManualFramingMode // is true and the framing is invalid, the framing headers are based on the // message body, and any framing headers already set in the message are // discarded. ManualFramingMode bool // contains filtered or unexported fields }
Request represents an HTTP request received by this server from a requesting client, or to be sent from this server during this execution. Some fields only have meaning in one context or the other.
func NewRequest ¶
NewRequest constructs an outgoing request with the given HTTP method, URI, and body. The URI is parsed via url.Parse.
func RequestFromContext ¶ added in v0.1.2
RequestFromContext returns the fsthttp.Request associated with the context, if any.
func (*Request) AddCookie ¶
AddCookie adds a cookie to the request. Per RFC 6265 section 5.4, AddCookie does not attach more than one Cookie header field. That means all cookies, if any, are written into the same line, separated by semicolon. AddCookie only sanitizes c's name and value, and does not sanitize a Cookie header already present in the request.
func (*Request) Clone ¶
Clone returns a copy of the request. The returned copy will have a nil Body field, and its URL will have a nil User field.
func (*Request) CloneWithBody ¶ added in v1.3.1
CloneWithBody returns a copy of the request, with the Body field set to the provided io.Reader. Its URL will have a nil User field.
func (*Request) Cookie ¶
Cookie returns the named cookie provided in the request or ErrNoCookie if not found. If multiple cookies match the given name, only one cookie will be returned.
func (*Request) Send ¶
Send the request to the named backend. Requests may only be sent to backends that have been preconfigured in your service, regardless of their URL. Once sent, a request cannot be sent again.
By default, read-through caching is enabled for requests. The HTTP response received from the backend will be cached and reused for subsequent requests if it meets cacheability requirements. The behavior of this automatic caching can be tuned (or disabled) via the Request's CacheOptions field. This function provides the full benefits of Fastly's purging, request collapsing, and revalidation capabilities, and is recommended for most users who need to cache HTTP responses.
func (*Request) SetBody ¶ added in v1.3.1
SetBody sets the Request's body to the provided io.Reader. Prefer using this method over setting the Body field directly, as it enables optimizations in the runtime.
If an unread body from an incoming client request is set on an outgoing upstream request, the body will be efficiently streamed from the incoming request. It is also possible to set the unread body of a received response to the body of a request, with the same results.
If the body is set from an in-memory reader such as bytes.Buffer, bytes.Reader, or strings.Reader, the runtime will send the request with a Content-Length header instead of Transfer-Encoding: chunked.
type Response ¶
type Response struct { // Request associated with the response. Request *Request // Backend that served the response. Backend string // StatusCode of the response. StatusCode int // Header received with the response. Header Header // Body of the response. Body io.ReadCloser // contains filtered or unexported fields }
Response to an outgoing HTTP request made by this server.
func ResponseFromContext ¶ added in v0.1.2
ResponseFromContext returns the fsthttp.Response associated with the context, if any.
type ResponseWriter ¶
type ResponseWriter interface { // Header returns the headers that will be sent by WriteHeader. // Changing the returned headers after a call to WriteHeader has no effect. Header() Header // WriteHeader initiates the response to the client by sending an HTTP // response preamble with the provided status code, and all of the response // headers collected by Header. If WriteHeader is not called explicitly, // the first call to Write or Close will trigger an implicit call to // WriteHeader with a code of 200. After the first call to WriteHeader, // subsequent calls have no effect. WriteHeader(code int) // Write the data to the connection as part of an HTTP reply. // // If WriteHeader has not yet been called, Write calls WriteHeader(200) // before writing the data. Unlike the ResponseWriter in net/http, Write // will not automatically add Content-Type or Content-Length headers. Write(p []byte) (int, error) // Close the response to the client. Close must be called to ensure the // response has been fully written to the client. // // If WriteHeader has not yet been called, Close calls WriteHeader(200) // before closing the response. Once closed, a ResponseWriter is // invalidated, and may no longer be accessed or used in any way. Close() error // SetManualFramingMode controls how the framing headers // (Content-Length/Transfer-Encoding) are set for a response. // // If set to true, the response uses the exact framing headers // set in the message. If set to false, or set to true and // the framing is invalid, the framing headers are based on the // message body, and any framing headers already set in the message are // discarded. // // To have an effect on the response, this must be called before any call to Write() or WriteHeader(). SetManualFramingMode(bool) // Append a body onto the end of this response. Will fail if passed anything other than a Response's Body field. // This operation is performed in amortized constant time, and so should always be preferred to directly copying a body with io.Copy. Append(other io.ReadCloser) error }
ResponseWriter is used to respond to client requests.
func ResponseWriterFromContext ¶ added in v0.1.2
func ResponseWriterFromContext(ctx context.Context) ResponseWriter
ResponseWriterFromContext returns the fsthttp.ResponseWriter associated with the context, if any.
type SameSite ¶
type SameSite int
SameSite allows a server to define a cookie attribute making it impossible for the browser to send this cookie along with cross-site requests. The main goal is to mitigate the risk of cross-origin information leakage, and provide some protection against cross-site request forgery attacks.
See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 for details.
type TLSInfo ¶
type TLSInfo struct { // Protocol contains the TLS protocol version used to secure the client TLS // connection, if any. Protocol string // ClientHello contains raw bytes sent by the client in the TLS ClientHello // message. See RFC 5246 for details. ClientHello []byte // CipherOpenSSLName contains the cipher suite used to secure the client TLS // connection. The value returned will be consistent with the OpenSSL name // for the cipher suite. CipherOpenSSLName string }
TLSInfo collects TLS-related metadata for incoming requests. All fields are ignored for outgoing requests.
type TLSVersion ¶ added in v0.1.5
type TLSVersion uint32
const ( TLSVersion1_0 TLSVersion = 0 TLSVersion1_1 TLSVersion = 1 TLSVersion1_2 TLSVersion = 2 TLSVersion1_3 TLSVersion = 3 )
Constants for dynamic backend TLS configuration
type Transport ¶ added in v0.1.2
type Transport struct { // Request is an optional callback invoked before the request is // sent to the backend. It allows callers to set // fsthttp.Request-specific fields, such as cache control options. Request func(req *Request) error // contains filtered or unexported fields }
Transport is an http.RoundTripper implementation for backend requests on Compute.
Compute requests must be made to a pre-configured named backend. Transport provides a mechanism for mapping hostnames to backend names. A default catchall backend is set when the Transport is created, but additional host-to-backend mappings can be added with the AddHostBackend method.
Transport is provided primarily to adapt existing code which uses http.Client instances to work on Compute. Using an http.Client pulls in substantially more code, resulting in slower compile times and larger binaries. For this reason, we recommend new code use the fsthttp.Request type and its Send() method directly whenever possible.
func NewTransport ¶ added in v0.1.2
NewTransport creates a new Transport instance with the given default backend. Any request made to a host not explicitly mapped to a backend using the AddHostBackend method will be sent to the default backend.
func (*Transport) AddHostBackend ¶ added in v0.1.2
AddHostBackend adds a new host-to-backend mapping. Multiple hosts may be mapped to the same backend.
func (*Transport) RoundTrip ¶ added in v0.1.2
RoundTrip implements the http.RoundTripper interface.
The provided http.Request is adapted into an fsthttp.Request. If the Transport's Request callback field is set, it is invoked so that the fsthttp.Request can be modified before it is sent. The request is then sent to the backend matching the host in the URL. The resulting fsthttp.Response is adapted into an http.Response and returned.
The http.Response's Request field contains a context from which the original fsthttp.Request and fsthttp.Response can be extracted using fsthttp.RequestFromContext and fsthttp.ResponseFromContext.