Modernise fqdn_rotate function

Convert the function to the modern function API as a namespaced function
and use the `networking` fact instead of legacy facts.

A non-namespaced shim is also created (but marked deprecated),
to preserve compatibility.

Author: alexjfisher

REFERENCE.md

@@ -71,8 +71,7 @@ as a result.
 * [`floor`](#floor): Returns the largest integer less or equal to the argument.
 * [`fqdn_rand_string`](#fqdn_rand_string): Generates a random alphanumeric string. Combining the `$fqdn` fact and an
 optional seed for repeatable randomness.
-* [`fqdn_rotate`](#fqdn_rotate): Rotates an array or string a random number of times, combining the `$fqdn` fact
-and an optional seed for repeatable randomness.
+* [`fqdn_rotate`](#fqdn_rotate): DEPRECATED.  Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead.
 * [`fqdn_uuid`](#fqdn_uuid): Returns a [RFC 4122](https://tools.ietf.org/html/rfc4122) valid version 5 UUID based
 on an FQDN string under the DNS namespace
 * [`get_module_path`](#get_module_path): Returns the absolute path of the specified module for the current
@@ -179,6 +178,7 @@ the provided regular expression.
 * [`stdlib::ensure`](#stdlib--ensure): function to cast ensure parameter to resource specific value
 * [`stdlib::extname`](#stdlib--extname): Returns the Extension (the Portion of Filename in Path starting from the
 last Period).
+* [`stdlib::fqdn_rotate`](#stdlib--fqdn_rotate): Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness.
 * [`stdlib::ip_in_range`](#stdlib--ip_in_range): Returns true if the ipaddress is within the given CIDRs
 * [`stdlib::sha256`](#stdlib--sha256): Run a SHA256 calculation against a given value.
 * [`stdlib::start_with`](#stdlib--start_with): Returns true if str starts with one of the prefixes given. Each of the prefixes should be a String.
@@ -2293,36 +2293,21 @@ fqdn_rand_string(10, '', 'custom seed')
 
 ### <a name="fqdn_rotate"></a>`fqdn_rotate`
 
-Type: Ruby 3.x API
-
-Rotates an array or string a random number of times, combining the `$fqdn` fact
-and an optional seed for repeatable randomness.
-
-#### Examples
+Type: Ruby 4.x API
 
-##### Example Usage:
+DEPRECATED.  Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead.
 
-```puppet
-fqdn_rotate(['a', 'b', 'c', 'd'])
-fqdn_rotate('abcd')
-fqdn_rotate([1, 2, 3], 'custom seed')
-```
-
-#### `fqdn_rotate()`
+#### `fqdn_rotate(Any *$args)`
 
 The fqdn_rotate function.
 
-Returns: `Any` rotated array or string
+Returns: `Any`
 
-##### Examples
+##### `*args`
+
+Data type: `Any`
 
-###### Example Usage:
 
-```puppet
-fqdn_rotate(['a', 'b', 'c', 'd'])
-fqdn_rotate('abcd')
-fqdn_rotate([1, 2, 3], 'custom seed')
-```
 
 ### <a name="fqdn_uuid"></a>`fqdn_uuid`
 
@@ -4881,6 +4866,76 @@ Data type: `String`
 
 The Filename
 
+### <a name="stdlib--fqdn_rotate"></a>`stdlib::fqdn_rotate`
+
+Type: Ruby 4.x API
+
+Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness.
+
+#### `stdlib::fqdn_rotate(String $input, Optional[Variant[Integer,String]] *$seeds)`
+
+The stdlib::fqdn_rotate function.
+
+Returns: `String` Returns the rotated String
+
+##### Examples
+
+###### Rotating a String
+
+```puppet
+stdlib::fqdn_rotate('abcd')
+```
+
+###### Using a custom seed
+
+```puppet
+stdlib::fqdn_rotate('abcd', 'custom seed')
+```
+
+##### `input`
+
+Data type: `String`
+
+The String you want rotated a random number of times
+
+##### `*seeds`
+
+Data type: `Optional[Variant[Integer,String]]`
+
+One of more values to use as a custom seed. These will be combined with the host's FQDN
+
+#### `stdlib::fqdn_rotate(Array $input, Optional[Variant[Integer,String]] *$seeds)`
+
+The stdlib::fqdn_rotate function.
+
+Returns: `Array` Returns the rotated Array
+
+##### Examples
+
+###### Rotating an Array
+
+```puppet
+stdlib::fqdn_rotate(['a', 'b', 'c', 'd'])
+```
+
+###### Using custom seeds
+
+```puppet
+stdlib::fqdn_rotate([1, 2, 3], 'custom', 'seed', 1)
+```
+
+##### `input`
+
+Data type: `Array`
+
+The Array you want rotated a random number of times
+
+##### `*seeds`
+
+Data type: `Optional[Variant[Integer,String]]`
+
+One of more values to use as a custom seed. These will be combined with the host's FQDN
+
 ### <a name="stdlib--ip_in_range"></a>`stdlib::ip_in_range`
 
 Type: Ruby 4.x API

lib/puppet/functions/fqdn_rotate.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# @summary DEPRECATED.  Use the namespaced function [`stdlib::fqdn_rotate`](#stdlibfqdn_rotate) instead.
+Puppet::Functions.create_function(:fqdn_rotate) do
+  dispatch :deprecation_gen do
+    repeated_param 'Any', :args
+  end
+  def deprecation_gen(*args)
+    call_function('deprecation', 'fqdn_rotate', 'This method is deprecated, please use stdlib::fqdn_rotate instead.')
+    call_function('stdlib::fqdn_rotate', *args)
+  end
+end

lib/puppet/functions/stdlib/fqdn_rotate.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# @summary Rotates an array or string a random number of times, combining the `fqdn` fact and an optional seed for repeatable randomness.
+Puppet::Functions.create_function(:'stdlib::fqdn_rotate') do
+  # @param input
+  #   The String you want rotated a random number of times
+  # @param seeds
+  #   One of more values to use as a custom seed. These will be combined with the host's FQDN
+  #
+  # @return [String] Returns the rotated String
+  #
+  # @example Rotating a String
+  #   stdlib::fqdn_rotate('abcd')
+  # @example Using a custom seed
+  #   stdlib::fqdn_rotate('abcd', 'custom seed')
+  dispatch :fqdn_rotate_string do
+    param 'String', :input
+    optional_repeated_param 'Variant[Integer,String]', :seeds
+    return_type 'String'
+  end
+
+  # @param input
+  #   The Array you want rotated a random number of times
+  # @param seeds
+  #   One of more values to use as a custom seed. These will be combined with the host's FQDN
+  #
+  # @return [String] Returns the rotated Array
+  #
+  # @example Rotating an Array
+  #   stdlib::fqdn_rotate(['a', 'b', 'c', 'd'])
+  # @example Using custom seeds
+  #   stdlib::fqdn_rotate([1, 2, 3], 'custom', 'seed', 1)
+  dispatch :fqdn_rotate_array do
+    param 'Array', :input
+    optional_repeated_param 'Variant[Integer,String]', :seeds
+    return_type 'Array'
+  end
+
+  def fqdn_rotate_array(input, *seeds)
+    # Check whether it makes sense to rotate ...
+    return input if input.size <= 1
+
+    result = input.clone
+
+    require 'digest/md5'
+    seed = Digest::MD5.hexdigest([fqdn_fact, seeds].join(':')).hex
+
+    offset = Puppet::Util.deterministic_rand(seed, result.size).to_i
+
+    offset.times do
+      result.push result.shift
+    end
+
+    result
+  end
+
+  def fqdn_rotate_string(input, *seeds)
+    fqdn_rotate_array(input.split(''), seeds).join
+  end
+
+  private
+
+  def fqdn_fact
+    closure_scope['facts']['networking']['fqdn']
+  end
+end

lib/puppet/parser/functions/fqdn_rotate.rb

@@ -4,9 +4,9 @@
 
 describe 'fqdn_rotate' do
   it { is_expected.not_to eq(nil) }
-  it { is_expected.to run.with_params.and_raise_error(Puppet::ParseError, %r{wrong number of arguments}i) }
-  it { is_expected.to run.with_params(0).and_raise_error(Puppet::ParseError, %r{Requires either array or string to work with}) }
-  it { is_expected.to run.with_params({}).and_raise_error(Puppet::ParseError, %r{Requires either array or string to work with}) }
+  it { is_expected.to run.with_params.and_raise_error(ArgumentError, %r{expects at least 1 argument, got none}) }
+  it { is_expected.to run.with_params(0).and_raise_error(ArgumentError, %r{parameter 'input' expects a value of type String or Array, got Integer}) }
+  it { is_expected.to run.with_params({}).and_raise_error(ArgumentError, %r{parameter 'input' expects a value of type String or Array, got Hash}) }
   it { is_expected.to run.with_params('').and_return('') }
   it { is_expected.to run.with_params('a').and_return('a') }
   it { is_expected.to run.with_params('ã').and_return('ã') }
@@ -48,8 +48,6 @@
   end
 
   it 'uses the Puppet::Util.deterministic_rand function' do
-    skip 'Puppet::Util#deterministic_rand not available' unless Puppet::Util.respond_to?(:deterministic_rand)
-
     expect(Puppet::Util).to receive(:deterministic_rand).with(44_489_829_212_339_698_569_024_999_901_561_968_770, 4)
     fqdn_rotate('asdf')
   end
@@ -68,9 +66,9 @@ def fqdn_rotate(value, args = {})
 
     # workaround not being able to use let(:facts) because some tests need
     # multiple different hostnames in one context
-    allow(scope).to receive(:lookupvar).with('::fqdn').and_return(host)
+    allow(subject.func.closure_scope).to receive(:[]).with('facts').and_return({ 'networking' => { 'fqdn' => host } })
 
     function_args = [value] + extra
-    scope.function_fqdn_rotate(function_args)
+    scope.call_function('fqdn_rotate', function_args)
   end
 end