Fediversity

Feature Specification: Resource nixos-module

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code at 093e68b6f (core/resources/nixos-module/default.nix, core/setups/hosts-common.nix, the "code".nixos-module requests in core/components/), pull request #1184.

User Scenarios & Testing (mandatory)

The nixos-module resource passes a NixOS module from a component to its node unchanged. It wraps no contract and selects no provider. The shared resource rules are in the resource family spec.

User Story 1 - Add a component's own NixOS configuration (Priority: P1)

A component needs NixOS settings that no other resource expresses, for example the service module of the component. The component requests "code".nixos-module.module = { ... }. apply returns a list with the policy module first and then each requested module. The node imports the list.

Why this priority: 13 components put their main NixOS configuration on the node through this resource.

Independent Test: nix-unit-resources-nixos-module evaluates the apply output as a node. Each check that builds a node with such a component also evaluates it.

Acceptance Scenarios:

  1. Given a component that requests "code".nixos-module.module.imports = [ ../bind.nix ], When its node evaluates, Then the node imports ../bind.nix.
  2. Given two requests on one node, When process runs, Then the list holds both modules after the policy module.

User Story 2 - Add a module from the environment (Priority: P3)

An environment can add one module to every node that uses it. It sets the policy option module. core/setups/hosts-common.nix sets "fediversity".nixos-module = { }, so the policy module is empty there.

Why this priority: the setups use no policy module.

Independent Test: no check covers a non-empty policy module.

Acceptance Scenarios:

  1. Given the policy module = { }, When process runs, Then the list starts with an empty module.

Edge Cases

  • A node whose component makes no request still gets a list with the policy module.
  • The request module has type unspecified. The module system of the node checks its content.

Requirements (mandatory)

Functional Requirements

  • FR-001: The request MUST accept module of any type.
  • FR-002: The policy MUST accept module (default { }).
  • FR-003: apply MUST return [ policy.module ] followed by the module of each request, in request order.
  • FR-004: core/setups/hosts-common.nix MUST add the process output to the imports of each node.

Key Entities

  • module: a NixOS module, given as-is by a component or by the environment.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: nix-unit-resources-nixos-module passes, and every component check that builds a node with a "code".nixos-module request evaluates without error.

Assumptions

  • A component author uses this resource only for settings that no dedicated resource covers.

Known Deviations

None.