blackevin 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c81bfd943d2a666cb4708cbf7fb68dda7e9bfa73a4563ad3ec444475031bc62
-  data.tar.gz: ef8433cd9a72fe8429521b93e2724044ec5fac06a94af1053962db3e67468379
+  metadata.gz: b88ba03b32ee0b815636e6cebc77a95669c1df92d3734ac6c6ec66023f781012
+  data.tar.gz: 7f01c4066dc941d1b86493eac3cd60dc2be0838475de5a3227da6a7d8dff4419
 SHA512:
-  metadata.gz: f11f01f55bbc204af64100bffb53e88540c3c8374c80df2d42a68b551279f9f3b80c0fc3611458fcd5643645a6efbad48b8f4a073af44c76c2b96e4811959193
-  data.tar.gz: d4fe938a5b52edfe02b9cf9e86b300b6ebe98fcceb22807dc0c7d7eb937b39f8f010a4a9de9c0f804f61359338934e523f536f9bd15ecac2484729a768d846e6
+  metadata.gz: 4fe362bb04448fd8cfc8177da89d07dbd225ebe4e7de4ee661021c8be7a338571c9b036dd654ff22439475e6a0d87fcfceec5131580aeb958837e52ee7211250
+  data.tar.gz: 210ea311e3c7acf55d63032fab8ebc05127c71a43874c0e015cae522063a42247ce3293251b56833c0c9ff84ca515e36169cefed024ca6cce1e6bacc867d16f2

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0
+
+**Breaking.** The client is an instance, always.
+
+- Removed `Blackevin.rest`. There is no process-wide client and no class-level call that
+  touches the network. Build one: `bk = Blackevin::Rest.new`.
+- `Blackevin::Rest.new` now falls back, option by option, to `Blackevin.configure` and then to
+  `BLACKEVIN_KEY` — so `new` with no arguments works wherever `Blackevin.rest` used to.
+- Every part stands alone: `Blackevin::Rest::Auth.new`, `Channels.new`, `Channel.new(name)`,
+  `Presence.new(name)`, `Clients.new` and `Queues.new` take an optional `client:` and build a
+  `Blackevin::Rest` without one. `bk.auth`, `bk.channels` and the rest are those same classes.
+- One class per file under `lib/blackevin/rest/`.
+- `Blackevin.configure` only stores defaults. Reconfiguring no longer affects a client already built.
+- `Blackevin::TokenEndpoint` without `rest:` builds a `Blackevin::Rest` per request.
+- The Railtie is unchanged: it fills the configuration from `config.blackevin.*` and credentials.
+- Style is RuboCop running Standard's rules with single quotes (`bundle exec rubocop`).
+- `bundle exec rake coverage` runs the suite under SimpleCov, Rails subprocesses merged in, and
+  fails under 100% lines or 95% branches.
+
+Migrating: replace `Blackevin.rest` with `Blackevin::Rest.new`.
+
 ## 0.1.1
 
 - Remove lint from CI

data/README.md

@@ -10,30 +10,70 @@ library — nothing that can break under you in an upgrade. Ruby 3.0 and up, in
 Rails, Sinatra, Hanami or a plain script.
 
 ```ruby
-gem "blackevin"
+gem 'blackevin'
 ```
 
-## Configure
+## The client
 
-With `BLACKEVIN_KEY` in the environment there is nothing to configure:
+You work with an instance. There is no global client and no class-level call
+that touches the network.
 
 ```ruby
-Blackevin.rest.channels.get("room:42").publish("greeting", {text: "hi"})
+bk = Blackevin::Rest.new
+
+ch = bk.channels.get('room:42')
+ch.publish('greeting', {text: 'hi'})
 ```
 
-Or say it explicitly, once, at boot:
+With `BLACKEVIN_KEY` in the environment, `new` needs no arguments. Creating one is
+cheap — it opens no connection and holds no state — so build it where you use
+it, or keep one in a constant; both are fine, and an instance is thread-safe.
+
+### Each part stands alone
+
+Nothing forces a chain through `Blackevin::Rest`. Every part is a class you can
+build by itself; without a `client:` it makes its own from the configuration.
 
 ```ruby
+Blackevin::Rest::Auth.new.create_token_request(client_id: current_user.id)
+Blackevin::Rest::Channel.new('room:42').publish('greeting', {text: 'hi'})
+Blackevin::Rest::Presence.new('room:42').get
+Blackevin::Rest::Queues.new.list
+Blackevin::Rest::Clients.new.disconnect(user.id)
+```
+
+Pass `client:` to share one, or to use another key:
+
+```ruby
+bk = Blackevin::Rest.new(key: other_key)
+
+Blackevin::Rest::Queues.new(client: bk).list
+```
+
+`bk.auth`, `bk.channels`, `bk.clients` and `bk.queues` are these same classes,
+already holding `bk`.
+
+Every option can be passed directly:
+
+```ruby
+bk = Blackevin::Rest.new(key: 'ck_live_….kAbC', read_timeout: 3)
+```
+
+### Defaults, set once
+
+`Blackevin.configure` holds the defaults a new `Blackevin::Rest` starts from. It
+builds nothing and calls nothing. An argument to `new` wins over it, and it wins
+over the environment.
+
+```ruby
+# config/initializers/blackevin.rb
 Blackevin.configure do |config|
-  config.key = ENV.fetch("BLACKEVIN_KEY")   # secret.keyId, from the console
-  config.open_timeout = 5                   # seconds
+  config.key = Rails.application.credentials.dig(:blackevin, :key)   # secret.keyId
+  config.open_timeout = 5                                          # seconds
   config.read_timeout = 10
 end
 ```
 
-`Blackevin.rest` is one shared, thread-safe client. For more than one key, build
-your own: `Blackevin::Rest.new(key: …)`.
-
 Against a local or self-hosted node, which serves REST and the socket from one
 origin, set `BLACKEVIN_ENDPOINT=ws://localhost:3000` (or `config.endpoint`) and the
 REST base is derived from it.
@@ -55,7 +95,7 @@ class BlackevinTokensController < ApplicationController
   before_action :authenticate_user!
 
   def show
-    render json: Blackevin.rest.auth.create_token_request(
+    render json: Blackevin::Rest::Auth.new.create_token_request(
       client_id: current_user.id,
       ttl: 1.hour.in_milliseconds,
       capability: {
@@ -67,7 +107,7 @@ class BlackevinTokensController < ApplicationController
 end
 
 # config/routes.rb
-resource :blackevin_token, only: :show, path: "blackevin/token"
+resource :blackevin_token, only: :show, path: 'blackevin/token'
 ```
 
 The key can live in credentials instead of the environment — the Railtie reads
@@ -75,20 +115,20 @@ The key can live in credentials instead of the environment — the Railtie reads
 
 ```ruby
 # config/environments/development.rb
-config.blackevin.endpoint = "ws://localhost:3000"
+config.blackevin.endpoint = 'ws://localhost:3000'
 ```
 
 ### Sinatra
 
 ```ruby
-require "sinatra"
-require "blackevin"
+require 'sinatra'
+require 'blackevin'
 
-get "/blackevin/token" do
+get '/blackevin/token' do
   halt 401 unless current_user
 
   content_type :json
-  Blackevin.rest.auth.create_token_request(client_id: current_user.id).to_json
+  Blackevin::Rest::Auth.new.create_token_request(client_id: current_user.id).to_json
 end
 ```
 
@@ -99,24 +139,24 @@ and answers who is asking; `nil` is a 401.
 
 ```ruby
 TOKENS = Blackevin::TokenEndpoint.new do |env|
-  user = env["warden"]&.user
+  user = env['warden']&.user
 
   next unless user
 
   {client_id: user.id, capability: {"team:#{user.team_id}" => %w[subscribe publish]}}
 end
 
-# Hanami:  mount TOKENS, at: "/blackevin/token"
-# Rails:   mount TOKENS, at: "/blackevin/token"
-# Rack:    map("/blackevin/token") { run TOKENS }
+# Hanami:  mount TOKENS, at: '/blackevin/token'
+# Rails:   mount TOKENS, at: '/blackevin/token'
+# Rack:    map('/blackevin/token') { run TOKENS }
 ```
 
 ## Publish
 
 ```ruby
-channel = Blackevin.rest.channels.get("orders:#{order.id}")
+channel = Blackevin::Rest::Channel.new("orders:#{order.id}")
 
-channel.publish("status", {state: "shipped"})
+channel.publish('status', {state: 'shipped'})
 ```
 
 It goes through the same fanout a socket publish does: subscribers, account
@@ -128,7 +168,7 @@ class BlackevinPublishJob < ApplicationJob
   retry_on Blackevin::ConnectionError, wait: :polynomially_longer
 
   def perform(channel, event, data)
-    Blackevin.rest.channels.get(channel).publish(event, data)
+    Blackevin::Rest::Channel.new(channel).publish(event, data)
   end
 end
 ```
@@ -141,15 +181,15 @@ channel.presence.get              # => [Blackevin::PresenceMember]
 channel.presence.history          # => [Blackevin::PresenceEvent]
 
 message = channel.history.first
-message.name        # "status"
-message.data        # {"state" => "shipped"}
+message.name        # 'status'
+message.data        # {'state' => 'shipped'}
 message.time        # a Time; message.timestamp is the wire value, in ms
 ```
 
 ## Sign a user out everywhere
 
 ```ruby
-Blackevin.rest.clients.disconnect(user.id)   # => how many connections were closed
+Blackevin::Rest::Clients.new.disconnect(user.id)   # => how many connections were closed
 ```
 
 ## Queues
@@ -157,10 +197,10 @@ Blackevin.rest.clients.disconnect(user.id)   # => how many connections were clos
 The key needs the `amqp-subscribe` capability. A queue is addressed by its `id`.
 
 ```ruby
-queues = Blackevin.rest.queues
+queues = Blackevin::Rest::Queues.new
 
-queue = queues.upsert(name: "inbox", max_length: 10_000)
-queues.add_rule(queue.id, source_pattern: "orders:*")
+queue = queues.upsert(name: 'inbox', max_length: 10_000)
+queues.add_rule(queue.id, source_pattern: 'orders:*')
 
 queues.update(queue.id, enabled: false)   # pause
 queues.list(all: true)                    # paused ones included
@@ -173,10 +213,10 @@ One rescue covers everything the SDK raises:
 
 ```ruby
 begin
-  channel.publish("status", payload)
+  channel.publish('status', payload)
 rescue Blackevin::Error => error
   error.status_code   # 403, 429, … or nil when no response arrived
-  error.reason        # "queue_limit", "connection_limit", or nil
+  error.reason        # 'queue_limit', 'connection_limit', or nil
   error.quota?        # a plan ceiling — show an upgrade prompt, retry later
   error.message       # the server's own sentence; do not branch on it
 end
@@ -188,7 +228,7 @@ rescue can branch by shape:
 ```ruby
 rescue Blackevin::Error => error
   case error
-  in {reason: "queue_limit"} then redirect_to upgrade_path
+  in {reason: 'queue_limit'} then redirect_to upgrade_path
   in {status_code: 401 | 403} then raise
   in {status_code: nil} then retry_job wait: 30.seconds
   end
@@ -202,21 +242,25 @@ rescue Blackevin::Error => error
 A token instead of a key restricts the client to that token's capability:
 
 ```ruby
-details = Blackevin.rest.auth.request_token(
-  Blackevin.rest.auth.create_token_request(client_id: "worker-1", capability: {"jobs:*" => %w[publish]})
+auth = Blackevin::Rest::Auth.new
+
+details = auth.request_token(
+  auth.create_token_request(client_id: 'worker-1', capability: {'jobs:*' => %w[publish]})
 )
 
-Blackevin::Rest.new(token: details.token).channels.get("jobs:1").publish("done")
+worker = Blackevin::Rest.new(token: details.token)
+
+Blackevin::Rest::Channel.new('jobs:1', client: worker).publish('done')
 ```
 
 ## Testing your app
 
-Swap the transport and nothing leaves the process:
+Swap the default transport and no `Blackevin::Rest` leaves the process:
 
 ```ruby
 Blackevin.configure do |config|
-  config.key = "secret.test"
-  config.transport = ->(request) { Blackevin::Response.new(status: 200, body: "{}") }
+  config.key = 'secret.test'
+  config.transport = ->(request) { Blackevin::Response.new(status: 200, body: '{}') }
 end
 ```
 
@@ -224,7 +268,8 @@ end
 
 ```sh
 bundle install
-bundle exec rake            # rspec + standard
+bundle exec rake            # rspec + rubocop (Standard rules, single quotes)
+bundle exec rake coverage        # SimpleCov: report in coverage/index.html, fails under the floor
 bundle exec rake contract:sync   # refresh spec/contract from ../blackevin/spec
 ```
 
@@ -236,7 +281,7 @@ Bump `lib/blackevin/version.rb`, add the entry to `CHANGELOG.md`, commit, then:
 bundle exec rake tag   # tags vX.Y.Z from version.rb and pushes it
 ```
 
-The tag runs `.github/workflows/release.yml`: lint, tests, publish to RubyGems by
+The tag runs `.github/workflows/release.yml`: tests, publish to RubyGems by
 Trusted Publishing (no API key), and a GitHub release with the `.gem` attached.
 
 `spec/contract` is a copy of the language-neutral contract — an OpenAPI file and

data/blackevin.gemspec

@@ -1,34 +1,35 @@
 # frozen_string_literal: true
 
-require_relative "lib/blackevin/version"
+require_relative 'lib/blackevin/version'
 
 Gem::Specification.new do |spec|
-  spec.name = "blackevin"
+  spec.name = 'blackevin'
   spec.version = Blackevin::VERSION
-  spec.authors = ["Blackevin"]
+  spec.authors = ['Blackevin']
 
-  spec.summary = "Blackevin Ruby SDK"
-  spec.description = "Sign token requests, publish, read history and presence, and manage queues on Blackevin. " \
-    "Standard library only: no runtime dependencies. Ruby 3.0 and up. Works in Rails, Sinatra, Hanami or plain Ruby."
-  spec.homepage = "https://blackevin.com"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0"
+  spec.summary = 'Blackevin Ruby SDK'
+  spec.description = 'Sign token requests, publish, read history and presence, and manage queues on Blackevin. ' \
+    'Standard library only: no runtime dependencies. Ruby 3.0 and up. Works in Rails, Sinatra, Hanami or plain Ruby.'
+  spec.homepage = 'https://blackevin.com'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0'
 
   spec.metadata = {
-    "rubygems_mfa_required" => "true",
-    "documentation_uri" => "https://docs.blackevin.com",
-    "source_code_uri" => "https://github.com/thadeu/blackevin-ruby",
-    "changelog_uri" => "https://github.com/thadeu/blackevin-ruby/blob/main/CHANGELOG.md"
+    'rubygems_mfa_required' => 'true',
+    'documentation_uri' => 'https://docs.blackevin.com',
+    'source_code_uri' => 'https://github.com/thadeu/blackevin-ruby',
+    'changelog_uri' => 'https://github.com/thadeu/blackevin-ruby/blob/main/CHANGELOG.md'
   }
 
   spec.files = Dir.chdir(__dir__) do
-    Dir["README.md", "CHANGELOG.md", "LICENSE", "blackevin.gemspec", "lib/**/*.rb"]
+    Dir['README.md', 'CHANGELOG.md', 'LICENSE', 'blackevin.gemspec', 'lib/**/*.rb']
   end
 
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "rake", ">= 13.0"
-  spec.add_development_dependency "rspec", ">= 3.13", "< 4.0"
-  spec.add_development_dependency "standard", ">= 1.0"
-  spec.add_development_dependency "railties", ">= 7.0"
+  spec.add_development_dependency 'rake', '>= 13.0'
+  spec.add_development_dependency 'rspec', '>= 3.13', '< 4.0'
+  spec.add_development_dependency 'simplecov', '>= 0.22'
+  spec.add_development_dependency 'standard', '>= 1.0'
+  spec.add_development_dependency 'railties', '>= 7.0'
 end

data/lib/blackevin/configuration.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
 module Blackevin
-  # Process-wide defaults for {Blackevin.rest}.
+  # The defaults a new {Blackevin::Rest} starts from. An argument given to
+  # +Rest.new+ wins over these, and these win over the environment.
   #
   #   Blackevin.configure do |config|
   #     config.key = ENV.fetch("BLACKEVIN_KEY")
   #   end
   #
   # Nothing here is required: with +BLACKEVIN_KEY+ in the environment,
-  # {Blackevin.rest} works unconfigured.
+  # +Blackevin::Rest.new+ works unconfigured.
   class Configuration
     ENV_KEY = 'BLACKEVIN_KEY'
 
@@ -33,17 +34,5 @@ module Blackevin
     end
 
     def key = @key || ENV[ENV_KEY]
-
-    # @return [Hash] the options {Blackevin::Rest.new} takes
-    def to_rest_options
-      {
-        key: key,
-        rest_endpoint: rest_endpoint,
-        endpoint: endpoint,
-        open_timeout: open_timeout,
-        read_timeout: read_timeout,
-        transport: transport
-      }
-    end
   end
 end

data/lib/blackevin/endpoints.rb

@@ -26,8 +26,8 @@ module Blackevin
       explicit_ws = present(endpoint) || present(env[ENV_WS])
 
       rest = present(rest_endpoint) ||
-             present(env[ENV_REST]) ||
-             (explicit_ws ? derive_rest(explicit_ws) : DEFAULT_REST)
+        present(env[ENV_REST]) ||
+        (explicit_ws ? derive_rest(explicit_ws) : DEFAULT_REST)
 
       Resolved.new(endpoint: explicit_ws || DEFAULT_WS, rest_endpoint: rest)
     end

data/lib/blackevin/errors.rb

@@ -33,7 +33,7 @@ module Blackevin
     #   in {status_code: 401 | 403} then rotate_key
     #   in {status_code: nil} then retry_later
     #   end
-    def deconstruct_keys(_keys) = { status_code: status_code, reason: reason, message: message }
+    def deconstruct_keys(_keys) = {status_code: status_code, reason: reason, message: message}
 
     # Builds the error for a non-2xx response, keeping the server's sentence.
     #
@@ -48,14 +48,14 @@ module Blackevin
       parsed = parse(body)
 
       detail = case parsed
-               in { error: String => sentence } unless sentence.empty? then sentence
-               else status
-               end
+      in {error: String => sentence} unless sentence.empty? then sentence
+      else status
+      end
 
       reason = case parsed
-               in { reason: String => slug } then slug
-               else nil
-               end
+      in {reason: String => slug} then slug
+      else nil
+      end
 
       new("#{what} failed: #{detail}", status, reason)
     end

data/lib/blackevin/railtie.rb

@@ -12,6 +12,8 @@ module Blackevin
   #   config.blackevin.rest_endpoint = "http://localhost:3000"
   #
   # An explicit +Blackevin.configure+ or +BLACKEVIN_KEY+ still wins over credentials.
+  # It only fills {Blackevin.configuration}; the application still builds its own
+  # +Blackevin::Rest.new+.
   class Railtie < Rails::Railtie
     SETTINGS = %i[key rest_endpoint endpoint open_timeout read_timeout transport].freeze
 

data/lib/blackevin/rest/auth.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
-require "json"
-require "securerandom"
+require 'json'
+require 'securerandom'
 
 module Blackevin
   class Rest
     # Token requests: signing one locally, and exchanging one for a token.
     class Auth
       DEFAULT_TTL_MS = 3_600_000
-      DEFAULT_CAPABILITY = {"*" => %w[subscribe publish presence history]}.freeze
+      DEFAULT_CAPABILITY = {'*' => %w[subscribe publish presence history]}.freeze
 
-      def initialize(rest, clock: nil, nonce: nil)
-        @rest = rest
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      # @param clock [#call, nil] returns milliseconds since the epoch; injected for tests
+      # @param nonce [#call, nil] returns a fresh nonce; injected for tests
+      def initialize(client: nil, clock: nil, nonce: nil)
+        @client = Rest.resolve(client)
         @clock = clock || -> { Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) }
         @nonce = nonce || -> { SecureRandom.hex(16) }
       end
@@ -31,7 +34,7 @@ module Blackevin
       # @return [Blackevin::TokenRequest] signed
       # @raise [Blackevin::ConfigurationError] without a usable API key
       def create_token_request(client_id: nil, ttl: nil, capability: nil, timestamp: nil, nonce: nil)
-        api_key = @rest.api_key
+        api_key = @client.api_key
 
         request = TokenRequest.new(
           key_name: api_key.key_name,
@@ -60,9 +63,9 @@ module Blackevin
           in Hash => hash then TokenRequest.from_h(hash).to_h
           else raise ConfigurationError, "request_token takes a TokenRequest or a Hash, got #{token_request.class}"
           end
-        path = "/keys/#{Rest.escape(wire.fetch("keyName"))}/requestToken"
+        path = "/keys/#{Rest.escape(wire.fetch('keyName'))}/requestToken"
 
-        TokenDetails.from_h(@rest.request("requestToken", "POST", path, body: wire, authorize: false))
+        TokenDetails.from_h(@client.request('requestToken', 'POST', path, body: wire, authorize: false))
       end
 
       private

data/lib/blackevin/rest/channel.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Blackevin
+  class Rest
+    # One channel: publish, history, presence.
+    class Channel
+      # @return [String]
+      attr_reader :name
+
+      # @return [Blackevin::Rest::Presence]
+      attr_reader :presence
+
+      # @param name [String]
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      def initialize(name, client: nil)
+        @name = name.to_s
+
+        raise ConfigurationError, 'a channel needs a name' if @name.empty?
+
+        @client = Rest.resolve(client)
+        @path = "/api/channels/#{Rest.escape(@name)}"
+        @presence = Presence.new(@name, client: @client)
+      end
+
+      # Publishes without a socket — from a job, a cron, or a webhook arriving
+      # at your backend. Subscribers, account queues and integrations see it
+      # exactly as they see a socket publish.
+      #
+      # @param event [String, Symbol] the event name
+      # @param data [Object, nil] anything JSON can carry
+      # @return [true]
+      # @raise [Blackevin::Error]
+      def publish(event, data = nil)
+        body = {'name' => event.to_s}
+        body['data'] = data unless data.nil?
+
+        @client.request('publish', 'POST', "#{@path}/publish", body: body)
+
+        true
+      end
+
+      # Stored messages, newest first.
+      #
+      # @param limit [Integer] clamped by the node to 1..1000
+      # @return [Array<Blackevin::Message>]
+      # @raise [Blackevin::Error]
+      def history(limit: DEFAULT_HISTORY_LIMIT)
+        body = @client.request('history', 'GET', "#{@path}/history", query: {'limit' => limit})
+
+        Array(body['messages']).map { Message.from_h(_1) }
+      end
+
+      def inspect = "#<Blackevin::Rest::Channel name=#{name.inspect}>"
+    end
+  end
+end

data/lib/blackevin/rest/channels.rb

@@ -4,8 +4,9 @@ module Blackevin
   class Rest
     # The channels of one client. +get+ returns the same object for the same name.
     class Channels
-      def initialize(rest)
-        @rest = rest
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      def initialize(client: nil)
+        @client = Rest.resolve(client)
         @channels = {}
         @mutex = Mutex.new
       end
@@ -15,89 +16,12 @@ module Blackevin
       def get(name)
         name = name.to_s
 
-        raise ConfigurationError, "a channel needs a name" if name.empty?
+        raise ConfigurationError, 'a channel needs a name' if name.empty?
 
-        @mutex.synchronize { @channels[name] ||= Channel.new(@rest, name) }
+        @mutex.synchronize { @channels[name] ||= Channel.new(name, client: @client) }
       end
 
       alias_method :[], :get
     end
-
-    # One channel: publish, history, presence.
-    class Channel
-      DEFAULT_HISTORY_LIMIT = 100
-
-      # @return [String]
-      attr_reader :name
-
-      # @return [Blackevin::Rest::Presence]
-      attr_reader :presence
-
-      def initialize(rest, name)
-        @rest = rest
-        @name = name
-        @path = "/api/channels/#{Rest.escape(name)}"
-        @presence = Presence.new(rest, @path)
-      end
-
-      # Publishes without a socket — from a job, a cron, or a webhook arriving
-      # at your backend. Subscribers, account queues and integrations see it
-      # exactly as they see a socket publish.
-      #
-      # @param event [String, Symbol] the event name
-      # @param data [Object, nil] anything JSON can carry
-      # @return [true]
-      # @raise [Blackevin::Error]
-      def publish(event, data = nil)
-        body = {"name" => event.to_s}
-        body["data"] = data unless data.nil?
-
-        @rest.request("publish", "POST", "#{@path}/publish", body: body)
-
-        true
-      end
-
-      # Stored messages, newest first.
-      #
-      # @param limit [Integer] clamped by the node to 1..1000
-      # @return [Array<Blackevin::Message>]
-      # @raise [Blackevin::Error]
-      def history(limit: DEFAULT_HISTORY_LIMIT)
-        body = @rest.request("history", "GET", "#{@path}/history", query: {"limit" => limit})
-
-        Array(body["messages"]).map { Message.from_h(_1) }
-      end
-
-      def inspect = "#<Blackevin::Rest::Channel name=#{name.inspect}>"
-    end
-
-    # Presence on one channel.
-    class Presence
-      def initialize(rest, channel_path)
-        @rest = rest
-        @path = "#{channel_path}/presence"
-      end
-
-      # Who is present now.
-      #
-      # @return [Array<Blackevin::PresenceMember>]
-      # @raise [Blackevin::Error]
-      def get
-        body = @rest.request("presence get", "GET", @path)
-
-        Array(body["members"]).map { PresenceMember.from_h(_1) }
-      end
-
-      # Past enter, leave and update events, newest first.
-      #
-      # @param limit [Integer] clamped by the node to 1..1000
-      # @return [Array<Blackevin::PresenceEvent>]
-      # @raise [Blackevin::Error]
-      def history(limit: Channel::DEFAULT_HISTORY_LIMIT)
-        body = @rest.request("presence history", "GET", "#{@path}/history", query: {"limit" => limit})
-
-        Array(body["events"]).map { PresenceEvent.from_h(_1) }
-      end
-    end
   end
 end

data/lib/blackevin/rest/clients.rb

@@ -4,8 +4,9 @@ module Blackevin
   class Rest
     # Acting on connected clients.
     class Clients
-      def initialize(rest)
-        @rest = rest
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      def initialize(client: nil)
+        @client = Rest.resolve(client)
       end
 
       # Closes every connection a client holds — for signing a user out
@@ -17,11 +18,11 @@ module Blackevin
       def disconnect(client_id)
         client_id = client_id.to_s
 
-        raise ConfigurationError, "disconnect needs a client_id" if client_id.empty?
+        raise ConfigurationError, 'disconnect needs a client_id' if client_id.empty?
 
         path = "/api/clients/#{Rest.escape(client_id)}/connections/close"
 
-        @rest.request("disconnect", "POST", path)["closed"].to_i
+        @client.request('disconnect', 'POST', path)['closed'].to_i
       end
     end
   end

data/lib/blackevin/rest/presence.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Blackevin
+  class Rest
+    # Presence on one channel.
+    class Presence
+      # @param channel [String] the channel's name
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      def initialize(channel, client: nil)
+        raise ConfigurationError, 'presence needs a channel name' if channel.to_s.empty?
+
+        @client = Rest.resolve(client)
+        @path = "/api/channels/#{Rest.escape(channel)}/presence"
+      end
+
+      # Who is present now.
+      #
+      # @return [Array<Blackevin::PresenceMember>]
+      # @raise [Blackevin::Error]
+      def get
+        body = @client.request('presence get', 'GET', @path)
+
+        Array(body['members']).map { PresenceMember.from_h(_1) }
+      end
+
+      # Past enter, leave and update events, newest first.
+      #
+      # @param limit [Integer] clamped by the node to 1..1000
+      # @return [Array<Blackevin::PresenceEvent>]
+      # @raise [Blackevin::Error]
+      def history(limit: DEFAULT_HISTORY_LIMIT)
+        body = @client.request('presence history', 'GET', "#{@path}/history", query: {'limit' => limit})
+
+        Array(body['events']).map { PresenceEvent.from_h(_1) }
+      end
+    end
+  end
+end

data/lib/blackevin/rest/queues.rb

@@ -7,17 +7,18 @@ module Blackevin
     # A queue is addressed by its id, never its name: the name is the physical
     # queue on the broker, so a 404 must mean "no such queue".
     class Queues
-      def initialize(rest)
-        @rest = rest
+      # @param client [Blackevin::Rest, nil] default: a new one, from the configuration
+      def initialize(client: nil)
+        @client = Rest.resolve(client)
       end
 
       # @param all [Boolean] include paused queues
       # @return [Array<Blackevin::Queue>]
       # @raise [Blackevin::Error]
       def list(all: false)
-        body = @rest.request("list queues", "GET", "/api/queues", query: all ? {"all" => "1"} : nil)
+        body = @client.request('list queues', 'GET', '/api/queues', query: all ? {'all' => '1'} : nil)
 
-        Array(body["queues"]).map { Queue.from_h(_1) }
+        Array(body['queues']).map { Queue.from_h(_1) }
       end
 
       # Creates a queue, or edits the one already holding this name. Only a new
@@ -29,10 +30,10 @@ module Blackevin
       # @return [Blackevin::Queue]
       # @raise [Blackevin::Error] with reason "queue_limit" at the plan's ceiling
       def upsert(name:, max_length: nil, enabled: true)
-        body = {"name" => name.to_s, "enabled" => enabled}
-        body["maxLength"] = max_length unless max_length.nil?
+        body = {'name' => name.to_s, 'enabled' => enabled}
+        body['maxLength'] = max_length unless max_length.nil?
 
-        Queue.from_h(@rest.request("upsert queue", "POST", "/api/queues", body: body).fetch("queue"))
+        Queue.from_h(@client.request('upsert queue', 'POST', '/api/queues', body: body).fetch('queue'))
       end
 
       alias_method :create, :upsert
@@ -48,13 +49,13 @@ module Blackevin
       def update(id, **changes)
         unknown = changes.except(:enabled, :max_length).keys
 
-        raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" unless unknown.empty?
+        raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
 
         body = {}
-        body["enabled"] = changes[:enabled] if changes.key?(:enabled)
-        body["maxLength"] = changes[:max_length] if changes.key?(:max_length)
+        body['enabled'] = changes[:enabled] if changes.key?(:enabled)
+        body['maxLength'] = changes[:max_length] if changes.key?(:max_length)
 
-        Queue.from_h(@rest.request("update queue", "PATCH", queue_path(id), body: body).fetch("queue"))
+        Queue.from_h(@client.request('update queue', 'PATCH', queue_path(id), body: body).fetch('queue'))
       end
 
       # Deletes the queue and whatever is waiting in it.
@@ -63,16 +64,16 @@ module Blackevin
       # @return [String] the name of the deleted queue
       # @raise [Blackevin::Error]
       def delete(id)
-        @rest.request("delete queue", "DELETE", queue_path(id))["deleted"]
+        @client.request('delete queue', 'DELETE', queue_path(id))['deleted']
       end
 
       # @param id [String] the queue's id
       # @return [Array<Blackevin::QueueRule>]
       # @raise [Blackevin::Error]
       def rules(id)
-        body = @rest.request("list queue rules", "GET", "#{queue_path(id)}/rules")
+        body = @client.request('list queue rules', 'GET', "#{queue_path(id)}/rules")
 
-        Array(body["rules"]).map { QueueRule.from_h(_1) }
+        Array(body['rules']).map { QueueRule.from_h(_1) }
       end
 
       # Copies messages from channels matching the pattern into the queue.
@@ -83,10 +84,10 @@ module Blackevin
       # @return [Blackevin::QueueRule]
       # @raise [Blackevin::Error]
       def add_rule(id, source_pattern:, filter: nil)
-        body = {"sourcePattern" => source_pattern.to_s}
-        body["filter"] = filter unless filter.nil?
+        body = {'sourcePattern' => source_pattern.to_s}
+        body['filter'] = filter unless filter.nil?
 
-        QueueRule.from_h(@rest.request("add queue rule", "POST", "#{queue_path(id)}/rules", body: body).fetch("rule"))
+        QueueRule.from_h(@client.request('add queue rule', 'POST', "#{queue_path(id)}/rules", body: body).fetch('rule'))
       end
 
       # Stops the copies at the source. Messages already enqueued stay.
@@ -96,7 +97,7 @@ module Blackevin
       # @return [true]
       # @raise [Blackevin::Error]
       def delete_rule(id, rule_id)
-        @rest.request("delete queue rule", "DELETE", "#{queue_path(id)}/rules/#{Rest.escape(rule_id)}")
+        @client.request('delete queue rule', 'DELETE', "#{queue_path(id)}/rules/#{Rest.escape(rule_id)}")
 
         true
       end
@@ -104,7 +105,7 @@ module Blackevin
       private
 
       def queue_path(id)
-        raise ConfigurationError, "a queue is addressed by its id" if id.to_s.empty?
+        raise ConfigurationError, 'a queue is addressed by its id' if id.to_s.empty?
 
         "/api/queues/#{Rest.escape(id)}"
       end

data/lib/blackevin/rest.rb

@@ -5,14 +5,28 @@ require 'json'
 module Blackevin
   # The REST client: no socket, no reconnection, no state beyond its options.
   #
-  #   rest = Blackevin::Rest.new(key: ENV.fetch("BLACKEVIN_KEY"))
+  #   bk = Blackevin::Rest.new
   #
-  #   rest.auth.create_token_request(client_id: "bob")
-  #   rest.channels.get("room:42").publish("greeting", {text: "hi"})
+  #   bk.auth.create_token_request(client_id: 'bob')
+  #   bk.channels.get('room:42').publish('greeting', {text: 'hi'})
+  #
+  # Each part also stands alone, so nothing forces a chain through this class:
+  #
+  #   Blackevin::Rest::Auth.new.create_token_request(client_id: 'bob')
+  #   Blackevin::Rest::Channel.new('room:42').publish('greeting', {text: 'hi'})
+  #   Blackevin::Rest::Queues.new.list
+  #
+  # Each takes an optional +client:+ and builds a +Blackevin::Rest.new+ without one.
+  #
+  # Every option falls back to {Blackevin.configuration}, and the key falls back
+  # from there to +BLACKEVIN_KEY+, so +new+ with no arguments is the usual call.
+  # Creating one is cheap — it opens nothing — so there is no need to share it.
   #
   # Safe to share across threads: every call opens its own connection and the
   # instance holds nothing mutable but a channel cache behind a mutex.
   class Rest
+    DEFAULT_HISTORY_LIMIT = 100
+
     USER_AGENT = "blackevin-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
 
     # @return [Blackevin::Rest::Auth]
@@ -30,33 +44,45 @@ module Blackevin
     # @return [String] the resolved REST base URL
     attr_reader :rest_endpoint
 
-    # @param key [String, nil] full API key +secret.keyId+; required to sign token requests
+    # @param key [String, nil] full API key +secret.keyId+; required to sign token requests.
+    #   Default: the configured key, then +BLACKEVIN_KEY+
     # @param token [String, nil] a token, when acting as one client rather than as the account
     # @param rest_endpoint [String, nil] overrides the resolved REST host
     # @param endpoint [String, nil] socket endpoint; read only to derive the REST base
-    # @param open_timeout [Numeric] seconds
-    # @param read_timeout [Numeric] seconds
+    # @param open_timeout [Numeric, nil] seconds; default from the configuration (5)
+    # @param read_timeout [Numeric, nil] seconds; default from the configuration (10)
     # @param transport [#call, nil] replaces Net::HTTP; receives a {Request}, returns a {Response}
     # @param clock [#call] returns milliseconds since the epoch; injected for tests
     # @param nonce [#call] returns a fresh nonce; injected for tests
     # @param env [#[]] where the endpoint variables are read from
-    def initialize(key: nil, token: nil, rest_endpoint: nil, endpoint: nil, open_timeout: 5, read_timeout: 10,
-                   transport: nil, clock: nil, nonce: nil, env: ENV)
-      @key = key
+    def initialize(key: nil, token: nil, rest_endpoint: nil, endpoint: nil, open_timeout: nil, read_timeout: nil,
+      transport: nil, clock: nil, nonce: nil, env: ENV)
+      defaults = Blackevin.configuration
+
+      @key = key || defaults.key
       @token = token
-      @rest_endpoint = Endpoints.resolve(endpoint: endpoint, rest_endpoint: rest_endpoint, env: env).rest_endpoint
-      @transport = transport || Transport.new(open_timeout: open_timeout, read_timeout: read_timeout)
 
-      @auth = Auth.new(self, clock: clock, nonce: nonce)
-      @channels = Channels.new(self)
-      @clients = Clients.new(self)
-      @queues = Queues.new(self)
+      @rest_endpoint = Endpoints.resolve(
+        endpoint: endpoint || defaults.endpoint,
+        rest_endpoint: rest_endpoint || defaults.rest_endpoint,
+        env: env
+      ).rest_endpoint
+
+      @transport = transport || defaults.transport || Transport.new(
+        open_timeout: open_timeout || defaults.open_timeout,
+        read_timeout: read_timeout || defaults.read_timeout
+      )
+
+      @auth = Auth.new(client: self, clock: clock, nonce: nonce)
+      @channels = Channels.new(client: self)
+      @clients = Clients.new(client: self)
+      @queues = Queues.new(client: self)
     end
 
     # @return [Blackevin::ApiKey]
     # @raise [Blackevin::ConfigurationError] when no key was given, or it is malformed
     def api_key
-      raise ConfigurationError, 'this call needs the API key: pass key: or set BLACKEVIN_KEY' if @key.to_s.strip.empty?
+      raise ConfigurationError, 'this call needs the API key: pass key:, set it in Blackevin.configure, or set BLACKEVIN_KEY' if @key.to_s.strip.empty?
 
       ApiKey.parse(@key)
     end
@@ -72,9 +98,20 @@ module Blackevin
       "Basic #{[@key].pack('m0')}"
     end
 
+    # What every resource class does with its +client:+ argument: use the one it
+    # was given, or build one from the configuration.
+    #
+    # @api private
+    def self.resolve(client)
+      return new if client.nil?
+      return client if client.respond_to?(:request) && client.respond_to?(:api_key)
+
+      raise ConfigurationError, "client: must be a Blackevin::Rest, got #{client.class}"
+    end
+
     # @api private
     def request(what, method, path, query: nil, body: nil, authorize: true)
-      headers = { 'accept' => 'application/json', 'user-agent' => USER_AGENT }
+      headers = {'accept' => 'application/json', 'user-agent' => USER_AGENT}
       authorization = authorize ? authorization_header : nil
 
       headers['authorization'] = authorization if authorization

data/lib/blackevin/token_details.rb

@@ -54,7 +54,7 @@ module Blackevin
     # Pattern matching, with the Ruby names. The token itself is left out on
     # purpose: a pattern's bindings end up in logs more easily than a reader.
     def deconstruct_keys(_keys)
-      { key_name: key_name, issued: issued, expires: expires, capability: capability, client_id: client_id }
+      {key_name: key_name, issued: issued, expires: expires, capability: capability, client_id: client_id}
     end
 
     # The token is a credential; keep it out of logs.

data/lib/blackevin/token_endpoint.rb

@@ -29,7 +29,8 @@ module Blackevin
       'cache-control' => 'no-store'
     }.freeze
 
-    # @param rest [Blackevin::Rest, nil] defaults to {Blackevin.rest}, resolved per request
+    # @param rest [Blackevin::Rest, nil] defaults to a new {Blackevin::Rest} per request, which
+    #   picks up whatever {Blackevin.configure} holds at that moment
     # @yieldparam env [Hash] the Rack env
     # @yieldreturn [Hash, nil] keyword arguments for +create_token_request+, or nil to answer 401
     def initialize(rest: nil, &identify)
@@ -43,14 +44,14 @@ module Blackevin
     # @return [Array(Integer, Hash, Array<String>)]
     def call(env)
       unless ALLOWED_METHODS.include?(env['REQUEST_METHOD'])
-        return respond(405, { 'error' => 'method not allowed' }, 'allow' => ALLOWED_METHODS.join(', '))
+        return respond(405, {'error' => 'method not allowed'}, 'allow' => ALLOWED_METHODS.join(', '))
       end
 
       case @identify.call(env)
       in nil | false
-        respond(401, { 'error' => 'unauthorized' })
+        respond(401, {'error' => 'unauthorized'})
       in Hash => params
-        respond(200, (@rest || Blackevin.rest).auth.create_token_request(**params.transform_keys(&:to_sym)).to_h)
+        respond(200, (@rest || Rest.new).auth.create_token_request(**params.transform_keys(&:to_sym)).to_h)
       in other
         raise ConfigurationError, "the TokenEndpoint block must return a Hash or nil, got #{other.class}"
       end

data/lib/blackevin/token_request.rb

@@ -9,7 +9,7 @@ module Blackevin
   #
   # Serialises to the wire shape, so a controller can render it as is:
   #
-  #   render json: Blackevin.rest.auth.create_token_request(client_id: current_user.id)
+  #   render json: Blackevin::Rest.new.auth.create_token_request(client_id: current_user.id)
   class TokenRequest
     # The field ORDER and the newline after each are the wire contract. The node
     # recomputes exactly this text to verify, and a reordering breaks every

data/lib/blackevin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Blackevin
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/blackevin.rb

@@ -11,6 +11,8 @@ require_relative 'blackevin/transport'
 require_relative 'blackevin/configuration'
 require_relative 'blackevin/rest'
 require_relative 'blackevin/rest/auth'
+require_relative 'blackevin/rest/presence'
+require_relative 'blackevin/rest/channel'
 require_relative 'blackevin/rest/channels'
 require_relative 'blackevin/rest/clients'
 require_relative 'blackevin/rest/queues'
@@ -19,9 +21,12 @@ require_relative 'blackevin/token_endpoint'
 # Server-side SDK for Blackevin: sign token requests, publish, read history and
 # presence, manage queues. Standard library only.
 #
-#   Blackevin.configure { |config| config.key = ENV.fetch("BLACKEVIN_KEY") }
+#   bk = Blackevin::Rest.new
 #
-#   Blackevin.rest.channels.get("room:42").publish("greeting", {text: "hi"})
+#   bk.channels.get('room:42').publish('greeting', {text: 'hi'})
+#
+# There is no process-wide client. {Blackevin.configure} only holds the defaults
+# a new {Blackevin::Rest} starts from.
 module Blackevin
   @mutex = Mutex.new
 
@@ -31,31 +36,20 @@ module Blackevin
       @mutex.synchronize { @configuration ||= Configuration.new }
     end
 
+    # Sets the defaults every later {Blackevin::Rest.new} starts from. It builds
+    # nothing and calls nothing: a client already created keeps what it was given.
+    #
     # @yieldparam config [Blackevin::Configuration]
     # @return [Blackevin::Configuration]
     def configure
       yield configuration
 
-      @mutex.synchronize { @rest = nil }
-
       configuration
     end
 
-    # The process-wide client, built from {configuration} on first use.
-    #
-    # @return [Blackevin::Rest]
-    def rest
-      options = configuration.to_rest_options
-
-      @mutex.synchronize { @rest ||= Rest.new(**options) }
-    end
-
-    # Forgets the configuration and the client. For test suites.
+    # Forgets the configuration. For test suites.
     def reset!
-      @mutex.synchronize do
-        @configuration = nil
-        @rest = nil
-      end
+      @mutex.synchronize { @configuration = nil }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blackevin
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Blackevin
@@ -43,6 +43,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -90,8 +104,10 @@ files:
 - lib/blackevin/railtie.rb
 - lib/blackevin/rest.rb
 - lib/blackevin/rest/auth.rb
+- lib/blackevin/rest/channel.rb
 - lib/blackevin/rest/channels.rb
 - lib/blackevin/rest/clients.rb
+- lib/blackevin/rest/presence.rb
 - lib/blackevin/rest/queues.rb
 - lib/blackevin/token_details.rb
 - lib/blackevin/token_endpoint.rb