MMP.RollingFiles 0.1.1

MMP.RollingFiles

Framework-neutral, AOT-clean rolling-file library for .NET. The consumer hands in bytes; the library puts them on disk, rolls on time / size / count, prunes by count / total-size / age, and runs deferred gzip / brotli compression on sealed files. Zero transitive NuGet dependencies — BCL only.

Multi-targets net8.0 and net10.0. AOT-publishable. Apache 2.0.

Install

dotnet add package MMP.RollingFiles

Minimal example

using MMP.RollingFiles;

var policy = new FilesManagerPolicy(
    Directory: "/var/log/myapp",
    FileNameTemplate: "events");

using var fm = new FilesManager(policy);
fm.AppendLine("hello world");

That writes /var/log/myapp/events.log with no rolling and no retention — fine for short-lived processes that just need an append-only file.

Realistic policy — daily roll + retention + gzip

using MMP.RollingFiles;

var policy = new FilesManagerPolicy(
    Directory: "/var/log/myapp",
    FileNameTemplate: "events-{date}",
    Interval: RollingInterval.Daily,
    MaxBytesPerFile: 64 * 1024 * 1024,             // 64 MiB hard cap
    MaxRetainedFiles: 30,                          // 30 newest rolls
    TotalSizeCapBytes: 2L * 1024 * 1024 * 1024,    // 2 GiB budget
    RetentionDays: 90,
    Compression: CompressionMode.Gzip,
    CleanRollOnStartup: true);

using var fm = new FilesManager(policy);

for (var i = 0; i < 10_000; i++)
{
    fm.AppendLine($"event {i:D5}");
}

The active file rolls on whichever trigger fires first (calendar day or 64 MiB). Sealed files get gzip'd by a background worker. The pruner enforces all three retention bounds — keep a rolled file only if it satisfies every cap.

Hooks — lifecycle callbacks

var hooks = new FilesManagerHooks
{
    OnOpenActive = path =>
    {
        // Fresh active file just opened — write a header line.
        Console.WriteLine($"opened: {path}");
        return ValueTask.CompletedTask;
    },

    OnPostRoll = path =>
    {
        // Sealed file at `path` is ready to ship downstream.
        Console.WriteLine($"rolled: {path}");
        return ValueTask.CompletedTask;
    },

    OnError = err =>
    {
        Console.Error.WriteLine($"[{err.Kind}] {err.Message}");
        return ValueTask.CompletedTask;
    }
};

using var fm = new FilesManager(policy, hooks);

All hooks run on a background thread, never on the hot append path. A failing hook surfaces through OnError if wired; without one, hook failures are swallowed silently (a buggy hook must not kill the writer).

What this library does

• Append-only writes to a managed active file
• Roll on time (RollingInterval.Hourly / Daily / Custom)
• Roll on size (MaxBytesPerFile)
• Roll on message count (MaxMessagesPerFile)
• Retention by count, total size, age — applied together
• Deferred gzip / brotli compression on sealed files
• Atomic temp-and-rename on roll (no torn files visible to readers)
• Startup-scanner crash recovery (finalises partial rolls from a previous process)
• AOT-clean output (<IsAotCompatible>true</IsAotCompatible> plus CI gate)

What this library does not do

• Render log events — it takes bytes, not events
• Format text — your code produces the line content
• Talk to any logger framework — framework-neutral by design
• Batch events semantically — the consumer decides

Cross-language

The on-disk format is a versioned contract shared with a Python port. A directory written by one is readable byte-for-byte by the other. Full walkthrough across .NET / Python / JavaScript / Vue:

• HOWTO
• spec/v1.md — the authoritative cross-language data model

License

Apache 2.0.

Source

github.com/mmpworks/MMP.RollingFiles.