Table of Contents

Class OpossumOptions

Namespace
Opossum.Configuration
Assembly
Opossum.dll

Configuration options for the Opossum event store

public sealed class OpossumOptions
Inheritance
OpossumOptions
Inherited Members

Properties

CrossProcessLockTimeout

Maximum time to wait when acquiring the cross-process append lock. When multiple application instances share the same store directory (e.g. via a UNC path or mapped drive), Opossum serialises appends across all processes using a file-system lock. If the lock is held by another process for longer than this timeout, AppendAsync(NewEvent[], AppendCondition?, CancellationToken) throws TimeoutException.

Default: 5 seconds — sufficient headroom for any business-operation event rate; increase only if appends are consistently queued behind large batch operations on a slow network share.

public TimeSpan CrossProcessLockTimeout { get; set; }

Property Value

TimeSpan

FlushEventsImmediately

When true, forces events to be physically written to disk (flushed) before append completes. This guarantees durability at the cost of performance.

Benchmarked Performance (SSD, Windows 11, .NET 10):

  • TRUE (flush enabled): ~10ms per event, ~100 events/sec throughput
  • FALSE (no flush): ~4.5ms per event, ~220 events/sec throughput

Why this matters:

  • TRUE (default): Events are guaranteed on disk before AppendAsync returns. Safe for production. Prevents data loss on power failure.
  • FALSE: Events may only be in OS page cache. Faster but risky. Only use for testing or when you accept potential data loss.

Note: FlushEventsImmediately = false provides ~2.2x speedup but risks data loss. See docs/benchmarking/results/20260212/ANALYSIS.md for detailed benchmarks.

Default: true (recommended for production)

public bool FlushEventsImmediately { get; set; }

Property Value

bool

RootPath

Root directory path for storing events and indices. Must be a valid, accessible directory path. Default: "OpossumStore"

[Required(ErrorMessage = "RootPath is required")]
[MinLength(1, ErrorMessage = "RootPath cannot be empty")]
public string RootPath { get; set; }

Property Value

string

StoreName

The name of this event store. Used as a subdirectory under RootPath. Set exactly once via UseStore(string).

public string? StoreName { get; }

Property Value

string

WriteProtectEventFiles

When true, committed event files are marked read-only at the OS level immediately after being written to disk. This prevents accidental modification or deletion of immutable event records.

What this provides:

  • Committed event files cannot be opened for writing by any process without explicitly removing the read-only attribute first.
  • On Windows, File Explorer warns before deleting a read-only file.
  • Satisfies the common compliance requirement that audit records "cannot be altered" (ISO 9001:2015 clause 7.5.3.2, EU GMP Annex 11 section 4.8, HACCP documentation).

What this does NOT provide:

  • Protection against a Windows Administrator or root user who explicitly removes the read-only attribute and then modifies or deletes the file.
  • On Linux, deletion is controlled by the parent directory's write permission, not the file's own permission, so read-only does not prevent deletion by the directory owner.

The additive maintenance operation (AddTagsAsync(string, Func<SequencedEvent, IReadOnlyList<Tag>>, CancellationToken)) automatically unprotects a file before rewriting it and re-applies protection afterward. Write protection is transparent to all Opossum operations.

Default: false. Enable in production environments where event files must not be accidentally modified or deleted by operators browsing the store directory.

public bool WriteProtectEventFiles { get; set; }

Property Value

bool

WriteProtectProjectionFiles

When true, projection files are marked read-only at the OS level immediately after being written to disk. This prevents accidental modification or deletion by humans or other processes while Opossum transparently manages unprotecting files before updates or rebuilds and re-applying protection afterwards.

What this provides:

  • Projection files cannot be opened for writing by any process without explicitly removing the read-only attribute first.
  • On Windows, File Explorer warns before deleting a read-only file.

What this does NOT provide:

  • Protection against a Windows Administrator or root user who explicitly removes the read-only attribute and then modifies or deletes the file.
  • On Linux, deletion is controlled by the parent directory's write permission, not the file's own permission, so read-only does not prevent deletion by the directory owner.

Unlike event files, projection files are derived state and can always be rebuilt from events. Write protection here is purely about preventing accidental edits by humans browsing the store directory.

Default: false. Enable in production environments where projection files must not be accidentally modified or deleted by operators browsing the store directory.

public bool WriteProtectProjectionFiles { get; set; }

Property Value

bool

Methods

UseStore(string)

Sets the name of this event store. RootPath and must be a valid directory name.

public OpossumOptions UseStore(string name)

Parameters

name string

The store name. Must be a valid directory name (no path separators or wildcards).

Returns

OpossumOptions

This options instance for fluent configuration.

Exceptions

ArgumentException

Thrown when the name is null, empty, or contains invalid characters.

InvalidOperationException

Thrown when UseStore(string) has already been called. Opossum supports exactly one store per instance. To use multiple isolated event stores, register separate IEventStore instances with different RootPath values.

Edit this page