From aef39bb741c3878bb8b5b2e50eeb909342e9933f Mon Sep 17 00:00:00 2001 From: John Keiser Date: Wed, 3 Sep 2014 19:09:18 -0700 Subject: Add many comments to DataHandler and FileSystem classes --- .../chef_fs/data_handler/client_data_handler.rb | 2 +- .../chef_fs/data_handler/container_data_handler.rb | 2 +- .../chef_fs/data_handler/cookbook_data_handler.rb | 2 +- .../data_handler/data_bag_item_data_handler.rb | 2 +- lib/chef/chef_fs/data_handler/data_handler_base.rb | 78 +++++++++++++++++++++- .../data_handler/environment_data_handler.rb | 2 +- .../chef_fs/data_handler/group_data_handler.rb | 2 +- lib/chef/chef_fs/data_handler/node_data_handler.rb | 2 +- .../data_handler/organization_data_handler.rb | 2 +- lib/chef/chef_fs/data_handler/role_data_handler.rb | 2 +- lib/chef/chef_fs/data_handler/user_data_handler.rb | 2 +- .../chef_repository_file_system_root_dir.rb | 28 +++++++- .../chef_fs/file_system/chef_server_root_dir.rb | 22 ++++++ .../file_system/organization_invites_entry.rb | 5 +- .../file_system/organization_members_entry.rb | 5 +- lib/chef/chef_fs/parallelizer.rb | 2 - 16 files changed, 138 insertions(+), 22 deletions(-) (limited to 'lib/chef') diff --git a/lib/chef/chef_fs/data_handler/client_data_handler.rb b/lib/chef/chef_fs/data_handler/client_data_handler.rb index 4b6b8f5c79..d81f35e861 100644 --- a/lib/chef/chef_fs/data_handler/client_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/client_data_handler.rb @@ -22,7 +22,7 @@ class Chef result end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/container_data_handler.rb b/lib/chef/chef_fs/data_handler/container_data_handler.rb index 8b108bcf73..980453cbab 100644 --- a/lib/chef/chef_fs/data_handler/container_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/container_data_handler.rb @@ -11,7 +11,7 @@ class Chef }) end - def preserve_key(key) + def preserve_key?(key) return key == 'containername' end diff --git a/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb b/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb index d2e2a3ef6c..56b7e0b765 100644 --- a/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/cookbook_data_handler.rb @@ -23,7 +23,7 @@ class Chef }) end - def preserve_key(key) + def preserve_key?(key) return key == 'cookbook_name' || key == 'version' end diff --git a/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb b/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb index 240a42756d..1306922081 100644 --- a/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/data_bag_item_data_handler.rb @@ -34,7 +34,7 @@ class Chef normalize_for_post(data_bag_item, entry) end - def preserve_key(key) + def preserve_key?(key) return key == 'id' end diff --git a/lib/chef/chef_fs/data_handler/data_handler_base.rb b/lib/chef/chef_fs/data_handler/data_handler_base.rb index a9bbc0bf1b..a3dc92405c 100644 --- a/lib/chef/chef_fs/data_handler/data_handler_base.rb +++ b/lib/chef/chef_fs/data_handler/data_handler_base.rb @@ -1,17 +1,32 @@ class Chef module ChefFS module DataHandler + # + # The base class for all *DataHandlers. + # + # DataHandlers' job is to know the innards of Chef objects and manipulate + # JSON for them, adding defaults and formatting them. + # class DataHandlerBase + # + # Remove all default values from a Chef object's JSON so that the only + # thing you see are the values that have been explicitly set. + # Achieves this by calling normalize({}, entry) to get the list of + # defaults, and subtracting anything that is the same. + # def minimize(object, entry) default_object = default(entry) object.each_pair do |key, value| - if default_object[key] == value && !preserve_key(key) + if default_object[key] == value && !preserve_key?(key) object.delete(key) end end object end + # + # Takes a name like blah.json and removes the .json from it. + # def remove_dot_json(name) if name.length < 5 || name[-5,5] != ".json" raise "Invalid name #{path}: must end in .json" @@ -19,14 +34,34 @@ class Chef name[0,name.length-5] end - def preserve_key(key) + # + # Return true if minimize() should preserve a key even if it is the same + # as the default. Often used for ids and names. + # + def preserve_key?(key) false end + # + # Get the default value for an entry. Calls normalize({}, entry). + # def default(entry) normalize({}, entry) end + # + # Utility function to help subclasses do normalize(). Pass in a hash + # and a list of keys with defaults, and normalize will: + # + # 1. Fill in the defaults + # 2. Put the actual values in the order of the defaults + # 3. Move any other values to the end + # + # == Example + # + # normalize_hash({x: 100, c: 2, a: 1}, { a: 10, b: 20, c: 30}) + # -> { a: 1, b: 20, c: 2, x: 100} + # def normalize_hash(object, defaults) # Make a normalized result in the specified order for diffing result = {} @@ -39,14 +74,25 @@ class Chef result end + # Specialized function to normalize an object before POSTing it, since + # some object types want slightly different values on POST. + # If not overridden, this just calls normalize() def normalize_for_post(object, entry) normalize(object, entry) end + # Specialized function to normalize an object before PUTing it, since + # some object types want slightly different values on PUT. + # If not overridden, this just calls normalize(). def normalize_for_put(object, entry) normalize(object, entry) end + # + # normalize a run list (an array of run list items). + # Leaves recipe[name] and role[name] alone, and translates + # name to recipe[name]. Then calls uniq on the result. + # def normalize_run_list(run_list) run_list.map{|item| case item.to_s @@ -60,22 +106,46 @@ class Chef }.uniq end + # + # Bring in an instance of this object from Ruby. (Like roles/x.rb) + # def from_ruby(ruby) chef_class.from_file(ruby).to_hash end + # + # Turn a JSON hash into a bona fide Chef object (like Chef::Node). + # def chef_object(object) chef_class.json_create(object) end + # + # Write out the Ruby file for this instance. (Like roles/x.rb) + # def to_ruby(object) raise NotImplementedError end + # + # Get the class for instances of this type. Must be overridden. + # def chef_class raise NotImplementedError end + # + # Helper to write out a Ruby file for a JSON hash. Writes out only + # the keys specified in "keys"; anything else must be emitted by the + # caller. + # + # == Example + # + # to_ruby_keys({"name" => "foo", "environment" => "desert", "foo": "bar"}, [ "name", "environment" ]) + # -> + # 'name "foo" + # environment "desert"' + # def to_ruby_keys(object, keys) result = '' keys.each do |key| @@ -115,6 +185,10 @@ class Chef result end + # + # Verify that the JSON hash for this type has a key that matches its name. + # Calls the on_error block with the error, if there is one. + # def verify_integrity(object, entry, &on_error) base_name = remove_dot_json(entry.name) if object['name'] != base_name diff --git a/lib/chef/chef_fs/data_handler/environment_data_handler.rb b/lib/chef/chef_fs/data_handler/environment_data_handler.rb index 9da10ebfa5..5105f2ac49 100644 --- a/lib/chef/chef_fs/data_handler/environment_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/environment_data_handler.rb @@ -17,7 +17,7 @@ class Chef }) end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/group_data_handler.rb b/lib/chef/chef_fs/data_handler/group_data_handler.rb index 619822fe70..4d1b10f321 100644 --- a/lib/chef/chef_fs/data_handler/group_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/group_data_handler.rb @@ -36,7 +36,7 @@ class Chef result end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/node_data_handler.rb b/lib/chef/chef_fs/data_handler/node_data_handler.rb index f2c97c734f..04faa527f0 100644 --- a/lib/chef/chef_fs/data_handler/node_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/node_data_handler.rb @@ -21,7 +21,7 @@ class Chef result end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/organization_data_handler.rb b/lib/chef/chef_fs/data_handler/organization_data_handler.rb index 1f2f9ffaf5..da911c08f0 100644 --- a/lib/chef/chef_fs/data_handler/organization_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/organization_data_handler.rb @@ -15,7 +15,7 @@ class Chef result end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/role_data_handler.rb b/lib/chef/chef_fs/data_handler/role_data_handler.rb index bc1c076280..21c3013e9f 100644 --- a/lib/chef/chef_fs/data_handler/role_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/role_data_handler.rb @@ -23,7 +23,7 @@ class Chef result end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/data_handler/user_data_handler.rb b/lib/chef/chef_fs/data_handler/user_data_handler.rb index 99a247f2db..2b50ce38d8 100644 --- a/lib/chef/chef_fs/data_handler/user_data_handler.rb +++ b/lib/chef/chef_fs/data_handler/user_data_handler.rb @@ -17,7 +17,7 @@ class Chef }) end - def preserve_key(key) + def preserve_key?(key) return key == 'name' end diff --git a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb index 14f3e8413b..1e180a8f57 100644 --- a/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb +++ b/lib/chef/chef_fs/file_system/chef_repository_file_system_root_dir.rb @@ -33,7 +33,22 @@ require 'chef/chef_fs/data_handler/container_data_handler' class Chef module ChefFS module FileSystem + # + # Represents the root of a local Chef repository, with directories for + # nodes, cookbooks, roles, etc. under it. + # class ChefRepositoryFileSystemRootDir < BaseFSDir + # + # Create a new Chef Repository File System root. + # + # == Parameters + # - child_paths - a hash of child paths, e.g.: + # "nodes" => [ '/var/nodes', '/home/jkeiser/nodes' ], + # "roles" => [ '/var/roles' ], + # ... + # - root_paths - an array of paths representing the top level, where + # org.json, members.json, and invites.json will be stored. + # def initialize(child_paths, root_paths=nil) super("", nil) @child_paths = child_paths @@ -67,7 +82,6 @@ class Chef def create_child(name, file_contents = nil) if file_contents - d = root_dir child = root_dir.create_child(name, file_contents) else child_paths[name].each do |path| @@ -86,7 +100,7 @@ class Chef nil end - # Used to print out the filesystem + # Used to print out a human-readable file system description def fs_description repo_paths = root_paths || [ File.dirname(child_paths['cookbooks'][0]) ] result = "repository at #{repo_paths.join(', ')}\n" @@ -105,6 +119,10 @@ class Chef private + # + # A FileSystemEntry representing the root path where invites.json, + # members.json and org.json may be found. + # def root_dir MultiplexedDir.new(root_paths.select { |path| File.exists?(path) }.map do |path| dir = ChefRepositoryFileSystemEntry.new(name, parent, path) @@ -113,6 +131,12 @@ class Chef end) end + # + # Create a child entry of the appropriate type: + # cookbooks, data_bags, acls, etc. All will be multiplexed (i.e. if + # you have multiple paths for cookbooks, the multiplexed dir will grab + # cookbooks from all of them when you list or grab them). + # def make_child_entry(name) paths = child_paths[name].select do |path| File.exists?(path) diff --git a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb index 069a2e29fa..755fd5dca3 100644 --- a/lib/chef/chef_fs/file_system/chef_server_root_dir.rb +++ b/lib/chef/chef_fs/file_system/chef_server_root_dir.rb @@ -36,7 +36,29 @@ require 'chef/chef_fs/data_handler/container_data_handler' class Chef module ChefFS module FileSystem + # + # Represents the root of a Chef server (or organization), under which + # nodes, roles, cookbooks, etc. can be found. + # class ChefServerRootDir < BaseFSDir + # + # Create a new Chef server root. + # + # == Parameters + # + # - root_name - a friendly name for the root, for printing--like "remote" or "chef_central". + # - chef_config - a hash with options that look suspiciously like Chef::Config, including the + # following keys: + # - :chef_server_url - the URL to the Chef server or top of the organization + # - :node_name - the username to authenticate to the Chef server with + # - :client_key - the private key for the user for authentication + # - :environment - the environment in which you are presently working + # - :repo_mode - the repository mode, :hosted_everything, :everything or :static. + # This determines the set of subdirectories the Chef server + # will offer up. + # - options - other options: + # - :cookbook_version - when cookbooks are retrieved, grab this version for them. + # def initialize(root_name, chef_config, options = {}) super("", nil) @chef_server_url = chef_config[:chef_server_url] diff --git a/lib/chef/chef_fs/file_system/organization_invites_entry.rb b/lib/chef/chef_fs/file_system/organization_invites_entry.rb index a83e058b77..cb26326050 100644 --- a/lib/chef/chef_fs/file_system/organization_invites_entry.rb +++ b/lib/chef/chef_fs/file_system/organization_invites_entry.rb @@ -5,10 +5,9 @@ class Chef module ChefFS module FileSystem # /organizations/NAME/invitations.json - # Represents the actual data at - # read: + # read data from: # - GET /organizations/NAME/association_requests - # write: + # write data to: # - remove from list: DELETE /organizations/NAME/association_requests/id # - add to list: POST /organizations/NAME/association_requests class OrganizationInvitesEntry < RestListEntry diff --git a/lib/chef/chef_fs/file_system/organization_members_entry.rb b/lib/chef/chef_fs/file_system/organization_members_entry.rb index c1151413f5..eb524d5ea2 100644 --- a/lib/chef/chef_fs/file_system/organization_members_entry.rb +++ b/lib/chef/chef_fs/file_system/organization_members_entry.rb @@ -5,10 +5,9 @@ class Chef module ChefFS module FileSystem # /organizations/NAME/members.json - # Represents the actual data at - # read: + # reads data from: # - GET /organizations/NAME/users - # write: + # writes data to: # - remove from list: DELETE /organizations/NAME/users/name # - add to list: POST /organizations/NAME/users/name class OrganizationMembersEntry < RestListEntry diff --git a/lib/chef/chef_fs/parallelizer.rb b/lib/chef/chef_fs/parallelizer.rb index f29a2deae7..116a626869 100644 --- a/lib/chef/chef_fs/parallelizer.rb +++ b/lib/chef/chef_fs/parallelizer.rb @@ -53,7 +53,6 @@ class Chef end def resize(to_threads, wait = true, timeout = nil) - to_threads = 0 if to_threads < num_threads threads_to_stop = @threads[to_threads..num_threads-1] @threads = @threads.slice(0, to_threads) @@ -90,7 +89,6 @@ class Chef begin while !@stop_thread[Thread.current] begin - puts "Got a task!" task = @tasks.pop task.call rescue -- cgit v1.2.1