Ably Pub/Sub Ruby SDK

The Ruby SDK for Ably Pub/Sub: publish and subscribe to channels, and use message history, presence and push notification administration, from servers.

Overview

This SDK provides the server package only, for trusted backends authenticating with an API key. There is no device package; for end-user devices, use a device SDK such as JavaScript, Swift/Objective-C, Java/Android, .NET or Flutter.

Package	Use it for	Entry point
ably-pubsub-server	Servers and other trusted backend environments	Ably::PubSub::Server.create_realtime_client, Ably::PubSub::Server.create_http_client

Requirements

Ruby 2.7 or later (tested on 2.7 to 3.3). The SDK also needs the libcurl system library (on Debian-based systems, install it with apt-get install libcurl4).

Installation

bundle add ably-pubsub-server

Quick start

Use an API key on a server. The samples read it from the ABLY_API_KEY environment variable; set it to an API key from your Ably dashboard. The following code connects, subscribes to a channel, publishes a message to it and waits for the message to arrive.

require 'ably/pubsub/server'

EventMachine.run do
  ably_api_key = ENV.fetch('ABLY_API_KEY')
  realtime = Ably::PubSub::Server.create_realtime_client(key: ably_api_key)
  channel = realtime.channels.get('test-channel')

  # Subscribing attaches the channel.
  channel.subscribe('test-event') do |message|
    puts "Received: #{message.data}"
    realtime.close { EventMachine.stop }
  end

  channel.attach do
    channel.publish('test-event', 'hello world')
  end
end

To publish over HTTP without a realtime connection, create an HTTP client instead:

require 'ably/pubsub/server'

ably_api_key = ENV.fetch('ABLY_API_KEY')
client = Ably::PubSub::Server.create_http_client(key: ably_api_key)
client.channels.get('test-channel').publish('test-event', 'hello world')

Important

Server clients must authenticate with an API key. To use a token instead, see Server clients and token authentication.

The following endpoint issues token requests. Devices using a device SDK set authUrl to its URL, for example https://your-server.example.com/ably-auth:

require 'sinatra'
require 'ably/pubsub/server'

ably_api_key = ENV.fetch('ABLY_API_KEY')
client = Ably::PubSub::Server.create_http_client(key: ably_api_key)

get '/ably-auth' do
  # Authenticate the caller first. Grant only the operations this user needs.
  # Without a capability, the token gets all of the API key's capabilities.
  user_id = 'me' # the signed-in user's ID, from your session
  token_request = client.auth.create_token_request(
    client_id: user_id,
    capability: { 'test-channel' => ['publish', 'subscribe', 'history'] }
  )

  content_type :json
  token_request.to_json
end

See token authentication for how devices use it.

Migrating from 1.x

Version 2.0 renames the gem and creates clients with factory methods.

	1.x	2.0
Package	ably or ably-rest	ably-pubsub-server
Require	require 'ably' or require 'ably-rest'	require 'ably/pubsub/server'
Realtime client	Ably::Realtime::Client.new(key: key)	Ably::PubSub::Server.create_realtime_client(key: key)
HTTP client	Ably::Rest::Client.new(key: key)	Ably::PubSub::Server.create_http_client(key: key)

See UPDATING.md for all other changes.

Common configuration

Both factories accept an API key or token string, or an options Hash.

Endpoint

endpoint selects the Ably host for HTTP requests and the realtime connection. It replaces the 1.x environment, rest_host and realtime_host options. 2.0 ignores those options, so a client that still sets them connects to production.

ably_api_key = ENV.fetch('ABLY_API_KEY')
realtime = Ably::PubSub::Server.create_realtime_client(key: ably_api_key, endpoint: 'nonprod:sandbox')

• Never put a port in endpoint: localhost:8080 is not a hostname and does not resolve.
• Set the port with tls_port, or with port when TLS is off.
• With TLS off (tls: false), use token authentication.

See UPDATING.md for how the old options map to endpoint.

Logging

Set log_level to :fatal, :error, :warn (the default), :info, :debug or :none. Logs go to standard output through Ruby's Logger. To send them elsewhere, pass a Logger-compatible object as logger:

require 'logger'
require 'ably/pubsub/server'

ably_api_key = ENV.fetch('ABLY_API_KEY')
client = Ably::PubSub::Server.create_http_client(
  key: ably_api_key,
  log_level: :debug,
  logger: Logger.new($stderr)
)

Platform notes

EventMachine

• The realtime client runs on EventMachine. Create and use it inside EventMachine.run.
• The HTTP client is synchronous. It does not need the EventMachine reactor.
• The gem depends on EventMachine even if you use only the HTTP client.

Known limitations

• LiveObjects is not supported.
• Token revocation is not supported.
• Delta compression is not supported.
• A Ruby client cannot be a push notification target. The push admin API is supported.

Further reading

• Getting started with Pub/Sub using Ruby
• Ably Pub/Sub documentation and examples
• Token authentication
• UPDATING.md: migrating from 1.x
• CHANGELOG.md: release notes; all Ably releases are listed on changelog.ably.com

Contributing

Read CONTRIBUTING.md before contributing; it also describes the release process.

Support, feedback and troubleshooting

For help, visit Ably's support page. Report bugs and compatibility problems on GitHub Issues.

License

Licensed under the Apache License, Version 2.0. See LICENSE.