Skip to content

feat(batteries): Opt-in den._.bidirectional #272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vic merged 1 commit into from
Mar 13, 2026
Merged

feat(batteries): Opt-in den._.bidirectional #272

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ name: Docs
on:
push:
branches: ["!main"]
paths: [ "docs/**" ]
paths: ["docs/**"]
pull_request:
types: [labeled, opened, synchronize, reopened, review_requested, ready_for_review]
paths: [ "docs/**" ]
paths: ["docs/**"]
pull_request_review:
types: [submitted]
concurrency:
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
on:
push:
branches: [main]
paths: [ "**/*.nix" ]
paths: ["**/*.nix"]
pull_request:
types: [labeled, opened, synchronize, reopened, review_requested, ready_for_review]
paths: [ "**/*.nix" ]
paths: ["**/*.nix"]
pull_request_review:
types: [submitted]
concurrency:
Expand Down
16 changes: 16 additions & 0 deletions modules/aspects/provides/bidirectional.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{ den, ... }:
let
description = ''
Enable Den bidirectionality: User takes configuration from Host.

**REALLY** IMPORTANT: Read the documentation for den.ctx.user

Consider as alternative den.provides.mutual-provider.
'';
in
{
den.provides.bidirectional = {
inherit description;
includes = [ den.ctx.user.provides.bidirectional ];
};
}
28 changes: 28 additions & 0 deletions modules/context/host.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{ den, lib, ... }:
let
inherit (den.lib.parametric) fixedTo;

ctx.host.description = ''
## Context: den.ctx.host{host}

Host context stage configures an OS

A {host} context fan-outs into many {host,user} contexts.

A `den.ctx.host{host}` transitions unconditionally into `den.ctx.default{host}`

A `den.ctx.host{host}` obtains OS configuration nixos/darwin by using `fixedTo{host} host-aspect`.
fixedTo takes:
- host-aspect's owned attrs
- static includes like { nixos.foo = ... } or ({ class, aspect-chain }: { nixos.foo = ...; })
- atLeast{host} parametric includes like ({ host }: { nixos.foo = ...; })
'';

ctx.host.into.user = { host }: map (user: { inherit host user; }) (lib.attrValues host.users);
ctx.host.into.default = lib.singleton;
ctx.host.provides.host = { host }: fixedTo { inherit host; } den.aspects.${host.aspect};

in
{
den.ctx = ctx;
}
28 changes: 0 additions & 28 deletions modules/context/os.nix
View file
Open in desktop

This file was deleted.

82 changes: 82 additions & 0 deletions modules/context/user.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
{ den, lib, ... }:
let
inherit (den.lib) take;
inherit (den.lib.parametric) fixedTo atLeast;

ctx.user.description = ''
## Context: den.ctx.user{host,user}

User context stage is produced by Host for each user.

This is a **continuation** of the pipeline started by `den.ctx.host`.

IMPORTANT: The configuration obtained from `den.ctx.user` is provided to the Host OS level

In Den, home-manager/hjem/maid are just forwarding classes that produce config at the OS
level: `home-manager.users.<alice>`, `hjem.users.<alice>`, `users.users.<alice>`, etc.

A `den.ctx.user{host,user}` transitions unconditionally into `den.ctx.default{host,user}`

A `den.ctx.user{host,user}` obtains OS configuration nixos/darwin by using `fixedTo{host,user} user-aspect`.
fixedTo takes:
- user-aspect's owned attrs
- static includes like { nixos.foo = ... } or ({ class, aspect-chain }: { nixos.foo = ...; })
- atLeast{host,user} parametric includes like ({ host,user }: { nixos.foo = ...; })

## Bidirectionality

Battery `den.provides.bidirectional` can be included on each user that needs to take configuration from the Host.

Enable per user:
den.aspects.tux.includes = [ den._.bidirectional ];

Enable for all users:
den.ctx.user.includes = [ den._.bidirectional ];

IMPORTANT: Enabling bidirectionality means that the following piepline is enabled:

host-aspect{host} => user-aspect{host,user} => host-aspect{host,user}

This means that any function at host-aspect.includes can be called:
- once when the host is obtaining its own configuration with context {host}
- once PER user that has bidirectionality enabled with context {host,user}

Because of this, parametric aspects at host-aspect must be careful

Instead of -in Nix both of these have the same functionArgs-

({host}: ...)

or

({host, ...}: ...)

Do this to prevent the function being invoked with `{host,user}`

take.exactly ({host}: ...)

Or this to avoid it being invoked with `{host}`

take.atLeast ({host,user}: ...)

Static aspects, -functions like `{class,aspect-chain}: ...`- at host-aspect.includes
have **no way** to distinguish when the calling context is `{host}` or `{host,user}` if
bidirectionality is enabled.

Because of this, if you have such functions, they might produce duplicate values on list or
conflicting values on package types. A work around is to wrap them in a context-aware function:

take.exactly ({host}: { includes = [ ({class, aspect-chain}: ...) ]; })

'';

ctx.user.into.default = lib.singleton;
ctx.user.provides.user = take.exactly from-user;
ctx.user.provides.bidirectional = take.exactly from-host;

from-user = { host, user }: fixedTo { inherit host user; } den.aspects.${user.aspect};
from-host = { host, user }: atLeast den.aspects.${host.aspect} { inherit host user; };
in
{
den.ctx = ctx;
}
3 changes: 3 additions & 0 deletions templates/ci/modules/features/auto-parametric.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
test-explicit-exactly-not-overridden-by-default = denTest (
{ den, igloo, ... }:
{
den.ctx.user.includes = [ den._.bidirectional ];
den.aspects.strict-helper = den.lib.parametric.exactly {
includes = [
(
Expand Down Expand Up @@ -109,6 +110,7 @@
test-second-level-helper-owned-config-preserved = denTest (
{ den, igloo, ... }:
{
den.ctx.user.includes = [ den._.bidirectional ];
den.hosts.x86_64-linux.igloo.users.tux = { };

den.aspects.second-with-owned = {
Expand Down Expand Up @@ -139,6 +141,7 @@
test-second-provides-helper-owned-config-preserved = denTest (
{ den, igloo, ... }:
{
den.ctx.user.includes = [ den._.bidirectional ];
den.hosts.x86_64-linux.igloo.users.tux = { };

den.aspects.second.provides.with-owned = {
Expand Down
1 change: 1 addition & 0 deletions templates/ci/modules/features/batteries/define-user.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
{
den.hosts.x86_64-linux.igloo.users.tux = { };
den.aspects.igloo.includes = [ den._.define-user ];
den.ctx.user.includes = [ den._.bidirectional ];
expr = igloo.users.users.tux.isNormalUser;
expected = true;
}
Expand Down
2 changes: 2 additions & 0 deletions templates/ci/modules/features/conditional-config.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@
users.tux.hasBar = true;
};

den.ctx.user.includes = [ den._.bidirectional ];

den.aspects.igloo.includes = [ conditionalAspect ];

expr = igloo.something;
Expand Down
1 change: 1 addition & 0 deletions templates/ci/modules/features/context/host-propagation.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
{

den.hosts.x86_64-linux.igloo.users.tux = { };
den.ctx.user.includes = [ den._.bidirectional ];

den.aspects.igloo.funny.names = [ "host-owned" ];
den.aspects.igloo.includes = [
Expand Down
2 changes: 2 additions & 0 deletions templates/ci/modules/features/deadbugs/external-namespace-deep-aspect.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@

test-functor-exactly-fires-only-in-user-context = denTest (
{
den,
provider,
igloo,
...
Expand All @@ -86,6 +87,7 @@
];
den.hosts.x86_64-linux.igloo.users.tux = { };
den.aspects.igloo.includes = [ provider.tools._.dev._.user-stamp ];
den.ctx.user.includes = [ den._.bidirectional ];
expr = igloo.users.users.tux.description;
expected = "user-of-igloo";
}
Expand Down
1 change: 1 addition & 0 deletions templates/ci/modules/features/deadbugs/issue-201-forward-multiple-users.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
}:
{
den.default.homeManager.home.stateVersion = "25.11";
den.ctx.user.includes = [ den._.bidirectional ];

den.hosts.x86_64-linux.igloo.users = {
tux = { };
Expand Down
6 changes: 2 additions & 4 deletions templates/ci/modules/features/host-options.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,9 @@
test-user-custom-username = denTest (
{ den, igloo, ... }:
{
den.hosts.x86_64-linux.igloo.users.tux = {
userName = "penguin";
};
den.default.homeManager.home.stateVersion = "25.11";
den.hosts.x86_64-linux.igloo.users.tux.userName = "penguin";
den.aspects.igloo.includes = [ den._.define-user ];
den.ctx.user.includes = [ den._.bidirectional ];

expr = igloo.users.users.penguin.isNormalUser;
expected = true;
Expand Down
Loading