DRN.Framework.Hosting 0.7.0-preview059

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
• Local Development
• Global Usings

QuickStart: Beginner

All DRN web apps inherit from DrnProgramBase<TProgram> to inherit the lifecycle hooks and default 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
├── Consent/          # GDPR cookie consent management
├── Identity/         # Identity integration and scoped user middleware
├── Middlewares/      # HttpScopeLogger, exception handling, security middlewares
├── TagHelpers/       # Razor TagHelpers (Vite, Nonce, CSRF, Auth-Only)
├── Areas/            # Framework-provided Razor Pages (e.g., Error pages)
├── wwwroot/          # Framework style and script assets

Lifecycle & Execution Flow

DrnProgramBase orchestrates the application startup to ensure security headers, logging scopes, and validation logic run in the correct order. Use DrnProgramActions to intercept these phases without cluttering your main Program class.

graph TD
    Start["RunAsync()"] --> CAB["CreateApplicationBuilder()"]
    
    subgraph "1. Builder Phase (Services & Config)"
    CAB --> CSO["ConfigureSwaggerOptions()"]
    CAB --> CDSH["ConfigureDefaultSecurityHeaders()"]
    CDSH --> CDCSP["ConfigureDefaultCsp()"]
    CAB --> CSHPB["ConfigureSecurityHeaderPolicyBuilder()"]
    CAB --> CCP["ConfigureCookiePolicy()"]
    CAB --> CSFO["ConfigureStaticFileOptions()"]
    CAB --> CFHO["ConfigureForwardedHeadersOptions()"]
    CAB --> CMVCB["ConfigureMvcBuilder()"]
    CAB --> CAO["ConfigureAuthorizationOptions()"]
    CAB --> ASA["AddServicesAsync()"]
    ASA --> ABC["ApplicationBuilderCreatedAsync (Action)"]
    end

    ABC --> Build["builder.Build()"]
    
    subgraph "2. Application Phase (Middleware)"
    Build --> CA["ConfigureApplication()"]
    CA --> CAPS["ConfigureApplicationPipelineStart() (HSTS/Headers)"]
    CAPS --> CAPR["ConfigureApplicationPreScopeStart() (Static Files)"]
    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()"]

DrnProgramBase Deep Dive

This section details the hooks available to customize your application's lifecycle. DrnProgramBase follows a "Hook Method" pattern: the base class defines the workflow, and you override virtual methods to inject logic.

1. Configuration Hooks (Builder Phase)

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

2. Pipeline Hooks (Application Phase)

These hooks define the request processing middleware sequence.

3. Verification Hooks

4. MFA Configuration Hooks

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

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

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"]);

3. Content Security Policy (Nonce-based)

DRN automatically generates a unique cryptographic nonce for every request.

• Automatic Protection: Scripts and styles 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.

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

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>

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

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;

Semper Progressivus: Always Progressive

Commit Info

Author: Duran Serkan KILIÇ
Date: 2026-01-26 21:12:39 +0300
Hash: 858b6f431aa962dcd742ffa77fa3a94322c3754e