plow 0.1.0 → 1.0.0

data/lib/plow/dependencies.rb

@@ -0,0 +1,123 @@
+# encoding: UTF-8
+
+class Plow
+  # `Plow::Dependencies` is a class-methods-only **singleton** class that performs both strict
+  # parse-time dependency checking and simple, elegant run-time dependency warning.
+  #
+  # My preferred mental model is to consider software library dependencies as a snapshot in time.
+  # I also make the assumption, sometimes incorrectly, that a newer version of a software library
+  # is not always a better version.
+  #
+  # `Plow::Dependencies` automatically enforces a strict parse-time check for the
+  # `REQUIRED_RUBY_VERSION` on both application and development processes for the `Plow` library.
+  # (i.e. `bin/plow`, `rake`, `spec`, etc)  Because of this, I've ensured this file is
+  # syntactically compatible with Ruby 1.8.6 or higher.
+  #
+  # Currently, `Plow` does **not** enforce strict parse-time version checking on `DEVELOPMENT_GEMS`.
+  # In the future, I would like to experiment with using RubyGems and the `Kernel#gem` method to
+  # this end.  For now, each developer is responsible for ensuring the correct versions of their
+  # necessary development gems are located in the `$LOAD_PATH` on their system.
+  #
+  # When a gem is required, but a `LoadError` is raised, and rescued, `Plow::Dependencies` can be
+  # incorporated into the process to warn a developer of missing development features.  Even with a
+  # few methods --  `.create_warning_for` and `.warn_at_exit` --  users are automatically warned, in
+  # this case at the moment of termination, about gems that could not found be in the `$LOAD_PATH`.
+  #  Using `Plow::Dependencies` is **not** a mandatory inclusion for all gem requirements, merely a
+  # guide to help developers quickly see obstacles in their path.
+  #
+  # @example Simple usage with the Jeweler gem
+  #   Plow::Dependencies.warn_at_exit
+  #   begin
+  #     require 'jeweler'
+  #     # work with the Jeweler gem
+  #   rescue LoadError => e
+  #     Plow::Dependencies.create_warning_for(e)
+  #   end
+  #
+  # @see Plow::Dependencies.create_warning_for
+  # @see Plow::Dependencies.warn_at_exit  
+  class Dependencies
+    # For now, starting with Ruby 1.9.1 but I would like to experiment with compatibility with Ruby >= 1.9.1 in the future.
+    REQUIRED_RUBY_VERSION = '1.9.1'
+    
+    # bluecloth is a hidden yard dependency for markdown support
+    DEVELOPMENT_GEMS = {
+      :jeweler   => '1.3.0',
+      :rspec     => '1.2.9',
+      :yard      => '0.4.0',
+      :bluecloth => '2.0.5'
+    }
+    
+    # Thanx rspec for bucking the pattern :(
+    FILE_NAME_TO_GEM_NAME = {
+      :spec => :rspec
+    }
+    
+    # Empties the warnings cache.  This method is called when the class is required.
+    def self.destroy_warnings
+      @@warnings_cache = []
+    end
+    destroy_warnings
+    
+    # Creates and caches a warning from a `LoadError` exception.  Warnings are only created for
+    # known development gem dependencies.
+    #
+    # @param [LoadError] error A rescued exception
+    # @raise [RuntimeError] Raised when the `LoadError` argument is an unknown development gem.
+    def self.create_warning_for(error)
+      error.message.match(/no such file to load -- (\w*)/) do |match_data|
+        file_name = match_data[1].to_sym
+        gem_name  = if DEVELOPMENT_GEMS.has_key?(file_name)
+          file_name
+        elsif FILE_NAME_TO_GEM_NAME.has_key?(file_name)
+          FILE_NAME_TO_GEM_NAME[file_name]
+        else
+          raise "Cannot create a dependency warning for unknown development gem -- #{file_name}"
+        end
+        
+        @@warnings_cache << "#{gem_name} --version '#{DEVELOPMENT_GEMS[gem_name]}'"
+      end
+    end
+    
+    # Displays a warning message to the user on the standard output channel if there are warnings
+    # to render.
+    #
+    # @example Sample warning message
+    #   The following development gem dependencies could not be found. Without them, some available development features are missing:
+    #   jeweler --version '1.3.0'
+    #   rspec --version '1.2.9'
+    #   yard --version '0.4.0'
+    #   bluecloth --version '2.0.5'
+    def self.render_warnings
+      unless @@warnings_cache.empty?
+        message = []
+        message << "The following development gem dependencies could not be found. Without them, some available development features are missing:"
+        message += @@warnings_cache
+        puts "\n" + message.join("\n")
+      end
+    end
+    
+    # Attaches a call to `render_warnings` to `Kernel#at_exit`
+    def self.warn_at_exit
+      at_exit { render_warnings }
+    end
+    
+    private
+    
+    # Checks that the version of the current Ruby process matches the `REQUIRED_RUBY_VERSION`.
+    # This method is automatically invoked at the first time this class is required, ensuring the
+    # correct Ruby version at parse-time.
+    #
+    # @param [String] ruby_version Useful for automated specifications.  Defaults to `RUBY_VERSION`.
+    # @raise [SystemExit] Raised, with a message, when the process is using an incorrect version of Ruby.
+    def self.check_ruby_version(ruby_version = RUBY_VERSION)
+      unless ruby_version == REQUIRED_RUBY_VERSION
+        abort <<-ERROR
+This library requires Ruby #{REQUIRED_RUBY_VERSION}, but you're using #{ruby_version}.
+Please visit http://www.ruby-lang.org/ for installation instructions.
+        ERROR
+      end
+    end
+    check_ruby_version
+  end
+end

data/lib/plow/errors.rb

@@ -1,27 +1,35 @@
 # encoding: UTF-8
 
 class Plow
+  # Should be raised when the current process is owned by a non-root user.
   class NonRootProcessOwnerError < StandardError
   end
   
+  # Should be raised when the user-supplied system user name is invalid.
   class InvalidSystemUserNameError < StandardError
   end
   
+  # Should be raised when the user-supplied web-site name is invalid.
   class InvalidWebSiteNameError < StandardError
   end
   
+  # Should be raised when the user-supplied web-site alias is invalid.
   class InvalidWebSiteAliasError < StandardError
   end
   
+  # Should be raised when the user-supplied system user name is reserved.
   class ReservedSystemUserNameError < StandardError
   end
   
+  # Should be raised when the user-supplied system user name is not found when it should be.
   class SystemUserNameNotFoundError < StandardError
   end
   
+  # Should be raised when an application root path already exists when it should not.
   class AppRootAlreadyExistsError < StandardError
   end
   
+  # Should be raised when a configuration file already exsits when it should not.
   class ConfigFileAlreadyExistsError < StandardError
   end
 end

data/lib/plow/generator.rb

@@ -1,15 +1,49 @@
 # encoding: UTF-8
-
 require 'erb'
-
 require 'plow/binding_struct'
-require 'plow/strategy/ubuntu_hardy/user_home_web_app'
+require 'plow/strategy/ubuntu_hardy'
 
 class Plow
+  # `Plow::Generator` is a **context** class.
+  #
+  # At run-time, `Plow::Generator` selects an appropiate strategy class.  Each strategy class
+  # implements a specific algorithm for web-site template generation.  An instance of 
+  # `Plow::Generator` is intended to be passed to the choosen strategy object, as it provides
+  # read-only data accessors for user-supplied input as well as convience methods that communicate
+  # messages to the user and execute commands on the system.
+  #
+  # Currently, there is a single strategy implementation.
+  #
+  # @see Plow::Strategy::UbuntuHardy
   class Generator
     attr_reader :user_name, :site_name, :site_aliases
     attr_reader :strategy
     
+    # Instantiates a new `Plow::Generator` object with a user name, site name, and optional
+    # site aliases.
+    #
+    # During instantiation, `Plow::Generator` performs basic data validation on the user-supplied
+    # input, raising an exception on any failure.  On success, parameters are cached to instance
+    # variables with read-only, public accessors.  Finally, the correct strategy class is selected.
+    # This decision is very simple as there is only 1 strategy class at the moment.
+    #
+    # @example Initialization with two required arguments
+    #   generator = Plow::Generator.new('steve', 'www.apple.com')
+    #
+    # @example Initialization with an optional third argument
+    #   generator = Plow::Generator.new('steve', 'www.apple.com', 'apple.com')
+    #
+    # @return [Plow::Generator] A new instance of `Plow::Generator`
+    #
+    # @param [String] user_name Name of a Linux system account user (e.g. steve)
+    # @param [String] site_name Name of the web-site (e.g. www.apple.com)
+    # @param [splat] *site_aliases (Optional) List of alias names of the web-site (e.g. apple.com)
+    #
+    # @raise [Plow::InvalidSystemUserNameError] Raised when a `user_name` is blank or includes an space character
+    # @raise [Plow::InvalidWebSiteNameError] Raised when a `site_name` is blank or includes an space character
+    # @raise [Plow::InvalidWebSiteAliasError] Raised when any `site_alias` is blank or includes an space character
+    #
+    # @see Plow::Strategy::UbuntuHardy
     def initialize(user_name, site_name, *site_aliases)
       if user_name.blank? || user_name.include?(' ')
         raise(Plow::InvalidSystemUserNameError, user_name)
@@ -29,18 +63,51 @@ class Plow
       @site_name    = site_name
       @site_aliases = site_aliases
       
-      @strategy = Plow::Strategy::UbuntuHardy::UserHomeWebApp.new(self)
+      @strategy = Plow::Strategy::UbuntuHardy.new(self)
     end
     
+    # Executes the pre-choosen strategy.
+    #
+    # @example Executing a strategy pre-choosen by a `Plow::Generator` instance
+    #   generator = Plow::Generator.new('steve', 'www.apple.com')
+    #   generator.run!
+    #
+    # @raise [Plow::NonRootProcessOwnerError] Raised when the process is owned by a non-root user
     def run!
       raise Plow::NonRootProcessOwnerError unless Process.uid == 0
-      strategy.execute
+      strategy.execute!
     end
     
+    # Renders a message, via the standard output channel, to the user.
+    #
+    # @example A sample user message
+    #   generator.say("Hello World!")
+    #
+    # @example Sample output
+    #   ==> Hello World!
+    #
+    # @param [String] message A brief message to the user
     def say(message)
       puts "==> #{message}"
     end
     
+    # Executes a set of commands in the user's shell enviroment.  Any text rendered out to any
+    # channel during execution is **not** captured and simply displayed to the user.  Leading
+    # spaces in a command are stripped away and empty lines are ignored.
+    #
+    # @example Sample usage
+    #   generator.shell <<-COMMANDS
+    #     
+    #     echo "Hello World!"
+    #     
+    #     cat /etc/passwd
+    #   COMMANDS
+    #
+    # @example Sample shell execution
+    #   echo "Hello World!"
+    #   cat /etc/passwd
+    #
+    # @param [String] commands A set of commands, delimited by line-breaks
     def shell(commands)
       commands.each_line do |command|
         command.strip!
@@ -48,8 +115,23 @@ class Plow
       end
     end
     
+    # Evaluates a template file, located on the user's filesystem, with a context
+    #
+    # @example Evaluating a template file with a context and writing the result to back disk
+    #   File.open('/path/to/output/file', 'wt') do |file|
+    #     generator = Plow::Generator.new('steve', 'www.apple.com')
+    #     context   = { :site_name => generator.site_name }
+    #     
+    #     config = generator.evaluate_template('/path/to/template/file', context)
+    #     file.write(config)
+    #   end
+    #
+    # @return [String] The evaluated template data
+    # @param [String] template_path A Unix path to a template file
+    # @param [Hash] context Key/value pairs, where the key is a template file instance variable, 
+    #   and a value is the value to be substituted during evaluation
     def evaluate_template(template_path, context)
-      template = File.read(template_path)
+      template       = File.read(template_path)
       context_struct = Plow::BindingStruct.new(context)
       ERB.new(template).result(context_struct.get_binding)
     end

data/lib/plow/strategy/ubuntu_hardy.rb

@@ -0,0 +1,316 @@
+# encoding: UTF-8
+
+class Plow
+  class Strategy
+    # `Plow::Strategy::UbuntuHardy` is a **strategy** class, conditionally instantiated at
+    # run-time, that implements a generator algorithm for it's **context** class,
+    # `Plow::Generator`.
+    #
+    # The algorithm implementation is compatible for and tested with Linux Ubuntu 8.04.3 LTS
+    # (Hardy Heron) running the Apache 2.2.8 web-server.  For a description of the algorithm,
+    # please see `Plow::Strategy::UbuntuHardy#execute!`.
+    #
+    # This class has a few code smells that I expect to iron out in time.  However, I'll worry
+    # about this when it comes time to share parts of this algorthm across multiple strategy
+    # classes.
+    #
+    # @see Plow::Strategy::UbuntuHardy#execute!
+    # @see Plow::Generator
+    class UbuntuHardy
+      attr_reader :context, :users_file_path, :vhost_file_name, :vhost_file_path, :vhost_template_file_path
+      attr_reader :user_home_path, :sites_home_path, :app_root_path, :app_public_path, :app_log_path
+      
+      # Instantiates a new `Plow::Strategy::UbuntuHardy` object from the context of a
+      # `Plow::Generator` instance.
+      #
+      # @example
+      #   class Plow
+      #     class Generator
+      #       def initialize
+      #         @strategy = Plow::Strategy::UbuntuHardy.new(self)
+      #       end
+      #     end
+      #   end
+      #
+      # @return [Plow::Strategy::UbuntuHardy] A new instance
+      # @param [Plow::Generator] context A reference to the generator context.
+      def initialize(context)
+        @context         = context
+        @users_file_path = "/etc/passwd"
+        @vhost_file_name = "#{context.site_name}.conf"
+        @vhost_file_path = "/etc/apache2/sites-available/#{vhost_file_name}"
+        
+        @vhost_template_file_path = "#{File.dirname(__FILE__)}/ubuntu_hardy/templates/apache2-vhost.conf"
+      end
+      
+      # Starts the generator algorithm.  The algorithm works as follows:
+      #
+      # 1. Check for a system user account, create it if one does not exist
+      # 2. Check for a system user home directory, create it if one does not exist
+      # 3. Check for a sites home directory within the system user home, create it if one does not
+      #    exist
+      # 4. Create an application root directory within the sites home, but raise an exception if
+      #    one already exists
+      # 5. Create an application public directory
+      # 6. Create an application log directory
+      # 7. Create an virtual host configuration file, but raise an exception if one already exists
+      # 8. Install the new virtual host configuration file into the web server
+      #
+      # In addition to the below exceptions, this method may pass-up a raised exception from within
+      # any of the private instance methods.
+      #
+      # @raise [Plow::AppRootAlreadyExistsError] Raised if the web-app root path directory
+      #   aleady exists
+      # @raise [Plow::ConfigFileAlreadyExistsError] Raised if a apache2 vhost configuration file
+      #   cannot be found
+      def execute!
+        if user_exists?
+          say "existing #{context.user_name} user"
+        else
+          say "creating #{context.user_name} user"
+          create_user!
+        end
+        
+        if user_home_exists?
+          say "existing #{user_home_path}"
+        else
+          say "creating #{user_home_path}"
+          create_user_home!
+        end
+        
+        if sites_home_exists?
+          say "existing #{sites_home_path}"
+        else
+          say "creating #{sites_home_path}"
+          create_sites_home!
+        end
+        
+        if app_root_exists?
+          raise(Plow::AppRootAlreadyExistsError, app_root_path)
+        else
+          say "creating #{app_root_path}"
+          create_app_root!
+        end
+        
+        @app_public_path = "#{app_root_path}/public"
+        say "creating #{@app_public_path}"
+        create_app_public!
+        
+        @app_log_path = "#{app_root_path}/log"
+        say "creating #{app_log_path}"
+        create_app_logs!
+        
+        if vhost_config_exists?
+          raise(Plow::ConfigFileAlreadyExistsError, vhost_file_path)
+        else
+          say "creating #{vhost_file_path}"
+          create_vhost_config!
+        end
+        
+        say "installing #{vhost_file_path}"
+        install_vhost_config!
+      end
+      
+      ############################################################################################################
+      
+      private
+      
+      # Proxy method to `Plow::Generator#say`.
+      # @param [String] message A user output message
+      # @see Plow::Generator#say
+      def say(message)
+        context.say(message)
+      end
+      
+      # Proxy method to `Plow::Generator#shell`.
+      # @param [String] commands Shell commands with multi-line support.
+      # @see Plow::Generator#shell
+      def shell(commands)
+        context.shell(commands)
+      end
+      
+      # Reads the file at `users_file_path` and yields each user iteratively.
+      #
+      # @yield [Hash] Each user account
+      # @example
+      #   users do |user|
+      #     user[:name]        #=> [String] The name
+      #     user[:password]    #=> [String] The bogus password
+      #     user[:id]          #=> [Number] The uid number
+      #     user[:group_ip]    #=> [Number] The gid number
+      #     user[:info]        #=> [String] General account info
+      #     user[:home_path]   #=> [String] The path to the home directory
+      #     user[:shell_path]  #=> [String] The path to the default shell
+      #   end
+      def users(&block)
+        File.readlines(users_file_path).each do |user_line|
+          user_line = user_line.chomp.split(':')
+          user = {
+            :name       => user_line[0],
+            :password   => user_line[1],
+            :id         => user_line[2].to_i,
+            :group_id   => user_line[3].to_i,
+            :info       => user_line[4],
+            :home_path  => user_line[5],
+            :shell_path => user_line[6]
+          }
+          yield user
+        end
+      end
+      
+      ############################################################################################################
+      
+      # Determines if the context.user_name already exists or not.
+      # 
+      # @return [Boolean] `true` if found otherwise `false`
+      # @raise [Plow::ReservedSystemUserNameError] Raised if the `context.user_name` is a reserved
+      #   system user name
+      def user_exists?
+        users do |user|
+          if user[:name] == context.user_name
+            unless user[:id] >= 1000 && user[:id] != 65534
+              raise(Plow::ReservedSystemUserNameError, context.user_name)
+            end
+            return true
+          end
+        end
+        
+        return false
+      end
+      
+      # Creates a system user account for `context.user_name`.
+      def create_user!
+        shell "adduser #{context.user_name}"
+      end
+      
+      ############################################################################################################
+      
+      # Determines if a home path for the `context.user_name` already exists.  As a side-effect,
+      # also correctly sets the `@user_home_path` variable.
+      #
+      # @return [Boolean] `true` if the path already exists, otherwise `false`
+      # @raise [Plow::SystemUserNameNotFoundError] Raised if the `context.user_name` is not found 
+      #   though it is expected to exist
+      def user_home_exists?
+        users do |user|
+          if user[:name] == context.user_name
+            @user_home_path = user[:home_path]
+            return Dir.exists?(user[:home_path])
+          end
+        end
+        
+        raise(Plow::SystemUserNameNotFoundError, context.user_name)
+      end
+      
+      # Creates a user home directory structure at `user_home_path`.
+      def create_user_home!
+        shell <<-RUN
+          mkdir #{user_home_path}
+          chown #{context.user_name}:#{context.user_name} #{user_home_path}
+        RUN
+      end
+      
+      ############################################################################################################
+      
+      # Determines if the `sites_home_path` already exists.  As a side-effect, also correctly
+      # sets the `@sites_home_path` variable.
+      #
+      # @return [Boolean] `true` if the path already exists, otherwise `false`
+      def sites_home_exists?
+        @sites_home_path = "#{user_home_path}/sites"
+        Dir.exists?(sites_home_path)
+      end
+      
+      # Creates the sites home directory structure at `sites_home_path`.
+      def create_sites_home!
+        shell <<-RUN
+          mkdir #{sites_home_path}
+          chown #{context.user_name}:#{context.user_name} #{sites_home_path}
+        RUN
+      end
+      
+      ############################################################################################################
+      
+      # Determines if the `app_root_path` already exists.  As a side-effect, also correctly
+      # sets the `@app_root_path` variable.
+      #
+      # @return [Boolean] `true` if the path exists, otherwise `false`
+      def app_root_exists?
+        @app_root_path = "#{sites_home_path}/#{context.site_name}"
+        Dir.exists?(app_root_path)
+      end
+      
+      # Creates the app root directory structure at `app_root_path`.
+      def create_app_root!
+        shell <<-RUN
+          mkdir #{app_root_path}
+          chown #{context.user_name}:#{context.user_name} #{app_root_path}
+        RUN
+      end
+      
+      ############################################################################################################
+      
+      # Creates the app public directory structure at `app_public_path`.
+      def create_app_public!
+        shell <<-RUN
+          mkdir #{app_public_path}
+          touch #{app_public_path}/index.html
+          chown -R #{context.user_name}:#{context.user_name} #{app_public_path}
+        RUN
+      end
+      
+      ############################################################################################################
+      
+      # Creates the app log directory structure at `app_log_path`.
+      def create_app_logs!
+        shell <<-RUN
+          mkdir #{app_log_path}
+          mkdir #{app_log_path}/apache2
+          chmod 750 #{app_log_path}/apache2
+          
+          touch #{app_log_path}/apache2/access.log
+          touch #{app_log_path}/apache2/error.log
+          
+          chmod 640 #{app_log_path}/apache2/*.log
+          chown -R #{context.user_name}:#{context.user_name} #{app_log_path}
+          chown root -R #{app_log_path}/apache2
+        RUN
+      end
+      
+      ############################################################################################################
+      
+      # Determines if the apache2 vhost config file already exists.
+      #
+      # @return [Boolean] `true` if the file exists, otherwise `false`
+      def vhost_config_exists?
+        Dir.exists?(vhost_file_path)
+      end
+      
+      # Creates an apache2 vhost config file at `vhost_file_path` by evaluateing a template file.
+      def create_vhost_config!
+        File.open(vhost_file_path, 'wt') do |file|
+          template_context = {
+            :site_name       => context.site_name,
+            :site_aliases    => context.site_aliases,
+            :app_public_path => app_public_path,
+            :app_log_path    => app_log_path
+          }
+          
+          config = context.evaluate_template(vhost_template_file_path, template_context)
+          file.write(config)
+        end
+      end
+      
+      ############################################################################################################
+      
+      # Installs the apache2 vhost config file by enabling the site and restarting the web server.
+      def install_vhost_config!
+        shell <<-RUN
+          a2ensite #{vhost_file_name} > /dev/null
+          apache2ctl graceful
+        RUN
+      end
+      
+    end
+  end
+end

data/lib/plow.rb

@@ -1,18 +1,12 @@
 # encoding: UTF-8
-
-unless RUBY_VERSION >= '1.9.1'
-  abort <<-ERROR
-Incompatible ruby version error in #{__FILE__} near line #{__LINE__}
-This library requires at least ruby v1.9.1 but you're using ruby v#{RUBY_VERSION}
-Please see http://www.ruby-lang.org/
-  ERROR
-end
-
+$LOAD_PATH.unshift(File.dirname(__FILE__)) unless $LOAD_PATH.include?(File.dirname(__FILE__))
+require 'plow/dependencies' # ruby version guard
 require 'plow/core_ext/object'
-
 require 'plow/errors'
 require 'plow/application'
 
+# Library namespace
 class Plow
-  VERSION = "0.1.0"
+  # Current stable released version
+  VERSION = "1.0.0"
 end

data/spec/plow/application_spec.rb

@@ -1,10 +1,10 @@
 # encoding: UTF-8
-require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'spec_helper'
 
 describe Plow::Application do
   
   before(:each) do
-    @expected_version_stamp = "Plow v0.1.0. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
+    @expected_version_stamp = "Plow 1.0.0. Copyright (c) 2009 Ryan Sobol. Licensed under the MIT license."
   end
   
   ##################################################################################################

data/spec/plow/binding_struct_spec.rb

@@ -1,6 +1,6 @@
 # encoding: UTF-8
 
-require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'spec_helper'
 
 describe Plow::BindingStruct do