request

Documentation

Overview

Package request provides helper functions to handle Request ID propagation.

Basics

It will be used the following service as example:

type Service interface {
	Do(context.Context, Request) (Response, error)
}
type Response struct {
//(...)
	RequestID request.ID
}

HTTP Layer

Use the function "WithID" to create and put a Request ID in context:

func MakeEndpoint(s Service) endpoint.Endpoint {
	return func(ctx context.Context, r interface{}) (interface{}, error) {
		req := r.(Request)
		ctx = request.WithID(ctx)
		response, err := s.Do(ctx, req)
		return response, err
	}
}

Logging

Use the function "GetIDFromContext" to log the Request ID:

func (l *logging) Do(ctx ontext.Context, req Request) (response Response, err error) {
	logger := log.Logger.With().
		EmbedObject(request.GetIDFromContext(ctx)).
		Logger()
	// (...)
}

Index

• Constants
• func HTTPMiddleware(next http.Handler) http.Handler
• func IsEmpty(id ID) bool
• func SetInHTTPRequest(ctx context.Context, request *http.Request)
• func SetInHTTPResponse(id ID, response http.ResponseWriter)
• func WithID(ctx context.Context, id ID) context.Context
• func WithNewID(ctx context.Context) context.Context
• type ID
  • func GetFromHTTPRequest(r *http.Request) ID
  • func GetFromHTTPResponse(r *http.Response) ID
  • func GetIDFromContext(ctx context.Context) ID
  • func Parse(id string) (ID, error)
  • func (i ID) IsEmpty() bool
  • func (i ID) MarshalJSON() ([]byte, error)
  • func (i ID) MarshalZerologObject(e *zerolog.Event)
  • func (i ID) String() string
  • func (i *ID) UnmarshalJSON(b []byte) error

Constants

const (
	// HTTPHeaderID is the HTTP Header to be used when sending ID in
	// HTTP Requests or Responses
	HTTPHeaderID = "X-REQUESTID"
)

Functions

func HTTPMiddleware

func HTTPMiddleware(next http.Handler) http.Handler

HTTPMiddleware returns an http middleware that adds a request id to the context of the request and the same id in the header of the http response. If there is an active trace span, the request id is also registered as an attribute 'request.id'. It's important that this middleware comes after the trace middleware.

func IsEmpty

func IsEmpty(id ID) bool

IsEmpty returns true if an request ID is in it's zero-value format

func SetInHTTPRequest

func SetInHTTPRequest(ctx context.Context, request *http.Request)

SetInHTTPRequest will add the ID registered in @ctx into the given @request as a HTTP Header. If @request is nil, an warning log will be emitted and nothing will be changed.

func SetInHTTPResponse

func SetInHTTPResponse(id ID, response http.ResponseWriter)

SetInHTTPResponse will add the ID registered in @ctx into the given @request as a HTTP Header. If @request is nil, an warning log will be emitted and nothing will be changed.

nolint: interfacer

func WithID

func WithID(ctx context.Context, id ID) context.Context

WithID returns a context with the given ID

If there is already an ID in the context, the context is returned unchanged.

func WithNewID

func WithNewID(ctx context.Context) context.Context

WithNewID calls WithID with a new ID

Types

type ID

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

ID is an identifier to uniquely identify a request

func GetFromHTTPRequest

func GetFromHTTPRequest(r *http.Request) ID

GetFromHTTPRequest attempts to read a Request ID from the given @r http request's header. If no ID is found, or the found ID is ill-formatted, an empty ID is returned.

func GetFromHTTPResponse

func GetFromHTTPResponse(r *http.Response) ID

GetFromHTTPResponse attempts to read a Request ID from the given @r http response's header. If no ID is found, or the found ID is ill-formatted, an empty ID is returned.

func GetIDFromContext

func GetIDFromContext(ctx context.Context) ID

GetIDFromContext returns the request ID in the context. Will return a empty ID if it is not set

func Parse

func Parse(id string) (ID, error)

Parse read the given @id into an request ID.

func (ID) IsEmpty

func (i ID) IsEmpty() bool

IsEmpty returns true if there is no timestamp or randomID in Request ID @i

func (ID) MarshalJSON

func (i ID) MarshalJSON() ([]byte, error)

MarshalJSON converts ID to a string.

func (ID) MarshalZerologObject

func (i ID) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements the zerolog marshaler so it can be logged using: log.With().EmbededObject(cuf).Msg("Some message")

func (ID) String

func (i ID) String() string

func (*ID) UnmarshalJSON

func (i *ID) UnmarshalJSON(b []byte) error

UnmarshalJSON parses an ID from a json