restful

package module
v1.8.1 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2024 License: BSD-3-Clause Imports: 36 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{...}
type respData struct{...}

func create(ctx context.Context, req *reqData) (*respData, error) {
    ... // You use data structures directly, without marshalling and unmarshalling.
}

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 and 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 request. That is all done without any extra coding on your side. Based on OpenTelemetry.
  • Monitor is a middleware that can pre-process requests and post-process responses. Pre and post hooks can be used for whatever you want, such as adding Prometheus counters on router level, without littering your business logic.
  • Error is a Go error object containing HTTP status code besides traditional error.

Trace context and error are the glue between Lambda and Client. That is why 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.
  • Have quite many goodies needed on 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

Variables

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, such as liveness and readiness probes.
	// Handled by default, 200 OK sent.
	// Ignored at logging. By default "/healthz".
	HealthCheckPath = "/healthz"

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

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

DefaultServeMux is the default HTTP mux served.

View Source 
var LambdaMaxBytesToParse = 0

LambdaMaxBytesToParse defines the maximum length of 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.

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 TokenClient *http.Client = &http.Client{Timeout: 10 * time.Second}

TokenClient 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.

If you want to use the same client, try 

restful.TokenClient = myClient.Client

Functions

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 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 interface{}) 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 unprocessed body of a response with error status. 

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

func GetErrStatusCode 

func GetErrStatusCode(err error) int

GetErrStatusCode returns status code of error response. If err is nil then http.StatusOK returned. If no status stored (e.g. unexpected content-type received) then http.StatusInternalServerError returned.

func GetErrStatusCodeElse 

func GetErrStatusCodeElse(err error, elseStatusCode int) int

GetErrStatusCodeElse returns status code of error response, if available. Else retuns the one the caller provided. Probably transport error happened and no HTTP response was received. If err is nil then http.StatusOK returned.

func GetRequestData 

func GetRequestData(req *http.Request, maxBytes int, data interface{}) 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 interface{}) 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 error is due to failed connection. I.e. does not contain HTTP status code, or 502 / 503 / 504.

func L 

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

L returns lambda-related data from context.

func LambdaWrap 

func LambdaWrap(f interface{}) 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, 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. 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. Logs start with a semi-random trace ID to be able to match requests to responses. If path matches LivenessProbePath or HealthCheckPath then does not log and responds with 200 OK. If path matches ReadinessProbePath then does not log, but processed as usual.

func Monitor 

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

Monitor wraps http.Handler, adding user defined pre and post ReporterFunc call after the handler is served. You may prefer Server's or Router's Monitor functions.

func NewCertPool 

func NewCertPool(path string) *x509.CertPool

NewCertPool loads PEM certificates from given path and returns them 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. 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 to be propagated. 

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

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 interface{}) 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 interface{}) (*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 interface{}) (*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.

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.

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 interface{}, 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 interface{}) 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 interface{}) 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) 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.

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) 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. Logs, except for automatically served LivenessProbePath and HealthCheckPath. Handles connections gracefully on TERM/INT signals.

Types

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
	// 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 NewH2CClient 

func NewH2CClient() *Client

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

func NewH2Client 

func NewH2Client() *Client

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

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 interface{}) 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) 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) Get 

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

Get gets a resource.

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

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, target string, reqData, respData interface{}) 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 interface{}) (*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 interface{}) (*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) Put 

func (c *Client) Put(ctx context.Context, target string, reqData, respData interface{}) (*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.

func (*Client) SendRecv 

func (c *Client) SendRecv(ctx context.Context, method string, target string, headers http.Header, reqData, respData interface{}) (*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 interface{}) (*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 interface{}) (*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 interface{}) (*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 interface{}) (*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 interface{}) (*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 interface{}) (*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, grant ...Grant) *Client

SetOauth2Conf makes client obtain OAuth2 access token with given grant. 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) 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) *Client

TLSOwnCerts loads PEM certificate + key from given directory and sets TLS config accordingly. Cert + key is used at mutual TLS (mTLS) connection when client authenticates itself. File names should be tls.crt and tls.key (see `kubectl create secret tls`).

func (*Client) TLSRootCerts 

func (c *Client) TLSRootCerts(path string) *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 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 retreived. 

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 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 interface{}) *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 interface{}) *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) 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 interface{}) *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) 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. 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) 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 sets monitor functions for the router. These functions are called pre / post serving each 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) 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. 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) 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. Caller may define gracePeriod to wait before shutting down, or zero to wait till server connections are closed. Grace period is respected even if server connections are shut down earlier, to allow background client connections to be closed.

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) *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. File name should match *.crt or *.pem.

func (*Server) TLSServerCert 

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

TLSServerCert sets server cert + 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.