gitlab 4.10.0 → 4.19.0

data/lib/gitlab/client/user_snippets.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+class Gitlab::Client
+  # Defines methods related to user snippets.
+  # @see https://docs.gitlab.com/ce/api/snippets.html
+  module UserSnippets
+    # Get a list of the snippets of the current user.
+    #
+    # @example
+    #   Gitlab.user_snippets
+    #
+    # @return [Array<Gitlab::ObjectifiedHash>] List of snippets of current user
+    def user_snippets
+      get('/snippets')
+    end
+
+    # Get a single snippet.
+    #
+    # @example
+    #   Gitlab.user_snippet(1)
+    #
+    # @param  [Integer] id ID of snippet to retrieve.
+    # @return [Gitlab::ObjectifiedHash] Information about the user snippet
+    def user_snippet(id)
+      get("/snippets/#{id}")
+    end
+
+    # Get raw contents of a single snippet.
+    #
+    # @example
+    #   Gitlab.user_snippet_raw(1)
+    #
+    # @param  [Integer] id ID of snippet to retrieve.
+    # @return [String] User snippet text
+    def user_snippet_raw(id)
+      get("/snippets/#{id}/raw",
+          format: nil,
+          headers: { Accept: 'text/plain' },
+          parser: ::Gitlab::Request::Parser)
+    end
+
+    # Create a new snippet.
+    #
+    # @example
+    #   Gitlab.create_user_snippet({ title: 'REST', file_name: 'api.rb', content: 'some code', description: 'Hello World snippet', visibility: 'public'})
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :title (required) Title of a snippet.
+    # @option options [String] :file_name (required) Name of a snippet file.
+    # @option options [String] :content (required) Content of a snippet.
+    # @option options [String] :description (optional) Description of a snippet.
+    # @option options [String] :visibility (optional) visibility of a snippet.
+    # @return [Gitlab::ObjectifiedHash] Information about created snippet.
+    def create_user_snippet(options = {})
+      post('/snippets', body: options)
+    end
+
+    # Update an existing snippet.
+    #
+    # @example
+    #   Gitlab.edit_user_snippet(34, { file_name: 'README.txt' })
+    #   Gitlab.edit_user_snippet(34, { file_name: 'README.txt', title: 'New title' })
+    #
+    # @param  [Integer] id ID of snippet to update.
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :title (optional) Title of a snippet.
+    # @option options [String] :file_name (optional) Name of a snippet file.
+    # @option options [String] :content (optional) Content of a snippet.
+    # @option options [String] :description (optional) Description of a snippet.
+    # @option options [String] :visibility (optional) visibility of a snippet.
+    # @return [Gitlab::ObjectifiedHash] Information about updated snippet.
+    def edit_user_snippet(id, options = {})
+      put("/snippets/#{id}", body: options)
+    end
+
+    # Delete an existing snippet.
+    #
+    # @example
+    #   Gitlab.delete_user_snippet(14)
+    #
+    # @param  [Integer] id ID of snippet to delete.
+    # @return [void] This API call returns an empty response body.
+    def delete_user_snippet(id)
+      delete("/snippets/#{id}")
+    end
+
+    # List all public snippets.
+    #
+    # @example
+    #   Gitlab.public_snippets
+    #   Gitlab.public_snippets(per_page: 2, page: 1)
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :per_page (optional) Number of snippets to return per page.
+    # @option options [String] :page (optional) Page to retrieve.
+    #
+    # @return [Array<Gitlab::ObjectifiedHash>] List of all public snippets
+    def public_snippets(options = {})
+      get('/snippets/public', query: options)
+    end
+
+    # Get user agent details for a snippet.
+    #
+    # @example
+    #   Gitlab.snippet_user_agent_details(1)
+    #
+    # @param  [Integer] id ID of snippet to delete.
+    #
+    # @return [Array<Gitlab::ObjectifiedHash>] Details of the user agent
+    def snippet_user_agent_details(id)
+      get("/snippets/#{id}/user_agent_detail")
+    end
+  end
+end

data/lib/gitlab/client/users.rb

@@ -37,11 +37,11 @@ class Gitlab::Client
     # @example
     #   Gitlab.create_user('joe@foo.org', 'secret', 'joe', { name: 'Joe Smith' })
     #   or
-    #   Gitlab.create_user('joe@foo.org', 'secret')
+    #   Gitlab.create_user('joe@foo.org', 'secret', 'joe')
     #
-    # @param  [String] email The email of a user.
-    # @param  [String] password The password of a user.
-    # @param  [String] username The username of a user.
+    # @param  [String] email(required) The email of a user.
+    # @param  [String] password(required) The password of a user.
+    # @param  [String] username(required) The username of a user.
     # @param  [Hash] options A customizable set of options.
     # @option options [String] :name The name of a user. Defaults to email.
     # @option options [String] :skype The skype of a user.
@@ -51,11 +51,9 @@ class Gitlab::Client
     # @return [Gitlab::ObjectifiedHash] Information about created user.
     def create_user(*args)
       options = args.last.is_a?(Hash) ? args.pop : {}
-      body = if args[2]
-               { email: args[0], password: args[1], username: args[2] }
-             else
-               { email: args[0], password: args[1], name: args[0] }
-             end
+      raise ArgumentError, 'Missing required parameters' unless args[2]
+
+      body = { email: args[0], password: args[1], username: args[2], name: args[0] }
       body.merge!(options)
       post('/users', body: body)
     end
@@ -112,6 +110,17 @@ class Gitlab::Client
       post("/users/#{user_id}/unblock")
     end
 
+    # Approves the specified user. Available only for admin.
+    #
+    # @example
+    #   Gitlab.approve_user(15)
+    #
+    # @param [Integer] user_id The Id of user
+    # @return [Boolean] success or not
+    def approve_user(user_id)
+      post("/users/#{user_id}/approve")
+    end
+
     # Creates a new user session.
     #
     # @example
@@ -125,6 +134,20 @@ class Gitlab::Client
       post('/session', body: { email: email, password: password }, unauthenticated: true)
     end
 
+    # Gets a list of user activities (for admin access only).
+    #
+    # @example
+    #   Gitlab.activities
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @option options [String] :from The start date for paginated results.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def activities(options = {})
+      get('/user/activities', query: options)
+    end
+
     # Gets a list of user's SSH keys.
     #
     # @example
@@ -227,10 +250,15 @@ class Gitlab::Client
     #
     # @param  [String] email Email address
     # @param  [Integer] user_id The ID of a user.
+    # @param  [Boolean] skip_confirmation     Skip confirmation and assume e-mail is verified
     # @return [Gitlab::ObjectifiedHash]
-    def add_email(email, user_id = nil)
+    def add_email(email, user_id = nil, skip_confirmation = nil)
       url = user_id.to_i.zero? ? '/user/emails' : "/users/#{user_id}/emails"
-      post(url, body: { email: email })
+      if skip_confirmation.nil?
+        post(url, body: { email: email })
+      else
+        post(url, body: { email: email, skip_confirmation: skip_confirmation })
+      end
     end
 
     # Delete email
@@ -262,5 +290,108 @@ class Gitlab::Client
       options[:search] = search
       get('/users', query: options)
     end
+
+    # Gets user custom_attributes.
+    #
+    # @example
+    #   Gitlab.user_custom_attributes(2)
+    #
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_custom_attributes(user_id)
+      get("/users/#{user_id}/custom_attributes")
+    end
+
+    # Gets single user custom_attribute.
+    #
+    # @example
+    #   Gitlab.user_custom_attribute(key, 2)
+    #
+    # @param  [String] key The custom_attributes key
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_custom_attribute(key, user_id)
+      get("/users/#{user_id}/custom_attributes/#{key}")
+    end
+
+    # Creates a new custom_attribute
+    #
+    # @example
+    #   Gitlab.add_custom_attribute('some_new_key', 'some_new_value', 2)
+    #
+    # @param  [String] key The custom_attributes key
+    # @param  [String] value The custom_attributes value
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Gitlab::ObjectifiedHash]
+    def add_user_custom_attribute(key, value, user_id)
+      url = "/users/#{user_id}/custom_attributes/#{key}"
+      put(url, body: { value: value })
+    end
+
+    # Delete custom_attribute
+    # Will delete a custom_attribute
+    #
+    # @example
+    #   Gitlab.delete_user_custom_attribute('somekey', 2)
+    #
+    # @param  [String] key The custom_attribute key to delete
+    # @param  [Integer] user_id The ID of a user.
+    # @return [Boolean]
+    def delete_user_custom_attribute(key, user_id)
+      delete("/users/#{user_id}/custom_attributes/#{key}")
+    end
+
+    # Get all impersonation tokens for a user
+    #
+    # @example
+    #   Gitlab.user_impersonation_tokens(1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [String] state Filter impersonation tokens by state {}
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def user_impersonation_tokens(user_id)
+      get("/users/#{user_id}/impersonation_tokens")
+    end
+
+    # Get impersonation token information
+    #
+    # @example
+    #   Gitlab.user_impersonation_token(1, 1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [Integer] impersonation_token_id ID of the impersonation token.
+    # @return [Gitlab::ObjectifiedHash]
+    def user_impersonation_token(user_id, impersonation_token_id)
+      get("/users/#{user_id}/impersonation_tokens/#{impersonation_token_id}")
+    end
+
+    # Create impersonation token
+    #
+    # @example
+    #   Gitlab.create_user_impersonation_token(2, "token", ["api", "read_user"])
+    #   Gitlab.create_user_impersonation_token(2, "token", ["api", "read_user"], "1970-01-01")
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [String] name Name for impersonation token.
+    # @param  [Array<String>] scopes Array of scopes for the impersonation token
+    # @param  [String] expires_at Date for impersonation token expiration in ISO format.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_user_impersonation_token(user_id, name, scopes, expires_at = nil)
+      body = { name: name, scopes: scopes }
+      body[:expires_at] = expires_at if expires_at
+      post("/users/#{user_id}/impersonation_tokens", body: body)
+    end
+
+    # Revoke an impersonation token
+    #
+    # @example
+    #   Gitlab.revoke_user_impersonation_token(1, 1)
+    #
+    # @param  [Integer] user_id The ID of the user.
+    # @param  [Integer] impersonation_token_id ID of the impersonation token.
+    # @return [Gitlab::ObjectifiedHash]
+    def revoke_user_impersonation_token(user_id, impersonation_token_id)
+      delete("/users/#{user_id}/impersonation_tokens/#{impersonation_token_id}")
+    end
   end
 end

data/lib/gitlab/client.rb

@@ -7,6 +7,7 @@ module Gitlab
 
     # Please keep in alphabetical order
     include AccessRequests
+    include ApplicationSettings
     include Avatar
     include AwardEmojis
     include Boards
@@ -15,23 +16,31 @@ module Gitlab
     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 Packages
     include PipelineSchedules
     include PipelineTriggers
     include Pipelines
@@ -41,10 +50,12 @@ module Gitlab
     include ProjectReleases
     include Projects
     include ProtectedTags
+    include RemoteMirrors
     include Repositories
     include RepositoryFiles
     include RepositorySubmodules
     include ResourceLabelEvents
+    include ResourceStateEvents
     include Runners
     include Search
     include Services
@@ -55,6 +66,7 @@ module Gitlab
     include Templates
     include Todos
     include Users
+    include UserSnippets
     include Versions
     include Wikis
 
@@ -67,14 +79,18 @@ module Gitlab
       inspected
     end
 
+    # 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)
-      URI.encode(url.to_s, /\W/)
+      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..]}"
     end
   end
 end

data/lib/gitlab/configuration.rb

@@ -35,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

data/lib/gitlab/error.rb

@@ -34,6 +34,17 @@ module Gitlab
         @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.
@@ -63,6 +74,14 @@ module Gitlab
         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
@@ -95,6 +114,9 @@ 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
 
@@ -112,5 +134,37 @@ module Gitlab
 
     # Raised when API endpoint returns the HTTP status code 503.
     class ServiceUnavailable < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 522.
+    class ConnectionTimedOut < 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,
+      522 => ConnectionTimedOut
+    }.freeze
+
+    # Returns error class that should be raised for this response. Returns nil
+    # if the response status code is not 4xx or 5xx.
+    #
+    # @param  [HTTParty::Response] response The response object.
+    # @return [Class<Error::ResponseError>, nil]
+    def self.klass(response)
+      error_klass = STATUS_MAPPINGS[response.code]
+      return error_klass if error_klass
+
+      ResponseError if response.server_error? || response.client_error?
+    end
   end
 end

data/lib/gitlab/help.rb

@@ -45,14 +45,13 @@ 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::)?/, '')
           hsh[key] ||= []
           hsh[key] << action.to_s
         end
-      end
     end
 
     # Table with available commands.
@@ -74,21 +73,22 @@ 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] }
+                   .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
 end

data/lib/gitlab/objectified_hash.rb

@@ -7,29 +7,45 @@ module Gitlab
     def initialize(hash)
       @hash = hash
       @data = hash.each_with_object({}) do |(key, value), data|
-        value = ObjectifiedHash.new(value) if value.is_a? Hash
+        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
       end
     end
 
     # @return [Hash] The original hash.
     def to_hash
-      @hash
+      hash
     end
     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
 
-    # Delegate to ObjectifiedHash.
-    def method_missing(key)
-      @data.key?(key.to_s) ? @data[key.to_s] : super
+    def [](key)
+      data[key]
+    end
+
+    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

@@ -7,7 +7,7 @@ module Gitlab
   class PageLinks
     HEADER_LINK = 'Link'
     DELIM_LINKS = ','
-    LINK_REGEX = /<([^>]+)>; rel=\"([^\"]+)\"/.freeze
+    LINK_REGEX = /<([^>]+)>; rel="([^"]+)"/.freeze
     METAS = %w[last next first prev].freeze
 
     attr_accessor(*METAS)

data/lib/gitlab/paginated_response.rb

@@ -42,18 +42,20 @@ 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 last_page?
@@ -64,8 +66,7 @@ module Gitlab
     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 first_page?
@@ -76,8 +77,7 @@ module Gitlab
     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 next_page?
@@ -88,8 +88,7 @@ module Gitlab
     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 prev_page?
@@ -100,8 +99,12 @@ module Gitlab
     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