diff --git a/.github/workflows/nuget.yml b/.github/workflows/nuget.yml new file mode 100644 index 0000000..3af3970 --- /dev/null +++ b/.github/workflows/nuget.yml @@ -0,0 +1,31 @@ +name: Publish on NuGet + +on: + push: + branches: [ main ] + +jobs: + publish: + name: Build and publish packages + runs-on: ubuntu-latest + environment: + name: nuget + url: https://github.com + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.PAT }} + + - name: Build and publish Incendium.Result if version changed + uses: alirezanet/publish-nuget@v3.0.3 + with: + PROJECT_FILE_PATH: Incendium.Result/Incendium.Result.csproj + PACKAGE_NAME: Incendium.Result + NUGET_KEY: ${{ secrets.NUGET_KEY }} + + - name: Build and publish Incendium.RetryPolicy if version changed + uses: alirezanet/publish-nuget@v3.0.3 + with: + PROJECT_FILE_PATH: Incendium.RetryPolicy/Incendium.RetryPolicy.csproj + PACKAGE_NAME: Incendium.RetryPolicy + NUGET_KEY: ${{ secrets.NUGET_KEY }} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ad9cc7a --- /dev/null +++ b/.gitignore @@ -0,0 +1,352 @@ +## Ignore Visual Studio temporary files, build results, and +## files generated by popular Visual Studio add-ons. +## +## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore + +# User environment +.env +secrets.json +logs/ + +# Certificates +*.p12 + +# User-specific files +*.rsuser +*.suo +*.user +*.userosscache +*.sln.docstates +*.bat + +# User-specific files (MonoDevelop/Xamarin Studio) +*.userprefs + +# Build results +[Dd]ebug/ +[Dd]ebugPublic/ +[Rr]elease/ +[Rr]eleases/ +x64/ +x86/ +[Aa][Rr][Mm]/ +[Aa][Rr][Mm]64/ +bld/ +[Bb]in/ +[Oo]bj/ +[Ll]og/ + +# Visual Studio 2015/2017 cache/options directory +.vs/ +# Uncomment if you have tasks that create the project's static files in wwwroot +#wwwroot/ + +# Visual Studio 2017 auto generated files +Generated\ Files/ + +# MSTest test Results +[Tt]est[Rr]esult*/ +[Bb]uild[Ll]og.* + +# NUNIT +*.VisualState.xml +TestResult.xml + +# Build Results of an ATL Project +[Dd]ebugPS/ +[Rr]eleasePS/ +dlldata.c + +# Benchmark Results +BenchmarkDotNet.Artifacts/ + +# .NET Core +project.lock.json +project.fragment.lock.json +artifacts/ + +# StyleCop +StyleCopReport.xml + +# Files built by Visual Studio +*_i.c +*_p.c +*_h.h +*.ilk +*.meta +*.obj +*.iobj +*.pch +*.pdb +*.ipdb +*.pgc +*.pgd +*.rsp +*.sbr +*.tlb +*.tli +*.tlh +*.tmp +*.tmp_proj +*_wpftmp.csproj +*.log +*.vspscc +*.vssscc +.builds +*.pidb +*.svclog +*.scc + +# Chutzpah Test files +_Chutzpah* + +# Visual C++ cache files +ipch/ +*.aps +*.ncb +*.opendb +*.opensdf +*.sdf +*.cachefile +*.VC.db +*.VC.VC.opendb + +# Visual Studio profiler +*.psess +*.vsp +*.vspx +*.sap + +# Visual Studio Trace Files +*.e2e + +# TFS 2012 Local Workspace +$tf/ + +# Guidance Automation Toolkit +*.gpState + +# ReSharper is a .NET coding add-in +_ReSharper*/ +*.[Rr]e[Ss]harper +*.DotSettings.user + +# JustCode is a .NET coding add-in +.JustCode + +# TeamCity is a build add-in +_TeamCity* + +# DotCover is a Code Coverage Tool +*.dotCover + +# AxoCover is a Code Coverage Tool +.axoCover/* +!.axoCover/settings.json + +# Visual Studio code coverage results +*.coverage +*.coveragexml + +# NCrunch +_NCrunch_* +.*crunch*.local.xml +nCrunchTemp_* + +# MightyMoose +*.mm.* +AutoTest.Net/ + +# Web workbench (sass) +.sass-cache/ + +# Installshield output folder +[Ee]xpress/ + +# DocProject is a documentation generator add-in +DocProject/buildhelp/ +DocProject/Help/*.HxT +DocProject/Help/*.HxC +DocProject/Help/*.hhc +DocProject/Help/*.hhk +DocProject/Help/*.hhp +DocProject/Help/Html2 +DocProject/Help/html + +# Click-Once directory +publish/ + +# Publish Web Output +*.[Pp]ublish.xml +*.azurePubxml +# Note: Comment the next line if you want to checkin your web deploy settings, +# but database connection strings (with potential passwords) will be unencrypted +*.pubxml +*.publishproj + +# Microsoft Azure Web App publish settings. Comment the next line if you want to +# checkin your Azure Web App publish settings, but sensitive information contained +# in these scripts will be unencrypted +PublishScripts/ + +# NuGet Packages +*.nupkg +# The packages folder can be ignored because of Package Restore +**/[Pp]ackages/* +# except build/, which is used as an MSBuild target. +!**/[Pp]ackages/build/ +# Uncomment if necessary however generally it will be regenerated when needed +#!**/[Pp]ackages/repositories.config +# NuGet v3's project.json files produces more ignorable files +*.nuget.props +*.nuget.targets + +# Microsoft Azure Build Output +csx/ +*.build.csdef + +# Microsoft Azure Emulator +ecf/ +rcf/ + +# Windows Store app package directories and files +AppPackages/ +BundleArtifacts/ +Package.StoreAssociation.xml +_pkginfo.txt +*.appx + +# Visual Studio cache files +# files ending in .cache can be ignored +*.[Cc]ache +# but keep track of directories ending in .cache +!*.[Cc]ache/ + +# Others +ClientBin/ +~$* +*~ +*.dbmdl +*.dbproj.schemaview +*.jfm +*.pfx +*.publishsettings +orleans.codegen.cs + +# Including strong name files can present a security risk +# (https://github.com/github/gitignore/pull/2483#issue-259490424) +#*.snk + +# Since there are multiple workflows, uncomment next line to ignore bower_components +# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) +#bower_components/ +# ASP.NET Core default setup: bower directory is configured as wwwroot/lib/ and bower restore is true +**/wwwroot/lib/ + +# RIA/Silverlight projects +Generated_Code/ + +# Backup & report files from converting an old project file +# to a newer Visual Studio version. Backup files are not needed, +# because we have git ;-) +_UpgradeReport_Files/ +Backup*/ +UpgradeLog*.XML +UpgradeLog*.htm +ServiceFabricBackup/ +*.rptproj.bak + +# SQL Server files +*.mdf +*.ldf +*.ndf + +# Business Intelligence projects +*.rdl.data +*.bim.layout +*.bim_*.settings +*.rptproj.rsuser + +# Microsoft Fakes +FakesAssemblies/ + +# GhostDoc plugin setting file +*.GhostDoc.xml + +# Node.js Tools for Visual Studio +.ntvs_analysis.dat +node_modules/ + +# Visual Studio 6 build log +*.plg + +# Visual Studio 6 workspace options file +*.opt + +# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) +*.vbw + +# Visual Studio LightSwitch build output +**/*.HTMLClient/GeneratedArtifacts +**/*.DesktopClient/GeneratedArtifacts +**/*.DesktopClient/ModelManifest.xml +**/*.Server/GeneratedArtifacts +**/*.Server/ModelManifest.xml +_Pvt_Extensions + +# Paket dependency manager +.paket/paket.exe +paket-files/ + +# FAKE - F# Make +.fake/ + +# JetBrains Rider +.idea/ +*.sln.iml + +# CodeRush personal settings +.cr/personal + +# Python Tools for Visual Studio (PTVS) +__pycache__/ +*.pyc + +# Cake - Uncomment if you are using it +# tools/** +# !tools/packages.config + +# Tabs Studio +*.tss + +# Telerik's JustMock configuration file +*.jmconfig + +# BizTalk build output +*.btp.cs +*.btm.cs +*.odx.cs +*.xsd.cs + +# OpenCover UI analysis results +OpenCover/ + +# Azure Stream Analytics local run output +ASALocalRun/ + +# MSBuild Binary and Structured Log +*.binlog + +# NVidia Nsight GPU debugger configuration file +*.nvuser + +# MFractors (Xamarin productivity tool) working folder +.mfractor/ + +# Local History for Visual Studio +.localhistory/ + +.vscode +.ionide + +.DS_Store \ No newline at end of file diff --git a/Images/icon.png b/Images/icon.png new file mode 100644 index 0000000..5cf504a Binary files /dev/null and b/Images/icon.png differ diff --git a/Images/icon_big.png b/Images/icon_big.png new file mode 100644 index 0000000..923824f Binary files /dev/null and b/Images/icon_big.png differ diff --git a/Incendium.Result/Error.cs b/Incendium.Result/Error.cs new file mode 100644 index 0000000..1e6fd90 --- /dev/null +++ b/Incendium.Result/Error.cs @@ -0,0 +1,36 @@ +using System; + +namespace Incendium +{ + /// + /// Represents error struct that contains code, message and optionally exception + /// + /// Error code + /// Error message + /// Inner exception + public readonly struct Error(int code, string message, Exception? exception) + { + /// + /// Gets error code + /// + public int Code { get; init; } = code; + /// + /// Gets error message + /// + public string Message { get; init; } = message; + /// + /// Gets optional inner exception + /// + public Exception? Exception { get; init; } = exception; + + /// + /// Initialize a new instance of the Error struct with a specified error code and message + /// + /// Error code + /// Error message + public Error(int code, string message) + : this(code, message, exception: null) + { + } + } +} diff --git a/Incendium.Result/Extensions/ErrorExtensions.cs b/Incendium.Result/Extensions/ErrorExtensions.cs new file mode 100644 index 0000000..da576ae --- /dev/null +++ b/Incendium.Result/Extensions/ErrorExtensions.cs @@ -0,0 +1,26 @@ +using System; + +namespace Incendium.Extensions +{ + public static class ErrorExtensions + { + /// + /// Gets error code + /// + /// Nullable error + /// Error code + public static int Code(this Error? error) => error!.Value.Code; + /// + /// Gets error message + /// + /// Nullable error + /// Error message + public static string Message(this Error? error) => error!.Value.Message; + /// + /// Gets inner exception + /// + /// Nullable error + /// Inner exception + public static Exception? Exception(this Error? error) => error!.Value.Exception; + } +} diff --git a/Incendium.Result/Incendium.Result.csproj b/Incendium.Result/Incendium.Result.csproj new file mode 100644 index 0000000..22dc1b7 --- /dev/null +++ b/Incendium.Result/Incendium.Result.csproj @@ -0,0 +1,45 @@ + + + + netstandard2.1 + preview + enable + $(SolutionName) + + + + icon.png + result;noexcept + README.md + LICENSE.txt + + git + https://github.com/matsakiv/Incendium + + Incendium.Result + mativ + Provides a Result<T> type that allows a method to return both a value and an error in Rust style without exceptions + 1.0.0 + Copyright © Igor Matsak + + + + + True + \ + + + True + \ + + + True + \ + + + + + + + + diff --git a/Incendium.Result/IsExternalInit.cs b/Incendium.Result/IsExternalInit.cs new file mode 100644 index 0000000..11f062f --- /dev/null +++ b/Incendium.Result/IsExternalInit.cs @@ -0,0 +1,4 @@ +namespace System.Runtime.CompilerServices +{ + internal static class IsExternalInit { } +} diff --git a/Incendium.Result/Result.cs b/Incendium.Result/Result.cs new file mode 100644 index 0000000..debf13e --- /dev/null +++ b/Incendium.Result/Result.cs @@ -0,0 +1,78 @@ +namespace Incendium +{ + /// + /// Represents result type that can contain a not null success value or error + /// + /// Type of value + public readonly struct Result + { + /// + /// Not null success value + /// + public T Value { get; init; } + /// + /// Error value + /// + public Error? Error { get; init; } + + /// + /// Initialize result instance from success value + /// + /// Value if success + public static implicit operator Result(T value) => new() { Value = value }; + /// + /// Initialize result instance from error value + /// + /// Error value + public static implicit operator Result(Error error) => new() { Error = error }; + /// + /// Initialize result instance from nullable error value + /// + /// Nullable error value + public static implicit operator Result(Error? error) => new() { Error = error }; + + public void Deconstruct(out T value, out Error? error) + { + value = Value; + error = Error; + } + } + + /// + /// Represents result type that can contain a nullable success value or error + /// + /// + public readonly struct NullableResult + { + /// + /// Not null success value + /// + public T? Value { get; init; } + /// + /// Error value + /// + public Error? Error { get; init; } + + /// + /// Initialize result instance from success value + /// + /// Value if success + public static implicit operator NullableResult(T value) => new() { Value = value }; + /// + /// Initialize result instance from error value + /// + /// Error value + public static implicit operator NullableResult(Error error) => new() { Error = error }; + /// + /// Initialize result instance from nullable error value + /// + /// Nullable error value + public static implicit operator NullableResult(Error? error) => new() { Error = error }; + + public void Deconstruct(out T? value, out Error? error) + { + value = Value; + error = Error; + } + } +} diff --git a/Incendium.RetryPolicy/Abstract/IRateGate.cs b/Incendium.RetryPolicy/Abstract/IRateGate.cs new file mode 100644 index 0000000..866e34d --- /dev/null +++ b/Incendium.RetryPolicy/Abstract/IRateGate.cs @@ -0,0 +1,30 @@ +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace Incendium.RetryPolicy.Abstract +{ + public interface IRateGate : IDisposable + { + /// + /// Asynchronously waits to proceed execution + /// + /// A cancellation token to cancel operation + /// The task object representing the asynchronous operation + Task WaitToProceedAsync(CancellationToken cancellationToken = default); + /// + /// Asynchronously waits to proceed execution during + /// + /// Timeout in milliseconds + /// A cancellation token to cancel operation + /// The task object representing the asynchronous operation + Task WaitToProceedAsync(int millisecondsTimeout, CancellationToken cancellationToken = default); + /// + /// Asynchronously waits to proceed execution during + /// + /// Timeout + /// A cancellation token to cancel operation + /// The task object representing the asynchronous operation + Task WaitToProceedAsync(TimeSpan timeout, CancellationToken cancellationToken = default); + } +} \ No newline at end of file diff --git a/Incendium.RetryPolicy/Common/ConcurrentRandom.cs b/Incendium.RetryPolicy/Common/ConcurrentRandom.cs new file mode 100644 index 0000000..d4c3a6c --- /dev/null +++ b/Incendium.RetryPolicy/Common/ConcurrentRandom.cs @@ -0,0 +1,21 @@ +using System; + +namespace Incendium.RetryPolicy.Common +{ + internal sealed class ConcurrentRandom(int? seed = null) + { + private static readonly Random _static_random = new(); + + private readonly Random _random = !seed.HasValue + ? _static_random + : new Random(seed.Value); + + public double NextDouble() + { + lock (_random) + { + return _random.NextDouble(); + } + } + } +} diff --git a/Incendium.RetryPolicy/Delays.cs b/Incendium.RetryPolicy/Delays.cs new file mode 100644 index 0000000..805e0a1 --- /dev/null +++ b/Incendium.RetryPolicy/Delays.cs @@ -0,0 +1,117 @@ +using System; +using System.Collections.Generic; +using Incendium.RetryPolicy.Common; + +namespace Incendium.RetryPolicy +{ + public static class Delays + { + /// + /// Gets a set of constant delays which are equal to + /// + /// For example, calling with count equal to 3 will create an enumeration like [delay, delay, delay] + /// Delay + /// Number of delays + /// Enumeration containing delays + /// + public static IEnumerable Constant(TimeSpan delay, int count) + { + if (delay < TimeSpan.Zero) + throw new ArgumentOutOfRangeException(nameof(delay), delay, "Should be >= 0ms"); + + if (count < 0) + throw new ArgumentOutOfRangeException(nameof(count), count, "Should be >= 0"); + + if (count == 0) + yield break; + + for (var i = 0; i < count; i++) + yield return delay; + } + + /// + /// Gets a set of exponential delays starting with and multiplying them by a + /// + /// For example, calling with count equal to 3 and factor 2 will create an enumeration like [firstDelay, firstDelay*2, firstDelay*4] + /// First delay + /// Number of delays + /// Factor, default is 2 + /// Enumeration containing delays + /// + public static IEnumerable Exponential(TimeSpan firstDelay, int count, double factor = 2) + { + if (firstDelay < TimeSpan.Zero) + throw new ArgumentOutOfRangeException(nameof(firstDelay), firstDelay, "Should be >= 0ms"); + + if (count < 0) + throw new ArgumentOutOfRangeException(nameof(count), count, "Should be >= 0"); + + if (factor <= 0) + throw new ArgumentOutOfRangeException(nameof(factor), factor, "Should be > 0"); + + if (count == 0) + yield break; + + for (var i = 0; i < count; i++) + { + yield return firstDelay; + + firstDelay *= factor; + } + } + + /// + /// Gets a set of exponential delays with randomized deviation (jitter) to prevent peak loads + /// + /// Median first delay + /// Number of delays + /// Seed for additional jitter randomization + /// Flag indicating whether the first delay should be set to zero (fast) + /// Enumeration containing delays + /// + public static IEnumerable DecorrelatedJitterBackoffV2( + TimeSpan medianFirstDelay, + int count, + int? seed = null, + bool fastFirst = false) + { + if (medianFirstDelay < TimeSpan.Zero) + throw new ArgumentOutOfRangeException(nameof(medianFirstDelay), medianFirstDelay, "Should be >= 0ms"); + + if (count < 0) + throw new ArgumentOutOfRangeException(nameof(count), count, "Should be >= 0"); + + if (count == 0) + return []; + + return Enumerate(medianFirstDelay, count, fastFirst, new ConcurrentRandom(seed)); + + static IEnumerable Enumerate(TimeSpan scaleFirstTry, int maxRetries, bool fast, ConcurrentRandom random) + { + var maxValue = TimeSpan.MaxValue; + var maxTimeSpanDouble = maxValue.Ticks - 1000.0; + int i = 0; + + if (fast) + { + i++; + yield return TimeSpan.Zero; + } + + var targetTicksFirstDelay = scaleFirstTry.Ticks; + var num = 0.0; + + for (; i < maxRetries; i++) + { + var num2 = i + random.NextDouble(); + var next = Math.Pow(2.0, num2) * Math.Tanh(Math.Sqrt(4.0 * num2)); + var num3 = next - num; + + yield return TimeSpan.FromTicks((long)Math.Min(num3 * 0.7142857142857143 * targetTicksFirstDelay, maxTimeSpanDouble)); + + num = next; + } + } + } + } +} diff --git a/Incendium.RetryPolicy/Incendium.RetryPolicy.csproj b/Incendium.RetryPolicy/Incendium.RetryPolicy.csproj new file mode 100644 index 0000000..4321985 --- /dev/null +++ b/Incendium.RetryPolicy/Incendium.RetryPolicy.csproj @@ -0,0 +1,40 @@ + + + + netstandard2.1 + preview + enable + + + + icon.png + LICENSE.txt + README.md + retry;retrypolicy;rate;ratelimit + + git + https://github.com/matsakiv/Incendium + + Incendium.RetryPolicy + mativ + Provides classes for easily managing requests rate limits and retrying after errors + 1.0.0 + Copyright © Igor Matsak + + + + + True + \ + + + True + \ + + + True + \ + + + + diff --git a/Incendium.RetryPolicy/IsExternalInit.cs b/Incendium.RetryPolicy/IsExternalInit.cs new file mode 100644 index 0000000..11f062f --- /dev/null +++ b/Incendium.RetryPolicy/IsExternalInit.cs @@ -0,0 +1,4 @@ +namespace System.Runtime.CompilerServices +{ + internal static class IsExternalInit { } +} diff --git a/Incendium.RetryPolicy/RateGate.cs b/Incendium.RetryPolicy/RateGate.cs new file mode 100644 index 0000000..6e64db7 --- /dev/null +++ b/Incendium.RetryPolicy/RateGate.cs @@ -0,0 +1,150 @@ +using System; +using System.Collections.Concurrent; +using System.Threading; +using System.Threading.Tasks; +using Incendium.RetryPolicy.Abstract; + +namespace Incendium.RetryPolicy +{ + /// + /// Represents a class that controls the number of requests in a given time unit + /// + public class RateGate : IDisposable, IRateGate + { + private readonly SemaphoreSlim _semaphore; + private readonly ConcurrentQueue _exitTimes; + private readonly Timer _exitTimer; + private bool _isDisposed; + + /// + /// Number of requests per time unit + /// + public int Occurrences { get; private set; } + /// + /// Time unit in milliseconds + /// + public int TimeUnitMilliseconds { get; private set; } + + /// + /// Initialize a new instance of the RateGate with the number of requests and time unit + /// + /// Number of requests per time unit + /// Time unit + /// + public RateGate(int occurrences, TimeSpan timeUnit) + { + if (occurrences <= 0) + throw new ArgumentOutOfRangeException(nameof(occurrences), "Number of occurrences must be a positive integer"); + if (timeUnit != timeUnit.Duration()) + throw new ArgumentOutOfRangeException(nameof(timeUnit), "Time unit must be a positive span of time"); + if (timeUnit >= TimeSpan.FromMilliseconds(uint.MaxValue)) + throw new ArgumentOutOfRangeException(nameof(timeUnit), "Time unit must be less than 2^32 milliseconds"); + + Occurrences = occurrences; + TimeUnitMilliseconds = (int)timeUnit.TotalMilliseconds; + + _semaphore = new SemaphoreSlim(Occurrences, Occurrences); + _exitTimes = new ConcurrentQueue(); + _exitTimer = new Timer(ExitTimerCallback, null, TimeUnitMilliseconds, -1); + } + + private void ExitTimerCallback(object? state) + { + try + { + var exitTimeValid = _exitTimes.TryPeek(out int exitTime); + + while (exitTimeValid) + { + if (unchecked(exitTime - Environment.TickCount) > 0) + break; + + _semaphore.Release(); + _exitTimes.TryDequeue(out exitTime); + + exitTimeValid = _exitTimes.TryPeek(out exitTime); + } + + var timeUntilNextCheck = exitTimeValid + ? Math.Min(TimeUnitMilliseconds, Math.Max(0, exitTime - Environment.TickCount)) + : TimeUnitMilliseconds; + + _exitTimer.Change(timeUntilNextCheck, -1); + } + catch (Exception) + { + // can throw if called when disposing + } + } + + /// + /// + /// + /// + public async Task WaitToProceedAsync( + int millisecondsTimeout, + CancellationToken cancellationToken = default) + { + if (millisecondsTimeout < -1) + throw new ArgumentOutOfRangeException(nameof(millisecondsTimeout)); + + CheckDisposed(); + + var entered = await _semaphore.WaitAsync(millisecondsTimeout, cancellationToken); + + if (entered) + { + var timeToExit = unchecked(Environment.TickCount + TimeUnitMilliseconds); + _exitTimes.Enqueue(timeToExit); + } + + return entered; + } + + /// + /// + /// + /// + public Task WaitToProceedAsync( + TimeSpan timeout, + CancellationToken cancellationToken = default) + { + return WaitToProceedAsync((int)timeout.TotalMilliseconds, cancellationToken); + } + + /// + /// + /// + /// + public async Task WaitToProceedAsync(CancellationToken cancellationToken = default) + { + await WaitToProceedAsync(Timeout.Infinite, cancellationToken); + } + + private void CheckDisposed() + { + if (_isDisposed) + throw new ObjectDisposedException("RateGate is already disposed"); + } + + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool isDisposing) + { + if (!_isDisposed) + { + if (isDisposing) + { + _semaphore.Dispose(); + _exitTimer.Dispose(); + + _isDisposed = true; + } + } + } + } +} diff --git a/Incendium.RetryPolicy/RetryHttpClientHandler.cs b/Incendium.RetryPolicy/RetryHttpClientHandler.cs new file mode 100644 index 0000000..063d6a6 --- /dev/null +++ b/Incendium.RetryPolicy/RetryHttpClientHandler.cs @@ -0,0 +1,146 @@ +using Incendium.RetryPolicy.Abstract; +using System; +using System.Collections.Generic; +using System.Net; +using System.Net.Http; +using System.Threading; +using System.Threading.Tasks; + +namespace Incendium.RetryPolicy +{ + /// + /// Represents HTTP client handler which allows you to resend requests in case of errors and control the number of requests sent per unit of time + /// + /// Inner HTTP message handler used to send requests + public class RetryHttpClientHandler(HttpMessageHandler httpMessageHandler) + : DelegatingHandler(httpMessageHandler) + { + private bool _isDisposed; + private IRateGate? _rateGate; + + /// + /// Retry count + /// + public int RetryCount { get; init; } + /// + /// Flag indicating whether the request should be resent in case of an HttpRequestException error + /// + public bool RetryOnHttpRequestException { get; init; } + /// + /// Delay for first retry attempt + /// + public TimeSpan FirstRetryDelay { get; init; } + /// + /// An object that controls the number of requests per unit of time. If equal to null, no control is performed + /// + public IRateGate? RateGate { get => _rateGate; init => _rateGate = value; } + /// + /// A custom factory used to get a set of delays. By default Delays.DecorrelatedJitterBackoffV2 is used + /// + public Func>? RetryDelaysFactory { get; init; } + + protected override async Task SendAsync( + HttpRequestMessage request, + CancellationToken cancellationToken) + { + IEnumerator? delays = null; + var retryCount = RetryCount; + + while (true) + { + try + { + if (_rateGate != null) + await _rateGate.WaitToProceedAsync(cancellationToken); + + var response = await base.SendAsync(request, cancellationToken); + + if (!response.IsSuccessStatusCode && + retryCount > 0 && + (IsServerError(response.StatusCode) || + IsRequestTimeoutError(response.StatusCode) || + IsTooManyRequestsError(response.StatusCode))) + { + delays ??= GetRetryDelays().GetEnumerator(); + + if (delays.MoveNext()) + { + var delay = delays.Current; + + retryCount--; + + await Task.Delay(delay, cancellationToken); + + continue; + } + } + + return response; + } + catch (HttpRequestException) + { + if (!RetryOnHttpRequestException) + throw; + + delays ??= GetRetryDelays().GetEnumerator(); + + if (retryCount > 0 && delays.MoveNext()) + { + var delay = delays.Current; + + retryCount--; + + await Task.Delay(delay, cancellationToken); + + continue; + } + + throw; + } + } + } + + private IEnumerable GetRetryDelays() => RetryDelaysFactory?.Invoke() ?? + Delays.DecorrelatedJitterBackoffV2(FirstRetryDelay, RetryCount); + + /// + /// Check if HTTP status code represents server error (5xx) + /// + /// HTTP status code + /// true if code represents server error, otherwise false + public static bool IsServerError(HttpStatusCode code) => + code >= HttpStatusCode.InternalServerError && (int)code < 600; + + /// + /// Check if HTTP status code represents request timeout error (408) + /// + /// HTTP status code + /// true if code represents request timeout error, otherwise false + public static bool IsRequestTimeoutError(HttpStatusCode code) => + code == HttpStatusCode.RequestTimeout; + + /// + /// Check if HTTP status code represents too many requests (429) + /// + /// HTTP status code + /// true if code represents too many request error, otherwise false + public static bool IsTooManyRequestsError(HttpStatusCode code) => + code == HttpStatusCode.TooManyRequests; + + protected override void Dispose(bool disposing) + { + if (!_isDisposed) + { + if (disposing) + { + _rateGate?.Dispose(); + _rateGate = null; + } + + _isDisposed = true; + } + + base.Dispose(disposing); + } + } +} diff --git a/Incendium.Tests/Incendium.Tests.csproj b/Incendium.Tests/Incendium.Tests.csproj new file mode 100644 index 0000000..9a99cc5 --- /dev/null +++ b/Incendium.Tests/Incendium.Tests.csproj @@ -0,0 +1,29 @@ + + + + net8.0 + enable + enable + + false + true + $(SolutionName) + + + + + + + + + + + + + + + + + + + diff --git a/Incendium.Tests/Result/ResultsTests.cs b/Incendium.Tests/Result/ResultsTests.cs new file mode 100644 index 0000000..b7773a8 --- /dev/null +++ b/Incendium.Tests/Result/ResultsTests.cs @@ -0,0 +1,81 @@ +using Incendium.Extensions; + +namespace Incendium.Result +{ + public class ResultsTests + { + private record TestObject(int IntField, string? StringField); + + [Fact] + public void Test_Result_DeconstructWhenSuccess() + { + // act + var (result, error) = GetResult(withError: false); + + // asserts + Assert.Equal(12, result.IntField); + Assert.Equal("Test", result.StringField); + Assert.NotNull(result); + Assert.Null(error); + } + + [Fact] + public void Test_Result_DeconstructWhenError() + { + // act + var (result, error) = GetResult(withError: true); + + // asserts + Assert.Null(result); + Assert.NotNull(error); + Assert.Equal(100, error.Value.Code); + Assert.Equal("Error", error.Value.Message); + Assert.Equal(100, error.Code()); + Assert.Equal("Error", error.Message()); + } + + [Fact] + public void Test_NullableResult_DeconstructWhenSuccess() + { + // act + var (result, error) = GetNullableResult(withError: false); + + // asserts + Assert.Equal(12, result!.IntField); + Assert.Equal("Test", result.StringField); + Assert.NotNull(result); + Assert.Null(error); + } + + [Fact] + public void Test_NullableResult_DeconstructWhenError() + { + // act + var (result, error) = GetNullableResult(withError: true); + + // asserts + Assert.Null(result); + Assert.NotNull(error); + Assert.Equal(100, error.Value.Code); + Assert.Equal("Error", error.Value.Message); + Assert.Equal(100, error.Code()); + Assert.Equal("Error", error.Message()); + } + + private static Result GetResult(bool withError) + { + if (withError) + return new Error(code: 100, message: "Error"); + + return new TestObject(12, "Test"); + } + + private static NullableResult GetNullableResult(bool withError) + { + if (withError) + return new Error(code: 100, message: "Error"); + + return new TestObject(12, "Test"); + } + } +} diff --git a/Incendium.Tests/RetryPolicy/RateGateTests.cs b/Incendium.Tests/RetryPolicy/RateGateTests.cs new file mode 100644 index 0000000..8d18251 --- /dev/null +++ b/Incendium.Tests/RetryPolicy/RateGateTests.cs @@ -0,0 +1,31 @@ +using System.Diagnostics; + +namespace Incendium.RetryPolicy +{ + public class RateGateTests + { + [Fact] + public async Task Test_RateGate_LimitRequestsByOneThread() + { + // arrange + const int callsPerTimeUnit = 5; + const int callsCount = 15; + + var timeUnit = TimeSpan.FromSeconds(1); + var expectedDuration = timeUnit * (callsCount - callsPerTimeUnit) / callsPerTimeUnit; + + var rateGate = new RateGate(occurrences: callsPerTimeUnit, timeUnit); + + var stopWatch = Stopwatch.StartNew(); + + // act + for (var i = 0; i < callsCount; ++i) + await rateGate.WaitToProceedAsync(); + + stopWatch.Stop(); + + // asserts + Assert.True(stopWatch.Elapsed >= expectedDuration); + } + } +} diff --git a/Incendium.Tests/RetryPolicy/RetryHttpClientHandlerTests.cs b/Incendium.Tests/RetryPolicy/RetryHttpClientHandlerTests.cs new file mode 100644 index 0000000..a846e05 --- /dev/null +++ b/Incendium.Tests/RetryPolicy/RetryHttpClientHandlerTests.cs @@ -0,0 +1,236 @@ +using System.Diagnostics; +using System.Net; + +namespace Incendium.RetryPolicy +{ + public class RetryHttpClientHandlerTests + { + private class MockHttpClientHandler : HttpMessageHandler + { + public const string MESSAGE = "Test HttpRequestException"; + public int SendCallCount { get; private set; } + + private readonly HttpStatusCode _responseCode; + private readonly bool _throwHttpRequestException; + + public MockHttpClientHandler(bool throwHttpRequestException) + { + _throwHttpRequestException = throwHttpRequestException; + } + + public MockHttpClientHandler(HttpStatusCode responseCode) + { + _responseCode = responseCode; + } + + protected override Task SendAsync( + HttpRequestMessage request, + CancellationToken cancellationToken) + { + SendCallCount++; + + if (_throwHttpRequestException) + throw new HttpRequestException(MESSAGE); + + return Task.FromResult(new HttpResponseMessage(_responseCode)); + } + } + + [Fact] + public async Task Test_RetryHttpClientHandler_RetryOnHttpException() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(throwHttpRequestException: true); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + HttpRequestException? exception = null; + + // act + try + { + await httpClient.SendAsync(httpRequestMessage); + } + catch (HttpRequestException e) + { + exception = e; + } + + // asserts + Assert.Equal(retryCount, mockHttpClientHandler.SendCallCount - 1); + Assert.NotNull(exception); + Assert.Equal(MockHttpClientHandler.MESSAGE, exception.Message); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_RetryOnServerError() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.InternalServerError); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + + // act + var response = await httpClient.SendAsync(httpRequestMessage); + + // asserts + Assert.Equal(retryCount, mockHttpClientHandler.SendCallCount - 1); + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.InternalServerError, response.StatusCode); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_RetryOnRequestTimeoutError() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.RequestTimeout); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + + // act + var response = await httpClient.SendAsync(httpRequestMessage); + + // asserts + Assert.Equal(retryCount, mockHttpClientHandler.SendCallCount - 1); + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.RequestTimeout, response.StatusCode); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_RetryOnTooManyRequestsError() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.TooManyRequests); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + + // act + var response = await httpClient.SendAsync(httpRequestMessage); + + // asserts + Assert.Equal(retryCount, mockHttpClientHandler.SendCallCount - 1); + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.TooManyRequests, response.StatusCode); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_NoRetryOnBadRequestError() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.BadRequest); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + + // act + var response = await httpClient.SendAsync(httpRequestMessage); + + // asserts + Assert.Equal(1, mockHttpClientHandler.SendCallCount); + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_NoRetryOnSuccess() + { + // arrange + var retryCount = 3; + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.OK); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + + // act + var response = await httpClient.SendAsync(httpRequestMessage); + + // asserts + Assert.Equal(1, mockHttpClientHandler.SendCallCount); + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + } + + [Fact] + public async Task Test_RetryHttpClientHandler_RateLimit() + { + // arrange + var rateLimit = 5; + var rateLimitPeriod = TimeSpan.FromSeconds(1); + var retryCount = 3; + var totalRequests = 15; + var expectedDuration = rateLimitPeriod * (totalRequests - rateLimit) / rateLimit; + + var mockHttpClientHandler = new MockHttpClientHandler(HttpStatusCode.OK); + var retryHttpClientHandler = new RetryHttpClientHandler(mockHttpClientHandler) + { + RetryCount = retryCount, + RetryOnHttpRequestException = true, + FirstRetryDelay = TimeSpan.FromMilliseconds(100), + RateGate = new RateGate( + occurrences: rateLimit, + timeUnit: rateLimitPeriod) + }; + var httpClient = new HttpClient(retryHttpClientHandler); + + var responses = new HttpResponseMessage[totalRequests]; + var stopWatch = Stopwatch.StartNew(); + + // act + for (var i = 0; i < totalRequests; ++i) + { + var httpRequestMessage = new HttpRequestMessage(HttpMethod.Get, "http://localhost"); + responses[i] = await httpClient.SendAsync(httpRequestMessage); + } + + stopWatch.Stop(); + + // asserts + Assert.Equal(totalRequests, mockHttpClientHandler.SendCallCount); + Assert.True(stopWatch.Elapsed >= expectedDuration); + + foreach (var response in responses) + { + Assert.NotNull(response); + Assert.Equal(HttpStatusCode.OK, response.StatusCode); + } + } + } +} diff --git a/Incendium.sln b/Incendium.sln new file mode 100644 index 0000000..55eb4a7 --- /dev/null +++ b/Incendium.sln @@ -0,0 +1,37 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 17 +VisualStudioVersion = 17.9.34607.119 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Incendium.Result", "Incendium.Result\Incendium.Result.csproj", "{57B0A352-4FE6-4ECC-87C1-066966429B90}" +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Incendium.Tests", "Incendium.Tests\Incendium.Tests.csproj", "{53D9492E-9EE9-48F7-9CB9-642AAB2E8D1D}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Incendium.RetryPolicy", "Incendium.RetryPolicy\Incendium.RetryPolicy.csproj", "{9B2DCBEC-61F3-4484-9426-98E280FCF7DB}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {57B0A352-4FE6-4ECC-87C1-066966429B90}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {57B0A352-4FE6-4ECC-87C1-066966429B90}.Debug|Any CPU.Build.0 = Debug|Any CPU + {57B0A352-4FE6-4ECC-87C1-066966429B90}.Release|Any CPU.ActiveCfg = Release|Any CPU + {57B0A352-4FE6-4ECC-87C1-066966429B90}.Release|Any CPU.Build.0 = Release|Any CPU + {53D9492E-9EE9-48F7-9CB9-642AAB2E8D1D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {53D9492E-9EE9-48F7-9CB9-642AAB2E8D1D}.Debug|Any CPU.Build.0 = Debug|Any CPU + {53D9492E-9EE9-48F7-9CB9-642AAB2E8D1D}.Release|Any CPU.ActiveCfg = Release|Any CPU + {53D9492E-9EE9-48F7-9CB9-642AAB2E8D1D}.Release|Any CPU.Build.0 = Release|Any CPU + {9B2DCBEC-61F3-4484-9426-98E280FCF7DB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {9B2DCBEC-61F3-4484-9426-98E280FCF7DB}.Debug|Any CPU.Build.0 = Debug|Any CPU + {9B2DCBEC-61F3-4484-9426-98E280FCF7DB}.Release|Any CPU.ActiveCfg = Release|Any CPU + {9B2DCBEC-61F3-4484-9426-98E280FCF7DB}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ExtensibilityGlobals) = postSolution + SolutionGuid = {41448C2A-C2BA-400E-BD92-BAC6E3A50BF8} + EndGlobalSection +EndGlobal diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..6ba5eae --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) Igor Matsak + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3226c8 --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +# Incendium +[![License: MIT](https://img.shields.io/github/license/matsakiv/incendium)](https://opensource.org/licenses/MIT) +Incendium.Result +![NuGet Version](https://img.shields.io/nuget/v/Incendium.Result)![NuGet Downloads](https://img.shields.io/nuget/dt/Incendium.Result) +Incendium.RetryPolicy +![NuGet Version](https://img.shields.io/nuget/v/Incendium.RetryPolicy)![NuGet Downloads](https://img.shields.io/nuget/dt/Incendium.RetryPolicy) + +Incendium is a small set of useful cross-platform .NET standard 2.1 libraries for .NET developers. + +| Package | Description | +| --------- | ----------- | +| Incendium.Result | Contains `Error`, `Result` and `NullableResult` types which allows to return a success value or an error (something vaguely similar to the Rust style) | +| Incendium.RetryPolicy | Provides `RetryHttpClientHandler` to easily retry HTTP requests in case of errors, as well as `RateGate` to control rate limiting | + +## Getting started + +### Installation + +`PM> Install-Package Incendium.Result` + +`PM> Install-Package Incendium.RetryPolicy` + +### Result and NullableResult + +The method can be synchronous or asynchronous and can return a value without explicitly creating a `Result` type: + +```cs +public async Result GetStringAsync() { + // ... + if (condition1) { + return "Test string result"; + } else { + return new Error(code: 123, message: "Test error"); + } + + try { + // ... + } catch (Exception e) { + return new Error(code: 321, message: "Test error", exception: e); + } +} +``` +Then processing the result might look like this: + +```cs +var (str, error) = await GetStringAsync(); + +if (error != null) { + log.LogError( + error.Exception(), + "Error with code {@code} and message {@message}", + error.Code(), + error.Message()); +} +``` +### RetryHttpClientHandler + +Сan be used as a handler for `HttpClient` and allows you to easily (compared to Polly) set up repeated requests in the following cases: +* `HttpNetworkException` +* Server errors (`5xx`) +* Request timeout error (`408`) +* Too many requests (`429`) + +and also allows you to configure rate limiting with exponential delays for outgoing requests using `RateGate`: + +```cs +var innerHttpClientHandler = new HttpClientHandler(); // can be easily mocked +var retryHttpClientHandler = new RetryHttpClientHandler(innerHttpClientHandler) +{ + RetryCount = 5, // sets 5 retry attempts + RetryOnHttpRequestException = true, // sets the retry flag in case of an HttpRequestException + FirstRetryDelay = TimeSpan.FromMilliseconds(100), // sets the median starting delay between requests + RateGate = new RateGate( + occurrences: 10, // sets rate limit to 10 request per 60 seconds + timeUnit: TimeSpan.FromSeconds(60)) +} +var httpClient = new HttpClient(retryHttpClientHandler); +``` + +There are several ready-made delay algorithms that can be used: +* Constant +* Exponential +* DecorrelatedJitterBackoffV2 (default) + +```cs +var retryHttpClientHandler = new RetryHttpClientHandler(innerHttpClientHandler) +{ + RetryDelaysFactory = () => Delays.Exponential( + firstDelay: TimeSpan.FromMilliseconds(100), + count: 10) +} +``` + +You can also pass your own delay algorithm in the `RetryDelaysFactory` property, which should return `IEnumerable`.