rundeck 0.0.3.pre → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c88f0666b4b89351a6e9c34f7769036936f5cf8
-  data.tar.gz: 9f7c1c30d0ece66d6dcfb297422e5b38d2e31ee2
+  metadata.gz: ff00bf23f1fde03b1f603132d506ae0695e02827
+  data.tar.gz: fb4a1f1a7b74dac64e73e03a5c23d2acdd089d99
 SHA512:
-  metadata.gz: 34e9d290de610879d9041338456b593e5e4ca57c40d77d0007bb0c5aefbf7e2bc05f8568b59647628dc38c3ccbcb1aed7d5c3cfe0691f393b54fb3e5d1f6eeea
-  data.tar.gz: ea34452acb80ed0782d9e5235ddb84c7083ae2d9377dc4fe80bf15c4b8bbdc8ac6b63f23b562bd0717b5e1d53a25e06146608cf07d3fa7a838efc5b55132e894
+  metadata.gz: c51e3995a9bb9ac36d5fe7522e9e98ca6d685b65d6b11b9fbf453c32c34883852976651fedf0fbf85b1fbf70d84291629681fca273ad358bdfc8c224ac57c3d9
+  data.tar.gz: 57094ebfae59988afb663fadda7ae78e0244feda93da93dc77e586dad0f20f08787999ede8de7a73014a7ff211b23eaf427fa1809a2b2ec872eb77eb2cfd9018

data/.rubocop.yml

@@ -5,3 +5,13 @@ inherit_from: .rubocop_todo.yml
 # Lots of crappy false-positives from this cop. Go home!
 GuardClause:
   Enabled: false
+
+# Sometimes the method is legitimately longer but not complex.
+# See spec/support/helpers.rb#job_xml
+Metrics/MethodLength:
+  Max: 30
+
+# I am a big fan of lines 80 chars and less. However, in some cases it makes
+# sense to let the line exceed that length, especially in specs.
+Metrics/LineLength:
+  Max: 500

data/.rubocop_todo.yml

@@ -9,16 +9,6 @@
 Metrics/CyclomaticComplexity:
   Max: 10
 
-# Offense count: 1
-# Configuration parameters: AllowURI.
-Metrics/LineLength:
-  Max: 159
-
-# Offense count: 1
-# Configuration parameters: CountComments.
-Metrics/MethodLength:
-  Max: 12
-
 # Offense count: 2
 Style/Documentation:
   Severity: warning

data/.travis.yml

@@ -5,7 +5,7 @@ rvm:
   - 2.1
 script:
   - bundle exec rake
-#  - bundle exec rubocop
+  - bundle exec rubocop
 addons:
   code_climate:
     repo_token: 2aea108baa65d08ea87fb2371ec22a1741cb760027b8605bdabd5e153e595f4c

data/lib/rundeck/client.rb

@@ -1,15 +1,73 @@
 module Rundeck
   # Wrapper for the Rundeck REST API.
   class Client < API
+    # Macros to simplify client method documentation.
+
+    # @!macro [new] options
+    #   @param  [Hash] options A set of options passed directly to HTTParty. See
+    #     http://rubydoc.info/gems/httparty/HTTParty/ClassMethods
+    #   @option options [Hash] :query The parameters to pass with the request
+    #      Use this hash to specify Rundeck parameters.
+    #      - +query: { project: 'anvils', id: '123456' }+
+
+    # @!macro [new] exceptions
+    #   @raise [Rundeck::Error::BadRequest] 400 error - Most likely indicates a
+    #     required parameter is missing.
+    #   @raise [Rundeck::Error::Unauthorized] 401 error - Unauthorized
+    #   @raise [Rundeck::Error::Forbidden] 403 forbidden - ACL policies prevent
+    #     accessing the given resource
+    #   @raise [Rundeck::Error::NotFound] 404 not found - Indicates a resource
+    #     could not be found at the location
+    #   @raise [Rundeck::Error::MethodNotAllowed] 405 method not allowed - The
+    #     request method is not allowed. This probably indicates a
+    #     misconfiguration in a reverse proxy, such as Nginx or Apache
+    #   @raise [Rundeck::Error::Conflict] 409 conflict - A conflicting resource
+    #     exists.
+    #   @raise [Rundeck::Error::InternalServerError] 500 server error -
+    #     Indicates the Rundeck server experienced an error.
+    #   @raise [Rundeck::Error::BadGateway] 502 bad gateway - Indicates
+    #     something probably isn't working right or is misconfigured on the
+    #     Rundeck server.
+    #   @raise [Rundeck::Error::ServiceUnavailable] 503 error - Indicates an
+    #     issue on the Rundeck server.
+
+    # @!macro [new] has_optional_params
+    #   @note This method has optional Rundeck parameters that can be passed
+    #     to the options parameter. See Rundeck API documentation
+    #     for more information.
+    #     - +query: { param1: 'value', param2: 'value' }+
+
+    # @!macro [new] has_required_params
+    #   @note This method has required Rundeck parameters that can be passed
+    #     to the options parameter. See Rundeck API documentation
+    #     for more information.
+    #     - +query: { param1: 'value', param2: 'value' }+
+
+    # @!macro [new] has_required_and_optional_params
+    #   @note This method has both required and optional Rundeck parameters that
+    #     can be passed to the options parameter. See Rundeck API documentation
+    #     for more information.
+    #     - +query { param1: 'value', param2: 'value' }+
+
     Dir[File.expand_path('../client/*.rb', __FILE__)].each { |f| require f }
 
-    include Jobs
-    include Keys
+    include Execution
+    include Job
+    include Key
 
+    # Turn a hash into an object for easy accessibility.
+    #
+    # @note This method will objectify nested hashes/arrays.
+    #
+    # @param  [Hash, Array] result An array or hash of results to turn into
+    #   an object
+    # @return [Rundeck::ObjectifiedHash] if +result+ was a hash
+    # @return [Rundeck::ObjectifiedHash] if +result+ was an array
+    # @raise  [Array<Rundeck::Error::Parsing>] Error objectifying array or hash
     def objectify(result)
       if result.is_a?(Hash)
         ObjectifiedHash.new(result)
-      elsif result.is_a? Array
+      elsif result.is_a?(Array)
         result.map! { |e| ObjectifiedHash.new(e) }
       elsif result.nil?
         nil

data/lib/rundeck/client/execution.rb

@@ -0,0 +1,194 @@
+module Rundeck
+  class Client
+    # Defines methods related to executions.
+    module Execution
+      # Execute a job
+      #
+      # @!macro has_optional_params
+      #
+      # @see http://rundeck.org/docs/api/index.html#running-a-job
+      #   Rundeck API documentation for 'POST /api/12/job/[ID]/executions'
+      #   endpoint
+      #
+      # @example
+      #   Rundeck.execute_job('c07518ef-b697-4792-9a59-5b4f08855b67')
+      #   Rundeck.run_job('c07518ef-b697-4792-9a59-5b4f08855b67')
+      #
+      # @param  [String] id Job id
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def execute_job(id, options = {})
+        objectify post("/job/#{id}/executions", options)['result']['executions']['execution']
+      end
+      alias_method :run_job, :execute_job
+
+      # Get executions for a specific job.
+      #
+      # @!macro has_optional_params
+      #
+      # @see http://rundeck.org/docs/api/index.html#getting-executions-for-a-job
+      #   Rundeck API documentation for 'GET /api/1/job/[ID]/executions'
+      #   endpoint
+      #
+      # @example
+      #   Rundeck.job_executions('c07518ef-b697-4792-9a59-5b4f08855b67')
+      #
+      # @param  [String] id Job id
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def job_executions(id, options = {})
+        r = get("/job/#{id}/executions", options)['result']['executions']['execution']
+        objectify r
+      end
+
+      # Get all running job executions
+      #
+      # @!macro has_required_params
+      #
+      # @see http://rundeck.org/docs/api/index.html#listing-running-executions
+      #   Rundeck API documentation for 'GET /api/1/executions/running' endpoint
+      #
+      # @example
+      #   Rundeck.running_job_executions('anvils')
+      #
+      # @param  [String] project List running executions from this project
+      # @!macro options
+      # @return [nil] if no running executions
+      # @return [Rundeck::ObjectifiedHash] if a single running job execution
+      # @return [Array<Rundeck::ObjectifiedHash>] if multiple running job executions
+      # @!macro exceptions
+      # def running_job_executions(project, options = {})
+      #   options[:query] = {} if options[:query].nil?
+      #   options[:query]['project'] = project
+      #   r = get('/executions/running', options)
+      #
+      #   if objectify(r['result']['executions']).count != '0'
+      #     objectify r['result']['executions']['execution']
+      #   else
+      #     nil
+      #   end
+      # end
+
+      # Delete all executions for a specific job
+      #
+      # @see http://rundeck.org/docs/api/index.html#delete-all-executions-for-a-job
+      #   Rundeck API documentation for 'DELETE /api/12/job/[ID]/executions'
+      #   endpoint
+      #
+      # @example
+      #   Rundeck.delete_job_executions('c07518ef-b697-4792-9a59-5b4f08855b67')
+      #
+      # @param  [String] id Job id
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def delete_job_executions(id, options = {})
+        objectify delete("/job/#{id}/executions", options)['deleteExecutions']
+      end
+
+      # Delete an execution
+      #
+      # @see http://rundeck.org/docs/api/index.html#delete-an-execution
+      #   Rundeck API documentation for 'DELETE /api/12/execution/[ID]' endpoint
+      #
+      # @param  [String] id Execution id
+      # @!macro options
+      # @return [nil] If the delete was successful
+      # @!macro exceptions
+      def delete_execution(id, options = {})
+        delete("/execution/#{id}", options)
+      end
+
+      # Abort a running execution
+      #
+      # @!macro has_optional_params
+      #
+      # @see http://rundeck.org/docs/api/index.html#aborting-executions
+      #   Rundeck API documentation for 'POST /api/1/execution/[ID]/abort'
+      #   endpoint
+      #
+      # @param  [String] id Execution id
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def abort_execution(id, options = {})
+        objectify post("/execution/#{id}/abort", options)['abort']
+      end
+
+      # Get info for an execution
+      #
+      # @see http://rundeck.org/docs/api/index.html#execution-info
+      #   Rundeck API documentation for 'GET /api/1/execution/[ID]' endpoint
+      #
+      # @example
+      #   Rundeck.execution('c07518ef-b697-4792-9a59-5b4f08855b67'')
+      #
+      # @param  [String] id Execution id
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def execution(id, options = {})
+        objectify get("/execution/#{id}", options)['result']['executions']['execution']
+      end
+
+      # Bulk delete executions
+      #
+      # @see http://rundeck.org/docs/api/index.html#bulk-delete-executions
+      #   Rundeck API documentation for 'POST /api/12/executions/delete'
+      #
+      # @param  [String] ids An array of execution ids to delete
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @raise  [Rundeck::Error::InvalidAttribites] if ids is not an array
+      # @!macro exceptions
+      def bulk_delete_executions(ids, options = {})
+        unless ids.is_a?(Array)
+          fail Rundeck::Error::InvalidAttributes, '`ids` must be an array of ids'
+        end
+
+        options[:query] = {} if options[:query].nil?
+        options[:query].merge!(ids: ids.join(','))
+        objectify post('/executions/delete', options)['deleteExecutions']
+      end
+
+      # Get the state of an execution
+      #
+      # @see http://rundeck.org/docs/api/index.html#execution-state
+      #   Rundeck API documentation for 'GET /api/12/execution/[ID]/state'
+      #
+      # @param  [String] id Execution ID
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      def execution_state(id, options = {})
+        objectify get("/execution/#{id}/state", options)['result']['executionState']
+      end
+
+      # Query for executions based on job or execution details.
+      #
+      # @note This method maps to an advanced Rundeck endpoint. View the Rundeck
+      #   API documentation and understand what query parameters are required.
+      #   Responses may include paging details. Recall this method with the
+      #   next set of paging values to retrieve more elements.
+      #
+      # @see http://rundeck.org/docs/api/index.html#execution-query
+      #   Rundeck API documentation for 'GET /api/12/executions'
+      # def execution_query(project, options = {})
+      #   options[:query] = {} if options[:query].nil?
+      #   options[:query]['project'] = project
+      #
+      #   objectify get('/executions', options)['result']
+      # end
+
+      # def execution_output()
+      #
+      # end
+      #
+      # def execution_output_with_state()
+      #
+      # end
+    end
+  end
+end

data/lib/rundeck/client/{jobs.rb → job.rb}

@@ -1,15 +1,16 @@
 module Rundeck
   class Client
-    # Defines methods related to projects.
-    module Jobs
+    # Defines methods related to jobs.
+    module Job
       # Gets a list of jobs for a specific project.
       #
       # @example
       #   Rundeck.jobs('project')
       #
       # @param  [String] project Project name
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [Array<Rundeck::ObjectifiedHash>]
+      # @!macro exceptions
       def jobs(project, options = {})
         objectify get("/project/#{project}/jobs", options)['jobs']['job']
       end
@@ -19,49 +20,27 @@ module Rundeck
       # @example Rundeck.job('c07518ef-b697-4792-9a59-5b4f08855b67')
       #
       # @param  [String] id Job id
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
       def job(id, options = {})
         objectify get("/job/#{id}", options)['joblist']['job']
       end
 
       # Delete a job
       #
+      # @TODO: What does this return?!
+      #
       # @example
       #   Rundeck.delete_job('c07518ef-b697-4792-9a59-5b4f08855b67')
       #
       # @param  [String] id Job id
-      # @param  [Hash] options A set of options passed directly to HTTParty
-      # @return [Rundeck::ObjectifiedHash]
+      # @!macro options
+      # @!macro exceptions
       def delete_job(id, options = {})
         delete("/job/#{id}", options)
       end
 
-      # Get executions for a specific job
-      #
-      # @example
-      #   Rundeck.job_executions('c07518ef-b697-4792-9a59-5b4f08855b67')
-      #
-      # @param  [String] id Job id
-      # @param  [Hash] options A set of options passed directly to HTTParty
-      # @return [Rundeck::ObjectifiedHash]
-      def job_executions(id, options = {})
-        r = get("/job/#{id}/executions", options)['result']['executions']['execution']
-        objectify r
-      end
-
-      # Run a job
-      #
-      # @example
-      #   Rundeck.run_job('c07518ef-b697-4792-9a59-5b4f08855b67', 'DEBUG')
-      #
-      # @param  [String] id Job id
-      # @param  [Hash]   options A set of options passed directly to HTTParty
-      # @return [Rundeck::ObjectifiedHash]
-      def run_job(id, options = {})
-        objectify post("/job/#{id}/executions", options)['result']['executions']['execution']
-      end
-
       # Import a job or multiple jobs
       #
       # @example
@@ -78,9 +57,11 @@ module Rundeck
       #   Rundeck.import_jobs(job, 'xml')
       #
       # @param  [String] content The job definition(s) as yaml or xml
-      # @param  [String] format The import format. 'yaml|xml', defaults to 'yaml'
-      # @param  [Hash]   options A set of options passed directly to HTTParty
+      # @param  [String] format The import format. 'yaml|xml', defaults to
+      #   'yaml'
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
       def import_jobs(content, format = 'yaml', options = {})
         unless format =~ /yaml|xml/
           fail Error::InvalidAttributes, 'format must be yaml or xml'
@@ -101,9 +82,11 @@ module Rundeck
       #   Rundeck.export_jobs('project')
       #
       # @param  [String] project Project name
-      # @param  [String] format The export format. 'yaml|xml', defaults to 'yaml'
-      # @param  [Hash]   options A set of options passed directly to HTTParty
-      # @return [String]
+      # @param  [String] format The export format. Either 'yaml' or 'xml'
+      # @!macro options
+      # @return [String] a string representation of the job in either xml or
+      #   yaml
+      # @!macro exceptions
       def export_jobs(project, format = 'yaml', options = {})
         unless format =~ /yaml|xml/
           fail Error::InvalidAttributes, 'format must be yaml or xml'

data/lib/rundeck/client/{keys.rb → key.rb}

@@ -1,8 +1,10 @@
 module Rundeck
   class Client
     # Defines methods related to projects.
-    module Keys
+    module Key
+      # The endpoint for key storage
       STORAGE_KEYS_PATH = '/storage/keys'
+      private_constant :STORAGE_KEYS_PATH
 
       # Gets a list of keys at a specific path.
       #
@@ -10,12 +12,15 @@ module Rundeck
       #   Rundeck.keys('path')
       #
       # @param  [String] path A key storage path
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [Array<Rundeck::ObjectifiedHash>]
+      # @!macro exceptions
+      # @raise  [Rundeck::Error::InvalidAttributes] if the path is a direct key
+      #   path
       def keys(path = '', options = {})
         r = get("#{STORAGE_KEYS_PATH}/#{path}", options)
 
-        #         # In case a user provides a direct path to a key, error.
+        # In case a user provides a direct path to a key, error.
         if r['resource']['contents']
           objectify r['resource']['contents']['resource']
         else
@@ -31,8 +36,11 @@ module Rundeck
       #   Rundeck.key_metadata('path/to/key1')
       #
       # @param  [String] path A key storage path, including key name
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      # @raise  [Rundeck::Error::InvalidAttributes] if the path is a direct key
+      #   path
       def key_metadata(path, options = {})
         r = get("#{STORAGE_KEYS_PATH}/#{path}", options)
 
@@ -54,13 +62,15 @@ module Rundeck
       #   Rundeck.key_contents('path/to/key1')
       #
       # @param  [String] path A key storage path, including key name
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
       def key_contents(path, options = {})
         # Check if key exists first. Otherwise we could return some
         # weird strings. Also, raise error if user is trying to get a
         # private key.
-        if key_metadata(path, options).rundeck_key_type == 'private'
+        key_content_type = key_metadata(path, options).rundeck_content_type
+        if key_content_type == content_type('private')
           fail Error::Unauthorized,
                'You are not allowed to retrieve the contents of a private key'
         end
@@ -79,8 +89,9 @@ module Rundeck
       #
       # @param  [String] path A key storage path
       # @param  [String] key The entire private key value
-      # @param  [Hash] options A set of options passed directory to HTTParty
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
       def create_private_key(path, key, options = {})
         create_or_update_key(path, key, 'private', 'post', options)
       end
@@ -93,11 +104,13 @@ module Rundeck
       #
       # @param  [String] path A key storage path
       # @param  [String] key The entire private key value
-      # @param  [Hash] options A set of options passed directory to HTTParty
+      # @!macro options
       # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      # @raise  [Rundeck::Error::NotFound] if the key was not found
       def update_private_key(path, key, options = {})
         key_check(path, 'private', options)
-        create_or_update_key(path, key, 'public', 'put', options)
+        create_or_update_key(path, key, 'private', 'put', options)
       end
 
       # Create a public key
@@ -108,8 +121,9 @@ module Rundeck
       #
       # @param  [String] path A key storage path
       # @param  [String] key The entire private key value
-      # @param  [Hash] options A set of options passed directory to HTTParty
-      # @return [Array<Rundeck::ObjectifiedHash>]
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
       def create_public_key(path, key, options = {})
         create_or_update_key(path, key, 'public', 'post', options)
       end
@@ -122,8 +136,10 @@ module Rundeck
       #
       # @param  [String] path A key storage path
       # @param  [String] key The entire private key value
-      # @param  [Hash] options A set of options passed directory to HTTParty
-      # @return [Array<Rundeck::ObjectifiedHash>]
+      # @!macro options
+      # @return [Rundeck::ObjectifiedHash]
+      # @!macro exceptions
+      # @raise  [Rundeck::Error::NotFound] if the key was not foun
       def update_public_key(path, key, options = {})
         key_check(path, 'public', options)
         create_or_update_key(path, key, 'public', 'put', options)
@@ -135,17 +151,19 @@ module Rundeck
       #   Rundeck.delete_key('path/to/key')
       #
       # @param  [String] path A key storage path
-      # @param  [Hash] options A set of options passed directly to HTTParty
+      # @!macro options
       # @return [nil]
+      # @!macro exceptions
       def delete_key(path, options = {})
         delete("#{STORAGE_KEYS_PATH}/#{path}", options)
       end
 
       private
 
-      def key_check(path, type, options)
+      def key_check(path, key_type, options)
+        content_type = content_type(key_type)
         # Check existence and type
-        if key_metadata(path, options).rundeck_key_type != type
+        if key_metadata(path, options).rundeck_content_type != content_type
           fail Error::NotFound,
                "A #{type} key was not found at the specified path."
         end
@@ -163,10 +181,14 @@ module Rundeck
       end
 
       def key_type_headers(type, options)
-        if type == 'private'
-          options.merge!(headers: { 'Content-Type' => 'application/octet-stream' })
-        elsif type == 'public'
-          options.merge!(headers: { 'Content-Type' => 'application/pgp-key' })
+        options.merge!(headers: { 'Content-Type' => content_type(type) })
+      end
+
+      def content_type(key_type)
+        if key_type == 'private'
+          'application/octet-stream'
+        elsif key_type == 'public'
+          'application/pgp-key'
         else
           fail Error::InvalidAttributes,
                'Invalid key type specified. Must be public or private.'