Finish conversion of postgresql_escape function

In puppetlabs#1129 the 3
functions from this module were ported to the modern function API and
namespaced.  None of the boilerplate was fixed up, tests weren't
updated, documentation wasn't updated etc.

This commit finishes the work for the `postgresql_escape` function.

* Remove old API puppet/parser/functions version.
* Create a replacement non-namespaced, (but deprecated), new API shim
  that calls the namespaced version. This function is *probably* not
  being used outside of this module, but it doesn't hurt to get the old
  version around for now.
* Replace argument validation in the function code with data-type based
  validation for the individual function parameters.
* Refactor function for increased readability.
* Test both shim and namespaced version of the function.
* Update `postgresql::server` to use namespaced version.
* Update REFERENCE.md

Author: alexjfisher

REFERENCE.md

@@ -63,10 +63,10 @@ _Private Classes_
 
 * [`postgresql::default`](#postgresqldefault): This function pull default values from the `params` class  or `globals` class if the value is not present in `params`.
 * [`postgresql::postgresql_acls_to_resources_hash`](#postgresqlpostgresql_acls_to_resources_hash): This internal function translates the ipv(4|6)acls format into a resource
-* [`postgresql::postgresql_escape`](#postgresqlpostgresql_escape): This function safely escapes a string using a consistent random tag
+* [`postgresql::postgresql_escape`](#postgresqlpostgresql_escape): This function escapes a string by performing `Dollar Quoting` using a randomly generated tag if required.
 * [`postgresql::postgresql_password`](#postgresqlpostgresql_password): This function returns the postgresql password hash from the clear text username / password
 * [`postgresql_acls_to_resources_hash`](#postgresql_acls_to_resources_hash): This internal function translates the ipv(4|6)acls format into a resource suitable for create_resources. It is not intended to be used outsid
-* [`postgresql_escape`](#postgresql_escape): This function safely escapes a string using a consistent random tag
+* [`postgresql_escape`](#postgresql_escape): DEPRECATED.  Use the namespaced function [`postgresql::postgresql_escape`](#postgresqlpostgresql_escape) instead.
 * [`postgresql_password`](#postgresql_password): This function returns the postgresql password hash from the clear text username / password
 
 **Tasks**
@@ -1097,6 +1097,14 @@ Sets PostgreSQL version
 
 Default value: `undef`
 
+##### `extra_systemd_config`
+
+Data type: `Any`
+
+Adds extra config to systemd config file, can for instance be used to add extra openfiles. This can be a multi line string
+
+Default value: $postgresql::params::extra_systemd_config
+
 ##### `manage_selinux`
 
 Data type: `Boolean`
@@ -1667,6 +1675,22 @@ Specifies whether to grant or revoke the privilege. Default is to grant the priv
 
 Default value: 'present'
 
+##### `group`
+
+Data type: `String`
+
+Sets the OS group to run psql
+
+Default value: $postgresql::server::group
+
+##### `psql_path`
+
+Data type: `String`
+
+Sets the path to psql command
+
+Default value: $postgresql::server::psql_path
+
 ##### `object_arguments`
 
 Data type: `Array[String[1],0]`
@@ -2181,6 +2205,38 @@ Specify whether to create or drop the role. Specifying 'present' creates the rol
 
 Default value: 'present'
 
+##### `psql_user`
+
+Data type: `Any`
+
+Sets the OS user to run psql
+
+Default value: $postgresql::server::user
+
+##### `psql_group`
+
+Data type: `Any`
+
+Sets the OS group to run psql
+
+Default value: $postgresql::server::group
+
+##### `psql_path`
+
+Data type: `Any`
+
+Sets path to psql command
+
+Default value: $postgresql::server::psql_path
+
+##### `module_workdir`
+
+Data type: `Any`
+
+Specifies working directory under which the psql command should be executed. May need to specify if '/tmp' is on volume mounted with noexec option.
+
+Default value: $postgresql::server::module_workdir
+
 ### postgresql::server::schema
 
 Create a new schema.
@@ -2790,26 +2846,19 @@ to get the full benefit of the modern function API.
 
 Type: Ruby 4.x API
 
-postgresql_escape.rb
----- original file header ----
-
-   @return Safely escapes a string using $$ using a random tag which should be consistent
+This function escapes a string by performing `Dollar Quoting` using a randomly generated tag if required.
 
-#### `postgresql::postgresql_escape(Any *$args)`
+#### `postgresql::postgresql_escape(String[1] $input_string)`
 
-postgresql_escape.rb
----- original file header ----
+The postgresql::postgresql_escape function.
 
-   @return Safely escapes a string using $$ using a random tag which should be consistent
+Returns: `String` A `Dollar Quoted` string
 
-Returns: `Data type` Describe what the function returns here
+##### `input_string`
 
-##### `*args`
-
-Data type: `Any`
+Data type: `String[1]`
 
-The original array of arguments. Port this to individually managed params
-to get the full benefit of the modern function API.
+The unescaped string you want to escape using `dollar quoting`
 
 ### postgresql::postgresql_password
 
@@ -2872,15 +2921,21 @@ Returns: `Any` This function accepts an array of strings that are pg_hba.conf ru
 
 ### postgresql_escape
 
-Type: Ruby 3.x API
+Type: Ruby 4.x API
 
-This function safely escapes a string using a consistent random tag
+DEPRECATED.  Use the namespaced function [`postgresql::postgresql_escape`](#postgresqlpostgresql_escape) instead.
 
-#### `postgresql_escape()`
+#### `postgresql_escape(Any *$args)`
+
+The postgresql_escape function.
+
+Returns: `Any`
+
+##### `*args`
+
+Data type: `Any`
 
-This function safely escapes a string using a consistent random tag
 
-Returns: `Any` Safely escapes a string using $$ using a random tag which should be consistent
 
 ### postgresql_password
 

lib/puppet/functions/postgresql/postgresql_escape.rb

@@ -1,52 +1,31 @@
-# This is an autogenerated function, ported from the original legacy version.
-# It /should work/ as is, but will not have all the benefits of the modern
-# function API. You should see the function docs to learn how to add function
-# signatures for type safety and to document this function using puppet-strings.
-#
-# https://puppet.com/docs/puppet/latest/custom_functions_ruby.html
-#
-# ---- original file header ----
 require 'digest/md5'
 
-# postgresql_escape.rb
-# ---- original file header ----
-#
-# @summary
-#       This function safely escapes a string using a consistent random tag
-#    @return Safely escapes a string using $$ using a random tag which should be consistent
-#
-#
+# @summary This function escapes a string by performing `Dollar Quoting` using a randomly generated tag if required.
+# @see https://www.postgresql.org/docs/12/sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING
 Puppet::Functions.create_function(:'postgresql::postgresql_escape') do
-  # @param args
-  #   The original array of arguments. Port this to individually managed params
-  #   to get the full benefit of the modern function API.
-  #
-  # @return [Data type]
-  #   Describe what the function returns here
+  # @param input_string
+  #   The unescaped string you want to escape using `dollar quoting`
   #
+  # @return [String]
+  #   A `Dollar Quoted` string
   dispatch :default_impl do
-    # Call the method named 'default_impl' when this is matched
-    # Port this to match individual params for better type safety
-    repeated_param 'Any', :args
+    param 'String[1]', :input_string
   end
 
-  def default_impl(*args)
-    if args.size != 1
-      raise(Puppet::ParseError, 'postgresql_escape(): Wrong number of arguments ' \
-        "given (#{args.size} for 1)")
+  def default_impl(input_string)
+    # Where allowed, just return the original string wrapped in `$$`
+    return "$$#{input_string}$$" unless tag_needed?(input_string)
+
+    # Keep generating possible values for tag until we find one that doesn't appear in the input string
+    tag = Digest::MD5.hexdigest(input_string)[0..5].gsub(%r{\d}, '')
+    until input_string !~ %r{#{tag}}
+      tag = Digest::MD5.hexdigest(tag)[0..5].gsub(%r{\d}, '')
     end
 
-    password = args[0]
+    "$#{tag}$#{input_string}$#{tag}$"
+  end
 
-    if password !~ %r{\$\$} && password[-1] != '$'
-      retval = "$$#{password}$$"
-    else
-      escape = Digest::MD5.hexdigest(password)[0..5].gsub(%r{\d}, '')
-      until password !~ %r{#{escape}}
-        escape = Digest::MD5.hexdigest(escape)[0..5].gsub(%r{\d}, '')
-      end
-      retval = "$#{escape}$#{password}$#{escape}$"
-    end
-    retval
+  def tag_needed?(input_string)
+    input_string =~ %r{\$\$} || input_string.end_with?('$')
   end
 end

lib/puppet/functions/postgresql_escape.rb

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

lib/puppet/parser/functions/postgresql_escape.rb

@@ -15,12 +15,12 @@
     default => ''
   }
 
-  if ($postgres_password != undef) {
+  if $postgres_password {
     # NOTE: this password-setting logic relies on the pg_hba.conf being
     #  configured to allow the postgres system user to connect via psql
     #  without specifying a password ('ident' or 'trust' security). This is
     #  the default for pg_hba.conf.
-    $escaped = postgresql_escape($postgres_password)
+    $escaped = postgresql::postgresql_escape($postgres_password)
     exec { 'set_postgres_postgrespw':
       # This command works w/no password because we run it as postgres system
       # user

manifests/server/passwd.pp

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe 'postgresql_escape' do
+  it_behaves_like 'postgresql_escape function'
+end

spec/functions/postgresql_escape_spec.rb

@@ -1,40 +1,5 @@
 require 'spec_helper'
 
 describe 'postgresql::postgresql_escape' do
-  # without knowing details about the implementation, this is the only test
-  # case that we can autogenerate. You should add more examples below!
-  it { is_expected.not_to eq(nil) }
-
-  #################################
-  # Below are some example test cases. You may uncomment and modify them to match
-  # your needs. Notice that they all expect the base error class of `StandardError`.
-  # This is because the autogenerated function uses an untyped array for parameters
-  # and relies on your implementation to do the validation. As you convert your
-  # function to proper dispatches and typed signatures, you should change the
-  # expected error of the argument validation examples to `ArgumentError`.
-  #
-  # Other error types you might encounter include
-  #
-  # * StandardError
-  # * ArgumentError
-  # * Puppet::ParseError
-  #
-  # Read more about writing function unit tests at https://rspec-puppet.com/documentation/functions/
-  #
-  #   it 'raises an error if called with no argument' do
-  #     is_expected.to run.with_params.and_raise_error(StandardError)
-  #   end
-  #
-  #   it 'raises an error if there is more than 1 arguments' do
-  #     is_expected.to run.with_params({ 'foo' => 1 }, 'bar' => 2).and_raise_error(StandardError)
-  #   end
-  #
-  #   it 'raises an error if argument is not the proper type' do
-  #     is_expected.to run.with_params('foo').and_raise_error(StandardError)
-  #   end
-  #
-  #   it 'returns the proper output' do
-  #     is_expected.to run.with_params(123).and_return('the expected output')
-  #   end
-  #################################
+  it_behaves_like 'postgresql_escape function'
 end

spec/functions/postgresql_postgresql_escape_spec.rb

@@ -41,3 +41,23 @@
 def param(type, title, param)
   param_value(catalogue, type, title, param)
 end
+
+shared_examples 'postgresql_escape function' do
+  it { is_expected.not_to eq(nil) }
+  it {
+    is_expected.to run.with_params('foo')
+      .and_return('$$foo$$')
+  }
+  it {
+    is_expected.to run.with_params('fo$$o')
+      .and_return('$ed$fo$$o$ed$')
+  }
+  it {
+    is_expected.to run.with_params('foo$')
+      .and_return('$a$foo$$a$')
+  }
+  it 'raises an error if there is more than 1 argument' do
+    is_expected.to run.with_params(['foo'], ['foo'])
+      .and_raise_error(StandardError)
+  end
+end