jiraby 0.0.1

data/lib/jiraby/jira.rb

@@ -0,0 +1,319 @@
+# Builtin
+require 'enumerator'
+
+# Gems
+require 'rubygems'
+require 'yajl'
+require 'rest_client'
+
+# Local
+require 'jiraby/issue'
+require 'jiraby/project'
+require 'jiraby/exceptions'
+require 'jiraby/json_resource'
+
+module Jiraby
+  # Wrapper for Jira
+  class Jira
+    @@max_results = 50
+
+    # Initialize a Jira instance at the given URL.
+    #
+    # @param [String] url
+    #   Full URL of the JIRA instance to connect to. If this does not begin
+    #   with http: or https:, then http:// is assumed.
+    # @param [String] username
+    #   Jira username
+    # @param [String] password
+    #   Jira password
+    # @param [String] api_version
+    #   The API version to use. For now, only '2' is supported.
+    #
+    # TODO: Handle the case where the wrong API version is used for a given
+    # Jira instance (should give 404s when resources are requested)
+    #
+    def initialize(url, username, password, api_version='2')
+      if !known_api_versions.include?(api_version)
+        raise ArgumentError.new("Unknown Jira API version: #{api_version}")
+      end
+
+      # Prepend http:// and remove trailing slashes
+      url = "http://#{url}" if url !~ /https:|http:/
+      url.gsub!(/\/+$/, '')
+      @url = url
+
+      @credentials = {:user => username, :password => password}
+      @api_version = api_version
+      @_field_mapping = nil
+
+      # All REST API access is done through the @rest attribute
+      @rest = Jiraby::JSONResource.new(base_url, @credentials)
+    end #initialize
+
+    attr_reader :url, :api_version, :rest
+
+    # Return a list of known Jira API versions.
+    #
+    def known_api_versions
+      return ['2']
+    end #known_api_versions
+
+
+    # Return the URL for authenticating to Jira.
+    #
+    def auth_url
+      "#{@url}/rest/auth/1/session"
+    end #auth_url
+
+    def base_url
+      "#{@url}/rest/api/#{@api_version}"
+    end
+
+    # Raise an exception if the current API version is one of those listed.
+    #
+    # @param [String] feature
+    #   Name or short description of the feature in question
+    # @param [Array] api_versions
+    #   One or more version strings for Jira APIs that do not support the
+    #   feature in question
+    #
+    def not_implemented_in(feature, *api_versions)
+      if api_versions.include?(@api_version)
+        raise NotImplementedError,
+          "#{feature} not supported by version #{@api_version} of the Jira API"
+      end
+    end #not_implemented_in
+
+    # Return a URL query, suitable for use in a GET/DELETE/HEAD request
+    # that accepts queries like `?var1=value1&var2=value2`.
+    def _path_with_query(path, query={})
+      # TODO: Escape special chars
+      params = query.map {|k,v| "#{k}=#{v}"}.join("&")
+      if params.empty?
+        return path
+      else
+        return "#{path}?#{params}"
+      end
+    end
+
+    # REST wrapper methods returning Jiraby::Entity
+    def get(path, query={})
+      @rest[_path_with_query(path, query)].get
+    end
+
+    def delete(path, query={})
+      @rest[_path_with_query(path, query)].delete
+    end
+
+    def put(path, data)
+      @rest[path].put data
+    end
+
+    def post(path, data)
+      @rest[path].post data
+    end
+
+    # Find all issues matching the given JQL query, and return an
+    # `Enumerator` that yields each one as an Issue object.
+    # Each Issue is fetched from the REST API as needed.
+    #
+    # @param [String] jql_query
+    #   JQL query for the issues you want to match
+    #
+    # @return [Enumerator]
+    #
+    def search(jql_query)
+      params = {
+        :jql => jql_query,
+      }
+      issues = self.enumerator(:post, 'search', params, 'issues')
+      return Enumerator.new do |e|
+        issues.each do |data|
+          e << Issue.new(self, data)
+        end
+      end
+    end
+
+    # Return an Enumerator yielding items returned by a REST method that
+    # accepts `startAt` and `maxResults` parameters. This allows you to
+    # iterate through large data sets
+    #
+    # For example, using the issue `search` method to look up all issues
+    # in project "FOO", then using `each` to iterate over them:
+    #
+    #     query = 'project=FOO order by key'
+    #     jira.enumerator(
+    #       :post, 'search', {:jql => query}, 'issues'
+    #     ).each do |issue|
+    #       puts "#{issue.key}: #{issue.fields.summary}"
+    #     end
+    #
+    # The output might be:
+    #
+    #   FOO-1: First issue in Foo project
+    #   FOO-2: Another issue
+    #   (...)
+    #   FOO-149: Penultimate issue
+    #   FOO-150: Last issue
+    #
+    # Below is a complete list of Jira REST API methods that accept `startAt`
+    # and `maxResults`.
+    #
+    # Returning Entity:
+    #   GET /dashboard => { 'dashboards' => [...], 'total' => N } (dashboards)
+    #   GET /search => { 'issues' => [...], 'total' => N } (issues)
+    #   POST /search => { 'issues' => [...], 'total' => N } (issues)
+    #
+    # Returning Array of Entity:
+    #   GET /user/assignable/multiProjectSearch => [...] (users)
+    #   GET /user/assignable/search => [...] (users)
+    #   GET /user/permission/search => [...] (users)
+    #   GET /user/search => [...] (users)
+    #   GET /user/viewissue/search => [...] (users)
+    #
+    def enumerator(method, path, params={}, list_key=nil)
+      max_results = @@max_results
+      return Enumerator.new do |enum|
+        page = 0
+        more = true
+        while(more) do
+          paged_params = params.merge({
+            :startAt => page * max_results,
+            :maxResults => max_results
+          })
+          response = self.send(method, path, paged_params)
+
+          # Some methods (like 'search') return an Entity, with the list of
+          # items indexed by `list_key`.
+          if response.is_a?(Jiraby::Entity)
+            items = response[list_key]
+          # Others (like 'user/search') return an array of Entity.
+          elsif response.is_a?(Array)
+            items = response
+          else
+            raise RuntimeError.new("Unexpected data: #{response}")
+          end
+
+          items.to_a.each do |item|
+            enum << item
+          end
+
+          if items.to_a.count < max_results
+            more = false
+          else
+            page += 1
+          end
+        end # while(more)
+      end # Enumerator.new
+    end
+
+    # Return the Issue with the given key.
+    #
+    # @param [String] key
+    #   The issue's unique identifier (usually like PROJ-NNN)
+    #
+    # @return [Issue]
+    #   An Issue populated with data returned by the API
+    #
+    # @raise [IssueNotFound]
+    #   If the issue was not found or fetching failed
+    #
+    def issue(key)
+      if key.nil? || key.to_s.strip.empty?
+        raise ArgumentError.new("Issue key is required")
+      end
+      json = self.get "issue/#{key}"
+      if json and (json.empty? or json['errorMessages'])
+        raise IssueNotFound.new("Issue '#{key}' not found in Jira")
+      else
+        return Issue.new(self, json)
+      end
+    end #issue
+
+
+    # Create a new issue
+    #
+    # @param [String] project_key
+    #   Identifier for the project to create the issue under
+    # @param [String] issue_type
+    #   The name of an issue type. May be any issue types accepted by the given
+    #   project; typically "Bug", "Task", "Improvement", "New Feature", or
+    #   "Sub-task"
+    #
+    # @return [Issue]
+    #
+    def create_issue(project_key, issue_type='Bug')
+      issue_data = self.post 'issue', {
+        "fields" => {"project" => {"key" => project_key} }
+      }
+      return Issue.new(self, issue_data) if issue_data
+      return nil
+    end #create_issue
+
+
+    # Return the Project with the given key.
+    #
+    # @param [String] key
+    #   The project's unique identifier (usually like PROJ)
+    #
+    # @return [Project]
+    #   A Project populated with data returned by the API, or
+    #   nil if no such project is found.
+    #
+    def project(key)
+      json = self.get "project/#{key}"
+      if json and (json.empty? or json['errorMessages'])
+        raise ProjectNotFound.new("Project '#{key}' not found in Jira")
+      else
+        return Project.new(json)
+      end
+    end #project
+
+
+    # Return the 'createmeta' data for the given project key, or nil if
+    # the project is not found.
+    #
+    # TODO: Move this into the Project class?
+    #
+    def project_meta(project_key)
+      meta = self.get 'issue/createmeta?expand=projects.issuetypes.fields'
+      metadata = meta.projects.find {|proj| proj['key'] == project_key}
+      if metadata and !metadata.nil?
+        return metadata
+      else
+        raise ProjectNotFound.new("Project '#{project_key}' not found in Jira")
+      end
+    end #project_meta
+
+
+    # Return the total number of issues matching the given JQL query, or
+    # the count of all issues if no JQL query is given.
+    #
+    # @param [String] jql
+    #   JQL query for the issues you want to match
+    #
+    # @return [Integer]
+    #   Number of issues matching the query
+    #
+    def count(jql='')
+      result = self.post 'search', {
+        :jql => jql,
+        :startAt => 0,
+        :maxResults => 1,
+        :fields => [''],
+      }
+      return result.total
+    end #count
+
+
+    # Return a hash of 'field_id' => 'Field Name' for all fields
+    def field_mapping
+      if @_field_mapping.nil?
+        ids_and_names = self.get('field').collect { |f| [f.id, f.name] }
+        @_field_mapping = Hash[ids_and_names]
+      end
+      return @_field_mapping
+    end #field_mapping
+
+  end # class Jira
+end # module Jiraby

data/lib/jiraby/json_resource.rb

@@ -0,0 +1,136 @@
+require 'rest_client'
+require 'jiraby/entity'
+
+module Jiraby
+  class JSONParseError < RuntimeError
+    attr_reader :response
+
+    def initialize(message, response)
+      super(message)
+      @response = response
+    end
+  end
+
+  # A RestClient::Resource that expects JSON data from all requests, and
+  # wraps all JSON in native Ruby hashes so you don't have to parse it.
+  #
+  # Expectations:
+  #
+  # - All GET, HEAD, DELETE, PUT, POST, and PATCH requests to your REST API
+  #   will return a JSON string. With JSONResource, the #get, #head, #delete,
+  #   #put, #post, and #patch methods return a Hash (if the response is actually
+  #   JSON and can be parsed), or raise a JSONParseError if parsing fails.
+  #
+  # - All payloads (first argument to #put, #post, and #patch) are expected to
+  #   be JSON strings; you can provide the raw JSON string, or provide a Hash
+  #   and it will be automatically encoded as a JSON string.
+  #
+  # - All error responses from the REST API are expected to be JSON strings.
+  #   When an error occurs (such as 401, 404, 500 etc.), normally a
+  #   RestClient::Exception is raised. With JSONResource, the error response
+  #   is parsed as JSON and returned as a Hash; no exception is raised.
+  #
+  class JSONResource < RestClient::Resource
+    @@debug = false
+
+    def initialize(url, options={}, backwards_compatibility=nil, &block)
+      options[:headers] = {} if options[:headers].nil?
+      options[:headers].merge!(:content_type => :json, :accept => :json)
+      super(url, options, backwards_compatibility, &block)
+    end
+
+    # Aliases to RestClient::Resource methods
+    alias_method :_get, :get
+    alias_method :_delete, :delete
+    alias_method :_head, :head
+    alias_method :_post, :post
+    alias_method :_put, :put
+    alias_method :_patch, :patch
+
+    # Wrapped RestClient::Resource methods that accept and return Hash data
+    def get(additional_headers={}, &block)
+      wrap(:_get, additional_headers, &block)
+    end
+
+    def delete(additional_headers={}, &block)
+      wrap(:_delete, additional_headers, &block)
+    end
+
+    def head(additional_headers={}, &block)
+      wrap(:_head, additional_headers, &block)
+    end
+
+    def post(payload, additional_headers={}, &block)
+      wrap_with_payload(:_post, payload, additional_headers, &block)
+    end
+
+    def put(payload, additional_headers={}, &block)
+      wrap_with_payload(:_put, payload, additional_headers, &block)
+    end
+
+    def patch(payload, additional_headers={}, &block)
+      wrap_with_payload(:_patch, payload, additional_headers, &block)
+    end
+
+    # Wrap the given method to return a Hash response parsed from JSON
+    #
+    def wrap(method, additional_headers={}, &block)
+      puts "#{@url} wrap(#{method})" if @@debug
+      response = maybe_error_response do
+        send(method, additional_headers, &block)
+      end
+      return parsed_response(response)
+    end
+
+    # Wrap the given method to send a Hash payload, and return a Hash response
+    # parsed from JSON.
+    #
+    def wrap_with_payload(method, payload, additional_headers={}, &block)
+      puts "#{@url} wrap_with_payload(#{method}, #{payload})" if @@debug
+      if payload.is_a?(Hash)
+        payload = Yajl::Encoder.encode(payload)
+      end
+      response = maybe_error_response do
+        send(method, payload, additional_headers, &block)
+      end
+      return parsed_response(response)
+    end
+
+    # Parse `response` as JSON and return a Hash or array of Hashes.
+    # Raise `JSONParseError` if parsing fails.
+    #
+    def parsed_response(response)
+      begin
+        json = Yajl::Parser.parse(response)
+      rescue Yajl::ParseError => ex
+        # FIXME: Sometimes getting "input must be a string or IO" error here
+        raise JSONParseError.new(ex.message, response)
+      else
+        if json.is_a?(Hash)
+          return Entity.new(json)
+        elsif json.is_a?(Array)
+          return json.collect do |hash|
+            Entity.new(hash)
+          end
+        else
+          return nil
+        end
+      end
+    end
+
+    # Yield a response from the given block; if a `RestClient::Exception` is
+    # raised, return the exception's response instead.
+    #
+    def maybe_error_response(&block)
+      begin
+        yield
+      rescue RestClient::RequestTimeout => ex
+        raise ex
+      rescue RestClient::Exception => ex
+        ex.response
+      end
+    end
+
+  end # class JSONResource
+end # module Jiraby
+