gitlab 4.2.0 → 4.18.0

data/lib/gitlab/client/wikis.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to wikis.
+  # @see https://docs.gitlab.com/ce/api/wikis.html
+  module Wikis
+    # Get all wiki pages for a given project.
+    #
+    # @example
+    #   Gitlab.wikis(3)
+    #   Gitlab.wikis(3, {with_content: 'Some wiki content'})
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] with_content(optional) Include pages content
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def wikis(project, options = {})
+      get("/projects/#{url_encode project}/wikis", query: options)
+    end
+
+    # Get a wiki page for a given project.
+    #
+    # @example
+    #   Gitlab.wiki(3, 'home')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page
+    # @return [Gitlab::ObjectifiedHash]
+    def wiki(project, slug)
+      get("/projects/#{url_encode project}/wikis/#{slug}")
+    end
+
+    # Creates a new wiki page for the given repository with the given title, slug, and content.
+    #
+    # @example
+    #   Gitlab.create_wiki(3, 'Some Title', 'Some Content')
+    #   Gitlab.create_wiki(3, 'Some Title', 'Some Content', { format: 'rdoc' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] content The content of the wiki page.
+    # @param  [String] title The title of the wiki page.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] format (optional) The format of the wiki page. Available formats are: markdown (default), rdoc, and asciidoc.
+    # @return [Gitlab::ObjectifiedHash] Information about created wiki page.
+    def create_wiki(project, title, content, options = {})
+      body = { content: content, title: title }.merge(options)
+      post("/projects/#{url_encode project}/wikis", body: body)
+    end
+
+    # Updates an existing wiki page. At least one parameter is required to update the wiki page.
+    #
+    # @example
+    #   Gitlab.update_wiki(6, 'home', { title: 'New title' })
+    #   Gitlab.update_wiki(6, 'home', { title: 'New title', content: 'New Message', format: 'rdoc' })
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] content The content of the wiki page.
+    # @option options [String] title The title of the wiki page.
+    # @option options [String] format (optional) The format of the wiki page. Available formats are: markdown (default), rdoc, and asciidoc.
+    # @return [Gitlab::ObjectifiedHash] Information about updated wiki page.
+    def update_wiki(project, slug, options = {})
+      put("/projects/#{url_encode project}/wikis/#{slug}", body: options)
+    end
+
+    # Deletes a wiki page with a given slug.
+    #
+    # @example
+    #   Gitlab.delete_wiki(42, 'foo')
+    #
+    # @param  [Integer, String] project The ID or name of a project.
+    # @param  [String] slug The slug (a unique string) of the wiki page.
+    # @return [Gitlab::ObjectifiedHash] An empty objectified hash
+    def delete_wiki(project, slug)
+      delete("/projects/#{url_encode project}/wikis/#{slug}")
+    end
+  end
+end

data/lib/gitlab/client.rb

@@ -1,58 +1,95 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Wrapper for the Gitlab REST API.
   class Client < API
-    Dir[File.expand_path('../client/*.rb', __FILE__)].each { |f| require f }
+    Dir[File.expand_path('client/*.rb', __dir__)].each { |f| require f }
 
+    # Please keep in alphabetical order
+    include AccessRequests
+    include ApplicationSettings
+    include Avatar
     include AwardEmojis
     include Boards
     include Branches
-    include Builds
+    include BroadcastMessages
     include BuildVariables
+    include Builds
     include Commits
+    include ContainerRegistry
+    include Deployments
     include Environments
+    include EpicIssues
+    include Epics
+    include Events
+    include Features
+    include GroupBadges
+    include GroupBoards
+    include GroupLabels
+    include GroupMilestones
     include Groups
+    include IssueLinks
     include Issues
+    include Jobs
     include Keys
     include Labels
+    include Lint
+    include Markdown
+    include MergeRequestApprovals
     include MergeRequests
     include Milestones
     include Namespaces
     include Notes
-    include Pipelines
+    include PipelineSchedules
     include PipelineTriggers
+    include Pipelines
+    include ProjectBadges
+    include ProjectClusters
+    include ProjectReleaseLinks
+    include ProjectReleases
     include Projects
+    include ProtectedTags
+    include RemoteMirrors
     include Repositories
     include RepositoryFiles
+    include RepositorySubmodules
+    include ResourceLabelEvents
+    include ResourceStateEvents
     include Runners
+    include Search
     include Services
+    include Sidekiq
     include Snippets
     include SystemHooks
     include Tags
+    include Templates
     include Todos
     include Users
-    include Jobs
+    include UserSnippets
+    include Versions
+    include Wikis
 
     # Text representation of the client, masking private token.
     #
     # @return [String]
     def inspect
       inspected = super
-
-      if @private_token
-        inspected = inspected.sub! @private_token, only_show_last_four_chars(@private_token)
-      end
-
+      inspected.sub! @private_token, only_show_last_four_chars(@private_token) if @private_token
       inspected
     end
 
-    def url_encode(s)
-      ERB::Util.url_encode(s)
+    # Utility method for URL encoding of a string.
+    # Copied from https://ruby-doc.org/stdlib-2.7.0/libdoc/erb/rdoc/ERB/Util.html
+    #
+    # @return [String]
+    def url_encode(url)
+      url.to_s.b.gsub(/[^a-zA-Z0-9_\-.~]/n) { |m| sprintf('%%%02X', m.unpack1('C')) } # rubocop:disable Style/FormatString
     end
 
     private
 
     def only_show_last_four_chars(token)
-      "#{'*'*(token.size - 4)}#{token[-4..-1]}"
+      "#{'*' * (token.size - 4)}#{token[-4..-1]}"
     end
   end
 end

data/lib/gitlab/configuration.rb

@@ -1,17 +1,19 @@
+# frozen_string_literal: true
+
 require 'gitlab/cli_helpers'
 module Gitlab
   # Defines constants and methods related to configuration.
   module Configuration
     # An array of valid keys in the options hash when configuring a Gitlab::API.
-    VALID_OPTIONS_KEYS = [:endpoint, :private_token, :user_agent, :sudo, :httparty].freeze
+    VALID_OPTIONS_KEYS = %i[endpoint private_token user_agent sudo httparty].freeze
 
     # The user agent that will be sent to the API endpoint if none is set.
-    DEFAULT_USER_AGENT = "Gitlab Ruby Gem #{Gitlab::VERSION}".freeze
+    DEFAULT_USER_AGENT = "Gitlab Ruby Gem #{Gitlab::VERSION}"
 
     # @private
     attr_accessor(*VALID_OPTIONS_KEYS)
     # @private
-    alias_method :auth_token=, :private_token=
+    alias auth_token= private_token=
 
     # Sets all configuration options to their default values
     # when this module is extended.
@@ -33,7 +35,7 @@ module Gitlab
 
     # Resets all configuration options to the defaults.
     def reset
-      self.endpoint       = ENV['GITLAB_API_ENDPOINT']
+      self.endpoint       = ENV['GITLAB_API_ENDPOINT'] || ENV['CI_API_V4_URL']
       self.private_token  = ENV['GITLAB_API_PRIVATE_TOKEN'] || ENV['GITLAB_API_AUTH_TOKEN']
       self.httparty       = get_httparty_config(ENV['GITLAB_API_HTTPARTY_OPTIONS'])
       self.sudo           = nil
@@ -44,11 +46,11 @@ module Gitlab
 
     # Allows HTTParty config to be specified in ENV using YAML hash.
     def get_httparty_config(options)
-      return options if options.nil?
+      return if options.nil?
 
       httparty = Gitlab::CLI::Helpers.yaml_load(options)
+      raise ArgumentError, 'HTTParty config should be a Hash.' unless httparty.is_a? Hash
 
-      raise ArgumentError, "HTTParty config should be a Hash." unless httparty.is_a? Hash
       Gitlab::CLI::Helpers.symbolize_keys httparty
     end
   end

data/lib/gitlab/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gitlab
   module Error
     # Custom error class for rescuing from all Gitlab errors.
@@ -11,38 +13,83 @@ module Gitlab
 
     # Custom error class for rescuing from HTTP response errors.
     class ResponseError < Error
+      POSSIBLE_MESSAGE_KEYS = %i[message error_description error].freeze
+
       def initialize(response)
         @response = response
         super(build_error_message)
       end
 
-      # Status code returned in the http response.
+      # Status code returned in the HTTP response.
       #
       # @return [Integer]
       def response_status
         @response.code
       end
 
+      # Body content returned in the HTTP response
+      #
+      # @return [String]
+      def response_message
+        @response.parsed_response.message
+      end
+
+      # Additional error context returned by some API endpoints
+      #
+      # @return [String]
+      def error_code
+        if @response.respond_to?(:error_code)
+          @response.error_code
+        else
+          ''
+        end
+      end
+
       private
 
       # Human friendly message.
       #
       # @return [String]
       def build_error_message
-        parsed_response = @response.parsed_response
-        message = parsed_response.message || parsed_response.error
-
+        parsed_response = classified_response
+        message = check_error_keys(parsed_response)
         "Server responded with code #{@response.code}, message: " \
         "#{handle_message(message)}. " \
         "Request URI: #{@response.request.base_uri}#{@response.request.path}"
       end
 
+      # Error keys vary across the API, find the first key that the parsed_response
+      # object responds to and return that, otherwise return the original.
+      def check_error_keys(resp)
+        key = POSSIBLE_MESSAGE_KEYS.find { |k| resp.respond_to?(k) }
+        key ? resp.send(key) : resp
+      end
+
+      # Parse the body based on the classification of the body content type
+      #
+      # @return parsed response
+      def classified_response
+        if @response.respond_to?('headers')
+          @response.headers['content-type'] == 'text/plain' ? { message: @response.to_s } : @response.parsed_response
+        else
+          @response.parsed_response
+        end
+      rescue Gitlab::Error::Parsing
+        # Return stringified response when receiving a
+        # parsing error to avoid obfuscation of the
+        # api error.
+        #
+        # note: The Gitlab API does not always return valid
+        # JSON when there are errors.
+        @response.to_s
+      end
+
       # Handle error response message in case of nested hashes
       def handle_message(message)
         case message
         when Gitlab::ObjectifiedHash
           message.to_h.sort.map do |key, val|
-            "'#{key}' #{(val.is_a?(Hash) ? val.sort.map { |k, v| "(#{k}: #{v.join(' ')})" } : val).join(' ')}"
+            "'#{key}' #{(val.is_a?(Hash) ? val.sort.map { |k, v| "(#{k}: #{v.join(' ')})" } : [val].flatten).join(' ')}"
           end.join(', ')
         when Array
           message.join(' ')
@@ -67,12 +114,18 @@ module Gitlab
     # Raised when API endpoint returns the HTTP status code 405.
     class MethodNotAllowed < ResponseError; end
 
+    # Raised when API endpoint returns the HTTP status code 406.
+    class NotAcceptable < ResponseError; end
+
     # Raised when API endpoint returns the HTTP status code 409.
     class Conflict < ResponseError; end
 
     # Raised when API endpoint returns the HTTP status code 422.
     class Unprocessable < ResponseError; end
 
+    # Raised when API endpoint returns the HTTP status code 429.
+    class TooManyRequests < ResponseError; end
+
     # Raised when API endpoint returns the HTTP status code 500.
     class InternalServerError < ResponseError; end
 
@@ -81,5 +134,21 @@ module Gitlab
 
     # Raised when API endpoint returns the HTTP status code 503.
     class ServiceUnavailable < ResponseError; end
+
+    # HTTP status codes mapped to error classes.
+    STATUS_MAPPINGS = {
+      400 => BadRequest,
+      401 => Unauthorized,
+      403 => Forbidden,
+      404 => NotFound,
+      405 => MethodNotAllowed,
+      406 => NotAcceptable,
+      409 => Conflict,
+      422 => Unprocessable,
+      429 => TooManyRequests,
+      500 => InternalServerError,
+      502 => BadGateway,
+      503 => ServiceUnavailable
+    }.freeze
   end
 end

data/lib/gitlab/file_response.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Wrapper class of file response.
   class FileResponse
-    HEADER_CONTENT_DISPOSITION = 'Content-Disposition'.freeze
+    HEADER_CONTENT_DISPOSITION = 'Content-Disposition'
 
     attr_reader :filename
 
@@ -18,7 +20,7 @@ module Gitlab
     def to_hash
       { filename: @filename, data: @file }
     end
-    alias_method :to_h, :to_hash
+    alias to_h to_hash
 
     # @return [String] Formatted string with the class name, object id and filename.
     def inspect
@@ -39,7 +41,7 @@ module Gitlab
 
     # Parse filename from the 'Content Disposition' header.
     def parse_headers!(headers)
-      @filename = headers[HEADER_CONTENT_DISPOSITION].split("filename=")[1]
+      @filename = headers[HEADER_CONTENT_DISPOSITION].split('filename=')[1]
       @filename = @filename[1...-1] if @filename[0] == '"' # Unquote filenames
     end
   end

data/lib/gitlab/help.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'gitlab'
 require 'gitlab/cli_helpers'
 
@@ -32,9 +34,7 @@ module Gitlab::Help
     # @return [String]
     def ri_cmd
       which_ri = `which ri`.chomp
-      if which_ri.empty?
-        fail "'ri' tool not found in $PATH. Please install it to use the help."
-      end
+      raise "'ri' tool not found in $PATH. Please install it to use the help." if which_ri.empty?
 
       which_ri
     end
@@ -45,23 +45,22 @@ module Gitlab::Help
     #
     # @return [Hash<Array>]
     def help_map
-      @help_map ||= begin
+      @help_map ||=
         actions.each_with_object({}) do |action, hsh|
-          key = client.method(action).
-                owner.to_s.gsub(/Gitlab::(?:Client::)?/, '')
+          key = client.method(action)
+                      .owner.to_s.gsub(/Gitlab::(?:Client::)?/, '')
           hsh[key] ||= []
           hsh[key] << action.to_s
         end
-      end
     end
 
     # Table with available commands.
     #
     # @return [Terminal::Table]
-    def actions_table(topic=nil)
+    def actions_table(topic = nil)
       rows = topic ? help_map[topic] : help_map.keys
       table do |t|
-        t.title = topic || "Help Topics"
+        t.title = topic || 'Help Topics'
 
         # add_row expects an array and we have strings hence the map.
         rows.sort.map { |r| [r] }.each_with_index do |row, index|
@@ -73,23 +72,23 @@ module Gitlab::Help
 
     # Returns full namespace of a command (e.g. Gitlab::Client::Branches.cmd)
     def namespace(cmd)
-      method_owners.select { |method| method[:name] === cmd }.
-        map { |method| method[:owner] + '.' + method[:name] }.
-        shift
+      method_owners.select { |method| method[:name] == cmd }
+                   .map { |method| "#{method[:owner]}.#{method[:name]}" }
+                   .shift
     end
 
     # Massage output from 'ri'.
     def change_help_output!(cmd, output_str)
-      output_str.gsub!(/#{cmd}\((.*?)\)/m, cmd + ' \1')
-      output_str.gsub!(/\,[\s]*/, ' ')
-      
+      output_str = +output_str
+      output_str.gsub!(/#{cmd}(\(.*?\))/m, "#{cmd}\\1")
+      output_str.gsub!(/,\s*/, ', ')
+
       # Ensure @option descriptions are on a single line
       output_str.gsub!(/\n\[/, " \[")
       output_str.gsub!(/\s(@)/, "\n@")
-      output_str.gsub!(/(\])\n(\:)/, '\1 \2')
-      output_str.gsub!(/(\:.*)(\n)(.*\.)/, '\1 \3')
-      output_str.gsub!(/\{(.+)\}/, '"{\1}"')
-      
+      output_str.gsub!(/(\])\n(:)/, '\\1 \\2')
+      output_str.gsub!(/(:.*)(\n)(.*\.)/, '\\1 \\3')
+      output_str.gsub!(/\{(.+)\}/, '"{\\1}"')
     end
-  end # class << self
+  end
 end

data/lib/gitlab/objectified_hash.rb

@@ -1,34 +1,51 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Converts hashes to the objects.
   class ObjectifiedHash
     # Creates a new ObjectifiedHash object.
     def initialize(hash)
       @hash = hash
-      @data = hash.inject({}) do |data, (key, value)|
-        value = ObjectifiedHash.new(value) if value.is_a? Hash
+      @data = hash.each_with_object({}) do |(key, value), data|
+        value = self.class.new(value) if value.is_a? Hash
+        value = value.map { |v| v.is_a?(Hash) ? self.class.new(v) : v } if value.is_a? Array
         data[key.to_s] = value
-        data
       end
     end
 
     # @return [Hash] The original hash.
     def to_hash
-      @hash
+      hash
     end
-    alias_method :to_h, :to_hash
+    alias to_h to_hash
 
     # @return [String] Formatted string with the class name, object id and original hash.
     def inspect
-      "#<#{self.class}:#{object_id} {hash: #{@hash.inspect}}"
+      "#<#{self.class}:#{object_id} {hash: #{hash.inspect}}"
+    end
+
+    def [](key)
+      data[key]
     end
 
-    # Delegate to ObjectifiedHash.
-    def method_missing(key)
-      @data.key?(key.to_s) ? @data[key.to_s] : nil
+    private
+
+    attr_reader :hash, :data
+
+    # Respond to messages for which `self.data` has a key
+    def method_missing(method_name, *args, &block)
+      if data.key?(method_name.to_s)
+        data[method_name.to_s]
+      elsif data.respond_to?(method_name)
+        warn 'WARNING: Please convert ObjectifiedHash object to hash before calling Hash methods on it.'
+        data.send(method_name, *args, &block)
+      else
+        super
+      end
     end
 
     def respond_to_missing?(method_name, include_private = false)
-      @hash.keys.map(&:to_sym).include?(method_name.to_sym) || super
+      hash.keys.map(&:to_sym).include?(method_name.to_sym) || super
     end
   end
 end

data/lib/gitlab/page_links.rb

@@ -1,21 +1,21 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Parses link header.
   #
   # @private
   class PageLinks
-    HEADER_LINK = 'Link'.freeze
-    DELIM_LINKS = ','.freeze
-    LINK_REGEX = /<([^>]+)>; rel=\"([^\"]+)\"/
-    METAS = %w(last next first prev)
+    HEADER_LINK = 'Link'
+    DELIM_LINKS = ','
+    LINK_REGEX = /<([^>]+)>; rel="([^"]+)"/.freeze
+    METAS = %w[last next first prev].freeze
 
     attr_accessor(*METAS)
 
     def initialize(headers)
       link_header = headers[HEADER_LINK]
 
-      if link_header && link_header =~ /(next|first|last|prev)/
-        extract_links(link_header)
-      end
+      extract_links(link_header) if link_header && link_header =~ /(next|first|last|prev)/
     end
 
     private
@@ -23,9 +23,11 @@ module Gitlab
     def extract_links(header)
       header.split(DELIM_LINKS).each do |link|
         LINK_REGEX.match(link.strip) do |match|
-          url, meta = match[1], match[2]
+          url = match[1]
+          meta = match[2]
           next if !url || !meta || METAS.index(meta).nil?
-          self.send("#{meta}=", url)
+
+          send("#{meta}=", url)
         end
       end
     end

data/lib/gitlab/paginated_response.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Gitlab
   # Wrapper class of paginated response.
   class PaginatedResponse
@@ -40,58 +42,69 @@ module Gitlab
       end
     end
 
-    def auto_paginate
-      response = block_given? ? nil : []
-      each_page do |page|
-        if block_given?
-          page.each do |item|
-            yield item
-          end
-        else
-          response += page
-        end
-      end
-      response
+    def lazy_paginate
+      to_enum(:each_page).lazy.flat_map(&:to_ary)
+    end
+
+    def auto_paginate(&block)
+      return lazy_paginate.to_a unless block
+
+      lazy_paginate.each(&block)
+    end
+
+    def paginate_with_limit(limit, &block)
+      return lazy_paginate.take(limit).to_a unless block
+
+      lazy_paginate.take(limit).each(&block)
     end
 
-    def has_last_page?
+    def last_page?
       !(@links.nil? || @links.last.nil?)
     end
+    alias has_last_page? last_page?
 
     def last_page
       return nil if @client.nil? || !has_last_page?
-      path = @links.last.sub(/#{@client.endpoint}/, '')
-      @client.get(path)
+
+      @client.get(client_relative_path(@links.last))
     end
 
-    def has_first_page?
+    def first_page?
       !(@links.nil? || @links.first.nil?)
     end
+    alias has_first_page? first_page?
 
     def first_page
       return nil if @client.nil? || !has_first_page?
-      path = @links.first.sub(/#{@client.endpoint}/, '')
-      @client.get(path)
+
+      @client.get(client_relative_path(@links.first))
     end
 
-    def has_next_page?
+    def next_page?
       !(@links.nil? || @links.next.nil?)
     end
+    alias has_next_page? next_page?
 
     def next_page
       return nil if @client.nil? || !has_next_page?
-      path = @links.next.sub(/#{@client.endpoint}/, '')
-      @client.get(path)
+
+      @client.get(client_relative_path(@links.next))
     end
 
-    def has_prev_page?
+    def prev_page?
       !(@links.nil? || @links.prev.nil?)
     end
+    alias has_prev_page? prev_page?
 
     def prev_page
       return nil if @client.nil? || !has_prev_page?
-      path = @links.prev.sub(/#{@client.endpoint}/, '')
-      @client.get(path)
+
+      @client.get(client_relative_path(@links.prev))
+    end
+
+    def client_relative_path(link)
+      client_endpoint_path = URI.parse(@client.endpoint).request_uri # api/v4
+      URI.parse(link).request_uri.sub(client_endpoint_path, '')
     end
   end
 end