Addition of stdlib::getpwnam to return /etc/passwd entry.

REFERENCE.md

@@ -124,6 +124,7 @@ last Period).
 * [`stdlib::fqdn_rand_string`](#stdlib--fqdn_rand_string): Generates a random alphanumeric string. Combining the `$fqdn` fact and an
 optional seed for repeatable randomness.
 * [`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::getpwnam`](#stdlib--getpwnam): Given a username returns the user's entry from the `/etc/passwd` file.
 * [`stdlib::has_function`](#stdlib--has_function): Returns whether the Puppet runtime has access to a given function.
 * [`stdlib::has_interface_with`](#stdlib--has_interface_with): Returns boolean based on network interfaces present and their attribute values.
 * [`stdlib::ip_in_range`](#stdlib--ip_in_range): Returns true if the ipaddress is within the given CIDRs
@@ -139,6 +140,7 @@ Puppet structure
 * [`stdlib::seeded_rand_string`](#stdlib--seeded_rand_string): Generates a consistent random string of specific length based on provided seed.
 * [`stdlib::sha256`](#stdlib--sha256): Run a SHA256 calculation against a given value.
 * [`stdlib::shell_escape`](#stdlib--shell_escape): Escapes a string so that it can be safely used in a Bourne shell command line.
+* [`stdlib::sort_by`](#stdlib--sort_by): Sort an Array, Hash or String by mapping values through a given block.
 * [`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.
 * [`stdlib::str2resource`](#stdlib--str2resource): This converts a string to a puppet resource.
 * [`stdlib::time`](#stdlib--time): This function is deprecated. It implements the functionality of the original non-namespaced stdlib `time` function.
@@ -3455,6 +3457,58 @@ 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--getpwnam"></a>`stdlib::getpwnam`
+
+Type: Ruby 4.x API
+
+>* Note:*   The `stdlib::getpwnam` function will work only on platforms that support
+  `getpwnam`. Typically that is on POSIX like OSes and not Windows.
+
+#### Examples
+
+##### Get a password entry for user steve as a hash.
+
+```puppet
+$passwd_entry = stdlib::getpwnam('steve')
+```
+
+##### Get the UID of user steve
+
+```puppet
+$uid = stdlib::getpwnam('steve')["uid"]
+```
+
+#### `stdlib::getpwnam(String $user)`
+
+>* Note:*   The `stdlib::getpwnam` function will work only on platforms that support
+  `getpwnam`. Typically that is on POSIX like OSes and not Windows.
+
+Returns: `Hash` [Hash] For example `{"name"=>"root", "passwd"=>"x", "uid"=>0, "gid"=>0, "gecos"=>"root", "dir"=>"/root", "shell"=>"/bin/bash"}`
+
+Raises:
+
+* `ArgumentError` if no password entry can be found for the specified user.
+
+##### Examples
+
+###### Get a password entry for user steve as a hash.
+
+```puppet
+$passwd_entry = stdlib::getpwnam('steve')
+```
+
+###### Get the UID of user steve
+
+```puppet
+$uid = stdlib::getpwnam('steve')["uid"]
+```
+
+##### `user`
+
+Data type: `String`
+
+The username to fetch password record for.
+
 ### <a name="stdlib--has_function"></a>`stdlib::has_function`
 
 Type: Ruby 4.x API
@@ -4003,6 +4057,75 @@ Data type: `Any`
 
 The string to escape
 
+### <a name="stdlib--sort_by"></a>`stdlib::sort_by`
+
+Type: Ruby 4.x API
+
+Sort an Array, Hash or String by mapping values through a given block.
+
+#### Examples
+
+##### Sort local devices according to their used space.
+
+```puppet
+$facts['mountpoints'].stdlib::sort_by |$m| { $m.dig(1, 'used_bytes') }
+```
+
+#### `stdlib::sort_by(Array $ary, Callable[1,1] &$block)`
+
+The stdlib::sort_by function.
+
+Returns: `Array` Returns an ordered copy of ary.
+
+##### `ary`
+
+Data type: `Array`
+
+The Array to sort.
+
+##### `&block`
+
+Data type: `Callable[1,1]`
+
+The block for transforming elements of ary.
+
+#### `stdlib::sort_by(String $str, Callable[1,1] &$block)`
+
+The stdlib::sort_by function.
+
+Returns: `String` Returns an ordered copy of str.
+
+##### `str`
+
+Data type: `String`
+
+The String to sort.
+
+##### `&block`
+
+Data type: `Callable[1,1]`
+
+The block for transforming elements of str.
+
+#### `stdlib::sort_by(Hash $hsh, Variant[Callable[1,1], Callable[2,2]] &$block)`
+
+The stdlib::sort_by function.
+
+Returns: `Hash` Returns an ordered copy of hsh.
+
+##### `hsh`
+
+Data type: `Hash`
+
+The Hash to sort.
+
+##### `&block`
+
+Data type: `Variant[Callable[1,1], Callable[2,2]]`
+
+The block for transforming elements of hsh.
+The block may have arity of one or two.
+
 ### <a name="stdlib--start_with"></a>`stdlib::start_with`
 
 Type: Ruby 4.x API

lib/puppet/functions/stdlib/getpwnam.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# @summary
+#   Given a username returns the user's entry from the `/etc/passwd` file.
+#
+# >* Note:*   The `stdlib::getpwnam` function will work only on platforms that support
+#   `getpwnam`. Typically that is on POSIX like OSes and not Windows.
+#
+Puppet::Functions.create_function(:'stdlib::getpwnam') do
+  # @param user
+  #    The username to fetch password record for.
+  #
+  # @example Get a password entry for user steve as a hash.
+  #   $passwd_entry = stdlib::getpwnam('steve')
+  #
+  # @example Get the UID of user steve
+  #   $uid = stdlib::getpwnam('steve')["uid"]
+  #
+  # @raise ArgumentError if no password entry can be found for the specified user.
+  #
+  # @return
+  #   [Hash] For example `{"name"=>"root", "passwd"=>"x", "uid"=>0, "gid"=>0, "gecos"=>"root", "dir"=>"/root", "shell"=>"/bin/bash"}`
+  dispatch :getpwnam do
+    param 'String', :user
+    return_type 'Hash'
+  end
+
+  def getpwnam(user)
+    Etc.getpwnam(user).to_h.first(7).map { |k, v| { k.to_s => v } }.reduce(:merge)
+  end
+end

spec/acceptance/getpwnam_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'spec_helper_acceptance'
+
+describe 'function stdlib::getpwnam' do
+  context 'finding the UID of the root user' do
+    let(:pp) do
+      <<-MANIFEST
+      $_password_entry = stdlib::getpwnam('root')
+      file{ '/tmp/roots_uid.txt':
+        ensure  => file,
+        content => "${_password_entry['uid']}\n",
+      }
+
+      # Test the use case for systemd module
+      user{ 'testu':
+        ensure => present,
+        uid    => 250,
+      }
+    MANIFEST
+    end
+
+    it 'works idempotently with no errors' do
+      apply_manifest(pp, catch_failures: true) unless os[:family] == 'windows'
+      apply_manifest(pp, catch_changes: true) unless os[:family] == 'windows'
+    end
+
+    describe file('/tmp/roots_uid.txt') do
+      it { is_expected.to contain '0' } unless os[:family] == 'windows'
+    end
+  end
+
+  context 'put the uid into environment of an exec ' do
+    let(:pp) do
+      <<-MANIFEST
+      exec{ 'env_to_file':
+        user        => 'testu',
+        environment => Deferred(
+          'inline_epp',
+          [
+            'MY_XDG_RUNTIME_DIR=/run/user/<%= $pwval["uid"] %>',
+            { 'pwval' => Deferred('stdlib::getpwnam',['testu'])}
+          ]
+        ),
+        command     => 'echo $MY_XDG_RUNTIME_DIR > /tmp/test-xdg-dir',
+        path        => $facts['path'],
+        creates     => '/tmp/test-xdg-dir',
+      }
+    MANIFEST
+    end
+
+    it 'works idempotently with no errors' do
+      apply_manifest(pp, catch_failures: true) unless os[:family] == 'windows'
+      apply_manifest(pp, catch_changes: true) unless os[:family] == 'windows'
+    end
+
+    describe file('/tmp/test-xdg-dir') do
+      it { is_expected.to contain '/run/user/250' } unless os[:family] == 'windows'
+      it { is_expected.to be_owned_by 'testu' } unless os[:family] == 'windows'
+    end
+  end
+
+  # This puppet fails on Puppet7
+  # It fails with " Error: can't find user for testx"
+  # This is
+  # https://puppet.atlassian.net/browse/PUP-11526
+  # Code below should be fine but the fact function is not defined
+  # which I don't understand so I can't mark as pending on Puppet7.
+  #  context 'put the uid into environment of an exec' do
+  #  let(:pp) do
+  #      <<-MANIFEST
+  #     user{ 'testx':
+  #       ensure => present,
+  #       uid    => 251,
+  #     }
+  #     exec{ 'env_to_file':
+  #       user        => 'testx',
+  #       environment => Deferred(
+  #         'inline_epp',
+  #         [
+  #           'MY_XDG_RUNTIME_DIR=/run/user/<%= $pwval["uid"] %>',
+  #           { 'pwval' => Deferred('stdlib::getpwnam',['testx'])}
+  #         ]
+  #       ),
+  #       command     => 'echo $MY_XDG_RUNTIME_DIR > /tmp/testx-xdg-dir',
+  #       path        => $facts['path'],
+  #       creates     => '/tmp/testx-xdg-dir',
+  #       require     => User['testx'],
+  #     }
+  #   MANIFEST
+  #    end
+  #
+  #    it 'works idempotently with no errors' do
+  #      pending('puppet7 having https://puppet.atlassian.net/browse/PUP-11526') if fact('puppetversion').to_f < 8 && (os[:family] != 'windows')
+  #      apply_manifest(pp, catch_failures: true) unless os[:family] == 'windows'
+  #      apply_manifest(pp, catch_changes: true) unless os[:family] == 'windows'
+  #    end
+  #
+  #    describe file('/tmp/testx-xdg-dir') do
+  #      it {
+  #        pending('puppet7 having https://puppet.atlassian.net/browse/PUP-11526') if fact('puppetversion').to_f < 8 && (os[:family] != 'windows')
+  #        is_expected.to contain '/run/user/251' unless os[:family] == 'windows'
+  #      }
+  #      it {
+  #        pending('puppet7 having https://puppet.atlassian.net/browse/PUP-11526') if fact('puppetversion').to_f < 8 && (os[:family] != 'windows')
+  #        is_expected.to be_owned_by 'testx' unless os[:family] == 'windows'
+  #      }
+  #    end
+end

spec/functions/getpwnam_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'stdlib::getpwnam' do
+  it { is_expected.not_to be_nil }
+  it { is_expected.to run.with_params.and_raise_error(ArgumentError, %r{expects 1 argument, got none}i) }
+
+  it {
+    passwd_entry = Etc::Passwd.new(
+       'steve',
+       'x',
+       1000,
+       1001,
+       'Steve',
+       '/home/steve',
+       '/bin/fish',
+     )
+    allow(Etc).to receive(:getpwnam).with(anything, anything).and_call_original
+    allow(Etc).to receive(:getpwnam).with('steve').and_return(passwd_entry)
+    is_expected.to run.with_params('steve').and_return(
+      {
+        'name' => 'steve',
+        'passwd' => 'x',
+        'uid' => 1000,
+        'gid' => 1001,
+        'gecos' => 'Steve',
+        'dir' => '/home/steve',
+        'shell' => '/bin/fish'
+      },
+    )
+  }
+
+  it { is_expected.to run.with_params('notexisting').and_raise_error(ArgumentError, %r{can't find user for notexisting}i) }
+end