DRN.Framework.Utils 0.9.7

DRN.Framework.Utils

Core utilities package providing attribute-based dependency injection, configuration management, scoped logging, ambient context, and essential extensions.

TL;DR

• Attribute DI — [Scoped<T>], [Singleton<T>], [Transient<T>] for zero-config service registration
• Configuration — IAppSettings with typed access, [Config("Section")] bindings
• App data roots — IAppData resolves temp/data paths with traversal-safe child paths
• Scoped Logging — IScopedLog aggregates structured logs per request
• Scoped Cancellation — Explicit root cancel-all plus stable keyed groups with optional type ownership
• AES-256 single block — Explicit runtime-intrinsic and portable paths with automatic fallback
• Validators — Reusable payload validators such as JpegValidator
• Monotonic Pagination — Cursor-based pagination leveraging entity ID temporal ordering
• Bit Packing — NumberBuilder for compact custom data structures
• Ambient Context — ScopeContext.UserId and ScopeContext.Settings within initialized DRN Hosting request scopes
• Auto-Registration — AddServicesWithAttributes() scans and registers public, concrete attributed services
• SourceKnownEntityId utilities — generation, validation, secure/plain conversion, auto-detecting Parse

Table of Contents

• QuickStart: Beginner
• QuickStart: Advanced
• Setup
• Dependency Injection
• Configuration
• Logging (IScopedLog)
• HTTP Client Factories (IExternalRequest, IInternalRequest)
• Scope & Ambient Context (ScopeContext)
• Data Utilities
• Validators
• Pagination
• Bit Packing
• Diagnostics
• Time & Async
• Concurrency
• Extensions
• Suggested Consumer Global Usings
• Related Packages

---

QuickStart: Beginner

Register and use a service with attribute-based DI:

// 1. Define your service with DI attribute
public interface IGreetingService { string Greet(string name); }

[Scoped<IGreetingService>]
public class GreetingService : IGreetingService
{
    public string Greet(string name) => $"Hello, {name}!";
}

// 2. Register public, concrete attributed services in Startup
services.AddServicesWithAttributes();

// 3. Inject and use
public class HomeController(IGreetingService greetingService) : Controller
{
    public IActionResult Index() => Ok(greetingService.Greet("World"));
}

QuickStart: Advanced

Complete example with configuration binding, scoped logging, and ambient context:

// Bind configuration section to strongly-typed class
[Config]
public class PaymentSettings
{
    public string ApiKey { get; set; } = "";
    public int TimeoutSeconds { get; set; } = 30;
}

// Service using scoped logging and settings
[Scoped<IPaymentService>]
public class PaymentService(IAppSettings settings, IScopedLog log, PaymentSettings config) : IPaymentService
{
    public async Task<PaymentResult> ProcessAsync(decimal amount)
    {
        // Track execution time
        using var duration = log.Measure("PaymentProcessing");
        
        // Add structured context
        log.Add("Amount", amount);
        log.AddToActions("Processing payment");
        
        // Access ambient data inside an initialized DRN Hosting request scope
        var userId = ScopeContext.UserId;
        
        // Use typed configuration
        if (config.TimeoutSeconds < 10)
            throw ExceptionFor.Configuration("Timeout too short");
        
        return new PaymentResult(Success: true);
    }
}

---

Setup

For manual registration (e.g. Console Apps, Workers):

// Registers attributes, HybridCache, and TimeProvider
builder.Services.AddDrnUtils();

AddDrnUtils() does not create an ambient ScopeContext; console and worker code should use injected services.

HybridCache Registration

AddDrnUtils() registers Microsoft's HybridCache with default in-memory caching. To configure distributed caching (e.g., Redis), add your IDistributedCache registration before calling AddDrnUtils():

// Optional: Add distributed cache backend
builder.Services.AddStackExchangeRedisCache(options => 
{
    options.Configuration = "localhost:6379";
});

// HybridCache will use the distributed cache if available
builder.Services.AddDrnUtils();

For DRN Hosting rate limiting, use HybridCache to cache tenant plan, feature flag, or quota policy data. Do not treat HybridCache / IDistributedCache as an atomic distributed rate-limit counter by itself; hard multi-instance quotas need a backend designed for atomic operations, such as Redis with server-side Lua scripts, or enforcement at an API gateway/CDN/WAF layer.

Dependency Injection

Attribute-Based Registration

Reduce configuration boilerplate by using attributes directly on services. AddServicesWithAttributes() scans the calling assembly by default; pass an Assembly argument to scan a specific target assembly.

Attribute	Lifetime	Usage
[Singleton<T>]	Singleton	[Singleton<IMyService>] public class MyService : IMyService
[Scoped<T>]	Scoped	[Scoped<IMyService>] public class MyService : IMyService
[Transient<T>]	Transient	[Transient<IMyService>] public class MyService : IMyService
[SingletonWithKey<T>]	Singleton (Keyed)	[SingletonWithKey<IMyService>("key")]
[ScopedWithKey<T>]	Scoped (Keyed)	[ScopedWithKey<IMyService>("key")]
[TransientWithKey<T>]	Transient (Keyed)	[TransientWithKey<IMyService>("key")]
[HostedService]	Singleton	[HostedService] public class MyWorker : BackgroundService
[Config]	Singleton	[Config("Section")] public class MySettings
[ConfigRoot]	Singleton	[ConfigRoot] public class RootSettings

Assembly scan metadata is cached, while registration modules and startup-validation state remain isolated to each service collection and provider. Repeating registration for the same assembly on one service collection is idempotent.

Hosted Services

Use [HostedService] to register IHostedService/BackgroundService implementations without manual AddHostedService<T>() calls. The class must implement IHostedService; otherwise the attribute is silently ignored.

[HostedService]
public class MyBackgroundWorker : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Do periodic work
            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }
    }
}

Validation & Testing

• Validation: Ensure all registrations are resolvable via ValidateServicesAddedByAttributesAsync().

// In Program.cs
await app.Services.ValidateServicesAddedByAttributesAsync();

In integration tests with DRN.Framework.Testing:

[Theory, DataInline]
public async Task Validate_Dependencies(DrnTestContext context)
{
    context.ServiceCollection.AddServicesWithAttributes(); // Register local assembly
    await context.ValidateServicesAsync(); // Verifies attribute-registered services can be resolved
}

Scoped Cancellation

ICancellationUtils owns a root and keyed child scopes within the current DI service scope.

Intent	API	Effect
Cancel all scoped work	cancellation.Root.Cancel() or cancellation.Root.Merge(token)	Reaches every existing and later-created child.
Cancel a component or workflow	GetOrCreateScope(key).Cancel() or .Merge(token)	Affects only that group.
Cancel one operation	A local linked CancellationTokenSource	Affects only caller-owned work.

public sealed class CheckoutWorkflow(ICancellationUtils cancellation)
{
    private static readonly CancellationScopeKey ScopeKey =
        CancellationScopeKey.For<CheckoutWorkflow>();

    public async Task RunAsync(
        CancellationToken workflowLifetimeToken,
        CancellationToken operationToken)
    {
        var scope = cancellation.GetOrCreateScope(ScopeKey);

        using var operationSource = CancellationTokenSource
            .CreateLinkedTokenSource(scope.Token, workflowLifetimeToken, operationToken);

        await SomeAsyncOp(operationSource.Token);
    }

    public void CancelWorkflow() => cancellation.GetOrCreateScope(ScopeKey).Cancel();

    public void CancelEverything() => cancellation.Root.Cancel();
}

The same key returns the same scope and token. Root cancellation reaches every child, while child cancellation does not affect the root or other groups. Canceled scopes cannot be reset.

Keys can be type-owned or ownerless. Prefer CancellationScopeKey.For<T>() for a compile-time type or For(Type) for a runtime type. Add a name with For<T>(name) or For(Type, name) when one type owns multiple intentional groups. Use CancellationScopeKey.For(name) only when different types intentionally share one group.

Names use ordinal, case-sensitive equality and must be non-null developer-defined constants of at most 128 characters (empty string and whitespace are permitted). Keys are opaque and factory-created; the default value is invalid.

Ownerless keys share one ordinal-name namespace within the current ICancellationUtils service scope. Although empty and whitespace names are valid, prefer qualified, centrally defined names such as "MyPackage.CheckoutShutdown", because unrelated callers using the same ownerless name receive the same scope and can cancel each other's work.

Do not derive keys from request data, user input, instance IDs, or operation IDs because these values represent individual work rather than shared component or workflow lifetimes. ICancellationUtils owns returned scopes; callers own and dispose local linked sources.

For root-wide migration, replace cancellation.Cancel(), Merge(token), Token, and IsCancellationRequested with their cancellation.Root equivalents.

Module Registration & Startup Actions

Services can require complex registration logic or post-startup actions. Attributes inheriting from ServiceRegistrationAttribute handle this.

Example: DrnContext<T> (in DRN.Framework.EntityFramework) is decorated with [DrnContextServiceRegistration], which:

1. Registers the DbContext.
2. Runs startup migration handling; Development auto-migration occurs when DrnDevelopmentSettings:AutoMigrateDevelopment is enabled (default: true).

// The base class DrnContext handles the registration attributes.
// You just inherit from it, and your context is auto-registered with migration support.
public class MyDbContext : DrnContext<MyDbContext> { }

Configuration

IAppSettings

Access configuration using strongly-typed environment checks and utility methods.

public class MyService(IAppSettings settings)
{
    public void DoWork()
    {
        if (settings.IsDevelopmentEnvironment) { /* dev-only logic */ }
        if (settings.IsStagingEnvironment) { /* staging-only logic */ }
        
        var conn = settings.GetRequiredConnectionString("Default");
        var value = settings.GetValue<int>("MySettings:Timeout", 30);
        var debugSummary = settings.GetDebugView().ToSummary(); // best-effort key-name redaction
    }
}

GetDebugView(includeRawValues: true) only includes raw values in Development. Summaries apply best-effort key-name redaction, not a complete security boundary; review them before logging or exposure. Child keys remain listed even when a provider also defines a scalar value for the parent section, and summary paths use the value provider's key casing. Object-based configuration helpers serialize through the framework JSON defaults and therefore use camelCase keys; explicit key/value configuration preserves the key text supplied by the caller.

Configuration Attributes ([Config])

Bind classes directly to configuration sections. These are registered as Singletons.

[Config("PaymentSettings")] // Binds to "PaymentSettings" section
public class PaymentOptions 
{ 
    public string ApiKey { get; set; }
}

[Config] // Binds to "FeatureFlags" section (class name)
public class FeatureFlags { ... }

[ConfigRoot] // Binds to root configuration
public class RootSettings { ... }

Configuration Sources

The framework automatically loads configuration in this order:

1. appsettings.json
2. appsettings.{Environment}.json
3. User Secrets when the application assembly is available
4. Environment variables (ASPNETCORE_, DOTNET_, then unprefixed)
5. Mounted Settings:
   • /appconfig/key-per-file-settings/*
   • /appconfig/json-settings/*.json
6. Command-line arguments

Environment is required and must be Development, Staging, or Production. DRN validates the value used to select appsettings.{Environment}.json; define it in appsettings.json, environment variables, mounted settings, or command-line arguments, and do not override it in environment-specific JSON or user secrets.

Override the mount directory by registering IMountedSettingsConventionsOverride.

IAppSettings Troubleshooting

Symptom	Cause	Solution
ConfigurationException on startup	Missing or invalid required configuration	Inspect the reported key and correct its source value
Environment setting is missing	Required Environment key not configured	Set Environment to Development, Staging, or Production in appsettings.json, environment variables, mounted settings, or command-line arguments
GetRequiredConnectionString throws	Connection string not found	Verify key exists under ConnectionStrings section
IsDevelopmentEnvironment always false	Resolved Environment is not Development	Set the Environment configuration key to Development in an applicable source
Mounted settings not loading	Wrong mount path	Verify files exist at /appconfig/json-settings/ or override via IMountedSettingsConventionsOverride
Environment variables not binding	Wrong naming format	Use __ (double underscore) for nested keys: MySection__MyKey

App Data Settings

DrnAppDataSettings controls required temp/data roots. Overrides use process environment variables because roots resolve before DRN configuration.

Environment variable	Purpose
DrnAppDataSettings__TempPath	Overrides the temp base; the resolved temp path is <TempPath>/<EntryAssemblyNameNormalized>.
DrnAppDataSettings__DataPath	Overrides the resolved data root as <DataPath>; the resolved temp path is <DataPath>/Temp/<EntryAssemblyNameNormalized> when temp is unset.

Set DrnAppDataSettings:RequireTemp or DrnAppDataSettings:RequireData to fail startup when the resolved path is not valid.

DrnAppFeatures

Feature flags and runtime knobs bound from the DrnAppFeatures configuration section via [Config].

{
  "DrnAppFeatures": {
    "SeedData": false,
    "SeedKey": "Peace at home! Peace in the world! - Mustafa Kemal Atatürk (1931)",
    "DisableRequestBuffering": false,
    "MaxRequestBufferingSize": 0,
    "DrnRateLimit": {
      "Disabled": false,
      "TokenLimit": 100,
      "ReplenishmentSeconds": 60,
      "TokensPerPeriod": 100,
      "PreAuthTokenLimit": 1000,
      "PreAuthReplenishmentSeconds": 60,
      "PreAuthTokensPerPeriod": 1000,
      "PostAuthTokenLimit": 0,
      "PostAuthReplenishmentSeconds": 0,
      "PostAuthTokensPerPeriod": 0
    }
  }
}

DrnRateLimit is the configuration key; application code reads the same settings through IAppSettings.Features.RateLimit. Shared values apply to both DRN Hosting rate limiting phases. Phase-specific values set to 0 inherit the shared value; positive phase-specific values override it. Treat these values as global defaults; tenant plan, feature-flag, and account-specific quotas belong in DRN Hosting rate-limit rules. See the Hosting README rate limiting settings for operational guidance, endpoint metadata behavior, and production scaling notes.

Nested option objects must be validated explicitly before relying on child data annotations for startup safety. DrnAppFeatures validates DrnRateLimit as part of root validation because plain Validator.TryValidateObject does not recursively walk nested objects by itself.

DrnAppFeatures.SeedKey feeds AppSecuritySettings. AppSecuritySettings derives AppHashKey, AppEncryptionKey, AppKey, and AppSeed through BLAKE3 derive-key mode with distinct DRN Framework context strings. AppHashKey and AppEncryptionKey remain Base64Url-encoded 32-byte values, AppKey remains an 8-character public discriminator, and AppSeed remains a signed 64-bit seed value. Changing SeedKey changes app-specific names, rate-limit keyed hash outputs, Development default Nexus key material, and seed-dependent operations.

Property	Type	Default	Description
ApplicationStartedBy	string?	null	Identifies which test started the application (set automatically by DrnTestContext).
SeedData	bool	false	Enables data seeding on startup.
SeedKey	string	"Peace at home!…"	Secret key for seed operations. Enforced [SecureKey(MinLength = 58)].
InternalRequestHttpVersion	string	"1.1"	HTTP version used by IInternalRequest.
InternalRequestProtocol	string	"http"	Protocol scheme used by IInternalRequest (e.g., http, https).
UseMonotonicDateTimeProvider	bool	false	Reserved experimental flag for monotonic time-provider behavior data; it is not wired as a provider switch.
DisableRequestBuffering	bool	false	Disables request body buffering entirely. Use for high-throughput services (e.g., file upload endpoints).
MaxRequestBufferingSize	int	0 (→ 30,000)	Maximum request body size to buffer in bytes. Values below 10,000 are ignored; 0 uses the 30,000-byte default.
DrnRateLimit.Disabled	bool	false	Disables both pre-auth and post-auth DRN Hosting rate limiting layers.
DrnRateLimit.PartitionLogMode	RateLimitPartitionLogMode	KeyedHash	Controls rejected IP/partition logging. KeyedHash logs deterministic keyed hashes for correlation; PlainText logs raw values and should be limited to controlled development or dedicated audit sinks.
DrnRateLimit.TokenLimit	int	100	Token bucket burst capacity. Must be positive.
DrnRateLimit.ReplenishmentSeconds	int	60	Token replenishment period in seconds. Must be positive.
DrnRateLimit.TokensPerPeriod	int	100	Tokens added per replenishment period. Must be positive.
DrnRateLimit.PreAuthTokenLimit	int	1000	Coarse pre-auth burst capacity for shared B2B NAT/VPN/CDN egress addresses. 0 inherits TokenLimit.
DrnRateLimit.PreAuthReplenishmentSeconds	int	60	Pre-auth replenishment period. 0 inherits ReplenishmentSeconds.
DrnRateLimit.PreAuthTokensPerPeriod	int	1000	Pre-auth tokens per period. 0 inherits TokensPerPeriod.
DrnRateLimit.PostAuthTokenLimit	int	0	Optional post-auth burst capacity. 0 inherits TokenLimit.
DrnRateLimit.PostAuthReplenishmentSeconds	int	0	Optional post-auth replenishment period. 0 inherits ReplenishmentSeconds.
DrnRateLimit.PostAuthTokensPerPeriod	int	0	Optional post-auth tokens per period. 0 inherits TokensPerPeriod.

NexusAppSettings and Nexus Keys

NexusAppSettings provides Nexus routing, source-known ID generator identity, secure/plain ID mode, and the Nexus key ring used by SourceKnownEntityIdUtils.

{
  "NexusAppSettings": {
    "NexusAddress": "localhost:5988",
    "AppId": 5,
    "AppInstanceId": 12,
    "UseSecureSourceKnownIds": true,
    "Keys": [
      {
        "KeyMaterial": "0123456789abcdef0123456789abcdef",
        "Format": "Utf8",
        "Default": true
      }
    ]
  }
}

Keys must contain exactly one default key. Generation always uses the default key. Parsing tries the default key first and then the remaining configured keys, so old IDs remain parseable during key rotation while the previous key stays in the key ring.

ByteEncoding	Requirement
Utf8	Default when omitted. KeyMaterial must be exactly 32 UTF-8 bytes. ASCII 32-character values satisfy this; non-ASCII values are valid only when the UTF-8 byte count is exactly 32.
Hex	KeyMaterial must hex-decode to exactly 32 bytes, normally 64 hex characters. A 32-character hex string is rejected because it decodes to 16 bytes.
Base64	KeyMaterial must Base64-decode to exactly 32 bytes.
Base64UrlEncoded	KeyMaterial must Base64Url-decode to exactly 32 bytes. This is the format used by Development default key-material generation.

Invalid user-provided keys are not hashed, stretched, truncated, repaired, or treated as another format. Startup validation rejects malformed encodings, empty keys, wrong decoded lengths, and raw values that are not exactly 32 UTF-8 bytes. Exception messages avoid including the secret key value.

When no default Nexus key is configured in the Development environment, AppSettings derives deterministic 32-byte key material from AppSecuritySettings context-derived values with BLAKE3 derive-key mode. DrnAppFeatures.SeedKey feeds AppSecuritySettings. The generated key material is not random, is stored in memory as Format = Base64UrlEncoded, and then goes through the same BLAKE3 derive-key separation as configured keys.

Logging (IScopedLog)

IScopedLog aggregates structured operational data, metrics, checkpoints, and exceptions for a logical scope. In DRN Hosting request scopes, Hosting enriches and emits that aggregate as a single log entry.

Core Features

• Contextual: DRN Hosting request scopes add TraceId, UserId, and RequestPath; custom ScopeData remains separate unless added explicitly.
• Aggregation: Groups all actions, metrics, and exceptions into a single structured log entry.
• Performance Tracking: Built-in measurement for code block durations and execution counts.
• Exception Recording: AddException records exception details without changing control flow; callers remain responsible for recovery, rethrowing, and excluding sensitive data.

API Usage

public class OrderService(IScopedLog logger)
{
    public void ProcessOrder(int orderId)
    {
        // 1. Measure execution time and count
        using var _ = logger.Measure("ProcessOrder"); 
        
        // 2. Add structured data (Key-Value)
        logger.Add("OrderId", orderId); 
        logger.AddIfNotNullOrEmpty("Referrer", "PartnerA");

        // 3. Track execution checkpoints
        logger.AddToActions("Validating order"); 
        
        try 
        {
            // ... logic ...
            // 4. Flatten and add complex objects that are safe to log
            logger.AddProperties("User", new { Name = "John", Role = "Admin" });
        }
        catch(Exception ex)
        {
            // 5. Record the exception, then preserve failure semantics
            logger.AddException(ex, "Failed to process order");
            throw;
        }
    }
}

HTTP Client Factories (IExternalRequest, IInternalRequest)

Wrappers around Flurl for HTTP clients with standardized JSON conventions and HTTP version policy configuration. Retries/circuit breakers are not configured by this package.

External Requests

Use IExternalRequest for standard external API calls. It pre-configures DefaultJsonSerializer and enforces HTTP version policies.

public class PaymentService(IExternalRequest request)
{
    public async Task Process()
    {
        // Enforces exact HTTP version for better compatibility with modern APIs
        var response = await request.For("https://api.example.com", HttpVersion.Version11)
            .AppendPathSegment("v1/charges")
            .PostJsonAsync(new { Amount = 1000 })
            .FromJsonAsync<ExternalApiResponse>();
    }
}

Internal Requests (Service Mesh)

Use IInternalRequest for Service-to-Service communication in Kubernetes. It's designed to work with Linkerd, supporting automatic protocol switching (HTTP/HTTPS) based on infrastructure settings.

Recommended Pattern: Request Wrappers

Instead of using IInternalRequest directly in business logic, wrap it in a typed request factory for better maintainability and configuration encapsulation.

// 1. Definition (External Factory Wrapper)
public interface INexusRequest { IFlurlRequest For(string path); }

[Singleton<INexusRequest>]
public class NexusRequest(IInternalRequest request, IAppSettings settings) : INexusRequest
{
    private readonly string _nexusAddress = settings.NexusAppSettings.NexusAddress;
    public IFlurlRequest For(string path) => request.For(_nexusAddress).AppendPathSegment(path);
}

// 2. Client Usage
public class NexusClient(INexusRequest request) : INexusClient
{
    public async Task<HttpResponse<string>> GetStatusAsync() =>
        await request.For("status").GetAsync().ToStringAsync();
}

Buffered response converters (ToStringAsync, ToBytesAsync, and FromJsonAsync) capture HttpStatus and Payload, then dispose the response even if reading or deserialization fails. Call converters as extension methods on Task<IFlurlResponse> or IFlurlResponse; HttpResponse models the converted result and no longer exposes static conversion entry points.

HttpResponse.StatusClass classifies the status as Informational, Success, Redirection, ClientError, ServerError, or Unknown; IsSuccessStatusCode is true only for 2xx. Flurl normally follows redirects, so a 3xx snapshot represents a redirect that remained final. Use AllowAnyHttpStatus() when the throwing converters should return non-success responses for direct inspection.

Use the TryToStringAsync, TryToBytesAsync, or TryFromJsonAsync<T> counterparts when transport, timeout, response-read, or deserialization failures must be inspected without catching exceptions:

var result = await request.For("status").GetAsync().TryFromJsonAsync<StatusResponse>();
if (result.Failure is { } failure)
{
    // Apply failure policy here; Payload may be unavailable.
    logger.LogWarning("HTTP conversion failed: {Kind}", failure.Kind);
}

if (result.StatusClass == HttpStatusClass.ClientError)
{
    // Handle 4xx. HttpStatus and a successfully converted Payload remain available.
}
else if (result.StatusClass == HttpStatusClass.ServerError)
{
    // Handle 5xx according to the caller's retry policy.
}

HTTP error statuses and processing failures are independent. For example, a 422 with readable JSON has StatusClass.ClientError and no Failure, while malformed JSON returned with 200 has StatusClass.Success, IsSuccess == false, and Failure.Kind == Deserialization. Try converters propagate cancellation. HttpFailure.Message and HttpFailure.Exception are available for local diagnostics, may contain request details, and must be redacted before logging or exposure; both are ignored by System.Text.Json serialization.

Call result.ThrowIfFailure() after inspection to rethrow a captured transport, timeout, response-read, or deserialization exception with its original stack preserved. The method does not throw for a 3xx, 4xx, or 5xx response without a processing failure; inspect StatusClass or IsSuccessStatusCode when status enforcement is required.

Use using for streaming responses so the payload and response are released together:

using var response = await request.For("export").GetAsync().ToStreamAsync();
await response.Payload!.CopyToAsync(destination);

HttpResponse<T>.Dispose() is idempotent and disposes any IDisposable payload. TryToStreamAsync() transfers the same ownership to HttpCallResult<T>; dispose that result after consuming its stream payload.

Scope & Ambient Context (ScopeContext)

ScopeContext provides ambient access to request-scoped data after a DRN Hosting request scope has been initialized. Use injected services during startup, in background work, and outside request scopes.

• Contextual Identity: Access UserId, TraceId, and Authenticated status within an initialized request scope.
• Static Accessors: Provides request-scope access to IAppSettings, IScopedLog, and IServiceProvider.
• RBAC Helpers: Built-in support for role and claim checks.
• Test Initialization: ScopeContext.InitializeForTest(...) resets the async-local scope before seeding test services, user, log, and trace data.

IScopedUser exposes authenticated identity and claim state. Use GetClaimParameter<TValue> for typed claims; ScopeContext.GetClaimParameter<TValue> provides ambient access to the same contract.

ScopeData is separate caller-owned ambient storage and is not automatically copied into IScopedLog. Use SetFlag and typed SetParameter values for validated application data.

var currentUserId = ScopeContext.UserId;
var traceId = ScopeContext.TraceId;
var settings = ScopeContext.Settings; // Static IAppSettings access
var logger = ScopeContext.Log; // Static IScopedLog access

if (ScopeContext.IsUserInRole("Admin")) { ... }

var tenantId = ScopeContext.GetClaimParameter<Guid>("tenant-id");
ScopeContext.Data.SetFlag("show-preview", true);
ScopeContext.Data.SetParameter("page-size", 50);

Data Utilities

App Data Roots (IAppData)

IAppData exposes validated temp/data roots. Normal startup recreates temp; DRN test contexts preserve sibling test data.

public class ExportService(IAppData appData)
{
    public string GetExportPath(string fileName) =>
        appData.Temp.GetPath("exports", fileName);
}

Use AppDataPathResult.GetPath(...) for traversal-safe child paths.

Encodings (EncodingExtensions)

Unified API for binary-to-text encodings and model serialization-encoding.

• Encodings: Base64, Base64Url (Safe for URLs), Hex, and Utf8.
• Integrated: model.Encode(ByteEncoding.Hex) and hexString.Decode<TModel>(ByteEncoding.Hex).

AES-256 Single-Block Encryption (Aes256)

Aes256 accepts and returns one Vector128<byte> block. It exposes explicit x86/ARM runtime-intrinsic and portable .NET AES paths; the default Encrypt and Decrypt methods select runtime intrinsics when available and otherwise use the portable provider. Construction therefore remains portable, while explicit runtime-intrinsic methods throw PlatformNotSupportedException on unsupported hosts.

Methods	Implementation
Encrypt / Decrypt	Runtime intrinsics with automatic portable fallback
EncryptRuntimeIntrinsics / DecryptRuntimeIntrinsics	Explicit x86 AES-NI or ARM AES intrinsics
EncryptWithFramework / DecryptWithFramework	Explicit cross-platform .NET AES provider

A live instance supports concurrent calls. Intrinsic operations read pre-expanded round keys without locks or per-call allocation. On .NET 10.0.10, framework-provider operations are also lock-free because each call creates its own cipher state without mutating the configured key. Reverify this framework-provider assumption when changing the target runtime. Dispose the instance after all callers finish to clear the intrinsic schedules and dispose portable key state.

using var aes = new Aes256(key);
Vector128<byte> ciphertext = aes.Encrypt(plaintext);
Vector128<byte> recovered = aes.Decrypt(ciphertext);

Vector128<byte> portableCiphertext = aes.EncryptWithFramework(plaintext);
if (Aes256.IsSupported)
{
    Vector128<byte> intrinsicPlaintext = aes.DecryptRuntimeIntrinsics(portableCiphertext);
}

Hashing (HashExtensions)

High-performance hashing extensions supporting modern and legacy algorithms.

• Blake3: Default modern cryptographic hash (fast and secure).
• XxHash3: Non-cryptographic hashing for performance-critical scenarios (IDs, Cache keys).
• Security: Keyed hashing support (HashWithKey) for integrity protection.
• Streams: Stream overloads hash files and large payloads without first materializing them as BinaryData; prefer these overloads for file and upload hashing.

JSON & Document Utilities

• Safe JSON Merge Patch: JsonMergePatch.SafeApplyMergePatch(target, patch) implements RFC 7396 processing semantics without mutating either input. Semantic no-ops reuse the target; changed object targets are cloned once and merged without repeated subtree cloning. MergeResult is a readonly record struct, Json is nullable for a root-level JSON null result, and Changed reports only actual document changes.
• In-Place JSON Merge Patch: JsonMergePatch.ApplyMergePatchInPlace(ref target, patch) and ApplyMergePatchInPlace(targetObject, patchObject) perform full RFC 7396 merge patch operations directly in-place, preserving existing nested object references and updating the ref target reference if the root type changes.
• Resource Safety: All merge methods validate the complete patch depth before applying changes. The repository unit suite includes every RFC 7396 Appendix A example.
• Query String Serialization: QueryParameterSerializer flattens complex nested objects/arrays into clean query strings for API clients.

Serialization & Streams

• Unified Extensions: model.Serialize(method) supports both JSON and Query String formats.
• Safe Stream Consumption: ToBinaryDataAsync and ToArrayAsync extensions with MaxSizeGuard to prevent memory exhaustion from untrusted streams.

Programmatic Validation

Extensions for programmatic validation using System.ComponentModel.DataAnnotations.

• Contextual: Integrates with DRN.Framework.SharedKernel.ValidationException for standardized error reporting across layers.

Entity Creation-Date Filters (IEntityDateTimeUtils)

IEntityDateTimeUtils filters SourceKnownEntity.Id by its 250ms Source-Known ID creation tick without requiring database timestamp columns. Each date boundary maps to minimum and maximum scalar long ID bounds for efficient query evaluation.

public class OrderService(IEntityDateTimeUtils dateTimeUtils)
{
    public IQueryable<Order> GetOrdersInDateRange(IQueryable<Order> query, DateTimeOffset start, DateTimeOffset end)
    {
        return dateTimeUtils.CreatedBetween(query, start, end, inclusive: true);
    }
}

Filter	Inclusive boundary	Exclusive boundary
CreatedAfter	Id >= tick.Min	Id > tick.Max
CreatedBefore	Id <= tick.Max	Id < tick.Min
CreatedBetween	Id >= begin.Min && Id <= end.Max	Id > begin.Max && Id < end.Min
CreatedOutside	Id <= begin.Max \|\| Id >= end.Min	Id < begin.Min \|\| Id > end.Max

Pagination

The framework provides IPaginationUtils for cursor-based pagination ordered by the temporal sequence of SourceKnownEntityId.

public class OrderDto(Order order) : Dto(order)
{
    public bool Active { get; } = order.Active;
}

public class OrderService(IPaginationUtils pagination, OrderDbContext dbContext)
{
    public async Task<PaginationResultModel<OrderDto>> GetRecentOrdersAsync(PaginationRequest request)
    {
        var query = dbContext.Orders.Where(x => x.Active);
        var result = await pagination.GetResultAsync(query, request);
        return result.ToModel(order => new OrderDto(order));
    }
}

Bit Packing

For scenarios requiring custom ID generation or compact binary data structures, use NumberBuilder and NumberParser. NumberBuilder<TNumber> is a ref struct; NumberParser is a value-type parser for low-allocation bit manipulation.

// Use NumberBuilder to pack data into a long
var builder = NumberBuilder.GetLong();
builder.TryAddNibble(0x05);  // Add 4 bits
builder.TryAddUShort(65535); // Add 16 bits
long packedValue = builder.GetValue();

// Use NumberParser to unpack
var parser = NumberParser.Get(packedValue);
byte nibble = parser.ReadNibble();
ushort value = parser.ReadUShort();

// Multi-format serialization
var json = model.Serialize(SerializationMethod.SystemTextJson);
var query = model.Serialize(SerializationMethod.QueryString);

// Data Integrity
var hash = data.Hash(HashAlgorithm.Blake3);
var fileHash = fileStream.Hash(HashAlgorithm.Sha256);

// Secure stream conversion
var bytes = await requestStream.ToBinaryDataAsync(maxSize: 1024 * 1024);

Validators

Reusable validators live under DRN.Framework.Utils.Validators.

using DRN.Framework.Utils.Validators;

var validation = await JpegValidator.ValidateAsync(requestStream, maxLength: 1024 * 1024);
if (!validation.IsValid)
{
    var message = validation.ErrorReason switch
    {
        JpegValidationErrorReason.MaxLengthExceeded => "Profile picture exceeds the maximum allowed size.",
        JpegValidationErrorReason.InvalidMaxLength => "Profile picture maximum size must be zero or greater.",
        _ => "Profile picture must be a valid JPEG image."
    };
    throw ExceptionFor.Validation(message);
}

var imageBytes = validation.ImageData;

JpegValidator performs structural JPEG checks for markers, segment bounds, frame metadata, scan metadata, scan data presence, and optional maximum byte length. JpegValidationResult.ErrorReason distinguishes MaxLengthExceeded, InvalidMaxLength, and InvalidJpeg failures. Use ValidateAsync when validating an upload stream and keeping the validated bytes for persistence.

Diagnostics

Development Status

Track database migration status and pending model changes in real-time during development.

public class StartupService(DevelopmentStatus status, IScopedLog log)
{
    public void CheckStatus()
    {
        if (status.HasPendingChanges)
        {
            log.AddToActions("Warning: Pending database changes detected");
            foreach (var model in status.Models)
            {
                 model.LogChanges(log, "Development");
            }
        }
    }
}

Time & Async

High-Performance Time (TimeStampManager)

For systems requiring frequent timestamp lookups (like ID generation or rate limiting), TimeStampManager provides a cached UTC timestamp updated periodically (default 10ms) to reduce DateTimeOffset.UtcNow overhead.

long precisionTicks = TimeStampManager.CurrentTimestamp(EpochTimeUtils.DefaultEpoch);
DateTimeOffset now = TimeStampManager.UtcNow; // Cached UTC time truncated to 250ms precision

Async-Safe Timer (RecurringAction)

An atomic timer implementation that prevents overlapping executions if one cycle takes longer than the period.

using var worker = new RecurringAction(async () => {
    await DoHeavyWork();
}, period: 1000, start: true);

worker.Stop();
worker.Start(); // Resume after stopping

Stop() prevents an active callback from rescheduling the timer after it completes. The callback itself is allowed to finish.

ID Generation & Validation

SourceKnownEntity ID's provide reversible, type-safe, and integrity-checked identifiers.

Generation Modes

The Generate method dispatches to secure or plain generation based on the UseSecureSourceKnownIds flag in NexusAppSettings (defaults to true). Explicit GenerateSecure and GeneratePlain methods are also available to bypass the flag.

Method	Behavior
Generate	Dispatches to secure or plain based on UseSecureSourceKnownIds
GenerateSecure	AES-256-ECB encrypted — full 16-byte GUID is a ciphertext block
GeneratePlain	Plaintext with visible 8D8D version/variant markers
ToSecure	Converts a plain ID to its secure form (idempotent)
ToPlain	Converts a secure ID to its plain form (idempotent)

Secure variant encrypts the entire 16-byte GUID with Aes256 as a pseudo-random permutation (PRP). For a single 128-bit block, ECB is mathematically identical to CBC with a zero IV — no nonce required, no nonce-reuse vulnerability. Key separation ensures BLAKE3 keyed MAC (integrity) and AES-256 (confidentiality) use cryptographically independent keys derived from the same decoded NexusKey material.

Generation uses the default NexusKey. Parse uses a default-first key-ring fallback, so IDs generated before key rotation can still be parsed while the previous key remains configured.

// Generate with flag-based dispatch (secure by default)
var entityId = sourceKnownEntityIdUtils.Generate<User>(id);

// Explicitly secure
var secureId = sourceKnownEntityIdUtils.GenerateSecure<User>(id);

// Explicitly plain (visible markers for debugging/development)
var plainId = sourceKnownEntityIdUtils.GeneratePlain<User>(id);

// Convert between secure and plain forms (idempotent)
var convertedSecureId = sourceKnownEntityIdUtils.ToSecure(plainEntityId);
var convertedPlainId = sourceKnownEntityIdUtils.ToPlain(secureEntityId);

Parse & Validation

Parse accepts secure and plaintext IDs and verifies their integrity.

Users can validate incoming IDs (e.g., from APIs) using multiple approaches depending on the context:

1. Injectable Utility (Recommended for Service Layer)

var sourceKnownId = sourceKnownEntityIdUtils.Validate<User>(externalGuidId);

2. SourceKnownRepository (Recommended for Data Access)

// Method on SourceKnownRepository<TEntity>
var sourceKnownId = userRepository.GetEntityId(externalGuidId); 

3. SourceKnownEntity (Recommended for Domain Logic)

// Helper on SourceKnownEntity base class
var sourceKnownId = userInstance.GetEntityId<User>(externalGuidId);

GUID Byte Layout

The plaintext form of a SourceKnownEntityId (SKEID) packs identity, integrity, time-addressing, and UUID V8 compatibility (RFC 9562 §5.8) into a single 128-bit GUID. Secure IDs are opaque ciphertext and are not guaranteed to retain UUID version or variant bits.

Byte(s)	Purpose
0	Epoch index (8 bits; current releases support epoch 0)
1–4	SKID upper half (32 bits, sign-toggled)
5	SKID low byte 0 (MSB of SKID lower half / timestamp LSB)
6	Version marker (0x8D — UUID V8, RFC 9562 §5.8)
7	Entity type (8 bits — up to 256 entity types)
8	Variant marker (0x8D — RFC 4122 compatible)
9–11	SKID low bytes (remaining 24 bits)
12–15	BLAKE3 keyed MAC (32 bits — integrity verification)

Epoch & Time Addressing

SourceKnownEntityIds use epoch-based time addressing for monotonic ordering. Current releases support the first epoch, which starts on 2025-01-01 and spans approximately 68 years ($2^{31}$ seconds total coverage, split across two halves).

Property	Value
Epoch start	2025-01-01
Supported duration	~68 years ($2^{31}$ seconds)
Supported epoch	0

Time

TimeProvider singleton is registered by default to TimeProvider.System for testable time entry. See Time & Async for high-performance alternatives.

Concurrency

Lock-Free Atomic Utilities (LockUtils)

LockUtils provides static helpers for lock-free atomic operations built on Interlocked. Use these primitives to coordinate concurrent access without OS-level locks.

Method	Purpose
TryClaimLock(ref int)	Atomically claims a lock (0 → 1). Returns true if successful.
TryClaimScope(ref int)	Returns a disposable LockScope that auto-releases on dispose.
ReleaseLock(ref int)	Unconditionally releases a lock (→ 0).
TrySetIfEqual<T>(ref T?, T, T?)	Atomic CAS for reference types; sets value if current is the same reference as comparand.
TrySetIfNull<T>(ref T?, T)	Sets value only if current is null.
TrySetIfNotEqual<T>(ref T?, T, T?)	Sets value only if current is not the same reference as comparand (retry loop).
TrySetIfNotNull<T>(ref T?, T)	Sets value only if current is not null.

TrySetIfNotEqual and TrySetIfNotNull use bounded retries (maxRetries, default 100). A false result can mean either that the comparison condition was not met or that retries were exhausted.

// Disposable lock scope (preferred) — auto-releases on dispose
private int _lock;

using var scope = LockUtils.TryClaimScope(ref _lock);
if (scope.Acquired) { /* critical section */ }

// One-time initialization guard
private MyService? _instance;
var service = new MyService();
LockUtils.TrySetIfNull(ref _instance, service);

Extensions

Comprehensive set of extensions for standard .NET types and reflection.

Reflection & MethodUtils

Reflection helpers with built-in caching for generic and non-generic method invocation.

• Invoke: instance.InvokeMethod("Name", args) and type.InvokeStaticMethod("Name", args).
• Generics: instance.InvokeGenericMethod("Name", typeArgs, args) with static and uncached variations.
• Caching: Caches generic and non-generic method lookups.

Service Collection

Advanced DI container manipulation for testing and modularity.

• Querying: sc.GetAllAssignableTo<TService>() retrieves all descriptors matching a type.
• Replacement: ReplaceScoped, ReplaceSingleton, and ReplaceInstance for mocking/overriding dependencies in integration tests.

String & Binary Extensions

• Parsing: string.Parse<T>() and string.TryParse<T>(out result) using the modern IParsable<T> interface.
• Binary: ToStream() and ToByteArray() shortcuts with UTF8 default.
• FileSystem: GetLines() for IFileInfo with efficient physical path reading.

Casing and safe path helpers live in DRN.Framework.SharedKernel.Extensions.

Type & Assembly Extensions

• Discovery: assembly.GetSubTypes(typeof(T)) and assembly.GetTypesAssignableTo(to).
• Instantiation: assembly.CreateSubTypes<T>() automatically discovers and instantiates classes with parameterless constructors.
• Metadata: type.GetAssemblyName() returns a clean assembly name.

Flurl & HTTP Diagnostics

• Logging: PrepareScopeLogForFlurlExceptionAsync() adds Flurl failure diagnostics to IScopedLog, and DRN Hosting applies it to unhandled Flurl exceptions. Captured request and response data is not automatically redacted; catch sensitive failures before they reach Hosting, or use the Try* converters and log only sanitized fields.
• Status Codes: GetGatewayStatusCode() preserves 4xx, 503, and 504 statuses and maps other statuses to 502.
• Testing: ClearFilteredSetups() utility for complex test scenarios.

Object & Dictionary Extensions

• Deep Discovery: instance.GetGroupedPropertiesOfSubtype(type) recursively finds properties matching a base type across complex object graphs.
• Dictionary Utility: Extensions for IDictionary to handle null-safe value retrieval and manipulation.
• Bit Manipulation: GetBitPositions() for long values and bitmask generators for signed/unsigned lengths.

// Discovery and Instantiation
var implementations = typeof(IMyInterface).Assembly.CreateSubTypes<IMyInterface>();

// Modern Parsing
int value = "123".Parse<int>();

// Binary shortcuts
using var body = "payload".ToStream();

---

Suggested Consumer Global Usings

global using DRN.Framework.SharedKernel;
global using DRN.Framework.SharedKernel.Extensions;
global using DRN.Framework.Utils.DependencyInjection;

---

Related Packages

• DRN.Framework.SharedKernel - Domain primitives and exceptions
• DRN.Framework.EntityFramework - EF Core integration
• DRN.Framework.Hosting - Web application hosting
• DRN.Framework.Testing - Testing utilities

For complete examples, see Sample.Hosted.

---

Documented with the assistance of DiSC OS

---

Semper Progressivus: Always Progressive

Commit Info

Author: Duran Serkan KILIÇ
Date: 2026-07-29 21:49:21 +0300
Hash: ba240f925c31f3f7a9d1d5f2bece8a68b4de8c12