v1.0.0¶

Overview¶

ContextR v1.0.0 is the first stable release of the context propagation library for distributed .NET systems.

ContextR provides a structured, unified model for propagating request, tenant, user, and operational metadata across async boundaries, HTTP, gRPC, and background processing -- without leaking transport concerns into business code.

Build once. Propagate everywhere.

Documentation: arttonoyan.github.io/ContextR Repository: github.com/arttonoyan/ContextR

Key Features¶

Core Context Model¶

AsyncLocal-based ambient storage with typed context accessors and writers
Snapshot-first model -- immutable snapshots for safe async, background, and cross-scope propagation
Domain-scoped context isolation -- separate context slots per (domain, contextType) pair
Required/optional property contracts via nullability conventions

Property Mapping DSL¶

Fluent MapProperty(c => c.TenantId, "X-Tenant-Id") API for mapping context properties to transport keys
Advanced Map(...) builder for complex mapping configurations
Automatic nullability-based required/optional conventions

Payload Strategies¶

Inline JSON -- serialize complex properties as JSON values in headers
Chunking -- UTF-8-safe split and reassembly for oversized payloads with security limits
Token/Reference -- contracts for out-of-band payload storage and retrieval

Propagation Policies and Failure Handling¶

Configurable oversize behavior: FailFast, SkipProperty, FallbackToToken, ChunkProperty
Domain-aware failure hooks with Throw, SkipProperty, SkipContext actions
Runtime strategy policy selection via IContextPropagationStrategyPolicy<T>

Transport Integrations¶

ASP.NET Core -- automatic incoming context extraction via IStartupFilter and middleware
HttpClient -- outgoing propagation via DelegatingHandler (per-client or global)
gRPC -- client and server interceptors for metadata-based propagation

Ingress Resolution¶

Resolve context from JWT, claims, headers, and other request sources at the gateway edge
External vs. internal trust boundary policies
Domain-specific resolver overrides

Context Signing¶

HMAC-based signing and verification of propagated context headers
Key rotation support with multi-key verification

OpenFeature Integration¶

Map ContextR context into OpenFeature EvaluationContext attributes
Circular reference detection for nested context types

Packages¶

This release includes 12 NuGet packages:

Package	Description
`ContextR`	Core ambient context primitives: accessor, writer, snapshots, domains, scopes
`ContextR.Resolution`	Ingress context resolution abstractions and orchestration
`ContextR.Propagation`	Propagation contracts, failure hooks, and strategy policies
`ContextR.Propagation.Mapping`	Fluent property mapping DSL (`MapProperty`, `Map`)
`ContextR.Propagation.InlineJson`	JSON serialization strategy for complex properties
`ContextR.Propagation.Chunking`	Chunk split/reassembly for oversized payloads
`ContextR.Propagation.Token`	Token/reference propagation contracts
`ContextR.Propagation.Signing`	HMAC signing and verification for propagated context
`ContextR.Hosting.AspNetCore`	ASP.NET Core ingress extraction middleware
`ContextR.Transport.Http`	HttpClient propagation handler
`ContextR.Transport.Grpc`	gRPC client and server propagation interceptors
`ContextR.OpenFeature`	OpenFeature evaluation context integration

Quick Start¶

Install¶

dotnet add package ContextR
dotnet add package ContextR.Propagation
dotnet add package ContextR.Propagation.Mapping
dotnet add package ContextR.Hosting.AspNetCore
dotnet add package ContextR.Transport.Http

Register¶

builder.Services.AddContextR(ctx =>
{
    ctx.Add<UserContext>(reg => reg
        .MapProperty(c => c.TraceId, "X-Trace-Id")
        .MapProperty(c => c.TenantId, "X-Tenant-Id")
        .MapProperty(c => c.UserId, "X-User-Id")
        .UseAspNetCore()
        .UseGlobalHttpPropagation());
});

This gives you: - Incoming middleware that extracts request headers into typed context - Outgoing HttpClient calls that automatically inject mapped headers - Business code that reads context from ContextR abstractions, not transport APIs

For gRPC propagation, add ContextR.Transport.Grpc and call .UseGlobalGrpcPropagation().

Requirements¶

.NET 10.0 or later
C# 13 (latest language version)

Samples¶

Six documented sample scenarios are included in the samples/ directory:

Multi-Tenant SaaS -- tenant, trace, and user propagation across services
Microservices HTTP + gRPC -- mixed transport with shared context model
Background Jobs -- snapshot capture at enqueue, activation in worker
Gateway Ingress Resolution -- JWT to UserContext at the gateway edge
HttpContextAccessor Replacement -- replace IHttpContextAccessor with IContextSnapshot
JWT Adjunct Context -- JWT for auth, ContextR for operational context

Known Limitations¶

Token payload strategy (ContextR.Propagation.Token) provides contracts and interfaces only; a concrete IContextPayloadStore implementation is not included and must be provided by consumers.
Distributed event propagation (message brokers, event buses) is not covered by built-in transport packages. Custom propagators can be built using the IContextPropagator<T> interface.
Samples are provided as documented patterns (README walkthroughs), not as runnable projects.

For Contributors¶

Build: dotnet build ContextR.slnx
Test: dotnet test ContextR.slnx
Docs preview: mkdocs serve
Branch naming: type/short-description (e.g., feat/, fix/, docs/)
Commits: Conventional Commits required
See CONTRIBUTING.md for full guidelines
See SECURITY.md for reporting vulnerabilities

Design Principles¶

Explicit over implicit behavior
Transport-agnostic core with transport-specific extensions
Safe defaults with configurable policies
Testable abstractions first (domain- and execution-scope aware)

License¶

Apache License 2.0

Acknowledgments¶

ContextR was born from practical pain in a real production gateway + microservices architecture. Thank you to everyone who contributed feedback, code reviews, and testing during the pre-release phase.

Full Changelog: https://github.com/arttonoyan/ContextR/commits/v1.0.0