Webority.Retention.Abstractions
0.5.0
See the version list below for details.
dotnet add package Webority.Retention.Abstractions --version 0.5.0
NuGet\Install-Package Webority.Retention.Abstractions -Version 0.5.0
<PackageReference Include="Webority.Retention.Abstractions" Version="0.5.0" />
<PackageVersion Include="Webority.Retention.Abstractions" Version="0.5.0" />
<PackageReference Include="Webority.Retention.Abstractions" />
paket add Webority.Retention.Abstractions --version 0.5.0
#r "nuget: Webority.Retention.Abstractions, 0.5.0"
#:package Webority.Retention.Abstractions@0.5.0
#addin nuget:?package=Webority.Retention.Abstractions&version=0.5.0
#tool nuget:?package=Webority.Retention.Abstractions&version=0.5.0
Webority.Retention
Runs every retention purge of a product. Register tables are trimmed by age: finished work rows in webhook intake, outboxes, idempotency records, side effects and job state. The tables and their rules come from the product's storage register, so the rules live in one place and a push check can verify them. Purges that need code (files, child rows, a clear) are classes the product or another package registers, and they join the same run.
Using it in a product
1. List the work tables in the register
.webority/data-placement.json names every table with a MAX column or that grows by appending. Entries of class workflow:<days> are trimmed:
{
"schemaVersion": 1,
"tables": [
{ "table": "dbo.InboundWebhookDelivery", "class": "workflow:30", "finishedAt": "ProcessedDateTimeUtc", "status": { "column": "Status", "finished": ["Processed", "Ignored"] } },
{ "table": "dbo.NotificationOutboxMessage", "class": "workflow:30", "finishedAt": "SentDateTimeUtc" },
{ "table": "dbo.SalesLead", "class": "record" }
]
}
| Field | Meaning |
|---|---|
table |
schema.table, or the table alone for dbo |
class |
workflow:<days> (1 to 3650) is trimmed; record, bounded-text, document-pointer, analytics and history:<years> are read and left alone |
finishedAt |
The UTC time the row finished (datetime2, datetime or datetimeoffset); a row where it is null is never deleted |
status |
Optional: column and the finished values. Pending and failed statuses are left out, so those rows are never deleted |
hold |
Optional, workflow entries only: a bit column on the same table. A row where it is 1 is never deleted; null or 0 is not held. The run is refused when the column is missing or not bit |
batchSize |
Optional: rows one delete statement removes from this table, 1 to 4000; the host's Retention:BatchSize when left out |
A wrong entry, or one that names a missing table or column, fails the whole run before anything is deleted.
An entry or status object with a key the package does not list (table, class, finishedAt, status, hold, batchSize, reason, package; status takes column and finished) fails parsing, so a misspelled key never goes unnoticed.
Each table needs an unfiltered index whose first column is finishedAt (with status as its second column when the entry has one), because each run reads the oldest due rows first. A table without one fails the run before anything is deleted, and the message names the index to add.
2. Copy the register into the Functions output
<None Include="..\.webority\data-placement.json" Link="data-placement.json" CopyToOutputDirectory="PreserveNewest" />
3. Register and configure
services.AddWeborityRetention();
"Retention": {
"RegisterPath": "data-placement.json",
"ConnectionStringName": "WeborityDbConnection",
"Brake": { "Mode": "DryRun" }
}
| Setting | Default | Meaning |
|---|---|---|
Retention:RegisterPath |
required | The register; a relative path is read from the app's base directory |
Retention:ConnectionStringName |
required | Which ConnectionStrings:<name> to trim |
Retention:BatchSize |
2,000 | Rows per delete statement (100 to 4,000, below SQL Server's lock escalation) |
Retention:TimeBudget |
4 minutes | A run stops cleanly when it passes this; the next run carries on |
Retention:CommandTimeoutSeconds |
60 | Per statement |
Retention:DryRunOnly |
Empty | Table or purge names held in dry run while the brake is Live; an unknown name refuses the run |
Retention:Brake:Mode |
DryRun |
Live deletes; DryRun only logs what would go |
Retention:Brake:MaxPerRun |
50,000 | Most rows one run takes from one table |
Retention:Brake:MaxShareOfPopulation |
1.0 | No share limit: a quiet table can be entirely due |
To add a new table or purge to a host in Live, add its name to Retention:DryRunOnly first, read its RetentionDryRun trace, then remove the name. No deploy is needed.
4. Call it from a timer
public sealed class RetentionFunction(RetentionRunner runner)
{
[Function("Retention")]
public Task RunAsync([TimerTrigger("0 15 * * * *")] TimerInfo timer, CancellationToken cancellationToken)
{
return runner.RunAsync(cancellationToken);
}
}
RunAsync returns a RetentionRunReport, whose Results holds one RetentionResult per table and per purge, each with the outcome Removed, NothingDue, DryRun, Refused, OutOfTime or Failed. When the brake refuses a table or purge, or one fails, the others still run, and the run then throws RetentionRunFailedException so it shows as failed.
Add a purge
A purge that needs code implements IRetentionPurge and is registered beside the runner. The contract types live in Webority.Retention.Abstractions, a package with no dependencies, so a library implements a purge without referencing Webority.Retention; the product references Webority.Retention and registers the purge:
public sealed class SessionFilePurge(IFileStore files) : IRetentionPurge
{
public string Name => "SessionFiles";
public Task<RetentionPurgePlan> PlanAsync(RetentionPurgeContext context, CancellationToken cancellationToken) =>
files.PlanExpiredAsync(context.NowDateTimeUtc, context.MaxPerRun, cancellationToken);
public async Task<int> PurgeAsync(RetentionPurgeContext context, RetentionPurgePlan plan, CancellationToken cancellationToken)
{
var removed = 0;
while (removed < plan.Due && !context.IsOutOfTime)
{
var batch = await files.DeleteExpiredBatchAsync(context.NowDateTimeUtc, Math.Min(500, plan.Due - removed), cancellationToken);
if (batch == 0)
{
break;
}
removed += batch;
}
return removed;
}
}
services.AddWeborityRetention();
services.AddWeborityRetentionPurge<SessionFilePurge>();
PlanAsyncnever changes data and is cheap when nothing is due.PurgeAsyncremoves at mostplan.Dueand repeats its own due check, so a row that changed after planning stays. A purge that removes more than it planned is reported asFailed.PurgeAsyncstops when a batch removes nothing: the rows it planned may already be gone.PurgeAsyncstops between batches whencontext.IsOutOfTimeis true.
How a run works
- Checks every register entry against the live schema, and refuses the whole run before anything is deleted when one does not match.
- Plans every table and purge.
- Starts with the oldest due table or purge, so a large backlog in one never keeps the others out of time.
- Checks each plan with the
Webority.Jobsdestructive-run guard (jobRetention). - In
Live, removes in batches. Each delete repeats the due check, so a row that changed after it was planned stays. A row whose hold column is 1 is never planned or deleted.
Build, test, release
dotnet restore Webority.Retention.slnx
dotnet build Webority.Retention.slnx -c Release --no-restore -v q
dotnet test --solution Webority.Retention.slnx -c Release --no-build
The set release tool in package-publisher publishes this package; a merge to main publishes nothing.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- No dependencies.
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Webority.Retention.Abstractions:
| Package | Downloads |
|---|---|
|
Webority.Retention
Deletes finished work rows from a product's SQL tables once they pass their retention window. The tables, their finished-time column and their finished statuses come from the product's storage register (.webority/data-placement.json); every column is checked against the live schema first, and every run is checked by the Webority.Jobs destructive-run guard. Purges that need code join the same run through IRetentionPurge. |
GitHub repositories
This package is not used by any popular GitHub repositories.