httpcomm

Documentation

Index

• Constants
• func CommunicateWithJSON(ctx context.Context, httpClient http.Client, httpMethod HTTPMethod, ...) (trace.Trace, error)
• type HTTPMethod
• type ResponseDetails
  • func CommunicateWithJSONAndHeadersDetailed(ctx context.Context, httpClient http.Client, httpMethod HTTPMethod, ...) (ResponseDetails, error)
  • func CommunicateWithJSONDetailed(ctx context.Context, httpClient http.Client, httpMethod HTTPMethod, ...) (ResponseDetails, error)

Constants

const (
	// ErrCodeExpiredContext is returned when an operation won't be
	// executed due to it's context being expired before the operation
	// start.
	ErrCodeExpiredContext errors.Code = "EXPIRED_CONTEXT"

	// ErrCodeRequestError is returned when a request could not be generated
	// for some reason or other.
	ErrCodeRequestError errors.Code = "REQUEST_ERROR"

	// ErrCodeDecodeError is returned when a received response body could not be
	// decoded. This usually means transport layer errors, such as HTTP or DNS.
	ErrCodeDecodeError errors.Code = "DECODE_ERROR"

	// ErrCodeResponseTooLong is returned when a received response body is too
	// long and can be assumed as an serious malfunction or an attack.
	ErrCodeResponseTooLong errors.Code = "RESPONSE_TOO_LONG"

	// ErrCodeTimeout is returned when a client side timeout on the HTTP Client
	// is detected. Note that as there are various ways of a timeout occurring, this
	// error code might not be returned in every type of timeout error happening.
	ErrCodeTimeout errors.Code = "TIMEOUT"

	// ErrCodeMissing is returned when a received response has an error without
	// code. This should never happen, indicating unexpected behavior in the
	// HTTP Server.
	ErrCodeMissing errors.Code = "CODE_MISSING"
)

Functions

func CommunicateWithJSON

func CommunicateWithJSON(
	ctx context.Context,
	httpClient http.Client,
	httpMethod HTTPMethod,
	fullURL string,
	requestData interface{},
	maxAcceptedBodySize int64,
	maxErrBodySize int,

	outResponse interface{},
) (trace.Trace, error)

CommunicateWithJSON uses a given @httpClient to communicate with a HTTP server at @fullURL using the specified @httpMethod. This function will send @requestData marshalled as a JSON content and wait for the server response. The response will be written into the given @outResponse (it will mutate the parameter contents) using the json unmarshaling rules set by @outResponse itself.

To reduce damage in case of bugs or attacks, a @maxAcceptedBodySize must be passed, and bodies contents larger than this will be considered noxious and return an error.

A value of @maxErrBodySize must be passed to indicate how much of response contents can be added into the error message.

Types

type HTTPMethod

type HTTPMethod = string

HTTPMethod is the method to use over HTTP. Expects the same values as defined per Go's http package.

type ResponseDetails

type ResponseDetails struct {
	Trace      trace.Trace
	RequestID  request.ID
	StatusCode int
	Header     http.Header
}

ResponseDetails holds details of the received response, such as HTTP Status and headers, if available.

func CommunicateWithJSONAndHeadersDetailed

func CommunicateWithJSONAndHeadersDetailed(
	ctx context.Context,
	httpClient http.Client,
	httpMethod HTTPMethod,
	fullURL string,
	requestData interface{},
	headers map[string][]string,
	maxAcceptedBodySize int64,
	maxErrBodySize int,

	outResponse interface{},
) (ResponseDetails, error)

CommunicateWithJSONAndHeadersDetailed uses a given @httpClient to communicate with a HTTP server at @fullURL using the specified @httpMethod. This function will send @requestData marshalled as a JSON content, with @headers as headers and wait for the server response. The response will be written into the given @outResponse (it will mutate the parameter contents) using the json unmarshaling rules set by @outResponse itself. This function returns detailed information of the response. It is possible that the detailed information might hold some data even if error is not nil, but the data may not be complete.

To reduce damage in case of bugs or attacks, a @maxAcceptedBodySize must be passed, and bodies contents larger than this will be considered noxious and return an error.

A value of @maxErrBodySize must be passed to indicate how much of response contents can be added into the error message.

func CommunicateWithJSONDetailed

func CommunicateWithJSONDetailed(
	ctx context.Context,
	httpClient http.Client,
	httpMethod HTTPMethod,
	fullURL string,
	requestData interface{},
	maxAcceptedBodySize int64,
	maxErrBodySize int,

	outResponse interface{},
) (ResponseDetails, error)

CommunicateWithJSONDetailed uses a given @httpClient to communicate with a HTTP server at @fullURL using the specified @httpMethod. This function will send @requestData marshalled as a JSON content and wait for the server response. The response will be written into the given @outResponse (it will mutate the parameter contents) using the json unmarshaling rules set by @outResponse itself. This function returns detailed information of the response. It is possible that the detailed information might hold some data even if error is not nil, but the data may not be complete.

To reduce damage in case of bugs or attacks, a @maxAcceptedBodySize must be passed, and bodies contents larger than this will be considered noxious and return an error.

A value of @maxErrBodySize must be passed to indicate how much of response contents can be added into the error message.