Repository navigation
Den v0.20.0
The headline change is #694: a user's aspects stop leaking into the hosts it's on. It arrives with a migration window, so upgrading changes nothing for your systems today. Den keeps the old behaviour until 2027-01-01 and warns about every host that depends on it.
Coming from an older release? The new What's changed in Den page summarises every release since 0.1, ending with a one-jump upgrade checklist.
User aspects stay with the user (#694)
Until now, anything a user aspect wrote to nixos, darwin or os reached every host that user was on, so one user's aspect could change a shared host for everyone. From 2027-01-01, that content stays with the user. It reaches a host only through a channel that names it, or because the host accepts it.
Until then, nothing changes without telling you:
- Transition defaults keep today's behaviour. These are
user-aspectsandmutual-provideron every host. - Each host that relies on them gets one warning, listing the content that reaches it only that way, by user and aspect.
- Some entries need nothing. An aspect written to work on a host or a user is meant to do nothing on the host when it's placed on a user.
- For the rest, the announcement (#750) gives the fix for each case. Usually you include the aspect on the host, use the
userclass for account settings, includeden.batteries.mutual-providerforprovides.to-hosts, or includeden.batteries.user-aspectsto keep today's behaviour on purpose. - To adopt the new behaviour now and silence the warnings:
den.migrations.user-host-content.acknowledged = true; # remove after 2027-01-01
Den's own templates, and the configs we tested, evaluate to the same systems as v0.19 with the transition defaults on. The one difference: an extraGroups list that v0.19 duplicated is now deduplicated. The cutover itself is tracked in #759.
New: a host chooses what it receives (#756)
These change nothing until you use them. See Receiving Content for examples.
-
den.lib.policy.include.at <entity> <aspect>names the entity a policy's content attaches to.include.atClass <class>names the class too, for an entity that has none of its own. -
admits, on a host or onden.schema.host, decides which deliveries land:denywithholds named ones;default = "deny"with anallowlist refuses everything else, and the error names what to add.
Den's own channels (home-manager, hjem, maid, the
userclass, shells) always land. -
policyEnforcement("strict","per-policy"or"lenient") andden.lib.policy.strictdecide who may exclude a policy. -
Excludes name exactly what they remove. Excluding an aspect on a host also removes the policies it carries for that host's users. Excluding a policy removes that record only, and still reaches it through
when,forandstrict.
Policy dispatch is more predictable (#749, #751, #752)
- A policy reaches every level below where it's registered. Before, a
{ host, user }policy registered on an environment never reached that environment's users, and a host with a single user missed some policies. - A policy fires once per set of argument values, including when one late-bound entity resolves after another.
- Guests (VMs) are their own hosts.
policy.forandpolicy.whenkeep the wrapped policy's arguments. This fixes acalled without required argument 'user'crash.- Policy claims and trace entries are looked up, not scanned (#749). This removes two quadratic costs on large fleets.
Fixes found while testing the stack
- A policy nested in an aspect that arrives late now fires (#754). Aspects can arrive late through
provides.to-users,provides.<user>,provides.to-hostsor a policy's include. Before, such a policy was silently dropped, which also stoppedden.batteries.unfreereaching the host in that case. - Excluding an argument-taking battery works:
excludes = [ den.batteries.unfree ];, along withinsecure,tty-autologin,vm-autologinandimport-tree, or a single use such as(den.batteries.unfree [ "steam" ]). - Batteries no longer collide on their arguments, and
import-treeroots no longer collide on their last directory name. Before, a second use could be silently dropped. - The transition warning reads cleanly (#755). It no longer lists collision validators, and it shows import-tree roots without a store hash.
Fixes reported after the first tag
- A class module that needs a user no longer takes the rest of its aspect with it (#761). Since v0.19.0, an aspect with any class module requiring
user(for examplehomeManager = { user, ... }: …) lost all its content on a host with no users, and applied its other content once per user on a host with several. Now only that module is applied per user, and the rest of the aspect stays on the host, once.- An aspect's includes, policies and provides apply once at the host, as on v0.18.
user ? null(optional) is applied once, without a user.den.default.nixos = { user, ... }:and a class key defined more than once now work, where they errored or applied twice.
- A host's own aspect excludes as far as the host (#762).
den.aspects.<host>.excludesnow also removes what the host's users include, asden.hosts.<system>.<host>.excludesandden.schema.host.excludesalready did. This covers the plain and parametric forms, and a policyexcludein its includes. Itsmeta.handleWithkeeps its own reach. - An exclude names the aspect written there (#762). Excluding
den.aspects.toolsno longer also removes an unrelated inline{ name = "tools"; … }that a user includes. excludesin a host'sprovides.<user>orprovides.to-usersis now an error (#762). It was silently ignored, because the provide is delivered after the user's includes are resolved. Exclude on the user, or on the host's own aspect, which now reaches its users.- A policy in a
den.defaultinclude registers once (#765, reported by @istvnurbn in #764). Since v0.20.0, a policy record built inside a{ host, user }include inden.defaultdelivered more than once:(den.batteries.user-shell "fish")there definedusers.users.<name>.shelltwice, so the host didn't evaluate, and a list option got duplicate entries. Copies of one include now register once, and two different policies under one name still both apply. - A revisited scope with a new policy include no longer throws (#767). Since v0.20.0, a config could fail to evaluate with
'builtins.elemAt' called with index 0 on a list of size 0inctxSeenHandler, when a scope was resolved again and brought a policy or schema include it hadn't seen. The include is now recorded and not applied twice. den.lib.schema.mkInstanceRegistrysupplieslibto its modules (#768, reported by @AlexLov in #766). A module in itsextraModulesthat took{ lib, ... }was refused, because onlymkInstanceTypepassedlibthrough. The registry now getsliband the entityresolvedcontext the same way; a caller's ownspecialArgsstill win.- An optional context arg with no context takes its default (#769, reported by @vipultyagi). A class module taking an optional entity arg with no context in scope next to one that is in scope, such as
homeManager = { home ? null, user ? null, ... }:on a host user, threwattribute 'home' missingonce the optional one was read. The absent arg is no longer passed to the module system, so its default applies. - The gen and nix-effects fallbacks fetch
.tar.gz(#771, reported by @Keyruu in #770). A config without agenornix-effectsinput made den fetch GitHub's.ziparchive throughbuiltins.fetchTarball, which an evaluator without a zip reader can't unpack. The pinned hashes are unchanged. - A host-class module taking
usersurvives the user's acceptance (#772, reported by @minhtrancccp). Since #761, an aspect inden.defaultwhosenixosmodule takes{ user, ... }was lost from a host that accepts the user, in transition mode or with an explicituser-aspects. It applies again, once per user.
Also in this release
- Schema and strictness: den follows gen-schema's options-first API, and strict mode is a property of the entity kind (#717).
- Optional
nixos-wslinput: you don't need it when WSL is unused (#703). - Guests and static resolves: they receive complex forwards and spawns (#743), and a static resolve of a user sets its host as the parent (#744).
- No-flake setups: the no-flake entry evaluates without flakes (#748).
- Exclude fixes: an exclude covers its includer's subtree (#729), and a schema-included parametric aspect can be excluded (#728).
- New docs:
- defining your own entity kind;
- direct aspect nesting and the
_glob; - den's lineage;
- collecting quirks across system scopes.
Known limits
- Late policy excludes have no effect. A
policy.excludeeffect returned by a policy that is itself delivered by another policy'sincludetakes effect too late and removes nothing. Write the exclude on the aspect that includes what it removes, or return it from a policy listed directly in that aspect'sincludes. - A host's provide to a user can't exclude. See #762 above. Exact support, an exclude in a provide removing what the same exclude on the user removes, needs constraints solved before content, which is planned for Den's rewrite.
- Constructor-built records need one shared value. An exclude names one record by value. So a constructor that builds a new record on each call needs that same value in both places: bind it once, or register it under
den.policies.
What's Changed
- fix(ci): use grep in versioned docs step, ripgrep is not on the runner by @sini in #699
- fix(ci): let versioned docs be republished for a given tag from main by @sini in #700
- fix: typo in flakeOutputs by @fmway in #704
- fix: don't require inputs.nixos-wsl when WSL is unused by @divyam234 in #703
- chore: fix formatting by @sini in #705
- fix: fire provides registered during a user scope's late pass by @sini in #710
- fix(docs): Fix duplicate attribute error by @AthereoAndromeda in #712
- docs: document collecting quirks across system scopes by @sini in #715
- improve: migrate to gen-schema's options-first API; strict mode as a property of the kind by @sini in #717
- fix: an aspect reference in a schema collection no longer recurses (#719) by @sini in #720
- fix: inputs' and self' batteries define their module argument once on a user@host home (#721) by @sini in #722
- docs: add den's lineage from traversals to effects to gen by @sini in #724
- docs: teach direct aspect nesting, inclusion routes, and the _ glob by @sini in #725
- fix: pipe value stages apply to a scope's own config-dependent quirk values (#713) by @sini in #723
- fix: a policy's exclude covers its includer's subtree, wherever it sits in includes by @sini in #729
- fix: routes that collect a class see what a class alias routed into it by @sini in #727
- fix: a schema-included parametric aspect keeps its own identity, so excludes match it by @sini in #728
- docs: add a guide for defining your own entity kind by @sini in #730
- fix(core): declare instance includes/excludes on conf by @sini in #731
- fix(core): give every entity kind's instances resolved by @sini in #732
- fix(core): the collision validator works in a freeform class target by @sini in #733
- docs: a { host } include in den.default also runs in user contexts by @sini in #734
- test: group templates/ci modules by Gen coverage level by @sini in #736
- test: prefix suites by their categorization: {deadbugs,c1,c2...} by @vic in #737
- fix(core): deliver complex-forward output and spawns to guests and static resolves by @sini in #743
- fix(core): a static resolve of a user seeds its host as parent, so host-aspects projects by @sini in #744
- fix(core): bump gen so the no-flake entry evaluates without flakes; home declares system once by @sini in #748
- fix(batteries): give the wsl-host scope its own id by @istvnurbn in #745
- perf(core): policy claims and trace entries are looked up, not scanned by @sini in #749
- fix(core): late dispatch offers every ancestor's policies, and fires each instance once by @sini in #751
- fix(core): late dispatch offers the registries of the entities a scope binds by @sini in #752
- feat(core): a delivery names its receiver entity (#694, 1/3) by @sini in #746
- feat(batteries): mutual-provider and user-aspects (#694, 2/3) by @sini in #747
- feat(core): an entity's content stays in its entity, with transition defaults (#694, 3/3) by @sini in #753
- feat(core): origin-matched excludes, admits, include.at and policy enforcement (#694, 4) by @sini in #756
- docs: a "what's changed in Den" overview, release by release since 0.1 by @sini in #758
- docs: 0.20 is released by @sini in #760
- fix(core): fan only the class module that needs a descendant entity by @sini in #761
- fix(core): a host's own aspect excludes as far as the host by @sini in #762
- fix(core): a policy in a den.default include registers once by @sini in #765
- fix(core): a revisited scope with a new policy include no longer throws by @sini in #767
- fix: mkInstanceRegistry supplies lib to its modules by @sini in #768
- fix(core): an optional context arg with no context takes its default by @sini in #769
- fix: fetch the gen and nix-effects fallbacks as .tar.gz by @sini in #771
- fix(core): a host-class module taking user survives the user's acceptance by @sini in #772
New Contributors
- @divyam234 made their first contribution in #703
- @AthereoAndromeda made their first contribution in #712
- @istvnurbn made their first contribution in #745
Full Changelog: v0.19.0...v0.20.0