jabber_admin 2.10.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5d70016fbded8c9138c773121cf64a0af9ad0649f977880b12349b6c5955227
-  data.tar.gz: 2630cf4d854e8eb3050ede0be81f3969a9489edece017b236ee8654779862393
+  metadata.gz: 3f2e90026aefdce2606c730204ccb616b9c75caf383bebcd0e1ff61b98ffd56d
+  data.tar.gz: 5ff8a175b171834fcd12fd6a41855880007e8fe4cf6c4b782217b8fb4cc45640
 SHA512:
-  metadata.gz: aaf70494a4f596e1dcb3d25635850ea5c8445e3952f57f85de229c594920ba16a4f6b226c9fb82111d72508e0cb7d0aaf4a85ee020339f82a3e86a6c7ecbef1f
-  data.tar.gz: db0859c08662419dd597d9034024874a3d5cc6026c31818f7233610b37c94f8e46b252e05ef786a05e5197e83374d0d8d4e974813e77b7c19ad125d0a5f4641b
+  metadata.gz: 8d05859217fd8975bec38d07531c54ee56ced4211f93164ef60626e9a0977685aa20a2290660624fdc28d6c7581ee1ed4e663fdca1f7044bd5050c562a8bae96
+  data.tar.gz: 1e4b22c10f62b0e6a0cc2bbcec1ed09a407839bc0fe977cfaf418a2b0c15e00dd648c433bdb39e91446435a79c8825e0c01ba284f9e4305e7ecc59ca54348c85

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 * TODO: Replace this bullet point with an actual description of a change.
 
+### 3.0.0 (18 September 2026)
+
+* Switched from the rest-client to the http gem ([#34](https://github.com/hausgold/jabber_admin/pull/34))
+
 ### 2.10.0 (27 August 2026)
 
 * Corrected some RuboCop glitches ([#33](https://github.com/hausgold/jabber_admin/pull/33))

data/Gemfile

@@ -21,6 +21,6 @@ gem 'rubocop-rails'
 gem 'rubocop-rspec'
 gem 'simplecov', '>= 0.22'
 gem 'vcr', '~> 6.0'
-gem 'webmock', '~> 3.18'
+gem 'webmock', '~> 3.26'
 gem 'yard', '>= 0.9.28'
 gem 'yard-activesupport-concern', '>= 0.0.1'

data/README.md

@@ -10,6 +10,7 @@ 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)
+- [Upgrading](#upgrading)
 - [Configuration](#configuration)
 - [Usage](#usage)
   - [Predefined commands](#predefined-commands)
@@ -39,6 +40,11 @@ Or install it yourself as:
 $ gem install jabber_admin
 ```
 
+## Upgrading
+
+Major releases come with breaking changes. See the [upgrade
+guide](./UPGRADING.md) for the details and the migration steps.
+
 ## Configuration
 
 You can configure the jabber_admin gem in a global initializer way with the
@@ -55,6 +61,10 @@ JabberAdmin.configure do |config|
   config.username = 'admin@jabber.local'
   # The password of the administrator account.
   config.password = 'password'
+  # The request timeout in seconds, or a hash with per-operation limits
+  # (eg. `{ connect: 5, read: 30, write: 10 }`), or `nil` to disable it.
+  # (60 seconds by default)
+  config.timeout = 60
 end
 ```
 
@@ -162,6 +172,22 @@ command.response.object_id # => 21934400
 command.response.object_id # => 21934400
 ```
 
+The response is an `HTTP::Response` of the
+[http](https://github.com/httprb/http) gem. Its body is already read, so you
+can access the status code and the body string as often as you like.
+
+```ruby
+response = JabberAdmin.get_last(check_res_body: false,
+                                user: 'tom', host: 'ejabberd.local')
+response.code # => 200
+response.body.to_s # => '{"timestamp":"2026-09-17T10:00:00Z","status":"..."}'
+JSON.parse(response.to_s) # => {"timestamp"=>"2026-09-17T10:00:00Z", ...}
+```
+
+Connection failures and timeouts raise an `HTTP::Error` (eg.
+`HTTP::ConnectionError` or `HTTP::TimeoutError`), on the bang and non-bang
+variants alike.
+
 ## Development
 
 After checking out the repo, run `make install` to install dependencies. Then,

data/UPGRADING.md

@@ -0,0 +1,276 @@
+# Upgrading from jabber_admin 2.x to 3.0
+
+This guide covers all breaking changes and required migration steps when
+upgrading from jabber_admin 2.10.x to 3.0.
+
+## Table of Contents
+
+- [Dependency Changes](#dependency-changes)
+- [Configuration Changes](#configuration-changes)
+  - [Request Timeout](#request-timeout)
+- [Response Changes](#response-changes)
+  - [Response Class](#response-class)
+  - [Response Body](#response-body)
+  - [Response Headers](#response-headers)
+  - [Request Content-Type](#request-content-type)
+- [Error Handling Changes](#error-handling-changes)
+  - [Command Errors](#command-errors)
+  - [Connection Failures and Timeouts](#connection-failures-and-timeouts)
+- [Testing Changes](#testing-changes)
+  - [Response Doubles](#response-doubles)
+  - [Request Stubs](#request-stubs)
+  - [VCR Cassettes](#vcr-cassettes)
+  - [WebMock Version](#webmock-version)
+- [Behavior Differences at a Glance](#behavior-differences-at-a-glance)
+
+---
+
+## Dependency Changes
+
+The HTTP client library changed from `rest-client` to `http` (http.rb).
+
+Dependency    | 2.x        | 3.0        | Upgrading Guide
+--------------|------------|------------|----------------
+`rest-client` | `~> 2.1`   | _removed_  | -
+`http`        | _not used_ | `~> 6.0`   | [Changelog](https://github.com/httprb/http/blob/main/CHANGELOG.md)
+
+**Removed transitive dependencies:**
+
+- `http-accept`, `mime-types`, `mime-types-data`, `netrc` — only rest-client
+  needed them
+
+**New transitive dependencies:**
+
+- `llhttp-ffi` — the HTTP parser of http.rb, a native extension loaded via
+  `ffi` (make sure your build environment supports it, `ffi` was already
+  part of the tree)
+- `http-form_data`, `base64` — pulled in by http.rb
+
+The `http-cookie` gem stays in the tree, both clients use it.
+
+If your application used rest-client itself and relied on jabber_admin to
+pull it in, add it to your own Gemfile now:
+
+```ruby
+gem 'rest-client', '~> 2.1'
+```
+
+## Configuration Changes
+
+### Request Timeout
+
+jabber_admin 3.0 adds the optional `config.timeout` option. It defaults to
+60 seconds, which matches the implicit Net::HTTP defaults (60 seconds to
+connect, 60 seconds to read) of jabber_admin 2.x, so nothing changes unless
+you set it.
+
+```ruby
+JabberAdmin.configure do |config|
+  config.url = 'http://jabber.local/api'
+  config.username = 'admin@jabber.local'
+  config.password = 'password'
+
+  # A single number caps the whole request (connect, write and read
+  # together) in seconds. This is the default with 60 seconds.
+  config.timeout = 60
+
+  # A hash sets per-operation limits in seconds instead. The keys are
+  # passed to http.rb as they are, unknown keys raise an ArgumentError on
+  # the first request.
+  config.timeout = { connect: 5, read: 30, write: 10 }
+
+  # Or disable the client timeout entirely.
+  config.timeout = nil
+end
+```
+
+See the [http.rb timeout
+documentation](https://github.com/httprb/http/wiki/Timeouts) for the
+details of the hash form.
+
+## Response Changes
+
+### Response Class
+
+Every command, `JabberAdmin::ApiCall#response`, `#perform` and `#perform!`
+now return an `HTTP::Response` instead of a `RestClient::Response`. The
+status code is still an Integer:
+
+```ruby
+response = JabberAdmin.get_last(check_res_body: false,
+                                user: 'tom', host: 'ejabberd.local')
+response.code # => 200
+```
+
+### Response Body
+
+**This is the change most likely to affect you.** `response.body` is no
+longer a String but an `HTTP::Response::Body` object. Use
+`response.body.to_s` (or the shortcut `response.to_s`) wherever you need
+the String:
+
+```diff
+- JSON.parse(response.body)
++ JSON.parse(response.body.to_s)
+
+- response.body == '0'
++ response.body.to_s == '0'
+
+- response.body.include?('error_no_vcard_found')
++ response.body.to_s.include?('error_no_vcard_found')
+
+- /room does not exist/.match?(response.body)
++ /room does not exist/.match?(response.body.to_s)
+```
+
+Beware of `include?` in particular: the body object is enumerable, so
+`response.body.include?(...)` does not raise a `NoMethodError` but tries
+to stream the already consumed body and fails with an
+`HTTP::StateError`.
+
+jabber_admin reads the body eagerly while performing the request, so the
+memoized response is complete, the connection is closed, and `to_s`
+returns the cached String as often as you call it.
+
+### Response Headers
+
+rest-client exposed the headers as a Hash with symbolized, underscored
+keys. http.rb uses the canonical header names:
+
+```diff
+- response.headers[:content_type]
++ response.headers['Content-Type']
+```
+
+### Request Content-Type
+
+Requests now carry a `Content-Type: application/json; charset=utf-8`
+header. jabber_admin 2.x sent the JSON payload without any content type.
+The payload itself is unchanged.
+
+## Error Handling Changes
+
+### Command Errors
+
+The error classes and their messages are unchanged. The bang variants still
+raise `JabberAdmin::RequestError`, `JabberAdmin::CommandError` and
+`JabberAdmin::UnknownCommandError`, all inheriting from
+`JabberAdmin::Error`, and the message still carries the response body
+(`"Response code was not 200 => {...}"`). Code which matches on
+`error.message` keeps working:
+
+```ruby
+begin
+  JabberAdmin.register!(user: 'tom@jabber.local', password: 'secret')
+rescue JabberAdmin::RequestError => e
+  raise e unless /already registered/.match?(e.message)
+end
+```
+
+Only `error.response` changed its class to `HTTP::Response`, so the
+[Response Body](#response-body) rules apply when you read it:
+
+```diff
+- e.response.body.include?('already registered')
++ e.response.body.to_s.include?('already registered')
+```
+
+### Connection Failures and Timeouts
+
+jabber_admin 2.x rescued every `RestClient::Exception`, including timeouts
+and broken connections, and memoized their (missing) response. The failure
+surfaced later as a `NoMethodError` on `nil`.
+
+jabber_admin 3.0 lets these failures raise directly from `#response`,
+`#perform` and `#perform!` as http.rb errors, all inheriting from
+`HTTP::Error`:
+
+- `HTTP::ConnectionError` — DNS failures, refused connections, broken
+  sockets
+- `HTTP::TimeoutError` — the configured timeout elapsed (see [Request
+  Timeout](#request-timeout))
+
+Rescue them where you want to handle unreachable ejabberd instances:
+
+```diff
+  begin
+    JabberAdmin.restart!
+- rescue JabberAdmin::Error, NoMethodError => e
++ rescue JabberAdmin::Error, HTTP::Error => e
+    # ...
+  end
+```
+
+Responses with a 4xx or 5xx status are still delivered as regular responses
+and turned into `JabberAdmin::Error` subclasses by the bang variants, as
+before.
+
+## Testing Changes
+
+### Response Doubles
+
+Replace `RestClient::Response` doubles with real `HTTP::Response` objects.
+They are cheap to build and behave like the responses jabber_admin
+delivers:
+
+```diff
+- let(:response) do
+-   instance_double(RestClient::Response, code: 200, body: '0')
+- end
++ let(:response) do
++   HTTP::Response.new(status: 200, version: '1.1', body: '0')
++ end
+```
+
+### Request Stubs
+
+Stubs of `RestClient::Request.execute` no longer intercept anything.
+Stub the wire format with WebMock instead, which also lets you assert on
+the request:
+
+```diff
+- allow(RestClient::Request).to receive(:execute).and_return(response)
++ stub_request(:post, 'http://jabber.local/api/restart').to_return(body: '0')
+
+- expect(RestClient::Request).to \
+-   receive(:execute).with(a_hash_including(user: 'admin@jabber.local'))
++ stub = stub_request(:post, 'http://jabber.local/api/restart')
++   .with(basic_auth: %w[admin@jabber.local password])
++ # ... perform the command ...
++ expect(stub).to have_been_requested
+```
+
+Stubbing at the jabber_admin level (`allow(JabberAdmin).to
+receive(:restart!)`) keeps working unchanged.
+
+### VCR Cassettes
+
+Cassettes recorded with jabber_admin 2.x replay without re-recording, as
+long as your VCR configuration uses the default request matchers (method
+and URI). The JSON request body is byte-identical to 2.x. If you match on
+headers, note the new `Content-Type` request header and the changed
+`User-Agent`.
+
+### WebMock Version
+
+http.rb 6 requires WebMock 3.26 or newer, older adapters build the
+responses with a positional Hash and fail with an `ArgumentError` on
+`HTTP::Response.new`. Update your lock:
+
+```shell
+$ bundle update webmock
+```
+
+## Behavior Differences at a Glance
+
+Aspect              | 2.x (rest-client)                 | 3.0 (http.rb)
+--------------------|-----------------------------------|----------------------------------------
+Response class      | `RestClient::Response`            | `HTTP::Response`
+`response.code`     | Integer                           | Integer
+`response.body`     | String                            | `HTTP::Response::Body`, use `.to_s`
+`response.headers`  | `{ content_type: ... }`           | `{ 'Content-Type' => ... }`
+4xx/5xx responses   | `JabberAdmin::Error` on bang       | unchanged
+Connection failures | swallowed, later `NoMethodError`  | `HTTP::ConnectionError`
+Timeouts            | implicit 60s connect / 60s read   | `config.timeout`, 60s global by default
+Request body        | `payload.to_json`                 | unchanged
+Request headers     | no `Content-Type`                 | `Content-Type: application/json; charset=utf-8`

data/gemfiles/rails_8.1.gemfile

@@ -15,7 +15,7 @@ gem "rubocop-rails"
 gem "rubocop-rspec"
 gem "simplecov", ">= 0.22"
 gem "vcr", "~> 6.0"
-gem "webmock", "~> 3.18"
+gem "webmock", "~> 3.26"
 gem "yard", ">= 0.9.28"
 gem "yard-activesupport-concern", ">= 0.0.1"
 gem "activesupport", "~> 8.1.0"

data/jabber_admin.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 4.0'
 
   spec.add_dependency 'activesupport', '>= 8.1'
+  spec.add_dependency 'http', '~> 6.0'
   spec.add_dependency 'logger', '~> 1.7'
-  spec.add_dependency 'rest-client', '~> 2.1'
   spec.add_dependency 'zeitwerk', '~> 2.6'
 end

data/lib/jabber_admin/api_call.rb

@@ -28,21 +28,31 @@ module JabberAdmin
       "#{JabberAdmin.configuration.url.strip.chomp('/')}/#{@command}"
     end
 
+    # Build a ready to use HTTP client for the API call. It carries the
+    # configured administrator credentials as HTTP basic authentication and
+    # the configured request timeout, when one is set.
+    #
+    # @return [HTTP::Session] the prepared HTTP client
+    def client
+      config = JabberAdmin.configuration
+      session = HTTP.basic_auth(user: config.username, pass: config.password)
+      session = session.timeout(config.timeout) if config.timeout
+      session
+    end
+
     # This method compose the actual request, performs 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
+    # The payload is sent as a JSON document. The response body is read
+    # right away, so the response is complete and the connection is closed
+    # when we hand it out. Any status code is delivered as a regular
+    # response, only connection failures and timeouts raise.
+    #
+    # @return [HTTP::Response] the response of the API call
+    # @raise [HTTP::Error] on connection failures or timeouts
     def response
-      @response ||= RestClient::Request.execute(
-        method: :post,
-        url: url,
-        user: JabberAdmin.configuration.username,
-        password: JabberAdmin.configuration.password,
-        payload: payload.to_json
-      )
-    rescue RestClient::Exception => e
-      @response = e.response
+      @response ||= client.post(url, json: payload).flush
     end
 
     # Check if the response was successful. Otherwise raise exceptions with
@@ -77,12 +87,13 @@ module JabberAdmin
       # not get any further information here, which makes error debugging a
       # struggle.
       raise CommandError.new('Command was not successful', response) \
-        unless response.body == '0'
+        unless response.body.to_s == '0'
     end
 
     # Just a simple DSL wrapper for the response method.
     #
-    # @return [RestClient::Response] the API call response
+    # @return [HTTP::Response] the API call response
+    # @raise [HTTP::Error] on connection failures or timeouts
     def perform
       response
     end
@@ -93,7 +104,8 @@ module JabberAdmin
     #
     # @raise JabberAdmin::ApiError
     # @raise JabberAdmin::CommandError
-    # @return [RestClient::Response] the API call response
+    # @raise [HTTP::Error] on connection failures or timeouts
+    # @return [HTTP::Response] the API call response
     def perform!
       check_response
       response
@@ -105,7 +117,8 @@ module JabberAdmin
     #
     # @param args [Array<Mixed>] the initializer arguments
     # @param kwargs [Hash{Symbol => Mixed}] the initializer arguments
-    # @return [RestClient::Response] the API call response
+    # @return [HTTP::Response] the API call response
+    # @raise [HTTP::Error] on connection failures or timeouts
     def self.perform(*, **)
       new(*, **).perform
     end
@@ -116,10 +129,11 @@ module JabberAdmin
     #
     # @param args [Array<Mixed>] the initializer arguments
     # @param kwargs [Hash{Symbol => Mixed}] the initializer arguments
-    # @return [RestClient::Response] the API call response
+    # @return [HTTP::Response] the API call response
     #
     # @raise JabberAdmin::ApiError
     # @raise JabberAdmin::CommandError
+    # @raise [HTTP::Error] on connection failures or timeouts
     def self.perform!(*, **)
       new(*, **).perform!
     end

data/lib/jabber_admin/commands/get_room_affiliations.rb

@@ -16,7 +16,9 @@ module JabberAdmin
                                                      name: name,
                                                      service: service)
 
-        res.body ? JSON.parse(res.body) : nil
+        # An empty body carries no affiliations to parse
+        body = res.body.to_s
+        body.empty? ? nil : JSON.parse(body)
       end
     end
   end

data/lib/jabber_admin/commands/get_vcard.rb

@@ -53,13 +53,13 @@ module JabberAdmin
 
           res = callable.call(meth, check_res_body: false,
                                     user: uid, host: host, **args)
-          body = (200..299).cover?(res.code) ? JSON.parse(res.body) : nil
+          body = (200..299).cover?(res.code) ? JSON.parse(res.body.to_s) : nil
           body.is_a?(Hash) ? body['content'] : body
         rescue JabberAdmin::Error => e
           # When ejabberd tells us there was no value, it does this the hard way
-          next if e.response.body.include? 'error_no_value_found_in_vcard'
+          next if e.response.body.to_s.include? 'error_no_value_found_in_vcard'
           # Same for the case when there is no vCard at all
-          next if e.response.body.include? 'error_no_vcard_found'
+          next if e.response.body.to_s.include? 'error_no_vcard_found'
 
           raise e
         end

data/lib/jabber_admin/configuration.rb

@@ -7,6 +7,25 @@ module JabberAdmin
   #
   # See the +JabberAdmin+ documentation for further details.
   class Configuration
+    # The ejabberd REST API endpoint and the administrator credentials
     attr_accessor :username, :password, :url
+
+    # The request timeout, either in seconds as a single number which caps
+    # the whole request (connect, write and read together), or a hash with
+    # per-operation limits (eg. +{ connect: 5, read: 30, write: 10 }+), or
+    # +nil+ to disable the client timeout entirely. The value is passed to
+    # the http gem as is, so a malformed hash raises an +ArgumentError+ on
+    # the first request.
+    #
+    # See: https://github.com/httprb/http/wiki/Timeouts
+    #
+    # @return [Numeric, Hash{Symbol => Numeric}, nil] the request timeout
+    attr_accessor :timeout
+
+    # Setup a new configuration instance with the defaults. The endpoint and
+    # the credentials have no defaults, the timeout defaults to 60 seconds.
+    def initialize
+      @timeout = 60
+    end
   end
 end

data/lib/jabber_admin/errors.rb

@@ -16,7 +16,7 @@ module JabberAdmin
     # Create a new exception.
     #
     # @param msg [String] the exception message
-    # @param response [RestClient::Response] the response when available
+    # @param response [HTTP::Response] the response when available
     def initialize(msg, response = nil)
       @response = response
       msg += " => #{response.body}" if response&.body

data/lib/jabber_admin/version.rb

@@ -3,7 +3,7 @@
 # The gem version details.
 module JabberAdmin
   # The version of the +jabber_admin+ gem
-  VERSION = '2.10.0'
+  VERSION = '3.0.0'
 
   class << self
     # Returns the version of gem as a string.

data/lib/jabber_admin.rb

@@ -4,7 +4,7 @@ require 'zeitwerk'
 require 'logger'
 require 'active_support/inflector'
 require 'json'
-require 'rest-client'
+require 'http'
 
 # jabber_admin
 #
@@ -37,6 +37,10 @@ require 'rest-client'
 #     config.username = 'admin@jabber.local'
 #     # The password of the administrator account.
 #     config.password = 'password'
+#     # The request timeout in seconds, or a per-operation hash
+#     # (eg. +{ connect: 5, read: 30, write: 10 }+), or +nil+ to
+#     # disable it. (60 seconds by default)
+#     config.timeout = 60
 #   end
 #
 # @example Restart the ejabberd service
@@ -97,7 +101,7 @@ module JabberAdmin
     # @param method [Symbol, String, #to_s] the name of the command to run
     # @param args [Array<Mixed>] all additional API call payload
     # @param kwargs [Hash{Symbol => Mixed}] all additional API call payload
-    # @return [RestClient::Response] the actual response of the command
+    # @return [HTTP::Response] the actual response of the command
     def method_missing(method, *, **)
       predefined_command(method).call(
         predefined_callable(method), *, **
@@ -144,7 +148,7 @@ module JabberAdmin
       get_room_affiliations!(room: room)
       true
     rescue JabberAdmin::CommandError => e
-      raise e unless /room does not exist/.match? e.response.body
+      raise e unless /room does not exist/.match? e.response.body.to_s
 
       false
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jabber_admin
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Hermann Mayer
@@ -25,33 +25,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8.1'
 - !ruby/object:Gem::Dependency
-  name: logger
+  name: http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +93,7 @@ files:
 - Makefile
 - README.md
 - Rakefile
+- UPGRADING.md
 - bin/config.rb
 - bin/console
 - bin/setup
@@ -150,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Library for the ejabberd RESTful admin API
 test_files: []