6.9 KiB
correlation
import "github.com/effective-security/porto/xhttp/correlation"
Package correlation propagates a per-request correlation ID through http.Request contexts, gRPC metadata and log entries.
An ID is taken from the incoming X-Correlation-ID or X-Request-ID header (gRPC: x-correlation-id / x-request-id metadata), truncated to IDSize characters, or generated randomly when absent. The ID is stored in the context (see ID, Value), attached to xlog context fields as "ctx", and echoed back in the X-Correlation-ID response header.
h := correlation.NewHandler(next) // HTTP middleware
srv := grpc.NewServer(grpc.UnaryInterceptor(correlation.NewAuthUnaryInterceptor()))
id := correlation.ID(ctx) // read it later
ctx = correlation.WithMetaFromContext(ctx) // outgoing gRPC call
Both gRPC interceptors also recover panics from downstream handlers, log them with a stack trace and return a generic "unhandled exception" error.
Index
- Constants
- Variables
- func ID(ctx context.Context) string
- func NewAuthUnaryInterceptor() grpc.UnaryServerInterceptor
- func NewFromContext(ctx context.Context) context.Context
- func NewHandler(delegate http.Handler) http.Handler
- func NewStreamServerInterceptor() grpc.StreamServerInterceptor
- func WithID(ctx context.Context) context.Context
- func WithMetaFromContext(ctx context.Context) context.Context
- func WithMetaFromRequest(req *http.Request) context.Context
- type Correlator
- type RequestContext
Constants
IDSize is the length in characters of generated correlation IDs; incoming IDs longer than this are truncated.
const IDSize = 12
Variables
CorrelationIDgRPCHeaderName is the gRPC metadata key used to carry the correlation ID on outgoing calls and read it on incoming ones. It is a process-global that may be changed at startup, before any traffic.
var CorrelationIDgRPCHeaderName = "x-correlation-id"
func ID
func ID(ctx context.Context) string
ID returns the correlation ID stored in ctx, or "" if none.
func NewAuthUnaryInterceptor
func NewAuthUnaryInterceptor() grpc.UnaryServerInterceptor
NewAuthUnaryInterceptor returns a grpc.UnaryServerInterceptor that adds the correlation ID (from incoming metadata or newly generated) to the context and xlog fields, and recovers panics from the handler, logging them and returning an Internal status with message "unhandled exception".
func NewFromContext
func NewFromContext(ctx context.Context) context.Context
NewFromContext returns a fresh context.Background (detached from ctx's cancellation and deadline) that carries ctx's correlation ID, or a new one, both as a context value and as outgoing gRPC metadata. Use it for background work that should outlive the request.
func NewHandler
func NewHandler(delegate http.Handler) http.Handler
NewHandler returns middleware that reads the correlation ID from the X-Correlation-ID or X-Request-ID request header (or generates one), stores it in the request context, adds it to the xlog context as "ctx" and sets the X-Correlation-ID response header before calling delegate. An ID already present in the context is reused.
func NewStreamServerInterceptor
func NewStreamServerInterceptor() grpc.StreamServerInterceptor
NewStreamServerInterceptor returns the streaming counterpart of NewAuthUnaryInterceptor; the stream is wrapped with streamctx.WithContext so handlers see the enriched context.
func WithID
func WithID(ctx context.Context) context.Context
WithID returns a context carrying a newly generated correlation ID (also added to the xlog fields). If ctx already has one, ctx is returned as is.
func WithMetaFromContext
func WithMetaFromContext(ctx context.Context) context.Context
WithMetaFromContext ensures the outgoing gRPC metadata of ctx carries the correlation ID under CorrelationIDgRPCHeaderName, generating and storing a new ID in the context when none exists. Use it before making a gRPC client call.
func WithMetaFromRequest
func WithMetaFromRequest(req *http.Request) context.Context
WithMetaFromRequest returns context with Correlation ID for the outgoing gRPC call, on wire or in memory. Both Incoming and Outgoing metadata are created out of HTTP request headers with x- and grpc- prefixes.
type Correlator
Correlator is implemented by values (such as httperror.Error) that carry a correlation ID.
type Correlator interface {
// CorrelationID returns the correlation ID, or "" when unknown.
CorrelationID() string
}
type RequestContext
RequestContext is the value stored in the context by this package; it holds the request ID, aka Request-ID or Correlation-ID (for cross system request correlation). Retrieve it with Value or ID.
type RequestContext struct {
// ID is the correlation ID.
ID string
}
func Value
func Value(ctx context.Context) *RequestContext
Value returns the RequestContext stored in ctx, or nil if none.
Generated by gomarkdoc