chef 0.9.8.rc.0 → 0.9.8

data/README.rdoc

@@ -1,6 +1,6 @@
 = Chef
 
-= DESCRIPTION:
+== DESCRIPTION:
 
 Chef is a configuration management tool designed to bring automation to your entire infrastructure. 
 
@@ -12,7 +12,7 @@ This README focuses on developers who want to modify Chef source code. For users
 
 * http://wiki.opscode.com/display/chef/Installing+Chef+from+HEAD
 
-= DEVELOPMENT:
+== DEVELOPMENT:
 
 Before working on the code, if you plan to contribute your changes, you need to read the Opscode Contributing document.
 
@@ -24,84 +24,120 @@ You will also need to set up the repository with the appropriate branches. We do
 
 Once your repository is set up, you can start working on the code. We do use BDD/TDD with RSpec and Cucumber, so you'll need to get a development environment running.
 
-= ENVIRONMENT:
+== ENVIRONMENT:
 
 In order to have a development environment where changes to the Chef code can be tested, we'll need to install a few things after setting up the Git repository.
 
-== Requirements:
+=== Non-Gem Dependencies
 
 Install these via your platform's preferred method; for example apt, yum, ports, emerge, etc.
 
-* Git
-* CouchDB
-* libxml2 development package (for webrat)
-* libxslt develoment package (for webrat)
-
-Install the following RubyGems.
+* Git[http://git-scm.com/]
+* Erlang/OTP[http://www.erlang.org/]
+* CouchDB[http://couchdb.apache.org/]
+* RabbitMQ[http://www.rabbitmq.com/]
+* GCC and C Standard Libraries, header files, etc. (i.e., build-essential on debian/ubuntu)
+* Ruby development package
+* libxml2 development package
 
+=== Runtime Rubygem Dependencies
+==== Chef Client and Solo
 * ohai
-* rake
-* rspec
-* cucumber
-* webrat
+* bunny
+* erubis
+* extlib
+* highline
+* json (1.4.2)
+* mixlib-authentication
+* mixlib-cli
+* mixlib-config
+* mixlib-log
+* moneta
+* rest-client
+* uuidtools
 * merb-core
-* roman-merb_cucumber
-* thin
 
-Ohai is also by Opscode and available on GitHub, http://github.com/opscode/ohai/tree/master.
+==== Chef Server, WebUI and Solr
+All of the above, plus the following:
+* coderay
+* haml
+* libxml-ruby
+* merb-assets
+* merb-core
+* merb-haml
+* merb-helpers
+* merb-param-protection
+* ruby-openid
+* thin
 
-roman-merb_cucumber is available from GitHub:
+=== Development Rubygem Dependencies
+* rake[http://rake.rubyforge.org/]
+* rspec[http://rspec.info/]
+* cucumber[http://cukes.info/]
 
-  gem install --source http://gems.github.com/ roman-merb_cucumber
+Ohai is also by Opscode and available on GitHub, http://github.com/opscode/ohai/tree/master.
 
 == Starting the Environment:
 
-Once everything is installed, run the dev:features rake task. Since the features do integration testing, root access is required.
+=== On Mac OS X:
+For ease of debugging, Chef includes a script to start each of the required
+daemons in a separate Terminal.app tab via applescript:
 
-  sudo rake dev:features
+  scripts/mac-dev-start features
 
-The dev:features task:
+=== On Linux and BSD
 
-* Starts CouchDB on port 5984.
-* Starts rabbitmq
-* Starts solr
-* Starts chef-indexer.
-* Starts chef-server on port 4000
+run the dev:features rake task. You may need to run it as root depending on how
+your system is configured.
 
+  rake dev:features
+
+=== Daemons
+After starting the environment, you should have the following processes running:
+* couchdb             listening on port 5984
+* rabbitmq            listening on port 5672
+* solr                listening on port 8983
+* chef-solr-indexer   connected as a client to rabbitmq
+* chef-server         listening on port 4000
+* chef-server-webui   listening on port 4040
 
 You'll know its running when you see:
 
-~ Activating slice 'ChefServerApi' ...
-merb : worker (port 4000) ~ Starting Thin at port 4000
-merb : worker (port 4000) ~ Using Thin adapter on host 0.0.0.0 and port 4000.
-merb : worker (port 4000) ~ Successfully bound to port 4000
+    merb : chef-server (api) : worker (port 4000) ~ Starting Thin at port 4000
+    merb : chef-server (api) : worker (port 4000) ~ Using Thin adapter on host 0.0.0.0 and port 4000.
+    merb : chef-server (api) : worker (port 4000) ~ Successfully bound to port 4000
 
 You'll want to leave this terminal running the dev environment.
 
-== Web Interface:
+=== Web Interface:
 
-With the dev environment running, you can now access the web interface via http://localhost:4000/.
+With the dev environment running, you can now access the web interface via http://localhost:4040/.
 
 == Spec testing:
 
-We use RSpec for unit/spec tests.
+We use RSpec for unit/spec tests. It is not necessary to start the development
+environment to run the specs--they are completely standalone.
 
   rake spec
 
-This doesn't actually use the development environment, because it does the testing on all the Chef internals. For integration/usage testing, we use Cucumber features.
-
 == Integration testing:
 
-We test integration with Cucumber. The available feature tests are rake tasks:
+We test integration with Cucumber. To run the full suite, run the rake task:
+
+  rake features
+
+Subsets of the integration tests can be run with the various tasks in the
+features namespace. To see the full list, run
+
+  rake -T
+
+To run individual feature tests, you can take advantage of cucumber's tagging
+support. Tag the feature you wish to run (tags are denoted with a leading `@'
+sign), then use the cucumber command:
 
-  rake features                            # Run Features with Cucumber
-  rake features:api                        # Run Features with Cucumber
-  rake features:client                     # Run Features with Cucumber
-  rake features:provider:package:macports  # Run Features with Cucumber
-  rake features:provider:remote_file       # Run Features with Cucumber
-  rake features:search                     # Run Features with Cucumber
+  cucumber -t @my_tag
 
-= LINKS:
+== LINKS:
 
 Source:
 

data/lib/chef/checksum.rb

@@ -18,10 +18,10 @@
 require 'chef/log'
 require 'uuidtools'
 
-
-# Checksum for an individual file; e.g., used for sandbox/cookbook uploading
-# to track which files the system already manages.
 class Chef
+  # == Chef::Checksum
+  # Checksum for an individual file; e.g., used for sandbox/cookbook uploading
+  # to track which files the system already manages.
   class Checksum
     attr_accessor :checksum, :create_time
     attr_accessor :couchdb_id, :couchdb_rev
@@ -42,7 +42,10 @@ class Chef
       }
     }
     
-    # Creates a new Chef::Checksum object.  
+    # Creates a new Chef::Checksum object.
+    # === Arguments
+    # checksum::: the MD5 content hash of the file
+    # couchdb::: An instance of Chef::CouchDB
     #
     # === Returns
     # object<Chef::Checksum>:: Duh. :)

data/lib/chef/client.rb

@@ -36,12 +36,16 @@ require 'chef/version'
 require 'ohai'
 
 class Chef
+  # == Chef::Client
+  # The main object in a Chef run. Preps a Chef::Node and Chef::RunContext,
+  # syncs cookbooks if necessary, and triggers convergence.
   class Client
     attr_accessor :node
     attr_accessor :ohai
     attr_accessor :rest
     attr_accessor :runner
 
+    #--
     # TODO: timh/cw: 5-19-2010: json_attribs should be moved to RunContext?
     attr_reader :json_attribs
 

data/lib/chef/cookbook/cookbook_collection.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Tim Hinderliter (<tim@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
@@ -19,15 +19,16 @@
 
 require 'extlib'
 
-# This class is the consistent interface for a node to obtain its
-# cookbooks by name.
-#
-# This class is basically a glorified Hash, but since there are
-# several ways this cookbook information is collected,
-# (e.g. CookbookLoader for solo, hash of auto-vivified Cookbook
-# objects for lazily-loaded remote cookbooks), it gets transformed
-# into this.
 class Chef
+  # == Chef::CookbookCollection
+  # This class is the consistent interface for a node to obtain its
+  # cookbooks by name.
+  #
+  # This class is basically a glorified Hash, but since there are
+  # several ways this cookbook information is collected,
+  # (e.g. CookbookLoader for solo, hash of auto-vivified Cookbook
+  # objects for lazily-loaded remote cookbooks), it gets transformed
+  # into this.
   class CookbookCollection < Mash
 
     # The input is a mapping of cookbook name to CookbookVersion objects. We

data/lib/chef/cookbook/file_system_file_vendor.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Author:: Tim Hinderliter (<tim@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
@@ -19,15 +19,16 @@
 
 require 'chef/cookbook/file_vendor'
 
-# This FileVendor loads files from Chef::Config.cookbook_path. The
-# thing that's sort of janky about this FileVendor implementation is
-# that it basically takes only the cookbook's name from the manifest
-# and throws the rest away then re-builds the list of files on the
-# disk. This is due to the manifest not having the on-disk file
-# locations, since in the chef-client case, that information is
-# non-sensical.
 class Chef
   class Cookbook
+    # == Chef::Cookbook::FileSystemFileVendor
+    # This FileVendor loads files from Chef::Config.cookbook_path. The
+    # thing that's sort of janky about this FileVendor implementation is
+    # that it basically takes only the cookbook's name from the manifest
+    # and throws the rest away then re-builds the list of files on the
+    # disk. This is due to the manifest not having the on-disk file
+    # locations, since in the chef-client case, that information is
+    # non-sensical.
     class FileSystemFileVendor < FileVendor
       
       def initialize(manifest)

data/lib/chef/cookbook/file_vendor.rb

@@ -18,9 +18,10 @@
 #
 
 
-# This class handles fetching of cookbook files based on specificity.
 class Chef
   class Cookbook
+    # == Chef::Cookbook::FileVendor
+    # This class handles fetching of cookbook files based on specificity.
     class FileVendor
 
       def self.on_create(&block)

data/lib/chef/cookbook/metadata.rb

@@ -25,6 +25,9 @@ require 'chef/cookbook/metadata/version'
 
 class Chef
   class Cookbook
+    # == Chef::Cookbook::Metadata
+    # Chef::Cookbook::Metadata provides a convenient DSL for declaring metadata
+    # about Chef Cookbooks.
     class Metadata
 
       COMPARISON_FIELDS = [ :name, :description, :long_description, :maintainer,

data/lib/chef/cookbook/remote_file_vendor.rb

@@ -18,10 +18,11 @@
 
 require 'chef/cookbook/file_vendor'
 
-# This FileVendor loads files by either fetching them from the local cache, or
-# if not available, loading them from the remote server.
 class Chef
   class Cookbook
+    # == Chef::Cookbook::RemoteFileVendor
+    # This FileVendor loads files by either fetching them from the local cache, or
+    # if not available, loading them from the remote server.
     class RemoteFileVendor < FileVendor
       
       def initialize(manifest, rest, valid_cache_entries)

data/lib/chef/cookbook/syntax_check.rb

@@ -21,11 +21,16 @@ require 'chef/mixin/shell_out'
 
 class Chef
   class Cookbook
+    # == Chef::Cookbook::SyntaxCheck
+    # Encapsulates the process of validating the ruby syntax of files in Chef
+    # cookbooks.
     class SyntaxCheck
       include Chef::Mixin::ShellOut
 
       attr_reader :cookbook_path
 
+      # Creates a new SyntaxCheck given the +cookbook_name+ and a +cookbook_path+.
+      # If no +cookbook_path+ is given, +Chef::Config.cookbook_path+ is used.
       def self.for_cookbook(cookbook_name, cookbook_path=nil)
         cookbook_path ||= Chef::Config.cookbook_path
         unless cookbook_path
@@ -34,6 +39,9 @@ class Chef
         new(File.join(cookbook_path, cookbook_name.to_s))
       end
 
+      # Create a new SyntaxCheck object
+      # === Arguments
+      # cookbook_path::: the (on disk) path to the cookbook
       def initialize(cookbook_path)
         @cookbook_path = cookbook_path
       end

data/lib/chef/cookbook_site_streaming_uploader.rb

@@ -22,8 +22,12 @@ require 'net/http'
 require 'mixlib/authentication/signedheaderauth'
 require 'openssl'
 
-# inspired by from http://stanislavvitvitskiy.blogspot.com/2008/12/multipart-post-in-ruby.html
 class Chef
+  # == Chef::CookbookSiteStreamingUploader
+  # A streaming multipart HTTP upload implementation. Used to upload cookbooks
+  # (in tarball form) to http://cookbooks.opscode.com
+  #
+  # inspired by http://stanislavvitvitskiy.blogspot.com/2008/12/multipart-post-in-ruby.html
   class CookbookSiteStreamingUploader
 
     DefaultHeaders = { 'accept' => 'application/json', 'x-chef-version' => ::Chef::VERSION }

data/lib/chef/cookbook_version.rb

@@ -24,9 +24,15 @@ require 'chef/resource_definition_list'
 require 'chef/recipe'
 require 'chef/cookbook/file_vendor'
 
-# TODO: timh/cw: 5-24-2010: mutators for files (e.g., recipe_filenames=,
-# recipe_filenames.insert) should dirty the manifest so it gets regenerated.
 class Chef
+  # == Chef::CookbookVersion
+  # CookbookVersion is a model object encapsulating the data about a Chef
+  # cookbook. Chef supports maintaining multiple versions of a cookbook on a
+  # single server; each version is represented by a distinct instance of this
+  # class.
+  #--
+  # TODO: timh/cw: 5-24-2010: mutators for files (e.g., recipe_filenames=,
+  # recipe_filenames.insert) should dirty the manifest so it gets regenerated.
   class CookbookVersion
     include Chef::IndexQueue::Indexable
 
@@ -228,23 +234,23 @@ class Chef
     # as well as describing cookbook metadata. The manifest follows a form
     # like the following:
     #
-    # {
-    #   :cookbook_name = "apache2",
-    #   :version = "1.0",
-    #   :name = "Apache 2"
-    #   :metadata = ???TODO: timh/cw: 5-24-2010: describe this format,
-    #
-    #   :files => [
-    #     {
-    #       :name => "afile.rb",
-    #       :path => "files/ubuntu-9.10/afile.rb",
-    #       :checksum => "2222",
-    #       :specificity => "ubuntu-9.10"
-    #     },
-    #   ],
-    #   :templates => [ manifest_record1, ... ],
-    #   ...
-    # }
+    #   {
+    #     :cookbook_name = "apache2",
+    #     :version = "1.0",
+    #     :name = "Apache 2"
+    #     :metadata = ???TODO: timh/cw: 5-24-2010: describe this format,
+    #   
+    #     :files => [
+    #       {
+    #         :name => "afile.rb",
+    #         :path => "files/ubuntu-9.10/afile.rb",
+    #         :checksum => "2222",
+    #         :specificity => "ubuntu-9.10"
+    #       },
+    #     ],
+    #     :templates => [ manifest_record1, ... ],
+    #     ...
+    #   }
     def manifest
       unless @manifest
         generate_manifest

data/lib/chef/exceptions.rb

@@ -16,6 +16,9 @@
 # limitations under the License.
 
 class Chef
+  # == Chef::Exceptions
+  # Chef's custom exceptions are all contained within the Chef::Exceptions
+  # namespace.
   class Exceptions
     class Application < RuntimeError; end
     class Cron < RuntimeError; end

data/lib/chef/file_access_control.rb

@@ -21,6 +21,7 @@ require 'chef/log'
 
 class Chef
 
+  # == Chef::FileAccessControl
   # FileAccessControl objects set the owner, group and mode of +file+ to
   # the values specified by a value object, usually a Chef::Resource.
   class FileAccessControl

data/lib/chef/handler.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0
@@ -18,6 +18,42 @@
 require 'forwardable'
 
 class Chef
+  # == Chef::Handler
+  # The base class for an Exception or Notification Handler. Create your own
+  # handler by subclassing Chef::Handler. When a Chef run fails with an
+  # uncaught Exception, Chef will set the +run_status+ on your handler and call
+  # +report+
+  #
+  # ===Example:
+  #
+  #   require 'net/smtp'
+  #
+  #   module MyOrg
+  #     class OhNoes < Chef::Handler
+  #
+  #       def report
+  #         # Create the email message
+  #         message  = "From: Your Name <your@mail.address>\n"
+  #         message << "To: Destination Address <someone@example.com>\n"
+  #         message << "Subject: Chef Run Failure\n"
+  #         message << "Date: #{Time.now.rfc2822}\n\n"
+  #
+  #         # The Node is available as +node+
+  #         message << "Chef run failed on #{node.name}\n"
+  #         # +run_status+ is a value object with all of the run status data
+  #         message << "#{run_status.formatted_exception}\n"
+  #         # Join the backtrace lines. Coerce to an array just in case.
+  #         message << Array(backtrace).join("\n")
+  #
+  #         # Send the email
+  #         Net::SMTP.start('your.smtp.server', 25) do |smtp|
+  #           smtp.send_message message, 'from@address', 'to@address'
+  #         end
+  #       end
+  #
+  #     end
+  #   end
+  #
   class Handler
 
     extend Forwardable