openbolt 5.0.0.rc1

data/bolt-modules/boltlib/lib/puppet/functions/upload_file.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Uploads the given file or directory to the given set of targets and returns the result from each upload.
+# This function does nothing if the list of targets is empty.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunction) do
+  # Upload a file or directory.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a
+  #               file or directory in $MODULEROOT/files.
+  # @param destination An absolute path on the target(s).
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target.
+  # @example Upload a local file to Linux targets and change owner to 'root'
+  #   upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, '_run_as' => 'root')
+  # @example Upload a module file to a Windows target
+  #   upload_file('postgres/default.conf', 'C:/ProgramData/postgres/default.conf', $target)
+  dispatch :upload_file do
+    scope_param
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  # Upload a file or directory, logging the provided description.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a
+  #               file or directory in $MODULEROOT/files.
+  # @param destination An absolute path on the target(s).
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target.
+  # @example Upload a file
+  #   upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, 'Uploading payload to unpack')
+  dispatch :upload_file_with_description do
+    scope_param
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def upload_file(scope, source, destination, targets, options = {})
+    upload_file_with_description(scope, source, destination, targets, nil, options)
+  end
+
+  def upload_file_with_description(scope, source, destination, targets, description = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'upload_file')
+    end
+
+    options = options.select { |opt| opt.start_with?('_') }.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    options[:description] = description if description
+
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(source, scope)
+    unless found && Puppet::FileSystem.exist?(found)
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: source
+      )
+    end
+    executor.report_file_source(self.class.name, source)
+    # Ensure that that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+    if targets.empty?
+      call_function('debug', "Simulating file upload of '#{found}' - no targets given - no action taken")
+      Bolt::ResultSet.new([])
+    else
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      r = if executor.in_parallel?
+            executor.run_in_thread do
+              executor.upload_file(targets, found, destination, options, file_line)
+            end
+          else
+            executor.upload_file(targets, found, destination, options, file_line)
+          end
+      if !r.ok && !options[:catch_errors]
+        raise Bolt::RunFailure.new(r, 'upload_file', source)
+      end
+      r
+    end
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/vars.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Returns a hash of the 'vars' (variables) assigned to a target.
+#
+# Vars can be assigned through the inventory file or `set_var` function.
+# Plan authors can call this function on a target to get the variable hash
+# for that target.
+Puppet::Functions.create_function(:vars) do
+  # @param target The Target object to get variables from. See {get_targets}.
+  # @return A hash of the 'vars' (variables) assigned to a target.
+  # @example Get vars for a target
+  #   $target.vars
+  dispatch :vars do
+    param 'Target', :target
+    return_type 'Hash[String, Data]'
+  end
+
+  def vars(target)
+    inventory = Puppet.lookup(:bolt_inventory)
+    # Bolt executor not expected when invoked from apply block
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
+    executor&.report_function_call(self.class.name)
+
+    inventory.vars(target)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/wait.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'bolt/logger'
+
+# Wait for a Future or array of Futures to finish and return results,
+# optionally with a timeout.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:wait, Puppet::Functions::InternalFunction) do
+  # Wait for Futures to finish.
+  # @param futures A Bolt Future object or array of Bolt Futures to wait on.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Upload a large file in the background, then wait until it's loaded
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures)
+  dispatch :wait do
+    param 'Variant[Future, Array[Future]]', :futures
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  # Wait for all Futures in the current plan to finish.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Perform multiple tasks in the background, then wait for all of them to finish
+  #   background() || { upload_file("./large_file", "/opt/jfrog/...", $targets) }
+  #   background() || { run_task("db::migrate", $targets) }
+  #   # Wait for all futures in the plan to finish and return all results
+  #   $results = wait()
+  dispatch :wait_for_all do
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  # Wait for all Futures in the current plan to finish with a timeout.
+  # @param timeout How long to wait for Futures to finish before raising a Timeout error.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Perform multiple tasks in the background, then wait for all of them to finish with a timeout
+  #   background() || { upload_file("./large_file", "/opt/jfrog/...", $targets) }
+  #   background() || { run_task("db::migrate", $targets) }
+  #   # Wait for all futures in the plan to finish and return all results
+  #   $results = wait(30)
+  dispatch :wait_for_all_with_timeout do
+    param 'Variant[Integer[0], Float[0.0]]', :timeout
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  # Wait for Futures to finish with timeout.
+  # @param futures A Bolt Future object or array of Bolt Futures to wait on.
+  # @param timeout How long to wait for Futures to finish before raising a Timeout error.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Upload a large file in the background with a 30 second timeout.
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures, 30)
+  #
+  # @example Upload a large file in the background with a 30 second timeout, catching any errors.
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures, 30, '_catch_errors' => true)
+  dispatch :wait_with_timeout do
+    param 'Variant[Future, Array[Future]]', :futures
+    param 'Variant[Integer[0], Float[0.0]]', :timeout
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  def wait(futures, options = {})
+    inner_wait(futures: futures, options: options)
+  end
+
+  def wait_for_all(options = {})
+    inner_wait(options: options)
+  end
+
+  def wait_for_all_with_timeout(timeout, options = {})
+    inner_wait(timeout: timeout, options: options)
+  end
+
+  def wait_with_timeout(futures, timeout, options = {})
+    inner_wait(futures: futures, timeout: timeout, options: options)
+  end
+
+  def inner_wait(futures: nil, timeout: nil, options: {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'wait')
+    end
+
+    valid, unknown = options.partition { |k, _v| %w[_catch_errors].include?(k) }.map(&:to_h)
+    if unknown.any?
+      file, line = Puppet::Pops::PuppetStack.top_of_stack
+      msg = "The wait() function call in #{file}#L#{line} received unknown options "\
+        "#{unknown.keys}. Removing unknown options and continuing..."
+      Bolt::Logger.warn("plan_function_options", msg)
+    end
+
+    valid = valid.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    valid[:timeout] = timeout if timeout
+
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    # If we get a single Future, make sure it's an array. If we didn't get any
+    # futures pass that on to wait so we can continue collecting any futures
+    # that are created while waiting on existing futures.
+    futures = Array(futures) unless futures.nil?
+    executor.wait(futures, **valid)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/wait_until_available.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'bolt/util'
+
+# Wait until all targets accept connections. This function allows a plan execution to wait for a customizable
+# amount of time via the `wait_time` option until a target connection can be reestablished. The plan proceeds
+# to the next step if the connection fails to reconnect in the time specified (default: 120 seconds). A typical
+# use case for this function is if your plan reboots a remote host and the plan needs to wait for the host to reconnect
+# before it continues to the next step.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:wait_until_available) do
+  # Wait until targets are available.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
+  # @option options [String] description A description for logging. (default: 'wait until available')
+  # @option options [Numeric] wait_time The time to wait, in seconds. (default: 120)
+  # @option options [Numeric] retry_interval The interval to wait before retrying, in seconds. (default: 1)
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A list of results, one entry per target. Successful results have no value.
+  # @example Wait for targets
+  #   wait_until_available($targets, wait_time => 300)
+  dispatch :wait_until_available do
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def wait_until_available(targets, options = nil)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'wait_until_available')
+    end
+
+    options ||= {}
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Ensure that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+
+    if targets.empty?
+      call_function('debug', "Simulating wait_until_available - no targets given")
+      r = Bolt::ResultSet.new([])
+    else
+      opts = Bolt::Util.symbolize_top_level_keys(options.reject { |k| k == '_catch_errors' })
+      r = executor.wait_until_available(targets, **opts)
+    end
+
+    if !r.ok && !options['_catch_errors']
+      raise Bolt::RunFailure.new(r, 'wait_until_available')
+    end
+    r
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/without_default_logging.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Define a block where default logging is suppressed.
+#
+# Messages for actions within this block will be logged at `info` level instead
+# of `notice`, so they will not be seen normally but will still be present
+# when `verbose` logging is requested.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:without_default_logging) do
+  # @param block The block where action logging is suppressed.
+  # @return [Undef]
+  # @example Suppress default logging for a series of functions
+  #   without_default_logging() || {
+  #     notice("Deploying on ${nodes}")
+  #     get_targets($targets).each |$target| {
+  #       run_task(deploy, $target)
+  #     }
+  #   }
+  dispatch :without_default_logging do
+    block_param 'Callable[0, 0]', :block
+  end
+
+  def without_default_logging
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'without_default_logging')
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    executor.without_default_logging do
+      yield
+    end
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/write_file.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+# Write contents to a file on the given set of targets.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:write_file) do
+  # @param content File content to write.
+  # @param destination An absolute path on the target(s).
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target.
+  # @example Write a file to a target
+  #   $content = 'Hello, world!'
+  #   write_file($content, '/Users/me/hello.txt', $targets)
+  dispatch :write_file do
+    required_param 'String', :content
+    required_param 'String[1]', :destination
+    required_param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def write_file(content, destination, target_spec, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'write_file')
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    inventory = Puppet.lookup(:bolt_inventory)
+    targets = inventory.get_targets(target_spec)
+
+    executor.log_action("write file #{destination}", targets) do
+      executor.without_default_logging do
+        Tempfile.create do |tmp|
+          call_function('file::write', tmp.path, content)
+          call_function('upload_file', tmp.path, destination, targets, options)
+        end
+      end
+    end
+  end
+end

data/bolt-modules/boltlib/types/planresult.pp

@@ -0,0 +1,18 @@
+# A PlanResult describes the supported return values of a plan. It
+# should be used as the return type of functions that run plans and return the
+# results.
+
+type Boltlib::PlanResult = Variant[Boolean, 
+                                   Numeric,
+                                   String,
+                                   Undef,
+                                   Error,
+                                   Result,
+                                   ApplyResult,
+                                   ResultSet,
+                                   Target,
+                                   ResourceInstance,
+                                   ContainerResult,
+                                   Future,
+                                   Array[Boltlib::PlanResult],
+                                   Hash[String, Boltlib::PlanResult]]

data/bolt-modules/boltlib/types/targetspec.pp

@@ -0,0 +1,7 @@
+# A TargetSpec represents any String, Target or combination thereof that can be
+# passed to get_targets() to return an Array[Target]. Generally, users
+# shouldn't need to worry about the distinction between TargetSpec and
+# Target/Array[Target], since the run_* functions will all handle them both
+# automatically. But for use cases that need to deal with the exact list of
+# Targets that will be used, get_targets() will return that.
+type Boltlib::TargetSpec = Variant[String[1], Target, Array[Boltlib::TargetSpec]]

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Repeat the block until it returns a truthy value. Returns the value.
+Puppet::Functions.create_function(:'ctrl::do_until') do
+  # @param options A hash of additional options.
+  # @param block The code block to repeat.
+  # @option options [Numeric] limit The number of times to repeat the block.
+  # @option options [Numeric] interval The number of seconds to wait before repeating the block.
+  # @return The value of the code block's last iteration
+  # @example Run a task until it succeeds
+  #   ctrl::do_until() || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  # @example Run a task until it succeeds or fails 10 times
+  #   ctrl::do_until('limit' => 10) || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  # @example Run a task and wait 10 seconds before running it again
+  #   ctrl::do_until('interval' => 10) || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  dispatch :do_until do
+    optional_param 'Hash[String[1], Any]', :options
+    block_param
+  end
+
+  def do_until(options = {})
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    limit = options['limit'] || 0
+    interval = options['interval']
+
+    i = 0
+    until (x = yield)
+      i += 1
+      break if limit != 0 && i >= limit
+      Kernel.sleep(interval) if interval
+    end
+    x
+  end
+end

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/sleep.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Sleeps for specified number of seconds.
+Puppet::Functions.create_function(:'ctrl::sleep') do
+  # @param period Time to sleep (in seconds)
+  # @example Sleep for 5 seconds
+  #   ctrl::sleep(5)
+  dispatch :sleeper do
+    required_param 'Numeric', :period
+    return_type 'Undef'
+  end
+
+  def sleeper(period)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    sleep(period)
+    nil
+  end
+end

data/bolt-modules/dir/lib/puppet/functions/dir/children.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# Returns an array containing all of the filenames except for "." and ".." in the given directory.
+Puppet::Functions.create_function(:'dir::children', Puppet::Functions::InternalFunction) do
+  # @param dirname Absolute path or Puppet module name.
+  # @return Array of files in the given directory.
+  # @example List filenames from an absolute path.
+  #   dir::children('/home/user/subdir/')
+  # @example List filenames from a Puppet file path.
+  #   dir::children('puppet_agent')
+  dispatch :children do
+    scope_param
+    required_param 'String', :dirname
+    return_type 'Array'
+  end
+
+  def children(scope, dirname)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+    modname, subpath = dirname.split(File::SEPARATOR, 2)
+    mod_path = scope.compiler.environment.module(modname)&.path
+
+    full_mod_path = File.join(mod_path, subpath || '') if mod_path
+
+    # Expand relative to the project directory if path is relative
+    project = Puppet.lookup(:bolt_project)
+    pathname = Pathname.new(dirname)
+    full_dir = pathname.absolute? ? dirname : File.expand_path(File.join(project.path, dirname))
+
+    # Sort for testability
+    Dir.children(full_mod_path || full_dir).sort
+  end
+end

data/bolt-modules/file/lib/puppet/functions/file/delete.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Delete a file on localhost using ruby's `File.delete`. This will only delete
+# files on the machine you run Bolt on.
+Puppet::Functions.create_function(:'file::delete') do
+  # @param filename Absolute path.
+  # @example Delete a file from disk
+  #   file::delete('C:/Users/me/report')
+  dispatch :delete do
+    required_param 'String[1]', :filename
+    return_type 'Undef'
+  end
+
+  def delete(filename)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    File.delete(filename)
+    nil
+  end
+end

data/bolt-modules/file/lib/puppet/functions/file/exists.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Check if a local file exists using Puppet's
+# `Puppet::Parser::Files.find_file()` function. This will only check files that
+# are on the machine Bolt is run on.
+Puppet::Functions.create_function(:'file::exists', Puppet::Functions::InternalFunction) do
+  # @param filename Absolute path or Puppet file path.
+  # @return Whether the file exists.
+  # @example Check a file on disk
+  #   file::exists('/tmp/i_dumped_this_here')
+  # @example check a file from the modulepath
+  #   file::exists('example/VERSION')
+  dispatch :exists do
+    scope_param
+    required_param 'String[1]', :filename
+    return_type 'Boolean'
+  end
+
+  def exists(scope, filename)
+    # Send Analytics Report
+    executor = Puppet.lookup(:bolt_executor) {}
+    executor&.report_function_call(self.class.name)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(filename, scope)
+    found ? Puppet::FileSystem.exist?(found) : false
+  end
+end

data/bolt-modules/file/lib/puppet/functions/file/join.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Join file paths using ruby's `File.join()` function.
+Puppet::Functions.create_function(:'file::join') do
+  # @param paths The paths to join.
+  # @return The joined file path.
+  # @example Join file paths
+  #   file::join('./path', 'to/files')
+  dispatch :join do
+    required_repeated_param 'String', :paths
+    return_type 'String'
+  end
+
+  def join(*paths)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+
+    File.join(paths)
+  end
+end

data/bolt-modules/file/lib/puppet/functions/file/read.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Read a file on localhost and return its contents using ruby's `File.read`. This will
+# only read files on the machine you run Bolt on.
+Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunction) do
+  # @param filename Absolute path or Puppet file path.
+  # @return The file's contents.
+  # @example Read a file from disk
+  #   file::read('/tmp/i_dumped_this_here')
+  # @example Read a file from the modulepath
+  #   file::read('example/VERSION')
+  dispatch :read do
+    scope_param
+    required_param 'String[1]', :filename
+    return_type 'String'
+  end
+
+  def read(scope, filename)
+    # Send Analytics Report
+    executor = Puppet.lookup(:bolt_executor) {}
+    executor&.report_function_call(self.class.name)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(filename, scope)
+    unless found && Puppet::FileSystem.exist?(found)
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: filename
+      )
+    end
+    executor&.report_file_source(self.class.name, filename)
+    File.read(found)
+  end
+end