jabber_admin 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 539a6c8f78226c54b34ef4fbba4a4efdab80070b
-  data.tar.gz: c775b07759beeeb2b4db8b4cc66297d04e38d0b2
+SHA256:
+  metadata.gz: 31b521fdd1da155402e58b436e83fcb22012648b601f543fd5e885f844fd019e
+  data.tar.gz: 9f14f04eaa52941167b0deaeb3322d1d1e947acf8ed2cc8e16cdc00dabeaa8a4
 SHA512:
-  metadata.gz: d5378a4478def4b3d76915f56e446cbbe522b2e89446908150bc25bc30a1308c76c046cfbd4f506f7c9114a4a87aa5c5884ce703c78a70e43f3e6199dfc81988
-  data.tar.gz: 9fe1f23a6679d11299d9d73bfd07b8523b4c88b016b1d04e9c03881380dcc6b03086682b9d68755dbbb2f0114c37ff452f7b0e3eb6479cfe93b7b4e6cc8b48cc
+  metadata.gz: 57e645f24f358c679b841cde89b8d8ee9fc978d5497a979ce5e87217f936af0438f9e8a75a1bcb94f9d2f195ea469fdc3be1f55137d8b20c66e5b04e0a61bf9d
+  data.tar.gz: b26205f1387f7b50c2ac30407402017f5ab70aa89d64d34905f6c2ddddb26e3d05fa48b6a49f418eb9716c20ec2ce95327e97155f6ab0be9d2c88ff930a732bf

data/.editorconfig

@@ -0,0 +1,30 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = true
+
+[*.json]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+trim_trailing_whitespace = true
+indent_style = tab
+indent_size = 4
+
+[*.sh]
+indent_style = space
+indent_size = 2

data/.gitignore

@@ -3,11 +3,13 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
+/doc/
 /pkg/
 /spec/reports/
 /tmp/
+/vendor/
+/gemfiles/vendor/
+*.gemfile.lock
 
 # rspec failure tracking
 .rspec_status
-
-*.gem

data/.rubocop.yml

@@ -0,0 +1,35 @@
+require: rubocop-rspec
+
+Documentation:
+  Enabled: true
+
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.5
+
+Metrics/BlockLength:
+  Exclude:
+    - Rakefile
+    - spec/**/*.rb
+    - '**/*.rake'
+    - '*.gemspec'
+
+# Document all the things.
+Style/DocumentationMethod:
+  Enabled: true
+  RequireForNonPublicMethods: true
+
+# Because +expect_any_instance_of().to have_received()+ is not
+# supported with the +with(hash_including)+ matchers
+RSpec/MessageSpies:
+  EnforcedStyle: receive
+
+# Allow deeper nesting because of the predefined/non-predefined -
+# bang/non-bang cases.
+RSpec/NestedGroups:
+  Max: 4
+
+# We stay at 80 characters per line.
+# See: https://rubystyle.guide/#max-line-length
+Metrics/LineLength:
+  Max: 80

data/.simplecov

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+SimpleCov.start 'test_frameworks' do
+  add_filter '/vendor/bundle/'
+end

data/.travis.yml

@@ -1,16 +1,18 @@
+sudo: false
 env:
   global:
-    - CC_TEST_REPORTER_ID=02d696c72627e730a3db553884276acf15672466e32e66a788672d3b167629ca
-sudo: false
+    - CC_TEST_REPORTER_ID=05f9944a34899135739ab519c57a179a3f4677999fd832fa87da25d3643702b7
 language: ruby
 rvm:
-  - 2.2
-  - 2.3
-  - 2.4
-before_install: gem install bundler -v 1.15.1
+  - 2.6
+  - 2.6
+  - 2.5
+before_install: gem install bundler
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter
   - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
 after_script:
   - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/.yardopts

@@ -0,0 +1,4 @@
+--output-dir=doc/app
+-
+README.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+### 1.0.0
+
+* All `JabberAdmin` errors `[UnknownCommandError, CommandError, RequestError]`
+  now ship the response object correctly (was always set to `nil` previously)
+  (#6)
+* Improved the default exceptions messages with the response body (#6)
+* Added support for setting/fetching vCard details (`JabberAdmin.set_vcard`,
+  `JabberAdmin.get_vcard`) (#6)
+* Dropped support for Ruby <2.5 (#6)
+* Added some versioning helpers (eg. `JabberAdmin.version`)
+
+### 0.2.0
+
+* [BC] The configuration has changed
+  * `api_host` => `url`, we require now the full base URL of the REST API, this
+    allows custom mod_http_api paths (See: https://bit.ly/2rBxatJ)
+  * `admin` => `username`, we want to be use common sense API client jargon
+    here
+* We support from now on predefined AND freestyle commands on the `JabberAdmin`
+  module
+* We support from now on bang and non-bang command variants (for both
+  predefined and freestyle commands) which allows the client to use builtin
+  error handling or not
+* [BC] Previously only bang variants were possible, without response checking,
+  look out for more exceptions when you migrate
+* New predefined commands:
+  * muc_register_nick
+  * send_stanza_c2s
+  * set_nickname
+  * set_presence
+* The documentation was greatly improved
+* The testcases were rewritten and tested with VCR against a real ejabberd
+  server (18.01)
+
+### 0.1.4
+
+* Added support for predefined commands
+  * ban_account
+  * create_room
+  * create_room_with_opts
+  * register
+  * registered_users
+  * restart
+  * send_direct_invitation
+  * send_stanza
+  * set_room_affiliation
+  * subscribe_room
+  * unregister
+  * unsubscribe_room

data/Gemfile

@@ -1,6 +1,8 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in jabber_admin.gemspec
 gemspec

data/Makefile

@@ -0,0 +1,108 @@
+MAKEFLAGS += --warn-undefined-variables -j1
+SHELL := bash
+.SHELLFLAGS := -eu -o pipefail -c
+.DEFAULT_GOAL := all
+.DELETE_ON_ERROR:
+.SUFFIXES:
+.PHONY:
+
+# Environment switches
+MAKE_ENV ?= docker
+COMPOSE_RUN_SHELL_FLAGS ?= --rm
+
+# Directories
+VENDOR_DIR ?= vendor/bundle
+
+# Host binaries
+BASH ?= bash
+COMPOSE ?= docker-compose
+ECHO ?= echo
+GREP ?= grep
+ID ?= id
+MKDIR ?= mkdir
+RM ?= rm
+SED ?= sed
+SORT ?= sort
+
+# Container binaries
+BUNDLE ?= bundle
+RAKE ?= rake
+RUBOCOP ?= rubocop
+
+all:
+	# jabber_admin
+	#
+	# install                  Install the dependencies
+	# test                     Run the whole test suite
+	# test-style               Check the coding styles
+	# clean                    Clean the dependencies
+	#
+	# shell                    Run an interactive shell on the container
+	# shell-irb                Run an interactive IRB shell on the container
+	#
+	# supported-commands-list  Generate the supported commands list
+
+# Define a generic shell run wrapper
+# $1 - The command to run
+ifeq ($(MAKE_ENV),docker)
+define run-shell
+	$(COMPOSE) run $(COMPOSE_RUN_SHELL_FLAGS) \
+		-e LANG=en_US.UTF-8 -e LANGUAGE=en_US.UTF-8 -e LC_ALL=en_US.UTF-8 \
+		-e HOME=/tmp -e BUNDLE_APP_CONFIG=/app/.bundle \
+		-u `$(ID) -u` test bash -c 'sleep 0.1; echo; $(1)'
+endef
+else ifeq ($(MAKE_ENV),baremetal)
+define run-shell
+	$(1)
+endef
+endif
+
+install:
+	# Install the dependencies
+	@$(MKDIR) -p $(VENDOR_DIR)
+	@$(call run-shell,$(BUNDLE) check || $(BUNDLE) install --path $(VENDOR_DIR))
+
+test: install
+	# Run the whole test suite
+	@$(call run-shell,$(BUNDLE) exec $(RAKE))
+
+test-style: test-style-ruby
+
+test-style-ruby:
+	# Run the static code analyzer (rubocop)
+	@$(call run-shell,$(BUNDLE) exec $(RUBOCOP) -a)
+
+clean:
+	# Clean the dependencies
+	@$(RM) -rf $(VENDOR_DIR)
+
+clean-containers:
+	# Clean running containers
+ifeq ($(MAKE_ENV),docker)
+	@$(COMPOSE) down
+endif
+
+distclean: clean clean-containers
+
+shell: install
+	# Run an interactive shell on the container
+	@$(call run-shell,$(BASH) -i)
+
+shell-irb: install
+	# Run an interactive IRB shell on the container
+	@$(call run-shell,bin/console)
+
+release:
+	# Release a new gem version
+	@$(RAKE) release
+
+supported-commands-list:
+	# Generate the supported commands list
+	@$(ECHO)
+	@$(GREP) -oP '@see https?://.*' -R lib/jabber_admin/commands/ \
+		| $(SED) \
+			-e 's/@see //g' \
+			-e 's/.rb:/](/g' \
+			-e 's/$$/)/g' \
+			-e 's#^lib/jabber_admin/commands/#- [#g' \
+		| $(SORT)

data/README.md

@@ -1,10 +1,21 @@
-# JabberAdmin
+![jabber_admin](doc/assets/project.svg)
 
-[![Maintainability](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/maintainability)](https://codeclimate.com/github/hausgold/jabber_admin/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/test_coverage)](https://codeclimate.com/github/hausgold/jabber_admin/test_coverage)
+[![Build Status](https://travis-ci.com/hausgold/jabber_admin.svg?branch=master)](https://travis-ci.com/hausgold/jabber_admin)
+[![Gem Version](https://badge.fury.io/rb/jabber_admin.svg)](https://badge.fury.io/rb/jabber_admin)
+[![Maintainability](https://api.codeclimate.com/v1/badges/dd51c4668e97771baaba/maintainability)](https://codeclimate.com/repos/5cac8bcb6969c376ed007c70/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/dd51c4668e97771baaba/test_coverage)](https://codeclimate.com/repos/5cac8bcb6969c376ed007c70/test_coverage)
+[![API docs](https://img.shields.io/badge/docs-API-blue.svg)](https://www.rubydoc.info/gems/jabber_admin)
 
-JabberAdmin is a small library to easily communicate with the Ejabberd
-admin API.
+jabber_admin is a small library to easily communicate with the [ejabberd
+admin API](https://docs.ejabberd.im/developer/ejabberd-api/admin-api).
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Predefined commands](#predefined-commands)
+  - [Freestyle commands](#freestyle-commands)
+- [Development](#development)
+- [Contributing](#contributing)
 
 ## Installation
 
@@ -16,36 +27,149 @@ gem 'jabber_admin'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install jabber_admin
+```bash
+$ gem install jabber_admin
+```
+
+## Configuration
+
+You can configure the jabber_admin gem in a global initializer way with the
+`JabberAdmin.configure` method which yields the configuration directly.
+
+```ruby
+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
+```
+
+In case this is not cool for you, you can get and modify the configuration
+directly with the help of the `JabberAdmin.configuration` getter.
+
+```ruby
+JabberAdmin.configuration.url = 'http://jabber.local/api'
+JabberAdmin.configuration.username = 'admin@jabber.local'
+JabberAdmin.configuration.password = 'password'
+```
 
 ## Usage
 
-``` ruby
+### Predefined commands
+
+We support some handy predefined commands out of the box which ease the quick
+start usage. These predefined commands comes with a good documentation
+(including valid example data) and a nifty interface. When it is possible to
+fill up missing data from a full user/room JID we do so. Say while sending a
+direct invitation, you just pass the full room JID and we take care of
+splitting it up to fulfill the separate room name and the separate MUC service
+domain.
+
+All our predefined commands are available directly underneath the `JabberAdmin`
+module as methods. Just call them like this:
+
+```ruby
 JabberAdmin.restart!
-JabberAdmin.create_room!(name: 'room1', host: '...')
+JabberAdmin.register(user: 'peter@example.com', password: '123')
 ```
 
-Currently these basic commands are supported:
+Have a close look at the method names. We support bang and non-bang variants.
+The bang variants perform in-deep response validation and raise children of
+`JabberAdmin::Error` in case of detected issues. These issues can be
+unpermitted API requests, or invalid payload values, etc. The predefined
+commands also perform response body checks when it is appropriate. (Eg. many
+commands respond a single zero as a success indicator)
+
+The non-bang variants will just fire the request and do not perform any checks
+on the response. You can implement your own error handling or response analysis
+if you like. You could also just fire and forget them. It's up to you.
+
+Here comes a list of all supported predefined commands:
+
+- [ban_account](https://bit.ly/2KW9xVt)
+- [create_room](https://bit.ly/2rB8DFR)
+- [create_room_with_opts](https://bit.ly/2IBEfVO)
+- [muc_register_nick](https://bit.ly/2G9EBNQ)
+- [registered_users](https://bit.ly/2KhwT6Z)
+- [register](https://bit.ly/2wyhAox)
+- [restart](https://bit.ly/2G7YEwd)
+- [send_direct_invitation](https://bit.ly/2wuTpr2)
+- [send_stanza_c2s](https://bit.ly/2wwUcYr)
+- [send_stanza](https://bit.ly/2rzxyK1)
+- [set_nickname](https://bit.ly/2rBdyqc)
+- [set_presence](https://bit.ly/2rzxyK1)
+- [set_room_affiliation](https://bit.ly/2G5MfbW)
+- [subscribe_room](https://bit.ly/2Ke7Zoy)
+- [unregister](https://bit.ly/2wwYnDE)
+- [unsubscribe_room](https://bit.ly/2G5zcrj)
+
+If you want to contribute more, we accept pull requests!
+
+### Freestyle commands
+
+In case you want to send commands easily without delivering new predefined
+commands with documentation and some nifty tricks, you can simply call the
+ejabberd REST API with your custom commands like this:
+
+```ruby
+JabberAdmin.status
+JabberAdmin.get_last(user: 'tom', host: 'ejabberd.local')
+JabberAdmin.set_presence!(...)
+```
+
+The `JabberAdmin` is smart enough to detect that the given command is not a
+predefined command and therefore it assembles a new `JabberAdmin::ApiCall`
+instance and passes down all arguments. If you look closely you see again that
+we support a bang and non-bang variant. The error handling works the same as on
+predefined commands.
+
+By default the `JabberAdmin::ApiCall` instance assumes it should perform body
+checks on the response which is not clever on data fetching commands, due to
+the fact that they do not deliver `0` as body. The body validation can be
+turned off with the additional `check_res_body: false` argument.
 
-- ban_account
-- create_room
-- register
-- restart
-- send_direct_invitation
-- subscribe_room
-- unregister
-- unsubscribe_room
+```ruby
+JabberAdmin.get_last! \
+  check_res_body: false, user: 'tom', host: 'ejabberd.local'
+```
+
+In case you want to make use of the memorize feature of each
+`JabberAdmin::ApiCall` instance, just build it up directly.
+
+```ruby
+command = JabberAdmin::ApiCall.new('get_last'
+                                   user: 'tom',
+                                   host: 'ejabberd.local')
+# Get the response and memorize it
+command.response.object_id # => 21934400
+# A second call to the response method will not perform a request again
+command.response.object_id # => 21934400
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `make install` to install dependencies. Then,
+run `make test` to run the tests. You can also run `make shell-irb` for an
+interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`, and then
+run `make release`, which will create a git tag for the version, push git
+commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/hausgold/jabber_admin.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/hausgold/jabber_admin.