restful

package module
v1.17.6 Latest Latest
Warning

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

 Go to latest Published: Feb 17, 2026 License: BSD-3-Clause Imports: 39 Imported by: 0

README

RESTful

Quick introduction

This Go package is a powerful extension of standard Go HTTP server and client libraries. It lets you handle HTTP+JSON without any extra code.

Reference.

Lambda server

You receive and respond with data structures.

type reqData struct {
    Num int `json:"num" validate:"lt=1000000"`
}

type respData struct {
    Number int `json:"number"`
}

func create(ctx context.Context, req *reqData) (*respData, error) {
    // You use data structures directly, without marshalling and unmarshalling.
    resp := respData{Number: req.Num}
    return &resp, nil
}

func main() {
    restful.HandleFunc("/user/v1", create).Methods(http.MethodPost)
    restful.Start()
}
RESTful client

You send and receive data structures.

location, err := restful.Post(ctx, "https://example.com", &reqData, &respData)

Details

  • Lambda server Focus on business logic. It is a modern variant of an HTTP server.
  • RESTful server An underlying HTTP server of Lambda. An HTTP server with goodies. Besides helper functions for receiving and sending JSON data, it can do logging. Router is based on Gorilla/Mux, offering similar services.
  • RESTful client Sending GET, POST (and receiving Location), PUT, PATCH or DELETE requests and receiving their responses. And numerous other helper functions.
  • Tracing Information is propagated in context, received in Lambda, and used in client requests. That is all done without any extra coding on your side. Based on OpenTelemetry.
  • Monitor is a convenient middleware solution to pre-process requests and post-process responses. Pre and post hooks can be used for whatever you want, such as adding Prometheus counters on the router level, without littering your business logic.
  • Error is a Go error object containing an HTTP status code besides the traditional error.

Trace context and error are used both at Lambda Server and Client. These use similar middleware solution called Monitor. That is why, unlike many other Go HTTP router packages, they form a module together.

Principles

  • Simple, intuitive, Go-ish.
  • Similar to Go's built-in http package, with some advanced router inherited from Gorilla/Mux project.
  • Powerful HTTP+JSON framework reducing development costs while improving quality.
  • Has quite many goodies needed for developing complex applications.

Documentation

Index

Constants

View Source 
const (
	KindBasic = ""
	KindH2    = "h2"
	KindH2C   = "h2c"
)

Kind is a string representation of what kind the client is. Depending on which New() function is called.

View Source 
const (
	AcceptHeader               = "Accept"
	ContentTypeHeader          = "Content-type"
	ContentTypeAny             = "*/*"
	ContentTypeApplicationAny  = "application/*"
	ContentTypeApplicationJSON = "application/json"
	ContentTypeProblemJSON     = "application/problem+json"     // RFC 7807
	ContentTypePatchJSON       = "application/json-patch+json"  // RFC 6902
	ContentTypeMergeJSON       = "application/merge-patch+json" // RFC 7386
	ContentTypeForm            = "application/x-www-form-urlencoded"
	ContentTypeMsgPack         = "application/msgpack"
	ContentTypeMultipartForm   = "multipart/form-data"
)

ContentType strings

View Source 
const ErrorBodyMaxLen = 4096

ErrorBodyMaxLen is the maximum length of the body that is stored to the error object in case of an 4xx or 5xx response.

Variables

View Source 
var (
	// ErrRevocationListReadError is when error happen during reading of revocation list
	ErrRevocationListReadError = errors.New("error reading revocation list")
	// ErrRevocationListOutOfDate is when the revocation list is out of date
	ErrRevocationListOutOfDate = errors.New("revocation list out of date")
	// ErrCertificateRevoked happens when the certificate revoked
	ErrCertificateRevoked = errors.New("certificate revoked")
)
View Source 
var (
	// ErrNonHTTPSURL means that using non-https URL not allowed.
	ErrNonHTTPSURL = errors.New("non-https URL not allowed")

	// ErrUnexpectedContentType is returned if content-type is unexpected.
	// It may be wrapped, so use errors.Is() for checking.
	ErrUnexpectedContentType = errors.New("unexpected Content-Type")
)
View Source 
var (
	// OwnTLSCert is the own TLS certificate used by server on StartTLS. Default is "/etc/own-tls/tls.crt".
	OwnTLSCert string = "/etc/own-tls/tls.crt"

	// OwnTLSKey is the own TLS private key used by servert on StartTLS. Default is "/etc/own-tls/tls.key".
	OwnTLSKey string = "/etc/own-tls/tls.key"

	// ClientCAs is a path of client certificate authorities, to be verified by the server on StartTLS on mTLS. Default is "/etc/clientcas".
	ClientCAs string = "/etc/clientcas"

	// AddrHTTP is the listening address / port of HTTP for Start / StartTLS. Default is ":8080"
	AddrHTTP = ":8080"

	// AddrHTTPS is the listening address / port of HTTPS for StartTLS. Default is ":8443"
	AddrHTTPS = ":8443"
)
View Source 
var (
	// HealthCheckPath is the path of health checking.
	// Handled automatically, 200 OK sent.
	// Similar to liveness endpoint, but sends `Connection: close` header as an extra in the response,
	// so that each invocation to check listening/accepting new connections.
	// Ignored at logging. By default "/healthz".
	HealthCheckPath = "/healthz"

	// LivenessProbePath is the path of liveness probes.
	// Handled automatically, 200 OK sent.
	// Ignored at logging. By default "/livez".
	LivenessProbePath = "/livez"

	// ReadinessProbePath is the path of readiess probes.
	// Not handled automatically. But a custom endpoint is needed.
	// Ignored at logging. By default "/readyz".
	ReadinessProbePath = "/readyz"
)
View Source 
var DefaultServeMux = NewRouter()

DefaultServeMux is the default HTTP mux served.

View Source 
var DefaultTokenClient *http.Client = &http.Client{Timeout: 10 * time.Second}

DefaultTokenClient is an http.Client used to obtain OAuth2 token. If not set, a default client is used with 10s timeout. The reason for having a separate client is that Authorization Server and Resource Server may support different transport.

View Source 
var DialTimeout = 2 * time.Second

DialTimeout defines the default timeout for dialing connections.

View Source 
var (
	// DisallowUnknownFields is a global setting for JSON decoder.
	// It tells if unknown fields to be ignored silently (false) or to make decoding fail (true).
	// By default unknown fields are ignored.
	// See also JSON schema and OpenAPI Specification `additionalProperties: false`.
	DisallowUnknownFields = false
)
View Source 
var LambdaMaxBytesToParse = 0

LambdaMaxBytesToParse defines the maximum length of the request content allowed to be parsed. If zero then no limits imposed.

View Source 
var LambdaSanitizeJSON = false

LambdaSanitizeJSON defines whether to sanitize JSON of Lambda return or SendResp. See SanitizeJSONString for details. Deprecated.

View Source 
var LambdaValidationErrorStatus = http.StatusUnprocessableEntity

LambdaValidationErrorStatus is the HTTP status code to return on message validation error. Default is 422 Unprocessable Entity, similarly to Python FastAPI/Pydantic. If you prefer 400 Bad Request, then change this.

View Source 
var LambdaValidator = true

LambdaValidator tells if incoming request is to be validated. Validation is done by https://github.com/go-playground/validator. See its documentation for details.

View Source 
var ReadErrConverter func(err error) error

ReadErrConverter is a function variable similar to ValidateErrConverter that allows customization of errors returned when the request body is read and Unmarhsaled

View Source 
var ServerReadHeaderTimeout = 5 * time.Second

ServerReadHeaderTimeout is the amount of time allowed to read request headers.

View Source 
var ServerReadTimeout = 60 * time.Second

ServerReadTimeout is the amount of time allowed to read request body. Default 60s is quite liberal.

View Source 
var Validate *validator.Validate = validator.New(validator.WithRequiredStructEnabled())

Validate is a singleton global object that performs Lambda server request validation of structs with fields with `validate` tagging. Validation is done by https://github.com/go-playground/validator. You can rely on the default value, unless you use custom validators.

View Source 
var ValidateErrConverter func(err error) error

ValidateErrConverter is a function variable that allows customization of error returned by validator. You can provide your own function here. This can be used if some standardized formatting is desired.

Functions

func AddLambdaToContext added in v1.9.0 

func AddLambdaToContext(ctx context.Context, l *lambda.Lambda) context.Context

AddLambdaToContext returns the context extended with value of the Lambda. Useful if a new goroutine is created with new context, but it is related to the original Context.

func BaseContentType 

func BaseContentType(contentType string) string

BaseContentType returns the MIME type of the Content-Type header as lower-case string E.g.: "application/JSON; charset=ISO-8859-1" --> "application/json"

func Delete 

func Delete(ctx context.Context, target string) error

Delete deletes a resource.

func DetailError 

func DetailError(err error, description string) error

DetailError adds further description to the error. Useful when cascading return values. Can be used on any error, though it is mostly used on errors created by restful.NewError() / NewDetailedError() E.g. restful.DetailError(err, "db query failed")

func Get 

func Get(ctx context.Context, target string, respData any) error

Get gets a resource.

func GetBaseContentType 

func GetBaseContentType(headers http.Header) string

GetBaseContentType returns base content type from HTTP header. E.g.: "Content-Type: application/JSON; charset=ISO-8859-1" --> "application/json"

func GetDataBytes 

func GetDataBytes(headers http.Header, ioBody io.ReadCloser, maxBytes int) (body []byte, err error)

GetDataBytes returns []byte received. If maxBytes > 0 then larger body is dropped.

func GetDataBytesForContentType 

func GetDataBytesForContentType(headers http.Header, ioBody io.ReadCloser, maxBytes int, expectedContentType string) (body []byte, err error)

GetDataBytesForContentType returns []byte received, if Content-Type is matching or empty string. If no content then Content-Type is not checked. If maxBytes > 0 then larger body is dropped.

func GetErrBody added in v1.7.6 

func GetErrBody(err error) (string, []byte)

GetErrBody returns the content-type and raw body stored within the given error. Note that the body may be chopped if too long. See ErrorBodyMaxLen. 

err := restful.Get()
contentType, Body := restful.GetErrBody(err)
if body != nil {fmt.Print(string(body))}

func GetErrStatusCode 

func GetErrStatusCode(err error) int

GetErrStatusCode determines the HTTP status code associated with a given error. If err is nil then http.StatusOK returned. If no HTTP status is found, then http.StatusInternalServerError (500) is returned.

func GetErrStatusCodeElse 

func GetErrStatusCodeElse(err error, elseStatusCode int) int

GetErrStatusCodeElse returns the HTTP status code associated with the given error. If no HTTP status code found in the error, then returns the one the caller provided. For example, in case of a transport error no HTTP status code is received. If the error is nil, it returns http.StatusOK.

func GetRequestData 

func GetRequestData(req *http.Request, maxBytes int, data any) error

GetRequestData returns request data from HTTP request. Data source depends on Content-Type (CT). JSON, form data or in case of GET w/o CT query parameters are used. If maxBytes > 0 it blocks parsing exceedingly huge data, which could be used for DoS or memory overflow attacks. If error is returned then suggested HTTP status may be encapsulated in it, available via GetErrStatusCode.

func GetResponseData 

func GetResponseData(resp *http.Response, maxBytes int, data any) error

GetResponseData returns response data from JSON body of HTTP response. If maxBytes > 0 it blocks parsing exceedingly huge JSON data, which could be used for DoS or memory overflow attacks.

func IsConnectError 

func IsConnectError(err error) bool

IsConnectError determines if the given error corresponds to a connection-related issue. I.e. non-nil, does not contain HTTP status code, or the status code is 502 / 503 / 504.

func L 

func L(ctx context.Context) *lambda.Lambda

L returns lambda-related data from context.

func LambdaWrap 

func LambdaWrap(f any) http.HandlerFunc

LambdaWrap wraps a Lambda function and makes it a http.HandlerFunc. This function is rarely needed, as restful's Router wraps handler functions automatically. You might need it if you want to wrap a standard http.HandlerFunc.

func ListenAndServe 

func ListenAndServe(addr string, handler http.Handler) error

ListenAndServe acts like standard http.ListenAndServe(). Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func ListenAndServeMTLS 

func ListenAndServeMTLS(addr, certFile, keyFile, clientCerts string, loadSystemCerts bool, handler http.Handler) error

ListenAndServeMTLS acts like standard http.ListenAndServeTLS(). Just authenticates client. Parameter clientCerts is a PEM cert file or a directory of PEM cert files case insensitively matching *.pem or *.crt. If loadSystemCerts is true, clients with CA from system CA pool are accepted, too. As the role of mTLS is to authorize certain clients to connect, enable system CAs only if those are reasonable for auth. Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func ListenAndServeTLS 

func ListenAndServeTLS(addr, certFile, keyFile string, handler http.Handler) error

ListenAndServeTLS acts like standard http.ListenAndServeTLS(). Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func Logger 

func Logger(h http.Handler) http.Handler

Logger wraps original handler and returns a handler that logs requests and responses separately when they happen. Logs contain the received or generated semi-random trace IDs to be able to correlate requests and responses.

  • If path matches LivenessProbePath or HealthCheckPath then it does not log anything and responds with 200 OK without any further processing.
  • If path matches ReadinessProbePath then it does not log anything, but the request is processed, as usual.

func Monitor 

func Monitor(h http.Handler, pre MonitorFuncPre, post MonitorFuncPost) http.Handler

Monitor wraps handler function, creating a middleware in a safe and convenient fashion. It adds pre and post functions to be called on serving a request. You may prefer Server's or Router's Monitor functions.

func NewCertPool 

func NewCertPool(path string, loadSystemCerts bool) *x509.CertPool

NewCertPool adds PEM certificates from given path in a way that is usable at TLS() as RootCAs. If path is a directory then scans for files recursively. If path is not set then defaults to /etc. If loadSystemCerts is true, the given client certificates are complemented with system root certificates. File name should match *.crt or *.pem.

func NewDetailedError added in v1.2.0 

func NewDetailedError(err error, status int, pd ProblemDetails) error

NewDetailedError creates a new error with specified problem details JSON structure (RFC7807)

func NewError 

func NewError(err error, statusCode int, description ...string) error

NewError creates a new error that contains HTTP status code. Coupling HTTP status code to error makes functions return values clean. And controls what Lambda sends on errors. 

if err != nil {return restful.NewError(err, http.StatusBadRequest)}

Parameter description is optional, caller may provide extra description, appearing at the beginning of the error string. 

if err != nil {return restful.NewError(err, http.StatusBadRequest, "bad data")}

Parameter err may be nil, if there is no error to wrap or original error text is better not be propagated. 

if err != nil {return restful.NewError(nil, http.StatusBadRequest, "bad data")}

func NewErrorWithBody added in v1.11.1 

func NewErrorWithBody(err error, statusCode int, contentType string, body []byte) error

NewErrorWithBody creates new error with custom HTTP status code, content-type and payload body.

func NewRequestCtx 

func NewRequestCtx(w http.ResponseWriter, r *http.Request) context.Context

NewRequestCtx adds request related data to r.Context(). You may use this at traditional http handler functions, and that is what happens at Lambda functions automatically. Returns new derived context. That can be used at client functions, silently propagating tracing headers.

E.g. ctx := NewRequestCtx(w, r)

func NewTestCtx 

func NewTestCtx(method string, rawurl string, header http.Header, vars map[string]string) context.Context

NewTestCtx helps creating tests. Caller can define headers and path variables.

func Patch 

func Patch(ctx context.Context, target string, reqData, respData any) error

Patch partially updates a resource.

func PingList 

func PingList(ctx context.Context, targets []string) error

PingList sends a HTTP GET requests to a list of URLs and expects 2xx responses for each. This way one can check liveness components.

func Post 

func Post(ctx context.Context, target string, reqData, respData any) (*url.URL, error)

Post sends a POST request. Primarily designed to create a resource and return its Location. That may be nil.

func Put 

func Put(ctx context.Context, target string, reqData, respData any) (*url.URL, error)

Put updates a resource. Might return Location of created resource, otherwise nil.

func SanitizeJSONBytes 

func SanitizeJSONBytes(b []byte) []byte

SanitizeJSONBytes clears empty entries from byte array of JSON. Deprecated.

func SanitizeJSONString 

func SanitizeJSONString(s string) string

SanitizeJSONString clears empty entries from string of JSON. Note that normally one should use "omitempty" in structures, and use pointers for arrays and structs. So sanitizing is not really needed. Deprecated.

func SendEmptyResponse 

func SendEmptyResponse(w http.ResponseWriter, statusCode int)

SendEmptyResponse sends an empty HTTP response. Caller may set additional headers like `w.Header().Set("Location", "https://me")` before calling this function.

func SendJSONResponse 

func SendJSONResponse(w http.ResponseWriter, statusCode int, data any, sanitizeJSON bool) (err error)

SendJSONResponse sends an HTTP response with an optionally sanitized JSON data. Caller may set additional headers like `w.Header().Set("Location", "https://me")` before calling this function.

func SendLocationResponse 

func SendLocationResponse(w http.ResponseWriter, location string)

SendLocationResponse sends an empty "201 Created" HTTP response with Location header.

func SendProblemDetails added in v1.2.0 

func SendProblemDetails(w http.ResponseWriter, r *http.Request, err error) error

SendProblemDetails adds detailed problem description to JSON body, if available. See RFC 7807.

func SendProblemResponse 

func SendProblemResponse(w http.ResponseWriter, r *http.Request, statusCode int, problem string) (err error)

SendProblemResponse sends response with problem text, and extends it to problem+json format if it is a plain string.

func SendResp 

func SendResp(w http.ResponseWriter, r *http.Request, err error, data any) error

SendResp sends an HTTP response with data. On no error 200/201/204 sent according to the request. On error send response depending on whether the error is created by NewError and the client supports RFC 7807. Caller may set additional headers like `w.Header().Set("Location", "https://me")` before calling this function.

func SendResponse 

func SendResponse(w http.ResponseWriter, statusCode int, data any) error

SendResponse sends an HTTP response with a JSON data. Caller may set additional headers like `w.Header().Set("Location", "https://me")` before calling this function.

func SetOTel added in v1.7.0 

func SetOTel(enabled bool, tp *sdktrace.TracerProvider)

SetOTel enables/disables Open Telemetry. By default it is disabled. Trace provider can be set, when enabling.

func SetOTelGrpc added in v1.7.3 

func SetOTelGrpc(target string, fraction float64) error

SetOTelGrpc enables Open Telemetry. Activates trace export to the OTLP gRPC collector target address defined. Port is 4317, unless defined otherwise in provided target string.

Fraction tells the fraction of spans to report, unless the parent is sampled.

  • Zero means no sampling.
  • Greater or equal 1 means sampling all the messages.
  • Else the sampling fraction, e.g. 0.01 for 1%.

func SetServerName added in v1.6.0 

func SetServerName(s string)

SetServerName allows settings a server name. That can be used at span name formatting.

func SetTrace added in v1.5.10 

func SetTrace(b bool)

SetTrace can enable/disable HTTP tracing. By default trace header generation and propagation is enabled.

func Start 

func Start() error

Start starts serving on port 8080 (AddrHTTP). Logs, except for automatically served LivenessProbePath and HealthCheckPath. Handles connections gracefully on TERM/INT signals.

func StartTLS 

func StartTLS(cleartext, mutualTLS bool, loadSystemCerts bool) error

StartTLS starts serving for TLS on port 8443 (AddrHTTPS) and for cleartext on port 8080 (AddrHTTP), if allowed. TLS cert must be at OwnTLSCert and key at OwnTLSKey. If mutualTLS=true, then client certs must be provided; see variable ClientCAs. If loadSystemCerts is true, clients with CA from system CA pool are accepted, too. As the role of mTLS is to authorize certain clients to connect, enable system CAs only if those are reasonable for auth. Logs, except for automatically served LivenessProbePath and HealthCheckPath. Handles connections gracefully on TERM/INT signals.

Types

type CRLOptions added in v1.17.0 

type CRLOptions struct {
	// Ctx is a cancelable background context used for the regular CRL reading
	Ctx context.Context

	// CRLLocation is the file name or comma-separated HTTP distribution point URI list where the revocation list shall be from
	CRLLocation string

	// ReadInterval is the time interval the CRL information is retrieved from the distribution list or re-read from the file
	ReadInterval time.Duration

	// FileExistTimeout allows for the CRL file to not exist for an initial duration of time without reporting an error
	FileExistTimeout time.Duration

	// StatusChan is a channel where the CRL status can be provided.
	// Every ReadInterval, an error is sent on the channel if getting the CRL is not successful or if the NextUpdate in the
	// latest CRL is in the past, or nil is sent in case of no error.
	StatusChan chan (error)

	// StrictValityCheck enables strict NextUpdate checking.
	// With this enabled, peer certificate checks will fail if the latest CRL file is outdated
	StrictValityCheck bool
}

CRLOptions defines the settings restful clients/servers can use for CRL verification

type Client 

type Client struct {
	// Client is the http.Client instance used by restful.Client.
	// Do not touch it, unless really necessary.
	Client *http.Client

	// Kind is a string representation of what kind the client is. Depending on which New() function is called.
	// Changing its value does not change client kind.
	Kind string

	// LoadBalanceRandom is a flag that tells whether to choose random IP address from the list of IPs received in DNS response for the target URI.
	LoadBalanceRandom bool
	// contains filtered or unexported fields
}

Client is an instance of RESTful client.

func NewClient 

func NewClient() *Client

NewClient creates a RESTful client instance. The instance has a semi-permanent transport TCP connection.

func NewClientWInterface added in v1.9.0 

func NewClientWInterface(networkInterface string) *Client

NewClientWInterface creates a RESTful client instance bound to that network interface. The instance has a semi-permanent transport TCP connection.

func NewH2CClient 

func NewH2CClient() *Client

NewH2CClient creates a RESTful client instance, forced to use HTTP2 Cleartext (H2C).

func NewH2CClientWInterface added in v1.11.6 

func NewH2CClientWInterface(networkInterface string) *Client

NewH2CClientWInterface creates a RESTful client instance with the http2 clear text protocol bound to that network interface. In other words, the http2 clear text is the http2 but without TLS handshake. The instance has a semi-permanent transport TCP connection.

func NewH2Client 

func NewH2Client() *Client

NewH2Client creates a RESTful client instance, forced to use HTTP2 with TLS (H2) (a.k.a. prior knowledge).

func NewH2ClientWInterface added in v1.11.6 

func NewH2ClientWInterface(networkInterface string) *Client

NewH2ClientWInterface creates a RESTful client instance with the http2 protocol bound to that network interface. The instance has a semi-permanent transport TCP connection.

func (*Client) AcceptProblemJSON added in v1.3.2 

func (c *Client) AcceptProblemJSON(acceptProblemJSON bool) *Client

AcceptProblemJSON sets whether client is to send "Accept: application/problem+json" header. I.e. tells the server whether your client wants RFC 7807 answers.

func (*Client) BroadcastRequest 

func (c *Client) BroadcastRequest(ctx context.Context, method string, target string, headers http.Header, reqData any) error

BroadcastRequest sends a HTTP request with JSON data to all of the IP addresses received in the DNS response for the target URI and expects 2xx responses, returning error in any other case. This is meant for sending notifications to headless kubernetes services. Response data is not returned or saved.

func (*Client) CRL added in v1.17.0 

func (c *Client) CRL(o CRLOptions) *Client

CRL sets up Certificate Revocation List watching for the Client. CRL cert is read from *path*, re-read every *readInterval* and has to exist until *fileExistTimeout*. Errors are delivered through *errChan*

func (*Client) CheckRedirect added in v1.3.6 

func (c *Client) CheckRedirect(checkRedirect func(req *http.Request, via []*http.Request) error) *Client

CheckRedirect set client CheckRedirect field CheckRedirect specifies the policy for handling redirects.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, target string) error

Delete deletes a resource.

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and returns an HTTP response. All the rules of http.Client.Do() apply. If URL of req is relative path then root defined at client.Root is added as prefix. If request context contains tracing headers then adds them to the request with a new span ID.

func (*Client) EnableLoadBalanceRandom added in v1.16.0 

func (c *Client) EnableLoadBalanceRandom(enable bool) *Client

EnableLoadBalanceRandom enables or disables load balancing by random IP address. If enabled, the client will resolve the hostname and choose a random IP address from the list

func (*Client) Get 

func (c *Client) Get(ctx context.Context, target string, respData any) error

Get gets a resource.

func (*Client) GetTransport added in v1.17.3 

func (c *Client) GetTransport() http.RoundTripper

GetTransport returns the client's underlying transport. It is not the same as reading client.Client.Transport, as that may be wrapped by OTEL, while this function returns the actual transport used.

func (*Client) HTTPS added in v1.7.4 

func (c *Client) HTTPS(config *HTTPSConfig) *Client

HTTPS lets you set what kind of URLs are allowed to be used. If HTTPS is not called, there are no restrictions applied. If HTTPS is called with nil config, then cleartext HTTP is not allowed. 

cLocal := restful.NewClient().Root(peerURL).HTTPS(restful.HTTPSConfig{AllowLocalhostHTTP: true})
cTest := restful.NewClient().Root(peerURL).HTTPS(restful.HTTPSConfig{AllowedHTTPHosts: []string{"test"}})

func (*Client) Head 

func (c *Client) Head(ctx context.Context, target string) (map[string][]string, error)

Head checks a resource. Returns headers map.

func (*Client) Insecure 

func (c *Client) Insecure() *Client

Insecure makes client skip server name checking.

func (*Client) Jar added in v1.3.5 

func (c *Client) Jar() http.CookieJar

Jar gets cookie jar of the client.

func (*Client) Monitor added in v1.5.0 

func (c *Client) Monitor(pre ClientMonitorFuncPre, post ClientMonitorFuncPost) *Client

Monitor adds middleware to the client. Functions to call before sending a request (pre), and after receiving the response (post).

func (*Client) MsgPack added in v1.8.1 

func (c *Client) MsgPack(allowed bool) *Client

MsgPack enables/disables msgpack usage instead of JSON content. If enabled, the first request is still using JSON, but indicates msgpack support in Accept header. If the response content-type is msgpack, then the client encodes further requests using msgpack. Restful Lambda server responds with msgpack if Accept header indicates its support automatically. This is an EXPERIMENTAL feature. Detailed at https://github.com/nokia/restful/issues/30

Deprecated. This feature will be dropped in the near-future.

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, target string, reqData, respData any) error

Patch partially updates a resource. Supports RFCs 6902 and 7386 only. Automatically chooses Content-Type header depending on the content itself.

WARNING: The chosen Content-Type header may not be what caller needs. One may prefer SendRecv2xx instead.

func (*Client) PingList 

func (c *Client) PingList(ctx context.Context, targets []string) error

PingList sends a HTTP GET requests to a list of URLs and expects 2xx responses for each. This way one can check liveness components.

func (*Client) Post 

func (c *Client) Post(ctx context.Context, target string, reqData, respData any) (*url.URL, error)

Post sends a POST request. Primarily designed to create a resource and return its Location. That may be nil.

func (*Client) PostForm 

func (c *Client) PostForm(ctx context.Context, target string, reqData url.Values, respData any) (*url.URL, error)

PostForm posts data as "application/x-www-form-urlencoded", expects response as "application/json", if any. Returns Location URL, if received.

func (*Client) PostFormWithFullResponse added in v1.13.0 

func (c *Client) PostFormWithFullResponse(ctx context.Context, target string, reqData url.Values, cookies []*http.Cookie, headers *http.Header) (*http.Response, error)

PostFormWithFullResponse posts data as "application/x-www-form-urlencoded". Returns the full response.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, target string, reqData, respData any) (*url.URL, error)

Put updates a resource. Might return Location of created resource, otherwise nil.

func (*Client) Retry 

func (c *Client) Retry(retries int, backoffInit time.Duration, backoffMax time.Duration) *Client

Retry sets the number of times and backoff sleep a client retransmits the request if connection failed or gateway returned errors 502, 503 or 504.

Truncated binary exponential backoff is done. I.e. sleep = 2^r * backoffInit, where r is the number of retries-1, capped at backoffMax. If backoffMax < backoffInit, e.g. 0, then set to 2^7*backoffInit.

Don't set retries or backoff too high. You may use it this way: client := New().Retry(3, 500 * time.Millisecond, 2 * time.Second) or just client.Retry(3, 1 * time.Second, 0)

func (*Client) Root 

func (c *Client) Root(rootURL string) *Client

Root sets default root URL for client. Returns object instance, just in case you need that. You may use it this way: client := New().Root(...) or just client.Root(...)

func (*Client) SanitizeJSON 

func (c *Client) SanitizeJSON() *Client

SanitizeJSON enables JSON sanitization. See details at SanitizeJSONString. Deprecated.

func (*Client) SendRecv 

func (c *Client) SendRecv(ctx context.Context, method string, target string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecv sends request with given data and returns response data. Caller may define headers to be added to the request. Received response is returned. E.g. resp.StatusCode. If request data is empty then request body is not sent in HTTP request. If response data is nil then response body is omitted.

func (*Client) SendRecv2xx 

func (c *Client) SendRecv2xx(ctx context.Context, method string, target string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecv2xx sends request with given data and returns response data and expects a 2xx response code. Caller may define headers to be added to the request. Received response is returned. E.g. resp.Header["Location"]. If request data is nil then request body is not sent in HTTP request. If response data is nil then response body is omitted.

func (*Client) SendRecvListFirst2xxParallel 

func (c *Client) SendRecvListFirst2xxParallel(ctx context.Context, method string, targets []string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecvListFirst2xxParallel acts similarly to SendRecv2xx, but broadcasts the request to all targets defined. The first positive (2xx) response is processed, the rest are cancelled. If all the responses are negative, then error is returned.

func (*Client) SendRecvListFirst2xxSequential 

func (c *Client) SendRecvListFirst2xxSequential(ctx context.Context, method string, targets []string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecvListFirst2xxSequential acts similarly to SendRecv2xx, but sends the request to the targets one-by-one, till a positive (2xx) response is received. If all the responses are negative, then error is returned. You may feed the list to a shuffle function before calling, if order is not defined.

func (*Client) SendRecvResolveFirst2xxParallel 

func (c *Client) SendRecvResolveFirst2xxParallel(ctx context.Context, method string, target string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecvResolveFirst2xxParallel acts similarly to SendRecv2xx, but broadcasts the request to all resolved servers of the target. The first positive (2xx) response is processed, the rest are cancelled. If all the responses are negative, then error is returned.

func (*Client) SendRecvResolveFirst2xxSequential 

func (c *Client) SendRecvResolveFirst2xxSequential(ctx context.Context, method string, target string, headers http.Header, reqData, respData any) (*http.Response, error)

SendRecvResolveFirst2xxSequential acts similarly to SendRecv2xx, but sends the request to the resolved targets one-by-one, till a positive (2xx) response is received. If all the responses are negative, then error is returned. You may feed the list to a shuffle function before calling, if order is not defined.

func (*Client) SendRequest 

func (c *Client) SendRequest(ctx context.Context, method string, target string, headers http.Header, data any) (*http.Response, error)

SendRequest sends an HTTP request with JSON data. Target URL and headers to be added can be defined. It is the caller's responsibility to close http.Response.Body.

func (*Client) SetBasicAuth added in v1.3.4 

func (c *Client) SetBasicAuth(username, password string) *Client

SetBasicAuth sets Authorization header for each request sent by the client. String username:password sent in HTTP header.

Make sure encrypted transport is used, e.g. the link is https.

func (*Client) SetJar added in v1.3.5 

func (c *Client) SetJar(jar http.CookieJar) *Client

SetJar sets cookie jar for the client.

func (*Client) SetMaxBytesToParse 

func (c *Client) SetMaxBytesToParse(max int) *Client

SetMaxBytesToParse sets a limit on parsing. Setting a value lower the risks of CPU-targeting DoS attack.

func (*Client) SetOauth2Conf added in v1.8.0 

func (c *Client) SetOauth2Conf(config oauth2.Config, tokenClient *http.Client, grant ...Grant) *Client

SetOauth2Conf initializes OAuth2 configuration with given grant. Depending on specific setup, custom http.Client can be added to obtain access tokens. Either on first request to be sent or later when the obtained access token is expired.

Make sure encrypted transport is used, e.g. the link is https. If client's HTTPS() has been called earlier, then token URL is checked accordingly. If token URL does not meet those requirements, then client credentials auth is not activated and error log is printed.

func (*Client) SetOauth2H2 added in v1.9.1 

func (c *Client) SetOauth2H2() *Client

SetOauth2H2 makes OAuth2 token client communicate using h2 transport with Authorization Server.

Warning: That resets all the earlier transport settings of the token client.

func (*Client) SetTransport added in v1.17.3 

func (c *Client) SetTransport(transport http.RoundTripper)

SetTransport sets the underlying transport, wrapping it with OTEL if needed. It is not the same as setting client.Client.Transport directly.

func (*Client) TLS 

func (c *Client) TLS(tlsConfig *tls.Config) *Client

TLS sets TLS setting for client. Returns object instance, just in case you need that. Use if specific config is needed, e.g. server cert or whether to accept untrusted certs. You may use it this way: client := New().TLS(...) or just client.TLS(...)

func (*Client) TLSOwnCerts 

func (c *Client) TLSOwnCerts(dir string, opts ...TLSOwnCertOpts) *Client

TLSOwnCerts loads PEM certificate + key from given directory and sets TLS config accordingly. That allows the client to authenticate itself using mutual TLS (mTLS).

If only the dir is specified, then looks for tls.crt and tls.key files in that dir. You may also specify custom file names by using TLSOwnCertOpts. In that case the key and cert file paths are appended to the provided directory.

Example usages: 

client = client.TLSOwnCerts("/path/to/certs")

client = client.TLSOwnCerts("/path/to/certs", TLSOwnCertOpts{Certificate: "mycert.crt", PrivateKey:  "mykey.key"})

client.TLSOwnCerts("/path/to/certs", TLSOwnCertOpts{Certificate: "/certs/mycert.pem", PrivateKey:  "/key/mykey.pem"})

func (*Client) TLSRootCerts 

func (c *Client) TLSRootCerts(path string, loadSystemCerts bool) *Client

TLSRootCerts loads PEM certificates from given path and sets TLS config accordingly. Cert can be Root CA or self-signed server cert, so that client can authenticate servers. If loadSystemCerts is true, the client accepts server CAs from system settings, too. If path is a directory then scans for files recursively. If path is not set then defaults to /etc. File name should match *.crt or *.pem.

func (*Client) Timeout added in v1.2.3 

func (c *Client) Timeout(timeout time.Duration) *Client

Timeout sets client timeout. Timeout and request context timeout are similar concepts. However, Timeout specified here applies to a single attempt, i.e. if Retry is used, then applies to each attempt separately, while context applies to all attempts together.

func (*Client) UserAgent 

func (c *Client) UserAgent(userAgent string) *Client

UserAgent to be sent as User-Agent HTTP header. If not set then default Go client settings are used.

type ClientMonitorFuncPost added in v1.5.0 

type ClientMonitorFuncPost func(req *http.Request, resp *http.Response, err error) *http.Response

ClientMonitorFuncPost is a type of user defined function to be called after the response is received. Response can be modified. If nil is returned, then the input response is retained.

type ClientMonitorFuncPre added in v1.5.0 

type ClientMonitorFuncPre func(req *http.Request) (*http.Response, error)

ClientMonitorFuncPre is a type of user defined function to be called before the request is sent. If returns non-nil response or error, then those are returned immediately, without any further processing (e.g. sending) the request. Request data can be freely modified.

type Grant added in v1.8.0 

type Grant string

Grant represents the flow how oauth2 access tokens are retrieved. 

const (
	// GrantClientCredentials represents oauth2 client credentials grant
	GrantClientCredentials Grant = "client_credentials"
	// GrantRefreshToken represents oauth2 refresh token grant
	GrantRefreshToken Grant = "refresh_token"
	// GrantPasswordCredentials represents oauth2 password credentials grant
	GrantPasswordCredentials Grant = "password"
)

type HTTPSConfig added in v1.7.4 

type HTTPSConfig struct {
	// AllowHTTP flag tells whether cleartext HTTP URLs are to be allowed to be used or not.
	AllowHTTP bool
	// AllowLocalhostHTTP flag tells whether to allow cleartext HTTP transport for localhost connections.
	// If AllowHttp is true, then that overrides this flag.
	AllowLocalhostHTTP bool
	// AllowedHTTPHosts lets hostnames defined which are allowed to be accessed by cleartext HTTP.
	// If AllowHttp is true, then this setting is not considered.
	AllowedHTTPHosts []string
}

HTTPSConfig contains some flags that control what kind of URLs to be allowed to be used. Don't confuse these with TLS config.

type InvalidParam added in v1.3.8 

type InvalidParam struct {
	Param  string `json:"param"`
	Reason string `json:"reason,omitempty"`
}

InvalidParam is the common InvalidParam object defined in 3GPP TS 29.571

type LocalIPs added in v1.17.2 

type LocalIPs struct {
	IPv4 *net.TCPAddr
	IPv6 *net.TCPAddr
}

LocalIPs is a struct which can contain IPv4 or IPv6 address

func GetIPFromInterface added in v1.17.2 

func GetIPFromInterface(networkInterface string) (theIPs LocalIPs)

GetIPFromInterface return IPv4 and IPv6 addresses of the network interface. If there is no address than that IPfamily is nil.

type MonitorFuncPost 

type MonitorFuncPost func(w http.ResponseWriter, r *http.Request, statusCode int)

MonitorFuncPost is a type of user defined function to be called after the request was served. Handle ResponseWriter with care.

type MonitorFuncPre 

type MonitorFuncPre func(w http.ResponseWriter, r *http.Request) *http.Request

MonitorFuncPre is a type of user defined function to be called before the request is served. If calls WriteHeader, then serving is aborted, the original handler and monitor post functions are not called. Pre may modify the request, especially its context, and return the modified request, or nil if not modified.

type ProblemDetails added in v1.2.0 

type ProblemDetails struct {
	Type          string         `json:"type,omitempty"`
	Title         string         `json:"title,omitempty"`
	Detail        string         `json:"detail,omitempty"`
	Cause         string         `json:"cause,omitempty"`
	Instance      string         `json:"instance,omitempty"`
	Status        int            `json:"status,omitempty"`
	InvalidParams []InvalidParam `json:"invalidParams,omitempty"`
}

ProblemDetails is a structure defining fields for RFC 7807 error responses.

func (ProblemDetails) String added in v1.2.0 

func (e ProblemDetails) String() string

String makes string of ProblemDetails.

type Route 

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

Route ...

func HandleFunc 

func HandleFunc(path string, f any) *Route

HandleFunc assigns an HTTP path template to a function.

func (*Route) GetError 

func (route *Route) GetError() error

GetError returns if building route failed.

func (*Route) Handler 

func (route *Route) Handler(handler http.Handler) *Route

Handler sets a handler for a route. Note: Cannot use Lambda here. Router's Monitor does not apply here.

func (*Route) HandlerFunc 

func (route *Route) HandlerFunc(f any) *Route

HandlerFunc sets a handler function or lambda for a route.

func (*Route) Methods 

func (route *Route) Methods(methods ...string) *Route

Methods defines on which HTTP methods to call your function. 

r.Methods(http.MethodPost, http.MethodPut)

func (*Route) Name 

func (route *Route) Name(name string) *Route

Name sets a name for a route.

func (*Route) Path 

func (route *Route) Path(pathTemplate string) *Route

Path registers a new route with a matcher for the URL path template. 

r.Path("/users/{id:[0-9]+}")

func (*Route) PathPrefix 

func (route *Route) PathPrefix(pathTemplate string) *Route

PathPrefix adds a matcher for the URL path template prefix.

func (*Route) Queries added in v1.3.0 

func (route *Route) Queries(pairs ...string) *Route

Queries adds a matcher for URL query values. 

route.Queries("id", "{id:[0-9]+}")

The odd (1st, 3rd, etc) string is the query parameter. The even (2nd, 4th, etc) string is the variable name and optional regex pattern.

func (*Route) Schemes 

func (route *Route) Schemes(schemes ...string) *Route

Schemes adds a matcher for URL schemes.

func (*Route) Subrouter 

func (route *Route) Subrouter() *Router

Subrouter creates a new sub-router for the route. 

r := restful.NewRouter()
s := r.PathPrefix("/api/v1/").Subrouter()
s.HandleFunc("/users", handleAllUsers)

Subrouter takes the existing Monitors of the parent route and apply them to the handle functions.

type Router 

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

Router routes requests to lambda functions.

func NewRouter 

func NewRouter() *Router

NewRouter creates new Router instance.

func (*Router) DisallowUnknownFields added in v1.14.0 

func (r *Router) DisallowUnknownFields() *Router

DisallowUnknownFields instructs JSON decoder to fail if unknown field in found in the received message. By default unknown fields are ignored. See also JSON schema and OpenAPI Specification `additionalProperties: false`.

func (*Router) Get 

func (r *Router) Get(name string) *Route

Get returns the route registered with the given name, or nil.

func (*Router) Handle 

func (r *Router) Handle(path string, handler http.Handler) *Route

Handle adds traditional http.Handler to route. Cannot use Lambda here.

func (*Router) HandleFunc 

func (r *Router) HandleFunc(path string, f any) *Route

HandleFunc assigns an HTTP path to a function. The function can be compatible with type http.HandlerFunc or a restful's Lambda. E.g. r.HandleFunc("/users/{id:[0-9]+}", myFunc)

func (*Router) Host 

func (r *Router) Host(hostRegex string) *Route

Host registers a new route with a matcher for the URL host regex. E.g. r.Host("{subdomain:[a-z]+}.example.com")

func (*Router) ListenAndServe 

func (r *Router) ListenAndServe(addr string) error

ListenAndServe starts router listening on given address. Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func (*Router) ListenAndServeMTLS 

func (r *Router) ListenAndServeMTLS(addr, certFile, keyFile, clientCerts string, loadSystemCerts bool) error

ListenAndServeMTLS starts router listening on given address. Parameter clientCerts is a PEM cert file or a directory of PEM cert files case insensitively matching *.pem or *.crt. If loadSystemCerts is true, clients with CA from system CA pool are accepted, too. As the role of mTLS is to authorize certain clients to connect, enable system CAs only if those are reasonable for auth. Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func (*Router) ListenAndServeTLS 

func (r *Router) ListenAndServeTLS(addr, certFile, keyFile string) error

ListenAndServeTLS starts router listening on given address. Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func (*Router) MethodNotAllowedHandler added in v1.17.6 

func (r *Router) MethodNotAllowedHandler(handler http.Handler) *Router

MethodNotAllowedHandler sets the handler invoked when a request matches a route path but not its HTTP method. Caution: if same path is set for multiple handlerfunction with different Methods, setting MethodNotAllowedHandler is not advised.

func (*Router) Methods 

func (r *Router) Methods(methods ...string) *Route

Methods registers a new route with a matcher for HTTP methods. E.g. r.Methods(http.MethodPost, http.MethodPut)

func (*Router) Monitor 

func (r *Router) Monitor(pre MonitorFuncPre, post MonitorFuncPost) *Router

Monitor wraps handler function, creating a middleware in a safe and convenient fashion. It adds pre and post functions to be called on serving a request.

func (*Router) Name 

func (r *Router) Name(name string) *Route

Name registers a new route with a name. That name can be used to query route.

func (*Router) Path 

func (r *Router) Path(pathTemplate string) *Route

Path registers a new route with a matcher for the URL path template. E.g. r.Path("/users/{id:[0-9]+}")

func (*Router) PathPrefix 

func (r *Router) PathPrefix(pathTemplate string) *Route

PathPrefix registers a new route with a matcher for the URL path template prefix.

func (*Router) Queries added in v1.3.0 

func (r *Router) Queries(pairs ...string) *Route

Queries registers a new route with a matcher for URL query values. 

router.Queries("id", "{id:[0-9]+}")

The odd (1st, 3rd, etc) string is the query parameter. The even (2nd, 4th, etc) string is the variable name and optional regex pattern.

func (*Router) Schemes 

func (r *Router) Schemes(schemes ...string) *Route

Schemes registers a new route with a matcher for URL schemes.

func (*Router) ServeHTTP 

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP serves HTTP request with matching handler.

func (*Router) Start 

func (r *Router) Start() error

Start starts router on port 8080 (AddrHTTP). Logs, except for automatically served LivenessProbePath and HealthCheckPath. Handles connections gracefully on TERM/INT signals.

func (*Router) StartTLS 

func (r *Router) StartTLS(cleartext, mutualTLS bool, loadSystemCerts bool) error

StartTLS starts router for TLS on port 8443 (AddrHTTPS) and for cleartext on port 8080 (AddrHTTP), if allowed. TLS cert must be at OwnTLSCert and key at OwnTLSKey. If mutualTLS=true, then client certs must be provided; see variable ClientCAs. If loadSystemCerts is true, clients with CA from system CA pool are accepted, too. As the role of mTLS is to authorize certain clients to connect, enable system CAs only if those are reasonable for auth. Logs, except for automatically served LivenessProbePath and HealthCheckPath. Handles connections gracefully on TERM/INT signals.

type Server 

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

Server represents a server instance.

func NewServer 

func NewServer() *Server

NewServer creates a new Server instance.

func (*Server) Addr 

func (s *Server) Addr(addr string) *Server

Addr sets address to listen on. E.g. ":8080". If not set then transport specific port (80/443) is listened on any interface.

func (*Server) CRL added in v1.17.0 

func (s *Server) CRL(o CRLOptions) *Server

CRL sets up Certificate Revocation List watching for the Server. CRL cert is read from *path*, re-read every *readInterval* and has to exist until *fileExistTimeout*. Errors are delivered through *errChan*

func (*Server) Close 

func (s *Server) Close() error

Close immediately closes all connections.

func (*Server) Graceful 

func (s *Server) Graceful(gracePeriod time.Duration) *Server

Graceful enables graceful shutdown. Awaits TERM/INT signals and exits when http shutdown completed, i.e. clients are served. Caller may define gracePeriod to wait before shutting down listening point. Client connection shutdown awaited indefinitely.

func (*Server) Handler 

func (s *Server) Handler(handler http.Handler) *Server

Handler defines handlers for server. Logs, except for automatically served LivenessProbePath and HealthCheckPath.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe() error

ListenAndServe starts listening and serves requests, blocking the caller. Uses HTTPS if server key+cert is set, otherwise HTTP. Port is set according to scheme, if listening address is not set. When Graceful() is used it may return nil.

func (*Server) Monitor 

func (s *Server) Monitor(pre MonitorFuncPre, post MonitorFuncPost) *Server

Monitor sets monitor functions for the server. These functions are called pre / post serving each request.

func (*Server) Restart added in v1.3.3 

func (s *Server) Restart()

Restart restarts the server abruptly. During restart active connections are dropped and there may be an outage.

func (*Server) Shutdown 

func (s *Server) Shutdown(ctx context.Context) error

Shutdown closes all connections gracefully. E.g. server.Shutdown(context.Background())

func (*Server) TLSClientCert 

func (s *Server) TLSClientCert(path string, loadSystemCerts bool) *Server

TLSClientCert adds client certs to server, enabling mutual TLS (mTLS). If path is a directory then scans for files recursively. If path is not set then defaults to /etc. If loadSystemCerts is true, clients with CA from system CA pool are accepted, too. As the role of mTLS is to authorize certain clients to connect, enable system CAs only if those are reasonable for auth. File names should match *.crt or *.pem.

func (*Server) TLSConfig added in v1.17.5 

func (s *Server) TLSConfig() *tls.Config

TLSConfig returns raw TLS config used by the server

func (*Server) TLSServerCert 

func (s *Server) TLSServerCert(certFile, keyFile string) *Server

TLSServerCert sets server cert + key.

type TLSOwnCertOpts added in v1.17.4 

type TLSOwnCertOpts struct {
	Certificate string
	PrivateKey  string // #nosec G117: exported, so that the client can specify the private key path
}

TLSOwnCertOpts allows specifying custom file paths for client certificate and private key.

Source Files

View all Source files

Directories

Path Synopsis
trace
traceb3
tracecommon
tracedata
traceotel
traceparent
tracer

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.