Lowdown
Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification Service.
For efficiency, multiple notification requests are multiplexed and a single client can manage a pool of connections.
$ bundle exec ruby examples/simple.rb path/to/certificate.pem development <device-token>
Sent notification with ID: 13
Sent notification with ID: 1
Sent notification with ID: 10
Sent notification with ID: 7
Sent notification with ID: 25
...
Sent notification with ID: 10000
Sent notification with ID: 9984
Sent notification with ID: 9979
Sent notification with ID: 9992
Sent notification with ID: 9999
Finished in 14.98157 seconds
This example was run with a pool of 10 connections.
Installation
Add this line to your application's Gemfile:
gem 'lowdown'
Or install it yourself, for instance for the command-line usage, as:
$ gem install lowdown
Usage
You can use the lowdown
bin that comes with this gem or for code usage see
the documentation.
There are mainly two different modes in which you’ll typically use this client. Either you deliver a batch of
notifications every now and then, in which case you only want to open a connection to the remote service when needed, or
you need to be able to continuously deliver transactional notifications, in which case you’ll want to maintain
persistent connections. You can find examples of both these modes in the examples
directory.
But first things first, this is how you create a notification object:
notification = Lowdown::Notification.new(:token => "device-token", :payload => { :alert => "Hello World!" })
There’s plenty more options for a notification, please refer to the Notification documentation.
Short-lived connection
After obtaining a client, the simplest way to open a connection for a short period is by passing a block to connect
.
This will open the connection, yield the block, and close the connection by the end of the block:
client = Lowdown::Client.production(true, certificate: File.read("path/to/certificate.pem")
client.connect do |group|
# ...
end
Persistent connection
⚠︎ NOTE: See the ‘Gotchas’ section, specifically about process forking.
The trick to creating a persistent connection is to specify the keep_alive: true
option when creating the client:
client = Lowdown::Client.production(true, certificate: File.read("path/to/certificate.pem"), keep_alive: true)
# Send a batch of notifications
client.group do |group|
# ...
end
# Send another batch of notifications
client.group do |group|
# ...
end
One big difference you’ll notice with the short-lived connection example, is that you no longer use the Client#connect
method, nor do you close the connection (at least not until your process ends). Instead you use the group
method to
group a set of deliveries.
Grouping requests
Because Lowdown uses background threads to deliver notifications, the thread you’re delivering them from would
normally chug along, which is often not what you’d want. To solve this, the group
method provides you with a group
object which allows you to handle responses for the requests made in that group and halts the caller thread
until all responses have been handled.
All responses in a group will be handled in a single background thread, without halting the connection threads.
In typical Ruby fashion, a group provides a way to specify callbacks as blocks:
group.send_notification(notification) do |response|
# ...
end
But there’s another possiblity, which is to provide a delegate object which gets a message sent for each response:
class Delegate
def handle_apns_response(response, context:)
# ...
end
end
delegate = Delegate.new
client.group do |group|
group.send_notification(notification, delegate: delegate)
end
Keep in mind that, like with the block version, this message is sent on the group’s background thread.
Threading
While we’re on the topic of threading anyways, here’s an important thing to keep in mind; each set of group
callbacks
is performed on its own thread. It is thus your responsibility to take this into account. E.g. if you are planning to
update a DB model with the status of a notification delivery, be sure to respect the threading rules of your DB client,
which usually means to not re-use models that were loaded on a different thread.
A simple approach to this is by passing the data you need to be able to update the DB as a context
, which can be any
type of object or an array objects:
group.send_notification(notification, context: model.id) do |response, model_id|
reloaded_model = Model.find(model_id)
if response.success?
reloaded_model.touch(:sent_at)
else
reloaded_model.update_attribute(:last_response, response.status)
end
end
Connection pool
When you need to be able to deliver many notifications in a short amount of time, it can be beneficial to open multiple
connections to the remote service. By default Lowdown will initialize clients with a single connection, but you may
increase this with the pool_size
option:
Lowdown::Client.production(true, certificate: File.read("path/to/certificate.pem"), pool_size: 3)
Connect to APNS via proxy
Lowdown::Connection#initialize
accepts a lambda to build TCPSocket. Build a duck type of TCPSocket which go through proxy.
socket_maker = lambda do |uri|
Proxifier::Proxy('http://127.0.0.1:3128').open \
uri.host, uri.port, nil, nil, Celluloid::IO::TCPSocket
end
connection_pool = Lowdown::Connection.pool \
size: 2,
args: [uri, cert.ssl_context, true, socket_maker]
client = Lowdown::Client.client_with_connection connection_pool, certificate: cert
Gotchas
-
If you’re forking your process, be sure to not load lowdown before forking (because this does not work well with Celluloid, or with threading and Ruby in general).
Forking is done by, e.g. Spring and DelayedJob, when daemonizing workers. In practice, this means that e.g. you should not initialize a client from a Rails initializer, but rather do it lazily when it’s really required. E.g.:
class PushNotificationService
def initialize(certificate_path)
@certificate_path = certificate_path
@client_mutex = Mutex.new
end
def client
client = nil
@client_mutex.synchronize do
@client ||= Lowdown::Client.production(true, File.read(certificate_path), keep_alive: true)
client = @client
end
client
end
end
# In your initializer:
PUSH_NOTIFICATION_SERVICE = PushNotificationService.new("path/to/certificate.pem")
- It's reported not working with spring and Rails 4.2.5 (issue #9) even when creating Lowdown::Client instance after forking, outside Rails initializer, e.g. in Rails console.
Related tool ☞
Also checkout this library for scheduling across time zones.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/alloy/lowdown.
License
The gem is available as open source under the terms of the MIT License.