Documentation
¶
Overview ¶
Package ctxkeys provides typed context keys for generic observability and networking identifiers (correlation, trace, span, request, real IP) propagated through context.Context.
Cell-model identifiers (cell, slice, journey) live in github.com/ghbvf/gocell/kernel/ctxkeys because they encode GoCell architectural concepts rather than generic cross-service conventions.
Authentication subject is propagated via runtime/auth.Principal — use auth.WithPrincipal / auth.FromContext instead of a ctxkeys entry.
Index ¶
- func ActorIDFrom(ctx context.Context) (string, bool)
- func CorrelationIDFrom(ctx context.Context) (string, bool)
- func RealIPFrom(ctx context.Context) (string, bool)
- func RequestIDFrom(ctx context.Context) (string, bool)
- func SessionIDFrom(ctx context.Context) (string, bool)
- func SpanIDFrom(ctx context.Context) (string, bool)
- func SubjectIDFrom(ctx context.Context) (string, bool)
- func TenantIDFrom(ctx context.Context) (string, bool)
- func TraceIDFrom(ctx context.Context) (string, bool)
- func TraceParentFrom(ctx context.Context) (string, bool)
- func WithActorID(ctx context.Context, id string) context.Context
- func WithCorrelationID(ctx context.Context, id string) context.Context
- func WithPeerIdentity(ctx context.Context, id PeerIdentity) context.Context
- func WithRealIP(ctx context.Context, ip string) context.Context
- func WithRequestID(ctx context.Context, id string) context.Context
- func WithSessionID(ctx context.Context, id string) context.Context
- func WithSpanID(ctx context.Context, id string) context.Context
- func WithSubjectID(ctx context.Context, id string) context.Context
- func WithTenantID(ctx context.Context, id string) context.Context
- func WithTraceID(ctx context.Context, id string) context.Context
- func WithTraceParent(ctx context.Context, traceparent string) context.Context
- type PeerIdentity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ActorIDFrom ¶
ActorIDFrom extracts the actor identifier from ctx. The boolean indicates presence.
func CorrelationIDFrom ¶
CorrelationIDFrom extracts the correlation ID from ctx. The boolean indicates presence.
func RealIPFrom ¶
RealIPFrom extracts the client's real IP from ctx. The boolean indicates presence.
func RequestIDFrom ¶
RequestIDFrom extracts the request ID from ctx. The boolean indicates presence.
func SessionIDFrom ¶
SessionIDFrom extracts the session identifier from ctx. The boolean indicates presence.
func SpanIDFrom ¶
SpanIDFrom extracts the span ID from ctx. The boolean indicates presence.
func SubjectIDFrom ¶
SubjectIDFrom extracts the subject identifier from ctx. The boolean indicates presence.
func TenantIDFrom ¶
TenantIDFrom extracts the tenant identifier from ctx. The boolean indicates presence.
func TraceIDFrom ¶
TraceIDFrom extracts the trace ID from ctx. The boolean indicates presence.
func TraceParentFrom ¶
TraceParentFrom extracts the W3C traceparent value from ctx. The boolean indicates presence.
func WithActorID ¶
WithActorID returns a new context carrying the actor identifier (OAuth impersonator — the principal actually triggering the action; in non- impersonation flows equals the Subject).
func WithCorrelationID ¶
WithCorrelationID returns a new context carrying the given correlation ID.
func WithPeerIdentity ¶
func WithPeerIdentity(ctx context.Context, id PeerIdentity) context.Context
WithPeerIdentity returns a new context carrying the given peer identity.
runtime/http/middleware.MTLS is the sole producer in practice, but this is a CONVENTION, not a statically enforced guarantee: WithPeerIdentity is exported (a cross-package context setter cannot be sealed in Go), so any package could call it. There is deliberately no caller-allowlist archtest — a handler injecting a forged identity into its own request context gains nothing it could not already do, so the sole-producer property is not security-load- bearing. What IS enforced (Hard) is the curated field set: see PeerIdentity's doc and archtest PEER-IDENTITY-FIELDS-FROZEN-01.
func WithRealIP ¶
WithRealIP returns a new context carrying the client's real IP address.
func WithRequestID ¶
WithRequestID returns a new context carrying the given request ID.
func WithSessionID ¶
WithSessionID returns a new context carrying the session identifier (the authenticated session the request was made under). It is credential-adjacent: it travels in cleartext in the outbox wire envelope (Principal.sessionId is a plain envelope field), and is masked only when surfaced as a telemetry span attribute — the key gocell.principal.session_id hits IsSensitiveKey in adapters/otel/span.go::safeStringAttr, so it does not leak into the trace backend. The wire/broker path itself carries it verbatim.
func WithSpanID ¶
WithSpanID returns a new context carrying the given span ID.
func WithSubjectID ¶
WithSubjectID returns a new context carrying the subject identifier (OAuth subject-of-record — the user the action is performed on behalf of).
func WithTenantID ¶
WithTenantID returns a new context carrying the tenant identifier (the organization / isolation boundary the action belongs to; empty in single-tenant deployments).
func WithTraceID ¶
WithTraceID returns a new context carrying the given trace ID.
Types ¶
type PeerIdentity ¶
PeerIdentity is the curated subset of a verified leaf X.509 client certificate surfaced to request-scope handlers.
The field set is intentionally narrow: callers consume Subject (CN / O / OU / ...), DNS SANs, and URI SANs (including raw SPIFFE spiffe:// entries that callers parse with their own helper). Raw *x509.Certificate is deliberately not exposed, so handlers do not depend on the x509 internal representation. This field set is frozen by archtest PEER-IDENTITY-FIELDS-FROZEN-01 (reflect lock: names, types, visibility, no embedding, no raw-cert field) — adding/removing/retyping a field fails CI.
SECURITY NOTE: Subject is the stdlib pkix.Name. Beyond CN/O/OU it carries Names []pkix.AttributeTypeAndValue and ExtraNames []pkix.AttributeTypeAndValue which can hold arbitrary OID-value pairs (e.g. emailAddress, serialNumber). Callers that serialize Subject wholesale into slog or access logs may leak PII. Read only the named fields you need (Subject.CommonName, Subject.Organization, etc.) and never marshal Subject directly into wire or log payloads.
func PeerIdentityFrom ¶
func PeerIdentityFrom(ctx context.Context) (PeerIdentity, bool)
PeerIdentityFrom extracts the peer identity from ctx. The boolean reports whether the key was present; absent → zero-value PeerIdentity{} + false.
CALLERS MUST CHECK ok BEFORE USING THE IDENTITY. Absent means the request did not pass through runtime/http/middleware.MTLS (e.g. mTLS not on this listener, or the request hit a non-mTLS auth chain). Using the zero-value PeerIdentity{} as if it were a real identity is a silent bug — it has an empty CN, nil DNSNames, and nil URIs that would compare equal to other zero values.
Source Files