Ruby
The blackevin gem — the server-side SDK for Rails, Sinatra and Hanami. Standard library only, Ruby 3.0 and up.
The gem is the server side of Blackevin: sign a token for your browsers, publish from a job or a webhook, read history and presence, manage queues. It does not open a socket — your browsers do that, with the JavaScript SDK.
No runtime dependencies. net/http, openssl and json from the standard
library, so nothing in it can break under you in an upgrade.
Install
gem 'blackevin'Ruby 3.0 and up. Source and changelog at thadeu/blackevin-ruby.
The client
You work with an instance. There is no global client, and no class-level call that touches the network.
bk = Blackevin::Rest.new
bk.channels.get('room:42').publish('greeting', {text: 'hi'})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. An instance is thread-safe.
It has four parts:
| what it does | page | |
|---|---|---|
bk.auth | sign a token request, exchange one for a token | Tokens |
bk.channels | publish, history, presence | Channels |
bk.clients | close every connection a client holds | Channels |
bk.queues | account queues and the rules that feed them | Queues |
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.
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:
bk = Blackevin::Rest.new(key: other_key)
Blackevin::Rest::Queues.new(client: bk).listbk.auth, bk.channels, bk.clients and bk.queues are these same classes,
already holding bk.
Configure
Every option can go straight to new:
bk = Blackevin::Rest.new(key: 'bk_live_….kAbC', read_timeout: 3)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.
Blackevin.configure do |config|
config.key = Rails.application.credentials.dig(:blackevin, :key)
config.open_timeout = 5
config.read_timeout = 10
end| option | default | |
|---|---|---|
key | BLACKEVIN_KEY | the full key, secret.keyId. Needed to sign token requests |
token | — | act as one client instead of as the account. Wins over key |
rest_endpoint | BLACKEVIN_REST_ENDPOINT, then https://api.blackevin.com | the REST base URL |
endpoint | BLACKEVIN_ENDPOINT | a socket endpoint, read only to derive the REST base |
open_timeout | 5 | seconds |
read_timeout | 10 | seconds |
transport | Net::HTTP | anything with call(request) — see Testing |
A local or self-hosted node serves REST and the socket from one origin, so
BLACKEVIN_ENDPOINT=ws://localhost:3000 is enough: the REST base becomes
http://localhost:3000.
Rails
Loaded only when Rails is, a Railtie fills the same configuration from two places, so an initializer is optional:
blackevin:
key: bk_live_….kAbCconfig.blackevin.endpoint = 'ws://localhost:3000'An explicit Blackevin.configure or BLACKEVIN_KEY still wins over credentials.