Class FileRepo

Represents a transactional file repository stored in a local directory.

Inheritance

object

FileRepo

Implements

IFileRepo

IFileRepoCleaner

IDisposable

Namespace: FulcrumFS

Assembly: FulcrumFS.Local.dll

Syntax

public sealed class FileRepo : IFileRepo, IFileRepoCleaner, IDisposable

Remarks

Code that only uses a repository, rather than creating and configuring it, can depend on IFileRepo instead, so that another implementation can replace this one. The members that return local types, such as RepoFileInfo with its path, implement the interface members explicitly.

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, RepoFormatVersion, Action<FileRepoOptions>?)	Initializes a new instance of the FileRepo class with the specified base directory, minimum format version and optional configuration action.

Properties

Name	Description
DeleteMode	Gets the mode in which deletions take physical effect, as configured by DeleteMode.
FileIdMode	Gets the algorithm the repository uses to generate file IDs, as configured by FileIdMode.
FilesDirectory	Gets the directory where files are stored.
FormatVersion	Gets the format version that the repository actually has, as read from its info file when this instance opened the repository or written to it by an upgrade at that point.
IsReadOnly	Gets a value indicating whether the repository was opened read-only, as configured by ReadOnly.
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.
BeginStagedTransactionAsync()	Begins a new staged transaction for the file repository: a transaction that records all of its deletions in a single journal file, for application transactions that delete many files. It is committed in two calls, StageAsync(CancellationToken) before the application commits its database and CommitAsync(CancellationToken) after.
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 it or repairing its directory structure as necessary, and then initializes this instance exactly as EnsureInitialized() does. When this method returns, the repository exists and this instance has it open.
EnsureInitialized()	Initializes this instance on an existing repository: verifies it, acquires the repository lock and upgrades it to MinimumFormatVersion if it is older. Unlike EnsureCreated(), this method does not create a repository that does not exist.
EnumerateFilesAsync(CancellationToken)	Enumerates every file group in the repository. Intended for recovery and audit tooling.
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.
OpenAsync(FileId, FileAccessPattern)	Opens a file stream for an existing file in the repository using the recommended sharing options.
OpenVariantAsync(FileId, string, FileAccessPattern)	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.

Explicit Interface Implementations

Name	Description
IFileRepo.AddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Adds a new variant (and any nested variants declared by the pipeline) to an existing file. Variants are not transactional: the add is committed by the time it returns.
IFileRepo.AddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Adds a new variant (and any nested variants declared by the pipeline) to an existing file. Variants are not transactional: the add is committed by the time it returns.
IFileRepo.BeginStagedTransactionAsync()	Begins a new staged transaction, for application transactions that delete many files. It is committed in two calls, StageAsync(CancellationToken) before the application commits its database and CommitAsync(CancellationToken) after.
IFileRepo.BeginTransactionAsync()	Begins a new transaction, in which main files are added and deleted and which is committed or rolled back as a whole.
IFileRepo.GetAsync(FileId)	Gets an existing main file.
IFileRepo.GetGroupAsync(FileId)	Gets an existing file together with all of its variants.
IFileRepo.GetOrAddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Adds the variants of a tree (a top-level variant and any nested variants declared by the pipeline) that do not exist yet, and returns every variant in the tree, whether it was added now or existed already.
IFileRepo.GetOrAddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Adds the variants of a tree (a top-level variant and any nested variants declared by the pipeline) that do not exist yet, and returns every variant in the tree, whether it was added now or existed already.
IFileRepo.GetVariantAsync(FileId, string)	Gets an existing variant of a file.
IFileRepo.OpenAsync(FileId, FileAccessPattern)	Opens a read-only, seekable stream over the content of an existing main file. The caller owns the stream and must dispose it.
IFileRepo.OpenVariantAsync(FileId, string, FileAccessPattern)	Opens a read-only, seekable stream over the content of an existing variant of a file. The caller owns the stream and must dispose it.
IFileRepo.TryAddVariantAsync(FileId, string, IFileProcessingPipelineSelector, CancellationToken)	Tries to add a new variant (and any nested variants declared by the pipeline) to an existing file. The operation is all-or-nothing: it returns null without adding anything if any variant ID in the tree already exists or is being added concurrently.
IFileRepo.TryAddVariantAsync(FileId, string, string?, IFileProcessingPipelineSelector, CancellationToken)	Tries to add a new variant (and any nested variants declared by the pipeline) to an existing file. The operation is all-or-nothing: it returns null without adding anything if any variant ID in the tree already exists or is being added concurrently.