I’m trying something else for upstreaming contracts. This is a contract with no clever implementation, just old plain options. I hope this will help focus the discussions on what I realize is the most important, the actual options and expected behavior of the contract #495303
4 Likes
kiara
March 16, 2026, 3:55am
42
how many PRs for an initial implementation can we get?
well, here’s a fourth!
master ← KiaraGrouwstra:contracts-secret-generated
opened 03:53AM - 16 Mar 26 UTC
This is a PR for contracts (https://github.com/NixOS/rfcs/pull/189), using a `fi… leSecrets` contracts as an example.
This iteration is similar to the earlier:
- #432529: like that PR made for a somewhat clean API, but the current PR addresses its docs build failure by avoiding `config` use within types
- #485453: the conceptual basis for the current PR, tho the current one reconstructs options to make for a cleaner API
- #495303: similarly limited to `fileSecrets`, and built on top of by the current PR to address its duplication
Feedback welcome!
## 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
4 Likes
kiara
April 3, 2026, 5:32pm
43
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.
4 Likes