nixos/nix-gc: add persistent and randomizeDelaySec options

nixos/doc/manual/release-notes/rl-2105.xml

@@ -738,6 +738,13 @@ self: super:
      terminology has been deprecated and should be replaced with Far/Near in the configuration file.
     </para>
    </listitem>
+   <listitem>
+    <para>
+     The nix-gc service now accepts randomizedDelaySec (default: 0) and persistent (default: true) parameters.
+     By default nix-gc will now run immediately if it would have been triggered at least
+     once during the time when the timer was inactive.
+    </para>
+   </listitem>
   </itemizedlist>
  </section>
 </section>

nixos/modules/services/misc/nix-gc.nix

@@ -21,13 +21,45 @@ in
       };
 
       dates = mkOption {
-        default = "03:15";
         type = types.str;
+        default = "03:15";
+        example = "weekly";
         description = ''
-          Specification (in the format described by
+          How often or when garbage collection is performed. For most desktop and server systems
+          a sufficient garbage collection is once a week.
+
+          The format is described in
           <citerefentry><refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum></citerefentry>) of the time at
+          <manvolnum>7</manvolnum></citerefentry>.
-          which the garbage collector will run.
+        '';
+      };
+
+      randomizedDelaySec = mkOption {
+        default = "0";
+        type = types.str;
+        example = "45min";
+        description = ''
+          Add a randomized delay before each automatic upgrade.
+          The delay will be chosen between zero and this value.
+          This value must be a time span in the format specified by
+          <citerefentry><refentrytitle>systemd.time</refentrytitle>
+          <manvolnum>7</manvolnum></citerefentry>
+        '';
+      };
+
+      persistent = mkOption {
+        default = true;
+        type = types.bool;
+        example = false;
+        description = ''
+          Takes a boolean argument. If true, the time when the service
+          unit was last triggered is stored on disk. When the timer is
+          activated, the service unit is triggered immediately if it
+          would have been triggered at least once during the time when
+          the timer was inactive. Such triggering is nonetheless
+          subject to the delay imposed by RandomizedDelaySec=. This is
+          useful to catch up on missed runs of the service when the
+          system was powered down.
         '';
       };
 
@@ -50,11 +82,18 @@ in
 
   config = {
 
-    systemd.services.nix-gc =
+    systemd.services.nix-gc = {
-      { description = "Nix Garbage Collector";
+      description = "Nix Garbage Collector";
-        script = "exec ${config.nix.package.out}/bin/nix-collect-garbage ${cfg.options}";
+      script = "exec ${config.nix.package.out}/bin/nix-collect-garbage ${cfg.options}";
-        startAt = optional cfg.automatic cfg.dates;
+      startAt = optional cfg.automatic cfg.dates;
+    };
+
+    systemd.timers.nix-gc = lib.mkIf cfg.automatic {
+      timerConfig = {
+        RandomizedDelaySec = cfg.randomizedDelaySec;
+        Persistent = cfg.persistent;
       };
+    };
 
   };