rundeck-ruby 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c0b2b8b341f0873b0ca2a5f5d38f75dc2ba99d4e
+  data.tar.gz: c03843110188e81e43939b5fe4b737c17c98b095
+SHA512:
+  metadata.gz: 92f5845c06eb9fde084af309ce89ca4a7aee5386c2f09848e86afa72df74e7ca7a26505c77a5651b9b3a107281bfe6bc9a91713e6da809fccd2fa758f39efaa9
+  data.tar.gz: 789262397ce473570fca1f4821bbcfe581a83295d403771ec3bc432e9573a5bcdb2d00b69c7c0d6a8a3bec879f2962cbd98f16597998912a0a1dfdb900762a81

data/.gitignore

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

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jon Phillips
+
+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,183 @@
+# Rundeck-ruby
+
+Like the name says, these are ruby bindings for the rundeck API
+
+## Installation
+
+The usual stuff: 
+
+Add this line to your application's Gemfile:
+
+    gem 'rundeck-ruby'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rundeck-ruby
+
+## Getting started
+
+So, you're not going to be using your username and password in this
+library. Instead it uses rundeck's token-based authentication for
+everything. See [the API docs](http://rundeck.org/docs/api/#token-authentication) for
+instructions about generating a token.
+
+## Command-line usage
+
+This gem installs a binstub named `rundeck`.
+Surprising, huh? Anyway, `rundeck` does one thing: execute jobs. Oh, you
+want more? Well then, send a pull request, buddy.
+
+The USAGE line:
+```
+rundeck exec <url> <token> <job guid> [<exec args>]
+```
+
+For example
+```
+$ rundeck exec https://my.server afdDSFasdfASD4334fasdfaasWERsW23423
+cd51b400-aad2-0131-c7f8-0438353e293e -arg0 1234 - arg1 blah
+https://my.server/executions/1234
+```
+
+That will connect to your rundeck server `my.server` using your auth
+token, find job cd51b400-aad2-0131-c7f8-0438353e293e and execute it. It
+prints out the url of the resulting execution.
+
+"But that's a lot of parameters," you say? Well, if you've got a better idea, submit a pull request. Also, you're probably going to `alias` common executions anyway, so it's really not too bad.
+
+## Library usage
+
+### Connecting
+
+Connections to your rundeck server are handled with the `Session` class.
+Like so:
+```
+require 'rundeck-ruby'
+session = Rundeck::Session('https://my.server', 'my token')
+```
+That's it. You have a session.
+
+From there you can get a hash of some of the server's system information:
+```
+info_hash = session.system_info
+```
+
+### Listing Projects
+The other thing the session lets you do get an array of your projects:
+```
+names = session.projects.map(&:name)
+```
+
+To get a single project, any of these will work:
+```
+project = session.projects.find{|p| p.name == "ReallyImportantProject"}
+project = session.project("ReallyImportantProject")
+project = Rundeck::Project.find(session, "ReallyImportantProject")
+```
+
+### Listing Jobs
+From each project, you can get a list of jobs. This code:
+```
+session.projects.first.jobs.map(&:name)
+```
+will give you a list of jobs in the project.
+
+You can get a single job object from the project in any of these ways:
+```
+job = project.jobs.find{|j| j.name == "MyJob"} # When you only have the name
+job = project.job_by_id(the_job_guid)
+```
+
+You can skip right over the project and go straight to the job too:
+```
+job = Rundeck::Job.find(session, the_job_guid)
+```
+
+### Executing a job
+Once you have a job object, you can work with its executions. To execute
+the job, do this:
+```
+execution = job.execute!("some fancy job arguments")
+```
+
+### Finding executions
+
+To get all executions from a job, do this:
+```
+executions = job.executions
+```
+
+If your rundeck is like mine, then there will be a boatload of executions in
+each job, so getting all of them will be a pain. Unnecessary, too. To
+filter down the results, do this:
+```
+active_executions = job.executions do |query|
+  query.status = :failed
+  query.max = 2
+  query.offset = 100
+end
+```
+It does what it looks like.
+
+...or, for the whole project:
+```
+active_executions = Rundeck::Execution.where(project) do |query|
+  query.status = :failed
+  query.max = 2
+  query.offset = 100
+end
+```
+
+To get the valid statuses, ask the query object:
+```
+statuses = []
+active_executions = job.executions do |query|
+  statuses = query.class.valid_statuses
+end
+puts statuses
+```
+Spoiler: they're one of the following: `succeeded`, `failed`, `aborted`, `running`, or `nil`.
+
+### Execution output
+To get the output from an execution, ask it:
+```
+output = execution.output
+```
+
+`output` will be a hash containing the following keys: `id`,
+`completed`, `hasFailedNodes`, `log`. `log` will, in turn, be a hash of
+hostnames to log entries, which will be self-explanatory
+
+## Contributing
+
+The usual boilerplate:
+
+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
+
+## Wishlist
+
+If you want to contribute, here's what I'd like to do sooner rather than
+later:
+
+* Add execution tailing to the `rundeck` binstub, à la:
+
+```
+rundeck tail <execution url> <token>
+```
+
+...or...
+
+```
+rundeck exec -tail ...the other parameters...
+```
+
+* Running ad-hoc commands, both in irb and with the binstub
+

data/Rakefile

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

data/exe/rundeck

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'rundeck-ruby'
+action, url, key, job, *exec_args = ARGV
+
+abort "I can only execute. Other stuff may be added later." unless action.downcase == "exec"
+
+sess = Rundeck::Session.new(url, key)
+j = Rundeck::Job.find(sess, job)
+encoded_args = URI::encode(exec_args.join(' '))
+arg_query = encoded_args && "argString=#{encoded_args}"
+puts j.execute!(arg_query).url

data/lib/rundeck-ruby.rb

@@ -0,0 +1,6 @@
+require "rundeck-ruby/maybe"
+require "rundeck-ruby/version"
+require "rundeck-ruby/session"
+require "rundeck-ruby/project"
+require "rundeck-ruby/job"
+require "rundeck-ruby/execution"

data/lib/rundeck-ruby/execution.rb

@@ -0,0 +1,83 @@
+module Rundeck
+  class Execution
+    def self.from_hash(session, hash)
+      job = Job.from_hash(session, hash['job'])
+      new(session, hash, job)
+    end
+
+    def initialize(session, hash, job)
+      @id = hash['id']
+      @url=hash['href']
+      @url = URI.join(session.server, URI.split(@url)[5]).to_s if @url # They always return a url of "localhost" for their executions. Replace it with the real URL
+      @status=hash['status'].to_sym
+      @date_started = hash['date_started']
+      @date_ended = hash['date_ended']
+      @user = hash['user']
+      @args = (hash['argstring'] || "").split
+                                      .each_slice(2)
+                                      .reduce({}){|acc,cur| acc[cur[0]] = cur[1]; acc}
+      @job = job
+      @session = session
+    end
+    attr_reader :id, :url, :status, :date_started, :date_ended, :user, :args, :job, :session
+
+    def self.find(session, id)
+      result = session.get("api/1/execution/#{id}", *%w(result executions execution))
+      return nil unless result
+      job = Job.find(session, result['job']['id'])
+      return nil unless job
+      Execution.new(session, result, job)
+    end
+
+    def self.where(project)
+      qb = QueryBuilder.new
+      yield qb if block_given?
+
+      endpoint = "api/5/executions?project=#{project.name}#{qb.query}"
+      pp endpoint
+      results = project.session.get(endpoint, 'result', 'executions', 'execution') || []
+      results = [results] if results.is_a?(Hash) #Work around an inconsistency in the API
+      results.map {|hash| from_hash(project.session, hash)}
+    end
+
+    def output
+      ret = session.get("api/9/execution/#{id}/output")
+      result = ret['result']
+      raise "API call not successful" unless result && result['success']=='true'
+
+      #sort the output by node
+      ret = result['output'].slice(*%w(id completed hasFailedNodes))
+      ret['log'] = result['output']['entries']['entry'].group_by{|e| e['node']}
+      ret
+    end
+
+    class QueryBuilder
+      attr_accessor :status, :max, :offset
+
+      def self.valid_statuses
+        %w(succeeded failed aborted running) << nil
+      end
+
+      def validate
+        raise "Invalid requested status: #{status}" unless status.nil? || elf.class.valid_statuses.include?(status.to_s)
+        raise "Invalid offset: #{offset}" unless offset.nil? || offset.to_i >= 0
+        raise "Invalid max: #{max}" unless max.nil? || max.to_i >= 0
+      end
+
+      def query
+        validate
+
+        [
+          "",
+          status && "statusFilter=#{status}",
+          max && "max=#{max.to_i}",
+          offset && "offset=#{offset.to_i}",
+        ].compact
+          .join("&")
+          .chomp("&")
+      end
+    end
+
+  end
+end
+

data/lib/rundeck-ruby/job.rb

@@ -0,0 +1,68 @@
+module Rundeck
+  class Job
+
+    def self.find(session, id)
+      result = session.get("api/1/job/#{id}", 'joblist', 'job')
+      return nil unless result
+      project = Project.find(session, result['context']['project'])
+      return nil unless project
+      Job.new(session, project, result['id'], result['name'])
+    end
+
+    def self.from_hash(session, hash)
+      project = Project.find(session, hash['project'])
+      new(session, project, hash['id'], hash['name'])
+    end
+
+    def initialize(session, project, id, name)
+      @session = session
+      @project = project
+      @id = id
+      @name = name
+    end
+
+    attr_reader :id, :name, :project, :session
+
+    def executions
+      qb = JobExecutionQueryBuilder.new
+      yield qb if block_given?
+
+      endpoint = "api/1/job/#{id}/executions#{qb.query}"
+      results = session.get(endpoint, 'result', 'executions', 'execution') || []
+      results = [results] if results.is_a?(Hash) #Work around an inconsistency in the API
+      results.map{|hash| Execution.from_hash(session, hash)}
+    end
+
+    def execute!(query_string = '')
+      query = "api/1/job/#{id}/run?#{query_string}".chomp("?")
+      hash = session.get(query, 'result', 'executions', 'execution') || {}
+      Execution.new(session, hash, self)
+    end
+
+    class JobExecutionQueryBuilder
+      attr_accessor :status, :max, :offset
+
+      def self.valid_statuses
+        Execution::QueryBuilder.valid_statuses
+      end
+
+      def validate
+        raise "Invalid requested status: #{status}" unless status.nil? || self.class.valid_statuses.include?(status.to_s)
+        raise "Invalid offset" unless offset.nil? || offset.to_i >= 0
+        raise "Invalid max" unless max.nil? || max.to_i >= 0
+      end
+
+      def query
+        validate
+
+        clauses = [
+          status && "status=#{status}",
+          max && "max=#{max.to_i}",
+          offset && "offset=#{offset.to_i}",
+        ].compact.join('&')
+
+        "?#{clauses}".chomp('?')
+      end
+    end
+  end
+end

data/lib/rundeck-ruby/maybe.rb

@@ -0,0 +1,5 @@
+require 'naught'
+
+NullObject = Naught.build
+
+include NullObject::Conversions

data/lib/rundeck-ruby/project.rb

@@ -0,0 +1,30 @@
+module Rundeck
+  class Project
+    def self.all(session)
+      @all ||= begin
+                 result = session.get('api/3/projects', 'result', 'projects', 'project') || []
+                 result.map{|hash| Project.new(session, hash)}
+               end
+    end
+
+    def self.find(session, name)
+      all(session).first{|p| p.name == name}
+    end
+
+    def initialize(session, hash)
+      @session = session
+      @name = hash['name']
+    end
+    attr_reader :session, :name
+
+    def jobs(force_reload = false)
+      return @jobs unless @jobs.nil? || force_reload
+      result = session.get("api/2/jobs?project=#{name}", 'result', 'jobs', 'job') || []
+      @jobs = result.map{|hash| Job.from_hash(session, hash)}
+    end
+
+    def job(id)
+      jobs.first{|j| j.id == id}
+    end
+  end
+end

data/lib/rundeck-ruby/session.rb

@@ -0,0 +1,34 @@
+require 'json'
+require 'active_support/all'
+require 'rest_client'
+
+
+module Rundeck
+  class Session
+    def initialize(server, token)
+      @server = server
+      @token = token
+    end
+
+    attr_reader :server, :token
+
+    def get(url, *keys)
+      endpoint = File.join(server, url)
+      xml = RestClient.get(endpoint, 'X-Rundeck-Auth-Token'=> token)
+      hash = Maybe(Hash.from_xml(xml))
+      keys.reduce(hash){|acc, cur| acc && acc[cur]}
+    end
+
+    def system_info
+      get('api/1/system/info', 'result', 'system')
+    end
+
+    def projects
+      Project.all(self)
+    end
+
+    def project(name)
+      Project.find(self, name)
+    end
+  end
+end

data/lib/rundeck-ruby/version.rb

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

data/rundeck-ruby.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rundeck-ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rundeck-ruby"
+  spec.version       = Rundeck::VERSION
+  spec.authors       = ["Jon Phillips"]
+  spec.email         = ["jphillips@biaprotect.com"]
+  spec.description   = %q{Ruby client for Rundeck API}
+  spec.summary       = %q{For talking to Rundeck}
+  spec.homepage      = "https://github.com/jonp/rundeck-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+  spec.bindir        = 'exe'
+  spec.executables   = `git ls-files -- exe/*`.split("\n").map{ |f| File.basename(f) }
+  spec.add_runtime_dependency "rest-client", "~> 1.6"
+  spec.add_runtime_dependency "json", "~> 1.8"
+  spec.add_runtime_dependency "activesupport", "~> 3.0"
+  spec.add_runtime_dependency "i18n", "~> 0.6"
+  spec.add_runtime_dependency "naught", "~> 1.0"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: rundeck-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jon Phillips
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2014-04-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: json
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: i18n
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: naught
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: bundler
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: rake
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  prerelease: false
+  type: :development
+description: Ruby client for Rundeck API
+email:
+- jphillips@biaprotect.com
+executables:
+- rundeck
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/rundeck
+- lib/rundeck-ruby.rb
+- lib/rundeck-ruby/execution.rb
+- lib/rundeck-ruby/job.rb
+- lib/rundeck-ruby/maybe.rb
+- lib/rundeck-ruby/project.rb
+- lib/rundeck-ruby/session.rb
+- lib/rundeck-ruby/version.rb
+- rundeck-ruby.gemspec
+homepage: https://github.com/jonp/rundeck-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.2.2
+signing_key:
+specification_version: 4
+summary: For talking to Rundeck
+test_files: []