Oragon.ElasticPool 0.1.1-beta

Oragon.ElasticPool

Generic, elastic, self-healing object pool for .NET 8 / 9 / 10 — with built-in OpenTelemetry.

Oragon.ElasticPool is a generic in-process object pool for expensive-to-create resources (clients, connections, handlers). It grows under sustained pressure, shrinks when idle, and heals itself by detecting and replacing broken items through pluggable lifecycle hooks. Async-first, DI-first, observable.

For RabbitMQ IConnection + IChannel pooling, install the companion package Oragon.ElasticPool.RabbitMQ.

Install

dotnet add package Oragon.ElasticPool

30-second quickstart

Every lifecycle hook ships in two flavors — a synchronous overload (no ValueTask wrapping) and the original asynchronous overload. Pick whichever fits what each hook actually does; mix sync and async freely in the same pool.

Sync hooks (no I/O)

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Oragon.ElasticPool.Abstractions;
using Oragon.ElasticPool.DependencyInjection;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddElasticPool<MyExpensiveClient>("default", pool =>
{
    pool.WithBounds(minSize: 1, maxSize: 16, initialSize: 2);
    pool.IdleTimeout(TimeSpan.FromMinutes(2));
    pool.MaxWaiterCount(256); // optional backpressure cap; default is unbounded

    pool.Factory  ((sp, ct) => new MyExpensiveClient());
    pool.BeforeUse((c, ct) => c.IsHealthy ? PoolState.Healthy : PoolState.Unhealthy);
    pool.Release  ((c, ct) => c.Dispose());
});

using var host = builder.Build();
// AddElasticPool registers a *keyed* singleton — match the name above.
var pool = host.Services.GetRequiredKeyedService<IElasticPool<MyExpensiveClient>>("default");

await using var lease = await pool.AcquireAsync();
lease.Value.DoWork();
// On Dispose, the item returns to the pool — or is discarded if BeforeUse said Unhealthy.
var liveItems = pool.Total;   // idle + in-use + being-created
var waiters = pool.Waiting;   // callers parked in AcquireAsync

public sealed class MyExpensiveClient : IDisposable
{
    public bool IsHealthy => true;
    public void DoWork() { /* ... */ }
    public void Dispose() { /* ... */ }
}

Async hooks (when you need I/O)

builder.Services.AddElasticPool<MyExpensiveClient>("default", pool =>
{
    pool.WithBounds(minSize: 1, maxSize: 16, initialSize: 2);

    pool.Factory  (async (sp, ct) => await MyExpensiveClient.CreateAsync(ct));
    pool.BeforeUse(async (c, ct)  => await c.PingAsync(ct) ? PoolState.Healthy : PoolState.Unhealthy);
    pool.Release  (async (c, ct)  => await c.DisposeAsync());
});

The sync overload wraps the result in a completed ValueTask internally — zero allocation on the fast path. Use it whenever the hook doesn't need await.

Why not Microsoft.Extensions.ObjectPool?

Microsoft.Extensions.ObjectPool is great for cheap, stateless, allocation-only pooling (e.g., StringBuilder). Oragon.ElasticPool is for expensive, stateful, lifecycle-sensitive resources where elasticity and health matter.

Three pillars

1. Elasticity — composite-signal grow (waiters + sustained utilization % + p95 acquire-wait), hysteretic shrink to a target size after sustained aggregate low pressure (Available high, InUse low, Waiting zero) past a cooldown since the last grow. No thrashing.
2. Auto-healing — five lifecycle hooks at every stage: Factory (create), BeforeUse (validate on borrow), Check (background sweep), AfterUse (validate on return; opt-in), Release (cleanup/dispose). Pluggable IItemFailurePolicy<T> decides discard vs. quarantine vs. custom.
3. Fluent DX — async-first, DI-first, builder pattern. services.AddElasticPool<T>(name, configure).

OpenTelemetry in 5 lines

Oragon.ElasticPool exposes a Meter and ActivitySource both named "Oragon.ElasticPool". Wire them to any OTel exporter:

using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services
    .AddOpenTelemetry()
    .WithMetrics(m => m.AddMeter("Oragon.ElasticPool").AddConsoleExporter())
    .WithTracing(t => t.AddSource("Oragon.ElasticPool").AddConsoleExporter());
// In production, swap AddConsoleExporter() for AddOtlpExporter() (Aspire / OTel collector / etc.).

The pool emits these metrics out of the box:

All instruments carry a single pool.name tag (the name passed to AddElasticPool). Cardinality stays bounded.

ActivitySource spans: Acquire, Release, HealthCheck, Grow, Shrink. Guarded by HasListeners() so you pay nothing if nobody is listening.

Lifecycle hooks

builder.Services.AddElasticPool<MyClient>("default", pool =>
{
    pool.Factory  ((sp, ct) => /* create new T */);                         // required (sync or async)
    pool.BeforeUse((c, ct) => /* return Healthy / Unhealthy */);            // optional (sync or async)
    pool.Check    ((c, ct) => /* background sweep — return Healthy / Unhealthy */); // optional (sync or async)
    pool.AfterUse ((c, ct) => /* validate on return; v1 default no-op */);  // optional (sync or async)
    pool.Release  ((c, ct) => /* dispose / close — runs on eviction */);    // optional (sync or async)
});

Each method has both a synchronous and an asynchronous overload. Returning PoolState.Healthy/PoolState.Unhealthy directly (sync) is equivalent to returning ValueTask.FromResult(...) (async) but reads cleaner when no await is involved.

Returning PoolState.Unhealthy from any hook invokes the configured IItemFailurePolicy<T>. The default DiscardAndReplaceFailurePolicy<T> discards the item and replaces it if the pool is below MinSize.

Bursty workload sample

See samples/Oragon.ElasticPool.RabbitMQ.Sample.BurstyPublisher for an end-to-end demo: a publisher that goes from "few/hour" to "100k simultaneous" and back to idle, watching the pool grow, shrink, and self-heal — with metrics visible in any OTel collector (Aspire Dashboard, Grafana, Console exporter).

Multi-targeting

Targets net10.0, net9.0, net8.0. No exclusive .NET 10 APIs without #if NET10_0_OR_GREATER guards.

Versioning & API stability

SemVer 2.0. Public surface enforced via Microsoft.CodeAnalysis.PublicApiAnalyzers: breaking changes require an explicit PublicAPI.Unshipped.txt update or the build fails.

Contributing

https://github.com/oragon/Oragon.ElasticPool

License

MIT