Self Host Blocks - Building blocks for self-hosting with best practices

kiara · April 3, 2026, 5:32pm

contracts: init

master ← KiaraGrouwstra:contracts-automated

opened 04:53PM - 03 Apr 26 UTC

Implements contracts (https://github.com/NixOS/rfcs/pull/189) by building on the… work by @ibizaman (and [earlier work](https://github.com/fricklerhandwerk/module-interfaces) by @fricklerhandwerk). Main differences between our implementation and RFC 189: 1. **Topology: point-to-point vs aggregated:** The RFC has each consumer directly link to one provider (consumer.provider = config.services.restic...), with bidirectional references (provider.consumer = config.services.nextcloud...). We use centralized aggregation - consumers register into `contracts.<type>.want`, providers register into `contracts.<type>.providers`, and a `defaultProvider`/`defaultProviderName` selects which provider fulfills all requests. This avoids the 'dual-link' problem the RFC mentioned. 1. **[Modular service](https://nixos.org/manual/nixos/stable/#modular-services) support:** The RFC doesn't address modular services. We implement a bridge pattern to give modular services the same API for using contracts as NixOS modules. 1. **Cross-system support:** The RFC is NixOS-only. Our `lib/contracts/module.nix` and `lib/services/` are system-agnostic, designed to pave the way for contracts support from other systems managing nix (modular) services, e.g. home-manager, nimi, nix-darwin, finix, NixBSD, etc. 1. **Contract type registration:** The RFC defines contracts inline as `contracts.<name>` with `deferredModule` types. We separate type definitions (`contractTypes`) from instances (`contracts`), with types shipped in `lib.contracts` (usable from the sandbox for docs builds) and extensible from outside nixpkgs via `config.contractTypes` (without such docs). 1. **Naming: input/output vs request/result:** The RFC uses input/output. We use request/result. This is more specific about the directionality (a consumer requests, a provider produces results), and more consistent with [SelfHostBlocks](https://github.com/ibizaman/selfhostblocks). Tests relevant to verify changes: - `bash lib/tests/modules.sh` - `nix-instantiate --eval lib/services/test.nix` - `nix-build -A nixosTests.contracts` - `nix-build -A stash.passthru.tests.stash` - `nix-build nixos/release.nix -A manual.x86_64-linux` (rendered docs at `options.html`) Note I have made use of a coding agent to get things to this state. Supersedes: #432529, #485453, #495303, #500287. ## Things done - Built on platform: - [x] x86_64-linux - [ ] aarch64-linux - [ ] x86_64-darwin - [ ] aarch64-darwin - Tested, as applicable: - [x] [NixOS tests] in [nixos/tests]. - [ ] [Package tests] at `passthru.tests`. - [x] Tests in [lib/tests] or [pkgs/test] for functions and "core" functionality. - [ ] Ran `nixpkgs-review` on this PR. See [nixpkgs-review usage]. - [ ] Tested basic functionality of all binary files, usually in `./result/bin/`. - Nixpkgs Release Notes - [ ] Package update: when the change is major or breaking. - NixOS Release Notes - [ ] Module addition: when adding a new NixOS module. - [ ] Module update: when the change is significant. - [ ] Fits [CONTRIBUTING.md], [pkgs/README.md], [maintainers/README.md] and other READMEs. [NixOS tests]: https://nixos.org/manual/nixos/unstable/index.html#sec-nixos-tests [Package tests]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md#package-tests [nixpkgs-review usage]: https://github.com/Mic92/nixpkgs-review#usage [CONTRIBUTING.md]: https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md [lib/tests]: https://github.com/NixOS/nixpkgs/blob/master/lib/tests [maintainers/README.md]: https://github.com/NixOS/nixpkgs/blob/master/maintainers/README.md [nixos/tests]: https://github.com/NixOS/nixpkgs/blob/master/nixos/tests [pkgs/README.md]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md [pkgs/test]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/test

i think i’m feeling more confident this may cover likely use-cases now.