hudkins 0.0.1

data/lib/hudkins/command.rb

@@ -0,0 +1,127 @@
+require "hudkins"
+require "optparse"
+require "yaml"
+
+##
+# === Description
+# Main class for the included bin to interact with Hudson at the command line.
+#
+# The Commands are setup in Hudkins::Command::Exec
+#
+# === Usage
+# see `hudkins -h'
+#
+# a host option is required. Can be configured in env variable +hudkins_host+ or
+# config file. all options can be specified in a yaml file in +~/.hudkinsrc+
+# and/or +`pwd`/.hudkinsrc+
+class Hudkins::Command
+  include Hudkins::Common
+
+  require "hudkins/command/exec"
+  # all the run_ commands
+  extend Hudkins::Command::Exec
+
+  class << self
+    def run
+      parse_options
+      begin
+        return_string = send( @command )
+        puts return_string if return_string
+      rescue => e
+        raise_usage e.message
+      end
+      if @options[:irb]
+        run_start_irb
+      end
+    end
+
+    # commands:
+    # helpers:
+    def usage_msg
+      usage = <<-EOB
+
+Usage: hudkins [opts] commands [job_name]
+
+  Commands:   unambiguous_partial_command
+  build:    start a job building.
+  config:   pretty print job config. job_name
+  create:   create new hudson job.
+  host:     print hudson host url
+  list:     list jobs. [job_name used as filter].
+
+
+  Optional:   job_name (depends on command)
+    may also be partial (picks first match)
+
+      EOB
+    end
+
+    def raise_usage msg = nil
+      warn msg if msg
+      puts usage_msg
+      exit 1
+    end
+
+    def parse_options
+      # initialize cmd_list. This seems hacky, but I like having the cmd_list
+      # near the usage statement.
+      @options = {}
+
+      OptionParser.new do |opts|
+        opts.banner = usage_msg
+
+        opts.separator ""
+        opts.separator "Specific options:"
+
+        opts.on("--hud-host HOST", "Hudson host to connect to. Overrides rc file") do |h|
+          @options[:host] = h
+        end
+
+        opts.on("-i", "--irb", "Drop into irb.") do |i|
+          @options[:irb] = i
+        end
+        opts.on("-v", "--[no-]verbose", "Turn on verbose messages.") do |v|
+          $VERBOSE = @options[:verbose] = v
+        end
+
+        opts.separator ""
+        opts.separator "Common options:"
+
+        opts.on_tail("--version", "Show version") do
+          puts "Hudkins (#{Hudkins::VERSION}) (c) 2010"
+          exit
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+
+      end.parse!
+
+      config.merge! @options
+
+      @command, @job_name = ARGV.shift(2)
+      @command ||= "default"
+
+      @hud = Hudkins.new hud_host
+      job @job_name
+
+      parse_command
+    end
+
+    def parse_command
+      # select unambiguous command to run.
+      cmds = cmd_list.select {|c| Regexp.new(@command.to_s, Regexp::IGNORECASE) === c}
+      case cmds.size
+      when 0 then
+        raise_usage "#{@command} is not recognized as a valid command."
+      when 1 then
+        @command = "run_" << cmds.first
+      else
+        raise_usage "Ambiguous command. Please specify:\n  #{cmds.join("\n  ")}\n\n"
+      end
+    end
+
+  end
+end

data/lib/hudkins/command/exec.rb

@@ -0,0 +1,113 @@
+class Hudkins
+  ##
+  # === Description
+  # mixin for interacting with the lib
+  #
+  # the bin is setup to run any command prefaced with `run_'
+  # each command should return something to be puts or nil
+  module Command::Exec
+    ##
+    # default command. here as a place holder
+    def run_default
+    end
+
+    def run_build
+      "building!!!"
+    end
+
+    def run_config job_name = @job_name
+      required_params job_name => "job_name is required for this command."
+      [
+        job( job_name ).name,
+        job( job_name ).config
+      ]
+    end
+
+    def run_create job_name = @job_name
+      required_params job_name => "job_name is required for this command."
+      "creating!!!"
+    end
+
+    def run_host
+      hud_host
+    end
+
+    def run_list job_name = @job_name
+      names( job_name || "" )
+    end
+
+    def run_start_irb
+      puts <<-EOS
+
+  ---
+  Welcome to hudkins irb console.
+  type hudkins for help.
+
+      EOS
+      require "hudkins/command/irb_start"
+      # turn job names into methods
+      extend Hudkins::Command::Irb
+      IRB.start_session(nil, binding)
+    end
+
+    # helper commands
+
+    def hud
+      @hud
+    end
+
+    def job job_name = nil
+      if job_name
+        @job = hud.jobs.find_by_name job_name
+      end
+      @job
+    end
+
+    # could probably be cleaned up
+    def required_params values
+      e = Hudkins::ArgumentError.new ""
+      raize = false
+      values.each do |k,msg|
+        e << msg unless k
+        raize = true unless k
+      end
+      raise e if raize
+    end
+
+    def cmd_list
+      command_list.map {|m| m.gsub(/^run_/, '')}
+    end
+
+    def command_list
+      self.methods.select {|m| m =~ /^run_/}
+    end
+
+    def names name = ""
+      hud.jobs.names name
+    end
+
+    def hud_host
+      ENV["hudkins_host"] || config[:host] || raise_usage( "no hudkins_host defined." )
+    end
+
+    def config
+      @config ||= load_rc
+    end
+
+    def load_rc
+      hudkins_rc.inject({}) do |ret, rc|
+        h = YAML.load_file( rc )
+        ret.merge! h if h
+        ret
+      end
+    end
+
+    def hudkins_rc
+      [
+        File.expand_path("~/.hudkinsrc"),
+        File.join(Dir.pwd, ".hudkinsrc")
+      ].select {|f| File.size? f} # exists and is non 0
+    end
+
+  end
+end

data/lib/hudkins/command/irb_start.rb

@@ -0,0 +1,86 @@
+require "irb"
+
+# thank you!
+# http://jameskilton.com/2009/04/02/embedding-irb-into-your-ruby-application/
+
+module IRB # :nodoc:
+  # originally used the code snippet from the above link, which turned out to
+  # be a snippet from `ruby-debug'. However, I was having problems with CNTR-C
+  # and I realized I wanted to mimic irb, just be able to actually pass Irb.new
+  # a workspace param which it expected.
+  def self.start_session(ap_path = nil, binding = nil)
+    @@hack_binding = binding
+    IRB.start ap_path
+  end
+
+  def self.get_binding
+    @@hack_binding
+  end
+
+  class Irb
+    alias_method :org_initialize, :initialize
+    def initialize *args
+      workspace = args.shift
+      workspace ||= WorkSpace.new(IRB.get_binding)
+      args.unshift workspace
+      org_initialize *args
+    end
+  end
+end
+
+class Hudkins
+  module Command::Irb
+
+    ##
+    # In the irb console I want to access the same commands as
+    # Hudkins::Command::Exec but without the `run_' part.
+    def self.extend_object obj # :doc:
+      # in IRB allow run_* commands to be exec without `run_'
+      obj.command_list.each do |cmd|
+        s = <<-EOE
+          def self.#{cmd.gsub(/^run_/, '')} *args; #{cmd} *args; end
+        EOE
+        obj.module_eval s
+      end
+      super
+    end
+
+    ##
+    # This is cool. Override default method to add convenience methods for each
+    # job_name in #jobs. This allows `job_name' to be used as a method to
+    # access that particular job.
+    def method_missing sym, *args, &block
+      if job = @hud.jobs.find_by_name( sym )
+        job
+      else
+        super sym, *args, &block
+      end
+    end
+
+    ##
+    # help method in irb console
+    def hudkins
+      puts <<-EOS
+
+  self is Hudkins::Command
+  hudkins            => This help message
+  reload!         => reload lib
+  hud             => Hudkins.new <hud_host>
+  job [job_name]  => Hudkins::Job
+  job_name        => Hudkins::Job
+  commands:
+    #{cmd_list.join("\n    ")}
+
+      EOS
+    end
+
+    ##
+    # helper method in irb console to reload all the lib files.
+    def reload!
+      $".grep( /hudkins/ ).each do |f|
+        load f
+      end
+      nil
+    end
+  end # Command::Irb
+end # Hudkins

data/lib/hudkins/common.rb

@@ -0,0 +1,69 @@
+class Hudkins
+  # common methods available for all classes
+  module Common
+
+    # hide instance variables
+    def inspect( string = nil )
+      new_string = " " << string if string
+      "#<%s:0x%x%s>" % [self.class, (self.object_id << 1), new_string]
+    end
+
+    ##
+    # === Description
+    # useful for escaping parameters to be sent to #get/#post
+    #
+    # === Parameters
+    # +Hash+::  converts a simple one dimentional hash to a url parameter
+    #           query string and uri escapes it.
+    # +else+::  converts to string and uri escapes it.
+    def url_escape msg
+      case msg
+      when Hash then
+        URI.escape( msg.map {|k,v| "#{k}=#{v}" }.join("&") )
+      else
+        URI.escape( msg.to_s )
+      end
+    end
+
+    #--
+    # these classes are being included in the @hudkins class.
+    #++
+
+    def hudkins
+      @hudkins
+    end
+
+    ##
+    # accessor methods for child classes to get
+    def get *args
+      @hudkins.get *args
+    end
+
+    ##
+    # accessor methods for child classes to post
+    def post *args
+      @hudkins.post *args
+    end
+
+    ##
+    # TODO host is not universally accessible so this method might not belong here..
+    # === Notes
+    # My Hudson server is not publicially accessible so when I can't connect,
+    # Socket#getaddrinfo (RestClient) times out after more than 20 seconds! I
+    # created a healper class Hudkins::HostLookup to timeout Socket#getaddrinfo
+    # after Hudkins::HostLookup#TIMEOUT seconds (defaults to 2).
+    def host_available?
+      HostLookup.available? @host, @options[:host_timeout]
+    end
+
+    ##
+    # TODO host is not universally accessible so this method might not belong here..
+    # Raise TimeoutError unless hudson host is responding within specified number of seconds.
+    def check_host_availability
+      # host is URI.
+      msg = "`%s' did not respond within the set number of seconds." % [ host.host ]
+      raise TimeoutError, msg unless host_available?
+    end
+
+  end
+end

data/lib/hudkins/errors.rb

@@ -0,0 +1,7 @@
+class Hudkins
+  class ArgumentError < ::ArgumentError
+    def << (msg)
+      self.message << "\n" + msg
+    end
+  end
+end

data/lib/hudkins/job.rb

@@ -0,0 +1,168 @@
+# === Description
+# Primary class for interacting with a Hudson job
+#
+# === Examples
+#   hud = Hudkins.new "http://hudson.com"
+#   job = hud.jobs.find_by_name :job_name
+#
+#   job.disabled? # => true
+#   job.disabled = false
+#   job.post_config!
+#
+# === attr_accessor_from_config methods
+#
+# I created custom attr_accessor like DSL methods that create accessor like
+# methods for the Hudkins::Job object to easily interact with the xml config.
+# Paradigm is to use method_name? for boolean values and method_name! for any
+# methods that post updates to the server.
+#
+class Hudkins::Job
+  include Hudkins::Common
+  extend Hudkins::Mixin
+
+  include Comparable
+
+  attr_reader :name, :url, :color, :path, :config
+
+  #TODO figure out how to define a custom rdoc method to correctly document these
+
+  ##
+  # :attr_accessor: scm_url
+  attr_accessor_from_config :scm_url,             "//scm//remote"
+  ##
+  # :attr_accessor: description
+  attr_accessor_from_config :description,         "//project//descriptoin"
+  ##
+  # :attr_accessor: can_roam
+  attr_accessor_from_config :can_roam,            "//project//canRoam",                         :bool
+  ##
+  # :attr_accessor: disabled
+  attr_accessor_from_config :disabled,            "//project//disabled",                        :bool
+  ##
+  # :attr_accessor: blocked_by_upstream
+  attr_accessor_from_config :blocked_by_upstream, "//project//blockBuildWhenUpstreamBuilding",  :bool
+  ##
+  # :attr_accessor: concurrent_builds
+  attr_accessor_from_config :concurrent_builds,   "//project//concurrentBuild",                 :bool
+  attr_accessor_from_config :mail_recipients,     "//publishers//recipients"
+  # this is really an array. I haven't added functionality for that yet
+  attr_accessor_from_config :shell_builders,     "//builders/hudson.tasks.Shell",               :array
+  ##
+  # :attr_accessor: :rotate_logs_num
+  # Number of builds to keep
+  # -1 == infinite
+  attr_accessor_from_config :rotate_logs_num,     "//logRotator/numToKeep",                     :int
+  ##
+  # :attr_accessor: :rotate_logs_days
+  # Number of days to keep builds
+  # -1 == infinite
+  attr_accessor_from_config :rotate_logs_days,    "//logRotator/daysToKeep",                    Integer
+
+  def initialize hudkins, data
+    @hudkins = hudkins
+    @name = data["name"]
+    @url = URI.parse data["url"]
+    @color = data["color"]
+    @path = @url.path
+  end
+
+  def inspect
+    super "@name=#{@name}"
+  end
+
+  def url
+    @url.to_s
+  end
+
+  # Enumerables/Comparables...
+  def <=> other
+    # TODO how do I implement jobs.sort(&:path) ?
+    self.name <=> other.name
+  end
+
+  ##
+  # === Description
+  # get the job's config
+  # takes string (xml) or other's config
+  def update_config config = nil
+    config = case config
+    when String then
+      hudkins.parse_string( config, :xml )
+    when Nokogiri::XML::Document, NilClass then
+      config
+    else
+      raise "unknown config type #{config.class}"
+    end
+    @config = config || hudkins.get_parsed( path + "/config.xml", :accept => "application/xml" )
+  end
+
+  ##
+  # === Description
+  # accessor for job's config. Initializes then caches. Use update_config if out of date.
+  def config
+    @config ||= update_config
+  end
+
+  ##
+  # === Description
+  # Post the job's config back to the server to update it.
+  def post_config!
+    post path + "/config.xml", @config
+  end
+
+  def build!
+    get path + "/build"
+  end
+
+  def delete!
+    post path + "/doDelete"
+  end
+
+  def recreate!
+    hudkins.add_job name, config
+  end
+
+  def disable!
+    post path + "/disable"
+  end
+
+  def enable!
+    post path + "/enable"
+  end
+
+  ##
+  # === Description
+  # The remote api allows for updating just the description. I had to tweak the
+  # name because I still wanted description to be an attr_accessor_from_config
+  #
+  # === Example
+  #   job.quick_description! # => "this is the description for job"
+  #   job.quick_description! = "this is the new desc." # => Response obj
+  def quick_description! msg = nil
+    # another yuck!
+    if msg
+      post path + "/description?" + url_escape(:description => msg)
+    else
+      get( path + "/description" ).body
+    end
+  end
+
+  ##
+  # === Description
+  # Copy job to new_job_name
+  #
+  # === Example
+  #   new_job = job.copy "new-job-name"
+  #   new_job.scm_url = "http://svn/new/job/path"
+  #   new_job.post_config!
+  def copy new_job_name
+    # post /createItem?name=NEWJOBNAME&mode=copy&from=FROMJOBNAME
+    response = post "/createItem?" +
+      url_escape(:name => new_job_name, :mode => "copy", :from => name)
+    # return new job object
+    hudkins.update_jobs.find_by_name new_job_name if response.success?
+  end
+
+  # not sure if we want this.
+  # alias_method :dup, :copy
+end