Skip to content

v0.20.0 - Good Fences

Latest

Choose a tag to compare

@sini sini released this 10 Nov 23:13
· 1 commit to main since this release
12b2146

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-aspects and mutual-provider on 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 user class for account settings, include den.batteries.mutual-provider for provides.to-hosts, or include den.batteries.user-aspects to 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 on den.schema.host, decides which deliveries land:

    • deny withholds named ones;
    • default = "deny" with an allow list refuses everything else, and the error names what to add.

    Den's own channels (home-manager, hjem, maid, the user class, shells) always land.

  • policyEnforcement ("strict", "per-policy" or "lenient") and den.lib.policy.strict decide 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, for and strict.

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.for and policy.when keep the wrapped policy's arguments. This fixes a called 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-hosts or a policy's include. Before, such a policy was silently dropped, which also stopped den.batteries.unfree reaching the host in that case.
  • Excluding an argument-taking battery works: excludes = [ den.batteries.unfree ];, along with insecure, tty-autologin, vm-autologin and import-tree, or a single use such as (den.batteries.unfree [ "steam" ]).
  • Batteries no longer collide on their arguments, and import-tree roots 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 example homeManager = { 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>.excludes now also removes what the host's users include, as den.hosts.<system>.<host>.excludes and den.schema.host.excludes already did. This covers the plain and parametric forms, and a policy exclude in its includes. Its meta.handleWith keeps its own reach.
  • An exclude names the aspect written there (#762). Excluding den.aspects.tools no longer also removes an unrelated inline { name = "tools"; … } that a user includes.
  • excludes in a host's provides.<user> or provides.to-users is 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.default include registers once (#765, reported by @istvnurbn in #764). Since v0.20.0, a policy record built inside a { host, user } include in den.default delivered more than once: (den.batteries.user-shell "fish") there defined users.users.<name>.shell twice, 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 0 in ctxSeenHandler, 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.mkInstanceRegistry supplies lib to its modules (#768, reported by @AlexLov in #766). A module in its extraModules that took { lib, ... } was refused, because only mkInstanceType passed lib through. The registry now gets lib and the entity resolved context the same way; a caller's own specialArgs still 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, threw attribute 'home' missing once 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 a gen or nix-effects input made den fetch GitHub's .zip archive through builtins.fetchTarball, which an evaluator without a zip reader can't unpack. The pinned hashes are unchanged.
  • A host-class module taking user survives the user's acceptance (#772, reported by @minhtrancccp). Since #761, an aspect in den.default whose nixos module takes { user, ... } was lost from a host that accepts the user, in transition mode or with an explicit user-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-wsl input: 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.exclude effect returned by a policy that is itself delivered by another policy's include takes 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's includes.
  • 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

Full Changelog: v0.19.0...v0.20.0