The project is in a healthy, maintained state
Ably Pub/Sub client for servers: backend services and other trusted runtimes. Construct clients with Ably::PubSub::Server.create_http_client or Ably::PubSub::Server.create_realtime_client.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

 Project Readme

Ably Pub/Sub Ruby Header

Gem: ably-pubsub-server License

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

Further reading

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.