Interface IFileRepo

Represents a transactional file repository. Code written against this interface rather than the local FileRepo keeps working when another implementation, such as a repository served remotely, replaces the local directory one.

Inherited Members
Namespace: FulcrumFS
Assembly: FulcrumFS.dll
Syntax
public interface IFileRepo : IFileRepoCleaner
Remarks

The interface covers everything an application does with a repository once it exists: transactions that add and delete main files, fetching files and variants, adding and retiring variants, enumeration, cleanup and the events that report failures and corruption. Creating, configuring and opening a repository are not part of it, since they depend on the implementation, and nothing on it exposes a local path: file content is read through OpenReadAsync(FileAccessPattern, CancellationToken), OpenAsync(FileId, FileAccessPattern) and OpenVariantAsync(FileId, string, FileAccessPattern).

Fetches do not read file sizes. Finding a file takes only its name, and a size would cost a separate metadata read for every fetched file and every member of a group, which a remote implementation would pay for on every request whether or not anyone wants it. A size is obtained on demand instead, through GetLengthAsync(CancellationToken), which costs nothing until it is called and is cached by the instance it is called on. The files an add returns know their sizes already, since the add has just written them. The streams that the open methods return are seekable, so Length on an opened stream is the size of the file too.

Implementations must be safe for concurrent use, so that one instance can serve a whole application. They must keep the commit model described on IFileRepoTransaction, including leaving a file whose commit or rollback failed accessible until a cleanup pass resolves it.

An implementation that generates file IDs in more than one place that is never coordinated with the others, such as a replicated implementation whose primary and secondary can both generate IDs after a fail-over, must keep enough random bits in each ID that the generators cannot collide. The version 7 IDs that Sequential generates keep 70 random bits for this reason, and the version 4 IDs of Secure are random apart from their version and variant bits.

Properties

Name Description
DeleteMode

Gets the mode in which deletions take physical effect.
FileIdMode

Gets the algorithm the repository uses to generate file IDs.
IsReadOnly

Gets a value indicating whether the repository is read-only.

Methods

Name Description
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.
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.
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.
BeginTransactionAsync()

Begins a new transaction, in which main files are added and deleted and which is committed or rolled back as a whole.
DeleteVariantsAsync(FileId, params ReadOnlySpan<string>)

Permanently retires the specified variants of a file, preserving any variant the caller did not list that depends on a listed one.
EnumerateFilesAsync(CancellationToken)

Enumerates every file group in the repository. Intended for recovery and audit tooling.
GetAsync(FileId)

Gets an existing main file.
GetGroupAsync(FileId)

Gets an existing file together with all of its variants.
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.
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.
GetVariantAsync(FileId, string)

Gets an existing variant of a file.
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.
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.
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.
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.

Events

Name Description
CorruptionDetected

Occurs when repository corruption is detected during a fetch or add operation, for example a variant alias whose source data file is missing.
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.