DRN.Framework.Hosting 0.9.5-preview005

DRN.Framework.Hosting

Application shell for DRN web applications with security-first design, structured lifecycle, and type-safe routing.

TL;DR

• Secure by Default - MFA enforced (Fail-Closed), strict CSP with Nonces, HSTS automatic
• Opinionated Startup - DrnProgramBase with 20+ overrideable lifecycle hooks
• Type-Safe Routing - Typed Endpoint and Page accessors replace magic strings
• Zero-Config Infrastructure - Auto-provision Postgres/RabbitMQ in Debug mode
• Frontend Integration - TagHelpers for Vite manifest, CSRF for HTMX, secure assets

Table of Contents

• QuickStart: Beginner
• QuickStart: Advanced
• Directory Structure
• Lifecycle & Execution Flow
• DrnProgramBase Deep Dive
• Configuration
• Security Features
• Endpoint Management
• Razor TagHelpers
• Developer Diagnostics
• Modern HTTP Standards
• GDPR & Consent Integration
• Local Development
• Global Usings
• Related Packages

---

QuickStart: Beginner

DRN web applications inherit from DrnProgramBase<TProgram> to implement standard lifecycle hooks and behaviors.

using DRN.Framework.Hosting.DrnProgram;
using DRN.Framework.Hosting.HealthCheck;

namespace Sample.Hosted;

public class Program : DrnProgramBase<Program>, IDrnProgram
{
    // Entry Point (Runs the opinionated bootstrapping)
    public static async Task Main(string[] args) => await RunAsync(args);

    // [Required] Service Registration Hook
    protected override Task AddServicesAsync(WebApplicationBuilder builder, IAppSettings appSettings, IScopedLog scopedLog)
    {
        builder.Services.AddSampleInfraServices(appSettings);
        builder.Services.AddSampleApplicationServices();
        return Task.CompletedTask;
    }
}

// Immediate API endpoint for testing and health checks (Inherits [AllowAnonymous] and Get())
[Route("[controller]")]
public class WeatherForecastController : WeatherForecastControllerBase;

QuickStart: Advanced

Test your application using DRN.Framework.Testing to spin up the full pipeline including databases.

[Theory, DataInline]
public async Task WeatherForecast_Should_Return_Data(DrnTestContext context, ITestOutputHelper outputHelper)
{
    // Arrange
    var client = await context.ApplicationContext.CreateClientAsync<Program>(outputHelper);
    
    // Act
    var response = await client.GetAsync("WeatherForecast");
    
    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.OK);
    var data = await response.Content.ReadFromJsonAsync<IEnumerable<WeatherForecast>>();
    data.Should().NotBeEmpty();
}

Directory Structure

DRN.Framework.Hosting/
├── DrnProgram/          # DrnProgramBase, options, actions, conventions
├── Endpoints/           # EndpointCollectionBase, PageForBase, type-safe accessors
├── Auth/                # Policies, MFA configuration, requirements
├── BackgroundServices/  # StaticAssetWarmService (pre-warm compressed assets)
├── Consent/             # GDPR cookie consent management
├── Extensions/          # Configuration, controller context, endpoint helpers
├── HealthCheck/         # WeatherForecastControllerBase for quick health checks
├── Identity/            # Identity integration and scoped user middleware
├── Middlewares/         # HttpScopeLogger, exception handling, security middlewares
├── Nexus/               # NexusClient for inter-service HTTP communication
├── TagHelpers/          # Razor TagHelpers (Vite, Nonce, CSRF, Auth-Only, Anon-Only)
├── Utils/               # AppStartupStatus, ServerSettings, Vite manifest, ResourceExtractor
├── Areas/               # Framework-provided Razor Pages (e.g., Error pages)
├── wwwroot/             # Framework style and script assets

Lifecycle & Execution Flow

DrnProgramBase manages application startup sequence to ensure security headers, logging scopes, and validation logic execute in order. Use DrnProgramActions to intercept these phases without modifying the primary Program class.

flowchart TD
    subgraph CONTAINER [" "]
        direction TB
        Start(["RunAsync()"]) --> CAB["CreateApplicationBuilder()"]
        
        subgraph BUILDER ["1. Builder Phase"]
            direction TB
            B_NOTE["Note: Handles Services & Config"]
            CAB --> CLB["ConfigureLoggingBuilder()"]
            CAB --> CWHB["ConfigureWebHostBuilder()"]
            CAB --> CSO["ConfigureSwaggerOptions()"]
            CAB --> CDSH["ConfigureDefaultSecurityHeaders()"]
            CDSH --> CDCSP["ConfigureDefaultCsp()"]
            CAB --> CSHPB["ConfigureSecurityHeaderPolicyBuilder()"]
            CAB --> CCP["ConfigureCookiePolicy()"]
            CAB --> CSFO["ConfigureStaticFileOptions()"]
            CAB --> CRCO["ConfigureResponseCachingOptions()"]
            CAB --> CRCMO["ConfigureResponseCompressionOptions()"]
            CAB --> CCP2["ConfigureCompressionProviders()"]
            CAB --> CFHO["ConfigureForwardedHeadersOptions()"]
            CAB --> CMVCB["ConfigureMvcBuilder()"]
            CAB --> CAO["ConfigureAuthorizationOptions()"]
            CAB --> ASA["AddServicesAsync()"]
            ASA --> ABC["ApplicationBuilderCreatedAsync (Action)"]
        end

        ABC --> Build["builder.Build()"]
        
        subgraph APPLICATION ["2. Application Phase"]
            direction TB
            A_NOTE["Note: Handles Middleware Pipeline"]
            Build --> CA["ConfigureApplication()"]
            CA --> CAPS["ConfigureApplicationPipelineStart() (HSTS/Headers)"]
            CAPS --> CAPR["ConfigureApplicationPreScopeStart() (Caching/Compression/Static)"]
            CAPR --> HSM["HttpScopeMiddleware (TraceId/Logging)"]
            HSM --> CPSS["ConfigureApplicationPostScopeStart()"]
            CPSS --> UR["UseRouting()"]
            UR --> CAPREA["ConfigureApplicationPreAuthentication()"]
            CAPREA --> AUTH["UseAuthentication()"]
            AUTH --> SUM["ScopedUserMiddleware"]
            SUM --> CAPOSTA["ConfigureApplicationPostAuthentication()"]
            CAPOSTA --> MFAE["MfaExemptionMiddleware"]
            CAPOSTA --> MFAR["MfaRedirectionMiddleware"]
            MFAE --> UA["UseAuthorization()"]
            MFAR --> UA
            UA --> CPSTAZ["ConfigureApplicationPostAuthorization() (Swagger UI)"]
            CPSTAZ --> MAE["MapApplicationEndpoints()"]
        end

        MAE --> ABA["ApplicationBuiltAsync (Action)"]
        ABA --> VE["ValidateEndpoints()"]
        VE --> VSA["ValidateServicesAsync()"]
        VSA --> AVA["ApplicationValidatedAsync (Action)"]
        AVA --> Run(["application.RunAsync()"])
    end

    %% WCAG AA Compliant Styling
    %% Outer Container
    style CONTAINER fill:#F0F8FF,stroke:#B0C4DE,stroke-width:2px,color:#4682B4

    %% Subgraph Backgrounds (Direct styling)
    style BUILDER fill:#E1F5FE,stroke:#0288D1,stroke-width:2px,color:#01579B
    style APPLICATION fill:#E8EAF6,stroke:#3F51B5,stroke-width:2px,color:#1A237E

    %% Node Styles (White for contrast against subgraph)
    classDef builderNode fill:#FFFFFF,stroke:#0288D1,stroke-width:2px,color:#01579B
    classDef appNode fill:#FFFFFF,stroke:#3F51B5,stroke-width:2px,color:#1A237E
    classDef action fill:#FFE0B2,stroke:#F57C00,stroke-width:2px,color:#E65100
    classDef core fill:#E8F5E9,stroke:#43A047,stroke-width:2px,color:#1B5E20
    classDef note fill:#FFF9C4,stroke:#F57C00,stroke-width:1px,color:#E65100,stroke-dasharray: 5 5
    classDef decision fill:#FFE0B2,stroke:#E65100,stroke-width:3px,color:#E65100

    %% Apply Styles
    class CAB,CLB,CWHB,CSO,CDSH,CDCSP,CSHPB,CCP,CSFO,CRCO,CRCMO,CCP2,CFHO,CMVCB,CAO,ASA builderNode
    class CA,CAPS,CAPR,HSM,CPSS,UR,CAPREA,AUTH,SUM,CAPOSTA,MFAE,MFAR,UA,CPSTAZ,MAE appNode
    class ABC,ABA,AVA action
    class Start,Build,VE,VSA,Run core
    class B_NOTE,A_NOTE note

    %% Link Styles for Decision Paths (Grey Arrows)
    linkStyle default stroke:#666,stroke-width:2px

DrnProgramBase Deep Dive

This section details the hooks for customizing the application lifecycle. DrnProgramBase implements a Hook Method pattern where the base defines the workflow and specific logic is injected via overrides.

1. Configuration Hooks (Builder Phase)

These hooks run while the WebApplicationBuilder is active, allowing you to configure the DI container and system options.

Category	Method	Purpose
Logging	ConfigureLoggingBuilder	Configure logging providers (clears defaults, applies config section, registers NLog).
WebHost	ConfigureWebHostBuilder	Configure Kestrel options (suppresses Server header, applies optional Kestrel section, registers static web assets).
OpenAPI	ConfigureSwaggerOptions	Customize Swagger UI title, version, and visibility settings.
MVC	ConfigureMvcBuilder	Add ApplicationParts, custom formatters, or MVC/Razor options. Razor edit loops use Hot Reload, not runtime compilation.
MVC	ConfigureMvcOptions	Add global filters, conventions, or customize model binding.
Auth	ConfigureAuthorizationOptions	Define security policies. Note: Sets MFA as the default/fallback by default.
Security	ConfigureDefaultSecurityHeaders	Define global headers (HSTS, CSP, FrameOptions).
Security	ConfigureDefaultCsp	Customize CSP directives (Script, Image, Style sources).
Security	ConfigureSecurityHeaderPolicyBuilder	Advanced conditional security policies (e.g., per-route CSP).
Cookies	ConfigureCookiePolicy	Set GDPR consent logic and security attributes for all cookies.
Cookies	ConfigureCookieTempDataProvider	Configure TempData cookie settings (HttpOnly, IsEssential).
Identity	ConfigureSecurityStampValidatorOptions	Customize security stamp validation and claim preservation.
Infras.	ConfigureStaticFileOptions	Customize caching (default: 1 year) and HTTPS compression.
Infras.	ConfigureForwardedHeadersOptions	Configure proxy/load-balancer header forwarding.
Infras.	ConfigureRequestLocalizationOptions	Configure culture providers and supported cultures.
Infras.	ConfigureHostFilteringOptions	Configure allowed hosts for host header validation.
Infras.	ConfigureResponseCachingOptions	Configure server-side response caching with sensible defaults (16MB max body size, case-insensitive paths).
Infras.	ConfigureResponseCompressionOptions	Configure response compression (Brotli/Gzip) for static assets. HTTPS compression disabled by default for BREACH prevention.
Infras.	ConfigureCompressionProviders	Configure Brotli and Gzip compression provider options including compression levels.
Infras.	ConfigureBrotliCompressionLevel	Customize Brotli compression level (default: SmallestSize for static assets).
Infras.	ConfigureGzipCompressionLevel	Customize Gzip compression level (default: SmallestSize for static assets).
Global	AddServicesAsync	[Required] The primary place to register your application services.

Razor Development

DRN uses Razor SDK build-time and publish-time compilation. For local .cshtml iteration, use IDE Hot Reload or dotnet watch instead of Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation; runtime compilation is obsolete in .NET 10 and disables Hot Reload.

References:

• Razor runtime compilation is obsolete
• .NET Hot Reload support for ASP.NET Core

2. Pipeline Hooks (Application Phase)

These hooks define the request processing middleware sequence.

Order	Hook	Typical Usage
1	ConfigureApplicationPipelineStart	UseForwardedHeaders, UseHostFiltering, UseCookiePolicy.
2	ConfigureApplicationPreScopeStart	UseResponseCaching, UseResponseCompression, UseStaticFiles. Caching placed before compression for efficiency.
3	ConfigureApplicationPostScopeStart	Add middleware that needs access to IScopedLog but runs before routing.
4	ConfigureApplicationPreAuthentication	UseRequestLocalization. Runs before the user identity is resolved.
5	ConfigureApplicationPostAuthentication	MfaRedirectionMiddleware, MfaExemptionMiddleware. Logic that runs after the user is known but before access checks.
6	ConfigureApplicationPostAuthorization	UseSwaggerUI. Runs after access is granted but before the final endpoint.
7	MapApplicationEndpoints	MapControllers, MapRazorPages, MapHubs.

3. Verification Hooks

Hook	Purpose
ValidateEndpoints	Ensures all type-safe endpoint accessors match actual mapped routes.
ValidateServicesAsync	Scans the container for [Attribute] based registrations and ensures they are resolvable at startup via ValidateServicesAddedByAttributesAsync.

4. MFA Configuration Hooks

Hook	Purpose
ConfigureMFARedirection	Configure MFA setup and login redirection URLs. Returns null to disable.
ConfigureMFAExemption	Configure authentication schemes exempt from MFA requirements. Returns null to disable.

5. Internal Wiring (Automatic)

• Service Validation: Calls ValidateServicesAsync to scan [Attribute]-registered services and ensure they are resolvable at startup.
• Secure JSON: Enforces HtmlSafeWebJsonDefaults to prevent XSS via JSON serialization.
• Endpoint Accessor: Registers IEndpointAccessor for typed access to EndpointCollectionBase.

6. Properties

Property	Default	Purpose
AppBuilderType	DrnDefaults	Controls builder creation. Use Slim for minimal APIs.
DrnProgramSwaggerOptions	(Object)	Toggles Swagger generation. Defaults to IsDevelopmentEnvironment.
NLogOptions	(Object)	Controls NLog bootstrapping (e.g., replace logger factory).

Configuration

Layering

1. appsettings.json
2. appsettings.{Environment}.json
3. User Secrets (Development only)
4. Environment Variables (ASPNETCORE_, DOTNET_)
5. Mounted Directories (e.g. /app/config)
6. Command Line Arguments

Host Filtering

AllowedHosts must be configured outside Development and cannot be *. Development may fall back to * for local convenience; production and staging should use explicit host names such as example.com;api.example.com.

Reference Configurations

NLog (Logging)

Standard configuration for Console and Graylog output.

{
  "NLog": {
    "throwConfigExceptions": true,
    "targets": {
      "async": true,
      "console": {
        "type": "Console",
        "layout": "${longdate}|${level:uppercase=true}|${logger}|${message} ${exception:format=tostring}"
      }
    },
    "rules": [
      { "logger": "*", "minLevel": "Info", "writeTo": "console" }
    ]
  }
}

Kestrel (Server)

{
  "Kestrel": {
    "EndpointDefaults": { "Protocols": "Http1" },
    "Endpoints": {
      "All": { "Url": "http://*:5988" }
    }
  }
}

Security Features

DRN Hosting enforces a "Fail-Closed" security model. If you forget to configure something, it remains locked.

1. MFA Enforcement (Fail-Closed)

The framework sets the FallbackPolicy for the entire application to require a Multi-Factor Authentication session.

• Result: Any new controller or page you add is secure by default.
• Opt-Out: Use [AllowAnonymous] or [Authorize(Policy = AuthPolicy.MfaExempt)] for single-factor pages like Login or MFA Setup.

2. MFA Configuration

Configure MFA behavior by overriding these hooks in your DrnProgramBase implementation:

// Configure MFA redirection URLs
protected override MfaRedirectionConfig ConfigureMFARedirection()
    => new(
        mfaSetupUrl: Get.Page.User.EnableAuthenticator,
        mfaLoginUrl: Get.Page.User.LoginWith2Fa,
        loginUrl: Get.Page.User.Login,
        logoutUrl: Get.Page.User.Logout,
        allowedUrls: Get.Page.All
    );

// Exempt specific authentication schemes from MFA
protected override MfaExemptionConfig ConfigureMFAExemption()
    => new(exemptSchemes: ["ApiKey", "Certificate"]);

Disabling MFA Entirely

To disable MFA enforcement for your entire application (e.g., for internal tools or development):

public class Program : DrnProgramBase<Program>, IDrnProgram
{
    // Return null to disable MFA redirection middleware
    protected override MfaRedirectionConfig? ConfigureMFARedirection() => null;

    // Return null to disable MFA exemption middleware  
    protected override MfaExemptionConfig? ConfigureMFAExemption() => null;

    // Override authorization to remove MFA requirement from fallback policy
    protected override void ConfigureAuthorizationOptions(AuthorizationOptions options)
    {
        // Remove MFA enforcement - authenticated users can access without MFA
        options.FallbackPolicy = new AuthorizationPolicyBuilder()
            .RequireAuthenticatedUser()
            .Build();
    }
}

3. Content Security Policy (Nonce-based)

DRN automatically generates a unique cryptographic nonce for every request.

• Baseline: default-src 'none' with explicit same-origin allowlists for styles, images, fonts, connections, media, manifests, and workers.
• Automatic Protection: Inline scripts and inline style elements without a matching nonce are blocked by the browser, stopping most XSS attacks.
• Usage: Use the NonceTagHelper (see below) to automatically inject these nonces.

4. Transparent Security Headers

Standard security headers are injected into every response:

• HSTS: Strict-Transport-Security (2 years, includes subdomains).
• FrameOptions: DENY (prevents clickjacking).
• ContentTypeOptions: nosniff.
• ReferrerPolicy: strict-origin-when-cross-origin.

5. GDPR & Cookie Security

Cookies are configured with SameSite=Strict and HttpOnly by default to mitigate CSRF and session hijacking. The ConsentCookie system ensures compliance with privacy regulations.

6. Per-Route Security Headers

Customize security headers for specific routes by overriding ConfigureSecurityHeaderPolicyBuilder:

protected override void ConfigureSecurityHeaderPolicyBuilder(
    HeaderPolicyCollection policies, 
    IAppSettings appSettings)
{
    base.ConfigureSecurityHeaderPolicyBuilder(policies, appSettings);
    
    // Add route-specific CSP for embedding external content
    policies.AddContentSecurityPolicy(builder =>
    {
        builder.AddFrameAncestors().Self();
        builder.AddScriptSrc().Self().UnsafeInline(); // Only for specific legacy routes
    }, 
    // Apply only to specific paths
    context => context.Request.Path.StartsWithSegments("/legacy"));
}

7. Rate Limiting

DRN Hosting provides first-class, dual-layer rate limiting with a pluggable rule engine.

• Pre-Auth Layer: Lightweight middleware placed before authentication. Rejects abusive requests (IP-based by default) early to save expensive auth/MFA checks. It evaluates singleton rules only. Endpoints with ASP.NET Core [DisableRateLimiting] metadata bypass this DRN pre-auth layer as well as the built-in post-auth layer; [EnableRateLimiting] does not bypass the global pre-auth limiter, matching ASP.NET Core global-limiter semantics.
• Post-Auth Layer: Placed after ScopedUserMiddleware to allow user-aware and tenant-based partitioning. The default authenticated partition uses stable user id claims (NameIdentifier/sub) with the authentication scheme, falling back to IP only for anonymous requests.

Post-auth defaults to Token Bucket (100 tokens/minute per authenticated user or anonymous IP). Pre-auth defaults to a coarser B2B-friendly IP bucket (1,000 tokens/minute) so shared corporate NAT/VPN/CDN egress addresses are not punished like one user. Both layers return 429 Too Many Requests with a Retry-After header.

flowchart LR
    request["Request"] --> routing["UseRouting"]
    routing --> pre["Pre-auth singleton rule chain"]
    pre --> auth["Authentication + ScopedUserMiddleware"]
    auth --> post["Post-auth singleton + scoped rule chain"]
    post --> endpoint["Endpoint"]
    endpoint -. "[EnableRateLimiting(policy)]" .-> post
    endpoint -. "[DisableRateLimiting]" .-> pre

Why DRN Rate Limiting

ASP.NET Core UseRateLimiter() has a single GlobalLimiter property and named policies per endpoint. A second limiter overwrites the first. Named policies do not compose on the same endpoint. There is no pre-auth layer. DRN solves these problems:

Capability	ASP.NET Core Native	DRN
Multiple rules per request	Manual CreateChained(...) wiring	✅ Automatic. Register rules to chain them
Pre-auth and post-auth layers	Single layer only	✅ Two layers with lifetime separation
Tenant, User, and IP together	Manual plumbing in one GlobalLimiter	✅ Separate rules that chain automatically
Add a rule without touching existing config	Risk overwriting GlobalLimiter	✅ Derive from base class
Policy-scoped rules that compose	One named policy per endpoint	✅ Multiple rules with same PolicyName chain
Named policies from AddRateLimiter(...)	✅ Supported	✅ Preserved. DRN enriches them
Multi-dimensional partitioning	Single key per limiter. Combine dimensions manually	✅ Each rule owns its partition key. Dimensions compose via chaining
Partition key isolation	Each Create(...) instance has own cache	✅ Same. Auto-namespaced keys for diagnostics and defense
Identity-aware partitioning	Write HttpContext.User parsing inline	✅ Scoped rules inject IScopedUser. Defaults use stable NameIdentifier or sub claims
Pre-auth partition defaults	No pre-auth layer	✅ IP-based with coarse limits
Post-auth partition defaults	Must implement from scratch	✅ User ID (auth) or IP (anonymous) out of the box

Register a class to chain automatically. No manual CreateChained(...). No single-property overwrite risk. No touching Program.cs.

Settings Quick Reference

Configure DRN defaults under DrnAppFeatures:DrnRateLimit. Application code reads the same values through IAppSettings.Features.RateLimit. Settings are a startup snapshot, so changing them requires an application restart.

Setting group	Default	Used by	Meaning
Disabled	false	Both phases	Disables DRN pre-auth and post-auth rate limiting entirely.
PartitionLogMode	KeyedHash	Both phases	Controls structured log values for rejected IP/partition keys. KeyedHash logs deterministic keyed hashes for correlation; PlainText logs raw values and should be limited to controlled development or dedicated audit sinks.
TokenLimit, ReplenishmentSeconds, TokensPerPeriod	100, 60, 100	Shared fallback	Base token bucket values for both phases.
PreAuthTokenLimit, PreAuthReplenishmentSeconds, PreAuthTokensPerPeriod	1000, 60, 1000	Pre-auth	Coarse IP/header limits before authentication. Keep these higher behind NAT, VPN, or CDN egress. 0 inherits the shared value.
PostAuthTokenLimit, PostAuthReplenishmentSeconds, PostAuthTokensPerPeriod	0, 0, 0	Post-auth	Authenticated user or anonymous IP limits after ScopedUserMiddleware. 0 inherits the shared value.

Usage guidance:

• Use the default post-auth rule for ordinary per-user throttling.
• Raise pre-auth limits or add a singleton trusted-header rule when many legitimate users share one edge IP.
• Add scoped post-auth rules for tenant, account, or user-claim partitions that need IScopedUser or other scoped collaborators.
• Use [DisableRateLimiting] for trusted health and operational endpoints that must not consume any quota.
• Use [EnableRateLimiting("policy-name")] for ASP.NET Core named post-auth policies. DRN pre-auth remains global; DRN rule PolicyName values compose with matching endpoint metadata.
• DRN's built-in token bucket queues are disabled (QueueLimit = 0) so rejected requests fail fast with 429. Custom rules can choose different algorithms or queue behavior.
• Treat DrnRateLimitOptions as global default policy. Put tenant plan, feature-flag, account, or endpoint-specific quota decisions in app-owned rules.
• Process-local limits are not a distributed enforcement boundary. In horizontally scaled production, pair DRN app-local limits with edge or distributed rate limiting.

Dynamic Tenant Policies and Distributed Enforcement

DrnRateLimitOptions is a startup snapshot for global defaults. Enterprise tenant plans should be modeled in rules, not in the global settings object. A scoped post-auth rule can read IScopedUser, request-scoped feature flags, or tenant plan data already loaded for the request and return a partition with the correct limit values.

Rule evaluation is synchronous because ASP.NET Core partition selection is synchronous. Do not perform database, Redis, or HybridCache I/O inside EvaluatePreAuth / EvaluatePostAuth. Load dynamic plan data earlier in the request, or maintain an in-memory snapshot refreshed by a background service.

HybridCache and IDistributedCache are useful for sharing and refreshing rate-limit policy data across app instances. They are not, by themselves, a hard distributed quota counter because DRN's built-in token/fixed/sliding/concurrency limiters keep counters inside each process. For strict multi-replica quotas, use an API gateway, CDN/WAF, service mesh policy, or a Redis-backed custom RateLimiter returned via RateLimitRuleResult.CustomPartition(...). Redis-backed counters should use atomic server-side operations such as Lua scripts with TTL.

Extensibility via Rate Limit Rules

You can customize rules by implementing ISingletonRateLimitRule / IScopedRateLimitRule, or by extending SingletonRateLimitRule / ScopedRateLimitRule. Rules are evaluated in ascending Order. Matching rules compose with .NET's native chained limiter, so tenant + user + IP policies can all apply to the same request. Framework defaults run last. Prefer the base classes for automatic attribute-based DI registration. If you implement the interfaces directly, add [Singleton<ISingletonRateLimitRule>(tryAdd: false)] or [Scoped<IScopedRateLimitRule>(tryAdd: false)] so multiple rules compose in the lifetime-specific rule chains.

Keep application-specific claim names in the hosted app, and compose them from claim-access primitives:

// Sample.Hosted/Helpers/RateLimitFor.cs
public class RateLimitFor
{
    public string? AccountPartition => Get.Claim.Account.Id == null ? null : $"account:{Get.Claim.Account.Id:N}";
    public string? TenantPartition => Get.Claim.Tenant.Id == null ? null : $"tenant:{Get.Claim.Tenant.Id:N}";
}

// Sample.Hosted rate limit rule using the helper
public class AccountRateLimitRule(DrnAppFeatures features) : ScopedRateLimitRule
{
    public override RateLimitRuleResult? EvaluatePostAuth(HttpContext context)
    {
        var partitionKey = Get.RateLimit.AccountPartition;
        if (partitionKey == null)
            return null;

        return RateLimitRuleResult.TokenBucket(partitionKey, _ => new TokenBucketRateLimiterOptions
        {
            TokenLimit = features.RateLimit.TokenLimit,
            ReplenishmentPeriod = TimeSpan.FromSeconds(features.RateLimit.ReplenishmentSeconds),
            TokensPerPeriod = features.RateLimit.TokensPerPeriod,
            QueueLimit = 0,
            AutoReplenishment = true
        });
    }
}

Rule Behavior Quick Reference

Return Value	Effect
null	Rule does not apply — skip to next rule
RateLimitRuleResult.TokenBucket(key, ...)	Apply token bucket limiter on this partition key
RateLimitRuleResult.AllowRequest("health")	Whitelist — no limiting, stop remaining rules
RateLimitRuleResult.DenyRequest("blocked")	Reject immediately with 429, stop remaining rules, optionally emit Retry-After
Any result with stopRemainingRules: true	Apply this limiter, then skip remaining rules

Partition helpers: TokenBucket, FixedWindow, SlidingWindow, ConcurrencyLimiter, CustomPartition. RateLimitRuleResult.Action is Limit, Allow, or Deny; StopRemainingRules only controls whether later rules compose after this result.

Rule Ordering and Composition

• Rules execute in ascending Order. Framework defaults use int.MaxValue. Your rules run first.
• Multiple matching rules compose via .NET's native chained limiter (e.g., tenant + user + IP all enforce together).
• ShortCircuitOnMatch = true: the rule runs before normal same-order rules. If it returns null, later rules still evaluate. If it returns a result, that result decides the action and remaining rules are skipped.
• AllowRequest succeeds without a limiter. DenyRequest fails immediately. Quota results such as TokenBucket still acquire their limiter, then skip remaining rules when ShortCircuitOnMatch or stopRemainingRules applies.
• Use a lower Order when an allow/deny rule must bypass earlier quotas entirely.

Partition Key Isolation

DRN rate limit rules namespace every partition identity with the phase and the rule type:

({phase}, {rule type}, {your partition key})

This namespacing provides:

• Diagnostics: Partition keys in metrics and logs identify the rule and phase.
• Defense in depth: Protects against future refactoring that might consolidate limiter instances.

Example: A request from IP 192.168.1.1 by tenant acme-corp hits three rules:

Rule	Your partition key	DRN internal identity
DefaultPreAuthRateLimitRule	ip:192.168.1.1	(PreAuth, DefaultPreAuthRateLimitRule, ip:192.168.1.1)
CustomIpRule	ip:192.168.1.1	(PostAuth, CustomIpRule, ip:192.168.1.1)
TenantRateLimitRule	tenant:acme-corp	(PostAuth, TenantRateLimitRule, tenant:acme-corp)

The namespacing is internal. Your EvaluatePreAuth or EvaluatePostAuth method returns a partition key like "ip:192.168.1.1". The framework handles the namespacing.

Scoped Rules

• Scoped rules are post-auth only. They are not evaluated by the pre-auth limiter.
• DRN detects scoped rule registrations at startup, resolves them from the request scope, and preserves global Order across singleton and scoped rules.

Claim-Based Partitions

• Use app-specific RateLimitFor wrappers (e.g., Sample.Hosted.Helpers.RateLimitFor) with claim-access primitives from Get.Claim.*.
• This reads claims from the cached scoped user model instead of repeatedly parsing HttpContext.User.

Named Policies

• Set PolicyName on a rule to scope it to endpoints marked with [EnableRateLimiting("policy-name")].
• null policy = global rule. Non-null policy names must be non-empty.
• Native policies configured via builder.Services.AddRateLimiter(options => ...) remain available and run alongside DRN rule policies.
• DRN invokes rule-specific OnRejectedAsync only when that DRN rule's limiter rejects; native named-policy rejections still flow through the configured ASP.NET Core OnRejected callback.

Telemetry

DRN emits OpenTelemetry-friendly metrics through the DRN.Framework.Hosting.RateLimiting meter:

Metric	Tags
drn.rate_limiting.requests	phase, policy, result, action, rule
drn.rate_limiting.rejections	phase, policy, result, action, rule
drn.rate_limiting.active_request_leases	phase, policy, result, action, rule
drn.rate_limiting.request_lease.duration	phase, policy, result, action, rule

ASP.NET Core's native rate limiting middleware continues to provide its built-in post-auth metrics. The action tag is limit, allow, deny, or unknown; this makes whitelist, blocklist, and quota decisions visible without inspecting rule names. When a native ASP.NET Core named policy rejects after DRN's global limiter succeeds, DRN records the rejection without a DRN rule tag because no DRN rule caused the failed lease. By default, pre-auth and post-auth rejection logs write IP and partition values as deterministic keyed hashes with a blake3-keyed: prefix. This preserves correlation for audits without exposing raw API-key, tenant-hint, service-identifier, user, or IP values. Set DrnAppFeatures:DrnRateLimit:PartitionLogMode to PlainText only for controlled development or a dedicated encrypted audit sink.

Overriding Defaults

Override CreatePreAuthRateLimiter or ConfigurePostAuthRateLimiterOptions in your DrnProgramBase to change limits, add named policies, or swap algorithms. DRN starts from the DI-configured RateLimiterOptions, so endpoint policies and existing rejection callbacks are preserved.

protected override void ConfigurePostAuthRateLimiterOptions(
    RateLimiterOptions options,
    IServiceProvider serviceProvider,
    IAppSettings appSettings)
{
    base.ConfigurePostAuthRateLimiterOptions(options, serviceProvider, appSettings);
    options.AddTokenBucketLimiter("strict", opt =>
    {
        opt.TokenLimit = 10;
        opt.ReplenishmentPeriod = TimeSpan.FromSeconds(60);
        opt.TokensPerPeriod = 10;
        opt.QueueLimit = 0;
    });
}

References

• ASP.NET Core rate limiting middleware
• RateLimiterOptions API
• RateLimitPartition API
• HybridCache library in ASP.NET Core
• Distributed caching in ASP.NET Core
• Redis token bucket rate limiter with .NET
• RFC 6585 Section 4: 429 Too Many Requests
• RFC 9110: Retry-After header

Endpoint Management

Avoid "magic strings" in your code. DRN provides a type-safe way to reference routes that is verified at startup.

1. Define Your Accessors

Create a class inheriting from EndpointCollectionBase<Program> or PageCollectionBase<Program>.

public class Get : EndpointCollectionBase<Program>
{
    public static UserEndpoints User { get; } = new();
}

public class UserEndpoints : ControllerForBase<UserController>
{
    // Template: /Api/User/[controller]/[action]
    public UserEndpoints() : base("/Api/User/[controller]") { }

    // Properties matching Controller Action names
    public ApiEndpoint Login { get; private set; } = null!;
    public ApiEndpoint Profile { get; private set; } = null!;
}

2. Usage in Code

Resolve routes at compile-time with full IDE support (intellisense).

// Get the typed endpoint object
ApiEndpoint endpoint = Get.User.Login;

// Generate the path string
string url = endpoint.Path(); // "/Api/User/User/Login"

// Generate path with route parameters
string profileUrl = Get.User.ProfileDetail.Path(new() { ["id"] = userId.ToString() });

Razor TagHelpers

TagHelper	Target	Purpose
ViteScriptTagHelper	<script src="buildwww/...">	Resolves Vite manifest entries, adds subresource integrity (SRI), and automatic nonce.
ViteLinkTagHelper	<link href="buildwww/...">	Resolves Vite manifest entries for CSS assets, adds SRI.
NonceTagHelper	<script>, <style>, <link>, <iframe>	Automatically injects the request-specific CSP nonce.
CsrfTokenTagHelper	hx-post, hx-put, etc.	Automatically adds RequestVerificationToken to HTMX headers for non-GET requests.
AuthorizedOnlyTagHelper	*[authorized-only]	Renders the element only if the user has an active MFA session.
AnonymousOnlyTagHelper	*[anonymous-only]	Renders the element only if the user is not authenticated.
PageAnchorTagHelper	<a asp-page="...">	Automatically adds active CSS class if the link matches current page.
ScriptDefaultsTagHelper	<script>	Modern defaults: defer for external scripts, type="module" for inline scripts. Opt-out via defer="false" or explicit type.

Vite Manifest Publish Support

DRN.Framework.Hosting ships a transitive MSBuild target that adds wwwroot/**/.vite/manifest.json files to Web SDK publish output. This keeps Vite manifest lookup, SRI generation, and static asset pre-warming working after publish, including Vite's default dot-directory manifest location.

Disable the publish item injection when an application owns this behavior itself:

<PropertyGroup>
  <DrnHostingViteManifestPublishItemsEnabled>false</DrnHostingViteManifestPublishItemsEnabled>
</PropertyGroup>

Developer Diagnostics

DRN Hosting provides deep observability into application failures, especially during the critical startup phase.

Startup Exception Reports

In Development, if the application fails to start during RunAsync, it generates a StartupExceptionReport.html in the execution directory. Production and staging fail with normal logs only. Development reports include:

• Full stack traces with source code highlighting (if symbols available).
• Environment details and configuration snapshots.
• Scoped logs leading up to the crash.

Custom Error Pages

The framework includes built-in Razor Pages for developer-time exception handling:

• RuntimeExceptionPage: Detailed breakdown of unhandled exceptions with request state and logs.
• CompilationExceptionPage: Visualizes Razor or code compilation errors with line-specific highlighting.

Request Body Buffering

RequestBufferingState provides size-gated request body capture for diagnostic error pages. It follows a producer/consumer pattern:

1. Producer — TryEnableBuffering runs in HttpScopeMiddleware early in the pipeline. For POST, PUT, and PATCH requests with a known Content-Length within the configured limit, it enables Request.EnableBuffering() so the body stream becomes seekable.
2. Consumer — ReadBodyAsync is called by the error page model builder (ExceptionUtils.CreateErrorPageModelAsync) to include the request body in diagnostic reports.

Security design:

• Size gate — requests exceeding the buffer limit are silently skipped (no buffering, no memory risk)
• Method filter — only POST/PUT/PATCH are buffered; GET/HEAD/DELETE/OPTIONS carry no semantic body
• Chunked transfer — requests without Content-Length (chunked encoding) are skipped to prevent unbounded DoS
• Kestrel enforcement — Content-Length is validated per-protocol (HTTP/1.1 slicing, HTTP/2 PROTOCOL_ERROR, HTTP/3 QUIC framing)

Configuration via DrnAppFeatures (in appsettings.json):

Key	Type	Default	Effect
DisableRequestBuffering	bool	false	Kill switch — disables all body buffering
MaxRequestBufferingSize	int	0 (→ 30,000)	Max bytes to buffer. Values below 10,000 are ignored

{
  "DrnAppFeatures": {
    "DisableRequestBuffering": false,
    "MaxRequestBufferingSize": 50000
  }
}

Modern HTTP Standards

DRN Hosting enforces modern web standards to improve security and predictability:

• 303 See Other: The middleware automatically converts 302 Found redirects to 303 See Other. This ensures that following a POST request, the browser correctly uses GET for the redirected URL, adhering to established web patterns.
• Strict Caching: By default, Cache-Control: no-store, no-cache, must-revalidate is applied to all sensitive responses to prevent data leaking into shared or browser caches.

GDPR & Consent Integration

The framework provides a structured way to handle user privacy choices:

• ConsentCookie: A strongly-typed model to track analytics and marketing preferences.
• Middleware Integration: ScopedUserMiddleware automatically extracts consent data and makes it available via ScopeContext.Data, allowing services to check consent status without reaching into the raw cookie.

Example: Secure Script Loading

<script src="buildwww/app/main.ts" crossorigin="anonymous"></script>


<script src="/app/main.abc123.js" 
        integrity="sha256-xyz..." 
        nonce="random_nonce_here" 
        crossorigin="anonymous"></script>

Static Asset Pre-Warming

StaticAssetWarmService is a [HostedService] that populates the ResponseCaching middleware cache with compressed static assets immediately after application startup.

How it works:

1. Waits for the host to fully start via IAppStartupStatus
2. Reads all entries from the Vite manifest
3. Requests each asset with Accept-Encoding: br and Accept-Encoding: gzip against the loopback address (via IServerSettings)
4. ResponseCaching stores each compressed variant keyed on Vary: Accept-Encoding

The warm-up client only accepts loopback base addresses before installing its certificate-bypass handler. Wildcard server bindings are normalized to localhost; non-loopback bindings are ignored for warm-up.

Compression defaults — both use CompressionLevel.SmallestSize (maximum compression) since only static files are compressed and the cost is paid once at startup:

Provider	Default Level	Override Hook
Brotli	SmallestSize (Level 11)	ConfigureBrotliCompressionLevel()
Gzip	SmallestSize	ConfigureGzipCompressionLevel()

First request after startup returns pre-compressed content from cache — zero compression latency for end users.

Local Development Infrastructure

Use DRN.Framework.Testing to provision infrastructure (Postgres, RabbitMQ) during local development without manual Docker management.

1. Add Conditional Reference

Add the following to your .csproj file to ensure the testing library (and its heavy dependencies like Testcontainers) is only included during development.

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
    <ProjectReference Include="..\DRN.Framework.Testing\DRN.Framework.Testing.csproj" />
</ItemGroup>

2. Configure Startup Actions

Implement DrnProgramActions to trigger the auto-provisioning.

#if DEBUG
public class SampleProgramActions : DrnProgramActions
{
    public override async Task ApplicationBuilderCreatedAsync<TProgram>(
        TProgram program, WebApplicationBuilder builder,
        IAppSettings appSettings, IScopedLog scopedLog)
    {
        var options = new ExternalDependencyLaunchOptions
        {
            PostgresContainerSettings = new() 
            { 
                Reuse = true, // Faster restarts
                HostPort = 6432 // Avoid conflicts with local Postgres
            }
        };

        // Auto-starts containers if not running and updates AppSettings
        await builder.LaunchExternalDependenciesAsync(scopedLog, appSettings, options);
    }
}
#endif

Hosting Utilities

IAppStartupStatus

Singleton gate for background services that need to wait until the host has fully started before executing.

public class MyWorker(IAppStartupStatus startupStatus) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        if (!await startupStatus.WaitForStartAsync(stoppingToken))
            return; // Cancelled before startup completed

        // Application is fully started — safe to proceed
    }
}

IServerSettings

Resolves bound server addresses from Kestrel. Normalizes wildcard hosts (0.0.0.0, [::], +, *) to localhost for internal self-requests. Prefers HTTP over HTTPS to avoid TLS overhead.

public class MyService(IServerSettings server)
{
    public void LogAddresses()
    {
        var loopback = server.GetLoopbackAddress();   // e.g. "http://localhost:5988"
        var all = server.GetAllAddresses();            // All normalized bound addresses
    }
}

Global Usings

Standard global usings for Hosted applications to reduce boilerplate:

global using DRN.Framework.Hosting.DrnProgram;
global using DRN.Framework.Hosting.Endpoints;
global using DRN.Framework.Utils.DependencyInjection;
global using DRN.Framework.Utils.Logging;
global using DRN.Framework.Utils.Settings;
global using Microsoft.AspNetCore.Mvc;

---

Related Packages

• DRN.Framework.SharedKernel - Domain primitives and exceptions
• DRN.Framework.Utils - Configuration and DI utilities
• DRN.Framework.EntityFramework - EF Core integration
• DRN.Framework.Testing - Testing utilities

For complete examples, see Sample.Hosted.

---

Documented with the assistance of DiSCOS

---

Semper Progressivus: Always Progressive

Commit Info

Author: Duran Serkan KILIÇ
Date: 2026-06-07 17:32:49 +0300
Hash: e482f3604d6508a3dd9b31903447706cb549bc96