hausgold/jabber_admin

Ruby library for the ejabberd RESTful admin API

jabber_admin is a small library to easily communicate with the ejabberd admin API.

• Installation
• Configuration
• Usage
  • Predefined commands
  • Freestyle commands
• Development
• Code of Conduct
• Contributing
• Releasing

Installation

Add this line to your application's Gemfile:

gem 'jabber_admin'

And then execute:

$ bundle

Or install it yourself as:

$ 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.

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.

JabberAdmin.configuration.url = 'http://jabber.local/api'
JabberAdmin.configuration.username = 'admin@jabber.local'
JabberAdmin.configuration.password = 'password'

Usage

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:

JabberAdmin.restart!
JabberAdmin.register(user: 'peter@example.com', password: '123')

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
• create_room
• create_room_with_opts
• muc_register_nick
• registered_users
• register
• restart
• send_direct_invitation
• send_stanza_c2s
• send_stanza
• set_nickname
• set_presence
• set_room_affiliation
• subscribe_room
• unregister
• unsubscribe_room
• destroy_room
• get_room_affiliations

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:

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.

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.

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 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.

Code of Conduct

Everyone interacting in the project codebase, issue tracker, chat rooms and mailing lists is expected to follow the code of conduct.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hausgold/jabber_admin. Make sure that every pull request adds a bullet point to the changelog file with a reference to the actual pull request.

Releasing

The release process of this Gem is fully automated. You just need to open the Github Actions Release Workflow and trigger a new run via the Run workflow button. Insert the new version number (check the changelog first for the latest release) and you're done.