Carom 1.7.0

Carom 🎱

A lean, fast, and safe resilience library for .NET

Carom is a zero-dependency resilience library that enforces best practices by default. Named after the billiards shot where the ball bounces before reaching its target, Carom helps your code gracefully handle failures.

Runs on .NET 10 and .NET 8. The core packages target netstandard2.0, so .NET Framework and older .NET are supported too; the ASP.NET Core, EF Core and OpenTelemetry packages target net8.0;net10.0. Tests run on both runtimes in CI.

🎯 Why Carom?

• Zero Dependencies (core packages)
• Minimal Allocations (<100 bytes on hot path)
• Safe by Default (mandatory decorrelated jitter)
• Tiny Footprint (13KB core, 20KB extensions)
• Fully Composable (all patterns work together)

📦 Packages

🚀 Quick Start

Installation

dotnet add package Carom
dotnet add package Carom.Extensions

Basic Usage

using Carom;

// Simple retry with exponential backoff
var result = await Carom.ShotAsync(() => api.CallAsync(), retries: 3);

// With timeout
var bounce = Bounce.Times(5).WithTimeout(TimeSpan.FromSeconds(30));
var data = await Carom.ShotAsync(() => apiClient.FetchAsync(), bounce);

Circuit Breaker

using Carom.Extensions;

var cushion = Cushion.ForService("payment-api")
    .OpenAfter(failures: 5, within: 10)
    .HalfOpenAfter(TimeSpan.FromSeconds(30));

var payment = await CaromCushionExtensions.ShotAsync(
    () => paymentApi.Charge(), 
    cushion);

Fallback

var config = await new Func<Task<AppConfig>>(() => configService.LoadAsync())
    .PocketAsync(AppConfig.Default);

Bulkhead

var dbCompartment = Compartment.ForResource("database")
    .WithMaxConcurrency(10)
    .Build();

var query = await CaromCompartmentExtensions.ShotAsync(
    () => db.QueryAsync(sql), 
    dbCompartment);

Rate Limiting

var apiThrottle = Throttle.ForService("external-api")
    .WithRate(100, TimeSpan.FromSeconds(1))
    .WithBurst(20)
    .Build();

var apiResult = await CaromThrottleExtensions.ShotAsync(
    () => apiClient.CallAsync(), 
    apiThrottle);

🎓 Patterns

�� Documentation

• Security Policy
• Changelog

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

📄 License

MPL-2.0 - see LICENSE for details.

🙏 Acknowledgments

Built with the Baryo.Dev philosophy: zero dependencies, minimal allocations, safe by default.

Made with ❤️ by Baryo.Dev

📊 Performance

Carom is significantly faster than Polly v8:

• 175,000x faster startup (0.02ns vs 3,857ns)
• 15x faster hot path (10.9ns vs 167.8ns)
• 4.8x faster async operations (45ns vs 216ns)

See detailed benchmarks for complete analysis.