Cocoar.Configuration 0.14.0

Cocoar.Configuration

Powerful layered configuration for .NET
Simple • Strongly typed • Reactive

Why?

Most apps just need: "Give me my configs, layered, strongly typed, and keep them fresh."

Cocoar.Configuration lets you:

• Define a few ordered rules → get ready-to-inject types
• Layer file + env + http + static sources deterministically (last-write-wins per key)
• Get push updates automatically via IReactiveConfig<T> (no extra setup)

If you need more later (interface binding, DI lifetime control, custom providers) it’s all there—opt‑in, not in your face.

Quick Start (Minimal ASP.NET Core)

appsettings.json:

{
  "App": {
    "FeatureFlag": true,
    "Message": "Hello from config"
  }
}

Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Register layered configuration (file + environment overlay)
builder.Services.AddCocoarConfiguration([
    Rule.From.File("appsettings.json").Select("App").For<AppSettings>(),
    Rule.From.Environment("APP_").For<AppSettings>()
]);

var app = builder.Build();

// Simple endpoint: inject concrete snapshot (Scoped)
app.MapGet("/feature", (AppSettings cfg) => new {
    snapshotFlag = cfg.FeatureFlag,  // Value at scope start (request)
    message = cfg.Message
});

// Reactive usage example (background logging)
var reactive = app.Services.GetRequiredService<IReactiveConfig<AppSettings>>();
var _ = reactive.Subscribe(c => Console.WriteLine($"[Config Updated] FeatureFlag={c.FeatureFlag}"));

app.Run();

public sealed class AppSettings
{
    public bool FeatureFlag { get; set; }
    public string Message { get; set; } = string.Empty;
}

appsettings.json changed? — future requests see the updated snapshot; reactive stream subscribers get a push..

Reactive by Default

Every configuration type you map gets a free reactive companion:

IReactiveConfig<T> gives you:

• CurrentValue – latest stable value
• Subscribe(...) – push updates only when actual content changes
• Safe & error-resilient stream: subscriber exceptions are logged, never terminate the pipeline

Guidance:

• In request/short-lived scopes: inject the concrete type (AppSettings) for a consistent snapshot
• In background services / singletons: inject IReactiveConfig<T>
• Need a frozen value inside a singleton? Capture live.CurrentValue once (rarely required)

Rule Basics

A rule = provider + (optional selection/query) + target config type. Order matters: later rules overwrite earlier values per flattened key (deterministic last-write-wins).

var rules = new [] {
    Rule.From.File("appsettings.json").For<AppSettings>(),
    Rule.From.Environment("APP_").For<AppSettings>()
};

Additional options (add only when needed):

Rule.From.File("secrets.json")
    .Select("Secrets:Db")        // select subtree
    .Mount("Database")           // mount under a new path
    .Required()                  // fail the rule if source missing
    .For<DatabaseConfig>();

Interface Binding (Optional)

Start without it. Add when you want to inject contracts instead of concretes.

services.AddCocoarConfiguration(rules, [
    Bind.Type<AppSettings>().To<IAppSettings>()
]);

public sealed class Handler(IAppSettings cfg, IReactiveConfig<IAppSettings> live)
{ /* ... */ }

More patterns: BINDING.md.

DI Lifetimes & Defaults

By default:

• Concrete config types: Scoped (one snapshot per request/scope)
• IReactiveConfig<T>: Singleton (continuous live updates)

Change the default lifetime:

services.AddCocoarConfiguration(rules, configureServices: o =>
    o.DefaultRegistrationLifetime(ServiceLifetime.Singleton));

Disable auto reactive registration (rare):

o.DisableAutoReactiveRegistration();

Manual overrides & keyed registrations: see ADVANCED.md.

Choosing a Lifetime: | Scenario | Lifetime | |----------|----------| | Typical web request consumption | Scoped | | High-read immutable small config | Singleton | | Background service (reactive) | Scoped + IReactiveConfig<T> (preferred) | | Large object, avoid mid-request drift | Scoped |

Providers (Built-In & Extensions)

Detailed provider docs: PROVIDERS.md.

Performance & Reliability (Short Version)

• Atomic recompute + full snapshot publish
• Incremental: recompute only from earliest changed rule
• Streaming JSON → MD5 hashing (no intermediate string allocations)
• Hash-gated reactive emissions (no duplicate pushes)
• Error-resilient reactive pipelines (no dead observables)
• 80+ tests (stress, cancellation, differential correctness)

Deep dive: ARCHITECTURE.md, CONCEPTS.md.

When You Need More

Installation

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

CLI:

dotnet add package Cocoar.Configuration
dotnet add package Cocoar.Configuration.DI

(Add extensions only when needed.)

Examples

Each example is a standalone runnable project under src/Examples/:

More details: Examples README.

Security Notes

• Do not commit secrets to repo JSON
• Overlay secrets via env/provider layers
• Use TLS + auth for remote polling
• Consider vault integration via Microsoft adapter

Contributing & Versioning

• SemVer (additive MINOR, breaking MAJOR)
• PRs & issues welcome
• Licensed under Apache License 2.0 (explicit patent grant & attribution via NOTICE)

License & Trademark

This project is licensed under the Apache License, Version 2.0. See NOTICE for attribution.

"Cocoar" and related marks are trademarks of COCOAR e.U. Use of the name in forks or derivatives should preserve attribution and avoid implying official endorsement. See TRADEMARKS for permitted and restricted uses.