M3 Motore: Governatore con tetti da action_log, interruttore con fermi 1/6/24 ore e ripresa manuale, fascia giornaliera spostata a caso e salvata, sessioni con pause log-normali e pavimento, composizione delle sessioni sulla coda persistente, «Controlla ora» con conferma fuori fascia, cruscotto per l'interfaccia e calcolatore «Con queste impostazioni», simulazione con orologio virtuale e comando --simula; prove del motore e dell'interruttore

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01Mzbb6zeFTjT6Rp8b92AVkA
This commit is contained in:
Claude committed 2026-10-13 17:33:28 +00:00
1 parent e2c987873b
commit 346d5ca075
38 files changed
+9308

No files matched your search

+3
View File
@@ -41,6 +41,9 @@ public enum DenialReason
AccountLimitReached,
UserIsDriving,
Paused,
/// <summary>The account is «Solo archivio», paused or not reachable: the engine does not contact it (spec §4.2, rule 6).</summary>
AccountNotContactable,
}
/// <summary>
@@ -0,0 +1,315 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Engine;
/// <summary>What the «Con queste impostazioni» panel needs (spec §4.4, mockup 05).</summary>
public sealed record AccountPlanInput
{
/// <summary>The account with the settings being edited (not yet saved).</summary>
public required Account Account { get; init; }
/// <summary>All the other accounts, to compute the load on the daily budgets (the edited account is ignored here by id).</summary>
public IReadOnlyList<Account> OtherAccounts { get; init; } = [];
/// <summary>The effective caution profile (settings applied).</summary>
public required CautionProfile Profile { get; init; }
/// <summary>Posts of this account already in the library (for the backfill estimate).</summary>
public int ArchivedPosts { get; init; }
public EngineOptions Options { get; init; } = EngineOptions.Default;
}
/// <summary>A line of the panel: «Nuovi post» — «controllati ogni 3 ore circa, tra le 7:30 e le 23:30».</summary>
public sealed record PlanLine(string Title, string Text);
/// <summary>The consequences of an account's settings, with real numbers (spec §4.5).</summary>
public sealed record AccountPlanEstimate
{
public required IReadOnlyList<PlanLine> Lines { get; init; }
/// <summary>Warnings: requested accounts and frequencies exceed what the budgets allow (checks get sparser, not forced).</summary>
public required IReadOnlyList<string> Warnings { get; init; }
/// <summary>The engine contacts this account at all (not paused, not «Solo archivio», reachable).</summary>
public bool Contacted { get; init; }
/// <summary>Profile checks as wished by the frequency.</summary>
public TimeSpan? ProfileCheckWanted { get; init; }
/// <summary>Profile checks as they will really happen (sparser when the budget is short).</summary>
public TimeSpan? ProfileCheckEvery { get; init; }
/// <summary>Planned interval between story checks (null with stories off).</summary>
public TimeSpan? StoryInterval { get; init; }
public double? StoryChecksPerDay { get; init; }
/// <summary>Profile openings per day caused by this account (after thinning).</summary>
public double ProfileOpensPerDay { get; init; }
/// <summary>Profile openings per day asked by all the accounts together (before thinning).</summary>
public double TotalProfileOpensPerDay { get; init; }
/// <summary>Daily budget of profiles opened (full, without gradual start or halving).</summary>
public int DailyProfileBudget { get; init; }
/// <summary>Share of the daily profile budget taken by this account, 0–1.</summary>
public double ShareOfDailyBudget { get; init; }
/// <summary>All the accounts together ask more than the budget allows.</summary>
public bool OverBudget { get; init; }
public int? BackfillRemainingPosts { get; init; }
/// <summary>Days the backfill needs (null when the number of posts is not known yet).</summary>
public int? BackfillDays { get; init; }
}
/// <summary>
/// The «Con queste impostazioni» calculator (spec §4.4): a pure function the web layer can call at every change.
/// The numbers are estimates from medians; they say «circa».
/// </summary>
public static class AccountPlanCalculator
{
/// <summary>Mean of the next-check jitter (log-normal, median 1, σ 0.25, truncated to [0.6, 1.8]).</summary>
private const double MeanCheckJitter = 1.03;
/// <summary>Mean of the story jitter (median 0.75, σ 0.25, truncated to [0.45, 1]).</summary>
private const double MeanStoryJitter = 0.74;
public static AccountPlanEstimate Calculate(AccountPlanInput input)
{
ArgumentNullException.ThrowIfNull(input);
var account = input.Account;
var profile = input.Profile;
var options = input.Options;
var window = CautionProfileRules.WindowLength(profile.WindowStart, profile.WindowEnd);
var windowText = $"tra le {Clock(profile.WindowStart)} e le {Clock(profile.WindowEnd)}";
var lines = new List<PlanLine>();
var warnings = new List<string>();
var all = input.OtherAccounts.Where(a => a.Id == 0 || a.Id != account.Id).Append(account).ToList();
var contactable = all.Where(CheckPolicy.IsContactable).ToList();
var totalDemand = contactable.Sum(a => ProfileOpensPerDay(a, window, options));
var budget = profile.Budgets.TryGetValue(ActionKind.ProfileOpen, out var b) ? b.PerDay : 0;
var overBudget = budget > 0 && totalDemand > budget;
var thinning = overBudget ? totalDemand / budget : 1.0;
var contacted = CheckPolicy.IsContactable(account);
var own = contacted ? ProfileOpensPerDay(account, window, options) : 0;
TimeSpan? wanted = null;
TimeSpan? every = null;
TimeSpan? storyInterval = null;
double? storyChecks = null;
if (!contacted)
{
lines.Add(new PlanLine("Controlli", NotContactedText(account)));
}
else
{
// New posts.
if (CheckPolicy.WantsProfileChecks(account))
{
wanted = account.IsFollowed ? CheckPolicy.ProfileCheckInterval(account) : CheckPolicy.VisitInterval(account, window, options.MinimumStoryChecksPerDay);
every = TimeSpan.FromTicks((long)(wanted.Value.Ticks * MeanCheckJitter * thinning));
var text = account.IsFollowed
? $"scoperti dal giro dei profili che segui, di norma entro {Minutes(profile.PauseMin)}–{Minutes(profile.PauseMax)} minuti dalla pubblicazione, {windowText}. Il profilo si riapre solo per riconciliare, {ItalianText.Every(Round(every.Value))} circa."
: $"controllati {ItalianText.Every(Round(every.Value))} circa, {windowText}.";
lines.Add(new PlanLine("Nuovi post", text));
}
else
{
lines.Add(new PlanLine("Nuovi post", "non scaricati con queste impostazioni."));
}
// Stories.
if (CheckPolicy.WantsStories(account))
{
storyInterval = CheckPolicy.StoryInterval(account, window, options.MinimumStoryChecksPerDay);
storyChecks = Math.Max(options.MinimumStoryChecksPerDay, 1 + (window / (storyInterval.Value * MeanStoryJitter)));
var how = account.IsFollowed && options.SweepCoversFollowedStories
? "a ogni giro dei profili che segui e"
: string.Empty;
lines.Add(new PlanLine(
"Storie",
$"controllate {how} almeno {ItalianText.Number(options.MinimumStoryChecksPerDay)} volte al giorno; fra due controlli passano al massimo {ItalianText.Duration(storyInterval.Value)} circa. Restano 24 ore, quindi nessuna dovrebbe scadere prima di essere vista."
.Replace(" ", " ", StringComparison.Ordinal)));
}
else
{
lines.Add(new PlanLine("Storie", "spente."));
}
}
// History.
var (backfillText, remaining, days) = Backfill(input, all);
lines.Add(new PlanLine("Storico", backfillText));
// Weight on the daily budget.
var ownAfter = own / thinning;
var share = budget > 0 ? ownAfter / budget : 0;
lines.Add(new PlanLine(
"Carico",
contacted
? $"circa {ItalianText.Decimal(ownAfter, ownAfter < 10 ? 1 : 0)} aperture del profilo al giorno, su {ItalianText.Number(budget)} disponibili ogni giorno per tutti gli account."
: "nessuno."));
if (overBudget)
{
warnings.Add(
$"Con {ItalianText.Count(contactable.Count, "account", "account")} e queste frequenze servirebbero circa {ItalianText.Number((long)Math.Round(totalDemand))} aperture di profili al giorno, "
+ $"ma il tetto è {ItalianText.Number(budget)}: i controlli si diradano (circa {ItalianText.Decimal(thinning, 1)} volte più radi), non si forzano.");
}
var sessionsPerDay = SessionsPerDay(profile, window);
var homeBudget = profile.Budgets.TryGetValue(ActionKind.Home, out var home) ? home.PerDay : 0;
if (contactable.Any(a => a.IsFollowed) && homeBudget > 0 && sessionsPerDay * options.SweepProbability > homeBudget)
{
warnings.Add($"Il tetto della home ({ItalianText.Number(homeBudget)} al giorno) è più basso del numero di sessioni: alcuni giri dei seguiti salteranno e i nuovi post arriveranno più tardi.");
}
if (profile.GradualStart && profile.RampUpDays > 0)
{
warnings.Add($"Con l'avvio graduale, nei primi {ItalianText.Count(profile.RampUpDays, "giorno", "giorni")} dopo il collegamento i tetti partono dalla metà: tutto è più lento.");
}
return new AccountPlanEstimate
{
Lines = lines,
Warnings = warnings,
Contacted = contacted,
ProfileCheckWanted = wanted,
ProfileCheckEvery = every,
StoryInterval = storyInterval,
StoryChecksPerDay = storyChecks,
ProfileOpensPerDay = ownAfter,
TotalProfileOpensPerDay = totalDemand,
DailyProfileBudget = budget,
ShareOfDailyBudget = share,
OverBudget = overBudget,
BackfillRemainingPosts = remaining,
BackfillDays = days,
};
}
/// <summary>Profile openings per day an account asks for (visits, reconciliations, tagged tab).</summary>
public static double ProfileOpensPerDay(Account account, TimeSpan window, EngineOptions? options = null)
{
ArgumentNullException.ThrowIfNull(account);
options ??= EngineOptions.Default;
if (!CheckPolicy.IsContactable(account))
{
return 0;
}
double visits;
if (CheckPolicy.WantsProfileChecks(account))
{
var interval = account.IsFollowed ? CheckPolicy.ProfileCheckInterval(account) : CheckPolicy.VisitInterval(account, window, options.MinimumStoryChecksPerDay);
visits = ChecksPerDay(interval * MeanCheckJitter, window);
}
else if (!account.IsFollowed && CheckPolicy.WantsStories(account))
{
visits = ChecksPerDay(CheckPolicy.StoryInterval(account, window, options.MinimumStoryChecksPerDay) * MeanStoryJitter, window);
}
else
{
visits = 0;
}
return (account.ContentTypes & ContentTypes.Tagged) != 0 ? visits * 2 : visits;
}
/// <summary>Checks a day at an interval, counting the morning catch-up after the night.</summary>
public static double ChecksPerDay(TimeSpan interval, TimeSpan window)
{
if (interval <= TimeSpan.Zero)
{
return 0;
}
if (interval >= TimeSpan.FromHours(24))
{
return 24 / interval.TotalHours;
}
return 1 + (window / interval);
}
/// <summary>Sessions a day with median session length and median pause.</summary>
public static double SessionsPerDay(CautionProfile profile, TimeSpan window)
{
ArgumentNullException.ThrowIfNull(profile);
var session = Math.Sqrt(profile.SessionMin.TotalMinutes * profile.SessionMax.TotalMinutes);
var pause = Math.Sqrt(profile.PauseMin.TotalMinutes * profile.PauseMax.TotalMinutes);
return window.TotalMinutes / (session + pause);
}
private static (string Text, int? Remaining, int? Days) Backfill(AccountPlanInput input, List<Account> all)
{
var account = input.Account;
var profile = input.Profile;
if (account.BackfillCompletedAt is { } done && account.State != AccountState.Backfilling)
{
return ($"completato il {ItalianText.Day(DateOnly.FromDateTime(done.UtcDateTime))}.", 0, 0);
}
if (account.Limits.Depth == HistoryDepth.FromDate && account.Limits.FromDate is { } from)
{
return ($"dipende da quanti post ci sono dopo il {ItalianText.Day(DateOnly.FromDateTime(from.UtcDateTime))}: lo saprò strada facendo.", null, null);
}
if (account.State is not (AccountState.Backfilling or AccountState.UpToDate) || !CheckPolicy.WantsProfileChecks(account))
{
return ("nessuno storico da scaricare con queste impostazioni.", null, null);
}
int? target = account.Limits.Depth == HistoryDepth.LastPosts
? account.Limits.LastPosts is { } last ? Math.Min(last, account.PostCount ?? last) : account.PostCount
: account.PostCount;
if (target is null)
{
return ("il numero dei post non è ancora noto: lo saprò dopo il primo controllo del profilo.", null, null);
}
var remaining = Math.Max(0, target.Value - input.ArchivedPosts);
if (remaining == 0)
{
return ("tutto già in libreria.", 0, 0);
}
var sharing = Math.Max(1, all.Count(a => a.State == AccountState.Backfilling && a.BackfillCompletedAt is null && CheckPolicy.IsContactable(a)));
var pagesPerDay = profile.Budgets.TryGetValue(ActionKind.BackfillPage, out var pages) ? pages.PerDay : 0;
var byBudget = pagesPerDay * input.Options.PostsPerBackfillPage / (double)sharing;
var perDay = Math.Min(Math.Min(account.Limits.BackfillPostsPerDay, profile.BackfillPostsPerAccountPerDay), byBudget);
if (perDay <= 0)
{
return ("fermo: il limite di storico al giorno è zero.", remaining, null);
}
var days = (int)Math.Ceiling(remaining / perDay);
var text = $"mancano {ItalianText.Count(remaining, "post", "post")}, servono circa {ItalianText.Count(days, "giorno", "giorni")} ({ItalianText.Number((long)Math.Floor(perDay))} post al giorno"
+ (sharing > 1 ? $", a turno con altri {ItalianText.Number(sharing - 1)} account" : string.Empty) + ").";
return (text, remaining, days);
}
private static string NotContactedText(Account account) => account.State switch
{
AccountState.ArchiveOnly => "«Solo archivio»: Febe non contatta questo account.",
AccountState.Paused => "in pausa: Febe non controlla questo account finché non lo riattivi.",
AccountState.Unreachable => "non raggiungibile: Febe non lo contatta finché non lo verifichi.",
_ => "Febe non contatta questo account.",
};
private static string Clock(TimeOnly time) => time.Hour.ToString(System.Globalization.CultureInfo.InvariantCulture) + ":" + time.Minute.ToString("00", System.Globalization.CultureInfo.InvariantCulture);
private static string Minutes(TimeSpan span) => ItalianText.Number((long)Math.Round(span.TotalMinutes));
/// <summary>Rounds an interval for display: to 5 minutes under 2 hours, to half an hour above.</summary>
private static TimeSpan Round(TimeSpan interval) => interval < TimeSpan.FromHours(2)
? TimeSpan.FromMinutes(Math.Max(5, Math.Round(interval.TotalMinutes / 5) * 5))
: TimeSpan.FromMinutes(Math.Round(interval.TotalMinutes / 30) * 30);
}
+138
View File
@@ -0,0 +1,138 @@
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;
}
+192
View File
@@ -0,0 +1,192 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Pacing;
namespace Febe.Core.Engine;
/// <summary>
/// Frequencies of spec §7.3 and the rules that say which accounts the engine may contact. A frequency expresses a
/// wish; the Governor decides what is possible.
/// </summary>
public static class CheckPolicy
{
/// <summary>Content types that need a visit of the profile page (posts, highlights, tagged posts, profile picture).</summary>
public const ContentTypes ProfileContent = ContentTypes.PostPhotos | ContentTypes.PostVideos | ContentTypes.Highlights
| ContentTypes.Tagged | ContentTypes.ProfilePicture;
/// <summary>
/// The engine contacts an account only when it is up to date or backfilling. «Solo archivio», «In pausa» (also
/// after the single download of «Tieni aggiornato» off) and «Non raggiungibile» are never contacted on the
/// engine's initiative.
/// </summary>
public static bool IsContactable(Account account)
{
ArgumentNullException.ThrowIfNull(account);
return account.State is AccountState.UpToDate or AccountState.Backfilling;
}
/// <summary>
/// Whether a «Controlla ora» of Alberto may contact the account: never «Solo archivio» and never a private profile
/// he does not follow (rule 6); paused and other unreachable accounts may be checked on request.
/// </summary>
public static bool AllowsManualCheck(Account account)
{
ArgumentNullException.ThrowIfNull(account);
return account.State switch
{
AccountState.ArchiveOnly => false,
AccountState.Unreachable => account.UnreachableReason is not UnreachableReason.PrivateNotFollowed,
_ => true,
};
}
public static bool WantsProfileChecks(Account account) => (account.ContentTypes & ProfileContent) != 0;
public static bool WantsStories(Account account) => (account.ContentTypes & ContentTypes.Stories) != 0;
/// <summary>
/// Interval between profile checks. Not followed: ~12 h / ~3 h / ~75 min (Su misura: the hours chosen). Followed: the
/// sweep discovers new posts, the profile check is only a reconciliation every 24 / 12 / 6 hours (Su misura: four
/// times the chosen interval, between 6 and 24 hours).
/// </summary>
public static TimeSpan ProfileCheckInterval(Account account)
{
ArgumentNullException.ThrowIfNull(account);
if (account.IsFollowed)
{
return account.Frequency switch
{
Frequency.Low => TimeSpan.FromHours(24),
Frequency.High => TimeSpan.FromHours(6),
Frequency.Custom when account.CustomPostInterval is { } custom =>
TimeSpan.FromTicks(Math.Clamp(custom.Ticks * 4, TimeSpan.FromHours(6).Ticks, TimeSpan.FromHours(24).Ticks)),
_ => TimeSpan.FromHours(12),
};
}
return account.Frequency switch
{
Frequency.Low => TimeSpan.FromHours(12),
Frequency.High => TimeSpan.FromMinutes(75),
Frequency.Custom when account.CustomPostInterval is { } custom && custom > TimeSpan.Zero => custom,
_ => TimeSpan.FromHours(3),
};
}
/// <summary>Maximum interval between two story checks: 8 / 6 / 3 hours (Su misura: the chosen one).</summary>
public static TimeSpan StoryMaxInterval(Account account)
{
ArgumentNullException.ThrowIfNull(account);
return account.Frequency switch
{
Frequency.Low => TimeSpan.FromHours(8),
Frequency.High => TimeSpan.FromHours(3),
Frequency.Custom when account.CustomStoryInterval is { } custom && custom > TimeSpan.Zero => custom,
_ => TimeSpan.FromHours(6),
};
}
/// <summary>
/// Story interval actually planned: the frequency's maximum, but never more than a third of the active window, so
/// that every account gets at least three story checks a day inside it (spec §7.3).
/// </summary>
public static TimeSpan StoryInterval(Account account, TimeSpan windowLength, int checksPerDay = 3)
{
var max = StoryMaxInterval(account);
if (windowLength <= TimeSpan.Zero || checksPerDay <= 0)
{
return max;
}
var cap = TimeSpan.FromTicks(windowLength.Ticks / checksPerDay);
return max < cap ? max : cap;
}
/// <summary>
/// Interval between visits of a profile that is not followed: its stories can be seen only from the profile, so a
/// visit serves both the profile check and the story check and comes at the shorter of the two intervals.
/// </summary>
public static TimeSpan VisitInterval(Account account, TimeSpan windowLength, int checksPerDay = 3)
{
var profile = ProfileCheckInterval(account);
if (account.IsFollowed || !WantsStories(account))
{
return profile;
}
var stories = StoryInterval(account, windowLength, checksPerDay);
return WantsProfileChecks(account) && profile < stories ? profile : stories;
}
/// <summary>Frequency weight of spec §7.2: High 3, Normal 2, Low 1 (Su misura from its interval).</summary>
public static double FrequencyWeight(Account account)
{
ArgumentNullException.ThrowIfNull(account);
return account.Frequency switch
{
Frequency.High => 3,
Frequency.Low => 1,
Frequency.Custom => ProfileCheckInterval(account with { IsFollowed = false }) switch
{
var i when i <= TimeSpan.FromHours(2) => 3,
var i when i <= TimeSpan.FromHours(6) => 2,
_ => 1,
},
_ => 2,
};
}
/// <summary>Weight of an account in the random order: frequency weight × (1 + delay ÷ interval), the ratio limited to 3.</summary>
public static double SelectionWeight(Account account, TimeSpan delay, TimeSpan interval)
{
var ratio = interval <= TimeSpan.Zero ? 0 : Math.Clamp(delay / interval, 0, 3);
return FrequencyWeight(account) * (1 + ratio);
}
/// <summary>The next check: interval × log-normal (median 1, σ 0.25, [0.6, 1.8]) (spec §7.2).</summary>
public static TimeSpan NextCheckDelay(IRandomSource random, TimeSpan interval) => random.JitteredInterval(interval);
/// <summary>
/// The next story check. «Intervallo massimo» is a maximum, so the jitter is drawn below it: interval × log-normal
/// with median 0.75, σ 0.25, truncated to [0.45, 1].
/// </summary>
public static TimeSpan NextStoryCheckDelay(IRandomSource random, TimeSpan maxInterval) =>
TimeSpan.FromTicks((long)(maxInterval.Ticks * random.TruncatedLogNormal(0.75, 0.25, 0.45, 1.0)));
/// <summary>
/// A random order of items by weight, never the same (Efraimidis–Spirakis: key = u^(1/w), highest first).
/// </summary>
public static IReadOnlyList<T> WeightedOrder<T>(IRandomSource random, IEnumerable<(T Item, double Weight)> items)
{
ArgumentNullException.ThrowIfNull(random);
return [.. items
.Select(i => (i.Item, Key: Math.Pow(1.0 - random.NextDouble(), 1.0 / Math.Max(i.Weight, 1e-6))))
.OrderByDescending(i => i.Key)
.Select(i => i.Item)];
}
/// <summary>Budget category a recipe needs first (to skip it when that budget is exhausted).</summary>
public static ActionKind CategoryOf(RecipeKind kind) => kind switch
{
RecipeKind.FollowingSweep => ActionKind.Home,
RecipeKind.AccountStories or RecipeKind.Highlight => ActionKind.StoryView,
RecipeKind.Backfill => ActionKind.BackfillPage,
RecipeKind.SinglePost => ActionKind.SinglePost,
RecipeKind.FollowingList => ActionKind.FollowingListPage,
_ => ActionKind.ProfileOpen,
};
public static RecipeKind RecipeOf(EngineTaskKind kind) => kind switch
{
EngineTaskKind.FollowingSweep => RecipeKind.FollowingSweep,
EngineTaskKind.AccountStories => RecipeKind.AccountStories,
EngineTaskKind.ProfileCheck => RecipeKind.ProfileCheck,
EngineTaskKind.Backfill => RecipeKind.Backfill,
EngineTaskKind.HighlightCheck => RecipeKind.Highlight,
EngineTaskKind.TaggedCheck => RecipeKind.Tagged,
EngineTaskKind.ReelsCheck => RecipeKind.Reels,
EngineTaskKind.SinglePost => RecipeKind.SinglePost,
EngineTaskKind.FollowingList => RecipeKind.FollowingList,
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null),
};
}
+409
View File
@@ -0,0 +1,409 @@
using System.Globalization;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// The circuit breaker («interruttore», spec §7.6).
/// <list type="bullet">
/// <item>Throttle: closes the session at once; stops 1 hour the first time, 6 hours the second within 24 hours,
/// 24 hours the third; then halved budgets for 48 hours. Reopens by itself.</item>
/// <item>Challenge and disconnection: stop everything and never restart alone; only <see cref="ResumeAsync"/>
/// (Alberto's «Riprendi», after fixing things in the browser) reopens, and the resume starts the gradual start.</item>
/// </list>
/// Every stop is an <c>incident</c> row and a line of the Activity timeline; the state is restored from the database
/// at start-up. <see cref="Report"/> is synchronous (signals arrive from capture threads): the state changes at once
/// and the rows are written in order in the background (<see cref="FlushAsync"/> waits for them).
/// </summary>
public sealed class CircuitBreaker : ICircuitBreaker
{
/// <summary>Fixed stop durations (spec §7.6: not editable in version 1).</summary>
public static readonly IReadOnlyList<TimeSpan> ThrottleStops = [TimeSpan.FromHours(1), TimeSpan.FromHours(6), TimeSpan.FromHours(24)];
public static readonly TimeSpan HalvedPeriod = TimeSpan.FromHours(48);
public static readonly TimeSpan EscalationWindow = TimeSpan.FromHours(24);
public static readonly TimeSpan ProposalWindow = TimeSpan.FromDays(7);
public const int ProposalThreshold = 3;
private readonly IFebeStorage _storage;
private readonly IClock _clock;
private readonly EngineRuntime _runtime;
private readonly EngineEvents? _events;
private readonly Lock _gate = new();
private readonly List<DateTimeOffset> _recentThrottles = [];
private readonly List<long> _openIncidents = [];
private BreakerState _state = BreakerState.Normal;
private Task _tail = Task.CompletedTask;
private CircuitBreaker(IFebeStorage storage, IClock clock, EngineRuntime runtime, EngineEvents? events)
{
_storage = storage;
_clock = clock;
_runtime = runtime;
_events = events;
}
/// <summary>Raised after every change of state (outside the internal lock). The engine closes the session on it.</summary>
public event EventHandler<BreakerState>? StateChanged;
/// <summary>Current state; a throttle stop that has expired turns into Closed here.</summary>
public BreakerState State
{
get
{
BreakerState state;
bool changed;
lock (_gate)
{
changed = ExpireLocked(_clock.Now);
state = _state;
}
if (changed)
{
StateChanged?.Invoke(this, state);
}
return state;
}
}
/// <summary>Restores the state from the incidents table (open stops, recent throttles, halved budgets).</summary>
public static async Task<CircuitBreaker> LoadAsync(
IFebeStorage storage,
IClock clock,
EngineRuntime runtime,
EngineEvents? events = null,
CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(storage);
ArgumentNullException.ThrowIfNull(clock);
ArgumentNullException.ThrowIfNull(runtime);
var breaker = new CircuitBreaker(storage, clock, runtime, events);
var now = clock.Now;
var recent = await storage.Incidents.ListAsync(now - ProposalWindow - EscalationWindow, now.AddSeconds(1), ct).ConfigureAwait(false);
DateTimeOffset? halvedUntil = null;
foreach (var incident in recent.Where(i => i.Level == SignalLevel.Throttle))
{
breaker._recentThrottles.Add(incident.At);
if (incident.StoppedUntil is { } until && until + HalvedPeriod > now && (halvedUntil is null || until + HalvedPeriod > halvedUntil))
{
halvedUntil = until + HalvedPeriod;
}
}
var state = new BreakerState(BreakerStatus.Closed, null, null, halvedUntil);
foreach (var incident in await storage.Incidents.ListOpenAsync(ct).ConfigureAwait(false))
{
var signal = new Signal(incident.Level, incident.Signal, incident.Url, incident.At);
switch (incident.Level)
{
case SignalLevel.Challenge:
state = state with { Status = BreakerStatus.Challenge, Until = null, LastSignal = signal };
breaker._openIncidents.Add(incident.Id);
break;
case SignalLevel.Disconnect:
state = state with { Status = BreakerStatus.Disconnected, Until = null, LastSignal = signal };
breaker._openIncidents.Add(incident.Id);
break;
case SignalLevel.Throttle when incident.StoppedUntil is { } until && until > now:
if (state.Status == BreakerStatus.Closed)
{
state = state with { Status = BreakerStatus.Throttled, Until = until, LastSignal = signal };
}
breaker._openIncidents.Add(incident.Id);
break;
default:
// An expired throttle left open by a previous process: resolved at its planned end.
await storage.Incidents.ResolveAsync(incident.Id, incident.StoppedUntil ?? now, ct).ConfigureAwait(false);
break;
}
}
breaker._state = state;
return breaker;
}
public void Report(Signal signal) => _ = ReportAsync(signal);
/// <summary>Same as <see cref="Report"/>, returning when the incident and the event are stored.</summary>
public Task ReportAsync(Signal signal, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(signal);
BreakerState state;
Task persisted;
lock (_gate)
{
var now = _clock.Now;
ExpireLocked(now);
var sessionId = _runtime.CurrentSession?.SessionId;
switch (signal.Level)
{
case SignalLevel.Throttle:
if (_state.Status != BreakerStatus.Closed)
{
// Already stopped: a late signal of the same stop does not escalate it.
return _tail;
}
_recentThrottles.RemoveAll(t => t < now - ProposalWindow);
var within24Hours = _recentThrottles.Count(t => t > now - EscalationWindow);
var stop = ThrottleStops[Math.Min(within24Hours, ThrottleStops.Count - 1)];
_recentThrottles.Add(now);
var until = now + stop;
_state = new BreakerState(BreakerStatus.Throttled, until, signal, until + HalvedPeriod);
var withinWeek = _recentThrottles.Count(t => t > now - ProposalWindow);
persisted = EnqueueLocked(c => PersistThrottleAsync(signal, now, until, stop, sessionId, withinWeek, c));
break;
case SignalLevel.Challenge:
case SignalLevel.Disconnect:
var status = signal.Level == SignalLevel.Challenge ? BreakerStatus.Challenge : BreakerStatus.Disconnected;
if (_state.Status == status)
{
return _tail;
}
var wasThrottled = _state.Status == BreakerStatus.Throttled;
_state = new BreakerState(status, null, signal, _state.HalvedBudgetsUntil);
persisted = EnqueueLocked(c => PersistManualStopAsync(signal, now, wasThrottled, sessionId, c));
break;
default:
throw new ArgumentOutOfRangeException(nameof(signal), signal.Level, null);
}
state = _state;
}
StateChanged?.Invoke(this, state);
return persisted;
}
/// <summary>
/// «Riprendi» after a verification or a disconnection, once Alberto fixed things in the browser. Resolves the open
/// incidents and restarts the gradual start. False when the breaker is not in such a stop (a throttle stop has a
/// fixed duration and cannot be shortened).
/// </summary>
public async Task<bool> ResumeAsync(CancellationToken ct = default)
{
BreakerState state;
Task persisted;
lock (_gate)
{
var now = _clock.Now;
if (_state.Status is not (BreakerStatus.Challenge or BreakerStatus.Disconnected))
{
return false;
}
var previous = _state.Status;
_state = _state with { Status = BreakerStatus.Closed, Until = null };
_runtime.RampStart = now;
persisted = EnqueueLocked(c => PersistResumeAsync(previous, now, c));
state = _state;
}
await persisted.WaitAsync(ct).ConfigureAwait(false);
StateChanged?.Invoke(this, state);
return true;
}
/// <summary>Waits until every incident and event reported so far is stored.</summary>
public Task FlushAsync()
{
lock (_gate)
{
return _tail;
}
}
private bool ExpireLocked(DateTimeOffset now)
{
if (_state.Status != BreakerStatus.Throttled || _state.Until is not { } until || now < until)
{
return false;
}
_state = _state with { Status = BreakerStatus.Closed, Until = null };
var halvedUntil = _state.HalvedBudgetsUntil;
EnqueueLocked(ct => PersistThrottleEndAsync(until, halvedUntil, ct));
return true;
}
private Task EnqueueLocked(Func<CancellationToken, Task> work)
{
// Rows are written strictly in order: an incident is opened before it is resolved.
_tail = _tail.ContinueWith(_ => work(CancellationToken.None), CancellationToken.None, TaskContinuationOptions.None, TaskScheduler.Default).Unwrap();
return _tail;
}
private async Task PersistThrottleAsync(Signal signal, DateTimeOffset now, DateTimeOffset until, TimeSpan stop, long? sessionId, int withinWeek, CancellationToken ct)
{
var incident = await _storage.Incidents.OpenAsync(
new Incident
{
At = signal.At,
Level = SignalLevel.Throttle,
Signal = signal.Code,
Url = signal.Url,
StoppedUntil = until,
SessionId = sessionId,
},
ct).ConfigureAwait(false);
lock (_gate)
{
_openIncidents.Add(incident.Id);
}
if (_events is null)
{
return;
}
var zone = _clock.LocalZone;
await _events.WriteAsync(
EventSeverity.Warning,
EngineEventCodes.ThrottleStop,
$"Instagram ha chiesto di rallentare (segnale {signal.Code}). Ho chiuso la sessione e mi fermo per {ItalianText.Duration(stop)}, "
+ $"fino {ItalianText.AtDay(until, now, zone)}. Poi i tetti restano dimezzati per 48 ore.",
sessionId: sessionId,
ct: ct).ConfigureAwait(false);
if (withinWeek >= ProposalThreshold)
{
var profile = _runtime.Profile.Kind;
var proposal = profile is CautionProfileKind.Prudent
? "Tre rallentamenti in sette giorni anche con il profilo «Prudente»: conviene ridurre gli account seguiti o abbassare le loro frequenze."
: $"Tre rallentamenti in sette giorni con il profilo «{ItalianText.Profile(profile)}»: conviene passare al profilo «{ItalianText.Profile(MorePrudent(profile))}» o ridurre gli account seguiti.";
await _events.WriteAsync(EventSeverity.Warning, EngineEventCodes.ProposeMorePrudence, proposal, ct: ct).ConfigureAwait(false);
}
}
private async Task PersistManualStopAsync(Signal signal, DateTimeOffset now, bool wasThrottled, long? sessionId, CancellationToken ct)
{
if (wasThrottled)
{
await ResolveOpenAsync(now, ct).ConfigureAwait(false);
}
var incident = await _storage.Incidents.OpenAsync(
new Incident
{
At = signal.At,
Level = signal.Level,
Signal = signal.Code,
Url = signal.Url,
SessionId = sessionId,
},
ct).ConfigureAwait(false);
lock (_gate)
{
_openIncidents.Add(incident.Id);
}
if (_events is null)
{
return;
}
var at = ItalianText.At(now, _clock.LocalZone);
var message = signal.Level == SignalLevel.Challenge
? $"Instagram chiede una verifica (segnale {signal.Code}). Ho fermato tutto {at} e non riparto da solo: apri il browser, completa la verifica a mano, poi premi «Riprendi»."
: $"La sessione di Instagram non c'è più (segnale {signal.Code}). Ho fermato tutto {at} e non provo a rientrare: apri il browser, accedi a mano, poi premi «Riprendi».";
await _events.WriteAsync(
EventSeverity.Error,
signal.Level == SignalLevel.Challenge ? EngineEventCodes.ChallengeStop : EngineEventCodes.DisconnectStop,
message,
sessionId: sessionId,
ct: ct).ConfigureAwait(false);
}
private async Task PersistThrottleEndAsync(DateTimeOffset until, DateTimeOffset? halvedUntil, CancellationToken ct)
{
await ResolveOpenAsync(until, ct).ConfigureAwait(false);
if (_events is null)
{
return;
}
var tail = halvedUntil is { } h
? $" Riprendo con i tetti dimezzati fino {ItalianText.AtDay(h, until, _clock.LocalZone)}."
: " Riprendo con i tetti normali.";
await _events.WriteAsync(EventSeverity.Info, EngineEventCodes.ThrottleEnd, "Fine del fermo per rallentamento." + tail, ct: ct).ConfigureAwait(false);
}
private async Task PersistResumeAsync(BreakerStatus previous, DateTimeOffset now, CancellationToken ct)
{
await ResolveOpenAsync(now, ct).ConfigureAwait(false);
await _storage.Settings.SetAsync(
EngineSettingKeys.RampStart,
now.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture),
ct).ConfigureAwait(false);
if (_events is null)
{
return;
}
var profile = _runtime.Profile;
var what = previous == BreakerStatus.Challenge ? "Ripresa dopo la verifica." : "Ripresa dopo il nuovo accesso.";
var ramp = profile.GradualStart && profile.RampUpDays > 0
? $" I tetti ripartono dalla metà e tornano pieni in {ItalianText.Count(profile.RampUpDays, "giorno", "giorni")}."
: string.Empty;
await _events.WriteAsync(EventSeverity.Success, EngineEventCodes.Resumed, what + ramp, ct: ct).ConfigureAwait(false);
}
private async Task ResolveOpenAsync(DateTimeOffset at, CancellationToken ct)
{
long[] open;
lock (_gate)
{
open = [.. _openIncidents];
_openIncidents.Clear();
}
foreach (var id in open)
{
await _storage.Incidents.ResolveAsync(id, at, ct).ConfigureAwait(false);
}
}
private static CautionProfileKind MorePrudent(CautionProfileKind kind) => kind switch
{
CautionProfileKind.Fast => CautionProfileKind.Balanced,
_ => CautionProfileKind.Prudent,
};
}
/// <summary>Stable codes of the engine's timeline events.</summary>
public static class EngineEventCodes
{
public const string ThrottleStop = "fermo-rallentamento";
public const string ThrottleEnd = "fine-fermo";
public const string ChallengeStop = "verifica-richiesta";
public const string DisconnectStop = "disconnessione";
public const string Resumed = "ripresa";
public const string ProposeMorePrudence = "proposta-prudenza";
public const string Paused = "pausa";
public const string Unpaused = "fine-pausa";
public const string BudgetReached = "tetto-raggiunto";
public const string SessionEnded = "sessione";
public const string BackfillCompleted = "storico-completato";
public const string BackfillWaiting = "storico-in-attesa";
public const string RecipeSuspended = "ricetta-sospesa";
public const string RecipeResumed = "ricetta-riattivata";
public const string FormatUnrecognized = "formato-non-riconosciuto";
public const string TargetNotFound = "bersaglio-non-trovato";
public const string AccountUnreachable = "account-non-raggiungibile";
public const string AccountPaused = "account-in-pausa";
public const string ManualCheck = "controlla-ora";
public const string RecipeFailed = "ricetta-fallita";
public const string SettingsChanged = "impostazioni-motore";
/// <summary>Prefix of the per-recipe lines («Appena fatto»): "ricetta." + recipe kind.</summary>
public const string RecipePrefix = "ricetta.";
}
+183
View File
@@ -0,0 +1,183 @@
using System.Globalization;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Pacing;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// The active window of one day (spec §7.2): the engine works only inside it. A window belongs to the local day it
/// starts on and may end after midnight (e.g. 06:30–00:30).
/// </summary>
public sealed record ActiveWindow(DateOnly Day, DateTimeOffset Start, DateTimeOffset End)
{
public TimeSpan Length => End - Start;
public bool Contains(DateTimeOffset instant) => instant >= Start && instant < End;
}
/// <summary>
/// Plans the active window of every day: the profile's start and end, each shifted every day by a random amount within
/// ± the profile's jitter (a normal draw with σ = jitter/2 truncated to ± jitter, never uniform), only on active
/// weekdays. The shifts of a day are derived from a seed drawn once from the engine's random source and persisted, so
/// they are deterministic per day and a restart never redraws them.
/// </summary>
public sealed class DayPlanner
{
private const double ShiftSigma = 0.5;
private static readonly TimeSpan MinimumLength = TimeSpan.FromMinutes(30);
private readonly ISettingsStore _settings;
private readonly IRandomSource _random;
private readonly Func<CautionProfile> _profile;
private readonly SemaphoreSlim _seedGate = new(1, 1);
private ulong? _seed;
public DayPlanner(ISettingsStore settings, IRandomSource random, Func<CautionProfile> profile, TimeZoneInfo zone)
{
_settings = settings ?? throw new ArgumentNullException(nameof(settings));
_random = random ?? throw new ArgumentNullException(nameof(random));
_profile = profile ?? throw new ArgumentNullException(nameof(profile));
Zone = zone ?? throw new ArgumentNullException(nameof(zone));
}
public TimeZoneInfo Zone { get; }
/// <summary>The window of a local day, or null when the weekday is not active.</summary>
public async Task<ActiveWindow?> GetWindowAsync(DateOnly day, CancellationToken ct = default)
{
var profile = _profile();
if (!profile.ActiveDays.Contains(day.DayOfWeek))
{
return null;
}
var seed = await GetSeedAsync(ct).ConfigureAwait(false);
return Compute(day, profile, seed, Zone);
}
/// <summary>The window containing <paramref name="instant"/> (today's, or yesterday's when it crosses midnight); null at night.</summary>
public async Task<ActiveWindow?> GetWindowAtAsync(DateTimeOffset instant, CancellationToken ct = default)
{
var today = LocalCalendar.Today(instant, Zone);
foreach (var day in new[] { today.AddDays(-1), today })
{
var window = await GetWindowAsync(day, ct).ConfigureAwait(false);
if (window is not null && window.Contains(instant))
{
return window;
}
}
return null;
}
/// <summary>The window containing <paramref name="instant"/>, or the next one to start; null only without active days.</summary>
public async Task<ActiveWindow?> GetNextWindowAsync(DateTimeOffset instant, CancellationToken ct = default)
{
var today = LocalCalendar.Today(instant, Zone);
for (var offset = -1; offset <= 8; offset++)
{
var window = await GetWindowAsync(today.AddDays(offset), ct).ConfigureAwait(false);
if (window is not null && window.End > instant)
{
return window;
}
}
return null;
}
/// <summary>The window of a day from a seed: pure, used by the planner and by tests.</summary>
public static ActiveWindow Compute(DateOnly day, CautionProfile profile, ulong seed, TimeZoneInfo zone)
{
ArgumentNullException.ThrowIfNull(profile);
var (startShift, endShift) = Shifts(seed, day);
var endDay = profile.WindowEnd > profile.WindowStart ? day : day.AddDays(1);
var baseStart = LocalCalendar.FromLocal(day.ToDateTime(profile.WindowStart), zone);
var baseEnd = LocalCalendar.FromLocal(endDay.ToDateTime(profile.WindowEnd), zone);
var start = baseStart + (profile.WindowJitter * startShift);
var end = baseEnd + (profile.WindowJitter * endShift);
if (end - start < MinimumLength)
{
end = start + MinimumLength;
}
// Whole seconds: easier to read and to compare with stored times (milliseconds).
return new ActiveWindow(day, TruncateToSecond(start), TruncateToSecond(end));
}
/// <summary>Daily shifts of start and end as fractions of the jitter, in [-1, 1].</summary>
internal static (double Start, double End) Shifts(ulong seed, DateOnly day)
{
var random = new SplitMixRandom(seed ^ ((ulong)day.DayNumber * 0x9E3779B97F4A7C15UL));
return (TruncatedNormal(random), TruncatedNormal(random));
}
private static double TruncatedNormal(IRandomSource random)
{
for (var attempt = 0; attempt < 64; attempt++)
{
var value = random.Normal(0, ShiftSigma);
if (value is >= -1 and <= 1)
{
return value;
}
}
return 0;
}
private static DateTimeOffset TruncateToSecond(DateTimeOffset value) =>
new(value.Ticks - (value.Ticks % TimeSpan.TicksPerSecond), value.Offset);
private async Task<ulong> GetSeedAsync(CancellationToken ct)
{
if (_seed is { } known)
{
return known;
}
await _seedGate.WaitAsync(ct).ConfigureAwait(false);
try
{
if (_seed is { } again)
{
return again;
}
var text = await _settings.GetAsync(EngineSettingKeys.WindowSeed, ct).ConfigureAwait(false);
if (!ulong.TryParse(text, NumberStyles.Integer, CultureInfo.InvariantCulture, out var seed))
{
var high = (ulong)(_random.NextDouble() * uint.MaxValue);
var low = (ulong)(_random.NextDouble() * uint.MaxValue);
seed = (high << 32) | low;
await _settings.SetAsync(EngineSettingKeys.WindowSeed, seed.ToString(CultureInfo.InvariantCulture), ct).ConfigureAwait(false);
}
_seed = seed;
return seed;
}
finally
{
_seedGate.Release();
}
}
}
/// <summary>SplitMix64: a tiny deterministic generator for values derived from a stored seed.</summary>
internal sealed class SplitMixRandom(ulong seed) : IRandomSource
{
private ulong _state = seed;
public double NextDouble() => (Next() >> 11) * (1.0 / (1UL << 53));
private ulong Next()
{
var z = _state += 0x9E3779B97F4A7C15UL;
z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
return z ^ (z >> 31);
}
}
+122
View File
@@ -0,0 +1,122 @@
using System.Runtime.CompilerServices;
using System.Threading.Channels;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>What changed in the engine, for the interface (the web layer turns these into server-sent events).</summary>
public enum EngineNotificationKind
{
/// <summary>A line was added to the Activity timeline (<see cref="EngineNotification.Event"/>).</summary>
Event,
/// <summary>The mode of the engine changed (session started or ended, pause, stop, resume...): refresh the snapshot.</summary>
StateChanged,
/// <summary>A recipe started or ended inside a session: refresh the current activity and the budgets.</summary>
ActivityChanged,
}
/// <summary>A notification of the engine. Never contains captions, bodies, cookies or signed addresses.</summary>
public sealed record EngineNotification(EngineNotificationKind Kind, DateTimeOffset At, EventRecord? Event = null);
/// <summary>
/// Writes the readable timeline (spec §8.3 <c>event</c>) and publishes engine notifications to any number of
/// subscribers. Slow subscribers lose the oldest notifications, never block the engine.
/// </summary>
public sealed class EngineEvents
{
private const int SubscriberCapacity = 256;
private readonly IEventStore _store;
private readonly IClock _clock;
private readonly Lock _gate = new();
private readonly List<Channel<EngineNotification>> _subscribers = [];
public EngineEvents(IEventStore store, IClock clock)
{
_store = store ?? throw new ArgumentNullException(nameof(store));
_clock = clock ?? throw new ArgumentNullException(nameof(clock));
}
/// <summary>Raised synchronously for every notification (after the event is stored).</summary>
public event EventHandler<EngineNotification>? Notified;
/// <summary>Stores an event of the timeline and publishes it.</summary>
public async Task<EventRecord> WriteAsync(
EventSeverity severity,
string code,
string message,
long? accountId = null,
long? sessionId = null,
CancellationToken ct = default)
{
var record = await _store.AppendAsync(
new EventRecord
{
At = _clock.Now,
Severity = severity,
Code = code,
Message = message,
AccountId = accountId,
SessionId = sessionId,
},
ct).ConfigureAwait(false);
Publish(new EngineNotification(EngineNotificationKind.Event, record.At, record));
return record;
}
/// <summary>Publishes a notification that is not a timeline line.</summary>
public void Publish(EngineNotificationKind kind) => Publish(new EngineNotification(kind, _clock.Now));
/// <summary>Notifications from now on, until <paramref name="ct"/> is cancelled.</summary>
public async IAsyncEnumerable<EngineNotification> SubscribeAsync([EnumeratorCancellation] CancellationToken ct = default)
{
var channel = Channel.CreateBounded<EngineNotification>(new BoundedChannelOptions(SubscriberCapacity)
{
FullMode = BoundedChannelFullMode.DropOldest,
SingleReader = true,
SingleWriter = false,
});
lock (_gate)
{
_subscribers.Add(channel);
}
try
{
while (await channel.Reader.WaitToReadAsync(ct).ConfigureAwait(false))
{
while (channel.Reader.TryRead(out var notification))
{
yield return notification;
}
}
}
finally
{
lock (_gate)
{
_subscribers.Remove(channel);
}
}
}
private void Publish(EngineNotification notification)
{
Channel<EngineNotification>[] subscribers;
lock (_gate)
{
subscribers = [.. _subscribers];
}
foreach (var subscriber in subscribers)
{
subscriber.Writer.TryWrite(notification);
}
Notified?.Invoke(this, notification);
}
}
+828
View File
@@ -0,0 +1,828 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Pacing;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>Outcome of «Controlla ora» (spec §7.8).</summary>
public enum CheckNowStatus
{
/// <summary>Put on top of the queue.</summary>
Queued,
/// <summary>Outside the active window: Alberto must confirm with <see cref="CheckNowResult.ConfirmationToken"/>.</summary>
NeedsConfirmation,
/// <summary>Not possible now (budget exhausted, engine stopped, account not contactable); the message says why.</summary>
Refused,
}
/// <summary>Answer to «Controlla ora»: an Italian message for the interface and, when needed, a confirmation token.</summary>
public sealed record CheckNowResult(CheckNowStatus Status, string Message, string? ConfirmationToken = null, DateTimeOffset? ExpectedAround = null);
/// <summary>Answer to «Riprendi».</summary>
public sealed record ResumeResult(bool Resumed, string Message);
/// <summary>
/// The engine (spec §7): a background loop that plans the day, opens sessions inside the active window, composes them
/// and rests between them. It only uses <see cref="IClock"/> for time and <see cref="IRandomSource"/> for chance, so the
/// same code runs under the virtual clock of the simulation.
/// </summary>
/// <remarks>
/// Commands from the interface (pause, resume, «Controlla ora», settings) are thread-safe and wake the loop.
/// While Alberto uses the browser, during a pause and during a stop of the breaker the engine opens nothing.
/// </remarks>
public sealed class EngineHost : IAsyncDisposable
{
private static readonly TimeSpan LongWait = TimeSpan.FromHours(6);
private readonly EngineServices _s;
private readonly IRecipeRunner _runner;
private readonly RecipeHealth _health;
private readonly RecentActions _recent = new();
private readonly SessionComposer _composer;
private readonly Lock _gate = new();
private readonly Dictionary<string, (long AccountId, DateTimeOffset Expires)> _confirmations = new(StringComparer.Ordinal);
private readonly Dictionary<long, DateTimeOffset> _outsideWindowAllowed = [];
private CancellationTokenSource _wake = new();
private CancellationTokenSource? _sessionCts;
private CancellationTokenSource? _loopCts;
private Task? _loop;
private bool _initialized;
private bool _manualWaiting;
private DateTimeOffset? _plannedAfterStop;
public EngineHost(EngineServices services, IRecipeRunner runner)
{
_s = services ?? throw new ArgumentNullException(nameof(services));
_runner = runner ?? throw new ArgumentNullException(nameof(runner));
_health = new RecipeHealth(services.Storage.Settings, services.Options.ConsecutiveFailuresToSuspend);
_composer = new SessionComposer(services, runner, _health, _recent, ManualDone);
Monitor = new EngineMonitor(services, this);
_s.Breaker.StateChanged += OnBreakerChanged;
}
public EngineServices Services => _s;
/// <summary>What the interface shows of the engine (Attività, sidebar, account settings panel).</summary>
public IEngineMonitor Monitor { get; }
/// <summary>Recipes suspended after repeated unrecognized formats, with when.</summary>
public IReadOnlyDictionary<RecipeKind, DateTimeOffset> SuspendedRecipes => _health.Suspended;
internal IReadOnlyList<RecentAction> RecentActions(int limit) => _recent.Snapshot(limit);
/// <summary>Starts the background loop.</summary>
public Task StartAsync(CancellationToken ct = default)
{
lock (_gate)
{
if (_loop is not null)
{
return Task.CompletedTask;
}
_loopCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
var token = _loopCts.Token;
_loop = Task.Run(() => RunAsync(token), CancellationToken.None);
}
return Task.CompletedTask;
}
/// <summary>Stops the loop; a session in progress ends as interrupted and the browser goes to rest.</summary>
public async Task StopAsync()
{
Task? loop;
lock (_gate)
{
loop = _loop;
_loopCts?.Cancel();
}
if (loop is not null)
{
try
{
await loop.ConfigureAwait(false);
}
catch (OperationCanceledException)
{
}
}
lock (_gate)
{
_loop = null;
_loopCts?.Dispose();
_loopCts = null;
}
}
public async ValueTask DisposeAsync()
{
_s.Breaker.StateChanged -= OnBreakerChanged;
await StopAsync().ConfigureAwait(false);
_wake.Dispose();
}
/// <summary>
/// The loop of the engine, until <paramref name="ct"/> is cancelled. <see cref="StartAsync"/> runs it in the
/// background; the simulation awaits it directly under the virtual clock.
/// </summary>
public async Task RunAsync(CancellationToken ct)
{
_s.Runtime.IsRunning = true;
try
{
await InitializeAsync(ct).ConfigureAwait(false);
while (true)
{
ct.ThrowIfCancellationRequested();
CancellationToken wake;
lock (_gate)
{
wake = _wake.Token;
}
var wait = await StepAsync(ct).ConfigureAwait(false);
if (wait is { } delay && delay > TimeSpan.Zero)
{
await WaitAsync(delay, wake, ct).ConfigureAwait(false);
}
}
}
finally
{
_s.Runtime.IsRunning = false;
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
}
/// <summary>«Metti in pausa»: stops the engine until «Riprendi»; a session in progress ends now.</summary>
public async Task PauseAsync(CancellationToken ct = default)
{
if (_s.Runtime.IsPaused)
{
return;
}
_s.Runtime.IsPaused = true;
await _s.Storage.Settings.SetBoolAsync(EngineSettingKeys.Paused, true, ct).ConfigureAwait(false);
CancelSession();
Wake();
await _s.Events.WriteAsync(EventSeverity.Info, EngineEventCodes.Paused, "Messo in pausa da te: Febe non apre nulla finché non premi «Riprendi».", ct: ct).ConfigureAwait(false);
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>
/// «Riprendi»: ends a pause and, after a verification or a disconnection that Alberto fixed in the browser, reopens
/// the breaker (with the gradual start). A throttle stop has a fixed length and is not shortened.
/// </summary>
public async Task<ResumeResult> ResumeAsync(CancellationToken ct = default)
{
var messages = new List<string>();
var resumed = false;
var breaker = _s.Breaker.State;
if (breaker.Status is BreakerStatus.Challenge or BreakerStatus.Disconnected)
{
resumed |= await _s.Breaker.ResumeAsync(ct).ConfigureAwait(false);
messages.Add(_s.Runtime.Profile.GradualStart ? "Ripreso dopo il fermo: i tetti ripartono dalla metà." : "Ripreso dopo il fermo.");
}
if (_s.Runtime.IsPaused)
{
_s.Runtime.IsPaused = false;
await _s.Storage.Settings.SetBoolAsync(EngineSettingKeys.Paused, false, ct).ConfigureAwait(false);
await _s.Events.WriteAsync(EventSeverity.Info, EngineEventCodes.Unpaused, "Ripreso dopo la pausa.", ct: ct).ConfigureAwait(false);
messages.Add("Ripreso dopo la pausa.");
resumed = true;
}
breaker = _s.Breaker.State;
if (breaker.Status == BreakerStatus.Throttled && breaker.Until is { } until)
{
messages.Add($"Il fermo per rallentamento dura fino {ItalianText.AtDay(until, _s.Clock.Now, _s.Clock.LocalZone)} e non si accorcia.");
}
else if (resumed)
{
// The first session after «Riprendi» comes 2–10 minutes later, as after a start.
var restart = _s.Clock.Now + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
if (_s.Runtime.NextSessionAt is not { } planned || planned < restart)
{
_s.Runtime.NextSessionAt = restart;
}
}
Wake();
_s.Events.Publish(EngineNotificationKind.StateChanged);
return new ResumeResult(resumed, messages.Count == 0 ? "Febe stava già lavorando." : string.Join(" ", messages));
}
/// <summary>
/// «Controlla ora» (spec §7.8): puts the check of an account on top of the queue. It still goes through the
/// Governor: with an exhausted budget Febe says so and does not do it. Outside the active window the first call
/// returns <see cref="CheckNowStatus.NeedsConfirmation"/> with a token; calling again with the token allows that
/// single check.
/// </summary>
public async Task<CheckNowResult> CheckNowAsync(long accountId, string? confirmationToken = null, CancellationToken ct = default)
{
var now = _s.Clock.Now;
var zone = _s.Clock.LocalZone;
var account = await _s.Storage.Accounts.GetAsync(accountId, ct).ConfigureAwait(false);
if (account is null)
{
return new CheckNowResult(CheckNowStatus.Refused, "Questo account non c'è più nell'elenco di Febe.");
}
var handle = ItalianText.Handle(account.Username);
if (!CheckPolicy.AllowsManualCheck(account))
{
return new CheckNowResult(
CheckNowStatus.Refused,
account.State == AccountState.ArchiveOnly
? $"{handle} è «Solo archivio»: Febe non lo contatta."
: $"{handle} è privato e non lo segui: Febe non lo apre.");
}
var breaker = _s.Breaker.State;
if (!breaker.AllowsSiteActions)
{
return new CheckNowResult(CheckNowStatus.Refused, Governor.BreakerMessage(breaker, now, zone));
}
if (_s.Runtime.IsPaused)
{
return new CheckNowResult(CheckNowStatus.Refused, "Febe è in pausa: premi «Riprendi» prima di chiedere un controllo.");
}
var kind = CheckPolicy.WantsProfileChecks(account) ? EngineTaskKind.ProfileCheck : EngineTaskKind.AccountStories;
var category = kind == EngineTaskKind.ProfileCheck ? ActionKind.ProfileOpen : ActionKind.StoryView;
var budget = await _s.Governor.EvaluateBudgetAsync(category, accountId, ct).ConfigureAwait(false);
if (!budget.Granted && budget.Reason != DenialReason.AccountNotContactable)
{
return new CheckNowResult(CheckNowStatus.Refused, (budget.Message ?? "Tetto raggiunto.") + " Il controllo non parte.");
}
var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
var floor = PauseFloor();
if (window is null)
{
bool confirmed;
lock (_gate)
{
PruneLocked(now);
confirmed = confirmationToken is not null
&& _confirmations.TryGetValue(confirmationToken, out var pending)
&& pending.AccountId == accountId;
if (confirmed)
{
_confirmations.Remove(confirmationToken!);
_outsideWindowAllowed[accountId] = now + TimeSpan.FromHours(1);
}
}
if (!confirmed)
{
var token = Guid.NewGuid().ToString("N");
lock (_gate)
{
_confirmations[token] = (accountId, now + _s.Options.ManualConfirmationLifetime);
}
var next = await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
var resumes = next is null ? string.Empty : $" Di solito riprende {ItalianText.Around(next.Start, now, zone)}.";
return new CheckNowResult(
CheckNowStatus.NeedsConfirmation,
$"Sei fuori dalla fascia oraria, quando Febe non apre nulla da solo.{resumes} Confermi un solo controllo di {handle} adesso?",
token);
}
await EnqueueManualAsync(kind, accountId, now, ct).ConfigureAwait(false);
var expected = floor is { } f && f > now ? f : now;
await _s.Events.WriteAsync(
EventSeverity.Info,
EngineEventCodes.ManualCheck,
$"Controllo di {handle} fuori fascia, confermato da te: parte {(expected > now ? ItalianText.Around(expected, now, zone) : "adesso")}.",
accountId,
ct: ct).ConfigureAwait(false);
Wake();
return new CheckNowResult(CheckNowStatus.Queued, $"Controllo di {handle} confermato: è l'unico che Febe fa fuori fascia.", null, expected);
}
await EnqueueManualAsync(kind, accountId, now, ct).ConfigureAwait(false);
Wake();
if (_s.Runtime.CurrentSession is not null)
{
return new CheckNowResult(CheckNowStatus.Queued, $"Controllo di {handle} in cima alla coda: parte in questa sessione.", null, now);
}
// The next session comes as soon as the pause floor allows (spec §7.2: the floor always holds).
var start = floor is { } minimum && minimum > now ? minimum : now;
await _s.Events.WriteAsync(
EventSeverity.Info,
EngineEventCodes.ManualCheck,
$"Controllo di {handle} chiesto da te: in cima alla coda.",
accountId,
ct: ct).ConfigureAwait(false);
return new CheckNowResult(
CheckNowStatus.Queued,
start > now
? $"Controllo di {handle} in cima alla coda: parte {ItalianText.Around(start, now, zone)}, dopo la pausa minima fra due sessioni."
: $"Controllo di {handle} in cima alla coda: parte adesso.",
null,
start);
}
/// <summary>«Leggi l'elenco dei seguiti» (spec §4.2): read at human pace inside the budgets, possibly over several sessions.</summary>
public async Task RequestFollowingListAsync(CancellationToken ct = default)
{
var now = _s.Clock.Now;
Volatile.Write(ref _manualWaiting, true);
await _s.Storage.Tasks.EnqueueAsync(
new EngineTask
{
Kind = EngineTaskKind.FollowingList,
DueAt = now,
Priority = _s.Options.ManualPriority,
IsManual = true,
CreatedAt = now,
},
ct).ConfigureAwait(false);
Wake();
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>Accounts were added, removed or changed: the queue is brought in step before the next session.</summary>
public async Task NotifyAccountsChangedAsync(CancellationToken ct = default)
{
await _composer.SyncQueueAsync(ct).ConfigureAwait(false);
Wake();
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>Alberto started or finished using the browser: when he starts, the session in progress ends at once.</summary>
public void NotifyUserDrivingChanged()
{
if (_s.Runtime.UserIsDriving)
{
CancelSession();
}
Wake();
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>Reactivates a recipe suspended after repeated unrecognized formats (after the reader was updated).</summary>
public async Task<bool> ResumeRecipeAsync(RecipeKind kind, CancellationToken ct = default)
{
var resumed = await _health.ResumeAsync(kind, ct).ConfigureAwait(false);
if (resumed)
{
await _s.Events.WriteAsync(
EventSeverity.Info,
EngineEventCodes.RecipeResumed,
$"«{ItalianText.Capitalize(SessionComposer.RecipeName(kind))}» riattivato.",
ct: ct).ConfigureAwait(false);
Wake();
}
return resumed;
}
/// <summary>Stores and applies new engine settings, then replans.</summary>
public async Task ApplySettingsAsync(EngineSettings settings, CancellationToken ct = default)
{
await _s.ApplySettingsAsync(settings, ct).ConfigureAwait(false);
Wake();
}
private async Task InitializeAsync(CancellationToken ct)
{
if (_initialized)
{
return;
}
var now = _s.Clock.Now;
var store = _s.Storage;
await _health.LoadAsync(ct).ConfigureAwait(false);
// A session left open by a process that ended abruptly closes at its last action.
var lastAction = await store.ActionLog.GetLastActionAtAsync(null, ct).ConfigureAwait(false);
var last = await store.Sessions.GetLastAsync(ct).ConfigureAwait(false);
if (last is { EndedAt: null })
{
var end = lastAction is { } a && a > last.StartedAt && a <= now ? a : last.StartedAt;
await store.Sessions.CloseInterruptedAsync(end, ct).ConfigureAwait(false);
last = await store.Sessions.GetLastAsync(ct).ConfigureAwait(false);
}
await store.Tasks.RequeueRunningAsync(ct).ConfigureAwait(false);
// A restart never brings the next session earlier than a program that stayed on would have.
var lastEnd = Max(last?.EndedAt, lastAction);
_s.Runtime.LastSessionEnd = lastEnd;
var persisted = await store.Settings.GetInt64Async(EngineSettingKeys.NextSession, ct).ConfigureAwait(false);
var next = now + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
if (persisted is { } ms && DateTimeOffset.FromUnixTimeMilliseconds(ms) > next)
{
next = DateTimeOffset.FromUnixTimeMilliseconds(ms);
}
if (PauseFloor() is { } floor && floor > next)
{
next = floor;
}
_s.Runtime.NextSessionAt = next;
_s.Runtime.StartedAt = now;
_s.Runtime.HadSessionSinceStart = false;
await store.Settings.SetInt64Async(EngineSettingKeys.NextSession, next.ToUnixTimeMilliseconds(), ct).ConfigureAwait(false);
await _composer.SyncQueueAsync(ct).ConfigureAwait(false);
_initialized = true;
_s.Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>One turn of the loop: runs a session when one is due, otherwise says how long to wait.</summary>
private async Task<TimeSpan?> StepAsync(CancellationToken ct)
{
var now = _s.Clock.Now;
var runtime = _s.Runtime;
if (runtime.IsPaused)
{
return LongWait;
}
var breaker = _s.Breaker.State;
if (!breaker.AllowsSiteActions)
{
if (breaker.Status == BreakerStatus.Throttled && breaker.Until is { } until)
{
// After the stop the engine does not restart on the dot: a few minutes later, as after a start.
if (_plannedAfterStop != until)
{
_plannedAfterStop = until;
var restart = until + _s.Random.Between(_s.Options.StartupDelayMin, _s.Options.StartupDelayMax);
if (runtime.NextSessionAt is not { } planned || planned < restart)
{
runtime.NextSessionAt = restart;
}
}
return until - now;
}
return LongWait;
}
if (runtime.UserIsDriving || runtime.IsConnected == false)
{
// Alberto at the browser, or no Instagram session yet: look again in a while.
return _s.Options.UserDrivingPoll;
}
var floor = PauseFloor();
var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
if (window is null)
{
// Night: nothing on the engine's initiative. The only exception is a «Controlla ora» Alberto confirmed.
var manual = await FindConfirmedManualAsync(now, ct).ConfigureAwait(false);
if (manual is not null)
{
if (floor is { } f && f > now)
{
return f - now;
}
await RunSessionAsync(null, manual, ct).ConfigureAwait(false);
return null;
}
var next = await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
if (next is null)
{
return LongWait;
}
var target = runtime.NextSessionAt is { } planned && planned > next.Start ? planned : next.Start;
if (floor is { } minimum && minimum > target)
{
target = minimum;
}
runtime.NextSessionAt = target;
return target - now;
}
var start = runtime.NextSessionAt ?? now;
if (start > now && Volatile.Read(ref _manualWaiting))
{
// «Controlla ora»: the next session comes as soon as the pause floor allows.
start = now;
}
if (floor is { } pauseFloor && pauseFloor > start)
{
start = pauseFloor;
}
if (start > now)
{
runtime.NextSessionAt = start;
return (start < window.End ? start : window.End) - now;
}
if (window.End - now < _s.Options.MinimumSessionRoom)
{
return window.End - now;
}
await RunSessionAsync(window, null, ct).ConfigureAwait(false);
return null;
}
private async Task RunSessionAsync(ActiveWindow? window, EngineTask? outsideWindowTask, CancellationToken ct)
{
var s = _s;
var profile = s.Runtime.Profile;
var start = s.Clock.Now;
var mood = s.Random.SessionMood();
var plannedEnd = start + s.Random.Between(profile.SessionMin, profile.SessionMax);
if (window is not null && plannedEnd > window.End)
{
plannedEnd = window.End;
}
var record = await s.Storage.Sessions.StartAsync(start, ct).ConfigureAwait(false);
var context = new SessionContext(record.Id, mood, start, plannedEnd, outsideWindowTask?.AccountId);
using var sessionCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
lock (_gate)
{
_sessionCts = sessionCts;
}
s.Runtime.CurrentSession = context;
s.Runtime.HadSessionSinceStart = true;
Volatile.Write(ref _manualWaiting, false);
s.Runtime.NextSessionAt = null;
s.Events.Publish(EngineNotificationKind.StateChanged);
var outcome = SessionOutcome.Completed;
var interrupted = false;
try
{
// A stop that arrived while the session was opening ends it before anything is done.
if (!s.Breaker.State.AllowsSiteActions || s.Runtime.IsPaused || s.Runtime.UserIsDriving)
{
sessionCts.Cancel();
}
var summary = await _composer.RunAsync(context, outsideWindowTask, sessionCts.Token).ConfigureAwait(false);
if (summary.StoppedEarly || !s.Breaker.State.AllowsSiteActions || s.Runtime.IsPaused || s.Runtime.UserIsDriving)
{
outcome = StopOutcome();
}
}
catch (OperationCanceledException) when (!ct.IsCancellationRequested)
{
outcome = StopOutcome();
}
catch (OperationCanceledException)
{
outcome = SessionOutcome.Interrupted;
interrupted = true;
throw;
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
outcome = SessionOutcome.Failed;
await s.Events.WriteAsync(
EventSeverity.Error,
EngineEventCodes.RecipeFailed,
$"La sessione si è chiusa per un errore imprevisto ({ex.GetType().Name}). Riprendo alla prossima.",
sessionId: record.Id,
ct: CancellationToken.None).ConfigureAwait(false);
}
finally
{
lock (_gate)
{
_sessionCts = null;
}
s.Runtime.CurrentSession = null;
s.Runtime.Activity = null;
await EndSessionAsync(record, context, outcome, outsideWindowTask, interrupted).ConfigureAwait(false);
}
}
private async Task EndSessionAsync(SessionRecord record, SessionContext context, SessionOutcome outcome, EngineTask? outsideWindowTask, bool interrupted)
{
var s = _s;
var ct = CancellationToken.None;
// Rest on the empty page, except when the page must stay as it is (verification, disconnection) or Alberto is
// using the browser (spec §6.1, §7.6).
var breaker = s.Breaker.State;
var keepPage = breaker.Status is BreakerStatus.Challenge or BreakerStatus.Disconnected || s.Runtime.UserIsDriving;
if (!keepPage)
{
try
{
await _runner.RestAsync(ct).ConfigureAwait(false);
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
await s.Events.WriteAsync(
EventSeverity.Warning,
EngineEventCodes.RecipeFailed,
$"Non sono riuscito a portare il browser sulla pagina vuota ({ex.GetType().Name}).",
sessionId: record.Id,
ct: ct).ConfigureAwait(false);
}
}
var end = s.Clock.Now;
var summaryText = $"{ItalianText.Count(context.ActionCount, "azione", "azioni")}, {ItalianText.Count(context.NewEntries, "contenuto nuovo", "contenuti nuovi")}";
var writes = new List<Task> { s.Storage.Sessions.EndAsync(record.Id, end, outcome, context.ActionCount, summaryText, ct) };
s.Runtime.LastSessionEnd = end;
if (outsideWindowTask?.AccountId is { } manualAccount)
{
ManualDone(manualAccount);
}
if (interrupted)
{
await Task.WhenAll(writes).ConfigureAwait(false);
return;
}
var pause = s.Random.Between(s.Runtime.Profile.PauseMin, s.Runtime.Profile.PauseMax);
var next = end + pause;
s.Runtime.NextSessionAt = next;
writes.Add(s.Storage.Settings.SetInt64Async(EngineSettingKeys.NextSession, next.ToUnixTimeMilliseconds(), ct));
if ((await s.Storage.Accounts.ListAsync(ct).ConfigureAwait(false)).Any(a => a.IsFollowed && CheckPolicy.IsContactable(a)))
{
writes.Add(_composer.EnsureSweepTaskAsync(next, ct));
}
var length = ItalianText.Duration(end - record.StartedAt);
var tail = outcome switch
{
SessionOutcome.Throttled => " Chiusa per un rallentamento chiesto da Instagram.",
SessionOutcome.Stopped => " Chiusa prima del previsto.",
SessionOutcome.Failed => " Chiusa per un errore.",
_ => string.Empty,
};
writes.Add(s.Events.WriteAsync(
outcome == SessionOutcome.Completed ? EventSeverity.Info : EventSeverity.Warning,
EngineEventCodes.SessionEnded,
$"Sessione di {length}: {summaryText}.{tail}",
sessionId: record.Id,
ct: ct));
await Task.WhenAll(writes).ConfigureAwait(false);
s.Events.Publish(EngineNotificationKind.StateChanged);
}
private SessionOutcome StopOutcome() =>
_s.Breaker.State.Status == BreakerStatus.Throttled ? SessionOutcome.Throttled : SessionOutcome.Stopped;
private DateTimeOffset? PauseFloor() =>
_s.Runtime.LastSessionEnd is { } end ? end + _s.Runtime.Profile.PauseMin : null;
private async Task<EngineTask?> FindConfirmedManualAsync(DateTimeOffset now, CancellationToken ct)
{
Dictionary<long, DateTimeOffset> allowed;
lock (_gate)
{
PruneLocked(now);
if (_outsideWindowAllowed.Count == 0)
{
return null;
}
allowed = new Dictionary<long, DateTimeOffset>(_outsideWindowAllowed);
}
var due = await _s.Storage.Tasks.PeekDueAsync(now, 100, ct).ConfigureAwait(false);
return due.FirstOrDefault(t => t.IsManual && t.AccountId is { } id && allowed.ContainsKey(id));
}
private void ManualDone(long accountId)
{
lock (_gate)
{
_outsideWindowAllowed.Remove(accountId);
}
}
private void PruneLocked(DateTimeOffset now)
{
foreach (var token in _confirmations.Where(c => c.Value.Expires <= now).Select(c => c.Key).ToList())
{
_confirmations.Remove(token);
}
foreach (var account in _outsideWindowAllowed.Where(c => c.Value <= now).Select(c => c.Key).ToList())
{
_outsideWindowAllowed.Remove(account);
}
}
private async Task EnqueueManualAsync(EngineTaskKind kind, long accountId, DateTimeOffset now, CancellationToken ct)
{
Volatile.Write(ref _manualWaiting, true);
await _s.Storage.Tasks.EnqueueAsync(
new EngineTask
{
Kind = kind,
AccountId = accountId,
DueAt = now,
Priority = _s.Options.ManualPriority,
IsManual = true,
CreatedAt = now,
},
ct).ConfigureAwait(false);
}
private void OnBreakerChanged(object? sender, BreakerState state)
{
// Signals arrive on capture threads: the engine is never run inline on them (it may need the browser to answer).
// The composer also checks the breaker before every recipe, so the session stops at once either way.
CancellationTokenSource? session = null;
if (!state.AllowsSiteActions)
{
lock (_gate)
{
session = _sessionCts;
}
}
_ = Task.Run(() =>
{
Cancel(session);
Wake();
_s.Events.Publish(EngineNotificationKind.StateChanged);
});
}
private void CancelSession()
{
CancellationTokenSource? session;
lock (_gate)
{
session = _sessionCts;
}
Cancel(session);
}
private static void Cancel(CancellationTokenSource? session)
{
try
{
session?.Cancel();
}
catch (ObjectDisposedException)
{
}
}
/// <summary>Wakes the loop if it is waiting; the wait it was in is cancelled synchronously.</summary>
private void Wake()
{
CancellationTokenSource old;
lock (_gate)
{
old = _wake;
_wake = new CancellationTokenSource();
}
// The old source is not disposed: the loop may still hold its (now cancelled) token.
old.Cancel();
}
private async Task WaitAsync(TimeSpan delay, CancellationToken wake, CancellationToken ct)
{
if (wake.IsCancellationRequested)
{
return;
}
using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct, wake);
try
{
await _s.Clock.Delay(delay, linked.Token).ConfigureAwait(false);
}
catch (OperationCanceledException) when (!ct.IsCancellationRequested)
{
// Woken by a command: look again.
}
}
private static DateTimeOffset? Max(DateTimeOffset? a, DateTimeOffset? b) =>
a is null ? b : b is null ? a : a > b ? a : b;
}
+71
View File
@@ -0,0 +1,71 @@
namespace Febe.Core.Engine;
/// <summary>
/// Tuning of the engine that is not part of a caution profile. Values marked «ipotesi» depend on how Instagram
/// behaves and must be confirmed in M0 (spec §6.6, rule 10): they are configuration, not facts.
/// </summary>
public sealed record EngineOptions
{
public static EngineOptions Default { get; } = new();
/// <summary>
/// Ipotesi da confermare in M0 (H3): posts loaded by one page of history. Used only to estimate how many pages
/// the per-account daily backfill limit allows and how many days a backfill needs; the Governor counts real posts.
/// </summary>
public int PostsPerBackfillPage { get; init; } = 12;
/// <summary>
/// Ipotesi da confermare in M0 (H2): the stories bar read by the Giro dei seguiti tells which followed profiles
/// have active stories, so a completed sweep counts as a story check of every followed account it did not flag.
/// With false, followed accounts get explicit story checks at their interval.
/// </summary>
public bool SweepCoversFollowedStories { get; init; } = true;
/// <summary>«Lo storico non corre più veloce dei download» (spec §6.3): backfill of an account waits above this many pending files.</summary>
public int BackfillMaxPendingDownloads { get; init; } = 60;
/// <summary>Minimum distance between two counted actions at the «naturale» gesture pace (spec §7.2); scaled by the pace.</summary>
public TimeSpan MinimumSpacing { get; init; } = TimeSpan.FromSeconds(4);
/// <summary>The first session starts 2–10 minutes after the program (spec §7.2).</summary>
public TimeSpan StartupDelayMin { get; init; } = TimeSpan.FromMinutes(2);
public TimeSpan StartupDelayMax { get; init; } = TimeSpan.FromMinutes(10);
/// <summary>«Una sessione comincia di norma con il Giro dei seguiti»: probability of opening with the sweep.</summary>
public double SweepProbability { get; init; } = 0.9;
/// <summary>«Circa una su tre si limita al giro e alle storie».</summary>
public double LightSessionProbability { get; init; } = 1.0 / 3.0;
/// <summary>«Qualche pagina di storico» per session: drawn in this range (log-normal), then limited by the account's daily maximum.</summary>
public int BackfillPagesMin { get; init; } = 3;
public int BackfillPagesMax { get; init; } = 12;
/// <summary>Wait between two recipes of a session («fra un account e l'altro da 1 a 4 s»), times mood and pace.</summary>
public TimeSpan BetweenRecipesMin { get; init; } = TimeSpan.FromSeconds(1);
public TimeSpan BetweenRecipesMax { get; init; } = TimeSpan.FromSeconds(4);
/// <summary>Consecutive «formato non riconosciuto» (or «bersaglio non trovato») outcomes that suspend a recipe (spec §6.4).</summary>
public int ConsecutiveFailuresToSuspend { get; init; } = 3;
/// <summary>How long a «Controlla ora» confirmation token stays valid outside the active window (spec §7.8).</summary>
public TimeSpan ManualConfirmationLifetime { get; init; } = TimeSpan.FromMinutes(10);
/// <summary>How often the idle engine looks again whether Alberto has finished using the browser.</summary>
public TimeSpan UserDrivingPoll { get; init; } = TimeSpan.FromSeconds(30);
/// <summary>A session does not start when less than this remains of the active window.</summary>
public TimeSpan MinimumSessionRoom { get; init; } = TimeSpan.FromMinutes(1);
/// <summary>With «Storie» on, every account gets at least this many story checks per day inside the window (spec §7.3).</summary>
public int MinimumStoryChecksPerDay { get; init; } = 3;
/// <summary>Priority of «Controlla ora» and of other commands of Alberto in the queue.</summary>
public int ManualPriority { get; init; } = 100;
/// <summary>Priority of story checks flagged by the stories bar.</summary>
public int FlaggedStoriesPriority { get; init; } = 10;
}
+170
View File
@@ -0,0 +1,170 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Engine;
/// <summary>
/// Live state shared by the engine host, the Governor, the circuit breaker and the monitor. Everything that must
/// survive a restart is persisted by its owner; this object only mirrors it in memory. Thread-safe.
/// </summary>
public sealed class EngineRuntime
{
private readonly Lock _gate = new();
private readonly Func<bool> _userIsDriving;
private readonly Func<bool>? _isConnected;
private CautionProfile _profile = CautionProfile.Prudent;
private DateTimeOffset? _rampStart;
private SessionContext? _session;
private string? _activity;
private DateTimeOffset? _nextSessionAt;
private DateTimeOffset? _lastSessionEnd;
private bool _paused;
private bool _running;
/// <param name="userIsDriving">True while Alberto uses the browser (<see cref="IBrowserHost.UserIsDriving"/>).</param>
/// <param name="isConnected">Whether the Instagram session exists in the browser; null when unknown.</param>
public EngineRuntime(Func<bool>? userIsDriving = null, Func<bool>? isConnected = null)
{
_userIsDriving = userIsDriving ?? (() => false);
_isConnected = isConnected;
}
/// <summary>The effective caution profile (settings applied).</summary>
public CautionProfile Profile
{
get { lock (_gate) { return _profile; } }
set { lock (_gate) { _profile = value ?? throw new ArgumentNullException(nameof(value)); } }
}
/// <summary>Start of the gradual start: first connection or last resolved verification/disconnection.</summary>
public DateTimeOffset? RampStart
{
get { lock (_gate) { return _rampStart; } }
set { lock (_gate) { _rampStart = value; } }
}
/// <summary>«Metti in pausa» is active.</summary>
public bool IsPaused
{
get { lock (_gate) { return _paused; } }
set { lock (_gate) { _paused = value; } }
}
/// <summary>True while Alberto uses the browser: the engine does not act.</summary>
public bool UserIsDriving => _userIsDriving();
/// <summary>Whether the browser holds an Instagram session; null when the host does not say.</summary>
public bool? IsConnected => _isConnected?.Invoke();
/// <summary>The session in progress, if any. The Governor refuses every site action without one.</summary>
public SessionContext? CurrentSession
{
get { lock (_gate) { return _session; } }
set { lock (_gate) { _session = value; } }
}
/// <summary>What the engine is doing now, in Italian («Sto guardando le storie di @marta.demo»).</summary>
public string? Activity
{
get { lock (_gate) { return _activity; } }
set { lock (_gate) { _activity = value; } }
}
/// <summary>Planned start of the next session (indicative: «verso le»).</summary>
public DateTimeOffset? NextSessionAt
{
get { lock (_gate) { return _nextSessionAt; } }
set { lock (_gate) { _nextSessionAt = value; } }
}
/// <summary>End of the last session (the pause floor counts from here).</summary>
public DateTimeOffset? LastSessionEnd
{
get { lock (_gate) { return _lastSessionEnd; } }
set { lock (_gate) { _lastSessionEnd = value; } }
}
/// <summary>The background loop of the engine is running.</summary>
public bool IsRunning
{
get { lock (_gate) { return _running; } }
set { lock (_gate) { _running = value; } }
}
/// <summary>When the loop started (the first session comes 2–10 minutes later).</summary>
public DateTimeOffset? StartedAt
{
get { lock (_gate) { return _startedAt; } }
set { lock (_gate) { _startedAt = value; } }
}
/// <summary>A session has started since the loop started.</summary>
public bool HadSessionSinceStart
{
get { lock (_gate) { return _hadSession; } }
set { lock (_gate) { _hadSession = value; } }
}
private DateTimeOffset? _startedAt;
private bool _hadSession;
}
/// <summary>The session in progress (spec §7.2), handed to every recipe.</summary>
public sealed class SessionContext : ISessionContext
{
private int _actions;
private int _newEntries;
private long _manualAccountId = -1;
public SessionContext(long sessionId, double mood, DateTimeOffset startedAt, DateTimeOffset plannedEnd, long? outsideWindowAccountId = null)
{
SessionId = sessionId;
Mood = mood;
StartedAt = startedAt;
PlannedEnd = plannedEnd;
OutsideWindowAccountId = outsideWindowAccountId;
if (outsideWindowAccountId is { } id)
{
_manualAccountId = id;
}
}
/// <summary>
/// The account of the «Controlla ora» being run, if any: a paused or unreachable account (not private and
/// unfollowed, not «Solo archivio») may be checked on Alberto's request.
/// </summary>
public long? ManualAccountId
{
get
{
var value = Interlocked.Read(ref _manualAccountId);
return value < 0 ? null : value;
}
internal set => Interlocked.Exchange(ref _manualAccountId, value ?? OutsideWindowAccountId ?? -1);
}
public long SessionId { get; }
public double Mood { get; }
public DateTimeOffset StartedAt { get; }
public DateTimeOffset PlannedEnd { get; }
/// <summary>
/// Set only for a «Controlla ora» confirmed by Alberto outside the active window (spec §7.8): the Governor allows
/// actions on this account only, and only during this session.
/// </summary>
public long? OutsideWindowAccountId { get; }
/// <summary>Counted actions granted in this session.</summary>
public int ActionCount => Volatile.Read(ref _actions);
/// <summary>New entries reported by the recipes of this session.</summary>
public int NewEntries => Volatile.Read(ref _newEntries);
internal void CountAction() => Interlocked.Increment(ref _actions);
internal void AddNewEntries(int count) => Interlocked.Add(ref _newEntries, count);
}
+148
View File
@@ -0,0 +1,148 @@
using System.Globalization;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// The parts of the engine that recipes and the interface need before the engine host exists: runtime state,
/// timeline, day planner, circuit breaker and Governor. Built in two steps because the real recipe runner needs the
/// Governor and the breaker, and the host needs the recipe runner:
/// <code>
/// var services = await EngineServices.CreateAsync(storage, clock, random);
/// var runner = new SomeRecipeRunner(services.Governor, services.Breaker, ...);
/// await using var engine = new EngineHost(services, runner);
/// await engine.StartAsync(ct);
/// </code>
/// </summary>
public sealed class EngineServices
{
private EngineServices(
IFebeStorage storage,
IClock clock,
IRandomSource random,
EngineOptions options,
EngineRuntime runtime,
EngineEvents events,
DayPlanner planner,
CircuitBreaker breaker,
Governor governor,
EngineSettings settings)
{
Storage = storage;
Clock = clock;
Random = random;
Options = options;
Runtime = runtime;
Events = events;
Planner = planner;
Breaker = breaker;
Governor = governor;
Settings = settings;
}
public IFebeStorage Storage { get; }
public IClock Clock { get; }
public IRandomSource Random { get; }
public EngineOptions Options { get; }
public EngineRuntime Runtime { get; }
public EngineEvents Events { get; }
public DayPlanner Planner { get; }
public CircuitBreaker Breaker { get; }
/// <summary>The Governor: <see cref="IGovernor"/> for recipes, <see cref="IDataBudget"/> for the download queue.</summary>
public Governor Governor { get; }
/// <summary>Current engine and caution settings.</summary>
public EngineSettings Settings { get; private set; }
/// <summary>
/// Loads settings, pause flag, gradual-start origin and breaker state from the database. When the gradual start has
/// no origin yet (first run after the first connection) it starts now.
/// </summary>
/// <param name="storage">The database.</param>
/// <param name="clock">Time source (virtual in tests and simulation).</param>
/// <param name="random">Random source (seeded in tests and simulation).</param>
/// <param name="options">Tuning; <see cref="EngineOptions.Default"/> when null.</param>
/// <param name="userIsDriving">True while Alberto uses the browser.</param>
/// <param name="isConnected">Whether the browser holds an Instagram session; null when unknown.</param>
/// <param name="ct">Cancellation.</param>
public static async Task<EngineServices> CreateAsync(
IFebeStorage storage,
IClock clock,
IRandomSource random,
EngineOptions? options = null,
Func<bool>? userIsDriving = null,
Func<bool>? isConnected = null,
CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(storage);
ArgumentNullException.ThrowIfNull(clock);
ArgumentNullException.ThrowIfNull(random);
options ??= EngineOptions.Default;
var runtime = new EngineRuntime(userIsDriving, isConnected);
var settings = await EngineSettingsStore.LoadAsync(storage.Settings, ct).ConfigureAwait(false);
runtime.Profile = settings.EffectiveProfile;
runtime.IsPaused = await storage.Settings.GetBoolAsync(EngineSettingKeys.Paused, false, ct).ConfigureAwait(false);
var rampStart = await storage.Settings.GetInt64Async(EngineSettingKeys.RampStart, ct).ConfigureAwait(false);
if (rampStart is null)
{
rampStart = clock.Now.ToUnixTimeMilliseconds();
await storage.Settings.SetInt64Async(EngineSettingKeys.RampStart, rampStart, ct).ConfigureAwait(false);
}
runtime.RampStart = DateTimeOffset.FromUnixTimeMilliseconds(rampStart.Value);
var events = new EngineEvents(storage.Events, clock);
var planner = new DayPlanner(storage.Settings, random, () => runtime.Profile, clock.LocalZone);
// Draws (or loads) the seed of the daily windows now, so that later readers never consume randomness.
await planner.GetNextWindowAsync(clock.Now, ct).ConfigureAwait(false);
var breaker = await CircuitBreaker.LoadAsync(storage, clock, runtime, events, ct).ConfigureAwait(false);
var governor = new Governor(storage, breaker, runtime, planner, clock, options, events);
return new EngineServices(storage, clock, random, options, runtime, events, planner, breaker, governor, settings);
}
/// <summary>
/// Validates and stores new engine settings (mockup 07) and applies them at once. Throws
/// <see cref="ArgumentException"/> with Italian messages when a value is outside the limits of spec §7.5.
/// </summary>
public async Task ApplySettingsAsync(EngineSettings settings, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(settings);
await EngineSettingsStore.SaveAsync(Storage.Settings, settings, ct).ConfigureAwait(false);
Settings = settings;
Runtime.Profile = settings.EffectiveProfile;
await Events.WriteAsync(
EventSeverity.Info,
EngineEventCodes.SettingsChanged,
$"Impostazioni del motore cambiate: profilo «{ItalianText.Profile(settings.ProfileKind)}».",
ct: ct).ConfigureAwait(false);
Events.Publish(EngineNotificationKind.StateChanged);
}
/// <summary>
/// The first connection to Instagram (spec §7.2): the gradual start begins now. Later connections do not restart it;
/// the resume after a verification or a disconnection does, through <see cref="CircuitBreaker.ResumeAsync"/>.
/// </summary>
public async Task NotifyFirstConnectionAsync(CancellationToken ct = default)
{
var now = Clock.Now;
Runtime.RampStart = now;
await Storage.Settings.SetAsync(
EngineSettingKeys.RampStart,
now.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture),
ct).ConfigureAwait(false);
}
}
+379
View File
@@ -0,0 +1,379 @@
using System.Globalization;
using System.Text.Json;
using System.Text.Json.Nodes;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>Setting keys of the engine (spec §8.3 <c>setting</c>). Values are invariant-culture text.</summary>
public static class EngineSettingKeys
{
/// <summary>Caution profile kind: Prudent, Balanced, Fast or Custom.</summary>
public const string Profile = "motore.profilo";
/// <summary>Values of the «Su misura» profile, as compact JSON.</summary>
public const string CustomProfile = "motore.profilo-su-misura";
/// <summary>«Ritmo dei gesti»: Slow, Natural, Brisk.</summary>
public const string Pace = "motore.ritmo-gesti";
/// <summary>«Avvio graduale» on or off.</summary>
public const string GradualStart = "motore.avvio-graduale";
/// <summary>Active weekdays as digits 0 (Sunday) … 6 (Saturday), e.g. "0123456".</summary>
public const string ActiveDays = "motore.giorni-attivi";
/// <summary>«Metti in pausa»: true while the engine is paused by Alberto.</summary>
public const string Paused = "motore.in-pausa";
/// <summary>Start of the gradual start (first connection, last resolved verification), Unix milliseconds.</summary>
public const string RampStart = "motore.avvio-graduale-dal";
/// <summary>Planned start of the next session, Unix milliseconds: a restart never brings it earlier.</summary>
public const string NextSession = "motore.prossima-sessione";
/// <summary>Seed of the daily shifts of the active window: a restart does not redraw them.</summary>
public const string WindowSeed = "motore.fascia-seme";
/// <summary>Recipes suspended after repeated unrecognized formats: "Kind=ms;Kind=ms".</summary>
public const string SuspendedRecipes = "motore.ricette-sospese";
/// <summary>Consecutive failures per recipe: "Kind=n;Kind=n".</summary>
public const string RecipeFailures = "motore.ricette-errori-consecutivi";
/// <summary>Last completed Giro dei seguiti, Unix milliseconds (it read the stories bar of every followed account).</summary>
public const string LastSweep = "motore.ultimo-giro";
}
/// <summary>
/// Engine and caution settings chosen by Alberto (mockup 07): profile, «Su misura» values, gesture pace, gradual
/// start, active days.
/// </summary>
public sealed record EngineSettings
{
public static readonly IReadOnlySet<DayOfWeek> AllDays = new HashSet<DayOfWeek>(Enum.GetValues<DayOfWeek>());
public CautionProfileKind ProfileKind { get; init; } = CautionProfileKind.Prudent;
/// <summary>Values of the «Su misura» profile; used when <see cref="ProfileKind"/> is Custom.</summary>
public CautionProfile? Custom { get; init; }
public GesturePace Pace { get; init; } = GesturePace.Natural;
public bool GradualStart { get; init; } = true;
public IReadOnlySet<DayOfWeek> ActiveDays { get; init; } = AllDays;
/// <summary>The profile the engine applies: preset or custom values, with pace, gradual start and active days.</summary>
public CautionProfile EffectiveProfile
{
get
{
var basis = ProfileKind == CautionProfileKind.Custom
? (Custom ?? CautionProfile.Prudent) with { Kind = CautionProfileKind.Custom }
: CautionProfile.For(ProfileKind);
return basis with { Pace = Pace, GradualStart = GradualStart, ActiveDays = ActiveDays };
}
}
/// <summary>A modified value turns the profile into «Su misura» (spec §7.5).</summary>
public EngineSettings WithCustomValues(CautionProfile values) =>
this with { ProfileKind = CautionProfileKind.Custom, Custom = values with { Kind = CautionProfileKind.Custom } };
}
/// <summary>Reads and writes <see cref="EngineSettings"/> in the settings table.</summary>
public static class EngineSettingsStore
{
public static async Task<EngineSettings> LoadAsync(ISettingsStore store, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(store);
var all = await store.GetAllAsync(ct).ConfigureAwait(false);
var settings = new EngineSettings();
if (all.TryGetValue(EngineSettingKeys.Profile, out var kindText) && Enum.TryParse<CautionProfileKind>(kindText, out var kind))
{
settings = settings with { ProfileKind = kind };
}
if (all.TryGetValue(EngineSettingKeys.CustomProfile, out var customText))
{
settings = settings with { Custom = CautionProfileCodec.TryDecode(customText) };
}
if (all.TryGetValue(EngineSettingKeys.Pace, out var paceText) && Enum.TryParse<GesturePace>(paceText, out var pace))
{
settings = settings with { Pace = pace };
}
if (all.TryGetValue(EngineSettingKeys.GradualStart, out var gradualText) && bool.TryParse(gradualText, out var gradual))
{
settings = settings with { GradualStart = gradual };
}
if (all.TryGetValue(EngineSettingKeys.ActiveDays, out var daysText))
{
var days = ParseDays(daysText);
if (days.Count > 0)
{
settings = settings with { ActiveDays = days };
}
}
if (settings.ProfileKind == CautionProfileKind.Custom && settings.Custom is null)
{
settings = settings with { ProfileKind = CautionProfileKind.Prudent };
}
return settings;
}
/// <summary>Validates and stores the settings. Throws <see cref="ArgumentException"/> with Italian messages when a value is outside the limits of spec §7.5.</summary>
public static async Task SaveAsync(ISettingsStore store, EngineSettings settings, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(store);
ArgumentNullException.ThrowIfNull(settings);
var errors = CautionProfileRules.Validate(settings.EffectiveProfile);
if (settings.ActiveDays.Count == 0)
{
errors = [.. errors, "Serve almeno un giorno attivo."];
}
if (errors.Count > 0)
{
throw new ArgumentException(string.Join(" ", errors), nameof(settings));
}
await store.SetManyAsync(
new Dictionary<string, string?>
{
[EngineSettingKeys.Profile] = settings.ProfileKind.ToString(),
[EngineSettingKeys.CustomProfile] = settings.Custom is null ? null : CautionProfileCodec.Encode(settings.Custom),
[EngineSettingKeys.Pace] = settings.Pace.ToString(),
[EngineSettingKeys.GradualStart] = settings.GradualStart ? "true" : "false",
[EngineSettingKeys.ActiveDays] = FormatDays(settings.ActiveDays),
},
ct).ConfigureAwait(false);
}
internal static string FormatDays(IReadOnlySet<DayOfWeek> days) =>
string.Concat(days.OrderBy(d => (int)d).Select(d => ((int)d).ToString(CultureInfo.InvariantCulture)));
internal static HashSet<DayOfWeek> ParseDays(string text)
{
var days = new HashSet<DayOfWeek>();
foreach (var c in text)
{
if (c is >= '0' and <= '6')
{
days.Add((DayOfWeek)(c - '0'));
}
}
return days;
}
}
/// <summary>Limits of what the interface accepts for a profile (spec §7.5).</summary>
public static class CautionProfileRules
{
/// <summary>Largest daily jitter of the window that makes sense.</summary>
public static readonly TimeSpan MaxJitter = TimeSpan.FromHours(2);
public const int MaxRampUpDays = 30;
/// <summary>Length of the active window before the daily shift (crossing midnight when the end is not after the start).</summary>
public static TimeSpan WindowLength(TimeOnly start, TimeOnly end)
{
var length = end.ToTimeSpan() - start.ToTimeSpan();
return length <= TimeSpan.Zero ? length + TimeSpan.FromDays(1) : length;
}
/// <summary>Italian messages for every value outside the limits; empty when the profile is acceptable.</summary>
public static IReadOnlyList<string> Validate(CautionProfile profile)
{
ArgumentNullException.ThrowIfNull(profile);
var errors = new List<string>();
if (profile.PauseMin < CautionProfile.Limits.MinPause)
{
errors.Add("La pausa minima non può scendere sotto i 5 minuti.");
}
if (profile.PauseMax < profile.PauseMin)
{
errors.Add("La pausa massima deve essere almeno pari alla minima.");
}
if (profile.SessionMin < TimeSpan.FromMinutes(1))
{
errors.Add("Una sessione dura almeno 1 minuto.");
}
if (profile.SessionMax > CautionProfile.Limits.MaxSession)
{
errors.Add("Una sessione non può durare più di 30 minuti.");
}
if (profile.SessionMax < profile.SessionMin)
{
errors.Add("La durata massima di una sessione deve essere almeno pari alla minima.");
}
var window = WindowLength(profile.WindowStart, profile.WindowEnd);
if (window > CautionProfile.Limits.MaxWindow)
{
errors.Add("La fascia oraria non può superare le 20 ore.");
}
if (profile.WindowJitter < TimeSpan.Zero || profile.WindowJitter > MaxJitter)
{
errors.Add("Lo spostamento giornaliero della fascia va da 0 a 2 ore.");
}
foreach (var kind in Enum.GetValues<ActionKind>())
{
if (kind == ActionKind.DataDownload)
{
continue;
}
if (!profile.Budgets.TryGetValue(kind, out var budget))
{
errors.Add($"Manca il tetto delle {ItalianText.Category(kind)}.");
continue;
}
var max = CautionProfile.Limits.MaxBudget(kind);
if (budget.PerHour < 0 || budget.PerDay < 0)
{
errors.Add($"Il tetto delle {ItalianText.Category(kind)} non può essere negativo.");
}
else if (budget.PerHour > max.PerHour || budget.PerDay > max.PerDay)
{
errors.Add(
$"Il tetto delle {ItalianText.Category(kind)} non può superare il doppio di «Rapido» ({ItalianText.Number(max.PerHour)} all'ora, {ItalianText.Number(max.PerDay)} al giorno).");
}
}
if (profile.DataPerDayBytes < 0 || profile.DataPerDayBytes > CautionProfile.Limits.MaxDataPerDayBytes)
{
errors.Add($"I dati scaricati al giorno non possono superare il doppio di «Rapido» ({ItalianText.Bytes(CautionProfile.Limits.MaxDataPerDayBytes)}).");
}
var maxBackfill = CautionProfile.Fast.BackfillPostsPerAccountPerDay * 2;
if (profile.BackfillPostsPerAccountPerDay < 0 || profile.BackfillPostsPerAccountPerDay > maxBackfill)
{
errors.Add($"Lo storico per account al giorno non può superare il doppio di «Rapido» ({ItalianText.Number(maxBackfill)} post).");
}
if (profile.RampUpDays < 0 || profile.RampUpDays > MaxRampUpDays)
{
errors.Add("L'avvio graduale dura da 0 a 30 giorni.");
}
if (profile.ActiveDays.Count == 0)
{
errors.Add("Serve almeno un giorno attivo.");
}
return errors;
}
}
/// <summary>
/// Compact JSON of a «Su misura» profile. Written with <see cref="JsonNode"/> (no reflection serializer), so it keeps
/// working in a trimmed single-file build.
/// </summary>
public static class CautionProfileCodec
{
public static string Encode(CautionProfile profile)
{
ArgumentNullException.ThrowIfNull(profile);
var budgets = new JsonObject();
foreach (var (kind, budget) in profile.Budgets.OrderBy(b => b.Key))
{
budgets[kind.ToString()] = new JsonArray(budget.PerHour, budget.PerDay);
}
var json = new JsonObject
{
["windowStart"] = profile.WindowStart.ToString("HH:mm", CultureInfo.InvariantCulture),
["windowEnd"] = profile.WindowEnd.ToString("HH:mm", CultureInfo.InvariantCulture),
["jitterMin"] = profile.WindowJitter.TotalMinutes,
["sessionMinMin"] = profile.SessionMin.TotalMinutes,
["sessionMaxMin"] = profile.SessionMax.TotalMinutes,
["pauseMinMin"] = profile.PauseMin.TotalMinutes,
["pauseMaxMin"] = profile.PauseMax.TotalMinutes,
["budgets"] = budgets,
["dataPerDayBytes"] = profile.DataPerDayBytes,
["backfillPerAccount"] = profile.BackfillPostsPerAccountPerDay,
["rampUpDays"] = profile.RampUpDays,
};
return json.ToJsonString();
}
/// <summary>Null when the text is not a valid profile (it then falls back to «Prudente»).</summary>
public static CautionProfile? TryDecode(string? text)
{
if (string.IsNullOrWhiteSpace(text))
{
return null;
}
try
{
if (JsonNode.Parse(text) is not JsonObject json)
{
return null;
}
var budgets = new Dictionary<ActionKind, Budget>();
if (json["budgets"] is JsonObject budgetNode)
{
foreach (var (key, value) in budgetNode)
{
if (Enum.TryParse<ActionKind>(key, out var kind) && value is JsonArray { Count: 2 } pair)
{
budgets[kind] = new Budget(pair[0]!.GetValue<int>(), pair[1]!.GetValue<int>());
}
}
}
foreach (var kind in Enum.GetValues<ActionKind>())
{
if (kind != ActionKind.DataDownload && !budgets.ContainsKey(kind))
{
budgets[kind] = CautionProfile.Prudent.Budgets[kind];
}
}
if (json["windowStart"] is not JsonValue start || json["windowEnd"] is not JsonValue end)
{
return null;
}
return new CautionProfile
{
Kind = CautionProfileKind.Custom,
WindowStart = TimeOnly.ParseExact(start.GetValue<string>(), "HH:mm", CultureInfo.InvariantCulture),
WindowEnd = TimeOnly.ParseExact(end.GetValue<string>(), "HH:mm", CultureInfo.InvariantCulture),
WindowJitter = TimeSpan.FromMinutes(Number(json, "jitterMin")),
SessionMin = TimeSpan.FromMinutes(Number(json, "sessionMinMin")),
SessionMax = TimeSpan.FromMinutes(Number(json, "sessionMaxMin")),
PauseMin = TimeSpan.FromMinutes(Number(json, "pauseMinMin")),
PauseMax = TimeSpan.FromMinutes(Number(json, "pauseMaxMin")),
Budgets = budgets,
DataPerDayBytes = (long)Number(json, "dataPerDayBytes"),
BackfillPostsPerAccountPerDay = (int)Number(json, "backfillPerAccount"),
RampUpDays = (int)Number(json, "rampUpDays"),
};
}
catch (Exception ex) when (ex is JsonException or FormatException or InvalidOperationException or KeyNotFoundException)
{
return null;
}
}
private static double Number(JsonObject json, string key) =>
json[key] is JsonValue value ? value.GetValue<double>() : throw new KeyNotFoundException(key);
}
+410
View File
@@ -0,0 +1,410 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Pacing;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// The Governor (spec §7.4): the single point through which every engine action toward the site passes (rule 7).
/// For every request it checks, in order: breaker state, pause and Alberto using the browser, active window, session
/// in progress, hourly (rolling 60 minutes) and daily (local calendar day) budget of the category, minimum spacing from
/// the previous counted action, the account's own limits. Counts come from <c>action_log</c>, never from memory, so a
/// restart resets nothing. Granted actions are recorded there with session and account.
/// </summary>
/// <remarks>
/// <para>The minimum spacing is a pace, not a refusal: <see cref="RequestAsync"/> waits for it (on <see cref="IClock"/>)
/// and then grants; <see cref="EvaluateAsync"/> reports it as <see cref="DenialReason.MinimumSpacing"/>.</para>
/// <para>CDN downloads are not site actions: <see cref="ActionKind.DataDownload"/> only checks the daily byte budget, also
/// during a stop (spec §7.6: queued downloads may complete), and bytes are recorded with <see cref="RecordAsync"/>.</para>
/// </remarks>
public sealed class Governor : IGovernor, IDataBudget
{
private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
private readonly IFebeStorage _storage;
private readonly ICircuitBreaker _breaker;
private readonly EngineRuntime _runtime;
private readonly DayPlanner _planner;
private readonly IClock _clock;
private readonly EngineOptions _options;
private readonly EngineEvents? _events;
private readonly SemaphoreSlim _gate = new(1, 1);
private readonly Lock _noticeGate = new();
private readonly HashSet<(ActionKind, DateOnly)> _dailyNoticesSent = [];
public Governor(
IFebeStorage storage,
ICircuitBreaker breaker,
EngineRuntime runtime,
DayPlanner planner,
IClock clock,
EngineOptions? options = null,
EngineEvents? events = null)
{
_storage = storage ?? throw new ArgumentNullException(nameof(storage));
_breaker = breaker ?? throw new ArgumentNullException(nameof(breaker));
_runtime = runtime ?? throw new ArgumentNullException(nameof(runtime));
_planner = planner ?? throw new ArgumentNullException(nameof(planner));
_clock = clock ?? throw new ArgumentNullException(nameof(clock));
_options = options ?? EngineOptions.Default;
_events = events;
}
/// <summary>Raised for every refusal of <see cref="RequestAsync"/> (the monitor shows the last one).</summary>
public event EventHandler<Permit>? Denied;
/// <summary>Raised for every granted site action.</summary>
public event EventHandler<Permit>? Granted;
/// <summary>Minimum distance between two counted actions at the current gesture pace.</summary>
public TimeSpan MinimumSpacing => _options.MinimumSpacing * GesturePaceFactors.For(_runtime.Profile.Pace);
/// <summary>Budgets in force at <paramref name="now"/>: profile, gradual start and halved budgets, strongest reduction.</summary>
public EffectiveBudgets GetEffectiveBudgets(DateTimeOffset now) =>
BudgetLimits.Compute(_runtime.Profile, _runtime.RampStart, _breaker.State.HalvedBudgetsUntil, now);
public async Task<Permit> RequestAsync(ActionKind kind, long? accountId, CancellationToken ct)
{
if (kind == ActionKind.DataDownload)
{
return await EvaluateDataAsync(accountId, ct).ConfigureAwait(false);
}
await _gate.WaitAsync(ct).ConfigureAwait(false);
try
{
while (true)
{
var now = _clock.Now;
var permit = await EvaluateCoreAsync(kind, accountId, now, ct).ConfigureAwait(false);
if (permit.Reason == DenialReason.MinimumSpacing && permit.RetryAfter is { } retry)
{
// Spacing is a pace: wait for it, then look again (the state may have changed meanwhile).
await _clock.Delay(retry - now, ct).ConfigureAwait(false);
continue;
}
if (!permit.Granted)
{
Denied?.Invoke(this, permit);
await NoticeDailyBudgetAsync(permit, now, ct).ConfigureAwait(false);
return permit;
}
var session = _runtime.CurrentSession;
await _storage.ActionLog.AppendAsync(
new ActionLogRecord { At = now, Category = kind, AccountId = accountId, SessionId = session?.SessionId },
ct).ConfigureAwait(false);
session?.CountAction();
Granted?.Invoke(this, permit);
return permit;
}
}
finally
{
_gate.Release();
}
}
/// <summary>
/// What <see cref="RequestAsync"/> would answer now, without recording or waiting (spacing is reported as a
/// refusal with its retry time). The scheduler uses it to skip work whose budget is exhausted.
/// </summary>
public Task<Permit> EvaluateAsync(ActionKind kind, long? accountId, CancellationToken ct = default) =>
kind == ActionKind.DataDownload
? EvaluateDataAsync(accountId, ct)
: EvaluateCoreAsync(kind, accountId, _clock.Now, ct);
/// <summary>Budget checks only (no breaker, window, session or spacing): «is there room today for this?».</summary>
public async Task<Permit> EvaluateBudgetAsync(ActionKind kind, long? accountId, CancellationToken ct = default)
{
if (kind == ActionKind.DataDownload)
{
return await EvaluateDataAsync(accountId, ct).ConfigureAwait(false);
}
var now = _clock.Now;
return await CheckBudgetsAsync(kind, accountId, now, GetEffectiveBudgets(now), ct).ConfigureAwait(false)
?? Permit.Grant(kind, accountId);
}
/// <summary>
/// How many more actions of a category the budgets allow right now (the smaller of the hourly and daily rest).
/// For recipes that need room for several actions, e.g. «the budget must allow at least ten stories» (spec §6.3).
/// </summary>
public async Task<long> RemainingAsync(ActionKind kind, CancellationToken ct = default)
{
if (kind == ActionKind.DataDownload)
{
return await RemainingTodayAsync(ct).ConfigureAwait(false);
}
var now = _clock.Now;
var budget = GetEffectiveBudgets(now).Budgets[kind];
var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, _clock.LocalZone);
var tick = TimeSpan.FromMilliseconds(1);
var today = await _storage.ActionLog.SumAsync(kind, dayStart, dayEnd, ct: ct).ConfigureAwait(false);
var lastHour = await _storage.ActionLog.SumAsync(kind, now - Hour + tick, now + tick, ct: ct).ConfigureAwait(false);
return Math.Max(0, Math.Min(budget.PerDay - today, budget.PerHour - lastHour));
}
/// <summary>Use of every category with the limits in force (spec §7.4, §7.9).</summary>
public async Task<IReadOnlyList<BudgetStatus>> GetBudgetStatusAsync(CancellationToken ct = default)
{
var now = _clock.Now;
var budgets = GetEffectiveBudgets(now);
var usage = await _storage.ActionLog.GetUsageAsync(now, _clock.LocalZone, ct).ConfigureAwait(false);
return [.. Enum.GetValues<ActionKind>().Select(kind =>
{
var used = usage.TryGetValue(kind, out var u) ? u : default;
return kind == ActionKind.DataDownload
? new BudgetStatus(kind, used.Today, budgets.DataPerDayBytes, null, null)
: new BudgetStatus(kind, used.Today, budgets.Budgets[kind].PerDay, used.LastHour, budgets.Budgets[kind].PerHour);
})];
}
public async Task<long> RemainingTodayAsync(CancellationToken ct)
{
var now = _clock.Now;
var (start, end) = LocalCalendar.DayBounds(now, _clock.LocalZone);
var used = await _storage.ActionLog.SumAsync(ActionKind.DataDownload, start, end, ct: ct).ConfigureAwait(false);
return Math.Max(0, GetEffectiveBudgets(now).DataPerDayBytes - used);
}
public async Task RecordAsync(long bytes, long? accountId, CancellationToken ct)
{
ArgumentOutOfRangeException.ThrowIfNegative(bytes);
if (bytes == 0)
{
return;
}
await _storage.ActionLog.AppendAsync(
new ActionLogRecord
{
At = _clock.Now,
Category = ActionKind.DataDownload,
AccountId = accountId,
SessionId = _runtime.CurrentSession?.SessionId,
Amount = bytes,
},
ct).ConfigureAwait(false);
}
private async Task<Permit> EvaluateDataAsync(long? accountId, CancellationToken ct)
{
var remaining = await RemainingTodayAsync(ct).ConfigureAwait(false);
if (remaining > 0)
{
return Permit.Grant(ActionKind.DataDownload, accountId);
}
var now = _clock.Now;
var limit = GetEffectiveBudgets(now).DataPerDayBytes;
return Permit.Deny(
ActionKind.DataDownload,
accountId,
DenialReason.DailyBudgetReached,
$"Raggiunto il tetto giornaliero dei dati scaricati ({ItalianText.Bytes(limit)}): gli scaricamenti riprendono domani.",
LocalCalendar.DayBounds(now, _clock.LocalZone).End);
}
private async Task<Permit> EvaluateCoreAsync(ActionKind kind, long? accountId, DateTimeOffset now, CancellationToken ct)
{
var zone = _clock.LocalZone;
// 1. Breaker.
var breaker = _breaker.State;
if (!breaker.AllowsSiteActions)
{
return Permit.Deny(kind, accountId, DenialReason.BreakerOpen, BreakerMessage(breaker, now, zone), breaker.Until);
}
// Pause and Alberto at the browser: the engine does not act.
if (_runtime.IsPaused)
{
return Permit.Deny(kind, accountId, DenialReason.Paused, "Febe è in pausa: premi «Riprendi» per ripartire.");
}
if (_runtime.UserIsDriving)
{
return Permit.Deny(kind, accountId, DenialReason.UserIsDriving, "Stai usando il browser di Febe: il motore aspetta che tu abbia finito.");
}
// 2. Active window; the only exception is a «Controlla ora» confirmed outside it, for that account only.
var session = _runtime.CurrentSession;
var manualOutside = session?.OutsideWindowAccountId is { } manualAccount && accountId == manualAccount;
if (!manualOutside)
{
var window = await _planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
if (window is null)
{
var next = await _planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
var when = next is null ? "nei giorni attivi" : ItalianText.Around(next.Start, now, zone);
return Permit.Deny(kind, accountId, DenialReason.OutsideActiveWindow, $"Fuori dalla fascia oraria: Febe riprende {when}.", next?.Start);
}
}
// 3. Session in progress.
if (session is null)
{
return Permit.Deny(kind, accountId, DenialReason.NoSession, "Nessuna sessione in corso: le azioni verso il sito partono solo dentro una sessione.");
}
// 4. Budgets of the category, then 5. spacing, then 6. the account's own limits.
var budgets = GetEffectiveBudgets(now);
var denial = await CheckCategoryBudgetsAsync(kind, accountId, now, budgets, ct).ConfigureAwait(false);
if (denial is not null)
{
return denial;
}
var last = await _storage.ActionLog.GetLastActionAtAsync(null, ct).ConfigureAwait(false);
var spacing = MinimumSpacing;
if (last is { } previous && now - previous < spacing)
{
return Permit.Deny(
kind,
accountId,
DenialReason.MinimumSpacing,
$"Troppo vicino all'azione precedente: fra due azioni passano almeno {ItalianText.Decimal(spacing.TotalSeconds, 1)} secondi.",
previous + spacing);
}
return await CheckAccountAsync(kind, accountId, now, budgets, session, ct).ConfigureAwait(false)
?? Permit.Grant(kind, accountId);
}
private async Task<Permit?> CheckBudgetsAsync(ActionKind kind, long? accountId, DateTimeOffset now, EffectiveBudgets budgets, CancellationToken ct) =>
await CheckCategoryBudgetsAsync(kind, accountId, now, budgets, ct).ConfigureAwait(false)
?? await CheckAccountAsync(kind, accountId, now, budgets, _runtime.CurrentSession, ct).ConfigureAwait(false);
private async Task<Permit?> CheckCategoryBudgetsAsync(ActionKind kind, long? accountId, DateTimeOffset now, EffectiveBudgets budgets, CancellationToken ct)
{
var zone = _clock.LocalZone;
var budget = budgets.Budgets[kind];
var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, zone);
var today = await _storage.ActionLog.SumAsync(kind, dayStart, dayEnd, ct: ct).ConfigureAwait(false);
var tick = TimeSpan.FromMilliseconds(1);
// Rolling window (now − 60 min, now], in the milliseconds of the database.
var lastHour = await _storage.ActionLog.SumAsync(kind, now - Hour + tick, now + tick, ct: ct).ConfigureAwait(false);
var used = new BudgetUsage(lastHour, today);
if (used.Today + 1 > budget.PerDay)
{
var tomorrow = LocalCalendar.DayBounds(now, zone).End;
var next = await _planner.GetNextWindowAsync(tomorrow, ct).ConfigureAwait(false);
var retry = next is null || next.Start < tomorrow ? tomorrow : next.Start;
return Permit.Deny(
kind,
accountId,
DenialReason.DailyBudgetReached,
$"Raggiunto il tetto giornaliero delle {ItalianText.Category(kind)} ({ItalianText.Number(budget.PerDay)} al giorno): la categoria riprende domani.",
retry);
}
if (used.LastHour + 1 > budget.PerHour)
{
var retry = await HourlyRetryAsync(kind, now, budget.PerHour, ct).ConfigureAwait(false);
return Permit.Deny(
kind,
accountId,
DenialReason.HourlyBudgetReached,
$"Raggiunto il tetto orario delle {ItalianText.Category(kind)} ({ItalianText.Number(budget.PerHour)} all'ora): la categoria riprende {ItalianText.Around(retry, now, zone)}.",
retry);
}
return null;
}
private async Task<Permit?> CheckAccountAsync(
ActionKind kind,
long? accountId,
DateTimeOffset now,
EffectiveBudgets budgets,
SessionContext? session,
CancellationToken ct)
{
if (accountId is not { } id)
{
return null;
}
var account = await _storage.Accounts.GetAsync(id, ct).ConfigureAwait(false);
if (account is null)
{
return Permit.Deny(kind, accountId, DenialReason.AccountNotContactable, "Questo account non c'è più nell'elenco di Febe.");
}
var manual = session?.ManualAccountId == id;
if (!CheckPolicy.IsContactable(account) && !(manual && CheckPolicy.AllowsManualCheck(account)))
{
return Permit.Deny(kind, accountId, DenialReason.AccountNotContactable, NotContactableMessage(account));
}
if (kind == ActionKind.BackfillPage)
{
var zone = _clock.LocalZone;
var limit = Math.Min(account.Limits.BackfillPostsPerDay, budgets.BackfillPostsPerAccountPerDay);
var (dayStart, dayEnd) = LocalCalendar.DayBounds(now, zone);
var today = await _storage.Entries.CountDiscoveredAsync(id, EntryKind.Post, dayStart, dayEnd, ct).ConfigureAwait(false);
if (today >= limit)
{
return Permit.Deny(
kind,
accountId,
DenialReason.AccountLimitReached,
$"Raggiunto il limite di storico di {ItalianText.Handle(account.Username)} per oggi ({ItalianText.Number(limit)} post): riprende domani.",
dayEnd);
}
}
return null;
}
/// <summary>When the oldest action that keeps the rolling hour full leaves the window.</summary>
private async Task<DateTimeOffset> HourlyRetryAsync(ActionKind kind, DateTimeOffset now, int perHour, CancellationToken ct)
{
var recent = await _storage.ActionLog.ListAsync(now - Hour, now.AddMilliseconds(1), ct).ConfigureAwait(false);
var times = recent.Where(r => r.Category == kind && r.At > now - Hour).Select(r => r.At).OrderBy(t => t).ToList();
var excess = times.Count - perHour;
return excess >= 0 && excess < times.Count ? times[excess] + Hour : now + TimeSpan.FromMinutes(1);
}
private async Task NoticeDailyBudgetAsync(Permit permit, DateTimeOffset now, CancellationToken ct)
{
if (_events is null || permit.Reason != DenialReason.DailyBudgetReached)
{
return;
}
var day = LocalCalendar.Today(now, _clock.LocalZone);
lock (_noticeGate)
{
if (!_dailyNoticesSent.Add((permit.Kind, day)))
{
return;
}
}
await _events.WriteAsync(EventSeverity.Info, EngineEventCodes.BudgetReached, permit.Message ?? string.Empty, ct: ct).ConfigureAwait(false);
}
internal static string BreakerMessage(BreakerState state, DateTimeOffset now, TimeZoneInfo zone) => state.Status switch
{
BreakerStatus.Throttled when state.Until is { } until =>
$"Instagram ha chiesto di rallentare: Febe è fermo fino {ItalianText.AtDay(until, now, zone)}.",
BreakerStatus.Challenge => "Instagram chiede una verifica: Febe è fermo finché non la completi nel browser e premi «Riprendi».",
BreakerStatus.Disconnected => "La sessione di Instagram è chiusa: Febe è fermo finché non accedi di nuovo nel browser e premi «Riprendi».",
_ => "Febe è fermo.",
};
private static string NotContactableMessage(Account account) => account.State switch
{
AccountState.ArchiveOnly => $"{ItalianText.Handle(account.Username)} è «Solo archivio»: Febe non lo contatta.",
AccountState.Paused => $"{ItalianText.Handle(account.Username)} è in pausa: Febe non lo controlla.",
AccountState.Unreachable => $"{ItalianText.Handle(account.Username)} non è raggiungibile: Febe non lo contatta.",
_ => $"Febe non contatta {ItalianText.Handle(account.Username)}.",
};
}
+237
View File
@@ -0,0 +1,237 @@
using System.Globalization;
using System.Text;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Engine;
/// <summary>
/// Italian wording used by the engine for events, denials and the monitor (spec §10.4): dot for thousands, comma for
/// decimals, «verso le» for future engine times. Independent of the process culture, so it reads the same in Docker
/// (invariant globalization) and on Windows.
/// </summary>
public static class ItalianText
{
private static readonly string[] Months =
[
"gennaio", "febbraio", "marzo", "aprile", "maggio", "giugno",
"luglio", "agosto", "settembre", "ottobre", "novembre", "dicembre",
];
private static readonly string[] Weekdays = ["domenica", "lunedì", "martedì", "mercoledì", "giovedì", "venerdì", "sabato"];
/// <summary>Whole number with dots for thousands: 7.682.</summary>
public static string Number(long value)
{
var digits = Math.Abs(value).ToString(CultureInfo.InvariantCulture);
var builder = new StringBuilder();
if (value < 0)
{
builder.Append('-');
}
for (var i = 0; i < digits.Length; i++)
{
if (i > 0 && (digits.Length - i) % 3 == 0)
{
builder.Append('.');
}
builder.Append(digits[i]);
}
return builder.ToString();
}
/// <summary>Decimal number with a comma: 1,3. Trailing zeros of the decimals are kept only when asked.</summary>
public static string Decimal(double value, int decimals = 1, bool keepZeros = false)
{
var rounded = Math.Round(value, decimals, MidpointRounding.AwayFromZero);
var whole = (long)Math.Truncate(rounded);
var fraction = Math.Abs(rounded - whole);
var text = Number(whole);
if (whole == 0 && rounded < 0)
{
text = "-0";
}
if (decimals <= 0)
{
return text;
}
var fractionDigits = ((long)Math.Round(fraction * Math.Pow(10, decimals))).ToString(CultureInfo.InvariantCulture).PadLeft(decimals, '0');
if (!keepZeros)
{
fractionDigits = fractionDigits.TrimEnd('0');
}
return fractionDigits.Length == 0 ? text : text + "," + fractionDigits;
}
/// <summary>Byte amount: «850 MB», «1,3 GB».</summary>
public static string Bytes(long bytes)
{
const double KB = 1024;
const double MB = KB * 1024;
const double GB = MB * 1024;
return bytes switch
{
>= (long)GB => Decimal(bytes / GB, 1) + " GB",
>= (long)MB => Decimal(bytes / MB, bytes >= 100 * MB ? 0 : 1) + " MB",
>= (long)KB => Decimal(bytes / KB, 0) + " kB",
_ => Number(bytes) + " byte",
};
}
/// <summary>Local clock time without a leading zero on the hour: «7:42», «15:30».</summary>
public static string Clock(DateTimeOffset instant, TimeZoneInfo zone)
{
var local = LocalCalendar.ToLocal(instant, zone);
return local.Hour.ToString(CultureInfo.InvariantCulture) + ":" + local.Minute.ToString("00", CultureInfo.InvariantCulture);
}
/// <summary>«alle 17:32», «all'1:05».</summary>
public static string At(DateTimeOffset instant, TimeZoneInfo zone) =>
(LocalCalendar.ToLocal(instant, zone).Hour == 1 ? "all'" : "alle ") + Clock(instant, zone);
/// <summary>«dalle 16:32», «dall'1:05».</summary>
public static string Since(DateTimeOffset instant, TimeZoneInfo zone) =>
(LocalCalendar.ToLocal(instant, zone).Hour == 1 ? "dall'" : "dalle ") + Clock(instant, zone);
/// <summary>
/// A future engine time, always indicative (spec §7.9): «verso le 15:30», «domani verso le 7:42»,
/// «giovedì verso le 7:42», «il 21 ottobre verso le 7:42».
/// </summary>
public static string Around(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
{
var hour = LocalCalendar.ToLocal(instant, zone).Hour;
var time = (hour == 1 ? "verso l'" : "verso le ") + Clock(instant, zone);
var prefix = DayPrefix(instant, now, zone);
return prefix.Length == 0 ? time : prefix + " " + time;
}
/// <summary>«alle 17:32», «domani alle 7:42»: a fixed future time (e.g. the end of a throttle stop).</summary>
public static string AtDay(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
{
var prefix = DayPrefix(instant, now, zone);
var at = At(instant, zone);
return prefix.Length == 0 ? at : prefix + " " + at;
}
/// <summary>«13 ottobre».</summary>
public static string Day(DateOnly day) => day.Day.ToString(CultureInfo.InvariantCulture) + " " + Months[day.Month - 1];
/// <summary>«lunedì 13 ottobre».</summary>
public static string DayWithWeekday(DateOnly day) => Weekdays[(int)day.DayOfWeek] + " " + Day(day);
/// <summary>A duration in words: «45 minuti», «1 ora e 20 minuti», «2 giorni e 3 ore», «30 secondi».</summary>
public static string Duration(TimeSpan span)
{
if (span < TimeSpan.Zero)
{
span = TimeSpan.Zero;
}
if (span < TimeSpan.FromMinutes(1))
{
var seconds = (long)Math.Round(span.TotalSeconds);
return seconds == 1 ? "1 secondo" : Number(seconds) + " secondi";
}
if (span < TimeSpan.FromHours(1))
{
return Minutes((long)Math.Round(span.TotalMinutes));
}
if (span < TimeSpan.FromDays(2))
{
var totalMinutes = (long)Math.Round(span.TotalMinutes);
var hours = totalMinutes / 60;
var minutes = totalMinutes % 60;
var text = hours == 1 ? "1 ora" : Number(hours) + " ore";
return minutes == 0 ? text : text + " e " + Minutes(minutes);
}
var totalHours = (long)Math.Round(span.TotalHours);
var days = totalHours / 24;
var restHours = totalHours % 24;
var dayText = days == 1 ? "1 giorno" : Number(days) + " giorni";
return restHours == 0 ? dayText : dayText + " e " + (restHours == 1 ? "1 ora" : Number(restHours) + " ore");
}
/// <summary>An interval of a check («ogni 3 ore», «ogni 75 minuti», «ogni giorno»).</summary>
public static string Every(TimeSpan interval)
{
if (interval >= TimeSpan.FromHours(23.5) && interval <= TimeSpan.FromHours(24.5))
{
return "ogni giorno";
}
if (interval < TimeSpan.FromHours(2) && interval.TotalMinutes % 60 != 0)
{
return "ogni " + Minutes((long)Math.Round(interval.TotalMinutes));
}
var hours = interval.TotalHours;
if (Math.Abs(hours - Math.Round(hours)) < 0.05)
{
var whole = (long)Math.Round(hours);
return whole == 1 ? "ogni ora" : "ogni " + Number(whole) + " ore";
}
return "ogni " + Decimal(hours, 1) + " ore";
}
/// <summary>Italian name of a budget category, as in the table of spec §7.5.</summary>
public static string Category(ActionKind kind) => kind switch
{
ActionKind.Home => "aperture della home",
ActionKind.ProfileOpen => "profili aperti",
ActionKind.StoryView => "storie viste",
ActionKind.BackfillPage => "pagine di storico",
ActionKind.SinglePost => "post singoli",
ActionKind.FollowingListPage => "pagine dell'elenco dei seguiti",
ActionKind.DataDownload => "dati scaricati",
_ => kind.ToString(),
};
/// <summary>Category name with a capital initial, for labels: «Profili aperti».</summary>
public static string CategoryLabel(ActionKind kind) => Capitalize(Category(kind));
/// <summary>Italian name of a caution profile: «Prudente».</summary>
public static string Profile(CautionProfileKind kind) => kind switch
{
CautionProfileKind.Prudent => "Prudente",
CautionProfileKind.Balanced => "Equilibrato",
CautionProfileKind.Fast => "Rapido",
CautionProfileKind.Custom => "Su misura",
_ => kind.ToString(),
};
/// <summary>«@marta.demo».</summary>
public static string Handle(string? username) => string.IsNullOrWhiteSpace(username) ? "un account" : "@" + username.TrimStart('@');
/// <summary>Count with its noun: «1 storia nuova», «3 storie nuove».</summary>
public static string Count(long count, string singular, string plural) =>
count == 1 ? "1 " + singular : Number(count) + " " + plural;
public static string Capitalize(string text) =>
string.IsNullOrEmpty(text) ? text : char.ToUpperInvariant(text[0]) + text[1..];
private static string Minutes(long minutes) => minutes == 1 ? "1 minuto" : Number(minutes) + " minuti";
private static string DayPrefix(DateTimeOffset instant, DateTimeOffset now, TimeZoneInfo zone)
{
var day = LocalCalendar.Today(instant, zone);
var today = LocalCalendar.Today(now, zone);
var difference = day.DayNumber - today.DayNumber;
return difference switch
{
<= 0 => string.Empty,
1 => "domani",
< 7 => Weekdays[(int)day.DayOfWeek],
_ => "il " + Day(day),
};
}
}
+536
View File
@@ -0,0 +1,536 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// Builds the snapshot of the engine for the interface. Reads only: it never draws from the engine's random source,
/// so watching the engine does not change what it does. Future times are indicative and written «verso le».
/// </summary>
public sealed class EngineMonitor : IEngineMonitor
{
private static readonly ActionKind[] Main = [ActionKind.ProfileOpen, ActionKind.StoryView, ActionKind.BackfillPage, ActionKind.DataDownload];
private readonly EngineServices _s;
private readonly EngineHost _host;
internal EngineMonitor(EngineServices services, EngineHost host)
{
_s = services;
_host = host;
}
public IAsyncEnumerable<EngineNotification> SubscribeAsync(CancellationToken ct = default) => _s.Events.SubscribeAsync(ct);
public async Task<EngineSnapshot> GetSnapshotAsync(CancellationToken ct = default)
{
var now = _s.Clock.Now;
var zone = _s.Clock.LocalZone;
var runtime = _s.Runtime;
var breaker = _s.Breaker.State;
var profile = runtime.Profile;
var window = await _s.Planner.GetWindowAtAsync(now, ct).ConfigureAwait(false);
var nextWindow = window ?? await _s.Planner.GetNextWindowAsync(now, ct).ConfigureAwait(false);
var session = runtime.CurrentSession;
var mode = ModeOf(runtime, breaker, session, window);
var resumes = ResumesAround(mode, runtime, breaker, nextWindow, now);
var (headline, details, sidebar) = Texts(mode, runtime, breaker, session, resumes, now, zone);
var budgets = _s.Governor.GetEffectiveBudgets(now);
var statuses = await _s.Governor.GetBudgetStatusAsync(ct).ConfigureAwait(false);
var views = statuses.Select(b => View(b, breaker, now, zone)).ToList();
var accounts = (await _s.Storage.Accounts.ListAsync(ct).ConfigureAwait(false)).ToDictionary(a => a.Id);
return new EngineSnapshot
{
At = now,
Mode = mode,
Headline = headline,
Details = details,
SidebarLine = sidebar,
ResumesAround = resumes,
Banner = Banner(breaker, now, zone),
Profile = profile.Kind,
ProfileLine = $"Profilo «{ItalianText.Profile(profile.Kind)}»",
ReductionNote = ReductionNote(budgets, now, zone),
Today = await StripAsync(now, zone, session, runtime, profile, accounts, ct).ConfigureAwait(false),
MainBudgets = [.. Main.Select(k => views.First(v => v.Kind == k))],
AllBudgets = views,
ProfilesOpenedToday = views.First(v => v.Kind == ActionKind.ProfileOpen),
Queue = await QueueAsync(now, zone, mode, session, runtime, accounts, ct).ConfigureAwait(false),
RecentActions = await RecentAsync(now, zone, ct).ConfigureAwait(false),
SuspendedRecipes = [.. _host.SuspendedRecipes.Select(r => new SuspendedRecipeView(r.Key, ItalianText.Capitalize(SessionComposer.RecipeName(r.Key)), r.Value))],
Breaker = breaker,
};
}
private static EngineMode ModeOf(EngineRuntime runtime, BreakerState breaker, SessionContext? session, ActiveWindow? window)
{
if (breaker.Status == BreakerStatus.Challenge)
{
return EngineMode.StoppedForVerification;
}
if (breaker.Status == BreakerStatus.Disconnected)
{
return EngineMode.Disconnected;
}
if (runtime.IsConnected == false)
{
return EngineMode.NotConnected;
}
if (breaker.Status == BreakerStatus.Throttled)
{
return EngineMode.Throttled;
}
if (runtime.IsPaused)
{
return EngineMode.Paused;
}
if (runtime.UserIsDriving)
{
return EngineMode.UserDriving;
}
if (!runtime.IsRunning)
{
return EngineMode.Off;
}
if (session is not null)
{
return EngineMode.InSession;
}
if (window is null)
{
return EngineMode.OutsideWindow;
}
return runtime.HadSessionSinceStart ? EngineMode.Resting : EngineMode.Starting;
}
private static DateTimeOffset? ResumesAround(EngineMode mode, EngineRuntime runtime, BreakerState breaker, ActiveWindow? nextWindow, DateTimeOffset now)
{
switch (mode)
{
case EngineMode.Throttled:
return breaker.Until;
case EngineMode.Resting or EngineMode.Starting or EngineMode.OutsideWindow:
var next = runtime.NextSessionAt;
if (mode == EngineMode.OutsideWindow && nextWindow is not null && (next is null || next < nextWindow.Start))
{
next = nextWindow.Start;
}
return next is { } n && n < now ? now : next;
default:
return null;
}
}
private static (string Headline, IReadOnlyList<string> Details, string Sidebar) Texts(
EngineMode mode,
EngineRuntime runtime,
BreakerState breaker,
SessionContext? session,
DateTimeOffset? resumes,
DateTimeOffset now,
TimeZoneInfo zone)
{
var around = resumes is { } r ? ItalianText.Around(r, now, zone) : null;
switch (mode)
{
case EngineMode.InSession when session is not null:
{
var activity = runtime.Activity ?? "Sto per iniziare il prossimo passo";
var left = session.PlannedEnd - now;
var timing = left > TimeSpan.FromMinutes(1)
? $"Iniziata {ItalianText.At(session.StartedAt, zone)}, ancora {ItalianText.Duration(left)} circa."
: $"Iniziata {ItalianText.At(session.StartedAt, zone)}, sta per finire.";
if (session.OutsideWindowAccountId is not null)
{
timing += " Controllo fuori fascia confermato da te.";
}
var sidebar = runtime.Activity is { } a && a.StartsWith("Sto ", StringComparison.Ordinal) ? ItalianText.Capitalize(a[4..]) : "In sessione";
return ("In sessione", [activity, timing], sidebar);
}
case EngineMode.Resting:
return ("In ascolto", [$"Riprende {around ?? "a breve"}.", "Fra una sessione e l'altra il browser resta sulla pagina vuota."], $"Riprende {around ?? "a breve"}");
case EngineMode.Starting:
return ("In avvio", [$"Prima sessione {around ?? "a breve"}."], $"Prima sessione {around ?? "a breve"}");
case EngineMode.OutsideWindow:
return ("Fuori fascia", ["Fuori dalla fascia oraria Febe non apre nulla da solo.", $"Riprende {around ?? "nei giorni attivi"}."], $"Riprende {around ?? "nei giorni attivi"}");
case EngineMode.Paused:
return ("In pausa", ["Messo in pausa da te.", "Premi «Riprendi» per ripartire."], "In pausa");
case EngineMode.Throttled:
{
var until = breaker.Until is { } u ? ItalianText.Around(u, now, zone) : "più tardi";
return ("Fermo per rallentamento", [$"Instagram ha chiesto di rallentare: riprende {until}.", "Poi i tetti restano dimezzati per 48 ore."], $"Riprende {until}");
}
case EngineMode.StoppedForVerification:
{
var since = breaker.LastSignal is { } s ? $"Fermo {ItalianText.Since(s.At, zone)}. " : string.Empty;
return ("Fermo", ["In attesa che tu completi la verifica", since + "Nessun nuovo tentativo finché non premi «Riprendi»."], "Serve il tuo intervento");
}
case EngineMode.Disconnected:
return ("Scollegato", ["La sessione di Instagram non c'è più.", "Apri il browser, accedi di nuovo, poi premi «Riprendi». Febe non prova a rientrare da solo."], "Accedi di nuovo");
case EngineMode.NotConnected:
return ("Non collegato", ["Il browser di Febe non ha una sessione di Instagram.", "Collegalo dalla pagina Collegamento."], "Non collegato");
case EngineMode.UserDriving:
return ("Stai usando il browser", ["Il motore resta fermo finché non hai finito."], "Stai usando il browser");
default:
return ("Motore spento", ["Il motore non è in funzione."], "Motore spento");
}
}
private static StopBanner? Banner(BreakerState breaker, DateTimeOffset now, TimeZoneInfo zone)
{
var at = breaker.LastSignal is { } s ? ItalianText.At(s.At, zone) : null;
return breaker.Status switch
{
BreakerStatus.Challenge => new StopBanner(
BannerLevel.Error,
"Instagram chiede una verifica",
$"Ho fermato tutto{(at is null ? string.Empty : " " + at)} e non riparto da solo. Apri il browser, completa la verifica a mano, poi premi «Riprendi».",
true),
BreakerStatus.Disconnected => new StopBanner(
BannerLevel.Error,
"Instagram ha chiuso la sessione",
$"Ho fermato tutto{(at is null ? string.Empty : " " + at)} e non provo a rientrare. Apri il browser, accedi a mano, poi premi «Riprendi».",
true),
BreakerStatus.Throttled when breaker.Until is { } until => new StopBanner(
BannerLevel.Warning,
"Instagram ha chiesto di rallentare",
$"Ho chiuso la sessione e mi fermo fino {ItalianText.AtDay(until, now, zone)}; poi riparto da solo con i tetti dimezzati per 48 ore.",
false),
_ => null,
};
}
private static string? ReductionNote(EffectiveBudgets budgets, DateTimeOffset now, TimeZoneInfo zone) => budgets.Reduction switch
{
BudgetReduction.GradualStart =>
$"Avvio graduale: tetti al {ItalianText.Number((long)Math.Round(budgets.Factor * 100))}%"
+ (budgets.Until is { } u ? $", pieni {ItalianText.Around(u, now, zone)}" : string.Empty) + ".",
BudgetReduction.HalvedAfterThrottle =>
"Tetti dimezzati dopo un rallentamento" + (budgets.Until is { } h ? $" fino {ItalianText.AtDay(h, now, zone)}" : string.Empty) + ".",
_ => null,
};
internal static BudgetView View(BudgetStatus status, BreakerState breaker, DateTimeOffset now, TimeZoneInfo zone)
{
var data = status.Kind == ActionKind.DataDownload;
var usedText = data ? ItalianText.Bytes(status.UsedToday) : ItalianText.Number(status.UsedToday);
var limitText = "di " + (data ? ItalianText.Bytes(status.LimitToday) : ItalianText.Number(status.LimitToday));
string note;
if (!breaker.AllowsSiteActions && !data)
{
note = breaker.LastSignal is { } s ? "Fermo " + ItalianText.Since(s.At, zone) : "Fermo";
}
else if (status.DailyReached)
{
note = "Tetto di oggi raggiunto: riprende domani";
}
else if (status.HourlyReached)
{
note = "Tetto orario raggiunto: riprende entro un'ora";
}
else if (status.DailyRatio >= BudgetStatus.AmberThreshold)
{
note = "Quasi al limite per oggi";
}
else if (status.HourlyRatio >= BudgetStatus.AmberThreshold)
{
note = "Quasi al limite di quest'ora";
}
else if (data)
{
note = "Restano " + ItalianText.Bytes(Math.Max(0, status.LimitToday - status.UsedToday));
}
else
{
note = $"In questa ora {ItalianText.Number(status.UsedLastHour ?? 0)} di {ItalianText.Number(status.LimitPerHour ?? 0)}";
}
return new BudgetView(
status.Kind,
ItalianText.CategoryLabel(status.Kind),
status.UsedToday,
status.LimitToday,
status.UsedLastHour,
status.LimitPerHour,
status.IsAmber,
Math.Clamp(status.DailyRatio, 0, 1),
usedText,
limitText,
note);
}
private async Task<DayStrip> StripAsync(
DateTimeOffset now,
TimeZoneInfo zone,
SessionContext? current,
EngineRuntime runtime,
CautionProfile profile,
Dictionary<long, Account> accounts,
CancellationToken ct)
{
var day = LocalCalendar.Today(now, zone);
var (dayStart, dayEnd) = LocalCalendar.DayBounds(day, zone);
var spans = new List<StripSpan>();
// Night and inactive hours: everything of the day outside the windows of yesterday and today.
var windows = new List<ActiveWindow>();
foreach (var d in new[] { day.AddDays(-1), day })
{
if (await _s.Planner.GetWindowAsync(d, ct).ConfigureAwait(false) is { } w && w.End > dayStart && w.Start < dayEnd)
{
windows.Add(w);
}
}
var cursor = dayStart;
foreach (var w in windows.OrderBy(w => w.Start))
{
var start = w.Start < dayStart ? dayStart : w.Start;
if (start > cursor)
{
spans.Add(new StripSpan(StripSpanKind.OutsideWindow, cursor, start, false, "Fuori fascia"));
}
cursor = w.End > cursor ? w.End : cursor;
}
if (cursor < dayEnd)
{
spans.Add(new StripSpan(StripSpanKind.OutsideWindow, cursor, dayEnd, false, "Fuori fascia"));
}
// Sessions of the day and the rests between them.
var sessions = await _s.Storage.Sessions.ListAsync(dayStart, dayEnd, ct).ConfigureAwait(false);
DateTimeOffset? previousEnd = null;
var activeMinutes = 0.0;
foreach (var session in sessions)
{
var end = session.EndedAt ?? now;
var inProgress = session.EndedAt is null && current?.SessionId == session.Id;
if (previousEnd is { } rest && session.StartedAt > rest)
{
spans.Add(new StripSpan(StripSpanKind.Rest, rest, session.StartedAt, false, "Pausa"));
}
spans.Add(new StripSpan(
inProgress ? StripSpanKind.CurrentSession : StripSpanKind.Session,
session.StartedAt,
end,
false,
(inProgress ? "Sessione in corso dalle " : "Sessione dalle ") + ItalianText.Clock(session.StartedAt, zone)
+ (inProgress ? string.Empty : " alle " + ItalianText.Clock(end, zone))));
activeMinutes += ((end < dayEnd ? end : dayEnd) - (session.StartedAt > dayStart ? session.StartedAt : dayStart)).TotalMinutes;
previousEnd = end;
}
if (current is null && previousEnd is { } lastEnd && lastEnd < now && windows.Any(w => w.Contains(now)))
{
spans.Add(new StripSpan(StripSpanKind.Rest, lastEnd, now, false, "Pausa"));
}
// Stops.
var throttles = 0;
foreach (var incident in await _s.Storage.Incidents.ListAsync(dayStart - TimeSpan.FromDays(2), dayEnd, ct).ConfigureAwait(false))
{
var end = incident.ResolvedAt ?? (incident.Level == SignalLevel.Throttle ? incident.StoppedUntil ?? now : now);
if (end <= dayStart || incident.At >= dayEnd)
{
continue;
}
if (incident.Level == SignalLevel.Throttle)
{
if (incident.At >= dayStart)
{
throttles++;
}
spans.Add(new StripSpan(StripSpanKind.Throttle, incident.At, end, incident.ResolvedAt is null, "Fermo per rallentamento"));
}
else
{
spans.Add(new StripSpan(
StripSpanKind.Stop,
incident.At,
incident.ResolvedAt ?? now,
false,
incident.Level == SignalLevel.Challenge ? "Fermo per una verifica" : "Fermo per disconnessione"));
}
}
// Planned sessions, indicative: median length and median pause from the next planned start.
if (current is null && runtime.NextSessionAt is { } next && _s.Breaker.State.AllowsSiteActions && !runtime.IsPaused)
{
var sessionLength = TimeSpan.FromTicks((long)Math.Sqrt((double)profile.SessionMin.Ticks * profile.SessionMax.Ticks));
var pause = TimeSpan.FromTicks((long)Math.Sqrt((double)profile.PauseMin.Ticks * profile.PauseMax.Ticks));
var start = next < now ? now : next;
for (var i = 0; i < 40 && start < dayEnd; i++)
{
var window = windows.FirstOrDefault(w => w.Contains(start));
if (window is null)
{
break;
}
var end = start + sessionLength;
spans.Add(new StripSpan(StripSpanKind.PlannedSession, start, end < window.End ? end : window.End, true, "Prossima sessione " + ItalianText.Around(start, now, zone)));
start = end + pause;
}
}
var newEntries = 0L;
foreach (var account in accounts.Values)
{
foreach (var kind in new[] { EntryKind.Post, EntryKind.Story, EntryKind.Highlight, EntryKind.Tagged })
{
newEntries += await _s.Storage.Entries.CountDiscoveredAsync(account.Id, kind, dayStart, dayEnd, ct).ConfigureAwait(false);
}
}
var summary = string.Join(", ", new[]
{
ItalianText.Count(sessions.Count, "sessione", "sessioni"),
ItalianText.Count((long)Math.Round(activeMinutes), "minuto di attività", "minuti di attività"),
ItalianText.Count(newEntries, "contenuto nuovo", "contenuti nuovi"),
throttles == 0 ? "nessun rallentamento" : ItalianText.Count(throttles, "rallentamento", "rallentamenti"),
});
return new DayStrip(day, dayStart, dayEnd, now, summary, [.. spans.OrderBy(s => s.Start).ThenBy(s => s.Kind)]);
}
private async Task<IReadOnlyList<QueueItem>> QueueAsync(
DateTimeOffset now,
TimeZoneInfo zone,
EngineMode mode,
SessionContext? session,
EngineRuntime runtime,
Dictionary<long, Account> accounts,
CancellationToken ct)
{
var suspended = mode is EngineMode.Paused or EngineMode.Throttled or EngineMode.StoppedForVerification or EngineMode.Disconnected
or EngineMode.NotConnected or EngineMode.Off;
var tasks = await _s.Storage.Tasks.ListPendingAsync(200, ct).ConfigureAwait(false);
var items = new List<QueueItem>();
foreach (var task in tasks
.OrderByDescending(t => t.IsManual)
.ThenBy(t => t.DueAt)
.ThenByDescending(t => t.Priority)
.Take(20))
{
Account? account = null;
if (task.AccountId is { } id)
{
accounts.TryGetValue(id, out account);
}
var (title, detail) = Describe(task, account);
DateTimeOffset? around = null;
string when;
if (suspended)
{
when = "Sospeso";
}
else if (session is not null && task.DueAt <= now)
{
around = now;
when = "In questa sessione";
}
else
{
var t = task.DueAt;
var next = runtime.NextSessionAt ?? now;
if (t < next)
{
t = next;
}
if (t < now)
{
t = now;
}
if (await _s.Planner.GetWindowAtAsync(t, ct).ConfigureAwait(false) is null
&& await _s.Planner.GetNextWindowAsync(t, ct).ConfigureAwait(false) is { } w)
{
t = w.Start;
}
around = t;
when = ItalianText.Around(t, now, zone);
}
items.Add(new QueueItem(task.Id, task.Kind, task.AccountId, title, detail, around, when, task.IsManual, suspended));
}
return items;
}
private static (string Title, string Detail) Describe(EngineTask task, Account? account)
{
var who = ItalianText.Handle(account?.Username);
return task.Kind switch
{
EngineTaskKind.FollowingSweep => ("Giro dei profili che segui", "Home e barra delle storie"),
EngineTaskKind.FollowingList => ("Elenco dei profili che segui", "Lettura chiesta da te"),
EngineTaskKind.ProfileCheck when task.IsManual => (who, "Controllo chiesto da te"),
EngineTaskKind.ProfileCheck when account is { IsFollowed: true } => (who, "Riconciliazione del profilo"),
EngineTaskKind.ProfileCheck when account is not null && CheckPolicy.WantsStories(account) => (who, "Nuovi post e storie"),
EngineTaskKind.ProfileCheck => (who, "Nuovi post"),
EngineTaskKind.AccountStories when task.IsManual => (who, "Storie, chieste da te"),
EngineTaskKind.AccountStories when task.Priority > 0 => (who, "Storie segnalate dalla barra"),
EngineTaskKind.AccountStories => (who, "Storie"),
EngineTaskKind.Backfill when account?.PostCount is { } count => (who, "Storico, " + ItalianText.Count(count, "post sul profilo", "post sul profilo")),
EngineTaskKind.Backfill => (who, "Storico"),
EngineTaskKind.HighlightCheck => (who, "Storie in evidenza"),
EngineTaskKind.TaggedCheck => (who, "Post in cui è taggato"),
EngineTaskKind.ReelsCheck => (who, "Reel"),
EngineTaskKind.SinglePost => (who, "Post singolo"),
_ => (who, task.Kind.ToString()),
};
}
private async Task<IReadOnlyList<RecentActionView>> RecentAsync(DateTimeOffset now, TimeZoneInfo zone, CancellationToken ct)
{
var views = new List<RecentActionView>();
if (_s.Runtime.CurrentSession is not null && _s.Runtime.Activity is { } activity)
{
views.Add(new RecentActionView(now, ItalianText.Clock(now, zone), activity.StartsWith("Sto ", StringComparison.Ordinal) ? ItalianText.Capitalize(activity[4..]) : activity, string.Empty, "In corso", true));
}
var recent = _host.RecentActions(10);
if (recent.Count > 0)
{
views.AddRange(recent.Select(r => new RecentActionView(r.At, ItalianText.Clock(r.At, zone), r.Title, r.Detail, r.Badge, false)));
return views;
}
// Just started: the latest lines of the timeline.
var events = await _s.Storage.Events.ListAsync(new EventQuery { Limit = 200 }, ct).ConfigureAwait(false);
foreach (var e in events.Where(e => e.Code.StartsWith(EngineEventCodes.RecipePrefix, StringComparison.Ordinal)).Take(10))
{
var split = e.Message.IndexOf(": ", StringComparison.Ordinal);
var title = split > 0 ? e.Message[..split] : e.Message;
var detail = split > 0 ? e.Message[(split + 2)..] : string.Empty;
views.Add(new RecentActionView(e.At, ItalianText.Clock(e.At, zone), title, detail, null, false));
}
return views;
}
}
+193
View File
@@ -0,0 +1,193 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
namespace Febe.Core.Engine;
/// <summary>What the interface shows of the engine (spec §7.9, mockups 06 and 11, sidebar of §10.2).</summary>
public interface IEngineMonitor
{
/// <summary>The state of the engine now: mode, texts, strip of the day, budgets, queue, latest actions.</summary>
Task<EngineSnapshot> GetSnapshotAsync(CancellationToken ct = default);
/// <summary>Notifications from now on (timeline lines and state changes); the web layer turns them into server-sent events.</summary>
IAsyncEnumerable<EngineNotification> SubscribeAsync(CancellationToken ct = default);
}
/// <summary>Mode of the engine, in order of precedence.</summary>
public enum EngineMode
{
/// <summary>The loop is not running.</summary>
Off,
/// <summary>Just started: the first session comes 2–10 minutes after the program.</summary>
Starting,
InSession,
/// <summary>Between two sessions, inside the active window («In ascolto»).</summary>
Resting,
/// <summary>Outside the active window (night or inactive day).</summary>
OutsideWindow,
/// <summary>«Metti in pausa».</summary>
Paused,
/// <summary>Timed stop after a throttle.</summary>
Throttled,
/// <summary>Stopped for a verification: needs Alberto and «Riprendi».</summary>
StoppedForVerification,
/// <summary>The Instagram session is gone: needs a new login and «Riprendi».</summary>
Disconnected,
/// <summary>The browser has no Instagram session yet.</summary>
NotConnected,
/// <summary>Alberto is using the browser.</summary>
UserDriving,
}
/// <summary>Severity of the strip at the top of every page.</summary>
public enum BannerLevel
{
Warning,
Error,
}
/// <summary>The strip at the top of every page while Febe is stopped and needs Alberto (mockup 11).</summary>
/// <param name="Level">Error for verification and disconnection, warning for a throttle stop.</param>
/// <param name="Title">«Instagram chiede una verifica».</param>
/// <param name="Message">What happened, what Febe did, what Alberto must do.</param>
/// <param name="NeedsResume">«Riprendi» is needed (after Alberto used the browser).</param>
public sealed record StopBanner(BannerLevel Level, string Title, string Message, bool NeedsResume);
public enum StripSpanKind
{
/// <summary>Outside the active window: night (hatched).</summary>
OutsideWindow,
/// <summary>A past session.</summary>
Session,
/// <summary>The session in progress.</summary>
CurrentSession,
/// <summary>A planned session, indicative («Prossime, orario indicativo»).</summary>
PlannedSession,
/// <summary>Rest between sessions («Pausa»).</summary>
Rest,
/// <summary>Throttle stop.</summary>
Throttle,
/// <summary>Stop for a verification or a disconnection.</summary>
Stop,
}
/// <summary>A stretch of the strip of the day.</summary>
public sealed record StripSpan(StripSpanKind Kind, DateTimeOffset Start, DateTimeOffset End, bool Indicative, string Label);
/// <summary>The strip of the day: a 24-hour bar with sessions as irregular strokes (spec §10.1).</summary>
/// <param name="Day">Local day.</param>
/// <param name="Start">Local midnight.</param>
/// <param name="End">Next local midnight.</param>
/// <param name="Now">Instant of the snapshot (the marker).</param>
/// <param name="Summary">«9 sessioni, 80 minuti di attività, 41 contenuti nuovi, nessun rallentamento».</param>
/// <param name="Spans">Stretches in time order (spans of different kinds may overlap: stops over sessions).</param>
public sealed record DayStrip(DateOnly Day, DateTimeOffset Start, DateTimeOffset End, DateTimeOffset Now, string Summary, IReadOnlyList<StripSpan> Spans);
/// <summary>One budget as the interface shows it (spec §7.4: amber from 80%).</summary>
/// <param name="Kind">Category.</param>
/// <param name="Label">«Profili aperti».</param>
/// <param name="UsedToday">Today (bytes for data).</param>
/// <param name="LimitToday">Daily limit in force.</param>
/// <param name="UsedLastHour">Rolling last hour (null for data).</param>
/// <param name="LimitPerHour">Hourly limit in force (null for data).</param>
/// <param name="Amber">At or above 80% of the daily or hourly budget.</param>
/// <param name="Ratio">Daily use between 0 and 1 (for the bar).</param>
/// <param name="UsedText">«38», «1,3 GB».</param>
/// <param name="LimitText">«di 100», «di 4 GB».</param>
/// <param name="Note">«In questa ora 3 di 12», «Quasi al limite per oggi», «Fermo dalle 16:32».</param>
public sealed record BudgetView(
ActionKind Kind,
string Label,
long UsedToday,
long LimitToday,
long? UsedLastHour,
long? LimitPerHour,
bool Amber,
double Ratio,
string UsedText,
string LimitText,
string Note);
/// <summary>A task of the queue with its indicative time.</summary>
/// <param name="TaskId">Task key.</param>
/// <param name="Kind">What it is.</param>
/// <param name="AccountId">Account, when it has one.</param>
/// <param name="Title">«@luca.viaggi.demo» or «Giro dei profili che segui».</param>
/// <param name="Detail">«Nuovi post», «Storico, altri 120 post».</param>
/// <param name="Around">Indicative time; null when suspended.</param>
/// <param name="When">«verso le 14:32», «In questa sessione», «Sospeso».</param>
/// <param name="IsManual">Asked by Alberto.</param>
/// <param name="Suspended">The engine is stopped or paused.</param>
public sealed record QueueItem(long TaskId, EngineTaskKind Kind, long? AccountId, string Title, string Detail, DateTimeOffset? Around, string When, bool IsManual, bool Suspended);
/// <summary>A line of «Appena fatto».</summary>
public sealed record RecentActionView(DateTimeOffset At, string Time, string Title, string Detail, string? Badge, bool InProgress);
/// <summary>A recipe suspended after repeated unrecognized formats.</summary>
public sealed record SuspendedRecipeView(RecipeKind Recipe, string Name, DateTimeOffset Since);
/// <summary>Everything the Activity page, the sidebar and the stop strip need, at one instant.</summary>
public sealed record EngineSnapshot
{
public required DateTimeOffset At { get; init; }
public required EngineMode Mode { get; init; }
/// <summary>«In sessione», «In ascolto», «Fermo».</summary>
public required string Headline { get; init; }
/// <summary>Lines under the headline: «Sto guardando le storie di @marta.demo», «Iniziata alle 15:31, ancora 3 minuti circa».</summary>
public required IReadOnlyList<string> Details { get; init; }
/// <summary>One short line for the sidebar: «Storie di @marta.demo», «Riprende verso le 15:30».</summary>
public required string SidebarLine { get; init; }
/// <summary>Indicative restart time when not working.</summary>
public DateTimeOffset? ResumesAround { get; init; }
/// <summary>The red (or amber) strip at the top of every page; null when the engine does not need Alberto.</summary>
public StopBanner? Banner { get; init; }
public required CautionProfileKind Profile { get; init; }
/// <summary>«Profilo «Prudente»» with the reduction in force, if any.</summary>
public required string ProfileLine { get; init; }
/// <summary>«Avvio graduale: tetti al 64%» or «Tetti dimezzati fino a giovedì alle 17:32»; null without reductions.</summary>
public string? ReductionNote { get; init; }
public required DayStrip Today { get; init; }
/// <summary>The four main budgets: profiles opened, stories viewed, history pages, data downloaded.</summary>
public required IReadOnlyList<BudgetView> MainBudgets { get; init; }
/// <summary>«Tutti i tetti».</summary>
public required IReadOnlyList<BudgetView> AllBudgets { get; init; }
/// <summary>«Profili aperti oggi» meter of the sidebar.</summary>
public required BudgetView ProfilesOpenedToday { get; init; }
public required IReadOnlyList<QueueItem> Queue { get; init; }
public required IReadOnlyList<RecentActionView> RecentActions { get; init; }
public required IReadOnlyList<SuspendedRecipeView> SuspendedRecipes { get; init; }
public required BreakerState Breaker { get; init; }
}
+60
View File
@@ -0,0 +1,60 @@
namespace Febe.Core.Engine;
/// <summary>One recipe run, as shown in «Appena fatto» (mockup 06).</summary>
/// <param name="At">When it ended.</param>
/// <param name="Recipe">Recipe.</param>
/// <param name="AccountId">Account, when the recipe has one.</param>
/// <param name="Title">«@marta.demo» or «Giro dei profili che segui».</param>
/// <param name="Detail">«2 storie nuove», «Nessuna novità».</param>
/// <param name="Status">How it ended.</param>
/// <param name="NewEntries">New entries found.</param>
public sealed record RecentAction(
DateTimeOffset At,
RecipeKind Recipe,
long? AccountId,
string Title,
string Detail,
RecipeStatus Status,
int NewEntries)
{
/// <summary>Short label of the outcome for a badge («Scaricato», «Rimandato»...); null when nothing to say.</summary>
public string? Badge => Status switch
{
RecipeStatus.Completed => NewEntries > 0 ? "Scaricato" : null,
RecipeStatus.Denied => "Rimandato",
RecipeStatus.StoppedBySignal => "Tutto fermo",
RecipeStatus.TargetNotFound => "Da controllare",
RecipeStatus.UnrecognizedFormat => "Formato nuovo",
RecipeStatus.AccountUnreachable => "Non raggiungibile",
RecipeStatus.Cancelled => "Interrotto",
RecipeStatus.Failed => "Errore",
_ => null,
};
}
/// <summary>The last recipe runs, newest first, in memory (the timeline keeps the full history).</summary>
internal sealed class RecentActions(int capacity = 50)
{
private readonly Lock _gate = new();
private readonly LinkedList<RecentAction> _items = new();
public void Add(RecentAction action)
{
lock (_gate)
{
_items.AddFirst(action);
while (_items.Count > capacity)
{
_items.RemoveLast();
}
}
}
public IReadOnlyList<RecentAction> Snapshot(int limit)
{
lock (_gate)
{
return [.. _items.Take(limit)];
}
}
}
+149
View File
@@ -0,0 +1,149 @@
using System.Globalization;
using Febe.Core.Storage;
namespace Febe.Core.Engine;
/// <summary>
/// Consecutive failures per recipe and suspended recipes (spec §6.4: after three «formato non riconosciuto» in a row
/// the recipe is suspended and the interface says so). Persisted in the settings table.
/// </summary>
internal sealed class RecipeHealth
{
private readonly ISettingsStore _settings;
private readonly int _threshold;
private readonly Lock _gate = new();
private readonly Dictionary<RecipeKind, int> _failures = [];
private readonly Dictionary<RecipeKind, DateTimeOffset> _suspended = [];
public RecipeHealth(ISettingsStore settings, int threshold)
{
_settings = settings;
_threshold = Math.Max(1, threshold);
}
public async Task LoadAsync(CancellationToken ct)
{
var failures = await _settings.GetAsync(EngineSettingKeys.RecipeFailures, ct).ConfigureAwait(false);
var suspended = await _settings.GetAsync(EngineSettingKeys.SuspendedRecipes, ct).ConfigureAwait(false);
lock (_gate)
{
_failures.Clear();
_suspended.Clear();
foreach (var (kind, value) in Parse(failures))
{
_failures[kind] = (int)value;
}
foreach (var (kind, value) in Parse(suspended))
{
_suspended[kind] = DateTimeOffset.FromUnixTimeMilliseconds(value);
}
}
}
public IReadOnlyDictionary<RecipeKind, DateTimeOffset> Suspended
{
get
{
lock (_gate)
{
return new Dictionary<RecipeKind, DateTimeOffset>(_suspended);
}
}
}
public bool IsSuspended(RecipeKind kind)
{
lock (_gate)
{
return _suspended.ContainsKey(kind);
}
}
public int Failures(RecipeKind kind)
{
lock (_gate)
{
return _failures.GetValueOrDefault(kind);
}
}
/// <summary>Counts a failure; true when this one suspends the recipe.</summary>
public async Task<bool> RecordFailureAsync(RecipeKind kind, DateTimeOffset now, CancellationToken ct)
{
bool suspendedNow;
lock (_gate)
{
var count = _failures.GetValueOrDefault(kind) + 1;
_failures[kind] = count;
suspendedNow = count >= _threshold && _suspended.TryAdd(kind, now);
}
await SaveAsync(ct).ConfigureAwait(false);
return suspendedNow;
}
public async Task RecordSuccessAsync(RecipeKind kind, CancellationToken ct)
{
lock (_gate)
{
if (!_failures.Remove(kind))
{
return;
}
}
await SaveAsync(ct).ConfigureAwait(false);
}
/// <summary>Alberto updated the reader and reactivated the recipe.</summary>
public async Task<bool> ResumeAsync(RecipeKind kind, CancellationToken ct)
{
bool removed;
lock (_gate)
{
removed = _suspended.Remove(kind);
_failures.Remove(kind);
}
await SaveAsync(ct).ConfigureAwait(false);
return removed;
}
private Task SaveAsync(CancellationToken ct)
{
string failures;
string suspended;
lock (_gate)
{
failures = string.Join(';', _failures.OrderBy(f => f.Key).Select(f => f.Key + "=" + f.Value.ToString(CultureInfo.InvariantCulture)));
suspended = string.Join(';', _suspended.OrderBy(s => s.Key).Select(s => s.Key + "=" + s.Value.ToUnixTimeMilliseconds().ToString(CultureInfo.InvariantCulture)));
}
return _settings.SetManyAsync(
new Dictionary<string, string?>
{
[EngineSettingKeys.RecipeFailures] = failures.Length == 0 ? null : failures,
[EngineSettingKeys.SuspendedRecipes] = suspended.Length == 0 ? null : suspended,
},
ct);
}
private static IEnumerable<(RecipeKind Kind, long Value)> Parse(string? text)
{
if (string.IsNullOrWhiteSpace(text))
{
yield break;
}
foreach (var part in text.Split(';', StringSplitOptions.RemoveEmptyEntries))
{
var pair = part.Split('=', 2);
if (pair.Length == 2 && Enum.TryParse<RecipeKind>(pair[0], out var kind)
&& long.TryParse(pair[1], NumberStyles.Integer, CultureInfo.InvariantCulture, out var value))
{
yield return (kind, value);
}
}
}
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,94 @@
using System.Diagnostics;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Storage;
namespace Febe.Core.Simulation;
/// <summary>Options of <c>--simula</c> (spec §14.3).</summary>
public sealed record SimulationOptions
{
public int Days { get; init; } = 30;
public CautionProfileKind Profile { get; init; } = CautionProfileKind.Prudent;
/// <summary>Seed of the engine; the world uses a seed derived from it unless <see cref="World"/> sets one.</summary>
public int Seed { get; init; } = 1;
/// <summary>Program start; by default 14 October 2026 at 6:00 in Rome.</summary>
public DateTimeOffset? Start { get; init; }
public TimeZoneInfo? Zone { get; init; }
public SimulatedWorldOptions? World { get; init; }
public EngineOptions? Engine { get; init; }
/// <summary>Full engine settings (e.g. a «Su misura» profile); when null, <see cref="Profile"/> with the other defaults.</summary>
public EngineSettings? Settings { get; init; }
}
/// <summary>
/// Runs the real engine (Governor, breaker, planner, scheduler) under the virtual clock against the simulated world,
/// on a real database, and builds the report Alberto reads to judge a profile (spec §14.3).
/// </summary>
public static class EngineSimulation
{
/// <param name="options">What to simulate.</param>
/// <param name="openStorage">Opens an empty database (e.g. <c>FebeDatabase.OpenAsync</c> in a temporary folder).</param>
/// <param name="ct">Cancellation.</param>
public static async Task<SimulationReport> RunAsync(
SimulationOptions options,
Func<CancellationToken, Task<IFebeStorage>> openStorage,
CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(options);
ArgumentNullException.ThrowIfNull(openStorage);
if (options.Days < 1)
{
throw new ArgumentOutOfRangeException(nameof(options), options.Days, "Servono almeno un giorno di simulazione.");
}
var stopwatch = Stopwatch.StartNew();
var zone = options.Zone ?? SimulationZones.Rome;
var start = options.Start ?? LocalCalendar.FromLocal(new DateTime(2026, 10, 14, 6, 0, 0), zone);
// Whole local days: the run ends at the midnight after the last one.
var end = LocalCalendar.StartOfDay(LocalCalendar.Today(start, zone).AddDays(options.Days), zone);
var storage = await openStorage(ct).ConfigureAwait(false);
await using (storage.ConfigureAwait(false))
{
var clock = new VirtualClock(start, zone);
await EngineSettingsStore.SaveAsync(storage.Settings, options.Settings ?? new EngineSettings { ProfileKind = options.Profile }, ct).ConfigureAwait(false);
var services = await EngineServices.CreateAsync(storage, clock, new SeededRandom(options.Seed), options.Engine, ct: ct).ConfigureAwait(false);
var worldOptions = options.World ?? new SimulatedWorldOptions { Seed = options.Seed };
var world = new SimulatedWorld(storage, services.Governor, services.Governor, services.Breaker, clock, worldOptions);
await world.InitializeAsync(start, end, services.Runtime.Profile, ct).ConfigureAwait(false);
var host = new EngineHost(services, world);
await using (host.ConfigureAwait(false))
{
using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
var loop = host.RunAsync(cts.Token);
try
{
await clock.RunUntilAsync(end, ct, loop).ConfigureAwait(false);
}
finally
{
await cts.CancelAsync().ConfigureAwait(false);
try
{
await loop.ConfigureAwait(false);
}
catch (OperationCanceledException)
{
}
}
}
await services.Breaker.FlushAsync().ConfigureAwait(false);
return await SimulationReport.BuildAsync(storage, world, services, options, start, end, clock.FiredTimers, stopwatch.Elapsed, ct).ConfigureAwait(false);
}
}
}
+691
View File
@@ -0,0 +1,691 @@
using System.Globalization;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Pacing;
using Febe.Core.Storage;
namespace Febe.Core.Simulation;
/// <summary>The fake world of the simulation (spec §14.3).</summary>
public sealed record SimulatedWorldOptions
{
public int FollowedAccounts { get; init; } = 25;
public int NotFollowedAccounts { get; init; } = 15;
/// <summary>Average posts per account per day (one every three days), with rates varying among accounts.</summary>
public double MeanPostsPerDay { get; init; } = 1.0 / 3.0;
/// <summary>Share of accounts that post stories every day.</summary>
public double StoryAccountShare { get; init; } = 0.5;
/// <summary>Posts of history of the first account, to download with the backfill (0 for none).</summary>
public int HistoricalPosts { get; init; } = 2000;
/// <summary>Probability that a counted action meets a throttle signal («qualche rallentamento inserito a caso»).</summary>
public double ThrottleProbabilityPerAction { get; init; } = 0.0003;
/// <summary>Seed of the world, independent of the engine's.</summary>
public int Seed { get; init; } = 1;
/// <summary>Check frequency of the account with this index: by default one in ten High, two in ten Low, the rest Normal.</summary>
public Func<int, Frequency> FrequencyOf { get; init; } = i => (i % 10) switch
{
0 => Frequency.High,
1 or 2 => Frequency.Low,
_ => Frequency.Normal,
};
/// <summary>Gesture pace of the simulated recipes.</summary>
public GesturePace Pace { get; init; } = GesturePace.Natural;
}
/// <summary>What the world saw happen: discoveries, story checks, backfill, throttles.</summary>
public sealed class WorldStats
{
/// <summary>Publication and discovery of every new post found (history excluded).</summary>
public List<(DateTimeOffset Published, DateTimeOffset Discovered, bool Followed)> PostDiscoveries { get; } = [];
/// <summary>Publication and viewing of every story seen.</summary>
public List<(DateTimeOffset Published, DateTimeOffset Seen)> StoryViews { get; } = [];
/// <summary>Completed explicit story checks per account and local day.</summary>
public Dictionary<(long Account, DateOnly Day), int> StoryChecks { get; } = [];
/// <summary>Completed sweeps per local day (each one reads the stories bar of every followed account).</summary>
public Dictionary<DateOnly, int> Sweeps { get; } = [];
/// <summary>Runs per recipe and status.</summary>
public Dictionary<(RecipeKind Kind, RecipeStatus Status), int> Runs { get; } = [];
public long? BackfillAccountId { get; set; }
public int BackfillPostsStored { get; set; }
public DateTimeOffset? BackfillFinishedAt { get; set; }
public int ThrottlesReported { get; set; }
public int ProfileOpensOutsideRecipes { get; set; }
}
/// <summary>
/// A fake Instagram for the simulation: implements <see cref="IRecipeRunner"/> by asking the real Governor for every
/// counted action, spending virtual time like the gestures of spec §7.7, storing entries in the real database and
/// «downloading» their files within the data budget. It never opens anything: there is no browser.
/// </summary>
/// <remarks>
/// The world's behaviour (H2: the stories bar shows which followed profiles have stories; twelve posts per page of
/// history; a sweep sees up to three posts per scroll burst) is an assumption of the simulation, not a fact about Instagram.
/// </remarks>
public sealed class SimulatedWorld : IRecipeRunner
{
private const int PostsPerPage = 12;
private const int PostsPerBurst = 3;
private const long MB = 1024 * 1024;
private readonly IFebeStorage _storage;
private readonly IGovernor _governor;
private readonly IDataBudget _data;
private readonly ICircuitBreaker _breaker;
private readonly IClock _clock;
private readonly IRandomSource _random;
private readonly SimulatedWorldOptions _options;
private readonly List<SimAccount> _accounts = [];
private readonly Dictionary<long, SimAccount> _byId = [];
private readonly List<PendingFile> _pending = [];
private long _fileCounter;
public SimulatedWorld(
IFebeStorage storage,
IGovernor governor,
IDataBudget data,
ICircuitBreaker breaker,
IClock clock,
SimulatedWorldOptions? options = null)
{
_storage = storage ?? throw new ArgumentNullException(nameof(storage));
_governor = governor ?? throw new ArgumentNullException(nameof(governor));
_data = data ?? throw new ArgumentNullException(nameof(data));
_breaker = breaker ?? throw new ArgumentNullException(nameof(breaker));
_clock = clock ?? throw new ArgumentNullException(nameof(clock));
_options = options ?? new SimulatedWorldOptions();
_random = new SeededRandom(unchecked((_options.Seed * 7919) + 13));
}
public WorldStats Stats { get; } = new();
public IReadOnlyList<SimAccount> Accounts => _accounts;
private double Pace => GesturePaceFactors.For(_options.Pace);
/// <summary>Creates the accounts in the database and the publications of the period [start, end).</summary>
public async Task InitializeAsync(DateTimeOffset start, DateTimeOffset end, CautionProfile profile, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(profile);
var zone = _clock.LocalZone;
var total = _options.FollowedAccounts + _options.NotFollowedAccounts;
for (var i = 0; i < total; i++)
{
var followed = i < _options.FollowedAccounts;
var username = string.Create(CultureInfo.InvariantCulture, $"{(followed ? "seguito" : "pubblico")}{i + 1:00}.demo");
// Rates are log-normal around the mean (σ 0.9): some accounts post daily, some once a month.
var rate = _options.MeanPostsPerDay / Math.Exp(0.9 * 0.9 / 2) * Math.Exp(0.9 * _random.StandardNormal());
var historical = i == 0 ? _options.HistoricalPosts : 0;
var account = Account.Create(username, StartingPoint.EverythingAndKeepUpdated, start, zone, profile) with
{
InstagramId = (9_000_000 + i).ToString(CultureInfo.InvariantCulture),
IsFollowed = followed,
Frequency = _options.FrequencyOf(i),
State = historical > 0 ? AccountState.Backfilling : AccountState.UpToDate,
BackfillCompletedAt = historical > 0 ? null : start,
PostCount = historical,
};
var stored = await _storage.Accounts.AddAsync(account, ct).ConfigureAwait(false);
var share = _options.StoryAccountShare;
var postsStories = Math.Floor((i + 1) * share) > Math.Floor(i * share);
var sim = new SimAccount(stored.Id, username, followed, i, rate, postsStories);
if (historical > 0)
{
Stats.BackfillAccountId = stored.Id;
for (var h = 0; h < historical; h++)
{
// Newest first, about one every two days before the start.
sim.History.Add(new SimPost(Id(i, "h", h), start - TimeSpan.FromHours(6 + (h * 47.3)), 1 + (h % 4 == 0 ? 2 : 0), h % 5 == 0));
}
}
Generate(sim, start, end, zone);
_accounts.Add(sim);
_byId[sim.Id] = sim;
}
}
public async Task<RecipeOutcome> RunAsync(RecipeRequest request, ISessionContext session, CancellationToken ct)
{
ArgumentNullException.ThrowIfNull(request);
ArgumentNullException.ThrowIfNull(session);
await DownloadPendingAsync(ct).ConfigureAwait(false);
var outcome = request.Kind switch
{
RecipeKind.FollowingSweep => await SweepAsync(session, ct).ConfigureAwait(false),
RecipeKind.ProfileCheck => await ProfileAsync(Get(request), session, ct).ConfigureAwait(false),
RecipeKind.AccountStories => await StoriesAsync(Get(request), session, ct).ConfigureAwait(false),
RecipeKind.Backfill => await BackfillAsync(Get(request), request.MaxPages ?? 5, session, ct).ConfigureAwait(false),
RecipeKind.SinglePost => await SimpleAsync(ActionKind.SinglePost, request.AccountId, session, ct).ConfigureAwait(false),
RecipeKind.FollowingList => await SimpleAsync(ActionKind.FollowingListPage, null, session, ct).ConfigureAwait(false),
_ => await SimpleAsync(ActionKind.ProfileOpen, request.AccountId, session, ct).ConfigureAwait(false),
};
var key = (request.Kind, outcome.Status);
Stats.Runs[key] = Stats.Runs.GetValueOrDefault(key) + 1;
return outcome;
}
public Task RestAsync(CancellationToken ct) => Task.CompletedTask;
/// <summary>Stories published in [start, end) that expired before anyone saw them.</summary>
public int MissedStories(DateTimeOffset start, DateTimeOffset end) =>
_accounts.Sum(a => a.Stories.Count(s => s.PublishedAt >= start && s.ExpiresAt <= end && s.SeenAt is null));
/// <summary>New posts published in [start, end) not yet discovered at the end.</summary>
public int UndiscoveredPosts(DateTimeOffset start, DateTimeOffset end) =>
_accounts.Sum(a => a.Posts.Count(p => p.PublishedAt >= start && p.PublishedAt < end && p.DiscoveredAt is null));
/// <summary>Stories published in [start, end).</summary>
public int PublishedStories(DateTimeOffset start, DateTimeOffset end) =>
_accounts.Sum(a => a.Stories.Count(s => s.PublishedAt >= start && s.PublishedAt < end));
/// <summary>Posts published in [start, end).</summary>
public int PublishedPosts(DateTimeOffset start, DateTimeOffset end) =>
_accounts.Sum(a => a.Posts.Count(p => p.PublishedAt >= start && p.PublishedAt < end));
private SimAccount Get(RecipeRequest request) =>
request.AccountId is { } id && _byId.TryGetValue(id, out var account)
? account
: throw new InvalidOperationException("Account sconosciuto al mondo simulato.");
private void Generate(SimAccount account, DateTimeOffset start, DateTimeOffset end, TimeZoneInfo zone)
{
var first = LocalCalendar.Today(start, zone);
var last = LocalCalendar.Today(end, zone);
for (var day = first; day <= last; day = day.AddDays(1))
{
var posts = Poisson(account.PostRate);
for (var p = 0; p < posts; p++)
{
var at = DaytimeInstant(day, zone);
if (at >= start && at < end)
{
account.Posts.Add(new SimPost(Id(account.Index, "p", account.Posts.Count), at, 1 + Poisson(0.6), _random.Chance(0.25)));
}
}
if (account.PostsStories)
{
var stories = 1 + Poisson(1.5);
for (var s = 0; s < stories; s++)
{
var at = DaytimeInstant(day, zone);
if (at >= start && at < end)
{
var video = _random.Chance(0.3);
account.Stories.Add(new SimStory(
Id(account.Index, "s", account.Stories.Count),
at,
at + TimeSpan.FromHours(24),
video,
video ? TimeSpan.FromSeconds(5 + (10 * _random.NextDouble())) : TimeSpan.Zero));
}
}
}
}
account.Posts.Sort((a, b) => a.PublishedAt.CompareTo(b.PublishedAt));
account.Stories.Sort((a, b) => a.PublishedAt.CompareTo(b.PublishedAt));
}
private DateTimeOffset DaytimeInstant(DateOnly day, TimeZoneInfo zone)
{
// People post mostly between 8:00 and 23:30.
var minutes = 8 * 60 + (_random.NextDouble() * 15.5 * 60);
return LocalCalendar.FromLocal(day.ToDateTime(TimeOnly.MinValue).AddMinutes(minutes), zone);
}
private int Poisson(double mean)
{
var limit = Math.Exp(-mean);
var product = _random.NextDouble();
var count = 0;
while (product > limit && count < 50)
{
count++;
product *= _random.NextDouble();
}
return count;
}
private static string Id(int account, string kind, int n) =>
string.Create(CultureInfo.InvariantCulture, $"{account + 1:000}{kind}{n:00000}");
private async Task<RecipeOutcome> SweepAsync(ISessionContext session, CancellationToken ct)
{
var permit = await AskAsync(ActionKind.Home, null, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return Denied(0, 0);
}
if (permit.Throttled)
{
return Signal(1, 0);
}
await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
var bursts = _random.CountBetween(3, 8);
var now = _clock.Now;
var visible = _accounts
.Where(a => a.Followed)
.SelectMany(a => a.Posts.Where(p => p.PublishedAt <= now && p.DiscoveredAt is null).Select(p => (Account: a, Post: p)))
.OrderByDescending(x => x.Post.PublishedAt)
.Take(bursts * PostsPerBurst)
.ToList();
for (var b = 0; b < bursts; b++)
{
await WaitAsync(session, 0.4, 4, 1.1, ct).ConfigureAwait(false);
}
if (bursts >= 6)
{
await WaitAsync(session, 3, 20, 6, ct).ConfigureAwait(false);
}
now = _clock.Now;
foreach (var group in visible.GroupBy(v => v.Account))
{
await StorePostsAsync(group.Key, [.. group.Select(g => g.Post)], now, history: false, ct).ConfigureAwait(false);
}
var day = LocalCalendar.Today(now, _clock.LocalZone);
Stats.Sweeps[day] = Stats.Sweeps.GetValueOrDefault(day) + 1;
var withStories = _accounts
.Where(a => a.Followed && a.Stories.Any(s => s.PublishedAt <= now && s.ExpiresAt > now && s.SeenAt is null))
.Select(a => a.Id)
.ToList();
return new RecipeOutcome(RecipeStatus.Completed, 1, visible.Count)
{
AccountsWithStories = withStories,
AccountsWithNewPosts = [.. visible.Select(v => v.Account.Id).Distinct()],
};
}
private async Task<RecipeOutcome> ProfileAsync(SimAccount account, ISessionContext session, CancellationToken ct)
{
var permit = await AskAsync(ActionKind.ProfileOpen, account.Id, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return Denied(0, 0);
}
if (permit.Throttled)
{
return Signal(1, 0);
}
account.LastProfileOpen = _clock.Now;
await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
var bursts = _random.CountBetween(1, 3);
for (var b = 0; b < bursts; b++)
{
await WaitAsync(session, 0.4, 4, 1.1, ct).ConfigureAwait(false);
}
var now = _clock.Now;
var firstPage = account.Posts.Where(p => p.PublishedAt <= now).OrderByDescending(p => p.PublishedAt).Take(PostsPerPage);
var fresh = firstPage.Where(p => p.DiscoveredAt is null).ToList();
await StorePostsAsync(account, fresh, now, history: false, ct).ConfigureAwait(false);
return new RecipeOutcome(RecipeStatus.Completed, 1, fresh.Count);
}
private async Task<RecipeOutcome> StoriesAsync(SimAccount account, ISessionContext session, CancellationToken ct)
{
var counted = 0;
var now = _clock.Now;
if (!account.Followed && (account.LastProfileOpen is not { } opened || now - opened > TimeSpan.FromMinutes(2)))
{
// A profile that is not followed shows its stories only from its page.
var permit = await AskAsync(ActionKind.ProfileOpen, account.Id, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return Denied(0, 0);
}
counted++;
if (permit.Throttled)
{
return Signal(counted, 0);
}
account.LastProfileOpen = _clock.Now;
await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
}
now = _clock.Now;
var active = account.Stories.Where(s => s.PublishedAt <= now && s.ExpiresAt > now && s.SeenAt is null).ToList();
var seen = 0;
foreach (var story in active)
{
var permit = await AskAsync(ActionKind.StoryView, account.Id, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return Denied(counted, seen);
}
counted++;
if (permit.Throttled)
{
return Signal(counted, seen);
}
if (story.IsVideo)
{
var seconds = Math.Min(15, story.Duration.TotalSeconds * (0.4 + (0.6 * _random.NextDouble())));
await _clock.Delay(TimeSpan.FromSeconds(seconds * session.Mood * Pace), ct).ConfigureAwait(false);
}
else
{
await WaitAsync(session, 1.8, 5, null, ct).ConfigureAwait(false);
}
var at = _clock.Now;
story.SeenAt = at;
Stats.StoryViews.Add((story.PublishedAt, at));
await StoreStoryAsync(account, story, at, ct).ConfigureAwait(false);
seen++;
}
await WaitAsync(session, 1, 4, null, ct).ConfigureAwait(false);
var day = LocalCalendar.Today(_clock.Now, _clock.LocalZone);
Stats.StoryChecks[(account.Id, day)] = Stats.StoryChecks.GetValueOrDefault((account.Id, day)) + 1;
return new RecipeOutcome(RecipeStatus.Completed, counted, seen);
}
private async Task<RecipeOutcome> BackfillAsync(SimAccount account, int maxPages, ISessionContext session, CancellationToken ct)
{
var pages = 0;
var stored = 0;
while (pages < maxPages && _clock.Now < session.PlannedEnd)
{
if (account.HistoryCursor >= account.History.Count)
{
break;
}
var permit = await AskAsync(ActionKind.BackfillPage, account.Id, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return pages > 0 ? new RecipeOutcome(RecipeStatus.Completed, pages, stored) : Denied(0, 0);
}
pages++;
if (permit.Throttled)
{
return Signal(pages, stored);
}
await WaitAsync(session, 2, 8, 3.5, ct).ConfigureAwait(false);
var page = account.History.Skip(account.HistoryCursor).Take(PostsPerPage).ToList();
account.HistoryCursor += page.Count;
await StorePostsAsync(account, page, _clock.Now, history: true, ct).ConfigureAwait(false);
stored += page.Count;
Stats.BackfillPostsStored += page.Count;
}
var finished = account.HistoryCursor >= account.History.Count;
if (finished && account.Id == Stats.BackfillAccountId && Stats.BackfillFinishedAt is null)
{
Stats.BackfillFinishedAt = _clock.Now;
}
return new RecipeOutcome(RecipeStatus.Completed, pages, stored) { BackfillFinished = finished };
}
private async Task<RecipeOutcome> SimpleAsync(ActionKind kind, long? accountId, ISessionContext session, CancellationToken ct)
{
var permit = await AskAsync(kind, accountId, ct).ConfigureAwait(false);
if (!permit.Granted)
{
return Denied(0, 0);
}
if (permit.Throttled)
{
return Signal(1, 0);
}
await WaitAsync(session, 1, 6, 2.2, ct).ConfigureAwait(false);
return new RecipeOutcome(RecipeStatus.Completed, 1, 0);
}
/// <summary>Asks the Governor; a granted action may meet a simulated throttle signal, reported to the breaker.</summary>
private async Task<(bool Granted, bool Throttled)> AskAsync(ActionKind kind, long? accountId, CancellationToken ct)
{
var permit = await _governor.RequestAsync(kind, accountId, ct).ConfigureAwait(false);
if (permit.Granted && _random.Chance(_options.ThrottleProbabilityPerAction))
{
Stats.ThrottlesReported++;
_breaker.Report(new Signal(SignalLevel.Throttle, "http-429", "sito-simulato/" + kind, _clock.Now));
return (true, true);
}
return (permit.Granted, false);
}
private Task WaitAsync(ISessionContext session, double min, double max, double? median, CancellationToken ct) =>
_clock.Delay(TimeSpan.FromSeconds(_random.Between(min, max, median) * session.Mood * Pace), ct);
private static RecipeOutcome Denied(int counted, int found) => new(RecipeStatus.Denied, counted, found);
private static RecipeOutcome Signal(int counted, int found) => new(RecipeStatus.StoppedBySignal, counted, found, "Rallentamento simulato");
private async Task StorePostsAsync(SimAccount account, IReadOnlyList<SimPost> posts, DateTimeOffset now, bool history, CancellationToken ct)
{
if (posts.Count == 0)
{
return;
}
foreach (var post in posts)
{
post.DiscoveredAt = now;
if (!history)
{
Stats.PostDiscoveries.Add((post.PublishedAt, now, account.Followed));
}
}
var remaining = await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
var batch = new List<NewEntry>(posts.Count);
var sizes = new List<long[]>(posts.Count);
foreach (var post in posts)
{
var bytes = new long[post.Files];
for (var f = 0; f < post.Files; f++)
{
var video = post.HasVideo && f == 0;
bytes[f] = (long)((video ? _random.Between(2, 25) : _random.Between(0.3, 1.6)) * MB);
}
sizes.Add(bytes);
var fits = bytes.Sum() <= remaining;
if (fits)
{
remaining -= bytes.Sum();
}
var media = bytes.Select((b, f) => File(post.Id, f + 1, post.HasVideo && f == 0, b, fits)).ToList();
batch.Add(new NewEntry(
new Entry
{
AccountId = account.Id,
Kind = EntryKind.Post,
InstagramId = post.Id,
Code = "C" + post.Id,
PublishedAt = post.PublishedAt,
DiscoveredAt = now,
},
media));
}
var results = await _storage.Entries.AddManyAsync(batch, ct).ConfigureAwait(false);
await RecordAsync(account, results, ct).ConfigureAwait(false);
}
private async Task StoreStoryAsync(SimAccount account, SimStory story, DateTimeOffset now, CancellationToken ct)
{
var bytes = (long)((story.IsVideo ? _random.Between(1, 8) : _random.Between(0.2, 0.9)) * MB);
var fits = bytes <= await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
var result = await _storage.Entries.AddAsync(
new Entry
{
AccountId = account.Id,
Kind = EntryKind.Story,
InstagramId = story.Id,
PublishedAt = story.PublishedAt,
ExpiresAt = story.ExpiresAt,
DiscoveredAt = now,
},
[File(story.Id, 1, story.IsVideo, bytes, fits)],
ct).ConfigureAwait(false);
await RecordAsync(account, [result], ct).ConfigureAwait(false);
}
private Media File(string id, int position, bool video, long bytes, bool downloaded)
{
var media = new Media
{
Position = position,
Kind = video ? MediaKind.Video : MediaKind.Photo,
Bytes = bytes,
State = downloaded ? MediaState.Downloaded : MediaState.ToDownload,
};
return downloaded
? media with
{
RelativePath = $"sim/{id}_{position}{(video ? ".mp4" : ".jpg")}",
Sha256 = (++_fileCounter).ToString("x64", CultureInfo.InvariantCulture),
DownloadedAt = _clock.Now,
}
: media;
}
private async Task RecordAsync(SimAccount account, IReadOnlyList<AddEntryResult> results, CancellationToken ct)
{
long downloaded = 0;
foreach (var result in results.Where(r => r.Created))
{
foreach (var media in result.Stored.Media)
{
if (media.State == MediaState.Downloaded)
{
downloaded += media.Bytes ?? 0;
}
else
{
_pending.Add(new PendingFile(media.Id, account.Id, media.Bytes ?? 0, result.Stored.Entry.Kind == EntryKind.Story, media.Kind == MediaKind.Video));
}
}
}
await _data.RecordAsync(downloaded, account.Id, ct).ConfigureAwait(false);
}
/// <summary>The download queue: files left waiting by the data budget go as soon as there is room (stories first).</summary>
private async Task DownloadPendingAsync(CancellationToken ct)
{
if (_pending.Count == 0)
{
return;
}
var remaining = await _data.RemainingTodayAsync(ct).ConfigureAwait(false);
foreach (var file in _pending.OrderByDescending(p => p.IsStory).ToList())
{
if (file.Bytes > remaining)
{
continue;
}
var sha = (++_fileCounter).ToString("x64", CultureInfo.InvariantCulture);
await _storage.Media.MarkStoredAsync(
file.MediaId,
new StoredFile($"sim/attesa-{file.MediaId}{(file.IsVideo ? ".mp4" : ".jpg")}", file.Bytes, sha),
MediaState.Downloaded,
_clock.Now,
ct).ConfigureAwait(false);
await _data.RecordAsync(file.Bytes, file.AccountId, ct).ConfigureAwait(false);
remaining -= file.Bytes;
_pending.Remove(file);
}
}
private sealed record PendingFile(long MediaId, long AccountId, long Bytes, bool IsStory, bool IsVideo);
}
/// <summary>An account of the simulated world.</summary>
public sealed class SimAccount(long id, string username, bool followed, int index, double postRate, bool postsStories)
{
public long Id { get; } = id;
public string Username { get; } = username;
public bool Followed { get; } = followed;
public int Index { get; } = index;
/// <summary>Average new posts per day.</summary>
public double PostRate { get; } = postRate;
public bool PostsStories { get; } = postsStories;
internal List<SimPost> Posts { get; } = [];
/// <summary>Posts before the start, newest first.</summary>
internal List<SimPost> History { get; } = [];
internal int HistoryCursor { get; set; }
internal List<SimStory> Stories { get; } = [];
internal DateTimeOffset? LastProfileOpen { get; set; }
}
internal sealed class SimPost(string id, DateTimeOffset publishedAt, int files, bool hasVideo)
{
public string Id { get; } = id;
public DateTimeOffset PublishedAt { get; } = publishedAt;
public int Files { get; } = Math.Max(1, files);
public bool HasVideo { get; } = hasVideo;
public DateTimeOffset? DiscoveredAt { get; set; }
}
internal sealed class SimStory(string id, DateTimeOffset publishedAt, DateTimeOffset expiresAt, bool isVideo, TimeSpan duration)
{
public string Id { get; } = id;
public DateTimeOffset PublishedAt { get; } = publishedAt;
public DateTimeOffset ExpiresAt { get; } = expiresAt;
public bool IsVideo { get; } = isVideo;
public TimeSpan Duration { get; } = duration;
public DateTimeOffset? SeenAt { get; set; }
}
@@ -0,0 +1,487 @@
using System.Globalization;
using System.Text;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Storage;
namespace Febe.Core.Simulation;
/// <summary>Numbers of one simulated day.</summary>
public sealed record SimulatedDay(
DateOnly Day,
int Sessions,
double ActiveMinutes,
IReadOnlyDictionary<ActionKind, long> Actions,
IReadOnlyDictionary<ActionKind, long> WorstHour,
int Throttles,
int Overruns);
/// <summary>Numbers of one budget category over the whole simulation.</summary>
public sealed record SimulatedCategory(ActionKind Kind, double MeanPerDay, long MaxPerDay, long WorstHour, long? HourlyLimit, long DailyLimit);
/// <summary>Mean and maximum of a delay, with how many cases.</summary>
public sealed record DelayStats(int Count, TimeSpan Mean, TimeSpan Max)
{
public static DelayStats From(IEnumerable<TimeSpan> delays)
{
var list = delays.ToList();
return list.Count == 0
? new DelayStats(0, TimeSpan.Zero, TimeSpan.Zero)
: new DelayStats(list.Count, TimeSpan.FromTicks((long)list.Average(d => d.Ticks)), list.Max());
}
}
/// <summary>
/// The report of the simulation (spec §14.3): sessions per day; actions per category per day and in the worst hour;
/// mean and maximum time between publication and discovery; days for the 2,000-post backfill; budget overruns (must be
/// zero). Overruns, actions outside the window and pause-floor violations are recomputed here from the database,
/// independently of the Governor.
/// </summary>
public sealed class SimulationReport
{
private static readonly ActionKind[] Categories = Enum.GetValues<ActionKind>();
private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
public required CautionProfileKind Profile { get; init; }
public required int Seed { get; init; }
public required DateTimeOffset Start { get; init; }
public required DateTimeOffset End { get; init; }
public required TimeZoneInfo Zone { get; init; }
public required int Accounts { get; init; }
public required int FollowedAccounts { get; init; }
public required IReadOnlyList<SimulatedDay> Days { get; init; }
public required IReadOnlyList<SimulatedCategory> CategoryTotals { get; init; }
public required int SessionCount { get; init; }
public required double SessionsPerDayMean { get; init; }
public required int SessionsPerDayMin { get; init; }
public required int SessionsPerDayMax { get; init; }
public required TimeSpan MeanSessionLength { get; init; }
/// <summary>Coefficient of variation of the intervals between session starts (whole run).</summary>
public required double SessionStartCv { get; init; }
/// <summary>Same, only for intervals inside one day (nights excluded).</summary>
public required double SessionStartCvWithinDay { get; init; }
public required TimeSpan ShortestPause { get; init; }
public required int PauseFloorViolations { get; init; }
public required int ActionsOutsideWindow { get; init; }
public required DelayStats FollowedPosts { get; init; }
public required DelayStats NotFollowedPosts { get; init; }
public required DelayStats Stories { get; init; }
public required int PublishedPosts { get; init; }
public required int UndiscoveredPosts { get; init; }
public required int PublishedStories { get; init; }
public required int MissedStories { get; init; }
public required int BackfillPosts { get; init; }
public required int BackfillStored { get; init; }
public DateTimeOffset? BackfillFinishedAt { get; init; }
public required IReadOnlyList<Incident> Throttles { get; init; }
/// <summary>Times Febe proposed a more prudent profile (three throttles in seven days).</summary>
public required int ProposalsOfMorePrudence { get; init; }
/// <summary>Overruns of the budgets in force (gradual start and halving applied): must be zero.</summary>
public required int Overruns { get; init; }
/// <summary>Overruns of the profile's full budgets: must be zero too.</summary>
public required int OverrunsOfFullBudgets { get; init; }
public required IReadOnlyList<string> OverrunDetails { get; init; }
public required long VirtualEvents { get; init; }
/// <summary>What the fake world saw (for tests and closer looks).</summary>
public required WorldStats World { get; init; }
/// <summary>The accounts of the fake world.</summary>
public required IReadOnlyList<SimAccount> WorldAccounts { get; init; }
public required TimeSpan RealDuration { get; init; }
public double? BackfillDays => BackfillFinishedAt is { } done ? (done - Start).TotalDays : null;
internal static async Task<SimulationReport> BuildAsync(
IFebeStorage storage,
SimulatedWorld world,
EngineServices services,
SimulationOptions options,
DateTimeOffset start,
DateTimeOffset end,
long virtualEvents,
TimeSpan realDuration,
CancellationToken ct)
{
var zone = services.Clock.LocalZone;
var profile = services.Runtime.Profile;
var sessions = (await storage.Sessions.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false))
.Where(s => s.StartedAt < end)
.ToList();
var actions = await storage.ActionLog.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false);
var incidents = await storage.Incidents.ListAsync(start, end + TimeSpan.FromDays(1), ct).ConfigureAwait(false);
var throttles = incidents.Where(i => i.Level == SignalLevel.Throttle).ToList();
var seedText = await storage.Settings.GetAsync(EngineSettingKeys.WindowSeed, ct).ConfigureAwait(false);
var seed = ulong.TryParse(seedText, NumberStyles.Integer, CultureInfo.InvariantCulture, out var s) ? s : 0;
var rampStart = services.Runtime.RampStart;
// Halving applies after the throttle: the action that met the signal was granted before it.
DateTimeOffset? HalvedUntil(DateTimeOffset t) => throttles
.Where(i => i.At < t && i.StoppedUntil is not null)
.Select(i => (DateTimeOffset?)(i.StoppedUntil!.Value + CircuitBreaker.HalvedPeriod))
.Where(u => u > t)
.DefaultIfEmpty(null)
.Max();
// Overruns, recomputed from action_log: at every action the rolling hour and the local day so far.
var overruns = 0;
var overrunsFull = 0;
var details = new List<string>();
var overrunsByDay = new Dictionary<DateOnly, int>();
var worstHourByDay = new Dictionary<(DateOnly, ActionKind), long>();
var worstHour = new Dictionary<ActionKind, long>();
foreach (var kind in Categories)
{
var list = actions.Where(a => a.Category == kind).OrderBy(a => a.At).ThenBy(a => a.Id).ToList();
var windowStart = 0;
long windowSum = 0;
long daySum = 0;
DateOnly? currentDay = null;
for (var i = 0; i < list.Count; i++)
{
var action = list[i];
windowSum += action.Amount;
while (list[windowStart].At <= action.At - Hour)
{
windowSum -= list[windowStart].Amount;
windowStart++;
}
var day = LocalCalendar.Today(action.At, zone);
if (day != currentDay)
{
currentDay = day;
daySum = 0;
}
daySum += action.Amount;
worstHour[kind] = Math.Max(worstHour.GetValueOrDefault(kind), windowSum);
worstHourByDay[(day, kind)] = Math.Max(worstHourByDay.GetValueOrDefault((day, kind)), windowSum);
var limits = BudgetLimits.Compute(profile, rampStart, HalvedUntil(action.At), action.At);
var over = kind == ActionKind.DataDownload
? daySum > limits.DataPerDayBytes
: windowSum > limits.Budgets[kind].PerHour || daySum > limits.Budgets[kind].PerDay;
var overFull = kind == ActionKind.DataDownload
? daySum > profile.DataPerDayBytes
: windowSum > profile.Budgets[kind].PerHour || daySum > profile.Budgets[kind].PerDay;
if (over)
{
overruns++;
overrunsByDay[day] = overrunsByDay.GetValueOrDefault(day) + 1;
if (details.Count < 20)
{
details.Add(string.Create(
CultureInfo.InvariantCulture,
$"{ItalianText.Category(kind)} {LocalCalendar.ToLocal(action.At, zone):yyyy-MM-dd HH:mm:ss}: ora {windowSum}, giorno {daySum}"));
}
}
if (overFull)
{
overrunsFull++;
}
}
}
// Actions outside the active window (recomputed with the persisted seed of the daily shifts).
var outside = 0;
var windows = new Dictionary<DateOnly, ActiveWindow?>();
ActiveWindow? WindowOf(DateOnly day)
{
if (!windows.TryGetValue(day, out var w))
{
w = profile.ActiveDays.Contains(day.DayOfWeek) ? DayPlanner.Compute(day, profile, seed, zone) : null;
windows[day] = w;
}
return w;
}
foreach (var action in actions.Where(a => a.Category != ActionKind.DataDownload))
{
var today = LocalCalendar.Today(action.At, zone);
var inside = (WindowOf(today)?.Contains(action.At) ?? false) || (WindowOf(today.AddDays(-1))?.Contains(action.At) ?? false);
if (!inside)
{
outside++;
}
}
// Pauses and irregularity of the session starts.
var ordered = sessions.OrderBy(x => x.StartedAt).ToList();
var shortest = TimeSpan.MaxValue;
var floorViolations = 0;
for (var i = 1; i < ordered.Count; i++)
{
if (ordered[i - 1].EndedAt is { } previousEnd)
{
var pause = ordered[i].StartedAt - previousEnd;
shortest = pause < shortest ? pause : shortest;
if (pause < profile.PauseMin)
{
floorViolations++;
}
}
}
var intervals = new List<double>();
var withinDay = new List<double>();
for (var i = 1; i < ordered.Count; i++)
{
var gap = (ordered[i].StartedAt - ordered[i - 1].StartedAt).TotalMinutes;
intervals.Add(gap);
if (LocalCalendar.Today(ordered[i].StartedAt, zone) == LocalCalendar.Today(ordered[i - 1].StartedAt, zone) && gap < 6 * 60)
{
withinDay.Add(gap);
}
}
// Days.
var firstDay = LocalCalendar.Today(start, zone);
var lastDay = LocalCalendar.Today(end - TimeSpan.FromTicks(1), zone);
var days = new List<SimulatedDay>();
for (var day = firstDay; day <= lastDay; day = day.AddDays(1))
{
var (dayStart, dayEnd) = LocalCalendar.DayBounds(day, zone);
var daySessions = ordered.Where(x => x.StartedAt >= dayStart && x.StartedAt < dayEnd).ToList();
var active = daySessions.Sum(x => ((x.EndedAt ?? x.StartedAt) - x.StartedAt).TotalMinutes);
var counts = Categories.ToDictionary(k => k, k => actions.Where(a => a.Category == k && a.At >= dayStart && a.At < dayEnd).Sum(a => a.Amount));
var worst = Categories.ToDictionary(k => k, k => worstHourByDay.GetValueOrDefault((day, k)));
days.Add(new SimulatedDay(
day,
daySessions.Count,
active,
counts,
worst,
throttles.Count(t => t.At >= dayStart && t.At < dayEnd),
overrunsByDay.GetValueOrDefault(day)));
}
var categories = Categories.Select(k => new SimulatedCategory(
k,
days.Count == 0 ? 0 : days.Average(d => (double)d.Actions[k]),
days.Count == 0 ? 0 : days.Max(d => d.Actions[k]),
worstHour.GetValueOrDefault(k),
k == ActionKind.DataDownload ? null : profile.Budgets[k].PerHour,
k == ActionKind.DataDownload ? profile.DataPerDayBytes : profile.Budgets[k].PerDay)).ToList();
var stats = world.Stats;
return new SimulationReport
{
Profile = profile.Kind,
Seed = options.Seed,
Start = start,
End = end,
Zone = zone,
Accounts = world.Accounts.Count,
FollowedAccounts = world.Accounts.Count(a => a.Followed),
Days = days,
CategoryTotals = categories,
SessionCount = ordered.Count,
SessionsPerDayMean = days.Count == 0 ? 0 : days.Average(d => d.Sessions),
SessionsPerDayMin = days.Count == 0 ? 0 : days.Min(d => d.Sessions),
SessionsPerDayMax = days.Count == 0 ? 0 : days.Max(d => d.Sessions),
MeanSessionLength = ordered.Count == 0 ? TimeSpan.Zero : TimeSpan.FromTicks((long)ordered.Average(x => ((x.EndedAt ?? x.StartedAt) - x.StartedAt).Ticks)),
SessionStartCv = Cv(intervals),
SessionStartCvWithinDay = Cv(withinDay),
ShortestPause = shortest == TimeSpan.MaxValue ? TimeSpan.Zero : shortest,
PauseFloorViolations = floorViolations,
ActionsOutsideWindow = outside,
FollowedPosts = DelayStats.From(stats.PostDiscoveries.Where(p => p.Followed).Select(p => p.Discovered - p.Published)),
NotFollowedPosts = DelayStats.From(stats.PostDiscoveries.Where(p => !p.Followed).Select(p => p.Discovered - p.Published)),
Stories = DelayStats.From(stats.StoryViews.Select(v => v.Seen - v.Published)),
PublishedPosts = world.PublishedPosts(start, end),
UndiscoveredPosts = world.UndiscoveredPosts(start, end),
PublishedStories = world.PublishedStories(start, end),
MissedStories = world.MissedStories(start, end),
BackfillPosts = (options.World ?? new SimulatedWorldOptions()).HistoricalPosts,
BackfillStored = stats.BackfillPostsStored,
BackfillFinishedAt = stats.BackfillFinishedAt,
Throttles = throttles,
ProposalsOfMorePrudence = throttles.Count(t => throttles.Count(o => o.At <= t.At && o.At > t.At - CircuitBreaker.ProposalWindow) >= CircuitBreaker.ProposalThreshold),
Overruns = overruns,
OverrunsOfFullBudgets = overrunsFull,
OverrunDetails = details,
VirtualEvents = virtualEvents,
World = stats,
WorldAccounts = world.Accounts,
RealDuration = realDuration,
};
}
/// <summary>Italian text report.</summary>
public string ToText()
{
var b = new StringBuilder();
var firstDay = LocalCalendar.Today(Start, Zone);
var lastDay = LocalCalendar.Today(End - TimeSpan.FromTicks(1), Zone);
b.AppendLine($"Simulazione del motore: {ItalianText.Count(Days.Count, "giorno", "giorni")} con il profilo «{ItalianText.Profile(Profile)}» (seme {Seed.ToString(CultureInfo.InvariantCulture)})");
b.AppendLine($"Periodo: dal {ItalianText.Day(firstDay)} alle {ItalianText.Clock(Start, Zone)} al {ItalianText.Day(lastDay)}, fuso {Zone.Id}");
b.AppendLine($"Mondo finto: {ItalianText.Number(Accounts)} account ({ItalianText.Number(FollowedAccounts)} seguiti, {ItalianText.Number(Accounts - FollowedAccounts)} no), {ItalianText.Number(PublishedPosts)} post e {ItalianText.Number(PublishedStories)} storie pubblicati nel periodo, uno storico di {ItalianText.Number(BackfillPosts)} post");
b.AppendLine("I tetti del profilo sono stime prudenti, non limiti ufficiali di Instagram.");
b.AppendLine();
b.AppendLine("Sessioni");
b.AppendLine($" al giorno: media {ItalianText.Decimal(SessionsPerDayMean, 1)}, minimo {ItalianText.Number(SessionsPerDayMin)}, massimo {ItalianText.Number(SessionsPerDayMax)} (in tutto {ItalianText.Number(SessionCount)})");
b.AppendLine($" durata media: {ItalianText.Duration(MeanSessionLength)}; pausa più breve: {ItalianText.Duration(ShortestPause)}");
b.AppendLine($" irregolarità degli inizi (coefficiente di variazione): {ItalianText.Decimal(SessionStartCv, 2)} in tutto, {ItalianText.Decimal(SessionStartCvWithinDay, 2)} dentro la giornata");
b.AppendLine();
b.AppendLine("Azioni per categoria: media al giorno, giorno peggiore, ora peggiore (tetto all'ora / al giorno)");
foreach (var c in CategoryTotals)
{
if (c.Kind == ActionKind.DataDownload)
{
b.AppendLine($" {ItalianText.CategoryLabel(c.Kind)}: {ItalianText.Bytes((long)c.MeanPerDay)} al giorno, giorno peggiore {ItalianText.Bytes(c.MaxPerDay)} (tetto {ItalianText.Bytes(c.DailyLimit)} al giorno)");
}
else
{
b.AppendLine($" {ItalianText.CategoryLabel(c.Kind)}: {ItalianText.Decimal(c.MeanPerDay, 1)} al giorno, giorno peggiore {ItalianText.Number(c.MaxPerDay)}, ora peggiore {ItalianText.Number(c.WorstHour)} (tetto {ItalianText.Number(c.HourlyLimit ?? 0)} / {ItalianText.Number(c.DailyLimit)})");
}
}
b.AppendLine();
b.AppendLine("Dalla pubblicazione alla scoperta");
b.AppendLine($" post degli account seguiti: {Delay(FollowedPosts)}");
b.AppendLine($" post degli account non seguiti: {Delay(NotFollowedPosts)}");
b.AppendLine($" storie: {Delay(Stories)}");
b.AppendLine($" post non ancora scoperti alla fine: {ItalianText.Number(UndiscoveredPosts)} di {ItalianText.Number(PublishedPosts)}; storie scadute senza essere viste: {ItalianText.Number(MissedStories)} di {ItalianText.Number(PublishedStories)}");
b.AppendLine();
b.AppendLine($"Storico di {ItalianText.Number(BackfillPosts)} post");
b.AppendLine(BackfillFinishedAt is { } done
? $" completato in {ItalianText.Decimal(BackfillDays ?? 0, 1)} giorni ({ItalianText.DayWithWeekday(LocalCalendar.Today(done, Zone))} {ItalianText.At(done, Zone)})"
: $" non completato: {ItalianText.Number(BackfillStored)} post scaricati in {ItalianText.Count(Days.Count, "giorno", "giorni")}");
b.AppendLine();
b.AppendLine("Rallentamenti simulati");
if (Throttles.Count == 0)
{
b.AppendLine(" nessuno");
}
foreach (var t in Throttles)
{
var stop = t.StoppedUntil is { } until ? ItalianText.Duration(until - t.At) : "?";
b.AppendLine($" {ItalianText.DayWithWeekday(LocalCalendar.Today(t.At, Zone))} {ItalianText.At(t.At, Zone)}: fermo di {stop}");
}
if (ProposalsOfMorePrudence > 0)
{
b.AppendLine($" proposte di passare a un profilo più prudente (tre rallentamenti in sette giorni): {ItalianText.Number(ProposalsOfMorePrudence)}");
}
b.AppendLine();
b.AppendLine("Controlli");
b.AppendLine($" superamenti dei tetti: {ItalianText.Number(Overruns)} (dei tetti pieni del profilo: {ItalianText.Number(OverrunsOfFullBudgets)})");
foreach (var detail in OverrunDetails)
{
b.AppendLine(" " + detail);
}
b.AppendLine($" azioni fuori dalla fascia oraria: {ItalianText.Number(ActionsOutsideWindow)}");
b.AppendLine($" pause più brevi della pausa minima: {ItalianText.Number(PauseFloorViolations)}");
b.AppendLine();
b.AppendLine($"Simulati {ItalianText.Number(VirtualEvents)} eventi in {ItalianText.Decimal(RealDuration.TotalSeconds, 1)} secondi.");
return b.ToString();
}
/// <summary>One row per day, ';' separated, for Excel in Italian (write it as UTF-8 with BOM).</summary>
public string ToCsv()
{
var b = new StringBuilder();
var headers = new List<string> { "giorno", "sessioni", "minuti di attività" };
headers.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => ItalianText.Category(k)));
headers.Add("dati scaricati (MB)");
headers.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => "ora peggiore, " + ItalianText.Category(k)));
headers.Add("rallentamenti");
headers.Add("superamenti");
b.AppendLine(string.Join(';', headers.Select(Quote)));
foreach (var day in Days)
{
var cells = new List<string>
{
day.Day.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
day.Sessions.ToString(CultureInfo.InvariantCulture),
ItalianText.Decimal(day.ActiveMinutes, 1, keepZeros: true).Replace(".", string.Empty, StringComparison.Ordinal),
};
cells.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => day.Actions[k].ToString(CultureInfo.InvariantCulture)));
cells.Add(ItalianText.Decimal(day.Actions[ActionKind.DataDownload] / (1024.0 * 1024.0), 1, keepZeros: true).Replace(".", string.Empty, StringComparison.Ordinal));
cells.AddRange(Categories.Where(k => k != ActionKind.DataDownload).Select(k => day.WorstHour[k].ToString(CultureInfo.InvariantCulture)));
cells.Add(day.Throttles.ToString(CultureInfo.InvariantCulture));
cells.Add(day.Overruns.ToString(CultureInfo.InvariantCulture));
b.AppendLine(string.Join(';', cells));
}
return b.ToString();
}
/// <summary>Writes <see cref="ToCsv"/> as UTF-8 with BOM.</summary>
public async Task WriteCsvAsync(string path, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(path);
await File.WriteAllTextAsync(path, ToCsv(), new UTF8Encoding(encoderShouldEmitUTF8Identifier: true), ct).ConfigureAwait(false);
}
private static string Delay(DelayStats stats) => stats.Count == 0
? "nessun caso"
: $"media {ItalianText.Duration(stats.Mean)}, massimo {ItalianText.Duration(stats.Max)} ({ItalianText.Count(stats.Count, "caso", "casi")})";
private static string Quote(string text) => text.Contains(';', StringComparison.Ordinal) || text.Contains('"', StringComparison.Ordinal)
? "\"" + text.Replace("\"", "\"\"", StringComparison.Ordinal) + "\""
: text;
private static double Cv(IReadOnlyList<double> values)
{
if (values.Count < 2)
{
return 0;
}
var mean = values.Average();
if (mean <= 0)
{
return 0;
}
var variance = values.Sum(v => (v - mean) * (v - mean)) / (values.Count - 1);
return Math.Sqrt(variance) / mean;
}
}
@@ -0,0 +1,30 @@
namespace Febe.Core.Simulation;
/// <summary>Alberto's time zone for the simulation, also where the system has no time zone data.</summary>
public static class SimulationZones
{
/// <summary>Europe/Rome, or an equivalent custom zone (CET/CEST, last Sunday of March and October).</summary>
public static TimeZoneInfo Rome { get; } = LoadRome();
private static TimeZoneInfo LoadRome()
{
foreach (var id in new[] { "Europe/Rome", "W. Europe Standard Time" })
{
try
{
return TimeZoneInfo.FindSystemTimeZoneById(id);
}
catch (TimeZoneNotFoundException)
{
}
catch (InvalidTimeZoneException)
{
}
}
var start = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(new DateTime(1, 1, 1, 2, 0, 0), 3, 5, DayOfWeek.Sunday);
var end = TimeZoneInfo.TransitionTime.CreateFloatingDateRule(new DateTime(1, 1, 1, 3, 0, 0), 10, 5, DayOfWeek.Sunday);
var rule = TimeZoneInfo.AdjustmentRule.CreateAdjustmentRule(DateTime.MinValue.Date, DateTime.MaxValue.Date, TimeSpan.FromHours(1), start, end);
return TimeZoneInfo.CreateCustomTimeZone("Europe/Rome", TimeSpan.FromHours(1), "Europe/Rome", "CET", "CEST", [rule]);
}
}
+274
View File
@@ -0,0 +1,274 @@
using System.Diagnostics;
using Febe.Core.Abstractions;
namespace Febe.Core.Simulation;
/// <summary>
/// Event-driven virtual clock for the simulation and the engine tests (spec §14.1, §14.3). A <see cref="Delay"/>
/// registers a timer that completes only when virtual time reaches it; <see cref="RunUntilAsync"/> waits until every
/// actor (by default one: the engine loop) is waiting on a timer, then moves time to the earliest timer and fires it.
/// Thirty simulated days take seconds, and the outcome depends only on the seeds.
/// </summary>
/// <remarks>
/// <para>Delays are rounded up to whole milliseconds, the resolution of the database, so stored and computed times compare exactly.</para>
/// <para>With <see cref="AutoAdvance"/> a delay moves time forward at once: handy for one component under test, without a driver.</para>
/// <para>Each actor must wait on at most one delay at a time, otherwise the driver could advance before the second is registered.</para>
/// </remarks>
public sealed class VirtualClock : IClock
{
private static readonly long TicksPerMillisecond = TimeSpan.TicksPerMillisecond;
private readonly Lock _gate = new();
private readonly PriorityQueue<PendingDelay, (long Due, long Sequence)> _timers = new();
private readonly SemaphoreSlim _registered = new(0);
private DateTimeOffset _now;
private long _sequence;
private int _active;
public VirtualClock(DateTimeOffset start, TimeZoneInfo? zone = null)
{
_now = new DateTimeOffset(start.UtcTicks - (start.UtcTicks % TicksPerMillisecond), TimeSpan.Zero);
LocalZone = zone ?? TimeZoneInfo.Utc;
}
public DateTimeOffset Now
{
get
{
lock (_gate)
{
return _now;
}
}
}
public TimeZoneInfo LocalZone { get; }
/// <summary>When true, <see cref="Delay"/> advances time at once (no driver).</summary>
public bool AutoAdvance { get; set; }
/// <summary>Independent actors that wait on this clock; time advances only when all of them wait.</summary>
public int Actors { get; set; } = 1;
/// <summary>Real-time limit without any progress before <see cref="RunUntilAsync"/> gives up.</summary>
public TimeSpan StallTimeout { get; set; } = TimeSpan.FromSeconds(60);
/// <summary>Delays registered and not yet completed or cancelled.</summary>
public int PendingTimers
{
get
{
lock (_gate)
{
return _active;
}
}
}
/// <summary>Delays that completed (a measure of how much the simulation did).</summary>
public long FiredTimers { get; private set; }
public Task Delay(TimeSpan time, CancellationToken ct)
{
if (ct.IsCancellationRequested)
{
return Task.FromCanceled(ct);
}
var ticks = time.Ticks <= 0 ? 0 : ((time.Ticks + TicksPerMillisecond - 1) / TicksPerMillisecond) * TicksPerMillisecond;
if (ticks == 0)
{
return Task.CompletedTask;
}
lock (_gate)
{
if (AutoAdvance)
{
_now = _now.AddTicks(ticks);
return Task.CompletedTask;
}
}
// Registered before the timer is queued, so the registration is complete before anyone can fire it.
var delay = new PendingDelay();
if (ct.CanBeCanceled)
{
delay.Registration = ct.Register(() => Cancel(delay, ct));
}
lock (_gate)
{
if (delay.Done)
{
return delay.Completion.Task;
}
delay.Due = _now.AddTicks(ticks);
delay.Queued = true;
_timers.Enqueue(delay, (delay.Due.UtcTicks, _sequence++));
_active++;
}
_registered.Release();
return delay.Completion.Task;
}
/// <summary>Moves time forward by hand, firing in order the timers that fall due on the way.</summary>
public void Advance(TimeSpan time) => AdvanceTo(Now + time);
/// <summary>Moves time to <paramref name="target"/>, firing in order the timers that fall due on the way.</summary>
public void AdvanceTo(DateTimeOffset target)
{
while (TryFireNext(target))
{
}
lock (_gate)
{
if (target > _now)
{
_now = target;
}
}
}
/// <summary>
/// Runs the simulation until <paramref name="target"/>: whenever all actors wait on a timer, time jumps to the
/// earliest one and fires it. Returns with time at <paramref name="target"/> and the actors waiting. If an actor
/// fails, its exception is thrown here.
/// </summary>
/// <param name="target">Virtual instant to reach.</param>
/// <param name="ct">Cancellation.</param>
/// <param name="actors">The actors' tasks: a finished actor no longer counts, a failed one stops the run.</param>
public async Task RunUntilAsync(DateTimeOffset target, CancellationToken ct = default, params Task[] actors)
{
ArgumentNullException.ThrowIfNull(actors);
while (true)
{
await WaitQuiescentAsync(actors, ct).ConfigureAwait(false);
if (actors.FirstOrDefault(a => a.IsFaulted) is { } failed)
{
await failed.ConfigureAwait(false);
}
if (!TryFireNext(target))
{
lock (_gate)
{
if (target > _now)
{
_now = target;
}
}
return;
}
}
}
private async Task WaitQuiescentAsync(Task[] actors, CancellationToken ct)
{
var stopwatch = Stopwatch.StartNew();
while (true)
{
ct.ThrowIfCancellationRequested();
if (actors.Any(a => a.IsFaulted))
{
return;
}
var running = Actors - actors.Count(a => a.IsCompleted);
if (running <= 0 || PendingTimers >= running)
{
return;
}
if (await _registered.WaitAsync(TimeSpan.FromMilliseconds(100), ct).ConfigureAwait(false))
{
stopwatch.Restart();
continue;
}
if (stopwatch.Elapsed > StallTimeout)
{
throw new TimeoutException(
$"La simulazione non avanza da {StallTimeout.TotalSeconds:0} secondi: un attore aspetta qualcosa che non è un timer dell'orologio virtuale.");
}
}
}
private bool TryFireNext(DateTimeOffset limit)
{
PendingDelay? fired = null;
lock (_gate)
{
while (_timers.TryPeek(out var next, out _))
{
if (next.Done)
{
_timers.Dequeue();
continue;
}
if (next.Due > limit)
{
break;
}
_timers.Dequeue();
next.Done = true;
_active--;
if (next.Due > _now)
{
_now = next.Due;
}
fired = next;
FiredTimers++;
break;
}
}
if (fired is null)
{
return false;
}
fired.Registration.Dispose();
fired.Completion.TrySetResult();
return true;
}
private void Cancel(PendingDelay delay, CancellationToken ct)
{
lock (_gate)
{
if (delay.Done)
{
return;
}
delay.Done = true;
if (delay.Queued)
{
_active--;
}
}
delay.Completion.TrySetCanceled(ct);
}
private sealed class PendingDelay
{
public DateTimeOffset Due { get; set; }
public bool Queued { get; set; }
public TaskCompletionSource Completion { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
public CancellationTokenRegistration Registration { get; set; }
public bool Done { get; set; }
}
}
+9
View File
@@ -1,2 +1,11 @@
// Composition root for Linux and Docker. Filled in by milestones M3–M5.
using Febe.Server;
if (SimulateCommand.Matches(args))
{
Console.OutputEncoding = System.Text.Encoding.UTF8;
return await SimulateCommand.RunAsync(args, Console.Out, Console.Error);
}
Console.WriteLine("Febe");
return 0;
+136
View File
@@ -0,0 +1,136 @@
using System.Globalization;
using Febe.Core.Domain;
using Febe.Core.Simulation;
using Febe.Data;
namespace Febe.Server;
/// <summary>
/// <c>--simula 30g --profilo prudente [--csv percorso] [--seme n]</c> (spec §14.3): runs the engine under the virtual
/// clock against the fake world, in a temporary database, and prints the Italian report. Never opens a browser and
/// never contacts any site. Exit code 0 when no budget was exceeded, 1 otherwise, 2 for wrong arguments.
/// </summary>
internal static class SimulateCommand
{
public const string Flag = "--simula";
public static bool Matches(string[] args) => args.Any(a => string.Equals(a, Flag, StringComparison.OrdinalIgnoreCase));
public static async Task<int> RunAsync(string[] args, TextWriter output, TextWriter error, CancellationToken ct = default)
{
if (!TryParse(args, out var options, out var csv, out var problem))
{
await error.WriteLineAsync(problem).ConfigureAwait(false);
await error.WriteLineAsync("Uso: --simula 30g --profilo prudente|equilibrato|rapido [--csv percorso.csv] [--seme numero]").ConfigureAwait(false);
return 2;
}
var folder = Path.Combine(Path.GetTempPath(), "febe-simulazione-" + Guid.NewGuid().ToString("N")[..10]);
Directory.CreateDirectory(folder);
try
{
var report = await EngineSimulation.RunAsync(
options,
async token => await FebeDatabase.OpenAsync(folder, token).ConfigureAwait(false),
ct).ConfigureAwait(false);
await output.WriteAsync(report.ToText()).ConfigureAwait(false);
if (csv is not null)
{
await report.WriteCsvAsync(csv, ct).ConfigureAwait(false);
await output.WriteLineAsync($"Resoconto CSV scritto in {csv}").ConfigureAwait(false);
}
return report.Overruns == 0 && report.OverrunsOfFullBudgets == 0 ? 0 : 1;
}
finally
{
try
{
Directory.Delete(folder, recursive: true);
}
catch (IOException)
{
}
catch (UnauthorizedAccessException)
{
}
}
}
internal static bool TryParse(string[] args, out SimulationOptions options, out string? csv, out string problem)
{
options = new SimulationOptions();
csv = null;
problem = string.Empty;
for (var i = 0; i < args.Length; i++)
{
var arg = args[i];
string? Next() => i + 1 < args.Length ? args[++i] : null;
switch (arg.ToLowerInvariant())
{
case Flag:
{
var value = Next();
var digits = value?.TrimEnd('g', 'G');
if (!int.TryParse(digits, NumberStyles.Integer, CultureInfo.InvariantCulture, out var days) || days < 1 || days > 366)
{
problem = $"Durata non valida: «{value}». Scrivi per esempio 30g.";
return false;
}
options = options with { Days = days };
break;
}
case "--profilo":
{
var value = Next();
CautionProfileKind? kind = value?.ToLowerInvariant() switch
{
"prudente" => CautionProfileKind.Prudent,
"equilibrato" => CautionProfileKind.Balanced,
"rapido" => CautionProfileKind.Fast,
_ => null,
};
if (kind is null)
{
problem = $"Profilo sconosciuto: «{value}». I profili sono prudente, equilibrato, rapido.";
return false;
}
options = options with { Profile = kind.Value };
break;
}
case "--csv":
csv = Next();
if (string.IsNullOrWhiteSpace(csv))
{
problem = "Dopo --csv serve il percorso del file.";
return false;
}
break;
case "--seme":
{
var value = Next();
if (!int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out var seed))
{
problem = $"Seme non valido: «{value}».";
return false;
}
options = options with { Seed = seed };
break;
}
default:
problem = $"Argomento sconosciuto: «{arg}».";
return false;
}
}
return true;
}
}
@@ -0,0 +1,120 @@
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class AccountPlanCalculatorTests
{
private static Account Make(string name, bool followed, Frequency frequency = Frequency.Normal, AccountState state = AccountState.UpToDate, int? posts = null, long id = 0) =>
Account.Create(name, StartingPoint.EverythingAndKeepUpdated, EngineTestBed.Noon, EngineTestBed.Zone) with
{
Id = id,
IsFollowed = followed,
Frequency = frequency,
State = state,
PostCount = posts,
};
[TestMethod]
public void AProfileNotFollowedIsCheckedEveryThreeHoursAtNormalFrequency()
{
var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("studio.lumen.demo", followed: false) with { ContentTypes = ContentTypes.PostPhotos | ContentTypes.PostVideos },
Profile = CautionProfile.Prudent with { GradualStart = false },
});
Assert.AreEqual(TimeSpan.FromHours(3), estimate.ProfileCheckWanted);
Assert.IsTrue(estimate.ProfileCheckEvery!.Value.TotalHours is > 2.9 and < 3.3);
Assert.IsFalse(estimate.OverBudget);
Assert.AreEqual(100, estimate.DailyProfileBudget);
var posts = estimate.Lines.Single(l => l.Title == "Nuovi post").Text;
StringAssert.Contains(posts, "ogni 3 ore circa");
StringAssert.Contains(posts, "tra le 7:30 e le 23:30");
Assert.AreEqual("spente.", estimate.Lines.Single(l => l.Title == "Storie").Text);
Assert.IsEmpty(estimate.Warnings);
}
[TestMethod]
public void FollowedProfilesAreDiscoveredByTheSweepAndStoriesGetThreeChecksADay()
{
var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("marta.demo", followed: true, Frequency.Low),
Profile = CautionProfile.Prudent,
});
StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Nuovi post").Text, "giro dei profili che segui");
StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Nuovi post").Text, "20–90 minuti");
Assert.IsTrue(estimate.StoryInterval <= TimeSpan.FromHours(16) / 3);
Assert.IsTrue(estimate.StoryChecksPerDay >= 3);
StringAssert.Contains(estimate.Lines.Single(l => l.Title == "Storie").Text, "almeno 3 volte al giorno");
Assert.IsTrue(estimate.Warnings.Any(w => w.Contains("avvio graduale", StringComparison.Ordinal)));
}
[TestMethod]
public void TheBackfillEstimateUsesThePostCountWhenKnown()
{
var profile = CautionProfile.Prudent with { GradualStart = false };
var known = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("storico.demo", followed: true, state: AccountState.Backfilling, posts: 2000) with { BackfillCompletedAt = null },
Profile = profile,
ArchivedPosts = 500,
});
Assert.AreEqual(1500, known.BackfillRemainingPosts);
Assert.AreEqual(5, known.BackfillDays, "1.500 posts at 300 a day.");
StringAssert.Contains(known.Lines.Single(l => l.Title == "Storico").Text, "mancano 1.500 post, servono circa 5 giorni");
var unknown = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("nuovo.demo", followed: true, state: AccountState.Backfilling) with { BackfillCompletedAt = null },
Profile = profile,
});
Assert.IsNull(unknown.BackfillDays);
StringAssert.Contains(unknown.Lines.Single(l => l.Title == "Storico").Text, "non è ancora noto");
// Shared with other accounts in backfill, within the daily budget of history pages (100 × 12 posts).
var others = Enumerable.Range(1, 7).Select(i => Make($"altro{i}.demo", true, state: AccountState.Backfilling, id: i) with { BackfillCompletedAt = null }).ToList();
var shared = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("storico.demo", followed: true, state: AccountState.Backfilling, posts: 2000, id: 100) with { BackfillCompletedAt = null },
OtherAccounts = others,
Profile = profile,
});
Assert.AreEqual(14, shared.BackfillDays, "2.000 posts at 150 a day (1.200 shared by 8 accounts).");
}
[TestMethod]
public void TooManyAccountsMakeTheChecksSparserWithAWarning()
{
var others = Enumerable.Range(1, 40).Select(i => Make($"pubblico{i}.demo", false, Frequency.High, id: i)).ToList();
var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("studio.demo", followed: false, id: 500),
OtherAccounts = others,
Profile = CautionProfile.Prudent with { GradualStart = false },
});
Assert.IsTrue(estimate.OverBudget);
Assert.IsTrue(estimate.TotalProfileOpensPerDay > 100);
Assert.IsTrue(estimate.ProfileCheckEvery > estimate.ProfileCheckWanted, "Sparser, not forced.");
Assert.IsTrue(estimate.Warnings.Any(w => w.Contains("si diradano", StringComparison.Ordinal)));
Assert.IsTrue(estimate.ShareOfDailyBudget < 0.1);
}
[TestMethod]
public void AccountsThatAreNotContactedCostNothing()
{
var estimate = AccountPlanCalculator.Calculate(new AccountPlanInput
{
Account = Make("archivio.demo", followed: false, state: AccountState.ArchiveOnly),
Profile = CautionProfile.Prudent,
});
Assert.IsFalse(estimate.Contacted);
Assert.AreEqual(0, estimate.ProfileOpensPerDay);
StringAssert.Contains(estimate.Lines[0].Text, "Solo archivio");
}
}
@@ -0,0 +1,165 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Storage;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class CircuitBreakerTests
{
private static Signal Throttle(DateTimeOffset at) => new(SignalLevel.Throttle, "http-429", "https://sito.prova/api", at);
[TestMethod]
public async Task ThrottlesStopOneSixAndTwentyFourHoursThenHalveTheBudgets()
{
await using var bed = await EngineTestBed.CreateAsync();
var breaker = bed.Breaker;
var t0 = bed.Clock.Now;
await breaker.ReportAsync(Throttle(t0));
Assert.AreEqual(BreakerStatus.Throttled, breaker.State.Status);
Assert.AreEqual(t0 + TimeSpan.FromHours(1), breaker.State.Until);
Assert.IsFalse(breaker.State.AllowsSiteActions);
bed.Clock.Advance(TimeSpan.FromHours(1));
Assert.AreEqual(BreakerStatus.Closed, breaker.State.Status);
Assert.AreEqual(t0 + TimeSpan.FromHours(1) + TimeSpan.FromHours(48), breaker.State.HalvedBudgetsUntil);
bed.Clock.Advance(TimeSpan.FromHours(1));
await breaker.ReportAsync(Throttle(bed.Clock.Now));
Assert.AreEqual(bed.Clock.Now + TimeSpan.FromHours(6), breaker.State.Until, "Second within 24 hours: 6 hours.");
bed.Clock.Advance(TimeSpan.FromHours(7));
Assert.IsTrue(breaker.State.AllowsSiteActions);
await breaker.ReportAsync(Throttle(bed.Clock.Now));
Assert.AreEqual(bed.Clock.Now + TimeSpan.FromHours(24), breaker.State.Until, "Third within 24 hours: 24 hours.");
bed.Clock.Advance(TimeSpan.FromHours(24));
Assert.IsTrue(breaker.State.AllowsSiteActions);
await breaker.FlushAsync();
var incidents = await bed.Db.Incidents.ListAsync(t0, bed.Clock.Now.AddSeconds(1));
Assert.HasCount(3, incidents);
Assert.IsTrue(incidents.All(i => i.Level == SignalLevel.Throttle && i.Signal == "http-429" && i.Url == "https://sito.prova/api"));
Assert.AreEqual(t0 + TimeSpan.FromHours(1), incidents[0].StoppedUntil);
Assert.AreEqual(incidents[0].StoppedUntil, incidents[0].ResolvedAt);
Assert.IsTrue(incidents.All(i => i.ResolvedAt is not null));
Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
var events = await bed.Db.Events.ListAsync(new EventQuery());
Assert.AreEqual(3, events.Count(e => e.Code == EngineEventCodes.ThrottleStop));
Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.ThrottleEnd));
}
[TestMethod]
public async Task AThrottleDuringAStopDoesNotEscalateIt()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
var until = bed.Breaker.State.Until;
bed.Clock.Advance(TimeSpan.FromMinutes(10));
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
Assert.AreEqual(until, bed.Breaker.State.Until);
await bed.Breaker.FlushAsync();
Assert.HasCount(1, await bed.Db.Incidents.ListAsync(bed.Clock.Now.AddDays(-1), bed.Clock.Now.AddDays(1)));
}
[TestMethod]
[DataRow(SignalLevel.Challenge, BreakerStatus.Challenge, EngineEventCodes.ChallengeStop)]
[DataRow(SignalLevel.Disconnect, BreakerStatus.Disconnected, EngineEventCodes.DisconnectStop)]
public async Task VerificationAndDisconnectionNeverRestartAlone(SignalLevel level, BreakerStatus status, string code)
{
await using var bed = await EngineTestBed.CreateAsync(gradualStart: true);
await bed.Breaker.ReportAsync(new Signal(level, "segnale-prova", "https://sito.prova/x", bed.Clock.Now));
Assert.AreEqual(status, bed.Breaker.State.Status);
bed.Clock.Advance(TimeSpan.FromDays(5));
Assert.AreEqual(status, bed.Breaker.State.Status);
Assert.IsFalse(bed.Breaker.State.AllowsSiteActions);
var open = await bed.Db.Incidents.ListOpenAsync();
Assert.HasCount(1, open);
Assert.AreEqual(level, open[0].Level);
Assert.IsNull(open[0].StoppedUntil);
var resumedAt = bed.Clock.Now;
Assert.IsTrue(await bed.Breaker.ResumeAsync());
Assert.AreEqual(BreakerStatus.Closed, bed.Breaker.State.Status);
Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
// The resume starts the gradual start again, persisted.
Assert.AreEqual(resumedAt, bed.Runtime.RampStart);
Assert.AreEqual(resumedAt.ToUnixTimeMilliseconds(), await bed.Db.Settings.GetInt64Async(EngineSettingKeys.RampStart));
Assert.AreEqual(0.5, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Factor, 1e-9);
var events = await bed.Db.Events.ListAsync(new EventQuery());
Assert.IsTrue(events.Any(e => e.Code == code && e.Severity == EventSeverity.Error));
Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.Resumed));
}
[TestMethod]
public async Task AThrottleStopCannotBeShortenedByResume()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
Assert.IsFalse(await bed.Breaker.ResumeAsync());
Assert.AreEqual(BreakerStatus.Throttled, bed.Breaker.State.Status);
}
[TestMethod]
public async Task TheStateIsRestoredFromTheDatabase()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
var until = bed.Breaker.State.Until;
await bed.Breaker.FlushAsync();
var restarted = await bed.ReopenAsync(seed: 99);
Assert.AreEqual(BreakerStatus.Throttled, restarted.Breaker.State.Status);
Assert.AreEqual(until, restarted.Breaker.State.Until);
bed.Clock.Advance(TimeSpan.FromHours(2));
await restarted.Breaker.ReportAsync(new Signal(SignalLevel.Challenge, "challenge-url", null, bed.Clock.Now));
var again = await bed.ReopenAsync(seed: 100);
Assert.AreEqual(BreakerStatus.Challenge, again.Breaker.State.Status);
Assert.IsNotNull(again.Breaker.State.HalvedBudgetsUntil, "The halving of the earlier throttle is restored too.");
// The expired throttle was resolved; resuming the verification leaves nothing open.
bed.Clock.Advance(TimeSpan.FromHours(1));
Assert.IsTrue(await again.Breaker.ResumeAsync());
Assert.HasCount(0, await bed.Db.Incidents.ListOpenAsync());
}
[TestMethod]
public async Task ThreeThrottlesInSevenDaysProposeAMorePrudentProfile()
{
await using var bed = await EngineTestBed.CreateAsync(profile: CautionProfileKind.Fast);
for (var i = 0; i < 3; i++)
{
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
bed.Clock.Advance(TimeSpan.FromDays(2));
_ = bed.Breaker.State;
}
await bed.Breaker.FlushAsync();
var proposals = (await bed.Db.Events.ListAsync(new EventQuery())).Where(e => e.Code == EngineEventCodes.ProposeMorePrudence).ToList();
Assert.HasCount(1, proposals);
StringAssert.Contains(proposals[0].Message, "«Equilibrato»");
}
[TestMethod]
public async Task TwoThrottlesInSevenDaysAreNotYetAProposal()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
bed.Clock.Advance(TimeSpan.FromDays(8));
_ = bed.Breaker.State;
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
bed.Clock.Advance(TimeSpan.FromDays(2));
_ = bed.Breaker.State;
await bed.Breaker.ReportAsync(Throttle(bed.Clock.Now));
await bed.Breaker.FlushAsync();
Assert.IsFalse((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.ProposeMorePrudence));
}
}
@@ -0,0 +1,93 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class DayPlannerTests
{
[TestMethod]
public async Task TheWindowMovesEveryDayWithinTheJitterAndNotUniformly()
{
await using var bed = await EngineTestBed.CreateAsync();
var planner = bed.Services.Planner;
var profile = CautionProfile.Prudent;
var day = new DateOnly(2026, 10, 14);
var starts = new List<double>();
for (var i = 0; i < 300; i++)
{
var d = day.AddDays(i);
var window = await planner.GetWindowAsync(d);
Assert.IsNotNull(window);
var baseStart = LocalCalendar.FromLocal(d.ToDateTime(profile.WindowStart), EngineTestBed.Zone);
var baseEnd = LocalCalendar.FromLocal(d.ToDateTime(profile.WindowEnd), EngineTestBed.Zone);
var shiftStart = (window!.Start - baseStart).TotalMinutes;
var shiftEnd = (window.End - baseEnd).TotalMinutes;
Assert.IsTrue(Math.Abs(shiftStart) <= 40, $"start shift {shiftStart}");
Assert.IsTrue(Math.Abs(shiftEnd) <= 40, $"end shift {shiftEnd}");
starts.Add(shiftStart);
}
Assert.IsTrue(starts.Distinct().Count() > 250, "Every day has its own shift.");
// A normal shape: far more draws in the central half than a uniform draw would give (50%).
var central = starts.Count(s => Math.Abs(s) <= 20) / (double)starts.Count;
Assert.IsTrue(central > 0.62, $"central share {central}");
}
[TestMethod]
public async Task TheDailyShiftIsNotRedrawnAfterARestart()
{
await using var bed = await EngineTestBed.CreateAsync();
var day = new DateOnly(2026, 10, 20);
var before = await bed.Services.Planner.GetWindowAsync(day);
var restarted = await bed.ReopenAsync(seed: 12345);
var after = await restarted.Planner.GetWindowAsync(day);
Assert.AreEqual(before, after);
}
[TestMethod]
public async Task AWindowMayEndAfterMidnight()
{
await using var bed = await EngineTestBed.CreateAsync(profile: CautionProfileKind.Fast);
var day = new DateOnly(2026, 10, 14);
var window = await bed.Services.Planner.GetWindowAsync(day);
Assert.IsNotNull(window);
Assert.AreEqual(day.AddDays(1), LocalCalendar.Today(window!.End, EngineTestBed.Zone), "06:30–00:30 ends on the next day.");
// Ten minutes before the end, after midnight, the instant belongs to the window of the previous day.
var lateNight = window.End - TimeSpan.FromMinutes(10);
var found = await bed.Services.Planner.GetWindowAtAsync(lateNight);
Assert.AreEqual(window, found);
Assert.IsNull(await bed.Services.Planner.GetWindowAtAsync(window.End + TimeSpan.FromMinutes(10)));
}
[TestMethod]
public async Task InactiveDaysHaveNoWindow()
{
var weekdays = new HashSet<DayOfWeek> { DayOfWeek.Monday, DayOfWeek.Tuesday, DayOfWeek.Wednesday, DayOfWeek.Thursday, DayOfWeek.Friday };
await using var bed = await EngineTestBed.CreateAsync(settings: new EngineSettings { GradualStart = false, ActiveDays = weekdays });
var saturday = new DateOnly(2026, 10, 17);
Assert.IsNull(await bed.Services.Planner.GetWindowAsync(saturday));
var next = await bed.Services.Planner.GetNextWindowAsync(LocalCalendar.StartOfDay(saturday, EngineTestBed.Zone).AddHours(12));
Assert.AreEqual(new DateOnly(2026, 10, 19), next!.Day);
}
[TestMethod]
public void WindowsAreComputedAcrossDaylightSavingTime()
{
// 25 October 2026: clocks go back in Rome at 3:00; the window is still 07:30–23:30 local time.
var profile = CautionProfile.Prudent with { WindowJitter = TimeSpan.Zero };
var window = DayPlanner.Compute(new DateOnly(2026, 10, 25), profile, 42, EngineTestBed.Zone);
Assert.AreEqual(new TimeOnly(7, 30), TimeOnly.FromDateTime(LocalCalendar.ToLocal(window.Start, EngineTestBed.Zone)));
Assert.AreEqual(new TimeOnly(23, 30), TimeOnly.FromDateTime(LocalCalendar.ToLocal(window.End, EngineTestBed.Zone)));
Assert.AreEqual(TimeSpan.FromHours(16), window.Length);
// 28 March 2027: clocks go forward at 2:00; a window from 22:00 to 6:00 loses that hour.
var night = profile with { WindowStart = new TimeOnly(22, 0), WindowEnd = new TimeOnly(6, 0) };
var spring = DayPlanner.Compute(new DateOnly(2027, 3, 27), night, 42, EngineTestBed.Zone);
Assert.AreEqual(TimeSpan.FromHours(7), spring.Length);
}
}
+473
View File
@@ -0,0 +1,473 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Storage;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class EngineHostTests
{
private static readonly DateTimeOffset Morning = EngineTestBed.Local(2026, 10, 14, 6, 0);
private static async Task<IReadOnlyList<SessionRecord>> SessionsAsync(EngineTestBed bed) =>
await bed.Db.Sessions.ListAsync(bed.Clock.Now.AddDays(-30), bed.Clock.Now.AddDays(1));
[TestMethod]
public async Task SessionsStayInsideTheWindowAndRespectThePauseFloor()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
await bed.AddAccountAsync("due.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(2));
var sessions = await SessionsAsync(bed);
Assert.IsTrue(sessions.Count > 20, $"{sessions.Count} sessions");
for (var i = 1; i < sessions.Count; i++)
{
var pause = sessions[i].StartedAt - sessions[i - 1].EndedAt!.Value;
Assert.IsTrue(pause >= TimeSpan.FromMinutes(20), $"pause of {pause}");
}
foreach (var session in sessions)
{
Assert.IsNotNull(await bed.Services.Planner.GetWindowAtAsync(session.StartedAt), $"session at {session.StartedAt:O}");
}
Assert.HasCount(0, await BudgetAudit.OutsideWindowAsync(bed.Db, bed.Services.Planner, Morning, bed.Clock.Now));
Assert.HasCount(0, await BudgetAudit.OverrunsAsync(bed.Db, bed.Runtime.Profile, EngineTestBed.Zone, Morning, bed.Clock.Now));
Assert.AreEqual(sessions.Count(s => s.EndedAt is not null), runner.Rests, "Every session ends on the empty page.");
// The first session comes 2–10 minutes after the start, but not before the window.
var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
Assert.IsTrue(sessions[0].StartedAt >= window!.Start);
}
[TestMethod]
public async Task TheFirstSessionComesTwoToTenMinutesAfterTheStart()
{
await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Noon);
await bed.AddAccountAsync("uno.demo", followed: true);
bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunForAsync(TimeSpan.FromMinutes(30));
var first = (await SessionsAsync(bed))[0].StartedAt - EngineTestBed.Noon;
Assert.IsTrue(first >= TimeSpan.FromMinutes(2) && first <= TimeSpan.FromMinutes(10), $"first session after {first}");
}
[TestMethod]
public async Task ARestartResetsNoCountsAndDoesNotShortenPauses()
{
// 60 profiles a day, and no hourly limit in the way: demand is far above it.
var custom = CautionProfile.Prudent with
{
Budgets = new Dictionary<ActionKind, Budget>(CautionProfile.Prudent.Budgets) { [ActionKind.ProfileOpen] = new Budget(60, 60) },
};
await using var bed = await EngineTestBed.CreateAsync(Morning, settings: new EngineSettings { GradualStart = false }.WithCustomValues(custom));
for (var i = 0; i < 30; i++)
{
await bed.AddAccountAsync($"pubblico{i}.demo", followed: false, Frequency.High, types: ContentTypes.PostPhotos | ContentTypes.PostVideos);
}
await bed.AddAccountAsync("seguito.demo", followed: true);
bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
await bed.RunUntilAsync(window!.Start + TimeSpan.FromMinutes(70));
var openedBefore = await bed.Db.ActionLog.SumAsync(ActionKind.ProfileOpen, Morning, bed.Clock.Now);
Assert.IsTrue(openedBefore is > 0 and < 60, $"{openedBefore} profiles opened before the restart");
await bed.StopAsync();
var plannedNext = DateTimeOffset.FromUnixTimeMilliseconds((await bed.Db.Settings.GetInt64Async(EngineSettingKeys.NextSession))!.Value);
var lastEnd = (await SessionsAsync(bed)).Max(s => s.EndedAt!.Value);
var restartAt = bed.Clock.Now + TimeSpan.FromMinutes(1);
bed.Clock.AdvanceTo(restartAt);
await bed.ReopenAsync(seed: 4242);
bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 0, 0));
var after = (await SessionsAsync(bed)).Where(s => s.StartedAt >= restartAt).ToList();
Assert.IsNotEmpty(after);
Assert.IsTrue(after[0].StartedAt >= plannedNext, "Not earlier than the session planned before the restart.");
Assert.IsTrue(after[0].StartedAt - lastEnd >= TimeSpan.FromMinutes(20), "The pause floor holds across the restart.");
Assert.IsTrue(after[0].StartedAt - restartAt >= TimeSpan.FromMinutes(2));
// Demand is far above the budget: the day ends exactly at the daily budget, counting the morning before the restart.
var openedToday = await bed.Db.ActionLog.SumAsync(ActionKind.ProfileOpen, Morning, bed.Clock.Now);
Assert.AreEqual(60L, openedToday);
Assert.HasCount(0, await BudgetAudit.OverrunsAsync(bed.Db, bed.Runtime.Profile, EngineTestBed.Zone, Morning, bed.Clock.Now));
}
[TestMethod]
public async Task RepeatedRestartsDoNotProduceMoreSessions()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
await bed.AddAccountAsync("uno.demo", followed: true);
var seed = 500;
for (var hour = 0; hour < 18; hour++)
{
bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunForAsync(TimeSpan.FromMinutes(59));
await bed.StopAsync();
await bed.ReopenAsync(++seed);
}
var sessions = await SessionsAsync(bed);
for (var i = 1; i < sessions.Count; i++)
{
Assert.IsTrue(sessions[i].StartedAt - sessions[i - 1].EndedAt!.Value >= TimeSpan.FromMinutes(20));
}
// A program that stays on makes at most 16 h / 20 min sessions in a window; restarts every hour stay well below.
Assert.IsTrue(sessions.Count <= 48, $"{sessions.Count} sessions");
}
[TestMethod]
public async Task MostSessionsOpenWithTheSweepAndAccountsComeInRandomOrder()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
for (var i = 0; i < 8; i++)
{
await bed.AddAccountAsync($"pubblico{i}.demo", followed: false, Frequency.High, types: ContentTypes.PostPhotos | ContentTypes.PostVideos);
}
await bed.AddAccountAsync("seguito.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(3));
var bySession = runner.Runs.GroupBy(r => r.SessionId).ToList();
var openedWithSweep = bySession.Count(g => g.First().Request.Kind == RecipeKind.FollowingSweep) / (double)bySession.Count;
Assert.IsTrue(openedWithSweep is > 0.75 and < 0.99, $"sweep first in {openedWithSweep:P0} of sessions");
var orders = bySession
.Select(g => string.Join(",", g.Where(r => r.Request.Kind == RecipeKind.ProfileCheck).Select(r => r.Request.AccountId)))
.Where(o => o.Contains(',', StringComparison.Ordinal))
.ToList();
Assert.IsTrue(orders.Distinct().Count() > orders.Count / 2, "The order of the accounts changes from session to session.");
// About one session in three stops after sweep and stories even with profile checks due.
var withChecks = bySession.Count(g => g.Any(r => r.Request.Kind == RecipeKind.ProfileCheck)) / (double)bySession.Count;
Assert.IsTrue(withChecks is > 0.45 and < 0.85, $"{withChecks:P0} of sessions with profile checks");
}
[TestMethod]
public async Task BackfillWaitsWhileTheAccountHasMoreThanSixtyFilesToDownload()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var account = await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, postCount: 3000);
for (var i = 0; i < 61; i++)
{
await bed.Db.Entries.AddAsync(
new Entry { AccountId = account.Id, Kind = EntryKind.Post, InstagramId = "attesa" + i, PublishedAt = Morning.AddDays(-400 + i), DiscoveredAt = Morning.AddDays(-1) },
[new Media { Position = 1, Kind = MediaKind.Photo, State = MediaState.ToDownload }]);
}
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(1));
Assert.IsFalse(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.BackfillWaiting && e.AccountId == account.Id));
// Down to 60 waiting files: the backfill goes on.
var pending = await bed.Db.Media.ListPendingDownloadsAsync(10);
await bed.Db.Media.MarkStoredAsync(pending[0].Media.Id, new StoredFile("post/a.jpg", 10, new string('a', 64)), MediaState.Downloaded, bed.Clock.Now);
await bed.RunUntilAsync(Morning.AddDays(2));
Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill && r.Request.AccountId == account.Id));
}
[TestMethod]
public async Task BackfillWaitsWhenTheDataBudgetIsReached()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, postCount: 3000);
await bed.Governor.RecordAsync(4L * 1024 * 1024 * 1024, null, CancellationToken.None);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
bed.Start(runner);
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 0, 0));
Assert.IsFalse(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 15, 23, 0));
Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.Backfill));
}
[TestMethod]
public async Task BackfillAlternatesAmongAccountsAndPausesAfterTheSingleDownload()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var first = await bed.AddAccountAsync("primo.demo", followed: true, state: AccountState.Backfilling, postCount: 500);
var second = await bed.AddAccountAsync("secondo.demo", followed: true, state: AccountState.Backfilling, postCount: 500);
await bed.Db.Accounts.UpdateAsync((await bed.Db.Accounts.GetAsync(second.Id))! with { KeepUpdated = false });
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var backfills = 0;
DateTimeOffset? finishedAt = null;
runner.Script = request =>
{
if (request.Kind != RecipeKind.Backfill || request.AccountId != second.Id || ++backfills < 3)
{
return null;
}
finishedAt = bed.Clock.Now;
return new RecipeOutcome(RecipeStatus.Completed, 1, 12) { BackfillFinished = true };
};
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(1));
var sequence = runner.Runs.Where(r => r.Request.Kind == RecipeKind.Backfill).Select(r => r.Request.AccountId!.Value).Take(4).ToList();
CollectionAssert.AreEqual(new[] { first.Id, second.Id, first.Id, second.Id }, sequence, "One account per session, alternating.");
Assert.IsTrue(runner.Runs.GroupBy(r => r.SessionId).All(g => g.Count(r => r.Request.Kind == RecipeKind.Backfill) <= 1));
var finished = await bed.Db.Accounts.GetAsync(second.Id);
Assert.AreEqual(AccountState.Paused, finished!.State, "«Tieni aggiornato» off: one download, then paused.");
Assert.IsNotNull(finished.BackfillCompletedAt);
Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.BackfillCompleted));
Assert.IsFalse(runner.Runs.Any(r => r.Request.AccountId == second.Id && r.At > finishedAt), "A paused account is not contacted.");
}
[TestMethod]
public async Task ThreeUnrecognizedFormatsInARowSuspendTheRecipe()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var account = await bed.AddAccountAsync("strano.demo", followed: false, Frequency.High);
var runner = new ScriptedRunner(bed.Governor, bed.Clock)
{
Script = r => r.Kind == RecipeKind.ProfileCheck ? new RecipeOutcome(RecipeStatus.UnrecognizedFormat, 1, 0) : null,
};
var host = bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(2));
Assert.AreEqual(3, runner.Runs.Count(r => r.Request.Kind == RecipeKind.ProfileCheck));
Assert.IsTrue(host.SuspendedRecipes.ContainsKey(RecipeKind.ProfileCheck));
var events = await bed.Db.Events.ListAsync(new EventQuery());
Assert.AreEqual(3, events.Count(e => e.Code == EngineEventCodes.FormatUnrecognized));
Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.RecipeSuspended && e.Severity == EventSeverity.Error));
Assert.IsTrue((await bed.Db.Accounts.GetAsync(account.Id))!.Notices.HasFlag(AccountNotices.UnrecognizedFormat));
var snapshot = await host.Monitor.GetSnapshotAsync();
Assert.HasCount(1, snapshot.SuspendedRecipes);
runner.Script = null;
Assert.IsTrue(await host.ResumeRecipeAsync(RecipeKind.ProfileCheck));
await bed.RunUntilAsync(Morning.AddDays(3));
Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.ProfileCheck && r.Status == RecipeStatus.Completed));
}
[TestMethod]
public async Task AnUnreachableAccountIsNotContactedAnyMore()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var account = await bed.AddAccountAsync("sparito.demo", followed: false, Frequency.High);
var runner = new ScriptedRunner(bed.Governor, bed.Clock)
{
Script = r => r.AccountId == account.Id ? new RecipeOutcome(RecipeStatus.AccountUnreachable, 1, 0) : null,
};
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(1));
Assert.AreEqual(1, runner.Runs.Count(r => r.Request.AccountId == account.Id));
Assert.AreEqual(AccountState.Unreachable, (await bed.Db.Accounts.GetAsync(account.Id))!.State);
Assert.IsTrue((await bed.Db.Events.ListAsync(new EventQuery())).Any(e => e.Code == EngineEventCodes.AccountUnreachable));
}
[TestMethod]
public async Task AThrottleClosesTheSessionAtOnceAndStopsForAnHour()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
await bed.AddAccountAsync("due.demo", followed: false, Frequency.High);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
DateTimeOffset? throttledAt = null;
runner.AfterGrant = r =>
{
if (throttledAt is null && r.Kind == RecipeKind.ProfileCheck)
{
throttledAt = bed.Clock.Now;
bed.Breaker.Report(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
}
};
bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(1));
Assert.IsNotNull(throttledAt);
var sessions = await SessionsAsync(bed);
var stopped = sessions.Single(s => s.StartedAt <= throttledAt && s.EndedAt >= throttledAt);
Assert.AreEqual(SessionOutcome.Throttled, stopped.Outcome);
Assert.IsTrue(stopped.EndedAt - throttledAt < TimeSpan.FromSeconds(30), "The session closes at once.");
var during = await bed.Db.ActionLog.ListAsync(throttledAt.Value.AddMilliseconds(1), throttledAt.Value + TimeSpan.FromHours(1));
Assert.HasCount(0, during.Where(a => a.Category != ActionKind.DataDownload).ToList());
Assert.IsTrue(sessions.Any(s => s.StartedAt > throttledAt.Value + TimeSpan.FromHours(1)), "It starts again by itself.");
}
[TestMethod]
public async Task AfterAVerificationNothingStartsUntilResumeWhichRestartsTheGradualStart()
{
await using var bed = await EngineTestBed.CreateAsync(Morning, gradualStart: true);
await bed.AddAccountAsync("uno.demo", followed: false, Frequency.High);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var challenged = false;
runner.AfterGrant = r =>
{
if (!challenged)
{
challenged = true;
bed.Breaker.Report(new Signal(SignalLevel.Challenge, "challenge-url", "https://sito.prova/challenge", bed.Clock.Now));
}
};
var host = bed.Start(runner);
await bed.RunUntilAsync(Morning.AddDays(3));
Assert.IsTrue(challenged);
Assert.AreEqual(1, runner.Runs.Count, "Nothing after the verification signal.");
Assert.AreEqual(0, runner.Rests, "The page is left as it is.");
var snapshot = await host.Monitor.GetSnapshotAsync();
Assert.AreEqual(EngineMode.StoppedForVerification, snapshot.Mode);
Assert.IsNotNull(snapshot.Banner);
Assert.AreEqual(BannerLevel.Error, snapshot.Banner!.Level);
var resume = await host.ResumeAsync();
Assert.IsTrue(resume.Resumed);
Assert.AreEqual(0.5, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Factor, 1e-9);
await bed.RunForAsync(TimeSpan.FromHours(6));
Assert.IsTrue(runner.Runs.Count > 1, "Work goes on after «Riprendi».");
}
[TestMethod]
public async Task PauseStopsEverythingUntilResume()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
await bed.AddAccountAsync("uno.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var host = bed.Start(runner);
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 10, 0));
await host.PauseAsync();
var count = runner.Runs.Count;
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 20, 0));
Assert.AreEqual(count, runner.Runs.Count);
Assert.AreEqual(EngineMode.Paused, (await host.Monitor.GetSnapshotAsync()).Mode);
Assert.IsTrue(await bed.Db.Settings.GetBoolAsync(EngineSettingKeys.Paused, false));
await host.ResumeAsync();
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 22, 0));
Assert.IsTrue(runner.Runs.Count > count);
}
[TestMethod]
public async Task WhileAlbertoUsesTheBrowserTheEngineDoesNotAct()
{
var driving = false;
await using var bed = await EngineTestBed.CreateAsync(Morning, userIsDriving: () => driving);
await bed.AddAccountAsync("uno.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var host = bed.Start(runner);
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 10, 0));
driving = true;
host.NotifyUserDrivingChanged();
var count = runner.Runs.Count;
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 14, 0));
Assert.AreEqual(count, runner.Runs.Count);
Assert.AreEqual(EngineMode.UserDriving, (await host.Monitor.GetSnapshotAsync()).Mode);
driving = false;
host.NotifyUserDrivingChanged();
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 16, 0));
Assert.IsTrue(runner.Runs.Count > count);
}
[TestMethod]
public async Task WithoutAnInstagramSessionNothingStarts()
{
var connected = false;
await using var bed = await EngineTestBed.CreateAsync(Morning, isConnected: () => connected);
await bed.AddAccountAsync("uno.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var host = bed.Start(runner);
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 14, 0));
Assert.IsEmpty(runner.Runs);
Assert.AreEqual(EngineMode.NotConnected, (await host.Monitor.GetSnapshotAsync()).Mode);
connected = true;
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 16, 0));
Assert.IsNotEmpty(runner.Runs);
}
[TestMethod]
public async Task CheckNowOutsideTheWindowNeedsConfirmationAndRunsOnlyThatCheck()
{
var night = EngineTestBed.Local(2026, 10, 14, 1, 0);
await using var bed = await EngineTestBed.CreateAsync(night);
var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
await bed.AddAccountAsync("altro.demo", followed: false, Frequency.High);
await bed.AddAccountAsync("seguito.demo", followed: true);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var host = bed.Start(runner);
await bed.RunForAsync(TimeSpan.FromMinutes(20));
Assert.IsEmpty(runner.Runs, "Nothing at night on the engine's initiative.");
var first = await host.CheckNowAsync(asked.Id);
Assert.AreEqual(CheckNowStatus.NeedsConfirmation, first.Status);
Assert.IsNotNull(first.ConfirmationToken);
StringAssert.Contains(first.Message, "fuori dalla fascia");
Assert.AreEqual(CheckNowStatus.NeedsConfirmation, (await host.CheckNowAsync(asked.Id, "gettone-sbagliato")).Status);
var confirmed = await host.CheckNowAsync(asked.Id, first.ConfirmationToken);
Assert.AreEqual(CheckNowStatus.Queued, confirmed.Status);
await bed.RunForAsync(TimeSpan.FromHours(2));
Assert.IsNotEmpty(runner.Runs);
Assert.IsTrue(runner.Runs.All(r => r.Request.AccountId == asked.Id), "Only the confirmed check.");
Assert.IsTrue(runner.Runs.Any(r => r.Request.Kind == RecipeKind.ProfileCheck && r.Request.Manual));
Assert.HasCount(1, runner.Runs.Select(r => r.SessionId).Distinct().ToList());
var actions = await bed.Db.ActionLog.ListAsync(night, bed.Clock.Now);
Assert.IsTrue(actions.All(a => a.AccountId == asked.Id));
// The token was used: a second check needs a new confirmation.
Assert.AreEqual(CheckNowStatus.NeedsConfirmation, (await host.CheckNowAsync(asked.Id, first.ConfirmationToken)).Status);
// Normal work waits for the window.
var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
await bed.RunUntilAsync(window!.Start + TimeSpan.FromHours(2));
Assert.IsTrue(runner.Runs.Where(r => r.Request.AccountId != asked.Id).All(r => r.At >= window.Start));
Assert.IsTrue(runner.Runs.Any(r => r.Request.AccountId != asked.Id));
}
[TestMethod]
public async Task CheckNowInsideTheWindowGoesOnTopOfTheQueueButAfterThePauseFloor()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var asked = await bed.AddAccountAsync("chiesto.demo", followed: true, Frequency.Low);
var runner = new ScriptedRunner(bed.Governor, bed.Clock);
var host = bed.Start(runner);
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 12, 0));
var before = runner.Runs.Count(r => r.Request.Manual);
var askedAt = bed.Clock.Now;
var result = await host.CheckNowAsync(asked.Id);
Assert.AreEqual(CheckNowStatus.Queued, result.Status);
StringAssert.Contains(result.Message, "cima alla coda");
await bed.RunForAsync(TimeSpan.FromMinutes(45));
var manual = runner.Runs.Where(r => r.Request.Manual).ToList();
Assert.AreEqual(before + 2, manual.Count, "Profile check and stories, on request.");
var session = (await SessionsAsync(bed)).Single(s => s.Id == manual[^1].SessionId);
var previous = (await SessionsAsync(bed)).Where(s => s.EndedAt <= session.StartedAt).Max(s => s.EndedAt!.Value);
Assert.IsTrue(session.StartedAt - previous >= TimeSpan.FromMinutes(20));
if (session.StartedAt >= askedAt)
{
Assert.IsTrue(runner.Runs.First(r => r.SessionId == session.Id).Request.Manual, "First thing of the session.");
}
}
[TestMethod]
public async Task CheckNowWithTheBudgetExhaustedIsRefused()
{
await using var bed = await EngineTestBed.CreateAsync(Morning);
var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
for (var i = 0; i < 100; i++)
{
await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = Morning.AddSeconds(i), Category = ActionKind.ProfileOpen });
}
var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 12, 0));
var result = await host.CheckNowAsync(asked.Id);
Assert.AreEqual(CheckNowStatus.Refused, result.Status);
StringAssert.Contains(result.Message, "tetto giornaliero");
}
}
@@ -0,0 +1,127 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class EngineMonitorTests
{
[TestMethod]
public async Task AtNightTheMonitorSaysWhenWorkResumes()
{
var night = EngineTestBed.Local(2026, 10, 14, 2, 0);
await using var bed = await EngineTestBed.CreateAsync(night);
await bed.AddAccountAsync("marta.demo", followed: true);
var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunForAsync(TimeSpan.FromMinutes(15));
var snapshot = await host.Monitor.GetSnapshotAsync();
Assert.AreEqual(EngineMode.OutsideWindow, snapshot.Mode);
Assert.AreEqual("Fuori fascia", snapshot.Headline);
StringAssert.Contains(snapshot.SidebarLine, "Riprende verso le ");
var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
Assert.AreEqual(window!.Start, snapshot.ResumesAround);
Assert.IsNull(snapshot.Banner);
Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.OutsideWindow && s.Start == snapshot.Today.Start));
Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.PlannedSession && s.Indicative));
Assert.IsTrue(snapshot.Queue.All(q => q.When.StartsWith("verso le", StringComparison.Ordinal)));
Assert.AreEqual(4, snapshot.MainBudgets.Count);
CollectionAssert.AreEqual(
new[] { ActionKind.ProfileOpen, ActionKind.StoryView, ActionKind.BackfillPage, ActionKind.DataDownload },
snapshot.MainBudgets.Select(b => b.Kind).ToArray());
Assert.AreEqual(Enum.GetValues<ActionKind>().Length, snapshot.AllBudgets.Count);
Assert.AreEqual("Profili aperti", snapshot.ProfilesOpenedToday.Label);
Assert.AreEqual("di 100", snapshot.ProfilesOpenedToday.LimitText);
}
[TestMethod]
public async Task DuringTheDayTheStripShowsSessionsRestsAndTheSummary()
{
await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 6, 0));
await bed.AddAccountAsync("marta.demo", followed: true);
await bed.AddAccountAsync("luca.demo", followed: false, Frequency.High);
var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunUntilAsync(EngineTestBed.Local(2026, 10, 14, 15, 0));
var snapshot = await host.Monitor.GetSnapshotAsync();
Assert.IsTrue(snapshot.Mode is EngineMode.Resting or EngineMode.InSession);
Assert.IsTrue(snapshot.Today.Spans.Count(s => s.Kind is StripSpanKind.Session or StripSpanKind.CurrentSession) >= 5);
Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.Rest));
StringAssert.Contains(snapshot.Today.Summary, "sessioni");
StringAssert.Contains(snapshot.Today.Summary, "nessun rallentamento");
Assert.IsNotEmpty(snapshot.RecentActions);
Assert.IsTrue(snapshot.RecentActions.Any(a => a.Title == "Giro dei profili che segui" || a.Title.StartsWith('@')));
if (snapshot.Mode == EngineMode.Resting)
{
Assert.AreEqual("In ascolto", snapshot.Headline);
StringAssert.StartsWith(snapshot.Details[0], "Riprende verso le ");
}
var profiles = snapshot.ProfilesOpenedToday;
Assert.IsTrue(profiles.UsedToday > 0);
StringAssert.StartsWith(profiles.Note, "In questa ora ");
}
[TestMethod]
public async Task AThrottleShowsAnAmberStripAndSuspendsTheQueue()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.AddAccountAsync("marta.demo", followed: true);
var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
await bed.RunForAsync(TimeSpan.FromMinutes(1));
await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
var snapshot = await host.Monitor.GetSnapshotAsync();
Assert.AreEqual(EngineMode.Throttled, snapshot.Mode);
Assert.AreEqual(BannerLevel.Warning, snapshot.Banner!.Level);
StringAssert.Contains(snapshot.Banner.Message, "tetti dimezzati");
Assert.IsTrue(snapshot.Queue.All(q => q.Suspended && q.When == "Sospeso"));
Assert.IsTrue(snapshot.Today.Spans.Any(s => s.Kind == StripSpanKind.Throttle));
StringAssert.StartsWith(snapshot.ProfilesOpenedToday.Note, "Fermo dalle ");
StringAssert.Contains(snapshot.ReductionNote!, "Tetti dimezzati");
}
[TestMethod]
public async Task TheEventStreamDeliversTimelineLines()
{
await using var bed = await EngineTestBed.CreateAsync();
var host = bed.Start(new ScriptedRunner(bed.Governor, bed.Clock));
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));
var received = new List<EngineNotification>();
var reading = Task.Run(async () =>
{
await foreach (var notification in host.Monitor.SubscribeAsync(cts.Token))
{
received.Add(notification);
if (notification.Kind == EngineNotificationKind.Event && notification.Event!.Code == EngineEventCodes.Paused)
{
break;
}
}
});
await Task.Delay(100);
await host.PauseAsync();
await reading;
Assert.IsTrue(received.Any(n => n.Event?.Code == EngineEventCodes.Paused));
StringAssert.Contains(received.Last().Event!.Message, "Riprendi");
}
[TestMethod]
public void ItalianTextUsesDotsCommasAndVersoLe()
{
Assert.AreEqual("7.682", ItalianText.Number(7682));
Assert.AreEqual("1.234.567", ItalianText.Number(1234567));
Assert.AreEqual("1,3 GB", ItalianText.Bytes((long)(1.3 * 1024 * 1024 * 1024)));
Assert.AreEqual("0,5", ItalianText.Decimal(0.5));
var zone = EngineTestBed.Zone;
var now = EngineTestBed.Local(2026, 10, 14, 12, 0);
Assert.AreEqual("verso le 15:30", ItalianText.Around(EngineTestBed.Local(2026, 10, 14, 15, 30), now, zone));
Assert.AreEqual("domani verso le 7:42", ItalianText.Around(EngineTestBed.Local(2026, 10, 15, 7, 42), now, zone));
Assert.AreEqual("verso l'1:05", ItalianText.Around(EngineTestBed.Local(2026, 10, 14, 13, 5).AddHours(12), now.AddHours(12), zone));
Assert.AreEqual("1 ora e 20 minuti", ItalianText.Duration(TimeSpan.FromMinutes(80)));
Assert.AreEqual("ogni 75 minuti", ItalianText.Every(TimeSpan.FromMinutes(75)));
Assert.AreEqual("ogni 3 ore", ItalianText.Every(TimeSpan.FromHours(3)));
}
}
@@ -0,0 +1,95 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Data;
using Febe.Tests.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class EngineSettingsTests
{
[TestMethod]
public async Task SettingsAreStoredAndReadBackWithACustomProfile()
{
using var folder = new TempFolder("impostazioni");
await using var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
Assert.AreEqual(CautionProfileKind.Prudent, (await EngineSettingsStore.LoadAsync(db.Settings)).ProfileKind, "«Prudente» is the default.");
var custom = CautionProfile.Balanced with
{
PauseMin = TimeSpan.FromMinutes(15),
WindowStart = new TimeOnly(8, 0),
WindowEnd = new TimeOnly(0, 30),
Budgets = new Dictionary<ActionKind, Budget>(CautionProfile.Balanced.Budgets) { [ActionKind.ProfileOpen] = new Budget(18, 150) },
};
var settings = new EngineSettings { Pace = GesturePace.Slow, GradualStart = false, ActiveDays = new HashSet<DayOfWeek> { DayOfWeek.Monday, DayOfWeek.Saturday } }
.WithCustomValues(custom);
await EngineSettingsStore.SaveAsync(db.Settings, settings);
var loaded = await EngineSettingsStore.LoadAsync(db.Settings);
Assert.AreEqual(CautionProfileKind.Custom, loaded.ProfileKind);
Assert.AreEqual(GesturePace.Slow, loaded.Pace);
Assert.IsFalse(loaded.GradualStart);
CollectionAssert.AreEquivalent(new[] { DayOfWeek.Monday, DayOfWeek.Saturday }, loaded.ActiveDays.ToArray());
var effective = loaded.EffectiveProfile;
Assert.AreEqual(CautionProfileKind.Custom, effective.Kind);
Assert.AreEqual(TimeSpan.FromMinutes(15), effective.PauseMin);
Assert.AreEqual(new TimeOnly(0, 30), effective.WindowEnd);
Assert.AreEqual(new Budget(18, 150), effective.Budgets[ActionKind.ProfileOpen]);
Assert.AreEqual(CautionProfile.Balanced.DataPerDayBytes, effective.DataPerDayBytes);
Assert.AreEqual(GesturePace.Slow, effective.Pace);
}
[TestMethod]
public void TheLimitsOfTheInterfaceAreEnforced()
{
var bad = CautionProfile.Fast with
{
PauseMin = TimeSpan.FromMinutes(4),
SessionMax = TimeSpan.FromMinutes(31),
WindowStart = new TimeOnly(5, 0),
WindowEnd = new TimeOnly(2, 0),
Budgets = new Dictionary<ActionKind, Budget>(CautionProfile.Fast.Budgets) { [ActionKind.StoryView] = new Budget(241, 800) },
DataPerDayBytes = CautionProfile.Limits.MaxDataPerDayBytes + 1,
};
var errors = CautionProfileRules.Validate(bad);
Assert.IsTrue(errors.Any(e => e.Contains("5 minuti", StringComparison.Ordinal)));
Assert.IsTrue(errors.Any(e => e.Contains("30 minuti", StringComparison.Ordinal)));
Assert.IsTrue(errors.Any(e => e.Contains("20 ore", StringComparison.Ordinal)));
Assert.IsTrue(errors.Any(e => e.Contains("storie viste", StringComparison.Ordinal)));
Assert.IsTrue(errors.Any(e => e.Contains("dati scaricati", StringComparison.Ordinal)));
Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Fast));
Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Prudent));
Assert.HasCount(0, CautionProfileRules.Validate(CautionProfile.Balanced));
Assert.AreEqual(TimeSpan.FromHours(18), CautionProfileRules.WindowLength(new TimeOnly(6, 30), new TimeOnly(0, 30)));
}
[TestMethod]
public async Task InvalidSettingsAreNotStored()
{
using var folder = new TempFolder("impostazioni");
await using var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
var settings = new EngineSettings().WithCustomValues(CautionProfile.Prudent with { PauseMin = TimeSpan.FromMinutes(1) });
var error = await Assert.ThrowsAsync<ArgumentException>(() => EngineSettingsStore.SaveAsync(db.Settings, settings));
StringAssert.Contains(error.Message, "pausa minima");
Assert.IsNull(await db.Settings.GetAsync(EngineSettingKeys.Profile));
}
[TestMethod]
public void TheCustomProfileSurvivesTheJsonRoundTrip()
{
var custom = CautionProfile.Fast with { Kind = CautionProfileKind.Custom, WindowJitter = TimeSpan.FromMinutes(25), RampUpDays = 10 };
var decoded = CautionProfileCodec.TryDecode(CautionProfileCodec.Encode(custom));
Assert.IsNotNull(decoded);
Assert.AreEqual(custom.WindowJitter, decoded!.WindowJitter);
Assert.AreEqual(10, decoded.RampUpDays);
foreach (var (kind, budget) in custom.Budgets)
{
Assert.AreEqual(budget, decoded.Budgets[kind]);
}
Assert.IsNull(CautionProfileCodec.TryDecode("{non è json"));
Assert.IsNull(CautionProfileCodec.TryDecode("{}"));
}
}
@@ -0,0 +1,174 @@
using System.Text;
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Simulation;
using Febe.Core.Storage;
using Febe.Data;
using Febe.Tests.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class EngineSimulationTests
{
private static async Task<SimulationReport> SimulateAsync(SimulationOptions options)
{
using var folder = new TempFolder("simula");
return await EngineSimulation.RunAsync(options, async ct => await FebeDatabase.OpenAsync(folder.Combine("dati"), ct));
}
[TestMethod]
[DataRow(CautionProfileKind.Prudent)]
[DataRow(CautionProfileKind.Balanced)]
[DataRow(CautionProfileKind.Fast)]
public async Task EveryProfileRunsAWeekWithoutExceedingAnyBudget(CautionProfileKind profile)
{
var report = await SimulateAsync(new SimulationOptions { Days = 7, Profile = profile, Seed = 3 });
Assert.AreEqual(0, report.Overruns, string.Join("\n", report.OverrunDetails));
Assert.AreEqual(0, report.OverrunsOfFullBudgets);
Assert.AreEqual(0, report.ActionsOutsideWindow);
Assert.AreEqual(0, report.PauseFloorViolations);
Assert.IsTrue(report.ShortestPause >= CautionProfile.For(profile).PauseMin);
Assert.IsTrue(report.SessionStartCv >= 0.35, $"CV {report.SessionStartCv}");
Assert.IsTrue(report.SessionsPerDayMean > 5);
Assert.IsTrue(report.BackfillStored > 0);
Assert.IsTrue(report.FollowedPosts.Count > 0 && report.Stories.Count > 0);
var text = report.ToText();
StringAssert.Contains(text, "Sessioni");
StringAssert.Contains(text, "superamenti dei tetti: 0");
StringAssert.Contains(text, "Storico di 2.000 post");
var csv = report.ToCsv();
Assert.HasCount(report.Days.Count + 1, csv.Split('\n', StringSplitOptions.RemoveEmptyEntries));
StringAssert.StartsWith(csv, "giorno;sessioni;");
}
[TestMethod]
public async Task HeavyDemandSmallDataBudgetAndFrequentThrottlesStillExceedNothing()
{
var custom = CautionProfile.Prudent with
{
Kind = CautionProfileKind.Custom,
DataPerDayBytes = 150L * 1024 * 1024,
Budgets = new Dictionary<ActionKind, Budget>(CautionProfile.Prudent.Budgets) { [ActionKind.StoryView] = new Budget(10, 40) },
};
var report = await SimulateAsync(new SimulationOptions
{
Days = 5,
Seed = 11,
Settings = new EngineSettings().WithCustomValues(custom),
World = new SimulatedWorldOptions
{
Seed = 11,
FollowedAccounts = 15,
NotFollowedAccounts = 25,
MeanPostsPerDay = 1.5,
StoryAccountShare = 1,
HistoricalPosts = 3000,
ThrottleProbabilityPerAction = 0.004,
FrequencyOf = _ => Frequency.High,
},
});
Assert.AreEqual(0, report.Overruns, string.Join("\n", report.OverrunDetails));
Assert.AreEqual(0, report.ActionsOutsideWindow);
Assert.AreEqual(0, report.PauseFloorViolations);
Assert.IsNotEmpty(report.Throttles);
var data = report.CategoryTotals.Single(c => c.Kind == ActionKind.DataDownload);
// Gradual start and throttles halve it: under pressure means near half of the full budget at least.
Assert.IsTrue(data.MaxPerDay > data.DailyLimit * 0.45, "The data budget was really under pressure.\n" + report.ToText());
Assert.IsTrue(data.MaxPerDay <= data.DailyLimit);
var stories = report.CategoryTotals.Single(c => c.Kind == ActionKind.StoryView);
Assert.IsTrue(stories.MaxPerDay <= 40);
var profiles = report.CategoryTotals.Single(c => c.Kind == ActionKind.ProfileOpen);
Assert.IsTrue(profiles.WorstHour >= 6, "The hourly profile budget (halved at first) was reached.");
Assert.IsTrue(profiles.WorstHour <= 12 && profiles.MaxPerDay <= 100);
}
[TestMethod]
[DataRow(true)]
[DataRow(false)]
public async Task WithStoriesOnEveryAccountGetsAtLeastThreeStoryChecksADay(bool sweepCoversFollowedStories)
{
var report = await SimulateAsync(new SimulationOptions
{
Days = 4,
Seed = 5,
Engine = EngineOptions.Default with { SweepCoversFollowedStories = sweepCoversFollowedStories },
World = new SimulatedWorldOptions
{
Seed = 5,
FollowedAccounts = 3,
NotFollowedAccounts = 3,
StoryAccountShare = 1,
HistoricalPosts = 0,
ThrottleProbabilityPerAction = 0,
FrequencyOf = i => i % 2 == 0 ? Frequency.Low : Frequency.Normal,
},
});
var stats = report.World;
foreach (var day in report.Days.Skip(1))
{
foreach (var account in report.WorldAccounts)
{
var explicitChecks = stats.StoryChecks.GetValueOrDefault((account.Id, day.Day));
var bySweep = account.Followed && sweepCoversFollowedStories ? stats.Sweeps.GetValueOrDefault(day.Day) : 0;
Assert.IsTrue(explicitChecks + bySweep >= 3, $"{account.Username} on {day.Day}: {explicitChecks} checks, {bySweep} sweeps");
}
}
Assert.AreEqual(0, report.MissedStories);
}
[TestMethod]
public async Task TheSameSeedGivesTheSameSimulation()
{
var first = await SimulateAsync(new SimulationOptions { Days = 2, Seed = 9 });
var second = await SimulateAsync(new SimulationOptions { Days = 2, Seed = 9 });
Assert.AreEqual(first.SessionCount, second.SessionCount);
Assert.AreEqual(first.VirtualEvents, second.VirtualEvents);
CollectionAssert.AreEqual(first.Days.Select(d => d.Actions[ActionKind.ProfileOpen]).ToList(), second.Days.Select(d => d.Actions[ActionKind.ProfileOpen]).ToList());
}
[TestMethod]
public async Task TheCsvIsUtf8WithBomAndSemicolons()
{
var report = await SimulateAsync(new SimulationOptions { Days = 1, Seed = 2 });
using var folder = new TempFolder("csv");
var path = folder.Combine("resoconto.csv");
await report.WriteCsvAsync(path);
var bytes = await File.ReadAllBytesAsync(path);
CollectionAssert.AreEqual(new byte[] { 0xEF, 0xBB, 0xBF }, bytes.Take(3).ToArray());
var text = Encoding.UTF8.GetString(bytes, 3, bytes.Length - 3);
StringAssert.Contains(text, "minuti di attività");
Assert.IsTrue(text.Split('\n')[1].Split(';').Length > 10);
}
[TestMethod]
public void TheCommandLineIsParsed()
{
Assert.IsTrue(Febe.Server.SimulateCommand.TryParse(["--simula", "30g", "--profilo", "equilibrato", "--csv", "x.csv", "--seme", "4"], out var options, out var csv, out _));
Assert.AreEqual(30, options.Days);
Assert.AreEqual(CautionProfileKind.Balanced, options.Profile);
Assert.AreEqual("x.csv", csv);
Assert.AreEqual(4, options.Seed);
Assert.IsFalse(Febe.Server.SimulateCommand.TryParse(["--simula", "trenta"], out _, out _, out var problem));
StringAssert.Contains(problem, "Durata non valida");
Assert.IsFalse(Febe.Server.SimulateCommand.TryParse(["--simula", "7g", "--profilo", "spericolato"], out _, out _, out problem));
StringAssert.Contains(problem, "Profilo sconosciuto");
}
[TestMethod]
public async Task TheCommandPrintsTheItalianReport()
{
using var output = new StringWriter();
using var error = new StringWriter();
var code = await Febe.Server.SimulateCommand.RunAsync(["--simula", "1g", "--profilo", "rapido"], output, error);
Assert.AreEqual(0, code, error.ToString());
StringAssert.Contains(output.ToString(), "profilo «Rapido»");
Assert.AreEqual(2, await Febe.Server.SimulateCommand.RunAsync(["--simula", "0g"], output, error));
}
}
+320
View File
@@ -0,0 +1,320 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Tests.Engine.Support;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class GovernorTests
{
[TestMethod]
public async Task GrantsInsideTheWindowDuringASessionAndRecordsTheAction()
{
await using var bed = await EngineTestBed.CreateAsync();
var account = await bed.AddAccountAsync("marta.demo", followed: false);
var session = await bed.BeginSessionAsync();
var permit = await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None);
Assert.IsTrue(permit.Granted, permit.Message);
var logged = await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddMinutes(-1), bed.Clock.Now.AddMinutes(1));
Assert.HasCount(1, logged);
Assert.AreEqual(ActionKind.ProfileOpen, logged[0].Category);
Assert.AreEqual(account.Id, logged[0].AccountId);
Assert.AreEqual(session.SessionId, logged[0].SessionId);
Assert.AreEqual(1, session.ActionCount);
}
[TestMethod]
public async Task RefusesWithoutASession()
{
await using var bed = await EngineTestBed.CreateAsync();
var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
Assert.IsFalse(permit.Granted);
Assert.AreEqual(DenialReason.NoSession, permit.Reason);
Assert.IsFalse(string.IsNullOrWhiteSpace(permit.Message));
Assert.HasCount(0, await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddDays(-1), bed.Clock.Now.AddDays(1)));
}
[TestMethod]
public async Task RefusesOutsideTheWindowWithTheNextWindowAsRetryTime()
{
await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 3, 0));
await bed.BeginSessionAsync();
var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
Assert.AreEqual(DenialReason.OutsideActiveWindow, permit.Reason);
Assert.IsNotNull(permit.RetryAfter);
var window = await bed.Services.Planner.GetWindowAsync(new DateOnly(2026, 10, 14));
Assert.AreEqual(window!.Start, permit.RetryAfter);
StringAssert.Contains(permit.Message!, "verso le");
}
[TestMethod]
public async Task TheBreakerIsCheckedFirst()
{
await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 3, 0));
await bed.Breaker.ReportAsync(new Signal(SignalLevel.Challenge, "challenge-url", "https://sito.prova/challenge", bed.Clock.Now));
// Outside the window and without a session too: the breaker comes first.
var permit = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
Assert.AreEqual(DenialReason.BreakerOpen, permit.Reason);
StringAssert.Contains(permit.Message!, "verifica");
}
[TestMethod]
public async Task PauseAndAlbertoAtTheBrowserRefuse()
{
var driving = false;
await using var bed = await EngineTestBed.CreateAsync(userIsDriving: () => driving);
await bed.BeginSessionAsync();
bed.Runtime.IsPaused = true;
Assert.AreEqual(DenialReason.Paused, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
bed.Runtime.IsPaused = false;
driving = true;
Assert.AreEqual(DenialReason.UserIsDriving, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
driving = false;
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
}
[TestMethod]
public async Task TheHourlyBudgetIsARolling60MinuteWindow()
{
await using var bed = await EngineTestBed.CreateAsync();
bed.Clock.AutoAdvance = true;
await bed.BeginSessionAsync();
var first = bed.Clock.Now;
// «Prudente»: 4 home pages per hour.
for (var i = 0; i < 4; i++)
{
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
}
var denied = await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
Assert.AreEqual(DenialReason.HourlyBudgetReached, denied.Reason);
Assert.AreEqual(first + TimeSpan.FromHours(1), denied.RetryAfter);
StringAssert.Contains(denied.Message!, "tetto orario");
// Other categories go on.
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
bed.Clock.AdvanceTo(first + TimeSpan.FromHours(1));
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Granted);
}
[TestMethod]
public async Task TheDailyBudgetUsesTheLocalCalendarDayAndComesFromTheDatabase()
{
await using var bed = await EngineTestBed.CreateAsync();
var account = await bed.AddAccountAsync("luca.demo", followed: false);
var morning = EngineTestBed.Local(2026, 10, 14, 8, 0);
for (var i = 0; i < 100; i++)
{
await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = morning.AddSeconds(i * 20), Category = ActionKind.ProfileOpen, AccountId = account.Id });
}
// Yesterday's actions do not count today.
await bed.Db.ActionLog.AppendAsync(new ActionLogRecord { At = morning.AddDays(-1), Category = ActionKind.StoryView });
await bed.BeginSessionAsync();
var denied = await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None);
Assert.AreEqual(DenialReason.DailyBudgetReached, denied.Reason);
Assert.IsTrue(denied.RetryAfter >= EngineTestBed.Local(2026, 10, 15, 0, 0));
StringAssert.Contains(denied.Message!, "domani");
var events = await bed.Db.Events.ListAsync(new Febe.Core.Storage.EventQuery());
Assert.IsTrue(events.Any(e => e.Code == EngineEventCodes.BudgetReached));
}
[TestMethod]
[DataRow(GesturePace.Natural, 4000)]
[DataRow(GesturePace.Brisk, 3000)]
[DataRow(GesturePace.Slow, 5400)]
public async Task TheMinimumSpacingIsWaitedAndScaledByThePace(GesturePace pace, int spacingMs)
{
await using var bed = await EngineTestBed.CreateAsync(settings: new EngineSettings { GradualStart = false, Pace = pace });
bed.Clock.AutoAdvance = true;
await bed.BeginSessionAsync();
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
var evaluation = await bed.Governor.EvaluateAsync(ActionKind.StoryView, null);
Assert.AreEqual(DenialReason.MinimumSpacing, evaluation.Reason);
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None)).Granted);
var log = await bed.Db.ActionLog.ListAsync(bed.Clock.Now.AddHours(-1), bed.Clock.Now.AddSeconds(1));
Assert.HasCount(2, log);
Assert.AreEqual(TimeSpan.FromMilliseconds(spacingMs), log[1].At - log[0].At);
}
[TestMethod]
public async Task TheAccountBackfillLimitCountsPostsDiscoveredToday()
{
await using var bed = await EngineTestBed.CreateAsync();
var account = await bed.AddAccountAsync("storico.demo", followed: true, state: AccountState.Backfilling, backfillPerDay: 24);
for (var i = 0; i < 24; i++)
{
await bed.Db.Entries.AddAsync(
new Entry { AccountId = account.Id, Kind = EntryKind.Post, InstagramId = "p" + i, PublishedAt = bed.Clock.Now.AddDays(-100 - i), DiscoveredAt = bed.Clock.Now.AddMinutes(-30) },
[new Media { Position = 1, Kind = MediaKind.Photo }]);
}
await bed.BeginSessionAsync();
var denied = await bed.Governor.RequestAsync(ActionKind.BackfillPage, account.Id, CancellationToken.None);
Assert.AreEqual(DenialReason.AccountLimitReached, denied.Reason);
StringAssert.Contains(denied.Message!, "@storico.demo");
// Other categories of the same account are not limited by the backfill limit.
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, account.Id, CancellationToken.None)).Granted);
}
[TestMethod]
public async Task AccountsThatMustNotBeContactedAreRefused()
{
await using var bed = await EngineTestBed.CreateAsync();
var archive = await bed.AddAccountAsync("archivio.demo", followed: false, state: AccountState.ArchiveOnly);
var paused = await bed.AddAccountAsync("pausa.demo", followed: false, state: AccountState.Paused);
var session = await bed.BeginSessionAsync();
Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, archive.Id, CancellationToken.None)).Reason);
Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, paused.Id, CancellationToken.None)).Reason);
// «Controlla ora» on a paused account is allowed; on an archive-only one never.
session.ManualAccountId = paused.Id;
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, paused.Id, CancellationToken.None)).Granted);
session.ManualAccountId = archive.Id;
bed.Clock.Advance(TimeSpan.FromSeconds(10));
Assert.AreEqual(DenialReason.AccountNotContactable, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, archive.Id, CancellationToken.None)).Reason);
}
[TestMethod]
public async Task AConfirmedManualCheckOutsideTheWindowAllowsOnlyThatAccount()
{
await using var bed = await EngineTestBed.CreateAsync(EngineTestBed.Local(2026, 10, 14, 2, 0));
var asked = await bed.AddAccountAsync("chiesto.demo", followed: false);
var other = await bed.AddAccountAsync("altro.demo", followed: false);
await bed.BeginSessionAsync(outsideWindowAccountId: asked.Id);
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.ProfileOpen, asked.Id, CancellationToken.None)).Granted);
bed.Clock.Advance(TimeSpan.FromSeconds(10));
Assert.AreEqual(DenialReason.OutsideActiveWindow, (await bed.Governor.RequestAsync(ActionKind.ProfileOpen, other.Id, CancellationToken.None)).Reason);
Assert.AreEqual(DenialReason.OutsideActiveWindow, (await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None)).Reason);
}
[TestMethod]
public void TheGradualStartGoesFromHalfToFullLinearly()
{
var profile = CautionProfile.Prudent;
var start = EngineTestBed.Noon;
Assert.AreEqual(0.5, BudgetLimits.GradualStartFactor(profile, start, start), 1e-9);
Assert.AreEqual(0.75, BudgetLimits.GradualStartFactor(profile, start, start.AddDays(3.5)), 1e-9);
Assert.AreEqual(1.0, BudgetLimits.GradualStartFactor(profile, start, start.AddDays(7)), 1e-9);
Assert.AreEqual(1.0, BudgetLimits.GradualStartFactor(profile with { GradualStart = false }, start, start), 1e-9);
var budgets = BudgetLimits.Compute(profile, start, null, start);
Assert.AreEqual(BudgetReduction.GradualStart, budgets.Reduction);
Assert.AreEqual(new Budget(6, 50), budgets.Budgets[ActionKind.ProfileOpen]);
Assert.AreEqual(2L * 1024 * 1024 * 1024, budgets.DataPerDayBytes);
Assert.AreEqual(150, budgets.BackfillPostsPerAccountPerDay);
}
[TestMethod]
public void TheStrongestReductionWinsNeverTheProduct()
{
var profile = CautionProfile.Prudent;
var start = EngineTestBed.Noon;
var now = start.AddDays(2);
var halvedUntil = now.AddHours(10);
var both = BudgetLimits.Compute(profile, start, halvedUntil, now);
Assert.AreEqual(0.5, both.Factor, 1e-9, "Halved (0.5) is stronger than the ramp at day 2 (0.64): 0.5, not 0.32.");
Assert.AreEqual(BudgetReduction.HalvedAfterThrottle, both.Reduction);
Assert.AreEqual(new Budget(6, 50), both.Budgets[ActionKind.ProfileOpen]);
var rampOnly = BudgetLimits.Compute(profile, start, halvedUntil, halvedUntil);
Assert.AreEqual(0.5 + (0.5 * (2 + (10.0 / 24)) / 7), rampOnly.Factor, 1e-9);
Assert.AreEqual(BudgetReduction.GradualStart, rampOnly.Reduction);
var none = BudgetLimits.Compute(profile, start, halvedUntil, start.AddDays(8));
Assert.AreEqual(1, none.Factor);
Assert.AreEqual(BudgetReduction.None, none.Reduction);
}
[TestMethod]
public async Task HalvedBudgetsApplyAfterAThrottle()
{
await using var bed = await EngineTestBed.CreateAsync();
await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
bed.Clock.Advance(TimeSpan.FromHours(1));
var budgets = bed.Governor.GetEffectiveBudgets(bed.Clock.Now);
Assert.AreEqual(BudgetReduction.HalvedAfterThrottle, budgets.Reduction);
Assert.AreEqual(new Budget(2, 15), budgets.Budgets[ActionKind.Home]);
bed.Clock.Advance(TimeSpan.FromHours(48));
Assert.AreEqual(BudgetReduction.None, bed.Governor.GetEffectiveBudgets(bed.Clock.Now).Reduction);
}
[TestMethod]
public async Task TheDataBudgetIsDailyInBytesAndWorksDuringAStop()
{
await using var bed = await EngineTestBed.CreateAsync();
var full = 4L * 1024 * 1024 * 1024;
Assert.AreEqual(full, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
// After a throttle the data budget is halved too.
await bed.Breaker.ReportAsync(new Signal(SignalLevel.Throttle, "http-429", null, bed.Clock.Now));
Assert.AreEqual(full / 2, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
await bed.Governor.RecordAsync((full / 2) - 1000, null, CancellationToken.None);
Assert.AreEqual(1000L, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
// Queued downloads may complete during a stop: the data budget does not look at the breaker.
Assert.IsTrue((await bed.Governor.RequestAsync(ActionKind.DataDownload, null, CancellationToken.None)).Granted);
await bed.Governor.RecordAsync(1000, null, CancellationToken.None);
var denied = await bed.Governor.RequestAsync(ActionKind.DataDownload, null, CancellationToken.None);
Assert.AreEqual(DenialReason.DailyBudgetReached, denied.Reason);
Assert.AreEqual(0L, await bed.Governor.RemainingTodayAsync(CancellationToken.None));
bed.Clock.AdvanceTo(EngineTestBed.Local(2026, 10, 15, 0, 0));
Assert.IsTrue(await bed.Governor.RemainingTodayAsync(CancellationToken.None) > 0);
}
[TestMethod]
public async Task RemainingSaysHowMuchRoomIsLeft()
{
await using var bed = await EngineTestBed.CreateAsync();
bed.Clock.AutoAdvance = true;
await bed.BeginSessionAsync();
Assert.AreEqual(50L, await bed.Governor.RemainingAsync(ActionKind.StoryView));
for (var i = 0; i < 45; i++)
{
await bed.Governor.RequestAsync(ActionKind.StoryView, null, CancellationToken.None);
}
Assert.AreEqual(5L, await bed.Governor.RemainingAsync(ActionKind.StoryView), "Not room for ten stories in this hour.");
}
[TestMethod]
public async Task BudgetsTurnAmberFrom80Percent()
{
await using var bed = await EngineTestBed.CreateAsync();
bed.Clock.AutoAdvance = true;
await bed.BeginSessionAsync();
for (var i = 0; i < 3; i++)
{
await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
}
var statuses = await bed.Governor.GetBudgetStatusAsync();
var home = statuses.Single(s => s.Kind == ActionKind.Home);
Assert.AreEqual(3L, home.UsedLastHour);
Assert.IsFalse(home.IsAmber, "3 of 4 is 75%.");
await bed.Governor.RequestAsync(ActionKind.Home, null, CancellationToken.None);
home = (await bed.Governor.GetBudgetStatusAsync()).Single(s => s.Kind == ActionKind.Home);
Assert.IsTrue(home.IsAmber);
Assert.IsTrue(home.HourlyReached);
Assert.IsFalse(statuses.Single(s => s.Kind == ActionKind.StoryView).IsAmber);
}
}
@@ -0,0 +1,71 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Storage;
namespace Febe.Tests.Engine.Support;
/// <summary>
/// Independent check of the budgets from <c>action_log</c>: at every action, the rolling hour and the local day so far
/// must stay within the profile's full limits (reductions only make them lower).
/// </summary>
internal static class BudgetAudit
{
private static readonly TimeSpan Hour = TimeSpan.FromMinutes(60);
public static async Task<IReadOnlyList<string>> OverrunsAsync(IFebeStorage storage, CautionProfile profile, TimeZoneInfo zone, DateTimeOffset from, DateTimeOffset to)
{
var actions = await storage.ActionLog.ListAsync(from, to);
var problems = new List<string>();
foreach (var kind in Enum.GetValues<ActionKind>())
{
var list = actions.Where(a => a.Category == kind).OrderBy(a => a.At).ThenBy(a => a.Id).ToList();
var first = 0;
long hour = 0;
long day = 0;
DateOnly? current = null;
foreach (var action in list)
{
hour += action.Amount;
while (list[first].At <= action.At - Hour)
{
hour -= list[first].Amount;
first++;
}
var today = LocalCalendar.Today(action.At, zone);
if (today != current)
{
current = today;
day = 0;
}
day += action.Amount;
var over = kind == ActionKind.DataDownload
? day > profile.DataPerDayBytes
: hour > profile.Budgets[kind].PerHour || day > profile.Budgets[kind].PerDay;
if (over)
{
problems.Add($"{kind} at {action.At:O}: hour {hour}, day {day}");
}
}
}
return problems;
}
/// <summary>Actions (data excluded) that fall outside the active window of their day.</summary>
public static async Task<IReadOnlyList<ActionLogRecord>> OutsideWindowAsync(IFebeStorage storage, DayPlanner planner, DateTimeOffset from, DateTimeOffset to)
{
var outside = new List<ActionLogRecord>();
foreach (var action in (await storage.ActionLog.ListAsync(from, to)).Where(a => a.Category != ActionKind.DataDownload))
{
if (await planner.GetWindowAtAsync(action.At) is null)
{
outside.Add(action);
}
}
return outside;
}
}
@@ -0,0 +1,172 @@
using Febe.Core.Abstractions;
using Febe.Core.Domain;
using Febe.Core.Engine;
using Febe.Core.Simulation;
using Febe.Data;
using Febe.Tests.Support;
namespace Febe.Tests.Engine.Support;
/// <summary>
/// A temporary database, a virtual clock in Rome's zone and the engine services on top, with a fixed seed.
/// <see cref="ReopenAsync"/> builds new engine objects on the same database, as a restart of the program does.
/// </summary>
internal sealed class EngineTestBed : IAsyncDisposable
{
private readonly TempFolder _folder;
private EngineHost? _host;
private CancellationTokenSource? _loopCts;
private Task? _loop;
private EngineTestBed(TempFolder folder, FebeDatabase db, VirtualClock clock, EngineServices services, EngineOptions options, int seed)
{
_folder = folder;
Db = db;
Clock = clock;
Services = services;
Options = options;
Seed = seed;
}
public static TimeZoneInfo Zone => SimulationZones.Rome;
/// <summary>Wednesday 14 October 2026 at 12:00 in Rome: inside every profile's window whatever the daily shift.</summary>
public static DateTimeOffset Noon { get; } = Local(2026, 10, 14, 12, 0);
public FebeDatabase Db { get; }
public VirtualClock Clock { get; }
public EngineServices Services { get; private set; }
public EngineOptions Options { get; }
public int Seed { get; }
public Governor Governor => Services.Governor;
public CircuitBreaker Breaker => Services.Breaker;
public EngineRuntime Runtime => Services.Runtime;
public static DateTimeOffset Local(int year, int month, int day, int hour, int minute) =>
LocalCalendar.FromLocal(new DateTime(year, month, day, hour, minute, 0), Zone);
/// <summary>A bed with the given profile; the gradual start is off unless asked, so budgets are the profile's.</summary>
public static async Task<EngineTestBed> CreateAsync(
DateTimeOffset? start = null,
CautionProfileKind profile = CautionProfileKind.Prudent,
bool gradualStart = false,
int seed = 7,
EngineOptions? options = null,
EngineSettings? settings = null,
Func<bool>? userIsDriving = null,
Func<bool>? isConnected = null)
{
var folder = new TempFolder("motore");
var db = await FebeDatabase.OpenAsync(folder.Combine("dati"));
var clock = new VirtualClock(start ?? Noon, Zone);
settings ??= new EngineSettings { ProfileKind = profile, GradualStart = gradualStart };
await EngineSettingsStore.SaveAsync(db.Settings, settings);
options ??= EngineOptions.Default;
var services = await EngineServices.CreateAsync(db, clock, new SeededRandom(seed), options, userIsDriving, isConnected);
return new EngineTestBed(folder, db, clock, services, options, seed);
}
/// <summary>New engine objects on the same database (a restart), with a different random stream.</summary>
public async Task<EngineServices> ReopenAsync(int seed, Func<bool>? userIsDriving = null)
{
await StopAsync();
Services = await EngineServices.CreateAsync(Db, Clock, new SeededRandom(seed), Options, userIsDriving);
return Services;
}
public async Task<Account> AddAccountAsync(
string username,
bool followed,
Frequency frequency = Frequency.Normal,
AccountState state = AccountState.UpToDate,
ContentTypes? types = null,
int? postCount = null,
int? backfillPerDay = null)
{
var account = Account.Create(username, StartingPoint.EverythingAndKeepUpdated, Clock.Now, Zone, Runtime.Profile) with
{
InstagramId = "77" + ((uint)username.GetHashCode(StringComparison.Ordinal)).ToString(System.Globalization.CultureInfo.InvariantCulture),
IsFollowed = followed,
Frequency = frequency,
State = state,
BackfillCompletedAt = state == AccountState.Backfilling ? null : Clock.Now,
PostCount = postCount,
};
if (types is { } t)
{
account = account with { ContentTypes = t };
}
if (backfillPerDay is { } perDay)
{
account = account with { Limits = account.Limits with { BackfillPostsPerDay = perDay } };
}
return await Db.Accounts.AddAsync(account);
}
/// <summary>A session as the engine opens it, for testing the Governor alone.</summary>
public async Task<SessionContext> BeginSessionAsync(long? outsideWindowAccountId = null)
{
var record = await Db.Sessions.StartAsync(Clock.Now);
var session = new SessionContext(record.Id, 1, Clock.Now, Clock.Now + TimeSpan.FromMinutes(10), outsideWindowAccountId);
Runtime.CurrentSession = session;
return session;
}
/// <summary>Starts the engine loop on the virtual clock (no time passes until <see cref="RunUntilAsync"/>).</summary>
public EngineHost Start(IRecipeRunner runner)
{
_host = new EngineHost(Services, runner);
_loopCts = new CancellationTokenSource();
_loop = _host.RunAsync(_loopCts.Token);
return _host;
}
public EngineHost Host => _host ?? throw new InvalidOperationException("Engine not started.");
/// <summary>Advances virtual time to <paramref name="target"/>, letting the engine run.</summary>
public Task RunUntilAsync(DateTimeOffset target) =>
_loop is null ? Task.Run(() => Clock.AdvanceTo(target)) : Clock.RunUntilAsync(target, CancellationToken.None, _loop);
public Task RunForAsync(TimeSpan span) => RunUntilAsync(Clock.Now + span);
/// <summary>Stops the loop as a shutdown would (a session in progress ends interrupted).</summary>
public async Task StopAsync()
{
if (_loop is null)
{
return;
}
await _loopCts!.CancelAsync();
try
{
await _loop;
}
catch (OperationCanceledException)
{
}
await _host!.DisposeAsync();
_loopCts.Dispose();
_loop = null;
_loopCts = null;
_host = null;
await Breaker.FlushAsync();
}
public async ValueTask DisposeAsync()
{
await StopAsync();
await Db.DisposeAsync();
_folder.Dispose();
}
}
@@ -0,0 +1,101 @@
using Febe.Core.Abstractions;
using Febe.Core.Engine;
namespace Febe.Tests.Engine.Support;
/// <summary>A recipe run seen by <see cref="ScriptedRunner"/>.</summary>
internal sealed record RunRecord(DateTimeOffset At, RecipeRequest Request, long SessionId, RecipeStatus Status);
/// <summary>
/// A recipe runner for engine tests: asks the Governor for one counted action like the real recipes (stories:
/// none, as if no story was active), spends a little virtual time and completes, unless <see cref="Script"/> says
/// otherwise. Records every run.
/// </summary>
internal sealed class ScriptedRunner(IGovernor governor, IClock clock) : IRecipeRunner
{
private readonly Lock _gate = new();
private readonly List<RunRecord> _runs = [];
/// <summary>Forced outcome for a request (null: default behaviour). Runs before the Governor is asked.</summary>
public Func<RecipeRequest, RecipeOutcome?>? Script { get; set; }
/// <summary>Called after the counted action was granted (e.g. to report a signal).</summary>
public Action<RecipeRequest>? AfterGrant { get; set; }
/// <summary>Accounts the stories bar flags in every sweep.</summary>
public IReadOnlyList<long> FlaggedStories { get; set; } = [];
public int Rests { get; private set; }
public IReadOnlyList<RunRecord> Runs
{
get
{
lock (_gate)
{
return [.. _runs];
}
}
}
public async Task<RecipeOutcome> RunAsync(RecipeRequest request, ISessionContext session, CancellationToken ct)
{
RecipeOutcome outcome;
try
{
outcome = Script?.Invoke(request) ?? await DefaultAsync(request, ct);
}
catch (OperationCanceledException)
{
lock (_gate)
{
_runs.Add(new RunRecord(clock.Now, request, session.SessionId, RecipeStatus.Cancelled));
}
throw;
}
lock (_gate)
{
_runs.Add(new RunRecord(clock.Now, request, session.SessionId, outcome.Status));
}
return outcome;
}
public Task RestAsync(CancellationToken ct)
{
Rests++;
return Task.CompletedTask;
}
private async Task<RecipeOutcome> DefaultAsync(RecipeRequest request, CancellationToken ct)
{
if (request.Kind == RecipeKind.AccountStories)
{
await clock.Delay(TimeSpan.FromSeconds(2), ct);
return new RecipeOutcome(RecipeStatus.Completed, 0, 0);
}
var kind = CheckPolicy.CategoryOf(request.Kind);
var pages = request.Kind == RecipeKind.Backfill ? Math.Max(1, request.MaxPages ?? 1) : 1;
var counted = 0;
for (var i = 0; i < pages; i++)
{
var permit = await governor.RequestAsync(kind, request.AccountId, ct);
if (!permit.Granted)
{
return new RecipeOutcome(counted > 0 ? RecipeStatus.Completed : RecipeStatus.Denied, counted, 0);
}
counted++;
AfterGrant?.Invoke(request);
await clock.Delay(TimeSpan.FromSeconds(5), ct);
}
return new RecipeOutcome(RecipeStatus.Completed, counted, 0)
{
AccountsWithStories = request.Kind == RecipeKind.FollowingSweep ? FlaggedStories : [],
};
}
}
@@ -0,0 +1,93 @@
using Febe.Core.Simulation;
namespace Febe.Tests.Engine;
[TestClass]
public sealed class VirtualClockTests
{
private static readonly DateTimeOffset Start = new(2026, 10, 14, 10, 0, 0, TimeSpan.Zero);
[TestMethod]
public async Task DelaysCompleteOnlyWhenTimeReachesThem()
{
var clock = new VirtualClock(Start);
var late = clock.Delay(TimeSpan.FromMinutes(10), CancellationToken.None);
var early = clock.Delay(TimeSpan.FromMinutes(5), CancellationToken.None);
Assert.AreEqual(2, clock.PendingTimers);
Assert.IsFalse(early.IsCompleted);
clock.Advance(TimeSpan.FromMinutes(6));
await early;
Assert.IsFalse(late.IsCompleted);
Assert.AreEqual(Start.AddMinutes(6), clock.Now);
clock.Advance(TimeSpan.FromMinutes(10));
await late;
Assert.AreEqual(0, clock.PendingTimers);
}
[TestMethod]
public async Task ACancelledDelayLeavesTheQueue()
{
var clock = new VirtualClock(Start);
using var cts = new CancellationTokenSource();
var delay = clock.Delay(TimeSpan.FromHours(1), cts.Token);
Assert.AreEqual(1, clock.PendingTimers);
await cts.CancelAsync();
Assert.AreEqual(0, clock.PendingTimers);
await Assert.ThrowsAsync<TaskCanceledException>(() => delay);
}
[TestMethod]
public async Task RunUntilJumpsFromTimerToTimerWhileTheActorWaits()
{
var clock = new VirtualClock(Start);
var seen = new List<DateTimeOffset>();
using var cts = new CancellationTokenSource();
async Task Actor()
{
for (var i = 0; i < 5; i++)
{
await Task.Yield();
await clock.Delay(TimeSpan.FromMinutes(30), cts.Token);
seen.Add(clock.Now);
}
await clock.Delay(TimeSpan.FromDays(10), cts.Token);
}
var actor = Actor();
await clock.RunUntilAsync(Start.AddHours(2), CancellationToken.None, actor);
Assert.AreEqual(Start.AddHours(2), clock.Now);
CollectionAssert.AreEqual(new[] { Start.AddMinutes(30), Start.AddMinutes(60), Start.AddMinutes(90), Start.AddMinutes(120) }, seen);
await clock.RunUntilAsync(Start.AddHours(3), CancellationToken.None, actor);
Assert.HasCount(5, seen);
await cts.CancelAsync();
await Assert.ThrowsAsync<TaskCanceledException>(() => actor);
}
[TestMethod]
public async Task AFailingActorStopsTheRun()
{
var clock = new VirtualClock(Start);
async Task Actor()
{
await clock.Delay(TimeSpan.FromMinutes(1), CancellationToken.None);
throw new InvalidOperationException("guasto");
}
var actor = Actor();
await Assert.ThrowsAsync<InvalidOperationException>(() => clock.RunUntilAsync(Start.AddHours(1), CancellationToken.None, actor));
}
[TestMethod]
public async Task AutoAdvanceMovesTimeAtOnceAndRoundsToMilliseconds()
{
var clock = new VirtualClock(Start) { AutoAdvance = true };
await clock.Delay(TimeSpan.FromTicks(1), CancellationToken.None);
Assert.AreEqual(Start.AddMilliseconds(1), clock.Now);
await clock.Delay(TimeSpan.FromSeconds(4), CancellationToken.None);
Assert.AreEqual(Start.AddMilliseconds(4001), clock.Now);
}
}