Cocoar.Configuration.AspNetCore 0.10.0

Cocoar.Configuration

Lightweight, strongly-typed, deterministic multi-source configuration layering for .NET (Current target framework: net9.0).

Why Cocoar.Configuration?

Deterministic, strongly-typed, rule-driven configuration layering that complements Microsoft.Extensions.Configuration.

Design Goals at a Glance

• Explicit ordered layering: Deterministic last-write-wins per key.
• Typed direct injection: Inject config classes or mapped interfaces (no IOptions<T> ceremony).
• Atomic snapshot recompute: Full ordered rebuild on change → consistent view for all consumers.
• Dynamic rule factories: Later rules can read earlier in-progress snapshots to shape options/queries.
• Pluggable provider model: File, environment, HTTP polling, Microsoft adapter, static & custom.
• DI lifetimes & keys: Configure singleton (default), scoped, transient, keyed variants per type.
• Per-type diagnostics: Inspect merged snapshots when troubleshooting.
• Interoperability: Bring any existing IConfigurationSource via the Microsoft Adapter package.

Installation

Supported TFM: net9.0 (multi-targeting planned).

<ItemGroup>
        <PackageReference Include="Cocoar.Configuration" />
        
        <PackageReference Include="Cocoar.Configuration.AspNetCore" />
        <PackageReference Include="Cocoar.Configuration.HttpPolling" />
        <PackageReference Include="Cocoar.Configuration.MicrosoftAdapter" />
</ItemGroup>

CLI:

dotnet add package Cocoar.Configuration
dotnet add package Cocoar.Configuration.AspNetCore
dotnet add package Cocoar.Configuration.HttpPolling
dotnet add package Cocoar.Configuration.MicrosoftAdapter

Quick Start

Minimal example (file + environment layering, strongly-typed access):

// ...
builder
    .AddCocoarConfiguration(
        // File + env layering (rule-level selection via .Select)
        Rule.From.File("appsettings.json").Select("App").For<AppSettings>().Optional(),
        Rule.From.Environment("APP_").For<AppSettings>()
    );

Then inject your config type directly:

var settings = app.Services.GetRequiredService<AppSettings>();
Console.WriteLine($"FeatureX: {settings.EnableFeatureX}");

Concepts

• Rule: Source + optional query + target configuration type
• Provider: Pluggable source (file, env, HTTP, static, custom, adapter)
• Merge: Ordered last-write-wins per flattened key
• Recompute: Incremental – only recompute from earliest changed rule; atomic snapshot publish.
• Dynamic dependencies: Rule factories (options/query) can read earlier in-progress rule outputs during a pass.
• Required vs Optional: Optional failure skips the layer.
• DI Lifetimes & Keys: Register as singleton (default), scoped, transient, keyed

👉 Read more in the Concepts Deep Dive

Providers

Built-in and extension providers:

👉 See Providers Overview for full details.

Advanced Features

• Service Lifetimes & Keys: control DI lifetimes, keyed configs
• Generic Provider API: Rule.From.Provider<>() for full control
• Microsoft Adapter: wrap any IConfigurationSource
• HTTP Polling Provider: auto-change detection

👉 Details in Advanced Features

Security

• Never commit secrets to JSON files in your repository
• Use environment variable overlays or dedicated secret management systems
• For remote providers: Always use TLS, set reasonable timeouts, and include auth headers when needed
• Consider using Azure Key Vault, AWS Secrets Manager, or similar via the Microsoft Adapter

Examples

Multi-project solution under src/Examples/ with runnable demos:

• BasicUsage – File + environment layering pattern (full code)
• AspNetCoreExample – Web application integration
• FileLayering – Multiple JSON layers (deterministic last-write-wins)
• ServiceLifetimes – DI lifetimes + keyed registrations
• DynamicDependencies – Rules reading other config mid-recompute
• GenericProviderAPI – Full generic provider control
• MicrosoftAdapterExample – Integrate any IConfigurationSource
• HttpPollingExample – Remote polling with change detection
• StaticProviderExample – Seeding & composition with static rules

Deep Dive Documentation

For more in-depth documentation, see:

• Architecture – execution & merge pipeline, change model
• Providers – static, file, env, HTTP, Microsoft adapter
• Concepts – rules, merge semantics, dependencies
• Examples – runnable samples
• Provider Development Guide – build your own provider

Thread Safety & Performance

• Reading config is thread-safe (atomic snapshot swap)
• Incremental recompute: only from earliest changed rule onward (prefix reused)
• Selection-hash gating: unchanged selected subtree events skipped
• Providers reused across recomputes when instance options stable
• Static rule set: rules immutable after initialization (use UseWhen to toggle)

Quality & Reliability

This project invests heavily in correctness-first incremental recompute. Optimisations (prefix reuse, cancellation, selection‑hash gating, debounce) are all guarded by strong differential and stress tests so performance never compromises determinism.

Core test suites (see src/tests/):

Why call this out? Incremental configuration layering is deceptively complex once you introduce cancellation and reuse. Many libraries silently drop updates or leak stale keys; these suites explicitly prevent that class of regression.

Versioning & Stability

• Stable releases follow SemVer; see GitHub Releases or NuGet version history for changes.
• Breaking changes only in MAJOR versions; MINOR for additive features; PATCH for fixes.
• Provider abstractions evolve conservatively.

Packages are published under the NuGet organization cocoar.

Contributing

Issues and PRs are welcome 🎉 Keep provider abstractions stable & deterministic. Examples and docs are validated in CI.

(This README reflects the current state – future optimizations & multi-targeting will be documented in docs/.)