Are aspect-oriented, context-aware just buzzwords?

[vic]

Note

No, this is actually how Den configures a NixOS host and support things like machine fleets, or terraform infra, anything that you can describe via a data structure and can be traversed can be configured like we do for NixOS.

Den is a data transformation pipeline (of your infra entities) to which functions (aspects producing configurations) are applied.

From docs about Aspects:

A Dendritic aspect is an attrset that contains modules of different Nix class.
gaming = { host, user }: { nixos = ...; homeManager = ...; hjem = ...; darwin = ...; }

Most importantly, the context {host,user} here are NOT _module.args nor specialArgs, it is an actual function, not a module-looking-as-a-function. This means config can depend on context without Nix infinite loops.

Den uses den.ctx.<name>.provides.<name> as Aspect Pointcuts where configuration is applied to data in that context stage.

Pointcuts in Aspect-Oriented-Programming determine where additional behavior (advice) should be applied in your code, typically at method execution points.

Say you have a data shape: { x }, that you name as a foo context stage:

# This says how to move from one context stage `foo` into `bar`
den.ctx.foo.into.bar = { x }: [ { y = x; } ] 

This den.ctx.bar.provides.bar is the actual aspect that configures using data { y } available at bar context stage. It is the point where bar configuration is applied.

den.ctx.bar.provides.bar = { y }: {
   nixos.networking.hostName = y;
}

AND since den.ctx.bar IS an aspect:

den.ctx.bar.nixos.keyboard.model = "us";
den.ctx.bar.includes = [ den.aspects.other ];

also apply at bar stage.

This is how everything works in Den, the following is the den.ctx.host { host }

# host configuration: THIS is where your host-aspect is hooked into the pipeline
den.ctx.host.provides.host = { host }: den.aspects.${host.aspect};

# host -> users context transformation
den.ctx.host.into.user = { host }: map (user: { inherit host user; }) (lib.attrValues host.users); # transition into many { host, user }

# user configuration: Lookup user aspect.
den.ctx.user.provides.user = { host, user }: den.aspects.${user.aspect}; # Hook for the user-aspect.

# conditional transition ONLY if hm is enabled for user and host.
den.ctx.user.into.hm-user = { host, user }: lib.optional (host.hm.enable && lib.elem "homeManager" user.classes) { inherit host user; }


# host -> wsl-host: Same data shape, different context stage.
den.ctx.host.into.wsl-host = { host }: lib.optional host.wsl.enable { inherit host; }

people can define their own extensions to Den's NixOS pipeline, or define other pipelines enterely, see the README example of three-lines on how Den invokes the den.ctx.host pipeline:

# These three lines is how Den instantiates a configuration.
# Other Nix configuration domains outside NixOS/nix-Darwin
# can use the same pattern. demo: templates/nvf-standalone

# A context transformation pipeline takes initially {host}
# and traverses its topology (host->[users]->[homes]) aggregating deps
aspect = den.ctx.host { host = den.hosts.x86_64-linux.my-laptop; };

# obtain the final module for nixos class
nixosModule = den.lib.aspects.resolve "nixos" aspect;

# Use NixOS API to instantiate or mix-in with other custom modules
nixosConfigurations.my-laptop = lib.nixosConfiguration {  modules = [ nixosModule ]; };

Note

v0.9.0 Release Notes where den.ctx was designed and introduced in Den.

From conversation at matrix. Docs about aspects and context pipeline

Minimal real-life example: wsl support

Context extensions examples: home-env is how Den implements homeManager/hjem/maid support, perSystem classes, microvm support

[Nickalus12]

This looks like a fundamental shift from static module trees to a dynamic traversal pipeline. The reason "aspect-oriented" fits here is that you're decoupling the what (the host/user data) from the where (the pointcut). Unlike standard NixOS imports, Den's into transitions let you map data across stages without triggering infinite recursion, as these are functions evaluated during traversal rather than global specialArgs.

# Example of a custom pointcut/transition
den.ctx.user.into.ssh-key = { user, ... }: 
  lib.optional (user ? pubkey) { key = user.pubkey; owner = user.name; };

den.ctx.ssh-key.provides.setup = { key, owner }: {
  nixos.users.users.${owner}.openssh.authorizedKeys.keys = [ key ];
};

One gotcha I've noticed: because these are functions and not standard modules, you have to be explicit about merging if your provides hook returns complex nested attrsets. Den handles the heavy lifting, but I believe you still need to ensure your output matches the target class (NixOS, Home Manager, etc.) or the collector might ignore it.

[vic]

Not sure what you mean by "collector", nor what you mean by explicit merging, when you invoke a pipeline like den.ctx.host, it returns an single aspect that has .includes of other aspects as the pipeline was traversed, nothing has been configured yet, it is only traversing the data topology into a single aspect, maybe this is the "collector"

aspect = den.ctx.host { host = den.hosts.x86_64-linux.my-laptop; };

then the aspect and its includes can have any arbitrary amount of different classes, the second step from the README, takes a single class you care about (nixos) and turns all aspect.includes into module.imports of corresponding nixos class modules from aspects in the chain.

nixosModule = den.lib.aspects.resolve "nixos" aspect;

From there you have a module with imports of all nixos deferredModules that were included in den.ctx.host, and this module can be used to configure anything. We have a nvf example showing this without nixos.

Also, a fix in your pipeline example, it should be ssh-key.provides.ssh-key: <name>.provides.<name> same name in both places:

# aspect configuring stage x
den.ctx.x.provides.x = xCtx: aspect;

# transition from x -> y
den.ctx.x.into.y = xCtx: [ yCtx ];

# aspect contribution from x to y stage
den.ctx.x.provides.y = xCtx: yCtx: aspect;

# aspect configuring stage y
den.ctx.y.provides.y = yCtx: aspect;

EDIT: I still have to document these kind of stuff.

You can also have transitions like

den.ctx.x.into = xCtx: {
  y = [ yCtx ];
  z = [ zCtx ];
}

or even non-flat contexts:

den.ctx.x.into = xCtx: {
  y.z = [ zCtx ];
};
den.ctx.x.provides."y.z" = xCtx: zCtx: aspect;

[vic]

And yes, like you pointed out, unlike module.imports, aspect.includes can have conditionals reading context, no mkIf is needed, if then else and lib.optional works because ctx values are not part of the module system. This is something important that might be overlooked by people, since aspects (a function) might look like a module-function.

To be even more specific, aspects DO are module based, but the context passing is not related to modules:

den.aspects.foo = { host, user }: 
{ config, lib, options, ... }: # These are the aspect-module args
{
  nixos = { pkgs, ... }: {};

  # it can import other modules to, for example, define custom attributes on the aspect!
  imports = [ { options.meta = lib.mkOption { type = lib.types.attrsOf lib.types.raw; }; } ];

  # power users (like @drupol) use this kind of things to propagate aspect-bound meta data. 
  meta.secret = "very";
}

[vic]

explicit about merging if your provides hook returns complex nested attrsets.

since all provides are aspects, they can have a list of includes. which can be static, other aspects, other pipe-line invocations, etc.

den.ctx.a.provides.a = aCtx: {
  includes = [
    { nixos.inlined = true; }
    den.aspects.foo
    (den.aspects.bar param)
    (den.ctx.z zCtx)
  ];
};

[Nickalus12]

Thanks for the corrections - I was off on the "collector" terminology and the merging point. The aspect.includes being able to use plain if/then/else and lib.optional without mkIf is a big deal that I glossed over. That's probably the clearest practical win over the standard module system for people evaluating whether to adopt Den.

[YesterKo]

Hi! Even though the concept and message of the post still stands, the naming of stuff in Den has changed dramatically (ctx is legacy). Also, this post is currently pinned to the top of the discussions page, giving it a more official feeling.

I think we should either unpin it or update the post? I'd help with the rewording, but I don't yet understand the concepts at a deep enough level to confidently edit yet 😅

[vic]

Context not only refers to old den.ctx (that was one way to achieve context expansion & propagation - hence the den.ctx name). Den still and will always be context-aware any time you use { host } or any other contextual parameter you are using context. So, the wording is yet valid, the internals and API for achieving context-awareness changed.

[YesterKo]

Oh, yeah exactly! I'm sorry about the confusion, I didn't mention that this comment is exactly about the naming of the implementation, not the concept itself. I want to help with the documentation part of Den and make sure that newcomers (like me haha) have access to quality and up-to-date guides and examples.

There are still a lot of keywords and terms that I don't quite understand and I feel there is an uncertainty whether a (new to me) feature that I'm reading about is the new recommended way or actually some deprecated feature that has a newer alternative.

How about a note at the top linking to https://den.denful.dev/guides/migrate-ctx/ and https://den.denful.dev/explanation/core-principles/ ? The latter link seems to be the canonical successor in a way to this post:)