subordinate 0.0.1

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/cassettes
+.DS_Store
+
+spec/fixtures/authentications.yml

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in subordinate.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jason Truluck
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# Subordinate
+
+Subordinate is a api wrapper for the Jenkins API. It is not exhaustive at the moment and is being built out.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'subordinate'
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install subordinate
+
+## Documentation
+
+## Configuration
+
+Configuration allows for specifying your Jenkins instances variables
+
+`domain` - The domain of your Jenkins server i.e. example.com
+
+`subdomain` - The subdomain of your Jenkins server i.e. jenkins
+
+`port` - The port of your Jenkins server i.e. 8080
+
+`ssl` - If you would like to use ssl [Boolean]
+
+Within an initializer `config/initializer/subordinate.rb`
+
+```ruby
+Subordinate.configure do |c|
+    c.subdomain = "subdomain"
+    c.domain    = "domain"
+    c.port      = 1234
+    c.ssl       = false
+end
+```
+
+## Examples
+
+### Setting up a new client
+
+```ruby
+client = Subordinate::Client.new(:username => "username", :api_token =>"token")
+```
+or
+```ruby
+client = Subordinate.new(:username => "username", :api_token =>"token")
+```
+
+You can also pass configuration keys such as `domain`, `subdomain`, `port` etc. as well.
+
+### [Jobs](http://rdoc.info/github/jasontruluck/subordinate/Subordinate/Client/Job)
+
+Currently offers the ability to build, delete, enable/disable jobs
+
+```ruby
+client.job("Job-Name")
+```
+
+### [Builds](http://rdoc.info/github/jasontruluck/subordinate/Subordinate/Client/Build)
+
+Currently can retrieve information, console output, and timestamps
+
+```ruby
+client.build("Job-Name", 1)
+```
+
+###[System](http://rdoc.info/github/jasontruluck/subordinate/Subordinate/Client/System)
+
+Currently can safe restart, restart, and quiet down
+
+```ruby
+client.restart
+```
+
+## Testing
+
+This gem uses VCR to record requests to the api so you must test using a valid Jenkins server and credentails to test
+
+Add a sample authentications file to your `spec/fixtures` directory:
+
+```ruby
+#spec/fixtures/authentications.yml
+username:  jasontruluck           # Your Username
+token:     12345678901234567890   # Your Jenkins Token (found at jenkins-server/user/your-user-name/configure)
+domain:    mydomain.com           # The domain of your Jenkins server
+port:      8080                   # The port of your Jenkins Server
+subdomain: jenkins                # The subdomain of your Jenkins Server
+job:       My-Jenkins-Job         # The job that you want to run tests on
+```
+
+A sample is included in the [source](https://github.com/jasontruluck/subordinate/blob/master/spec/fixtures/authentications.yml.sample).
+
+*Note: for tests concerning disabling, deleting, restarting, etc they are mocked explicitly with webmock and will not effect your server*
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/subordinate/authentication.rb

@@ -0,0 +1,22 @@
+# Authentication Module
+module Subordinate
+  module Authentication
+    def authentication
+      if username && api_token
+        { :username => username, :api_token => api_token}
+      else
+        {}
+      end
+    end
+
+    def authenticated?
+      !authentication.empty?
+    end
+
+    def username_and_token(username = "", api_token = "")
+      return if username.nil? || api_token.nil?
+      self.username   = username
+      self.api_token  = api_token
+    end
+  end
+end

data/lib/subordinate/client/build.rb

@@ -0,0 +1,85 @@
+# Build
+module Subordinate
+  class Client
+    # Build management and configuration
+    #
+    # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/322/api/
+    module Build
+      # Returns the response with information about the specific build
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/322/api/json?pretty=true
+      #
+      # @param [String] job the job that you want to retrieve information about
+      # @param [String] build_number the build number that you want to retrieve information about
+      #
+      # @return [Hashie::Mash] build response
+      #
+      # @example Get the build api response
+      #   Subordinate::Client.build("My-Job-I-Want-Info-On", 5)
+      #
+      # @author Jason Truluck
+      def build(job, build_number, options = {})
+        get("job/#{job}/#{build_number}/api/json", options)
+      end
+
+      # Returns the builds timestamp
+      # This methods accepts the simple data formatter seen here:
+      # @see http://docs.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/322/buildTimestamp
+      #
+      # @param [String] job the job that you want to retrieve the build number from
+      # @param [String] build_number the build number that you want to retrieve information about
+      # @param [String] format the timestamp format you want returned
+      #
+      # @return [String] build timestamp
+      #
+      # @example Get the first builds timestamp
+      #   Subordinate::Client.build_timestamp("My-Job-I-Want-Info-On", 1)
+      #
+      # @example Get the first builds timestamp in format "yyyy/MM/dd"
+      #   Subordinate::Client.build_timestamp("My-Job-I-Want-Info-On", 1, "yyyy/MM/dd")
+      #
+      # @author Jason Truluck
+      def build_timestamp(job, build_number, format = nil, options = {})
+        options.merge!(
+          :format => format
+        ) if !format.nil?
+
+        get("job/#{job}/#{build_number}/buildTimestamp", options)
+      end
+
+      # Returns the console output for the build specified
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/322/logText/progressiveText?start=0
+      #
+      # @param [String] job the job that you want to retrieve the build number from
+      # @param [String] build_number the build number that you want to retrieve information about
+      # @param [String] start_offset the byte offset of where you start.
+      # @param [Boolean] pre if you want the output to be returned in a pre-formatted foramat for use in <pre> tags
+      #
+      # @return [String] console output of build
+      #
+      # @example Get the console output of the first build
+      #   Subordinate::Client.console_output_for_build("My-Job-I-Want-Info-On", 1)
+      #
+      # @example Get the console output of the first build pre formatted
+      #   Subordinate::Client.console_output_for_build("My-Job-I-Want-Info-On", 1, 0, true)
+      #
+      # @example Get the console output of the first build starting from the 200th byte
+      #   Subordinate::Client.console_output_for_build("My-Job-I-Want-Info-On", 1, 200)
+      #
+      # @author Jason Truluck
+      def console_output_for_build(job, build_number, start_offset = 0, pre = false, options = {})
+        options.merge!(
+          :start => start_offset
+        )
+        if pre
+          get("job/#{job}/#{build_number}/logText/pregressiveHTML", options)
+        else
+          get("job/#{job}/#{build_number}/logText/pregressiveText", options)
+        end
+      end
+    end
+  end
+end

data/lib/subordinate/client/job.rb

@@ -0,0 +1,89 @@
+# Job
+module Subordinate
+  class Client
+    # Job management and configuration
+    #
+    # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/
+    module Job
+      # Returns the response with information about the specific job
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/json?pretty=true
+      #
+      # @param [String] job the job that you want to retrieve information about
+      #
+      # @return [Hashie::Mash] job response
+      #
+      # @example Get the job api response
+      #   Subordinate::Client.job("My-Job-I-Want-Info-On")
+      #
+      # @author Jason Truluck
+      def job(job, options = {})
+        get("job/#{job}/api/json", options)
+      end
+
+      # Builds the job specified on the Jenkins server
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/
+      #
+      # @param [String] job the job that you want to build
+      #
+      # @return [Integer] status
+      #
+      # @example Build the job
+      #   Subordinate::Client.build("My-Job-I-Want-Info-On")
+      #
+      # @author Jason Truluck
+      def build_job(job, options = {})
+        post("job/#{job}/build", options).status
+      end
+
+      # Disables the specified job on the Jenkins Server
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/
+      #
+      # @param [String] job the job that you want to disable
+      #
+      # @return [Integer] status
+      #
+      # @example Disable the job
+      #   Subordinate::Client.disable("My-Job-I-Want-Info-On")
+      #
+      # @author Jason Truluck
+      def disable_job(job, options = {})
+        post("job/#{job}/disable", options).status
+      end
+
+      # Enables the specified job on the Jenkins Server
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/
+      #
+      # @param [String] job the job that you want to enable
+      #
+      # @return [Integer] status
+      #
+      # @example Enable the job
+      #   Subordinate::Client.enable("My-Job-I-Want-Info-On")
+      #
+      # @author Jason Truluck
+      def enable_job(job, options = {})
+        post("job/#{job}/enable", options).status
+      end
+
+      # Deletes the specified job on the Jenkins Server
+      #
+      # @see https://ci.jenkins-ci.org/job/jenkins_rc_branch/api/
+      #
+      # @param [String] job the job that you want to delete
+      #
+      # @return [Integer] status
+      #
+      # @example Disable the job
+      #   Subordinate::Client.disable("My-Job-I-Want-Info-On")
+      #
+      # @author Jason Truluck
+      def delete_job(job, options = {})
+        post("job/#{job}/disable", options).status
+      end
+    end
+  end
+end

data/lib/subordinate/client/system.rb

@@ -0,0 +1,81 @@
+# System
+module Subordinate
+  class Client
+    # System level tasks for Jenkins Server. These functions typically require admin
+    # level privileges to execute.
+    #
+    # @see https://ci.jenkins-ci.org/api/
+    module System
+
+      # Returns the response from the root api
+      #
+      # @see https://ci.jenkins-ci.org/api/json?pretty=true
+      #
+      # @return [Hashie::Mash] State is the server is currently up
+      #
+      # @example Get the root api response
+      #   Subordinate::Client.root
+      #
+      # @author Jason Truluck
+      def root(options = {})
+        get('/api/json', options)
+      end
+
+      # Shuts down Jenkins Server
+      #
+      # @see https://ci.jenkins-ci.org/api/
+      #
+      # @return [Integer] response code
+      #
+      # @example Send a quiet down request to the Jenkins server
+      #   Subordinate::Client.quiet_down
+      #
+      # @author Jason Truluck
+      def quiet_down(options = {})
+        post('/quietDown', options).status
+      end
+
+      # Cancel a shut down request to the Jenkins Server
+      #
+      # @see https://ci.jenkins-ci.org/api/
+      #
+      # @return [Integer] response code
+      #
+      # @example Send a quiet down request to the Jenkins server
+      #   Subordinate::Client.cancel_quiet_down
+      #
+      # @author Jason Truluck
+      def cancel_quiet_down(options = {})
+        post('/cancelQuietDown', options).status
+      end
+
+      # Restarts the jenkins server, will not wait for jobs to finish
+      #
+      # @see https://ci.jenkins-ci.org/api/
+      #
+      # @return [Integer] response code
+      #
+      # @example Sends a force restart request to the Jenkins server
+      #   Subordinate::Client.restart(true)
+      #
+      # @author Jason Truluck
+      def restart(options = {})
+        post("restart", options).status
+      end
+
+      # Safely Restarts the jenkins server, will wait for jobs to finish
+      #
+      # @see https://ci.jenkins-ci.org/api/
+      #
+      # @return [Integer] response code
+      #
+      # @example Sends a restart request to the Jenkins server (defaults to no force)
+      #   Subordinate::Client.restart
+      #
+      # @author Jason Truluck
+      def safe_restart(options = {})
+        post("safeRestart", options).status
+      end
+    end
+  end
+end

data/lib/subordinate/client.rb

@@ -0,0 +1,46 @@
+# Client Module
+require "subordinate/authentication"
+require "subordinate/connection"
+require "subordinate/request"
+
+require "subordinate/client/job"
+require "subordinate/client/system"
+require "subordinate/client/build"
+
+module Subordinate
+  class Client
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    def initialize(options = {})
+      options = Subordinate.options.merge(options)
+
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+
+      username_and_token(options[:username], options[:api_token])
+      build_endpoint
+    end
+
+    # Builds the api endpoint to reach the Jenkins Server
+    #
+    # @return [String] Endpoint
+    #
+    # @author Jason Truluck
+    def build_endpoint
+      endpoint = ssl ? "https://" : "http://"
+      endpoint << "#{self.username}:#{self.api_token}@" if self.authenticated?
+      endpoint << "#{self.subdomain}.#{self.domain}:#{self.port}"
+      endpoint << "?depth=#{self.depth}" if !depth.nil?
+      self.api_endpoint = endpoint
+    end
+
+    include Subordinate::Authentication
+    include Subordinate::Connection
+    include Subordinate::Request
+
+    include Subordinate::Client::Job
+    include Subordinate::Client::System
+    include Subordinate::Client::Build
+  end
+end

data/lib/subordinate/configuration.rb

@@ -0,0 +1,35 @@
+#Configuration
+module Subordinate
+  module Configuration
+    VALID_OPTIONS_KEYS = [
+      :username,
+      :api_token,
+      :api_endpoint,
+      :domain,
+      :subdomain,
+      :port,
+      :ssl,
+      :depth
+    ]
+
+    attr_accessor(*VALID_OPTIONS_KEYS)
+
+    def configure
+      yield self
+    end
+
+    def options
+      VALID_OPTIONS_KEYS.inject({}){|o,k| o.merge!(k => send(k)) }
+    end
+
+    def reset!
+      self.username            = nil
+      self.api_token           = nil
+      self.domain              = nil
+      self.subdomain           = nil
+      self.port                = nil
+      self.ssl                 = true
+      self.depth               = nil
+    end
+  end
+end

data/lib/subordinate/connection.rb

@@ -0,0 +1,20 @@
+# Connection
+require "faraday_middleware"
+
+module Subordinate
+  module Connection
+    def connection(options = {})
+      options = {
+        :ssl              => { :verify => false }
+      }.merge(options)
+
+      connection = Faraday.new(options) do |build|
+        build.use FaradayMiddleware::Mashify
+        build.use FaradayMiddleware::ParseJson, :content_type => /\bjson$/
+        build.adapter  Faraday.default_adapter
+      end
+
+      connection
+    end
+  end
+end

data/lib/subordinate/request.rb

@@ -0,0 +1,33 @@
+module Subordinate
+  module Request
+    def get(path, options = {})
+      response = request(:get, path, options)
+      response.body
+    end
+
+    def post(path, options = {})
+      response = request(:post, path, options)
+      response
+    end
+
+    private
+    def request(method, path, options = {})
+      url = options.delete(:endpoint) || api_endpoint
+
+      connection_options = {
+        :url => url
+      }
+
+      response = connection(connection_options).send(method) do |request|
+        case method
+        when :get
+          request.url(path, options)
+        when :post
+          request.path = path
+          request.body = options unless options.empty?
+        end
+      end
+      response
+    end
+  end
+end

data/lib/subordinate/version.rb

@@ -0,0 +1,3 @@
+module Subordinate
+  VERSION = "0.0.1"
+end

data/lib/subordinate.rb

@@ -0,0 +1,19 @@
+require "subordinate/version"
+require "subordinate/configuration"
+require "subordinate/client"
+
+module Subordinate
+  extend Configuration
+
+  class << self
+    # Alias for Subordinate::Client.new
+    # @return [Subordinate::Client]
+    def new(options = {})
+      Subordinate::Client.new(options)
+    end
+
+    def respond_to?(method, include_private=false)
+      new.respond_to?(method, include_private) || super(method, include_private)
+    end
+  end
+end

data/spec/fixtures/authentications.yml.sample

@@ -0,0 +1,6 @@
+username:  jasontruluck           # Your Username
+token:     12345678901234567890   # Your Jenkins Token (found at jenkins-server/user/your-user-name/configure)
+domain:    mydomain.com           # The domain of your Jenkins server
+port:      8080                   # The port of your Jenkins Server
+subdomain: jenkins                # The subdomain of your Jenkins Server
+job:       My-Jenkins-Job         # The job that you want to run tests on

data/spec/spec_helper.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+
+# This file is copied to spec/ when you run 'rails generate rspec:install'
+ENV["RAILS_ENV"] ||= 'test'
+
+if ENV['RAILS_ENV'] == 'test'
+  require 'simplecov'
+  SimpleCov.start 'rails'
+  class SimpleCov::Formatter::QualityFormatter
+    def format(result)
+      SimpleCov::Formatter::HTMLFormatter.new.format(result)
+      File.open("coverage/covered_percent", "w") do |f|
+        f.puts result.source_files.covered_percent.to_f
+      end
+    end
+  end
+  SimpleCov.formatter = SimpleCov::Formatter::QualityFormatter
+end
+
+require 'subordinate'
+require 'vcr'
+require "webmock/rspec"
+require "mocha/api"
+
+authentications = YAML::load(File.open(File.expand_path("../fixtures/authentications.yml", __FILE__)))
+VCR.configure do |c|
+  c.cassette_library_dir = 'spec/cassettes'
+  c.hook_into :faraday
+  c.ignore_localhost = true
+  # Uncomment if you need to log VCR
+  # c.debug_logger = File.open(Rails.root.join("log","vcr_debugger.log"), 'w')
+  c.configure_rspec_metadata!
+  c.allow_http_connections_when_no_cassette = true
+end
+
+WebMock.allow_net_connect!
+
+Dir[File.expand_path("spec/support/**/*.rb", __FILE__)].each {|f| require f}
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.order                                           = "random"
+end