Class FileRepo

Represents a transactional file repository.

Inheritance

object

FileRepo

Implements

IFileRepoCleaner

IDisposable

Namespace: FulcrumFS

Assembly: FulcrumFS.dll

Syntax

public sealed class FileRepo : IFileRepoCleaner, IDisposable

Constructors

Name	Description
FileRepo(FileRepoOptions)	Initializes a new instance of the FileRepo class with the specified options.
FileRepo(IOptions<FileRepoOptions>)	Initializes a new instance of the FileRepo class with the specified options.
FileRepo(IAbsoluteDirectoryPath, Action<FileRepoOptions>?)	Initializes a new instance of the FileRepo class with the specified base directory and optional configuration action.

Properties

Name	Description
FilesDirectory	Gets the directory where files are stored.
Options	Gets the configuration options for the file repository. The returned instance is frozen and cannot be modified.

Methods

Name	Description
AddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Adds a new file variant (and any nested auto-variants declared by the pipeline) to an existing file in the repository.
AddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Adds a new file variant (and any nested auto-variants declared by the pipeline) to an existing file in the repository.
BeginTransactionAsync()	Begins a new transaction for the file repository, allowing changes to be committed or rolled back.
CleanAsync(TimeSpan, Func<FileId, IndeterminateResolution>?, CancellationToken)	Cleans up the repository by removing files whose delete markers are older than deleteDelay and resolving indeterminate files using the provided synchronous callback.
CleanAsync(TimeSpan, Func<FileId, Task<IndeterminateResolution>>?, CancellationToken)	Cleans up the repository by removing files whose delete markers are older than deleteDelay and resolving indeterminate files using the provided asynchronous callback.
CleanAsync(TimeSpan, CancellationToken)	Cleans up the repository by removing files whose delete markers are older than deleteDelay.
DeleteVariantsAsync(FileId, params ReadOnlySpan<string>)	Permanently retires the specified variants of a file, automatically preserving any dependent variants the caller did not list.
Dispose()	Disposes of the file repository, releasing any resources and locks held by it.
EnsureCreated()	Ensures that the file repository exists at the configured base directory, creating or repairing the required directory structure as necessary. May also acquire the repository lock for an instance session via a subsequent operation.
EnsureInitialized()	Ensures the file repository has been verified and the repository lock is acquired. The repository must already exist (call EnsureCreated() first if needed).
GetAsync(FileId)	Gets information about an existing file in the repository.
GetGroupAsync(FileId)	Gets information about an existing file and all of its variants in the repository.
GetOrAddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Adds new file variants where they do not already exist, processing missing variants through their pipelines and keeping existing ones unchanged. Each declared variant ID in the tree is represented in the returned list; variants whose pipelines stored an alias due to AliasWhenVariantSourceUnchanged resolve transparently to their source.
GetOrAddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Adds new file variants where they do not already exist, processing missing variants through their pipelines and keeping existing ones unchanged. Each declared variant ID in the tree is represented in the returned list; variants whose pipelines stored an alias due to AliasWhenVariantSourceUnchanged resolve transparently to their source.
GetVariantAsync(FileId, string)	Gets information about an existing file variant in the repository.
MigrateLegacyLayout()	Migrates a repository created by early pre-release legacy versions of FulcrumFS that used dot-prefixed .temp and .cleanup directory names to the current layout. Must be called before EnsureCreated() or any other operation on hosts that may still have legacy repositories on disk. Safe to call on already-migrated or non-existent repositories - it is a no-op when no legacy artifacts are present.
OpenAsync(FileId)	Opens a file stream for an existing file in the repository using the recommended sharing options.
OpenVariantAsync(FileId, string)	Opens a file stream for an existing file variant in the repository using the recommended sharing options.
TryAddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Tries to add a new file variant (and any nested auto-variants declared by the pipeline) to an existing file in the repository. Returns null if any declared variant ID in the tree already exists or if any per-variant lock cannot be acquired immediately. The operation is strict and all-or-nothing: any collision aborts the entire add.
TryAddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Tries to add a new file variant (and any nested auto-variants declared by the pipeline) to an existing file in the repository. Returns null if any declared variant ID in the tree already exists or if any per-variant lock cannot be acquired immediately. The operation is strict and all-or-nothing: any collision aborts the entire add.

Events

Name	Description
CorruptionDetected	Occurs when repository corruption is detected during a fetch or add operation. Corruption conditions (for example a variant alias whose source data file is missing) are surfaced through this event so monitoring and repair tooling can observe them, in addition to any direct exception or per-operation handling that already applies.
TransactionCompletionFailed	Occurs when a transaction-completion step (commit or rollback) fails. The handler receives a RepoTransactionCompletionFailureInfo carrying the operation that failed and the underlying exception, and can be used to log errors or perform custom error handling.