DRN.Framework.Utils 0.9.5

👁 master
👁 develop
👁 Quality Gate Status

👁 Security Rating
👁 Maintainability Rating
👁 Reliability Rating
👁 Vulnerabilities
👁 Bugs
👁 Lines of Code
👁 Coverage

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
• Scoped Logging — IScopedLog aggregates structured logs per request
• Scoped Cancellation — Scoped ICancellationUtils for request lifecycle control
• Validators — Reusable payload validators such as JpegValidator
• Monotonic Pagination — Cursor-based pagination leveraging entity ID temporal ordering
• Bit Packing — High-performance NumberBuilder for custom data structures
• Ambient Context — ScopeContext.UserId, ScopeContext.Settings anywhere
• Auto-Registration — AddServicesWithAttributes() scans and registers all 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
• 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 all 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 anywhere
 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 installation (e.g. Console Apps, Workers):

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

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

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

Manage request-scoped cancellation tokens using ICancellationUtils. It supports merging tokens from multiple sources, such as HttpContext.RequestAborted and application-level timeouts.

public class MyScopedService(ICancellationUtils cancellation)
{
 public async Task DoWorkAsync(CancellationToken externalToken)
 {
 // Automatically merges with the scoped token
 cancellation.Merge(externalToken);
 
 // Use the unified token
 await SomeAsyncOp(cancellation.Token);
 
 if (cancellation.IsCancellationRequested)
 return;
 }
}

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. Automatically triggers EF Core Migrations when the application starts in Development environments (via PostStartupValidationAsync).

// 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(); // redacts secret-looking values by default
 }
}

GetDebugView(includeRawValues: true) only includes raw values in Development. Secret-looking keys and sections are redacted by default in summaries. 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

Override the mount directory by registering IMountedSettingsConventionsOverride.

IAppSettings Troubleshooting

Symptom	Cause	Solution
ConfigurationException on startup	Missing required configuration key	Add the key to appsettings.json or environment variables
GetRequiredConnectionString throws	Connection string not found	Verify key exists under ConnectionStrings section
IsDevelopmentEnvironment always false	ASPNETCORE_ENVIRONMENT not set	Set environment variable or use launchSettings.json
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

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 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.

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 MAC Keys

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

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

MacKeys 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. Key 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	Key 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	Key must Base64-decode to exactly 32 bytes.
Base64UrlEncoded	Key must Base64Url-decode to exactly 32 bytes. This is the format produced by the framework Hash() default.

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 MAC key is configured in the Development environment, AppSettings adds one automatically. This key is deterministic from DrnAppFeatures.SeedKey, not random, and is stored in memory as Format = Base64UrlEncoded.

Logging (IScopedLog)

IScopedLog provides request-scoped structured logging. It aggregates operational data, metrics, and checkpoints during the request lifecycle, flushing them as a single entry for efficient monitoring.

Core Features

• Contextual: Automatically captures TraceId, UserId, RequestPath, and custom scope data.
• 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.
• Resilience: Captures exceptions without interrupting the business flow unless explicitly thrown.

API Usage

public class OrderService(IScopedLog logger)
{
 public void ProcessOrder(int orderId)
 {
 // 1. Measure execution time and count
 // Automatically tracks duration and increments "Stats_ProcessOrder_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
 logger.AddProperties("User", new { Name = "John", Role = "Admin" });
 }
 catch(Exception ex)
 {
 // 5. Log exception but keep the request contextual log intact
 logger.AddException(ex, "Failed to process order");
 }
 }
}

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 })
 .ToJsonAsync<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();
}

Scope & Ambient Context (ScopeContext)

ScopeContext provides ambient access to request-scoped data. This simplifies cross-cutting concerns like auditing, multi-tenancy, and security by avoiding deep parameter passing especially in Razor Pages(.cshtml) files.

• Contextual Identity: Access UserId, TraceId, and Authenticated status anywhere.
• Static Accessors: Provides direct 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.

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")) { ... }

Data Utilities

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>().

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

• JSON Merge Patch: JsonMergePatch.SafeApplyMergePatch follows RFC 7386 for partial updates with built-in recursion depth protection.
• 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.

Pagination

The framework provides IPaginationUtils for high-performance, monotonic cursor-based pagination. It leverages the temporal sequence of SourceKnownEntityId to ensure stable results even as data is being added.

public class OrderService(IPaginationUtils pagination)
{
 public async Task<PaginationResult<Order>> GetRecentOrdersAsync(PaginationRequest request)
 {
 var query = dbContext.Orders.Where(x => x.Active);
 return await pagination.GetResultAsync(query, request);
 }
}

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)

A lock-free, atomic timer implementation that prevents overlapping executions if one cycle takes longer than the period.

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

worker.Stop();

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 using AES-256-ECB 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 from the same keyring entry.

Generation uses the default NexusMacKey. 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 auto-detects encrypted and plaintext IDs — it first checks for plaintext markers, then attempts AES-ECB decryption if markers are absent. Both paths verify MAC 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

Each SourceKnownEntityId (SKEID) packs identity, integrity, time-addressing, and UUID V8 compatibility (RFC 9562 §5.8) into a single 128-bit GUID:

Byte(s)	Purpose
0	Epoch index (8 bits — up to 256 epochs)
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. Each epoch spans approximately 68 years ($2^{31}$ seconds total coverage, split across two halves), starting from 2025-01-01.

Property	Value
Epoch start	2025-01-01
Single epoch duration	~68 years ($2^{31}$ seconds)
Maximum epochs	256 (byte 0)
Total address space	~17,421 monotonic years

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 equals comparand.
TrySetIfNull<T>(ref T?, T)	Sets value only if current is null.
TrySetIfNotEqual<T>(ref T?, T, T?)	Sets value only if current does not equal comparand (retry loop).
TrySetIfNotNull<T>(ref T?, T)	Sets value only if current is not null.

// 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

Highly optimized 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: Uses internal ConcurrentDictionary and record struct keys for zero-allocation cache 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, Path & Binary Extensions

• Casing: ToSnakeCase, ToCamelCase, and ToPascalCase for clean code-to-external system mapping.
• Parsing: string.Parse<T>() and string.TryParse<T>(out result) using the modern IParsable<T> interface.
• Path: NormalizeDirectoryPath() resolves a directory path to a full path and trims trailing separators without trimming filesystem roots. IsPathWithinDirectory() performs full-path containment checks.
• Binary: ToStream() and ToByteArray() shortcuts with UTF8 default.
• FileSystem: GetLines() for IFileInfo with efficient physical path reading.

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() captures exhaustive request/response metadata from Flurl exceptions into IScopedLog.
• Status Codes: GetGatewayStatusCode() maps API errors to standard gateway codes (502, 503, 504).
• 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>();

// Casing for APIs
var key = "MyPropertyName".ToSnakeCase(); // my_property_name

---

Global Usings

global using DRN.Framework.SharedKernel;
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-06-14 21:30:19 +0300
Hash: ebe902574f06c0a2c2c0d8b4b2e28aafbfe418a6