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. 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), an optional flag marking the ones that are applications in the glossary sense, and a configurable flag marking the ones the operator form shows, which holds for every application. The per-component configuration options themselves are filled in by concrete component modules; the configurable ones appear, wired up, on the operator configuration page.
  • applications -- the configurable components, derived read-only from components.<name>.configurable. 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. Contracts and data flow shows where resources fit in a deployment, and how they use contracts. 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 a process function and an apply function. process takes the requests of the components that it gets, selects the requests for this resource and gives them to apply. apply checks or renames each request and turns the requests into the resource. Most policies of a resource that wraps a contract also have a routing module. This module selects the provider of the contract and gives the provider its coordinates, for example an address and a port.

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.

A setup runs one environment per node, and gives process only the requests of the component on that node. Thus a policy does not combine the requests of different components. supportingRequests collects the requests across components and groups, and the provider of the contract combines them.

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>.artwork

The file in this repository that gives the scalable artwork the component is shown by: a function { pkgs, sources }: { icon; iconDark ? null; }, where iconDark is the variant for a dark background. A surface in dark mode shows iconDark in place of icon, or icon if it is null. core/lib/artwork.nix calls the file.

A path and not the artwork, so that the plan of a node holds no store path. The file takes the artwork out of the upstream source (pkgs.<name>.src) instead of keeping it in this repository, so that the artwork an operator sees is the artwork the project ships. For a project whose source has no logo, it takes it from another repository of the project, pinned in npins. null for a component that no surface shows artwork for.

Type: null or absolute path

Default:

null

Declared by:

components.<name>.configurable

Whether the operator form shows this component and the options of its module. An optional component is always configurable, because the operator must be able to turn it on. Other components can declare their module options for the deployment only, so they are configurable only when they say so.

Type: boolean

Default:

optional

Declared by:

components.<name>.description

What the component is, for an operator choosing it.

A component states its own only where its part in a deployment is not what the project describes: valkey is a cache node with one instance per application, which pkgs.valkey has no way to say.

Type: string

Default: package.meta.description

Declared by:

components.<name>.homepage

Home page of the project behind the component.

Type: null or string

Default: package.meta.homepage

Declared by:

components.<name>.module

Operator-facing configuration options for the component

Type: module

Default:

<function>

Declared by:

components.<name>.name

The name the component is called by, capitalized the way the project capitalizes itself (PeerTube, OpenBao).

Stated here because nixpkgs carries no display name: pname is an attribute name, lowercase by convention, while every surface an operator reads shows the project its own way.

Type: string

Default: the attribute name the component is declared under

Declared by:

components.<name>.optional

Whether the operator turns this component on and off: it is an application in the glossary sense, software the operator picks. Components left at false are infrastructure that the applications need, and a deployment runs them without a choice from the operator.

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 the requests

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

Declared by:

resources.<name>.policy.apply-input-type

The type of the argument of apply. A policy whose own process keys the requests sets it. Each call of apply checks only the outer shape of its argument against this type.

Type: optionType

Declared by:

resources.<name>.policy.process

Select the requests for this resource from the given 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>.policy.routing

A module that the resource merges into the eval of the contract provider. The module selects the provider and gives the provider its context, for example an address and a port. A resource that wraps no contract does not read this option.

Type: module

Default:

{ }

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: