clan-core/decisions/01-ClanModules.md

# Interface for module authors

Status: proposed

## Context

ClanModules define cross `machine` `services`.
Services can be `instantiated` multiple times.
To make configuration more natural each service instance has multiple `roles` (.i.e. `client`  `server`)

Overall this makes it a 4-Dimensional problem where n-`machines` can have m-`services`, m-`services` can have k-`instances` and k-`instances` can have l-`roles`.

### Problems

Problems with the current way of writing clanModules.

1. No way to retrieve the config of a single service instance
    2. -> We can't really support multiple instances even though the nix module *could* support multiple instances
    3. the "config" of a service MUST be evaluated against the "interface" outside of any machine.
    -> Solution: evaluate each instance config and store it in seperate attributes
3. Can't merge multiple config instances -> Example: https://pad.lassul.us/i9uSspVbRUmiBmsJ8OR1ug#
    -> Propsed change: feed the instance config into a helper that defines the merge behavior
5. Writing modules for multiple instances is cumbersome
    -> Propsed change: Helper utility such as "perInstance"
6. No clearly separated, role based interface that is usable via json based APIs
    1. Currently we just import the module into a test machine and try to figure out what changes
    -> Proposed change: enforce machine agnostic inventory interface definitions

### Some immediate ideas

#### simple idea

Just use another nested attribute set

- `clan.something.borgbackup.instance1 = config`
- `clan.something.borgbackup.instance1 = config`

Problems solved:

- each instance has its own config

Problems not solved:

- Machine independent seperated interface
- Still cumbersome to merge the instances
- Unclear how to get to each config because the interface also depends on the role

#### Improved Idea

- PerInstance: utility that maps over all instances and defines what needs to be set for each instance and receives the instanceConfig as argument.
- GlobalConfig: Some stuff that needs to be set statically on a machine if the service is enabled.

## Proposed Change

Change the ClanModule interface

`client.nix`
```nix
{
  # Allows backwards compatibility
  _class = "clan";

  # Allows importing other service modules
  module.zerotier = {
    # function that receives each instance along with its config and resolved roles
    perInstance =
      {
        # serviceConfig is the config of this instance
        # as described in interface attribute below.
        # Merged without differing priority:
        # service.<instanceName>.config
        # + role.<roleName>.config
        # + machine.<machineName>.config
        serviceConfig,
        # : string
        instanceName,
        # machine :: { name :: string , roles :: listOf string; }
        machine,
        # : { {roleName} :: { machines :: listOf string; } }
        roles,
      ... }:
      {
        nixosModule = {
          config.debug."${instanceName}-client" = serviceConfig;
        };
      };
    # Function that is appplied once for this role
    perService = {
      nixosModule =
        { lib, ... }:
        {
          # Some shared code should be put into a shared file
          # Which is then imported into all/some roles
          imports = [
            ../shared.nix
          ];
          options.debug = lib.mkOption {
            type = lib.types.attrsOf lib.types.raw;
          };
        };
    };

    # Describes the settings how a `client` can be configured.
    # These are the `options` of serviceConfig of a `client`. (Since: This file is called client.nix)
    interface =
      { lib, ... }:
      {
        options.foo = lib.mkOption {
          type = lib.types.str;
          default = "bar";
        };
      };
  };
}
```

## Not Changed! (existing inventory.services for api configuration of clanModules)

```nix
{
    inventory.services = {
        test."instance1" = {
            roles.client.tags = [ "all" ];
            machines.foo.config = { ... };
            roles.client.config = { ... };

        };
        test."instance2" = {
        roles.server.tags = [ "all" ];
        config = { ... };
        };
    };
}
```

We don't propse to change anything here. Because we had no problems with that interface yet.
We even like it because it is very fast to evaluate and can be configured via UI.

### Example of borgbackup before and after

```nix
# client.nix (BEFORE)
{config, ...}:
let
  instances = config.clan.inventory.services.borgbackup or { };
  # roles = { ${role_name} :: { machines :: [string] } }
  allServers = lib.foldlAttrs (
    acc: _instanceName: instanceConfig:
    acc
    ++ (
      if builtins.elem machineName instanceConfig.roles.client.machines then
        instanceConfig.roles.server.machines
      else
        [ ]
    )
  ) [ ] instances;

  machineName = config.clan.core.settings.machine.name;

  cfg = config.clan.borgbackup;
in
{
#  ... Some nixos config
}
```

```nix
# client.nix (AFTER)
{
  _class = "clan";
  perInstance = {instanceName, serviceConfig, machine, roles }: {
    # allServers => roles.server;
    # machineName => machine.name;
    # cfg => serviceConfig;
    nixosModule = {config, ...}: {
    #   ...some nixos config
    }
    # Extendable. I.e. Instances can also define 'vars' or other things later.
  };
}
```