Table of Contents

Orleans.Lattice.Storage.File

Durable, cloud-free local disk WAL provider for Orleans.Lattice. It plugs into the public IWalStorageProvider seam so a single-cluster deployment can persist its commit log to a mounted directory - crash-safe across silo restarts - without an external storage account.

What is it?

Orleans.Lattice.Storage.File is the optional on-disk WAL backend for the core lattice:

  • Durable WAL storage. FileWalStorageProvider stores each WAL partition of each tree as a segmented, append-only file on the local filesystem and implements the public IWalStorageProvider contract.
  • All-or-nothing batch append. Each batch is framed as a run of data records sealed by a single commit trailer and made durable with one write plus fsync; a crash before the trailer is durable rolls the whole batch back on recovery.
  • Restart recovery. Activation-time reconciliation rolls every committed batch forward, discards a torn tail, and reclaims trimmed space, so after a crash the log ends cleanly at its last committed batch; an honest offset gap left by a failed append is preserved, never renumbered.
  • Drop-in registration. AddFileWalStorage displaces the in-memory WAL backend installed by core lattice registration, and wires the durable-WAL garbage-collection stack alongside it.

As a WAL store it matches the observable durability guarantees of the Azure Table Storage provider without any cloud dependency. Tree state - each leaf's state row and its snapshots - still lives in the grain storage provider AddLattice registers, so a durable deployment pairs it with a durable grain storage provider, which must enforce ETags on write (see The grain storage provider must enforce ETags); that pairing makes it the enabler for a single-container, "codebase memory in a box" deployment (see the RepoContext MCP package and its container sample, which uses Orleans ADO.NET grain storage over a single SQLite file).

Core WAL semantics, the provider seam, and placement are covered in WAL Storage Providers.

Core Properties

  • Per-shard ordering. Offsets are stored verbatim and read back in ascending order within each (tree, shard) stream.
  • Batch atomicity. A successful append is visible as a complete batch; a torn or uncommitted trailing batch leaves no visible partial state after recovery.
  • Crash recoverability. Interrupted appends are reconciled before normal reads and writes rely on the stored tail.
  • Self-compacting. Trimmed payload bytes are physically reclaimed by rewriting a shard's segment file once enough dead space accumulates.
  • Published to NuGet as Orleans.Lattice.Storage.File, released under lattice.storage.file-v<X.Y.Z> tags.

Public surface

Type or member Role
FileWalStorageProvider Public IWalStorageProvider implementation (also IDisposable) that stores one wal.log per (tree, shard) stream under FileWalStorageOptions.RootDirectory. Its public constructor, FileWalStorageProvider(IOptions<FileWalStorageOptions>, Serializer<WalRecord>), builds a provider without the routing reader, so its filtered replay reads decode every record they examine; AddFileWalStorage is the registration that supplies one.
FileWalStorageOptions Public options type for the root directory, flush policy, compaction thresholds, and read-page byte ceiling, with public Default* constants for the compaction and read-page defaults.
LatticeFileServiceCollectionExtensions.AddFileWalStorage Registration extension that installs the file WAL provider, its options validator, and the durable-WAL garbage-collection wiring on an ISiloBuilder.

Quick Start

Install the package and register it on the silo that owns the WAL:

dotnet add package Orleans.Lattice.Storage.File

using Orleans.Lattice.Storage.File;

siloBuilder.AddFileWalStorage(options =>
{
    options.RootDirectory = "/data/wal";
});

Register it alongside AddLattice(...) on the silo that owns the WAL. The registration order does not matter: AddFileWalStorage displaces the in-memory baseline whether it runs before or after AddLattice.

Reference

  • Configuration - every FileWalStorageOptions knob, default, and validation rule.
  • Architecture - the on-disk layout, the append/commit framing, the durability contract, compaction, and recovery behaviour.

Related package docs: