Namespace Fabricator.Core

The Fabricator.Core package includes the definitions of the core Fabricator interfaces.

Resource checks and applications receive a ResourceContext pinned to the running operation. Its IReporter allows to report:

a short status of the operation (Status), shown next to it in the live progress display;
the progress of the operation (WithProgress), either determinate (with the known total) or not, in abstract items or in bytes;
the log lines (Log). The logs of concurrently running operations are never interleaved: the lines of the operations that are not shown at the moment are buffered until their turn comes.

Use ResourceContext.Null to call the resource functions directly, e.g. in tests.

Secrets

If a resource requires secrets (passwords, access tokens, etc.), it should list them in Resource.Secrets. Each SecretRequest contains a SecretRef naming a secret in an ISecretStore, and defines which operations of the resource require it: the check, the application, or both. Resources taking secrets from the user should accept them as SecretRefs, and decide themselves which operations require them.

The secrets are handled the following way:

Before checking or applying anything, Fabricator opens every store that might be required by the execution, one by one. While opening, a store may interact with the user via ISecretStoreUi, e.g. to ask for its own password. It also receives the names of the secrets it's about to be asked for, which it may use to prefetch them (not recommended for the purpose of security, but can be done). If any store fails to open, nothing is checked or applied.
Right before an operation starts, the secrets it requires are fetched from the opened stores, and passed to it via ResourceContext.Secrets, by their SecretRefs. If a secret fails to be fetched, the operation fails.
Right after the operation finishes, its secrets are disposed automatically. Every secret string is single-use: the operation is encouraged to dispose it as soon as it's not needed anymore, even before the operation finishes.
After all the operations have finished, the opened stores are closed.

Stores and secret references are compared by reference.

Note that SecureString in the API provides little actual protection. Fabricator uses it mostly to indicate that the string has to be handled carefully, and to clean it up from the memory as soon as possible.

PlainSecretStore is the simplest store implementation: it asks the user to enter every required secret when opening. It is not secure: the entered secrets are kept in the process memory for the whole Fabricator session. Only use it for simple cases, when you're fine with entering the secrets manually on every run, and have no security concerns about keeping them in the process memory for longer than strictly needed.

Classes

ConcurrencyGroup: A group of resources sharing some part of the environment that is not safe to check or change concurrently, e.g. the same file or the same package manager. Fabricator never runs checks or applications of resources from the same group concurrently.

Diff: A change of a text entity, e.g. a file, presented as a patch.

PlainSecretStore: A secret store asking the user to enter every requested secret when opening, and keeping the entered secrets in the process memory until the end of the execution.

ProgressReporter: Helper functions to work with <see cref="T:Fabricator.Core.IProgressReporter"/>.

ProgressUnit: The unit of the values reported via <see cref="T:Fabricator.Core.IProgressReporter"/>, used to present them.

ProgressUnit.Tags

Reporter: Helper functions to work with <see cref="T:Fabricator.Core.IReporter"/>.

Resource: A resource is a part of the desired environment state that Fabricator is able to check and apply.

ResourceChange: A change of the environment required to apply a resource (as returned from AlreadyApplied), or made by applying it (as returned from Apply).

ResourceChange.NamedChange: A human-readable description of the change, e.g. new service "name". May contain several lines.

ResourceChange.Tags

ResourceChange.TextDiff: A change of a text entity, e.g. a file. Shown as a patch.

ResourceContext: The context of a resource check or application.

ResourceContextModule: Helper functions to work with <see cref="T:Fabricator.Core.ResourceContext"/>.

ResourceModule: Helper functions to work with <see cref="T:Fabricator.Core.Resource"/>.

SecretName: The name of a secret in a secret store, e.g. SecretName "dns-provider-token". This is a label used to look the secret up.

SecretRef: A reference to a secret: the store, and the name of the secret in the store. Resources requiring secrets from the user should accept them as references.

SecretRequest: A secret required by a resource, and the operations requiring it. See Secrets.

SecretRequestMode: Defines which operations of a resource require a secret, see SecretRequest.

SecretRequestMode.Tags

SecretStoreContext: Optional information about the upcoming use of a secret store, passed to Open(ISecretStoreUi, SecretStoreContext). Most stores may ignore it, but some might use it, e.g. to prefetch the secrets while opening.

Secrets

Interfaces

IProgressReporter: Reports the progress of an operation started via <see cref="M:Fabricator.Core.IReporter.WithProgress"/>.

IReporter: Reports the status, progress, and log of the resource check or application it is passed to.

ISecretStore: A secret store: a storage of the secrets (passwords, tokens, etc.) required by the resources, see Secrets.

ISecretStoreScope: An opened secret store, see Open(ISecretStoreUi, SecretStoreContext). Disposing the scope closes it.

ISecretStoreUi: The user interface available to a secret store while it is being opened (see Open(ISecretStoreUi, SecretStoreContext)).

Table of Contents

Namespace Fabricator.Core

Secrets

Classes

Interfaces