cap-util 0.3.0 → 0.4.0

data/README.md

@@ -83,6 +83,89 @@ task :some_rake_task do
 end
 ```
 
+## GitBranch util
+
+This util helps when working with git branches.  Right now, it only has a singleton helpers for fetching the current branch the user is on.  This can be useful in setting the `:branch` cap var if you always want to deploy from the branch you are currently on.
+
+```ruby
+set (:branch) { CapUtil::GitBranch.current }
+```
+
+## SharedPath util
+
+This utile helps when working with cap's `shared_path`.  Right now, it only has a method for removing things from the shared_path
+
+```ruby
+CapUtil::SharedPath.new(self).rm_rf 'cached-copy'
+```
+
+## Dynamic Server Roles helpers
+
+CapUtil has a few utils for fetching and applying cap server roles from dynamic data.  It assumes you have your server role data stored in yaml either locally or on some remote location.
+
+### Format
+
+The server role yaml needs to be in a format like:
+
+```yaml
+---
+
+app:
+  server1: [primary]
+  server2: []
+
+db:
+  server3: [primary, no_release]
+```
+
+### ServerRolesYaml util
+
+This util serves as a base for fetching role yaml data.  It provides a framework for subclasses to override and supply the necessary logic to fetch/validate/read yaml data.  Use it to pull local or remote config files using the given hooks.
+
+### ServerRoles util
+
+This util, given a raw yaml string, will model out the roles and apply them to your cap invocation.
+
+### Example
+
+This example shows how a different set of roles could be used for different stages in cap.  The yaml config files are located local to the 'my_server_roles_yaml.rb' file.
+
+```ruby
+# in your Capfile...
+require 'my_server_roles_yaml'
+set (:server_roles_yaml) { MyServerRolesYaml.new(self, stage) }
+set (:server_roles) { CapUtil::ServerRoles.new(self, server_roles_yaml.get) }
+
+# in my_server_roles_yaml.rb
+
+class MyServerRolesYaml < CapUtil::ServerRolesYaml
+
+  # fetch role data from the local config/#{stage}_server_roles.yaml file
+
+  def initialize(cap, stage)
+    super(cap, :desc => stage)
+
+    roles_file_name = "#{stage}_server_roles.yaml"
+    @roles_file_path = File.expand_path("../../../config/#{roles_file_name}", __FILE__)
+  end
+
+  def validate
+    if !valid?
+      say_error "`#{@roles_file_path}' does not exist."
+    end
+  end
+
+  def valid?
+    File.exists?(@roles_file_path)
+  end
+
+  def read
+    File.read(@roles_file_path)
+  end
+
+end
+```
+
 ## Contributing
 
 1. Fork it

data/lib/cap-util/git_branch.rb

@@ -0,0 +1,18 @@
+require 'cap-util'
+
+module CapUtil
+  class GitBranch
+    include CapUtil
+
+    def self.current(action=:run)
+      git_cmd = "git symbolic-ref HEAD"
+      if action == :run
+        say "Fetching #{color "current git branch", :bold, :cyan} from HEAD"
+        (r = run_locally(git_cmd)).success? ? r.stdout.split('/').last.strip : halt
+      elsif action == :cmd
+        git_cmd
+      end
+    end
+
+  end
+end

data/lib/cap-util/server_roles.rb

@@ -0,0 +1,85 @@
+require 'yaml'
+require 'cap-util'
+
+module CapUtil
+
+  class ServerRoles
+    include CapUtil
+    attr_reader :roles
+
+    def initialize(cap, roles_yaml)
+      @cap = cap
+      @roles = RoleSet.new(YAML.load(roles_yaml))
+    end
+
+    # Since this is a CapUtil, we can call cap cmds using the `cap` accessor.
+    # For each role, call cap's `role` method, passing the relevant values.
+
+    def apply
+      @roles.each do |name, host, opts|
+        cap.role name, host, opts
+      end
+
+    end
+
+    class RoleSet
+
+      attr_reader :role_defs
+
+      def initialize(roles_hash)
+        @role_defs = roles_hash.map do |(role_name, role_servers_hash)|
+          RoleDef.new(role_name, role_servers_hash)
+        end
+      end
+
+      def each(&block)
+        @role_defs.each {|role_def| role_def.apply(&block)}
+      end
+
+    end
+
+    class RoleDef
+
+      attr_reader :name, :servers
+
+      def initialize(name, servers_hash)
+        @name = name
+        @servers = servers_hash.map do |(server_name, server_options_list)|
+          ServerDef.new(server_name, server_options_list)
+        end
+      end
+
+      def apply(&block)
+        @servers.each do |server|
+          block.call @name, server.hostname, server.options
+        end
+      end
+
+    end
+
+    class ServerDef
+
+      attr_reader :hostname, :options
+
+      def initialize(name, options_list=[])
+        @hostname = "#{name}.reelfx.com"
+        @options = {}
+
+        # so, weird cap bug.  options have to match type when using them in
+        # a task's definition.  so if you have (string) 'primary' option, you
+        # have to use a string in your task defs.
+        # this is not the case for the role names (string or symbol works).
+        # so, I'm just defining each option, both in string (how it comes from
+        # the configs) and symbol form.
+
+        options_list.each do |option|
+          @options[option.to_s]   = true
+          @options[option.to_sym] = true
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/cap-util/server_roles_yaml.rb

@@ -0,0 +1,32 @@
+require 'cap-util'
+
+module CapUtil
+
+  # the class should be use as a superclass for fetching server roles yaml.
+
+  class ServerRolesYaml
+    include CapUtil
+    attr_reader :desc, :source
+
+    def initialize(cap, opts=nil)
+      opts ||= {}
+
+      @cap    = cap
+      @desc   = opts[:desc]   ? "#{opts[:desc]} server roles" : "server roles"
+      @source = opts[:source] ? " from #{opts[:source]}" : ""
+    end
+
+    def get
+      say "Applying #{color @desc, :bold, :cyan}#{@source}."
+
+      validate
+      valid? ? read : halt
+    end
+
+    def validate; raise NotImplementedError; end
+    def valid?;   raise NotImplementedError; end
+    def read;     raise NotImplementedError; end
+
+  end
+
+end

data/lib/cap-util/shared_path.rb

@@ -0,0 +1,22 @@
+require 'cap-util'
+
+module CapUtil
+
+  # SharedPath models the path to the set of shared deployed code.  named
+  # after cap's `shared_path` method b/c they point at similar locations.
+
+  class SharedPath
+    include CapUtil
+
+    def initialize(cap, path=nil)
+      @cap = cap
+      @shared_path = File.expand_path(path || cap.shared_path)
+    end
+
+    def rm_rf(rel_path)
+      run "rm -rf #{@shared_path}/#{rel_path}"
+    end
+
+  end
+
+end

data/lib/cap-util/version.rb

@@ -1,3 +1,3 @@
 module CapUtil
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/test/git_branch_tests.rb

@@ -0,0 +1,19 @@
+require 'assert'
+
+require 'cap-util/git_branch'
+
+module CapUtil
+
+  class GitBranchTests < Assert::Context
+    desc "the GitBranch util"
+    subject { GitBranch }
+
+    should have_imeth :current
+
+    should "use the symbolic ref the HEAD is at for the current branch" do
+      assert_equal "git symbolic-ref HEAD", subject.current(:cmd)
+    end
+
+  end
+
+end

data/test/server_roles_tests.rb

@@ -0,0 +1,120 @@
+require 'assert'
+
+require 'cap-util/server_roles'
+
+module CapUtil
+
+  class ServerRolesTests < Assert::Context
+    desc "the ServerRoles handler"
+    setup do
+      roles_yaml = <<YAML
+---
+hosts:
+  host1: [primary]
+  host2: []
+YAML
+      @fake_cap = FakeCap.new
+      @server_roles = ServerRoles.new(@fake_cap, roles_yaml)
+    end
+    subject { @server_roles }
+
+    should have_reader :roles
+    should have_imeth :apply
+
+    should "build cap roles from yaml using the apply meth" do
+      subject.apply
+      roles = @fake_cap.roles.sort{|a,b| a[1] <=> b[1]}
+
+      assert_equal 2, @fake_cap.roles.size
+      assert_equal ['hosts', 'host2.reelfx.com', {}], roles.last
+    end
+
+  end
+
+  class ServerRoles
+
+    class RoleSetTests < Assert::Context
+      desc "the server roles RoleSet"
+      setup do
+        @roles_hash = {
+          'hosts' => {
+            'host1' => ['primary'],
+            'host2' => []
+          }
+        }
+        @role_set = RoleSet.new @roles_hash
+      end
+      subject { @role_set }
+
+      should have_reader :role_defs
+      should have_imeth :each
+
+      should "yield the name, hostname, and opts for each host/server when iterating the roles" do
+        exp = [
+          ['hosts', 'host1.reelfx.com', {:primary => true, 'primary' => true}],
+          ['hosts', 'host2.reelfx.com', {}]
+        ]
+        actual = []
+        subject.each do |name, host, opts|
+          actual << [name, host, opts]
+        end
+
+        assert_equal exp, actual.sort{|a, b| a[1] <=> b[1]}
+      end
+    end
+
+    class RoleDefTests < RoleSetTests
+      desc "the server roles RoleDef"
+      setup do
+        @role_servers_hash = {
+          'host1' => ['primary'],
+          'host2' => []
+        }
+        @role = RoleDef.new('hosts', @role_servers_hash)
+      end
+      subject { @role }
+
+      should have_reader :name, :servers
+      should have_imeth :apply
+
+      should "build a set of servers from a definition hash" do
+        servs = subject.servers.sort{|a, b| a.hostname <=> b.hostname }
+
+        assert_kind_of ::Array, servs
+        assert_equal 2, servs.size
+        assert_kind_of ServerDef, servs.first
+        assert_equal 'host2.reelfx.com', servs.last.hostname
+        assert_equal true, servs.first.options['primary']
+      end
+
+    end
+
+    class ServerDefTests < Assert::Context
+      desc "the server roles ServerDef"
+      setup do
+        @server = ServerDef.new('host1')
+      end
+      subject { @server }
+
+      should have_readers :hostname, :options
+
+      should "build its hostname from the server name" do
+        assert_equal "host1.reelfx.com", subject.hostname
+      end
+
+      should "have no options by defoult" do
+        assert_empty subject.options
+      end
+
+      should "build its options with both string and symbol keys" do
+        server = ServerDef.new('opts1', 'primary')
+
+        assert_equal true, server.options[:primary]
+        assert_equal true, server.options['primary']
+      end
+
+    end
+
+  end
+
+end

data/test/server_roles_yaml_tests.rb

@@ -0,0 +1,39 @@
+require 'assert'
+
+require 'cap-util/server_roles_yaml'
+
+module CapUtil
+
+  class ServerRolesYamlTests < Assert::Context
+    desc "the ServerRolesYaml util"
+    setup do
+      @roles_yaml = ServerRolesYaml.new(FakeCap.new )
+    end
+    subject { @roles_yaml }
+
+    should have_imeths :get, :validate, :valid?, :read
+    should have_reader :desc, :source
+
+    should "default the yaml's desc and source" do
+      assert_equal "server roles", subject.desc
+      assert_equal "", subject.source
+    end
+
+    should "use a custom desc and source if given" do
+      yml = ServerRolesYaml.new(FakeCap.new, {
+        :desc => 'staging',
+        :source => 'the place'
+      })
+      assert_equal "staging server roles", yml.desc
+      assert_equal " from the place", yml.source
+    end
+
+    should "raise appropriate NotImplementedErrors" do
+      assert_raises(NotImplementedError) { subject.validate }
+      assert_raises(NotImplementedError) { subject.valid? }
+      assert_raises(NotImplementedError) { subject.read }
+    end
+
+  end
+
+end

data/test/shared_path_tests.rb

@@ -0,0 +1,30 @@
+require 'assert'
+require 'fileutils'
+require 'pathname'
+
+require 'cap-util/shared_path'
+
+module CapUtil
+
+  class SharedPathTests < Assert::Context
+    desc "the SharedPath util"
+    setup do
+      @fake_cap = FakeCap.new
+      @fake_cap.shared_path = Pathname.new File.expand_path("tmp/shared")
+
+      @shared_path = SharedPath.new(@fake_cap)
+    end
+    subject { @shared_path }
+
+    should have_imeths :rm_rf
+
+    should "remove a given relative path with the `rm_rf` method" do
+      subject.rm_rf 'cached-copy'
+      exp_cmd = "rm -rf #{File.expand_path("tmp/shared/cached-copy")}"
+
+      assert_equal [exp_cmd], @fake_cap.cmds_run.last
+    end
+
+  end
+
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cap-util
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 15
   prerelease: 
   segments: 
   - 0
-  - 3
+  - 4
   - 0
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Kelly Redding
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-10-16 00:00:00 Z
+date: 2012-10-18 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: assert
@@ -78,19 +78,27 @@ files:
 - cap-util.gemspec
 - lib/cap-util.rb
 - lib/cap-util/fake_cap.rb
+- lib/cap-util/git_branch.rb
 - lib/cap-util/halt.rb
 - lib/cap-util/rake_task.rb
 - lib/cap-util/run.rb
 - lib/cap-util/say.rb
+- lib/cap-util/server_roles.rb
+- lib/cap-util/server_roles_yaml.rb
+- lib/cap-util/shared_path.rb
 - lib/cap-util/time.rb
 - lib/cap-util/timer.rb
 - lib/cap-util/unset_var.rb
 - lib/cap-util/version.rb
 - test/cap_util_tests.rb
 - test/fake_cap_tests.rb
+- test/git_branch_tests.rb
 - test/helper.rb
 - test/irb.rb
 - test/rake_task_tests.rb
+- test/server_roles_tests.rb
+- test/server_roles_yaml_tests.rb
+- test/shared_path_tests.rb
 - test/timer_tests.rb
 - test/unset_var_tests.rb
 homepage: http://github.com/redding/cap-util
@@ -129,8 +137,12 @@ summary: A set of utilities for writing cap tasks.
 test_files: 
 - test/cap_util_tests.rb
 - test/fake_cap_tests.rb
+- test/git_branch_tests.rb
 - test/helper.rb
 - test/irb.rb
 - test/rake_task_tests.rb
+- test/server_roles_tests.rb
+- test/server_roles_yaml_tests.rb
+- test/shared_path_tests.rb
 - test/timer_tests.rb
 - test/unset_var_tests.rb