jabber_admin 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. checksums.yaml +5 -5
  2. data/.editorconfig +30 -0
  3. data/.gitignore +4 -2
  4. data/.rubocop.yml +33 -0
  5. data/.simplecov +3 -0
  6. data/.travis.yml +7 -3
  7. data/.yardopts +4 -0
  8. data/CHANGELOG.md +30 -0
  9. data/Gemfile +4 -2
  10. data/Makefile +100 -0
  11. data/README.md +142 -22
  12. data/Rakefile +5 -3
  13. data/bin/console +4 -3
  14. data/docker-compose.yml +15 -0
  15. data/jabber_admin.gemspec +22 -15
  16. data/lib/jabber_admin.rb +100 -34
  17. data/lib/jabber_admin/api_call.rb +106 -20
  18. data/lib/jabber_admin/commands.rb +6 -5
  19. data/lib/jabber_admin/commands/ban_account.rb +11 -10
  20. data/lib/jabber_admin/commands/create_room.rb +15 -10
  21. data/lib/jabber_admin/commands/create_room_with_opts.rb +20 -14
  22. data/lib/jabber_admin/commands/muc_register_nick.rb +26 -0
  23. data/lib/jabber_admin/commands/register.rb +16 -11
  24. data/lib/jabber_admin/commands/registered_users.rb +8 -6
  25. data/lib/jabber_admin/commands/restart.rb +8 -5
  26. data/lib/jabber_admin/commands/send_direct_invitation.rb +19 -16
  27. data/lib/jabber_admin/commands/send_stanza.rb +12 -10
  28. data/lib/jabber_admin/commands/send_stanza_c2s.rb +28 -0
  29. data/lib/jabber_admin/commands/set_nickname.rb +22 -0
  30. data/lib/jabber_admin/commands/set_presence.rb +37 -0
  31. data/lib/jabber_admin/commands/set_room_affiliation.rb +17 -12
  32. data/lib/jabber_admin/commands/subscribe_room.rb +19 -12
  33. data/lib/jabber_admin/commands/unregister.rb +13 -7
  34. data/lib/jabber_admin/commands/unsubscribe_room.rb +10 -7
  35. data/lib/jabber_admin/configuration.rb +6 -1
  36. data/lib/jabber_admin/exceptions.rb +40 -0
  37. data/lib/jabber_admin/version.rb +3 -1
  38. metadata +85 -16
  39. data/lib/jabber_admin/initializer.rb +0 -6
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 9b60bf9121f5fd712ba6e08eec98005067fc2957
4
- data.tar.gz: '0931c367247d9500e1086590361e0e97067ad602'
2
+ SHA256:
3
+ metadata.gz: 7595ac9bd9cd6f045626d75d5198e65515b6a1c81b5dd2ff98d71067f66a8b1a
4
+ data.tar.gz: 344565013c98a99b5aa6a58e4ae1292fcece4a24d19fc9b3a7366bfbb95af80a
5
5
  SHA512:
6
- metadata.gz: 4b925cd9840cefa15a39fa8e578681ab5b411e9361384f1f8adf8197de0c60136ddedaa375b88223d700bfef6213aa521b449bfba1be4d5d3e60c649436afae2
7
- data.tar.gz: b2586b050d2314014ee9bb2a4390a204a91817b00fa2cb468b22e8d37f35148a135f7d56bef22a207ac2904ee116efe17e1b418b22811f15cb7267c1c7af5864
6
+ metadata.gz: 1aad50ff432b9e24ac56ea25e3394cc601e3acf610a809944f301043cdd3a7fa407f4fd7ed962b6413364588caa5f4616d1a90e28b5e540a80ad22a462c02594
7
+ data.tar.gz: c6b3547c3dd1adb0728cc592743a46c9d012f708e881370d36da63be8d5b8148ed5a76975c25696d7d1a3b2dca501142cde24e01c435730ae9e803e636f37ccf
@@ -0,0 +1,30 @@
1
+ # http://editorconfig.org
2
+ root = true
3
+
4
+ [*]
5
+ indent_style = space
6
+ indent_size = 2
7
+ end_of_line = lf
8
+ charset = utf-8
9
+ trim_trailing_whitespace = true
10
+ insert_final_newline = true
11
+
12
+ [*.md]
13
+ trim_trailing_whitespace = true
14
+
15
+ [*.json]
16
+ indent_style = space
17
+ indent_size = 2
18
+
19
+ [*.yml]
20
+ indent_style = space
21
+ indent_size = 2
22
+
23
+ [Makefile]
24
+ trim_trailing_whitespace = true
25
+ indent_style = tab
26
+ indent_size = 4
27
+
28
+ [*.sh]
29
+ indent_style = space
30
+ indent_size = 2
data/.gitignore CHANGED
@@ -3,11 +3,13 @@
3
3
  /Gemfile.lock
4
4
  /_yardoc/
5
5
  /coverage/
6
+ /doc/
6
7
  /pkg/
7
8
  /spec/reports/
8
9
  /tmp/
10
+ /vendor/
11
+ /gemfiles/vendor/
12
+ *.gemfile.lock
9
13
 
10
14
  # rspec failure tracking
11
15
  .rspec_status
12
-
13
- *.gem
@@ -0,0 +1,33 @@
1
+ require: rubocop-rspec
2
+
3
+ Rails:
4
+ Enabled: true
5
+
6
+ Documentation:
7
+ Enabled: true
8
+
9
+ AllCops:
10
+ DisplayCopNames: true
11
+ TargetRubyVersion: 2.2
12
+
13
+ Metrics/BlockLength:
14
+ Exclude:
15
+ - Rakefile
16
+ - spec/**/*.rb
17
+ - '**/*.rake'
18
+ - '*.gemspec'
19
+
20
+ # Document all the things.
21
+ Style/DocumentationMethod:
22
+ Enabled: true
23
+ RequireForNonPublicMethods: true
24
+
25
+ # Because +expect_any_instance_of().to have_received()+ is not
26
+ # supported with the +with(hash_including)+ matchers
27
+ RSpec/MessageSpies:
28
+ EnforcedStyle: receive
29
+
30
+ # Allow deeper nesting because of the predefined/non-predefined -
31
+ # bang/non-bang cases.
32
+ RSpec/NestedGroups:
33
+ Max: 4
@@ -0,0 +1,3 @@
1
+ SimpleCov.start 'test_frameworks' do
2
+ add_filter '/vendor/bundle/'
3
+ end
@@ -1,12 +1,16 @@
1
+ sudo: false
2
+
1
3
  env:
2
4
  global:
3
5
  - CC_TEST_REPORTER_ID=02d696c72627e730a3db553884276acf15672466e32e66a788672d3b167629ca
4
- sudo: false
6
+
5
7
  language: ruby
6
8
  rvm:
7
- - 2.2
8
- - 2.3
9
+ - 2.5
9
10
  - 2.4
11
+ - 2.3
12
+ - 2.2
13
+
10
14
  before_install: gem install bundler -v 1.15.1
11
15
  before_script:
12
16
  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
@@ -0,0 +1,4 @@
1
+ --output-dir=doc/app
2
+ -
3
+ README.md
4
+ lib/**/*.rb
@@ -0,0 +1,30 @@
1
+ ### 0.2.0
2
+
3
+ * [BC] The configuration has changed
4
+ * `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)
5
+ * `admin` => `username`, we want to be use common sense API client jargon here
6
+ * We support from now on predefined AND freestyle commands on the `JabberAdmin` module
7
+ * 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
8
+ * [BC] Previously only bang variants were possible, without response checking, look out for more exceptions when you migrate
9
+ * New predefined commands:
10
+ * muc_register_nick
11
+ * send_stanza_c2s
12
+ * set_nickname
13
+ * The documentation was greatly improved
14
+ * The testcases were rewritten and tested with VCR against a real ejabberd server (18.01)
15
+
16
+ ### 0.1.4
17
+
18
+ * Added support for predefined commands
19
+ * ban_account
20
+ * create_room
21
+ * create_room_with_opts
22
+ * register
23
+ * registered_users
24
+ * restart
25
+ * send_direct_invitation
26
+ * send_stanza
27
+ * set_room_affiliation
28
+ * subscribe_room
29
+ * unregister
30
+ * unsubscribe_room
data/Gemfile CHANGED
@@ -1,6 +1,8 @@
1
- source "https://rubygems.org"
1
+ # frozen_string_literal: true
2
2
 
3
- git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
3
+ source 'https://rubygems.org'
4
+
5
+ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
4
6
 
5
7
  # Specify your gem's dependencies in jabber_admin.gemspec
6
8
  gemspec
@@ -0,0 +1,100 @@
1
+ MAKEFLAGS += --warn-undefined-variables -j1
2
+ SHELL := bash
3
+ .SHELLFLAGS := -eu -o pipefail -c
4
+ .DEFAULT_GOAL := all
5
+ .DELETE_ON_ERROR:
6
+ .SUFFIXES:
7
+ .PHONY:
8
+
9
+ # Environment switches
10
+ MAKE_ENV ?= docker
11
+ COMPOSE_RUN_SHELL_FLAGS ?= --rm
12
+
13
+ # Directories
14
+ VENDOR_DIR ?= vendor/bundle
15
+
16
+ # Host binaries
17
+ BASH ?= bash
18
+ COMPOSE ?= docker-compose
19
+ ECHO ?= echo
20
+ GREP ?= grep
21
+ ID ?= id
22
+ MKDIR ?= mkdir
23
+ RM ?= rm
24
+ SED ?= sed
25
+ SORT ?= sort
26
+
27
+ # Container binaries
28
+ BUNDLE ?= bundle
29
+ RAKE ?= rake
30
+
31
+ all:
32
+ # jabber_admin
33
+ #
34
+ # install Install the dependencies
35
+ # test Run the whole test suite
36
+ # clean Clean the dependencies
37
+ #
38
+ # shell Run an interactive shell on the container
39
+ # shell-irb Run an interactive IRB shell on the container
40
+ #
41
+ # supported-commands-list Generate the supported commands list
42
+
43
+ # Define a generic shell run wrapper
44
+ # $1 - The command to run
45
+ ifeq ($(MAKE_ENV),docker)
46
+ define run-shell
47
+ $(COMPOSE) run $(COMPOSE_RUN_SHELL_FLAGS) \
48
+ -e LANG=en_US.UTF-8 -e LANGUAGE=en_US.UTF-8 -e LC_ALL=en_US.UTF-8 \
49
+ -e HOME=/tmp -e BUNDLE_APP_CONFIG=/app/.bundle \
50
+ -u `$(ID) -u` test bash -c 'sleep 0.1; echo; $(1)'
51
+ endef
52
+ else ifeq ($(MAKE_ENV),baremetal)
53
+ define run-shell
54
+ $(1)
55
+ endef
56
+ endif
57
+
58
+ install:
59
+ # Install the dependencies
60
+ @$(MKDIR) -p $(VENDOR_DIR)
61
+ @$(call run-shell,$(BUNDLE) check || $(BUNDLE) install --path $(VENDOR_DIR))
62
+
63
+ test: install
64
+ # Run the whole test suite
65
+ @$(call run-shell,$(BUNDLE) exec $(RAKE))
66
+
67
+ clean:
68
+ # Clean the dependencies
69
+ @$(RM) -rf $(VENDOR_DIR)
70
+
71
+ clean-containers:
72
+ # Clean running containers
73
+ ifeq ($(MAKE_ENV),docker)
74
+ @$(COMPOSE) down
75
+ endif
76
+
77
+ distclean: clean clean-containers
78
+
79
+ shell: install
80
+ # Run an interactive shell on the container
81
+ @$(call run-shell,$(BASH) -i)
82
+
83
+ shell-irb: install
84
+ # Run an interactive IRB shell on the container
85
+ @$(call run-shell,bin/console)
86
+
87
+ release:
88
+ # Release a new gem version
89
+ @$(RAKE) release
90
+
91
+ supported-commands-list:
92
+ # Generate the supported commands list
93
+ @$(ECHO)
94
+ @$(GREP) -oP '@see https?://.*' -R lib/jabber_admin/commands/ \
95
+ | $(SED) \
96
+ -e 's/@see //g' \
97
+ -e 's/.rb:/](/g' \
98
+ -e 's/$$/)/g' \
99
+ -e 's#^lib/jabber_admin/commands/#- [#g' \
100
+ | $(SORT)
data/README.md CHANGED
@@ -1,10 +1,21 @@
1
1
  ![jabber_admin](doc/assets/project.png)
2
2
 
3
+ [![Build Status](https://travis-ci.org/hausgold/jabber_admin.svg?branch=master)](https://travis-ci.org/hausgold/jabber_admin)
4
+ [![Gem Version](https://badge.fury.io/rb/jabber_admin.svg)](https://badge.fury.io/rb/jabber_admin)
3
5
  [![Maintainability](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/maintainability)](https://codeclimate.com/github/hausgold/jabber_admin/maintainability)
4
6
  [![Test Coverage](https://api.codeclimate.com/v1/badges/0b3c444d8db8acaaba97/test_coverage)](https://codeclimate.com/github/hausgold/jabber_admin/test_coverage)
7
+ [![API docs](https://img.shields.io/badge/docs-API-blue.svg)](https://www.rubydoc.info/gems/jabber_admin)
5
8
 
6
- jabber_admin is a small library to easily communicate with the ejabberd
7
- admin API.
9
+ jabber_admin is a small library to easily communicate with the [ejabberd
10
+ admin API](https://docs.ejabberd.im/developer/ejabberd-api/admin-api).
11
+
12
+ - [Installation](#installation)
13
+ - [Configuration](#configuration)
14
+ - [Usage](#usage)
15
+ - [Predefined commands](#predefined-commands)
16
+ - [Freestyle commands](#freestyle-commands)
17
+ - [Development](#development)
18
+ - [Contributing](#contributing)
8
19
 
9
20
  ## Installation
10
21
 
@@ -16,40 +27,149 @@ gem 'jabber_admin'
16
27
 
17
28
  And then execute:
18
29
 
19
- $ bundle
30
+ ```bash
31
+ $ bundle
32
+ ```
20
33
 
21
34
  Or install it yourself as:
22
35
 
23
- $ gem install jabber_admin
36
+ ```bash
37
+ $ gem inst.object_idall jabber_admin
38
+ ```
39
+
40
+ ## Configuration
41
+
42
+ You can configure the jabber_admin gem in a global initializer way with the
43
+ `JabberAdmin.configure` method which yields the configuration directly.
44
+
45
+ ```ruby
46
+ JabberAdmin.configure do |config|
47
+ # The ejabberd REST API endpoint as a full URL.
48
+ # Take care of the path part, because this is individually
49
+ # configured on ejabberd. (See: https://bit.ly/2rBxatJ)
50
+ config.url = 'http://jabber.local/api'
51
+ # Provide here the full user JID in order to authenticate as
52
+ # a administrator.
53
+ config.username = 'admin@jabber.local'
54
+ # The password of the administrator account.
55
+ config.password = 'password'
56
+ end
57
+ ```
58
+
59
+ In case this is not cool for you, you can get and modify the configuration
60
+ directly with the help of the `JabberAdmin.configuration` getter.
61
+
62
+ ```ruby
63
+ JabberAdmin.configuration.url = 'http://jabber.local/api'
64
+ JabberAdmin.configuration.username = 'admin@jabber.local'
65
+ JabberAdmin.configuration.password = 'password'
66
+ ```
24
67
 
25
68
  ## Usage
26
69
 
27
- ``` ruby
70
+ ### Predefined commands
71
+
72
+ We support some handy predefined commands out of the box which ease the quick
73
+ start usage. These predefined commands comes with a good documentation
74
+ (including valid example data) and a nifty interface. When it is possible to
75
+ fill up missing data from a full user/room JID we do so. Say while sending a
76
+ direct invitation, you just pass the full room JID and we take care of
77
+ splitting it up to fulfill the separate room name and the separate MUC service
78
+ domain.
79
+
80
+ All our predefined commands are available directly underneath the `JabberAdmin`
81
+ module as methods. Just call them like this:
82
+
83
+ ```ruby
28
84
  JabberAdmin.restart!
29
- JabberAdmin.create_room!(name: 'room1', host: '...')
85
+ JabberAdmin.register(user: 'peter@example.com', password: '123')
30
86
  ```
31
87
 
32
- Currently these basic commands are supported:
88
+ Have a close look at the method names. We support bang and non-bang variants.
89
+ The bang variants perform in-deep response validation and raise children of
90
+ +JabberAdmin::Error+ in case of detected issues. These issues can be
91
+ unpermitted API requests, or invalid payload values, etc. The predefined
92
+ commands also perform response body checks when it is appropriate. (Eg. many
93
+ commands respond a single zero as a success indicator)
94
+
95
+ The non-bang variants will just fire the request and do not perform any checks
96
+ on the response. You can implement your own error handling or response analysis
97
+ if you like. You could also just fire and forget them. It's up to you.
98
+
99
+ Here comes a list of all supported predefined commands:
100
+
101
+ - [ban_account](https://bit.ly/2KW9xVt)
102
+ - [create_room](https://bit.ly/2rB8DFR)
103
+ - [create_room_with_opts](https://bit.ly/2IBEfVO)
104
+ - [muc_register_nick](https://bit.ly/2G9EBNQ)
105
+ - [registered_users](https://bit.ly/2KhwT6Z)
106
+ - [register](https://bit.ly/2wyhAox)
107
+ - [restart](https://bit.ly/2G7YEwd)
108
+ - [send_direct_invitation](https://bit.ly/2wuTpr2)
109
+ - [send_stanza_c2s](https://bit.ly/2wwUcYr)
110
+ - [send_stanza](https://bit.ly/2rzxyK1)
111
+ - [set_nickname](https://bit.ly/2rBdyqc)
112
+ - [set_presence](https://bit.ly/2rzxyK1)
113
+ - [set_room_affiliation](https://bit.ly/2G5MfbW)
114
+ - [subscribe_room](https://bit.ly/2Ke7Zoy)
115
+ - [unregister](https://bit.ly/2wwYnDE)
116
+ - [unsubscribe_room](https://bit.ly/2G5zcrj)
117
+
118
+ If you want to contribute more, we accept pull requests!
119
+
120
+ ### Freestyle commands
121
+
122
+ In case you want to send commands easily without delivering new predefined
123
+ commands with documentation and some nifty tricks, you can simply call the
124
+ ejabberd REST API with your custom commands like this:
125
+
126
+ ```ruby
127
+ JabberAdmin.status
128
+ JabberAdmin.get_last(user: 'tom', host: 'ejabberd.local')
129
+ JabberAdmin.set_presence!(...)
130
+ ```
131
+
132
+ The `JabberAdmin` is smart enough to detect that the given command is not a
133
+ predefined command and therefore it assembles a new `JabberAdmin::ApiCall`
134
+ instance and passes down all arguments. If you look closely you see again that
135
+ we support a bang and non-bang variant. The error handling works the same as on
136
+ predefined commands.
137
+
138
+ By default the `JabberAdmin::ApiCall` instance assumes it should perform body
139
+ checks on the response which is not clever on data fetching commands, due to
140
+ the fact that they do not deliver `0` as body. The body validation can be
141
+ turned off with the additional `check_res_body: false` argument.
33
142
 
34
- - ban_account
35
- - create_room
36
- - create_room_with_opts
37
- - register
38
- - registered_users
39
- - restart
40
- - send_direct_invitation
41
- - send_stanza
42
- - set_room_affiliation
43
- - subscribe_room
44
- - unregister
45
- - unsubscribe_room
143
+ ```ruby
144
+ JabberAdmin.get_last! \
145
+ check_res_body: false, user: 'tom', host: 'ejabberd.local'
146
+ ```
147
+
148
+ In case you want to make use of the memorize feature of each
149
+ `JabberAdmin::ApiCall` instance, just build it up directly.
150
+
151
+ ```ruby
152
+ command = JabberAdmin::ApiCall.new('get_last'
153
+ user: 'tom',
154
+ host: 'ejabberd.local')
155
+ # Get the response and memorize it
156
+ command.response.object_id # => 21934400
157
+ # A second call to the response method will not perform a request again
158
+ command.response.object_id # => 21934400
159
+ ```
46
160
 
47
161
  ## Development
48
162
 
49
- 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.
163
+ After checking out the repo, run `make install` to install dependencies. Then,
164
+ run `make test` to run the tests. You can also run `make shell-irb` for an
165
+ interactive prompt that will allow you to experiment.
50
166
 
51
- 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).
167
+ To release a new version, update the version number in `version.rb`, and then
168
+ run `make release`, which will create a git tag for the version, push git
169
+ commits and tags, and push the `.gem` file to
170
+ [rubygems.org](https://rubygems.org).
52
171
 
53
172
  ## Contributing
54
173
 
55
- Bug reports and pull requests are welcome on GitHub at https://github.com/hausgold/jabber_admin.
174
+ Bug reports and pull requests are welcome on GitHub at
175
+ https://github.com/hausgold/jabber_admin.