Contracts rfc functions by ibizaman · Pull Request #485453 · NixOS/nixpkgs

ibizaman · 2026-01-30T20:04:46Z

Second draft PR for showing implementation of the NixOS/rfcs#189 as well as 2 contracts example. I did not implement here the streaming backup service because it felt redundant and I rather had this PR published ASAP.

This PR is a sibling to the earlier #432529 PR. It is also incompatible with that PR. I personally prefer this implementation which is much closer to what I have in my SelfHostBlocks project. It is simpler to understand, does not lead to infinite recursions at the slightest mistake and the documentation just fine. I actually followed how modular services did it.

I purposely split the PR into similar commits as the #432529 one to allow easier apples to apples comparison.

What it does better than the first PR is:

Documentation can be built just fine. I copied screenshots here under so you can have a look.
When the user messes up, the error message is not an infinite recursion. It’s not to say the error message is great but it’s better than infinite recursion.
The default values set from a consumer can be accessed from within the global config. This was not the case is the first PR.

For example take this commit in the first PR 80ec05c where we are required to define the default values from within the config of the submodule. The reason is that otherwise the values of the input attrset are not accessible. It is not at all the style used in nixpkgs so it feels awkward.

Vs the same commit in this PR c6776a6?w=1 which is in the normal style of nixpkgs.

Commands that work in the PR are:

build manual: (cd nixos/; nix-build release.nix -A manual.x86_64-linux)
nix-build -A nixosTests.contracts-filebackup-restic
nix-build -A nixosTests.contracts-secrets-hardcoded-secret
nix-build -A nixosTests.restic
nix-build -A nixosTests.stash

Here are screenshots from the manual

contracts

services.restic.fileBackups

services.nextcloud.fileBackup

Things done

nixos-discourse · 2026-01-30T20:25:54Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/self-host-blocks-building-blocks-for-self-hosting-with-best-practices/26963/39

KiaraGrouwstra · 2026-02-02T13:45:17Z

thanks for getting this out!
i might be tending a bit toward full module system to facilitate overrides, tho for splitting out bits not requiring the round-trip at least, that distinction should not apply i think. ideally, by then, we may have found further feedback here on the implementation differences as well.

ibizaman · 2026-02-02T16:57:15Z

That's a fair point although TBH I don't know how much we'll need to override in practice. Also, this implementation is less prone to infinite recursion and works with the documentation which IMO makes it already better.

KiaraGrouwstra · 2026-02-02T17:39:38Z

+              type = submodule {
+                options = {
+                  content = mkOption {
+                    type = nullOr str;


just noticed this looks different from the original.
without having checked the content too much yet, could you comment on this difference maybe?
like, is there a reason this would work here yet not in the original?

Ah I think that's because in the previous PR, I stripped down the module to avoid adding unnecessary details. I just forgot to do it here 😅

ah, guess i got maybe the wrong one - i'd wondered about equivalents here of challenge sub-thread https://github.com/NixOS/nixpkgs/pull/432529/changes#r2328714550

ibizaman · 2026-02-04T17:01:47Z

I updated the description here to show what this PR does better than the first one.

KiaraGrouwstra · 2026-02-06T10:52:20Z

given the tasks listed are all marked as done, is there anything that would need to be done here before this PR can be switched from being listed as draft to ready for review?

ibizaman · 2026-02-06T16:32:11Z

@KiaraGrouwstra I don’t see anything but I don’t know how it works for RFCs. I still set it as ready.

ThinkChaos

Thanks for your work on this. I would really like a standard pattern for configuring secrets in NixOS!

My initial reaction was that it would make sense to use the module system more. I hacked up a quick demo then. Then today read the RFC again (last time was a long time ago). I realized independently landed on almost exactly the same thing as modules-interface! I've now also read the previous PR which seems closer to that.
I think doing that way has nice benefits because the module system takes care of some things for you, like propagating _file so errors point to the right place. It also seems more idiomatic to parametrize modules via config._module.args & config directly instead of using functors.
Basically my gut feeling is "I like the other version better". I'm not saying that as opposition to this implementation, just think multiple people landing on the same design is a good sign it. I might play with it more to get an idea of the issues you raise for myself.

Anyways, with this implementation, I think it's still possible to use modules in a more idiomatic way and left comments about that.
I also have opinions about the secrets contract. In general I think it makes sense to have the contracts promise the least possible, so providers have more flexibility in how they're implemented.

Are these APIs going to be frozen as soon as this PR is merged?
If not it could be nice to add a warning when accessing them to say they're still experimental.

Also high level, since contracts are for NixOS behavior, maye only the generic code should be in lib, and the contracts themselves all be defined in NixOS modules?

ThinkChaos · 2026-02-05T02:44:06Z

+  importContract =
+    module:
+    let
+      importedModule = import module { inherit lib; };
+    in
+    mkContractFunctions {
+      inherit (importedModule) mkConsumerOptions mkProviderOptions;
+    }
+    // {
+      inherit (importedModule) description behaviorTest;
+    };


This loses the module's filepath, which'll lead to confusing messages for errors generated from within the contract's code.

Along with my other suggestion of changing mkConsumer & mkProvider to return modules, you could use lib.setDefaultModuleLocation to let the module system know where the code is from, which will then be used for error messages.

I tried setting an option wrong, specifically setting this one to true instead of a path to a file and got:

… while evaluating the option `nodes.machine.testing.hardcoded-secret.mysecret.output.path': (stack trace truncated; use '--show-trace' to show the full, detailed trace) error: A definition for option `nodes.machine.testing.hardcoded-secret.mysecret.output.path' is not of type `string'. Definition values: - In `nixpkgs/nixos/modules/testing/hardcoded-secret.nix': true

It doesn't seem too bad to me. TBH after checking in nixpkgs I still have no idea how to use setDefaultModuleLocation.

I mean if the contract itself has a bug, say during development. Not the user code.
So for instance I added config.dummy = "plz-fail"; to the secret contract's mkConsumerOptions submodule type (here), and got this error:

error: The option `nodes.machine.testing.hardcoded-secret.mysecret.input.dummy' does not exist. Definition values: - In `/nix/store/pcsb7z45hwi5y5yhl91slz1443p3i78f-source/nixos/modules/testing/hardcoded-secret.nix': "plz-fail"

It confusingly points to nixos/modules/testing/hardcoded-secret.nix since that's what the closest _file attr contains. When the error was actually in lib/contracts/secrets.nix.

See my other review for a partial fix.

ThinkChaos · 2026-02-06T17:44:31Z

+          restartUnits = mkOption {
+            description = ''
+              Systemd units to restart after the secret is updated.
+            '';
+            type = listOf str;
+            default = restartUnits;
+          };


I have a custom secrets solution, and it only decrypts secrets when the unit using them is actually running, so "restart" doesn't really make sense in that context.
I'd propose a more generic name like "dependentUnits" or something along those lines.

ThinkChaos · 2026-02-06T17:46:05Z

+                This path will exist after deploying to a target host,
+                it is not available through the nix store.


Same here, "This path will exist after deploying to a target host" sounds like to large of a guarantee. I think we should constrain it to something like "will exist when the dependent units run".

Actually, I think we should be more generic. Maybe something that doesn't use systemd units depend on the secret. This should probably list a series of commands.

Or could this be a good use case for overriding contracts? There could be a plain contract without this option, another one for systemd units and another one with a list of commands to run?

ibizaman · 2026-02-06T19:08:30Z

@ThinkChaos thank you for the review.

multiple people landing on the same design is a good sign it

I cannot agree more! I like the other implementation but the shortcomings feel to me like show stoppers. If they can be solved, that would be great. I tried at the time when creating the other PR but I got to the point where I needed to modify the module system itself. But I didn't know its inner workings enough to even know what I was looking for.

To be bluntly honest, I don't particularly care about a specific implementation. I care much more about getting the idea through with some properties I find important and also getting momentum going in the community.

In general I think it makes sense to have the contracts promise the least possible

Fully agreed too. From my experience writing Golang, that was one of the best properties of interfaces and the reason why I didn't want to introduce too many options in contracts either.

Are these APIs going to be frozen as soon as this PR is merged?

I would discourage freezing them. At least not until we have a handful of contracts with a handful of consumer and provider modules each.

Also high level, since contracts are for NixOS behavior, maye only the generic code should be in lib, and the contracts themselves all be defined in NixOS modules?

Sure, that makes sense.

KiaraGrouwstra · 2026-02-06T19:13:09Z

on the secrets contract, i'm also sort of wondering still if that might go well with say systemd's LoadCredential (also used in e.g. systemd-vaultd / systemd-openbaod)

ThinkChaos

Just a basic example of what's needed to set the generated module's _file to get errors to point to the implementation's file.

lib.setDefaultModuleLocation is the main part: it basically sets _file in the module, which is a special attr the module system uses to know where the module was originally defined.

This isn't perfect though:

_file = modulePath should only apply to the result of mkConsumerOptions & mkProviderOptions, whereas here it also applies to user code via inputDefaults
the module defined in this file itself, i.e. the return value of mkConsumer, is reported being part of modulePath, not lib/contracts/default.nix. In this case the module is trivial, but over time that might no longer be true and lead to confusion again.
mkProvider needs a similar adjustment

(Using deferredModule gives us this for free by propagating _file from where the option was set in the original config)

ThinkChaos · 2026-02-06T22:02:54Z

+      importedModule = import module { inherit lib; };
+    in
+    mkContractFunctions {
+      inherit (importedModule) mkConsumerOptions mkProviderOptions;


Suggested change

inherit (importedModule) mkConsumerOptions mkProviderOptions;

modulePath = module;

inherit (importedModule) mkConsumerOptions mkProviderOptions;

ThinkChaos · 2026-02-06T22:03:20Z

+
+  mkContractFunctions =
+    {
+      mkConsumerOptions,


Suggested change

mkConsumerOptions,

modulePath,

mkConsumerOptions,

ThinkChaos · 2026-02-06T22:17:33Z

+      mkConsumer = inputDefaults: {
+        options = {
+          input = mkConsumerOptions inputDefaults;
+
+          output = mkProviderOptions { } // {
+            visible = "shallow";
+          };
+        };
+      };


mkConsumer = inputDefaults: lib.setDefaultModuleLocation modulePath { input = mkConsumerOptions inputDefaults; output = mkProviderOptions { } // { visible = "shallow"; }; };

KiaraGrouwstra · 2026-03-03T14:41:42Z

having compared the further with the original PR, i no longer so much feel so reluctant on this approach anymore.

for documentation purposes though, it would be good to get an example of the type of cases where this approach is more robust to user errors than the original, and what kind of error messages one might get here for those issues compared to in the original.

KiaraGrouwstra · 2026-03-14T23:09:20Z

+  inherit (lib.types) listOf submodule str;
+in
+{
+  mkConsumerOptions =


these mk*Options functions seem like a clunky way of merging option types.
as an additional data point in this space, i tried an approach to this that abstracts over (potentially nested) attributes as well as over types of info to put in (default, defaultText, ...).
i suppose ideally, since using and perhaps declaring options for secrets are fairly common operations, it might make sense to try and look for a somewhat terse approach to this.
i dunno if this is the right way, but maybe it'll help give some ideas at least.

I really like this approach. It even works when building the docs! Seems like we’re in to something now.

filed at #500287 for feedback

contract: init underlying module

ca00371

ibizaman force-pushed the contracts-rfc-functions branch from 492afb4 to 0f2e463 Compare January 30, 2026 20:09

ibizaman requested review from KiaraGrouwstra, aforemny, fricklerhandwerk and roberth January 30, 2026 20:09

nixpkgs-ci Bot added the 2.status: merge conflict This PR has merge conflicts with the target branch label Jan 30, 2026

nixpkgs-ci Bot added 10.rebuild-linux: 1-10 This PR causes between 1 and 10 packages to rebuild on Linux. 10.rebuild-darwin: 1-10 This PR causes between 1 and 10 packages to rebuild on Darwin. 10.rebuild-darwin: 1 This PR causes 1 package to rebuild on Darwin. labels Jan 30, 2026

KiaraGrouwstra reviewed Feb 2, 2026

View reviewed changes

This was referenced Feb 4, 2026

[RFC 0189] Contracts NixOS/rfcs#189

Open

Contracts RFC 189 #432529

Draft

ibizaman marked this pull request as ready for review February 6, 2026 16:32

nixpkgs-ci Bot requested review from hsjobeki and infinisil February 6, 2026 16:46

ThinkChaos reviewed Feb 6, 2026

View reviewed changes

ibizaman added 5 commits February 6, 2026 20:17

contract for secrets: init

ab72ed6

hardcoded-secret: new contract for secrets consumer

45bcadf

contract for secrets: declare behavior test

da39055

hardcoded-secret: define behavior test for contract for secrets

e39ea8f

stash: use contract for secrets

4a1814e

ibizaman added 7 commits February 6, 2026 20:17

filebackup contract: init

df410d5

restic: implement file backup contract provider

be3b731

filebackup contract: declare behavior test

328978e

restic: define file backup contract behavior test

4df3c48

contracts: add documentation

3e6a375

nextcloud: use file backup contract

68983f4

make mkConsumer and mkProvider return a module

3fb7107

ibizaman force-pushed the contracts-rfc-functions branch from 0f2e463 to 3fb7107 Compare February 6, 2026 20:11

ThinkChaos reviewed Feb 6, 2026

View reviewed changes

KiaraGrouwstra mentioned this pull request Feb 15, 2026

modular services: porting legacy modules consisting of multiple services #490688

Open

KiaraGrouwstra mentioned this pull request Mar 3, 2026

Contract for files containing secrets #495303

Open

13 tasks

KiaraGrouwstra reviewed Mar 14, 2026

View reviewed changes

KiaraGrouwstra mentioned this pull request Mar 16, 2026

contracts RFC - alternate implementation using generated options #500287

Closed

13 tasks

KiaraGrouwstra mentioned this pull request Apr 3, 2026

contracts: init #506343

Open

17 tasks

		This path will exist after deploying to a target host,
		it is not available through the nix store.

	inherit (importedModule) mkConsumerOptions mkProviderOptions;
	modulePath = module;
	inherit (importedModule) mkConsumerOptions mkProviderOptions;

Uh oh!

Conversation

ibizaman commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Things done

Uh oh!

nixos-discourse commented Jan 30, 2026

Uh oh!

KiaraGrouwstra commented Feb 2, 2026

Uh oh!

ibizaman commented Feb 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibizaman commented Feb 4, 2026

Uh oh!

KiaraGrouwstra commented Feb 6, 2026

Uh oh!

ibizaman commented Feb 6, 2026

Uh oh!

ThinkChaos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibizaman commented Feb 6, 2026

Uh oh!

KiaraGrouwstra commented Feb 6, 2026

Uh oh!

ThinkChaos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KiaraGrouwstra commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ibizaman commented Jan 30, 2026 •

edited

Loading

KiaraGrouwstra commented Mar 3, 2026 •

edited

Loading