jabber_admin 0.1.4 → 0.2.0

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "jabber_admin"
+require 'bundler/setup'
+require 'jabber_admin'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "jabber_admin"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/docker-compose.yml

@@ -0,0 +1,15 @@
+version: "3"
+services:
+  jabber:
+    image: hausgold/ejabberd:18.01
+    network_mode: bridge
+    ports: ["4560", "5222", "5269", "5280", "5443"]
+
+  test:
+    image: ruby:2.3
+    network_mode: bridge
+    working_dir: /app
+    volumes:
+      - .:/app
+    links:
+      - jabber

data/jabber_admin.gemspec

@@ -1,20 +1,23 @@
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'jabber_admin/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = 'jabber_admin'
-  spec.version       = JabberAdmin::VERSION
-  spec.authors       = ['Henning Vogt']
-  spec.licenses      = ['MIT']
-  spec.email         = ['henning.vogt@hausgold.de']
-
-  spec.summary       = %q{Library for the ejabberd RESTful admin API}
-  spec.description   = %q{Library for the ejabberd RESTful admin API}
-  spec.homepage      = 'https://github.com/hausgold/jabber_admin'
-
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  spec.name        = 'jabber_admin'
+  spec.version     = JabberAdmin::VERSION
+  spec.authors     = ['Henning Vogt', 'Hermann Mayer']
+  spec.licenses    = ['MIT']
+  spec.email       = ['henning.vogt@hausgold.de', 'hermann.mayer@hausgold.de']
+
+  spec.summary     = 'Library for the ejabberd RESTful admin API'
+  spec.description = 'Library for the ejabberd RESTful admin API'
+  spec.homepage    = 'https://github.com/hausgold/jabber_admin'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the
+  # 'allowed_push_host' to allow pushing to a single host or delete this
+  # section to allow pushing to any host.
   if spec.respond_to?(:metadata)
     spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
@@ -22,20 +25,24 @@ Gem::Specification.new do |spec|
       'public gem pushes.'
   end
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'rest-client', '~> 2.0', '>= 2.0.2'
   spec.add_dependency 'activesupport', '>= 4.2.5'
+  spec.add_dependency 'rest-client', '~> 2.0', '>= 2.0.2'
 
   spec.required_ruby_version = '>= 2.2'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
   spec.add_development_dependency 'simplecov', '~> 0.15'
+  spec.add_development_dependency 'vcr', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.0'
 end

data/lib/jabber_admin.rb

@@ -1,61 +1,127 @@
 # frozen_string_literal: true
 
-require "active_support/inflector"
-require "rest-client"
+require 'active_support/inflector'
+require 'json'
+require 'pathname'
+require 'rest-client'
 
-require "jabber_admin/initializer"
-require "jabber_admin/configuration"
-require "jabber_admin/commands"
-require "jabber_admin/api_call"
-require "jabber_admin/version"
+require 'jabber_admin/exceptions'
+require 'jabber_admin/configuration'
+require 'jabber_admin/commands'
+require 'jabber_admin/api_call'
+require 'jabber_admin/version'
 
-##
-# Jabber Admin Library
+# jabber_admin
 #
-# allows making API calls to the ejabberd RESTful admin backend
-# All supported commands are available in /lib/jabber_admin/commands/
+# This gem allows making API calls to the ejabberd RESTful admin backend.  We
+# support a bunch of predefined commands out of the box, just have a look at
+# the +lib/jabber_admin/commands/+ directory or the readme file.
 #
-# Usage:
-# All commands can be called via JabberAdmin.[method_name]!
-# (Do not forget the bang at the end)
+# All predefined commands can be called via +JabberAdmin.COMMAND!+ or via
+# +JabberAdmin.COMMAND+.  The bang variant checks the result of the command
+# (successful, or not) and raise a subclass of +JabberAdmin::Exception+ in case
+# of issues. The non-bang variant just sends the commands in a fire and forget
+# manner.
 #
-# @example:
-#   JabberAdmin.register!(user: 'peter', 'host': 'example.com', password: '123')
-#   JabberAdmin.unregister!(user: 'peter', 'host': 'example.com')
+# When you're missing a command you want to use, you can use the
+# +JabberAdmin::ApiCall+ class directly. It allows you to easily fulfill your
+# custom needs with the power of error handling (if you like).
+#
+# You can also use your custom command directly on the +JabberAdmin+ module, in
+# both banged and non-banged versions and we pass them as a shortcut to a new
+# +JabberAdmin::ApiCall+ instance.
+#
+# @example Configure jabber_admin gem
+#   JabberAdmin.configure do |config|
+#     # The ejabberd REST API endpoint as a full URL.
+#     # Take care of the path part, because this is individually
+#     # configured on ejabberd. (See: https://bit.ly/2rBxatJ)
+#     config.url = 'http://jabber.local/api'
+#     # Provide here the full user JID in order to authenticate as
+#     # a administrator.
+#     config.username = 'admin@jabber.local'
+#     # The password of the administrator account.
+#     config.password = 'password'
+#   end
+#
+# @example Restart the ejabberd service
 #   JabberAdmin.restart!
 #
+# @example Register a new user to the XMPP service
+#   JabberAdmin.register! user: 'peter@example.com', password: '123'
+#
+# @example Delete a user from the XMPP service, in fire and forget manner
+#   JabberAdmin.unregister user: 'peter@example.com'
 module JabberAdmin
   class << self
     attr_writer :configuration
   end
 
-  # @return [JabberAdmin::Configuration] The global JabberAdmin configuration
+  # A simple getter to the global JabberAdmin configuration structure.
+  #
+  # @return [JabberAdmin::Configuration] the global JabberAdmin configuration
   def self.configuration
-    @configuration ||= JabberAdmin::Configuration.new
+    @configuration ||= Configuration.new
   end
 
-  # Class method to set and change the global configuration
+  # Class method to set and change the global configuration. This is just a
+  # tapped variant of the +.configuration+ method.
   #
-  # @example
-  #   JabberAdmin.configure do |config|
-  #     config.api_host = 'xmpp.example.com'
-  #     config.admin = 'admin'
-  #     config.password = 'password'
-  #   end
+  # @yield [configuration]
+  # @yieldparam [JabberAdmin::Configuration] configuration
   def self.configure
     yield(configuration)
   end
 
-  def self.method_missing(method, *args, &block)
-    command = "jabber_admin/commands/#{method[0..-2]}".classify.constantize
-    args.empty? ? command.call : command.call(*args)
+  # Allow an easy to use DSL on the +JabberAdmin+ module. We support predefined
+  # (known) commands and unknown ones in bang and non-bang variants. This
+  # allows maximum flexibility to the user. The bang versions perform the
+  # response checks and raise in case of issues. The non-bang versions skip
+  # this checks. For unknown commands the +JabberAdmin::ApiCall+ is directly
+  # utilized with the method name as command. (Without the trailling bang, when
+  # it is present)
+  #
+  # @param method [Symbol, String, #to_s] the name of the command to run
+  # @param args all additional payload to pass down to the API call
+  # @return [RestClient::Response] the actual response of the command
+  #
+  # rubocop:disable Style/MethodMissing we support all given methods
+  def self.method_missing(method, *args)
+    predefined_command(method).call(predefined_callable(method), *args)
   rescue NameError
-    super
+    predefined_callable(method).call(method.to_s.chomp('!'), *args)
   end
+  # rubocop:enable Style/MethodMissing
 
-  def self.respond_to_missing?(method, include_private = false)
-    "jabber_admin/commands/#{method[0..-2]}".classify.constantize && true
-  rescue NameError
-    super
+  # Try to find the given name as a predefined command. When there is no such
+  # predefined command, we raise a +NameError+.
+  #
+  # @param name [Symbol, String, #to_s] the command name to lookup
+  # @return [Class] the predefined command class constant
+  def self.predefined_command(name)
+    # Remove bangs and build the camel case variant
+    "JabberAdmin::Commands::#{name.to_s.chomp('!').camelize}".constantize
+  end
+
+  # Generate a matching API call wrapper for the given command name. When we
+  # have to deal with a bang version, we pass the bang down to the API call
+  # instance. Otherwise we just run the regular +#perform+ method on the API
+  # call instance.
+  #
+  # @param name [Symbol, String, #to_s] the command name to match
+  # @return [Proc] the API call wrapper
+  def self.predefined_callable(name)
+    method = name.to_s.end_with?('!') ? 'perform!' : 'perform'
+    proc { |*args| ApiCall.send(method, *args) }
+  end
+
+  # We support all methods if you ask for. This is our dynamic command approach
+  # here to support predefined and custom commands in the same namespace.
+  #
+  # @param method [String] the method to lookup
+  # @param include_private [Boolean] allow the lookup of private methods
+  # @return [Boolean] always +true+
+  def self.respond_to_missing?(_method, _include_private = false)
+    true
   end
 end

data/lib/jabber_admin/api_call.rb

@@ -1,42 +1,128 @@
 # frozen_string_literal: true
 
 module JabberAdmin
-  # Error that will be raised when API call is not successful
-  class ApiError < StandardError; end
-
-  # Handles the communication with the API
+  # Handles a single communication with the API. An instance persists the
+  # response when performed once. So you can get the response multiple times,
+  # without repeating the request.
   class ApiCall
-    attr_reader :command, :payload
-
-    def self.perform(command, payload = {})
-      new(command, payload).perform
-    end
+    attr_reader :command, :payload, :check_res_body
 
-    def initialize(command, payload)
+    # Setup a new API call instance with the given command and the given
+    # request payload.
+    #
+    # @param command [String] the command to execute
+    # @param check_res_body [Boolean] whenever to check the response body
+    # @param payload the request payload, empty by default
+    def initialize(command, check_res_body: true, **payload)
       @command = command
       @payload = payload
+      @check_res_body = check_res_body
     end
 
-    def perform
-      raise(ApiError, response.to_s) if response.code != 200
-
-      response
+    # The resulting URL of the API call. This URL is constructed with the
+    # +JabberAdmin.configuration.url+ as base and the command name as the
+    # suffix. The configuration is allowed to end with trailling slash, or not.
+    #
+    # @return [String] the API call URL
+    def url
+      "#{JabberAdmin.configuration.url.strip.chomp('/')}/#{@command}"
     end
 
-    private
-
+    # This method compose the actual request, perfoms it and stores the
+    # response to the instance.  Additional calls to this method will not
+    # repeat the request, but will deliver the response directly.
+    #
+    # @return [RestClient::Response] the response of the API call
     def response
-      @res ||= RestClient::Request.execute(
+      @response ||= RestClient::Request.execute(
         method: :post,
         url: url,
-        user: JabberAdmin.configuration.admin,
+        user: JabberAdmin.configuration.username,
         password: JabberAdmin.configuration.password,
         payload: payload.to_json
       )
+    rescue RestClient::Exception => err
+      @response = err.response
     end
 
-    def url
-      "#{JabberAdmin.configuration.api_host}/api/#{@command}"
+    # Check if the response was successful. Otherwise raise exceptions with
+    # +JabberAdmin::Exception+ as base type.
+    #
+    # @raise JabberAdmin::ApiError
+    # @raise JabberAdmin::CommandError
+    #
+    # rubocop:disable Metrics/AbcSize because its the bundled check logic
+    def check_response
+      # The REST API responds a 404 status code when the command is not known.
+      raise UnknownCommandError, "Command '#{command}' is not known", response \
+        if response.code == 404
+
+      # In case we send commands with missing data or any other validation
+      # issues, the REST API will respond with a 400 Bad Request status
+      # code.
+      raise CommandError, 'Invalid arguments for command', response \
+        if response.code == 400
+
+      # Looks like the ejabberd REST API is returning 200 OK in case the
+      # request was valid and permitted. But it does not indicate that the
+      # request was successful handled. This is indicated on the response body
+      # as a one (1) or a zero (0). (0 on success, 1 otherwise)
+      raise RequestError, 'Response code was not 200', response \
+        unless response.code == 200
+
+      # Stop the check, when we should not check the response body
+      return unless check_res_body
+
+      # The command was not successful, for some reason. Unfortunately we do
+      # not get any further information here, which makes error debugging a
+      # struggle.
+      raise CommandError, 'Command was not successful', response \
+        unless response.body == '0'
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Just a simple DSL wrapper for the response method.
+    #
+    # @return [RestClient::Response] the API call response
+    def perform
+      response
+    end
+
+    # Just a simple DSL wrapper for the response method. But this variant
+    # perfoms a response check which will raise excpetions when there are
+    # issues.
+    #
+    # @raise JabberAdmin::ApiError
+    # @raise JabberAdmin::CommandError
+    # @return [RestClient::Response] the API call response
+    def perform!
+      check_response
+      response
+    end
+
+    # A simple class level shortcut of the +perform+ method. This is just DSL
+    # code which accepts the same arguments as the instance initialize method.
+    # (+#new+)
+    #
+    # @param command [String] the command to execute
+    # @param payload [Hash] the request payload, empty by default
+    # @return [RestClient::Response] the API call response
+    def self.perform(*args)
+      new(*args).perform
+    end
+
+    # A simple class level shortcut of the +perform!+ method. This is just DSL
+    # code which accepts the same arguments as the instance initialize method.
+    # (+#new+)
+    #
+    # @param command [String] the command to execute
+    # @param payload [Hash] the request payload, empty by default
+    # @return [RestClient::Response] the API call response
+    #
+    # @raise JabberAdmin::ApiError
+    # @raise JabberAdmin::CommandError
+    def self.perform!(*args)
+      new(*args).perform!
     end
   end
 end

data/lib/jabber_admin/commands.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-# Require all commands from the commands subfolder
-Dir["#{File.dirname(__FILE__)}/commands/**/*.rb"].each {|file| require file }
-
-##
-# Contains alle commands that are supported
 module JabberAdmin
+  # Contains all predefined commands that are supported.
   module Commands; end
 end
+
+# Require all commands from the commands subfolder
+Dir[Pathname.new(__dir__).join('commands', '**', '*.rb')].each do |file|
+  require file
+end

data/lib/jabber_admin/commands/ban_account.rb

@@ -2,17 +2,18 @@
 
 module JabberAdmin
   module Commands
-    ##
-    # Ban an account: kick sessions and set random password
-    # https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#ban-account-ban-an-account-kick-sessions-and-set-random-password
+    # Ban an account by kicking sessions and set random password.
+    #
+    # @see https://bit.ly/2KW9xVt
     class BanAccount
-      # @param [user] The user
-      # @param [host] Server name
-      # @param [reason] Reason for banning user
-      def self.call(user:, host:, reason:)
-        JabberAdmin::ApiCall.perform(
-          'ban_account', user: user, host: host, reason: reason
-        )
+      # Pass the correct data to the given callable.
+      #
+      # @param callable [Proc, #call] the callable to call
+      # @param user [String] user JID wo/ resource (eg. +tom@localhost+)
+      # @param reason [String] the banning reason (eg. +Spamming other users+)
+      def self.call(callable, user:, reason:)
+        uid, host = user.split('@')
+        callable.call('ban_account', user: uid, host: host, reason: reason)
       end
     end
   end