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 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
• func WithNewRequestID(ctx context.Context) context.Context
• func WithRequestID(ctx context.Context, id ID) context.Context
• type ID
  • func GetFromHTTPRequest(r *http.Request) ID
  • func GetFromHTTPResponse(r *http.Response) ID
  • func GetIDFromContext(ctx context.Context) ID
  • func GetRequestIDFromContext(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 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

func WithNewRequestID

func WithNewRequestID(ctx context.Context) context.Context

WithNewRequestID calls WithNewID

Deprecated: use WithNewID instead

func WithRequestID

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

WithRequestID returns a context with the given ID

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

Deprecated: use WithID instead

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 GetRequestIDFromContext

func GetRequestIDFromContext(ctx context.Context) ID

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

Deprecated: use GetIDFromContext instead

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