Add "randInt" template function for random number (#540)

The `randInt` function added by this change returns a pseudo-random
number in a given range and using a seed for repeatable randomness. It
can be used, for example, in cron schedules to pick a minute offset
based on an environment variable (e.g. hostname).

Author: hansmi

docs/content/configuration/templates.md

@@ -600,6 +600,9 @@ resticprofile supports the following set of own functions in all templates:
 * `{{ tempDir }}` => `/tmp/resticprofile.../t` - unique OS specific existing temporary directory
 * `{{ tempFile "filename" }}` => `/tmp/resticprofile.../t/filename` - unique OS specific existing temporary file
 * `{{ env }}` => `/tmp/resticprofile.../t/profile.env` - unique OS specific existing temporary file that is added to the current profile env-files list
+* `{{ "seed" | randInt low high }}` => `123` -
+  Generate a random number greater than or equal to `low` and less than `high`,
+  using the value of `seed` for repeatable randomness.
 
 All `{{ temp* }}` functions guarantee that returned temporary directories and files are existing & writable. 
 When resticprofile ends, temporary directories and files are removed.

util/templates/functions.go

@@ -1,11 +1,14 @@
 package templates
 
 import (
+	"crypto/md5" //nolint:gosec
 	"encoding/base64"
+	"encoding/binary"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"maps"
+	"math/rand/v2"
 	"os"
 	"path"
 	"path/filepath"
@@ -43,6 +46,7 @@ import (
 //   - {{ "plain" | base64 }} => "cGxhaW4="
 //   - {{ tempDir }} => "/path/to/unique-tempdir"
 //   - {{ tempFile "filename" }} => "/path/to/unique-tempdir/filename"
+//   - {{ "seed" | randInt 123 456 }} => 166
 func TemplateFuncs(funcs ...map[string]any) (templateFuncs map[string]any) {
 	templateFuncs = map[string]any{
 		"contains":   func(search any, src any) bool { return strings.Contains(toString(src), toString(search)) },
@@ -64,6 +68,7 @@ func TemplateFuncs(funcs ...map[string]any) (templateFuncs map[string]any) {
 		"tempDir":    TempDir,
 		"tempFile":   TempFile,
 		"env":        func() string { return TempFile(".env.none") }, // satisfies the {{env}} interface w.o. functionality
+		"randInt":    randInt,
 	}
 
 	// aliases
@@ -214,3 +219,22 @@ func toMap(args ...any) (m map[string]any) {
 	}
 	return
 }
+
+// randInt uses the seed to initialize a pseudo-random number generator and
+// returns a number between low (inclusive) and high (exclusive).
+func randInt(low, high int64, seed string) int64 {
+	if low >= high {
+		panic(fmt.Sprintf("low (%d) must be less than high (%d)", low, high))
+	}
+
+	// MD5 produces the right amount of output bytes and isn't used for
+	// cryptography.
+	sum := md5.Sum([]byte(seed)) //nolint:gosec
+
+	seed1 := binary.LittleEndian.Uint64(sum[0:8])
+	seed2 := binary.LittleEndian.Uint64(sum[8:16])
+
+	r := rand.New(rand.NewPCG(seed1, seed2))
+
+	return low + r.Int64N(high-low)
+}

util/templates/functions_test.go

@@ -59,6 +59,10 @@ func TestTemplateFuncs(t *testing.T) {
 		{template: `{{ "plain" | hex }}`, expected: "706c61696e"},
 		{template: `{{ "plain" | base64 }}`, expected: "cGxhaW4="},
 		{template: `{{ hello }}`, expected: `Hello World`},
+		{template: `{{ "" | randInt 0 1 }}`, expected: `0`},
+		{template: `{{ "hello" | randInt 5 6 }}`, expected: `5`},
+		{template: `{{ "" | randInt -1000 1000 }}`, expected: `419`},
+		{template: `{{ "ABC" | randInt -1000 1000 }}`, expected: `-272`},
 	}
 
 	extraFuncs := map[string]any{