Cocoar.Configuration.HttpPolling v0.9.1 — nugetz
cocoar/Cocoar.Configuration.HttpPollingv0.9.1
.NET 9.0
HTTP polling provider for Cocoar.Configuration enabling remote configuration sources with configurable polling intervals, automatic retries, and failure sentinel values for resilient distributed configuration management.
Get Started
$ dotnet add package Cocoar.Configuration.HttpPollingReadme
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" />
<!-- Optional extensions -->
<PackageReference Include="Cocoar.Configuration.AspNetCore" />
<PackageReference Include="Cocoar.Configuration.HttpPolling" />
<PackageReference Include="Cocoar.Configuration.MicrosoftAdapter" />
</ItemGroup>
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(
Rule.From.File(_ => FileSourceRuleOptions.FromFilePath("appsettings.json", "App")).For<AppSettings>().Optional(),
Rule.From.Environment(_ => new EnvironmentVariableRuleOptions("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: Any change → full recompute → atomic snapshot swap
- Dynamic dependencies: Rule factories (options/query) can read in-progress snapshots.
- Required vs Optional: Pptional failure skips the layer.
- DI Lifetimes & Keys: Register as singleton (default), scoped, transient, keyed
Providers
Built-in and extension providers:
| Provider | Package | Change Signal | Notes |
|---|
| Static | Core | ❌ | Seed defaults, compose values |
| File (JSON) | Core | ✅ Filesystem watcher | Deterministic layering |
| Environment | Core | ❌ | Prefix filter; __ & : nesting |
| HTTP Polling | Extension | ✅ | Interval polling, payload diffing |
| Microsoft Adapter | Extension | Depends | Any IConfigurationSource |
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
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
Deep Dive Documentation
For more in-depth documentation, see:
Thread Safety & Performance
- Reading config is thread-safe
- Recompute is O(n) per rules + JSON size
- Providers reused across recomputes when options stable
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/.)