session

package module
v1.2.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 2 Imported by: 18

README

gorib/session

Request and command identity, carried in the context. One struct that every transport fills on the way in and every client reads on the way out, so a correlation id and a trace context survive an HTTP call, a gRPC call, an AMQP delivery and a CLI command without any of them knowing about the others.

Zero dependencies — the module requires nothing beyond the standard library (uuid is stdlib as of Go 1.27).

The struct

type Session struct {
	Uri           string
	Method        string
	Body          string
	CorrelationId string
	UserAgent     string
	UserLanguage  string
	SourceIp      string
}

Method is the transport, not the HTTP verb alone: GET/POST from HTTP, GRPC, AMQP, OUTBOX, CLI, CRON. Uri is whatever names the work in that transport — a URL, a full gRPC method, a routing key, a command name. Body is the raw payload, kept for error reporting; an AMQP delivery handled in a batch of several carries none.

Every field is written once, by the transport that builds the session, and is read-only from then on. That is what makes the struct safe to copy out of the context, which pry does on every log line.

The trace context

W3C Trace Context does not live in the struct. The tracing middleware replaces the traceparent with the id of the span it just started, so an outgoing call is a child of the current span rather than of the incoming one — and that happens while other goroutines hold the same session. So it rides the context instead, where a write derives rather than mutates:

ctx, span := tracer.Start(ctx, name, ...)
if tp := hilton.FormatTraceparent(span.SpanContext()); tp != "" {
	ctx = session.WithTraceparent(ctx, tp)
}
// the derived ctx is what must reach the handler
traceparent, tracestate := session.TraceFromContext(ctx)

WithTraceparent and WithTracestate each keep the other half. Reading a context that never passed through tracing middleware yields empty strings rather than panicking, and a nil ctx is tolerated.

Scope follows the span

The traceparent is visible for exactly as long as the context it was written to. A function that starts a span, uses it and returns cannot leave its traceparent behind for its caller:

func (r *publisher) Publish(ctx context.Context, ...) error {
	ctx, span := tracer.Start(ctx, r.exchange+" publish", ...)
	defer span.End()
	ctx = session.WithTraceparent(ctx, tp)
	...
}
// the caller's ctx still names the request span, not the finished publish span

That is the whole reason the pair is not a field. A writer must therefore make sure the derived context is the one that travels on — src.SetRequest, the handler call, msgs[i].WithContext — or the write is lost.

API

Function What
Setup(Session) *Session Fills a missing CorrelationId with a UUIDv7 and returns a pointer
NewContextWithSession(ctx, Session) context.Context Setup plus store under the package key
FromContext(ctx) *Session The session, or nil — a nil ctx is tolerated
NewEmptyContextWithSession(ctx) context.Context A context.Background() carrying a copy of the current session and its trace
WithTrace(ctx, traceparent, tracestate) context.Context Both halves
WithTraceparent(ctx, traceparent) / WithTracestate(ctx, tracestate) One half, keeping the other
TraceFromContext(ctx) (traceparent, tracestate string) The trace, or empty strings
TraceparentFromContext(ctx) / TracestateFromContext(ctx) string One half

The pointer is deliberate

FromContext returns a *Session so that reading it costs one context lookup and no allocation — pry.Ctx runs on every log line. Nothing mutates it: the one thing that used to be rewritten in place now lives on the context. Writing an identity field after the session reaches a context is a data race the compiler will not catch.

Detaching from the request

Work that must outlive the request — a goroutine started from a handler — cannot keep the request context: its cancellation would kill the work when the client disconnects. NewEmptyContextWithSession returns a context built on context.Background() carrying a copy of the current session, so the correlation id follows the work while the deadline does not. The trace is carried over explicitly — context.Background() holds nothing — so the detached work starts under the span that forked it.

bg := session.NewEmptyContextWithSession(ctx)
go func() {
	if err := s.notify(bg, order); err != nil {
		logger.Error(err, pry.Ctx(bg))
	}
}()

If the incoming context has no session at all, a fresh one is created with a new correlation id rather than returning nothing.

Who fills it, who reads it

Package On the way in On the way out
http middleware.NewSession reads the correlation, user-agent, language, source-ip and traceparent headers the same middleware echoes CorrelationId back as a response header; client sends all of them
grpc interceptor.Session reads incoming metadata, falling back to peer for SourceIp and to gRPC's own user-agent client/interceptor.Session appends them to outgoing metadata
amqp the consumer builds a session per delivery from the message headers and CorrelationId the publisher writes them back into amqp.Publishing headers
waffle app.NewContextWithCommand (CLI), the cron tool (CRON) and the outbox relay (OUTBOX) synthesize one, so a background job is as traceable as a request —
pry — pry.Ctx(ctx) forwards the fields to Sentry as tags, request url/method/data and headers

Header names are not this package's business: each transport owns its own constants (http/model, grpc/model, amqp/model), because the spellings differ — correlation-id in gRPC metadata, User-Agent in AMQP headers.

What it does not do

  • No propagation of its own. It is a holder; the transports move it.
  • No trace-context parsing. The traceparent is an opaque string here; hilton formats and parses it.
  • No authentication or user identity. Nothing in Session is a claim about who the caller is — it identifies a request, not a principal.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewContextWithSession

func NewContextWithSession(ctx context.Context, session Session) context.Context

func NewEmptyContextWithSession

func NewEmptyContextWithSession(ctx context.Context) context.Context

func TraceFromContext

func TraceFromContext(ctx context.Context) (traceparent, tracestate string)

func TraceparentFromContext

func TraceparentFromContext(ctx context.Context) string

func TracestateFromContext

func TracestateFromContext(ctx context.Context) string

func WithTrace

func WithTrace(ctx context.Context, traceparent, tracestate string) context.Context

func WithTraceparent

func WithTraceparent(ctx context.Context, traceparent string) context.Context

func WithTracestate

func WithTracestate(ctx context.Context, tracestate string) context.Context

Types

type Key

type Key struct{}

type Session

type Session struct {
	Uri           string
	Method        string
	Body          string
	CorrelationId string
	UserAgent     string
	UserLanguage  string
	SourceIp      string
}

func FromContext

func FromContext(ctx context.Context) *Session

func Setup

func Setup(session Session) *Session

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL