chef-api 0.2.0

data/lib/chef-api/schema.rb

@@ -0,0 +1,112 @@
+module ChefAPI
+  #
+  # A wrapper class that describes a remote schema (such as the Chef Server
+  # API layer), with validation and other magic spinkled on top.
+  #
+  class Schema
+
+    #
+    # The full list of attributes defined on this schema.
+    #
+    # @return [Hash]
+    #
+    attr_reader :attributes
+
+    attr_reader :ignored_attributes
+    attr_reader :transformations
+
+    #
+    # The list of defined validators for this schema.
+    #
+    # @return [Array]
+    #
+    attr_reader :validators
+
+    #
+    # Create a new schema and evaulte the block contents in a clean room.
+    #
+    def initialize(&block)
+      @attributes = {}
+      @ignored_attributes = {}
+      @transformations = {}
+      @validators = []
+
+      instance_eval(&block) if block
+
+      @attributes.freeze
+      @ignored_attributes.freeze
+      @transformations.freeze
+      @validators.freeze
+    end
+
+    #
+    # The defined primary key for this schema. If no primary key is given, it
+    # is assumed to be the first item in the list.
+    #
+    # @return [Symbol]
+    #
+    def primary_key
+      @primary_key ||= @attributes.first[0]
+    end
+
+    #
+    # DSL method for defining an attribute.
+    #
+    # @param [Symbol] key
+    #   the key to use
+    # @param [Hash] options
+    #   a list of options to create the attribute with
+    #
+    # @return [Symbol]
+    #   the attribute
+    #
+    def attribute(key, options = {})
+      if primary_key = options.delete(:primary)
+        @primary_key = key.to_sym
+      end
+
+      @attributes[key] = options.delete(:default)
+
+      # All remaining options are assumed to be validations
+      options.each do |validation, options|
+        if options
+          @validators << Validator.find(validation).new(key, options)
+        end
+      end
+
+      key
+    end
+
+    #
+    # Ignore an attribute. This is handy if you know there's an attribute that
+    # the remote server will return, but you don't want that information
+    # exposed to the user (or the data is sensitive).
+    #
+    # @param [Array<Symbol>] keys
+    #   the list of attributes to ignore
+    #
+    def ignore(*keys)
+      keys.each do |key|
+        @ignored_attributes[key.to_sym] = true
+      end
+    end
+
+    #
+    # Transform an attribute onto another.
+    #
+    # @example Transform the +:bacon+ attribute onto the +:ham+ attribute
+    #   transform :bacon, ham: true
+    #
+    # @example Transform an attribute with a complex transformation
+    #   transform :bacon, ham: ->(value) { value.split('__', 2).last }
+    #
+    # @param [Symbol] key
+    #   the attribute to transform
+    # @param [Hash] options
+    #   the key-value pair of the transformations to make
+    #
+    def transform(key, options = {})
+      @transformations[key.to_sym] = options
+    end
+  end
+end

data/lib/chef-api/util.rb

@@ -0,0 +1,119 @@
+module ChefAPI
+  module Util
+    extend self
+
+    #
+    # Covert the given CaMelCaSeD string to under_score. Graciously borrowed
+    # from http://stackoverflow.com/questions/1509915.
+    #
+    # @param [String] string
+    #   the string to use for transformation
+    #
+    # @return [String]
+    #
+    def underscore(string)
+      string
+        .to_s
+        .gsub(/::/, '/')
+        .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+        .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+        .tr('-', '_')
+        .downcase
+    end
+
+    #
+    # Convert an underscored string to it's camelcase equivalent constant.
+    #
+    # @param [String] string
+    #   the string to convert
+    #
+    # @return [String]
+    #
+    def camelize(string)
+      string
+        .to_s
+        .split('_')
+        .map { |e| e.capitalize }
+        .join
+    end
+
+    #
+    # Truncate the given string to a certain number of characters.
+    #
+    # @param [String] string
+    #   the string to truncate
+    # @param [Hash] options
+    #   the list of options (such as +length+)
+    #
+    def truncate(string, options = {})
+      length = options[:length] || 30
+
+      if string.length > length
+        string[0..length-3] + '...'
+      else
+        string
+      end
+    end
+
+    #
+    # "Safely" read the contents of a file on disk, catching any permission
+    # errors or not found errors and raising a nicer exception.
+    #
+    # @example Reading a file that does not exist
+    #   safe_read('/non-existent/file') #=> Error::FileNotFound
+    #
+    # @example Reading a file with improper permissions
+    #   safe_read('/bad-permissions') #=> Error::InsufficientFilePermissions
+    #
+    # @example Reading a regular file
+    #   safe_read('my-file.txt') #=> ["my-file", "..."]
+    #
+    # @param [String] path
+    #   the path to the file on disk
+    #
+    # @return [Array<String>]
+    #   A array where the first value is the basename of the file and the
+    #   second value is the literal contents from +File.read+.
+    #
+    def safe_read(path)
+      path     = File.expand_path(path)
+      name     = File.basename(path, '.*')
+      contents = File.read(path)
+
+      [name, contents]
+    rescue Errno::EACCES
+      raise Error::InsufficientFilePermissions.new(path: path)
+    rescue Errno::ENOENT
+      raise Error::FileNotFound.new(path: path)
+    end
+
+    #
+    # Quickly iterate over a collection using native Ruby threads, preserving
+    # the original order of elements and being all thread-safe and stuff.
+    #
+    # @example Parse a collection of JSON files
+    #
+    #   fast_collect(Dir['**/*.json']) do |item|
+    #     JSON.parse(File.read(item))
+    #   end
+    #
+    # @param [#each] collection
+    #   the collection to iterate
+    # @param [Proc] block
+    #   the block to evaluate (typically an expensive operation)
+    #
+    # @return [Array]
+    #   the result of the iteration
+    #
+    def fast_collect(collection, &block)
+      collection.map do |item|
+        Thread.new do
+          Thread.current[:result] = block.call(item)
+        end
+      end.collect do |thread|
+        thread.join
+        thread[:result]
+      end
+    end
+  end
+end

data/lib/chef-api/validator.rb

@@ -0,0 +1,16 @@
+module ChefAPI
+  module Validator
+    autoload :Base,       'chef-api/validators/base'
+    autoload :Required,   'chef-api/validators/required'
+    autoload :Type,       'chef-api/validators/type'
+
+    #
+    # Find a validator by the given key.
+    #
+    def self.find(key)
+      const_get(Util.camelize(key))
+    rescue NameError
+      raise Error::InvalidValidator.new(key: key)
+    end
+  end
+end

data/lib/chef-api/validators/base.rb

@@ -0,0 +1,82 @@
+module ChefAPI
+  class Validator::Base
+    #
+    # @return [Symbol]
+    #   the attribute to apply this validation on
+    #
+    attr_reader :attribute
+
+    #
+    # @return [Hash]
+    #   the hash of additional arguments passed in
+    #
+    attr_reader :options
+
+    #
+    # Create anew validator.
+    #
+    # @param [Symbol] attribute
+    #   the attribute to apply this validation on
+    # @param [Hash] options
+    #   the list of options passed in
+    #
+    def initialize(attribute, options = {})
+      @attribute = attribute
+      @options   = options.is_a?(Hash) ? options : {}
+    end
+
+    #
+    # Just in case someone forgets to define a key, this will return the
+    # class's underscored name without "validator" as a symbol.
+    #
+    # @example
+    #   FooValidator.new.key #=> :foo
+    #
+    # @return [Symbol]
+    #
+    def key
+      name = self.class.name.split('::').last
+      Util.underscore(name).to_sym
+    end
+
+    #
+    # Execute the validations. This is an abstract class and must be
+    # overridden in custom validators.
+    #
+    # @param [Resource::Base::Base] resource
+    #   the parent resource to validate against
+    #
+    def validate(resource)
+      raise Error::AbstractMethod.new(method: 'Validators::Base#validate')
+    end
+
+    #
+    # The string representation of this validation.
+    #
+    # @return [String]
+    #
+    def to_s
+      "#<#{classname}>"
+    end
+
+    #
+    # The string representation of this validation.
+    #
+    # @return [String]
+    #
+    def inspect
+      "#<#{classname} :#{attribute}>"
+    end
+
+    private
+
+    #
+    # The class name for this validator.
+    #
+    # @return [String]
+    #
+    def classname
+      @classname ||= self.class.name.split('::')[1..-1].join('::')
+    end
+  end
+end

data/lib/chef-api/validators/required.rb

@@ -0,0 +1,11 @@
+module ChefAPI
+  class Validator::Required < Validator::Base
+    def validate(resource)
+      value = resource._attributes[attribute]
+
+      if value.to_s.strip.empty?
+        resource.errors.add(attribute, 'must be present')
+      end
+    end
+  end
+end

data/lib/chef-api/validators/type.rb

@@ -0,0 +1,23 @@
+module ChefAPI
+  class Validator::Type < Validator::Base
+    attr_reader :types
+
+    #
+    # Overload the super method to capture the type attribute in the options
+    # hash.
+    #
+    def initialize(attribute, type)
+      super
+      @types = Array(type)
+    end
+
+    def validate(resource)
+      value = resource._attributes[attribute]
+
+      if value && !types.any? { |type| value.is_a?(type) }
+        short_name = type.to_s.split('::').last
+        resource.errors.add(attribute, "must be a kind of #{short_name}")
+      end
+    end
+  end
+end

data/lib/chef-api/version.rb

@@ -0,0 +1,3 @@
+module ChefAPI
+  VERSION = '0.2.0'
+end

data/lib/chef-api.rb

@@ -0,0 +1,76 @@
+require 'json'
+require 'pathname'
+require 'chef-api/version'
+
+module ChefAPI
+  autoload :Boolean,         'chef-api/boolean'
+  autoload :Configurable,    'chef-api/configurable'
+  autoload :Connection,      'chef-api/connection'
+  autoload :Defaults,        'chef-api/defaults'
+  autoload :Error,           'chef-api/errors'
+  autoload :ErrorCollection, 'chef-api/error_collection'
+  autoload :Logger,          'chef-api/logger'
+  autoload :Resource,        'chef-api/resource'
+  autoload :Schema,          'chef-api/schema'
+  autoload :Util,            'chef-api/util'
+  autoload :Validator,       'chef-api/validator'
+
+  #
+  # @todo Document this and why it's important
+  #
+  UNSET = Object.new
+
+  class << self
+    include ChefAPI::Configurable
+
+    #
+    # The source root of the ChefAPI gem. This is useful when requiring files
+    # that are relative to the root of the project.
+    #
+    # @return [Pathname]
+    #
+    def root
+      @root ||= Pathname.new(File.expand_path('../../', __FILE__))
+    end
+
+    #
+    # API connection object based off the configured options in {Configurable}.
+    #
+    # @return [ChefAPI::Connection]
+    #
+    def connection
+      unless @connection && @connection.same_options?(options)
+        @connection = ChefAPI::Connection.new(options)
+      end
+
+      @connection
+    end
+
+    #
+    # Delegate all methods to the connection object, essentially making the
+    # module object behave like a {Connection}.
+    #
+    def method_missing(m, *args, &block)
+      if connection.respond_to?(m)
+        connection.send(m, *args, &block)
+      else
+        super
+      end
+    end
+
+    #
+    # Delegating +respond_to+ to the {Connection}.
+    #
+    def respond_to_missing?(m, include_private = false)
+      connection.respond_to?(m) || super
+    end
+  end
+end
+
+require 'i18n'
+I18n.enforce_available_locales = false
+I18n.load_path << Dir[ChefAPI.root.join('locales', '*.yml').to_s]
+
+# Load the initial default values
+ChefAPI.setup
+

data/locales/en.yml

@@ -0,0 +1,89 @@
+en:
+  chef_api:
+    errors:
+      abstract_method: >
+        `%{method}` is an abstract method. You must override this method in
+        your subclass with the proper implementation and logic. For more
+        information, please see the inline documentation for %{method}. If you
+        are not a developer, this is most likely a bug in the ChefAPI gem.
+        Please file a bug report at
+        https://github.com/sethvargo/chef-api/issues/new and include the
+        command(s) you ran to arrive at this error.
+      cannot_regenerate_key: >
+        You called `regenerate_key` on a client that does not exist on the
+        remote Chef Server. You can only regenerate a private key for a client
+        that is persisted. Try saving this record this client before
+        regenerating the private key.
+      file_not_found: >
+        I could not find a file at `%{path}`. Please make sure you have typed
+        the path correctly and that the resource at `%{path}` does actually
+        exist.
+      http_bad_request: >
+        The Chef Server did not understand the request because it was malformed.
+        The Chef Server returned this message:
+
+            %{message}
+      http_forbidden_request: >
+        The Chef Server actively refused to fulfill the request. The Chef Server
+        returned this message:
+
+            %{message}
+      http_method_not_allowed: >
+        That HTTP method is not allowed on this URL. The Chef Server returned
+        this message:
+
+            %{message}
+      http_not_acceptable: >
+        The Chef Server identified this request as unacceptable. This usually
+        means you have not specified the correct Accept or Content-Type headers
+        on the request object. The Chef Server returned this message:
+
+            %{message}
+      http_not_found: >
+        The requested URL does not exist on the Chef Server. The Chef Server
+        returned this message:
+
+            %{message}
+      http_server_unavailable: >
+        The Chef Server is currently unavailable or is not currently accepting
+        client connections. Please ensure the server is accessible via ping
+        or telnet on your local network. If this error persists, please contact
+        your network administrator.
+      http_unauthorized_request: >
+        The Chef Server requires authorization. Please ensure you have specified
+        the correct client name and private key. If this error continues, please
+        verify the given client has the proper permissions on the Chef Server.
+        The Chef Server returned this message:
+
+            %{message}
+      insufficient_file_permissions: >
+        I cannot read the file at `%{path}` because the permissions on the file
+        do not permit it. Please ensure the file has the correct permissions and
+        that this Ruby process is running as a user with access to `%{path}`.
+      invalid_resource: >
+        There were errors saving your resource: %{errors}
+      invalid_validator: >
+        `%{key}` is not a valid validator. Please make sure it is spelled
+        correctly and that the constant is properly defined. If you are using
+        a custom validator, please ensure the validator extends
+        ChefAPI::Validator::Base and is a subclass of ChefAPI::Validator.
+      missing_url_parameter: >
+        The required URL parameter `%{param}' was not present. Please specify
+        `%{param}' as an option, like Resource.new(id, %{param}: 'value').
+      not_a_directory: >
+        The given path `%{path}' is not a directory. Please make sure you have
+        passed the path to a directory on disk.
+      resource_already_exists: >
+        The %{type} `%{id}` already exists on the Chef Server. Each
+        %{type} must have a unique identifier and the Chef Server indicated
+        this %{type} already exists. If you are trying to update the %{type},
+        consider using the `update` method instead.
+      resource_not_found: >
+        There is no %{type} with an id of `%{id}` on the Chef Server. If you
+        are updating the %{type}, please make sure the %{type} exists and has
+        the correct Chef identifier (primary key).
+      resource_not_mutable: >
+        The %{type} `%{id}` is not mutable. It may be locked by the remote
+        Chef Server, or the Chef Server may not permit modifying the resource.
+      unknown_attribute: >
+        `%{attribute}` is not a valid attribute

data/spec/integration/resources/client_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+module ChefAPI
+  describe Resource::Client do
+    it_behaves_like 'a Chef API resource', :client,
+      update: { validator: true }
+  end
+end

data/spec/integration/resources/environment_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+module ChefAPI
+  describe Resource::Environment do
+    it_behaves_like 'a Chef API resource', :environment,
+      update: { description: 'This is the new description' }
+  end
+end

data/spec/integration/resources/node_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+module ChefAPI
+  describe Resource::Node do
+    it_behaves_like 'a Chef API resource', :node,
+      update: { chef_environment: 'my_environment' }
+  end
+end

data/spec/integration/resources/role_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+module ChefAPI
+  describe Resource::Role do
+    it_behaves_like 'a Chef API resource', :role,
+      update: { description: 'This is the new description' }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+require 'chef-api'
+
+RSpec.configure do |config|
+  # Chef Server
+  require 'support/chef_server'
+  config.include(RSpec::ChefServer::DSL)
+
+  # Shared Examples
+  Dir[ChefAPI.root.join('spec/support/shared/**/*.rb')].each { |file| require file }
+
+  # Basic configuraiton
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run(:focus)
+
+  #
+  config.before(:each) do
+    ChefAPI::Logger.level = :fatal
+  end
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end