fs-gitlab 4.18.1

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Gitlab
+  # Wrapper for the Gitlab REST API.
+  class Client < API
+    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 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 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 UserSnippets
+    include Versions
+    include Wikis
+
+    # Text representation of the client, masking private token.
+    #
+    # @return [String]
+    def inspect
+      inspected = super
+      inspected.sub! @private_token, only_show_last_four_chars(@private_token) if @private_token
+      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)
+      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..]}"
+    end
+  end
+end

data/lib/gitlab/configuration.rb

@@ -0,0 +1,57 @@
+# 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 = %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}"
+
+    # @private
+    attr_accessor(*VALID_OPTIONS_KEYS)
+    # @private
+    alias auth_token= private_token=
+
+    # Sets all configuration options to their default values
+    # when this module is extended.
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block.
+    def configure
+      yield self
+    end
+
+    # Creates a hash of options and their values.
+    def options
+      VALID_OPTIONS_KEYS.inject({}) do |option, key|
+        option.merge!(key => send(key))
+      end
+    end
+
+    # Resets all configuration options to the defaults.
+    def reset
+      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
+      self.user_agent     = DEFAULT_USER_AGENT
+    end
+
+    private
+
+    # Allows HTTParty config to be specified in ENV using YAML hash.
+    def get_httparty_config(options)
+      return if options.nil?
+
+      httparty = Gitlab::CLI::Helpers.yaml_load(options)
+      raise ArgumentError, 'HTTParty config should be a Hash.' unless httparty.is_a? Hash
+
+      Gitlab::CLI::Helpers.symbolize_keys httparty
+    end
+  end
+end

data/lib/gitlab/error.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module Error
+    # Custom error class for rescuing from all Gitlab errors.
+    class Error < StandardError; end
+
+    # Raised when API endpoint credentials not configured.
+    class MissingCredentials < Error; end
+
+    # Raised when impossible to parse response body.
+    class Parsing < Error; end
+
+    # 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.
+      #
+      # @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 = 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].flatten).join(' ')}"
+          end.join(', ')
+        when Array
+          message.join(' ')
+        else
+          message
+        end
+      end
+    end
+
+    # Raised when API endpoint returns the HTTP status code 400.
+    class BadRequest < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 401.
+    class Unauthorized < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 403.
+    class Forbidden < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 404.
+    class NotFound < ResponseError; end
+
+    # 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
+
+    # Raised when API endpoint returns the HTTP status code 502.
+    class BadGateway < ResponseError; end
+
+    # 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/file_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Gitlab
+  # Wrapper class of file response.
+  class FileResponse
+    HEADER_CONTENT_DISPOSITION = 'Content-Disposition'
+
+    attr_reader :filename
+
+    def initialize(file)
+      @file = file
+    end
+
+    # @return [bool] Always false
+    def empty?
+      false
+    end
+
+    # @return [Hash] A hash consisting of filename and io object
+    def to_hash
+      { filename: @filename, data: @file }
+    end
+    alias to_h to_hash
+
+    # @return [String] Formatted string with the class name, object id and filename.
+    def inspect
+      "#<#{self.class}:#{object_id} {filename: #{filename.inspect}}>"
+    end
+
+    def method_missing(name, *args, &block)
+      if @file.respond_to?(name)
+        @file.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      super || @file.respond_to?(method_name, include_private)
+    end
+
+    # Parse filename from the 'Content Disposition' header.
+    def parse_headers!(headers)
+      @filename = headers[HEADER_CONTENT_DISPOSITION].split('filename=')[1]
+      @filename = @filename[1...-1] if @filename[0] == '"' # Unquote filenames
+    end
+  end
+end

data/lib/gitlab/help.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'gitlab'
+require 'gitlab/cli_helpers'
+
+module Gitlab::Help
+  extend Gitlab::CLI::Helpers
+
+  class << self
+    # Returns the (modified) help from the 'ri' command or returns an error.
+    #
+    # @return [String]
+    def get_help(cmd)
+      cmd_namespace = namespace cmd
+
+      if cmd_namespace
+        ri_output = `#{ri_cmd} -T #{cmd_namespace} 2>&1`.chomp
+
+        if $CHILD_STATUS == 0
+          change_help_output! cmd, ri_output
+          yield ri_output if block_given?
+
+          ri_output
+        else
+          "Ri docs not found for #{cmd}, please install the docs to use 'help'."
+        end
+      else
+        "Unknown command: #{cmd}."
+      end
+    end
+
+    # Finds the location of 'ri' on a system.
+    #
+    # @return [String]
+    def ri_cmd
+      which_ri = `which ri`.chomp
+      raise "'ri' tool not found in $PATH. Please install it to use the help." if which_ri.empty?
+
+      which_ri
+    end
+
+    # A hash map that contains help topics (Branches, Groups, etc.)
+    # and a list of commands that are defined under a topic (create_branch,
+    # branches, protect_branch, etc.).
+    #
+    # @return [Hash<Array>]
+    def help_map
+      @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
+
+    # Table with available commands.
+    #
+    # @return [Terminal::Table]
+    def actions_table(topic = nil)
+      rows = topic ? help_map[topic] : help_map.keys
+      table do |t|
+        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|
+          t.add_row row
+          t.add_separator unless rows.size - 1 == index
+        end
+      end
+    end
+
+    # 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
+    end
+
+    # Massage output from 'ri'.
+    def change_help_output!(cmd, output_str)
+      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}"')
+    end
+  end
+end

data/lib/gitlab/objectified_hash.rb

@@ -0,0 +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.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
+      end
+    end
+
+    # @return [Hash] The original hash.
+    def to_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}}"
+    end
+
+    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
+    end
+  end
+end

data/lib/gitlab/page_links.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Gitlab
+  # Parses link header.
+  #
+  # @private
+  class PageLinks
+    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]
+
+      extract_links(link_header) if link_header && link_header =~ /(next|first|last|prev)/
+    end
+
+    private
+
+    def extract_links(header)
+      header.split(DELIM_LINKS).each do |link|
+        LINK_REGEX.match(link.strip) do |match|
+          url = match[1]
+          meta = match[2]
+          next if !url || !meta || METAS.index(meta).nil?
+
+          send("#{meta}=", url)
+        end
+      end
+    end
+  end
+end