fix(launchd): improve `StartCalendarInterval`

Stricter launchd -> StartCalendarInterval type:

- Verify that the integers passed to `Minute`, `Hour`, etc. are within
  range.

- When provided, the value for StartCalendarInterval must be a non-empty
  list of calendar intervals and must not contain duplicates entries
  (throw an error otherwise).

- For increased flexibility and backwards-compatibility, allow an
  attrset to be passed as well (which will be type-checked and is
  functionally equivalent to passing a singleton list). Allowing an
  attrset or list is precisely in-line with what `launchd.plist(5)`
  accepts for StartCalendarInterval.

Migrate `nix.gc.interval` and `nix.optimise.interval` over to use this
new type, and update their defaults to run weekly instead of daily.

Create `modules/launchd/types.nix` file for easier/modular use of
launchd types needed in multiple files.

Documentation:

- Update and improve wording/documentation of launchd's
  `StartCalendarInterval`.

- Improve wording/documentation of `nix.gc.interval` and
  `nix.optimise.interval` ("time interval" can be misleading as it's
  actually a "calendar interval"; e.g. `{ Hour = 3; Minute = 15;}`
  runs daily, not every 3.25 hours).

1 files changed, 9 insertions, 4 deletions

diff --git a/modules/services/nix-optimise/default.nix b/modules/services/nix-optimise/default.nix
index 94f6e1c..d8dc401 100644
--- a/modules/services/nix-optimise/default.nix
+++ b/modules/services/nix-optimise/default.nix
@@ -14,6 +14,7 @@ let
     ;
 
   cfg = config.nix.optimise;
+  launchdTypes = import ../../launchd/types.nix { inherit config lib; };
 in
 
 {
@@ -41,9 +42,13 @@ in
       };
 
       interval = mkOption {
-        type = types.attrs;
-        default = { Hour = 3; Minute = 15; };
-        description = "The time interval at which the optimiser will run.";
+        type = launchdTypes.StartCalendarInterval;
+        default = [{ Weekday = 7; Hour = 4; Minute = 15; }];
+        description = ''
+          The calendar interval at which the optimiser will run.
+          See the {option}`serviceConfig.StartCalendarInterval` option of
+          the {option}`launchd` module for more info.
+        '';
       };
 
     };
@@ -63,7 +68,7 @@ in
           "/bin/wait4path ${config.nix.package} && exec ${config.nix.package}/bin/nix-store --optimise"
         ];
         RunAtLoad = false;
-        StartCalendarInterval = [ cfg.interval ];
+        StartCalendarInterval = cfg.interval;
         UserName = cfg.user;
       };
     };