jabber_admin 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9b60bf9121f5fd712ba6e08eec98005067fc2957
-  data.tar.gz: '0931c367247d9500e1086590361e0e97067ad602'
+SHA256:
+  metadata.gz: 7595ac9bd9cd6f045626d75d5198e65515b6a1c81b5dd2ff98d71067f66a8b1a
+  data.tar.gz: 344565013c98a99b5aa6a58e4ae1292fcece4a24d19fc9b3a7366bfbb95af80a
 SHA512:
-  metadata.gz: 4b925cd9840cefa15a39fa8e578681ab5b411e9361384f1f8adf8197de0c60136ddedaa375b88223d700bfef6213aa521b449bfba1be4d5d3e60c649436afae2
-  data.tar.gz: b2586b050d2314014ee9bb2a4390a204a91817b00fa2cb468b22e8d37f35148a135f7d56bef22a207ac2904ee116efe17e1b418b22811f15cb7267c1c7af5864
+  metadata.gz: 1aad50ff432b9e24ac56ea25e3394cc601e3acf610a809944f301043cdd3a7fa407f4fd7ed962b6413364588caa5f4616d1a90e28b5e540a80ad22a462c02594
+  data.tar.gz: c6b3547c3dd1adb0728cc592743a46c9d012f708e881370d36da63be8d5b8148ed5a76975c25696d7d1a3b2dca501142cde24e01c435730ae9e803e636f37ccf

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,33 @@
+require: rubocop-rspec
+
+Rails:
+  Enabled: true
+
+Documentation:
+  Enabled: true
+
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.2
+
+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

data/.simplecov

@@ -0,0 +1,3 @@
+SimpleCov.start 'test_frameworks' do
+  add_filter '/vendor/bundle/'
+end

data/.travis.yml

@@ -1,12 +1,16 @@
+sudo: false
+
 env:
   global:
     - CC_TEST_REPORTER_ID=02d696c72627e730a3db553884276acf15672466e32e66a788672d3b167629ca
-sudo: false
+
 language: ruby
 rvm:
-  - 2.2
-  - 2.3
+  - 2.5
   - 2.4
+  - 2.3
+  - 2.2
+
 before_install: gem install bundler -v 1.15.1
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter

data/.yardopts

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

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+### 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
+* 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,100 @@
+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
+
+all:
+	# jabber_admin
+	#
+	# install                  Install the dependencies
+	# test                     Run the whole test suite
+	# 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))
+
+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 @@
 ![jabber_admin](doc/assets/project.png)
 
+[![Build Status](https://travis-ci.org/hausgold/jabber_admin.svg?branch=master)](https://travis-ci.org/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/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)
+[![API docs](https://img.shields.io/badge/docs-API-blue.svg)](https://www.rubydoc.info/gems/jabber_admin)
 
-jabber_admin 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,40 +27,149 @@ gem 'jabber_admin'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install jabber_admin
+```bash
+$ gem inst.object_idall 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
-- create_room_with_opts
-- register
-- registered_users
-- restart
-- send_direct_invitation
-- send_stanza
-- set_room_affiliation
-- 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.