chef 18.10.17 → 19.2.12

data/lib/chef/resource/_rest_resource.rb

@@ -1,5 +1,5 @@
 #
-# Copyright:: Copyright 2008-2016, Chef, Inc.
+# Copyright (c) 2009-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +15,101 @@
 # limitations under the License.
 #
 
+unified_mode true
+
+provides :rest_resource
+
+description "Base resource for interacting with REST APIs. Extend this resource to create custom resources that manage REST API endpoints."
+
+introduced "18.0"
+
+examples <<~'DOC'
+  **Create a custom REST resource for managing users in an API**
+
+  ```ruby
+  class Chef::Resource::ApiUser < Chef::Resource::RestResource
+    resource_name :api_user
+    provides :api_user
+
+    rest_api_endpoint "https://api.example.com"
+    rest_api_collection "/api/v1/users"
+    rest_identity_property :username
+
+    property :username, String, name_property: true
+    property :email, String
+    property :full_name, String
+    property :active, [true, false], default: true
+
+    rest_property_map({
+      username: "username",
+      email: "email",
+      full_name: "profile.fullName",
+      active: "status.active"
+    })
+
+    rest_post_only_properties [:username]
+  end
+  ```
+
+  **Use the custom resource to create a user**
+
+  ```ruby
+  api_user "testuser" do
+    email "testuser@example.com"
+    full_name "Test User"
+    active true
+    action :configure
+  end
+  ```
+
+  **Delete a user via the API**
+
+  ```ruby
+  api_user "testuser" do
+    action :delete
+  end
+  ```
+
+  **Use JMESPath for complex JSON mapping**
+
+  ```ruby
+  class Chef::Resource::ApiProject < Chef::Resource::RestResource
+    resource_name :api_project
+
+    rest_api_endpoint "https://api.example.com"
+    rest_api_collection "/projects"
+    rest_identity_property :project_id
+
+    property :project_id, String, name_property: true
+    property :member_emails, Array
+
+    # Extract email addresses from nested members array
+    rest_property_map({
+      project_id: "id",
+      member_emails: "members[*].email"
+    })
+  end
+  ```
+
+  **Configure authentication with custom headers**
+
+  ```ruby
+  class Chef::Resource::ApiResource < Chef::Resource::RestResource
+    rest_api_endpoint "https://api.example.com"
+    rest_api_collection "/resources"
+
+    action_class do
+      def rest_headers
+        {
+          "Authorization" => "Bearer #{node['api_token']}",
+          "X-API-Version" => "2024-01-01"
+        }
+      end
+    end
+  end
+  ```
+DOC
+
 require "addressable/template" unless defined?(Addressable::Template)
 require "rest-client" unless defined?(RestClient)
 require "jmespath" unless defined?(JMESPath)
@@ -48,7 +143,7 @@ action_class do
   end
 end
 
-action :configure do
+action :configure, description: "Create or update the resource via the REST API. If the resource doesn't exist, this performs a POST to create it. If the resource exists and properties changed, this performs a PATCH to update it." do
   if resource_exists?
     converge_if_changed do
       data = {}
@@ -79,24 +174,36 @@ action :configure do
   end
 end
 
-action :delete do
+action :delete, description: "Delete the resource via the REST API. If the resource doesn't exist, this action takes no action." do
   if resource_exists?
     converge_by "deleting resource" do
       rest_delete
     end
   else
     logger.debug format("REST resource %<name>s of type %<type>s does not exist. Skipping.",
-      type: new_resource.name, name: id_property)
+                        type: new_resource.name, name: id_property)
   end
 end
 
 action_class do
-  # Override this for postprocessing device-specifics (paging, data conversion)
+  #
+  # Postprocess API responses. Override in custom resources to transform
+  # or extract data from responses, handle pagination, etc.
+  #
+  # @param response [RestClient::Response] The API response object
+  # @return [RestClient::Response] The processed response
+  #
   def rest_postprocess(response)
     response
   end
 
-  # Override this for error handling of device-specifics (readable error messages)
+  #
+  # Handle REST API errors. Override in custom resources to provide
+  # user-friendly error messages or handle specific error codes.
+  #
+  # @param error_obj [RestClient::Exception] The exception object
+  # @return [RestClient::Exception] The processed error
+  #
   def rest_errorhandler(error_obj)
     error_obj
   end
@@ -111,7 +218,9 @@ action_class do
     current_resource.class.properties.select { |_, v| v.required? }.except(:name).keys
   end
 
+  #
   # Return changed value or nil for delta current->new
+  #
   def changed_value(property)
     new_value = new_resource.send(property)
     return new_value if current_resource.nil?
@@ -127,7 +236,9 @@ action_class do
     current_resource.class.identity_attr
   end
 
+  #
   # Map properties to their current values
+  #
   def property_map
     map = {}
 
@@ -142,7 +253,15 @@ action_class do
     map
   end
 
-  # Map part of a JSON (Hash) to resource property via JMESPath or user-supplied function
+  #
+  # Convert JSON API response to a resource property value.
+  # Supports JMESPath expressions (String) or custom functions (Symbol).
+  #
+  # @param match_instruction [String, Symbol] How to extract the value
+  # @param property [Symbol] The property name
+  # @param resource_data [Hash] The JSON response data
+  # @return [Object] The extracted property value
+  #
   def json_to_property(match_instruction, property, resource_data)
     case match_instruction
     when String
@@ -157,7 +276,14 @@ action_class do
     end
   end
 
-  # Map resource contents into a JSON (Hash) via JMESPath-like syntax or user-supplied function
+  #
+  # Convert a resource property value to JSON for API request.
+  # Supports JMESPath-like notation (String) or custom functions (Symbol).
+  #
+  # @param property [Symbol] The property name
+  # @param match_instruction [String, Symbol] How to structure the value
+  # @return [Hash] A hash representing the JSON structure
+  #
   def property_to_json(property, match_instruction)
     case match_instruction
     when String
@@ -177,13 +303,17 @@ action_class do
     current_resource.class.rest_api_collection
   end
 
+  #
   # Resource document URL after RFC 6570 template evaluation via properties substitution
+  #
   def rest_url_document
     template = ::Addressable::Template.new(current_resource.class.rest_api_document)
     template.expand(property_map).to_s
   end
 
+  #
   # Convenience method for conditional requires
+  #
   def conditionally_require_on_setting(property, dependent_properties)
     dependent_properties = Array(dependent_properties)
 
@@ -198,9 +328,9 @@ action_class do
       end
 
       message = format("Setting property :%<property>s requires properties :%<properties>s to be set as well on resource %<resource_name>s",
-        property: property,
-        properties: dependent_properties.join(", :"),
-        resource_name: current_resource.to_s)
+                       property: property,
+                       properties: dependent_properties.join(", :"),
+                       resource_name: current_resource.to_s)
 
       a.failure_message message
     end
@@ -267,12 +397,16 @@ action_class do
 
   # REST parameter mapping
 
+  #
   # Return number of parameters needed to identify a resource (pre- and post-creation)
+  #
   def rest_arity
     rest_identity_map.keys.count
   end
 
+  #
   # Return mapping of template placeholders to property value of identity parameters
+  #
   def rest_identity_values
     data = {}
 
@@ -288,11 +422,14 @@ action_class do
     rest_identity_explicit || rest_identity_implicit
   end
 
+  #
   # Accept direct mapping like { "svm.name" => :name } for specifying the x-ary identity of a resource
+  #
   def rest_identity_explicit
     current_resource.class.rest_identity_map
   end
 
+  #
   # Parse document URL for RFC 6570 templates and map them to resource properties.
   #
   # Examples:
@@ -351,8 +488,11 @@ action_class do
     Chef.run_context.transport.connection
   end
 
+  #
   # Remove all empty keys (recursively) from Hash.
+  #
   # @see https://stackoverflow.com/questions/56457020/#answer-56458673
+  #
   def deep_compact!(hsh)
     raise TypeError unless hsh.is_a? Hash
 
@@ -361,15 +501,20 @@ action_class do
     end.reject! { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
   end
 
+  #
   # Deep merge two hashes
+  #
   # @see https://stackoverflow.com/questions/41109599#answer-41109737
+  #
   def deep_merge!(hsh1, hsh2)
     raise TypeError unless hsh1.is_a?(Hash) && hsh2.is_a?(Hash)
 
     hsh1.merge!(hsh2) { |_, v1, v2| deep_merge!(v1, v2) }
   end
 
+  #
   # Create nested hashes from JMESPath syntax.
+  #
   def bury(path, value)
     raise TypeError unless path.is_a?(String)
 

data/lib/chef/resource/action_class.rb

@@ -1,6 +1,6 @@
 #
 # Author:: John Keiser (<jkeiser@chef.io)
-# Copyright:: Copyright (c) Chef Software Inc.
+# Copyright:: Copyright (c) 2009-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/lib/chef/resource/alternatives.rb

@@ -1,5 +1,5 @@
 #
-# Copyright:: Copyright (c) Chef Software Inc.
+# Copyright:: Copyright (c) 2009-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
 # Copyright:: 2016-2020, Virender Khatri
 #
 # License:: Apache License, Version 2.0
@@ -23,59 +23,60 @@ class Chef
   class Resource
     class Alternatives < Chef::Resource
 
-      provides(:alternatives) { true }
+      provides(:alternatives, target_mode: true) { true }
+      target_mode support: :full
 
       description "Use the **alternatives** resource to configure command alternatives in Linux using the alternatives or update-alternatives packages."
       introduced "16.0"
       examples <<~DOC
-        **Install an alternative**:
-
-        ```ruby
-        alternatives 'python install 2' do
-          link_name 'python'
-          path '/usr/bin/python2.7'
-          priority 100
-          action :install
-        end
-        ```
+      **Install an alternative**:
+
+      ```ruby
+      alternatives 'python install 2' do
+        link_name 'python'
+        path '/usr/bin/python2.7'
+        priority 100
+        action :install
+      end
+      ```
 
-        **Set an alternative**:
+      **Set an alternative**:
 
-        ```ruby
-        alternatives 'python set version 3' do
-          link_name 'python'
-          path '/usr/bin/python3'
-          action :set
-        end
-        ```
+      ```ruby
+      alternatives 'python set version 3' do
+        link_name 'python'
+        path '/usr/bin/python3'
+        action :set
+      end
+      ```
 
-        **Set the automatic alternative state**:
+      **Set the automatic alternative state**:
 
-        ```ruby
-        alternatives 'python auto' do
-          link_name 'python'
-          action :auto
-        end
-        ```
+      ```ruby
+      alternatives 'python auto' do
+        link_name 'python'
+        action :auto
+      end
+      ```
 
-        **Refresh an alternative**:
+      **Refresh an alternative**:
 
-        ```ruby
-        alternatives 'python refresh' do
-          link_name 'python'
-          action :refresh
-        end
-        ```
+      ```ruby
+      alternatives 'python refresh' do
+        link_name 'python'
+        action :refresh
+      end
+      ```
 
-        **Remove an alternative**:
+      **Remove an alternative**:
 
-        ```ruby
-        alternatives 'python remove' do
-          link_name 'python'
-          path '/usr/bin/python3'
-          action :remove
-        end
-        ```
+      ```ruby
+      alternatives 'python remove' do
+        link_name 'python'
+        path '/usr/bin/python3'
+        action :remove
+      end
+      ```
       DOC
 
       property :link_name, String,
@@ -113,7 +114,7 @@ class Chef
 
         requirements.assert(:install, :set, :remove) do |a|
           a.assertion do
-            ::File.exist?(new_resource.path)
+            ::TargetIO::File.exist?(new_resource.path)
           end
 
           a.whyrun("Assuming file #{new_resource.path} already exists or was created already")

data/lib/chef/resource/apt_package.rb

@@ -1,6 +1,6 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
-# Copyright:: Copyright (c) Chef Software Inc.
+# Copyright:: Copyright (c) 2009-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -24,49 +24,54 @@ class Chef
 
       provides :apt_package, target_mode: true
       provides :package, platform_family: "debian", target_mode: true
+      target_mode support: :full,
+        introduced: "15.1",
+        updated: "19.0",
+        description: "Does not support the `response_file` property in Target Mode."
+
       examples <<~DOC
-        **Install a package using package manager**:
+      **Install a package using package manager**:
 
-        ```ruby
-        apt_package 'name of package' do
-          action :install
-        end
-        ```
+      ```ruby
+      apt_package 'name of package' do
+        action :install
+      end
+      ```
 
-        **Install a package without specifying the default action**:
+      **Install a package without specifying the default action**:
 
-        ```ruby
-        apt_package 'name of package'
-        ```
+      ```ruby
+      apt_package 'name of package'
+      ```
 
-        **Install multiple packages at once**:
+      **Install multiple packages at once**:
 
-        ```ruby
-        apt_package %w(package1 package2 package3)
-        ```
+      ```ruby
+      apt_package %w(package1 package2 package3)
+      ```
 
-        **Install without using recommend packages as a dependency**:
+      **Install without using recommend packages as a dependency**:
 
-        ```ruby
-        package 'apache2' do
-          options '--no-install-recommends'
-        end
-        ```
+      ```ruby
+      package 'apache2' do
+        options '--no-install-recommends'
+      end
+      ```
 
-        **Prevent the apt_package resource from installing packages with pattern matching names**:
+      **Prevent the apt_package resource from installing packages with pattern matching names**:
 
-        By default, the apt_package resource will install the named package.
-        If it can't find a package with the exact same name, it will treat the package name as regular expression string and match with any package that matches that regular expression.
-        This may lead Chef Infra Client to install one or more packages with names that match that regular expression.
+      By default, the apt_package resource will install the named package.
+      If it can't find a package with the exact same name, it will treat the package name as regular expression string and match with any package that matches that regular expression.
+      This may lead Chef Infra Client to install one or more packages with names that match that regular expression.
 
-        In this example, `anchor_package_regex true` prevents the apt_package resource from installing matching packages if it can't find the `lua5.3` package.
+      In this example, `anchor_package_regex true` prevents the apt_package resource from installing matching packages if it can't find the `lua5.3` package.
 
-        ```ruby
-        apt_package 'lua5.3' do
-          version '5.3.3-1.1ubuntu2'
-          anchor_package_regex true
-        end
-        ```
+      ```ruby
+      apt_package 'lua5.3' do
+        version '5.3.3-1.1ubuntu2'
+        anchor_package_regex true
+      end
+      ```
       DOC
 
       description "Use the **apt_package** resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system."
@@ -96,7 +101,7 @@ class Chef
         default: false
 
       property :environment, Hash,
-        introduced: "18.8",
+        introduced: "19.0",
         description: "A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} to be set before running the command.",
         default: {}, desired_state: false
     end

data/lib/chef/resource/apt_preference.rb

@@ -1,6 +1,6 @@
 #
 # Author:: Tim Smith (<tsmith@chef.io>)
-# Copyright:: Copyright (c) Chef Software Inc.
+# Copyright:: Copyright (c) 2009-2026 Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -22,39 +22,40 @@ class Chef
   class Resource
     class AptPreference < Chef::Resource
 
-      provides(:apt_preference) { true }
+      provides(:apt_preference, target_mode: true) { true }
+      target_mode support: :full
 
       description "Use the **apt_preference** resource to create APT [preference files](https://wiki.debian.org/AptPreferences). Preference files are used to control which package versions and sources are prioritized during installation."
       introduced "13.3"
       examples <<~DOC
-        **Pin libmysqlclient16 to a version 5.1.49-3**:
+      **Pin libmysqlclient16 to a version 5.1.49-3**:
 
-        ```ruby
-        apt_preference 'libmysqlclient16' do
-          pin          'version 5.1.49-3'
-          pin_priority '700'
-        end
-        ```
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        pin          'version 5.1.49-3'
+        pin_priority '700'
+      end
+      ```
 
-        Note: The `pin_priority` of `700` ensures that this version will be preferred over any other available versions.
+      Note: The `pin_priority` of `700` ensures that this version will be preferred over any other available versions.
 
-        **Unpin a libmysqlclient16**:
+      **Unpin a libmysqlclient16**:
 
-        ```ruby
-        apt_preference 'libmysqlclient16' do
-          action :remove
-        end
-        ```
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        action :remove
+      end
+      ```
 
-        **Pin all packages to prefer the packages.dotdeb.org repository**:
+      **Pin all packages to prefer the packages.dotdeb.org repository**:
 
-        ```ruby
-        apt_preference 'dotdeb' do
-          glob         '*'
-          pin          'origin packages.dotdeb.org'
-          pin_priority '700'
-        end
-        ```
+      ```ruby
+      apt_preference 'dotdeb' do
+        glob         '*'
+        pin          'origin packages.dotdeb.org'
+        pin_priority '700'
+      end
+      ```
       DOC
 
       property :package_name, String,