Files
Febe/src/Febe.Core/Engine/BudgetLimits.cs
T

139 lines
5.9 KiB
C#

using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Engine;
/// <summary>Which reduction of the budgets is in force (spec §7.2 avvio graduale, §7.6 tetti dimezzati).</summary>
public enum BudgetReduction
{
None,
/// <summary>Gradual start: from half to full over the profile's ramp days.</summary>
GradualStart,
/// <summary>Halved for 48 hours after a throttle stop.</summary>
HalvedAfterThrottle,
}
/// <summary>The budgets in force at an instant, after the strongest reduction.</summary>
/// <param name="Budgets">Hourly and daily budget per category (data excluded).</param>
/// <param name="DataPerDayBytes">Daily download budget.</param>
/// <param name="BackfillPostsPerAccountPerDay">The profile's per-account backfill limit, reduced as the budgets.</param>
/// <param name="Factor">Multiplier applied to the profile's values (1 = full).</param>
/// <param name="Reduction">The reduction that determined <paramref name="Factor"/>.</param>
/// <param name="Until">When the reduction ends (end of the ramp or of the 48 hours), if any.</param>
public sealed record EffectiveBudgets(
IReadOnlyDictionary<ActionKind, Budget> Budgets,
long DataPerDayBytes,
int BackfillPostsPerAccountPerDay,
double Factor,
BudgetReduction Reduction,
DateTimeOffset? Until)
{
/// <summary>Daily limit of a category (bytes for data).</summary>
public long DailyLimit(ActionKind kind) => kind == ActionKind.DataDownload ? DataPerDayBytes : Budgets[kind].PerDay;
/// <summary>Hourly limit of a category; null for data, which only has a daily budget.</summary>
public long? HourlyLimit(ActionKind kind) => kind == ActionKind.DataDownload ? null : Budgets[kind].PerHour;
}
/// <summary>
/// Effective budgets (spec §7.4): when several reductions apply together (gradual start, halved budgets after a
/// throttle) the strongest wins, never their product.
/// </summary>
public static class BudgetLimits
{
/// <summary>Gradual start factor: 0.5 at <paramref name="rampStart"/>, rising linearly to 1 after the profile's ramp days.</summary>
public static double GradualStartFactor(CautionProfile profile, DateTimeOffset? rampStart, DateTimeOffset now)
{
ArgumentNullException.ThrowIfNull(profile);
if (!profile.GradualStart || rampStart is not { } start || profile.RampUpDays <= 0)
{
return 1;
}
var elapsed = (now - start).TotalDays;
if (elapsed < 0)
{
return 0.5;
}
return elapsed >= profile.RampUpDays ? 1 : 0.5 + (0.5 * elapsed / profile.RampUpDays);
}
/// <summary>0.5 while the 48 hours after a throttle stop last, otherwise 1.</summary>
public static double ThrottleFactor(DateTimeOffset? halvedUntil, DateTimeOffset now) =>
halvedUntil is { } until && now < until ? 0.5 : 1;
public static EffectiveBudgets Compute(CautionProfile profile, DateTimeOffset? rampStart, DateTimeOffset? halvedUntil, DateTimeOffset now)
{
ArgumentNullException.ThrowIfNull(profile);
var ramp = GradualStartFactor(profile, rampStart, now);
var throttle = ThrottleFactor(halvedUntil, now);
// The strongest reduction wins, never the product (spec §7.4).
var factor = Math.Min(ramp, throttle);
var reduction = factor >= 1 ? BudgetReduction.None
: throttle <= ramp ? BudgetReduction.HalvedAfterThrottle
: BudgetReduction.GradualStart;
DateTimeOffset? until = reduction switch
{
BudgetReduction.HalvedAfterThrottle => halvedUntil,
BudgetReduction.GradualStart => rampStart?.AddDays(profile.RampUpDays),
_ => null,
};
var budgets = new Dictionary<ActionKind, Budget>();
foreach (var (kind, budget) in profile.Budgets)
{
budgets[kind] = new Budget(Scale(budget.PerHour, factor), Scale(budget.PerDay, factor));
}
foreach (var kind in Enum.GetValues<ActionKind>())
{
if (kind != ActionKind.DataDownload && !budgets.ContainsKey(kind))
{
budgets[kind] = new Budget(0, 0);
}
}
return new EffectiveBudgets(
budgets,
ScaleBytes(profile.DataPerDayBytes, factor),
Scale(profile.BackfillPostsPerAccountPerDay, factor),
factor,
reduction,
until);
}
/// <summary>A budget times the factor, rounded down, never below 1 when the full budget is positive.</summary>
public static int Scale(int value, double factor) =>
value <= 0 ? 0 : Math.Max(1, (int)Math.Floor((value * factor) + 1e-9));
public static long ScaleBytes(long value, double factor) =>
value <= 0 ? 0 : Math.Max(1, (long)Math.Floor((value * factor) + 1e-6));
}
/// <summary>Use of one budget category, for the interface (spec §7.4, §7.9).</summary>
/// <param name="Kind">Category.</param>
/// <param name="UsedToday">Actions (bytes for data) of the current local day.</param>
/// <param name="LimitToday">Daily limit in force.</param>
/// <param name="UsedLastHour">Actions in the rolling last 60 minutes (null for data).</param>
/// <param name="LimitPerHour">Hourly limit in force (null for data).</param>
public sealed record BudgetStatus(ActionKind Kind, long UsedToday, long LimitToday, long? UsedLastHour, long? LimitPerHour)
{
/// <summary>Amber threshold of the interface (spec §7.4).</summary>
public const double AmberThreshold = 0.8;
public double DailyRatio => LimitToday <= 0 ? 1 : (double)UsedToday / LimitToday;
public double HourlyRatio => LimitPerHour is not > 0 ? 0 : (double)(UsedLastHour ?? 0) / LimitPerHour.Value;
/// <summary>At or above 80% of the daily or of the hourly budget.</summary>
public bool IsAmber => DailyRatio >= AmberThreshold || HourlyRatio >= AmberThreshold;
public bool DailyReached => UsedToday >= LimitToday;
public bool HourlyReached => LimitPerHour is { } limit && (UsedLastHour ?? 0) >= limit;
}