Fediversity

Data model

The Fediversity data model is the typed configuration system at the heart of the project. It is declared in core/lib/data-model.nix and evaluated together with the resource modules under core/resources (garage, network, secrets, authelia, otel, nixos-module). This page documents its own top-level options; the hosting resources page documents the concrete request options each resource declares.

The data model's options

The data model surfaces these top-level options, declared in core/lib/data-model.nix:

  • resources -- the collection of deployment resources components can require and hosting providers can police. Each resource declares a description, a request module, and a policy module.
  • components -- the collection of Fediversity components: every piece of software the project knows how to deploy, applications and the infrastructure they need alike. Each has a description, a module (its configuration), and an operatorFacing flag marking the ones that are applications in the glossary sense. The per-component configuration options themselves are filled in by concrete component modules; the operator-facing ones appear, wired up, on the operator configuration page.
  • applications -- the operator-facing components, derived read-only from components.<name>.operatorFacing. This is what narrows frontendConfiguration; it does not affect what gets deployed.
  • environments -- the run-time environments components are deployed to. An environment ties together the resources a hosting provider makes available (and their policies) with the functions that turn an operator configuration into a deployable result. Its sub-options are shown below; because they are config-dependent functions and policy trees rather than concrete values, they are documented informally (a prose description with the real type replaced by a short note).
  • configuration -- the configuration type operators set (enabling components and the apex domain). Carries every declared component, because the deploy path enables the infrastructure ones too.
  • frontendConfiguration -- the same type narrowed to applications, so the panel form, the JSON schema and the operator configuration page only offer what an operator picks.
  • supportingRequests -- resource requests not tied to a single component.

An environment's sub-options are:

  • resources -- the per-resource policies the provider offers (optional; shape fixed by each resource's policy module).
  • implementation -- the provider-written function mapping the components' required resources to this environment's resources, yielding a deployment.
  • resource-mapping -- the type-checked function type of implementation (required resources in, deployment out).
  • config-mapping -- the mapping from an operator configuration to a deployment: resolve each component's required resources, then apply resource-mapping.
  • deployment -- the end-to-end entry point: apply the environment's policies to the components' resource mappings (by default, config-mapping applied).

The matching function-typed sub-options of components (implementation, config-mapping, resources) work the same way: they map a component's configuration to the resources it requires. Their types reference configuration only defined for a concrete deployment, so they too are described here rather than shown with a concrete type. The same applies to the effect and env-output options, which are bare type-valued options whose structure lives entirely in their defaults.

The request/policy resource pattern

A resource is the abstraction that bridges what a component needs and what a hosting provider offers. Each resource declares two module types:

  • resources.<name>.request describes how a component consumes the resource. Components set these options to declare their requirements. The data model declares request as a deferred module, so these concrete sub-options live in the resource configuration rather than in the option type; they are surfaced on the hosting resources page by building a submodule from each resource's request module.
  • resources.<name>.policy describes how a hosting provider makes the resource available. A policy carries an apply function that turns a list of requests into the concrete resource, and a process function that collects the relevant requests across all components before applying the policy.

Resource policies are provider-facing and carry computed defaults that reference other options only defined for a concrete deployment, so they are documented through the generic resources.<name>.policy structure below rather than per resource.

Components map their configuration to resource requests; environments map those requests to a deployment by applying the hosting provider's policies.

Options

components

Collection of Fediversity components

Type: attribute set of (submodule)

Declared by:

components.<name>.description

Description to be shown in the component overview

Type: string

Declared by:

components.<name>.module

Operator-facing configuration options for the component

Type: module

Default:

<function>

Declared by:

components.<name>.operatorFacing

Whether this component is an application in the glossary sense: software the operator picks, configures and toggles. Components left at false are infrastructure the applications need and the operator never chooses.

Type: boolean

Default:

false

Declared by:

configuration

Configuration type declaring options to be set by operators. Carries every declared component, so the deploy path (default-configuration, which enables every roster node including the infrastructure nodes) type-checks against it.

Type: optionType

Declared by:

environments

Run-time environments for Fediversity components to be deployed to

Type: attribute set of (submodule)

Declared by:

environments.<name>.config-mapping

The mapping from an operator configuration to a deployment: it resolves each enabled component’s required resources and then applies this environment’s resource-mapping. Declared as a type-checked function whose output is a deployment (env-output).

Type: type-checked function type (configuration -> deployment)

Declared by:

environments.<name>.deployment

Generates a deployment from a configuration by applying this environment’s resource policies to the components’ resource mappings. By default this is just config-mapping applied, i.e. the end-to-end “configuration in, deployment out” entry point for the environment.

Type: function: configuration -> deployment (applies the env’s policies)

Declared by:

environments.<name>.implementation

Maps the resources required by the deployed components to the resources this environment actually offers, producing something that can be deployed. This is the environment-specific glue a hosting provider writes; its exact function type (resource-mapping.function-type) is fixed per deployment.

Type: function: required component resources -> deployment

Declared by:

environments.<name>.resource-mapping

The function type for implementation: it takes the components’ required resources (plus a deployment name) and returns a deployment (env-output). Declared as a type-checked function so inputs and outputs are validated.

Type: type-checked function type (resources -> deployment)

Declared by:

environments.<name>.resources

Resources the hosting provider makes available in this environment, keyed by resource name, each holding that resource’s policy (how the provider supplies it). Setting this is optional; it is a place to declare provider-side resource information for use in the resource mapping. The concrete shape of each entry is fixed by the matching resource’s policy module under core/resources, so it depends on which resources the environment wires in.

Type: per-resource policies the hosting provider makes available (shape set by each resource’s policy module)

Declared by:

resources

Collection of deployment resources that can be required by components and policed by hosting providers

Type: attribute set of (submodule)

Declared by:

resources.<name>.description

Description of the resource to help component module authors and hosting providers to work with it

Type: string

Declared by:

resources.<name>.policy

Options for configuring the resource policy for the hosting provider, a description of how the resource is made available

Type: module

Declared by:

resources.<name>.policy.apply

Apply the policy to a request

Type: function that evaluates to a(n) unspecified value

Declared by:

resources.<name>.policy.process

Collect the relevant requests across all components, then apply the policy to them

Type: function that evaluates to a(n) unspecified value

Declared by:

resources.<name>.policy.resource-type

The type of resource this policy configures

Type: optionType

Declared by:

resources.<name>.request

Options for declaring resource requirements by a component, a description of how the resource is consumed or accessed

Type: module

Default:

{ }

Declared by:

supportingRequests

Supporting resource requests not tied to a single component, made available to every environment.

Type: module

Default:

{
  options = { };
}

Declared by: