lowdown 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74b301dd024aaf5cf6933d95639ff6b0f016e26f
-  data.tar.gz: 13981473dbf0c6a8c117fadd09152e23a93c9073
+  metadata.gz: ab366da937c62aeebaaa7070b47f3f3a108e1460
+  data.tar.gz: 568554722d19bf9899cfdfda1fa96de1698365ce
 SHA512:
-  metadata.gz: dc3bef31593849519775831cc608a34321c5883a12f72b7ad8baabbd9796d70bf5d184dd092b0beaa7b14e85a171f683a58c0a3f6a66623ca5d71fa196298c10
-  data.tar.gz: 191a7e45a3e6af3e9ac3c8af8ad04733195754d7822c5463ef26939d0171e0bbe02479dd34100255b20443ddfea8b618f429e810b7549cfc69424fdbe776ae3f
+  metadata.gz: 90a597f2d9faae4afe0a4640b3618303b8740de0132fbfd5d9b291526ef3a240b0bbbe35208279197811a021305cb0edff7408c4d96e356a14a7a3a686b4db01
+  data.tar.gz: 81fe7bf93ff1c4fa94090720c32293155a08b59fe2b6e6e0b5ca9dce7feac5d322d0f6c260a9ba68a8476443656710882dd33610b824a21601131cc9db96abba

data/.rubocop.yml

@@ -0,0 +1,121 @@
+AllCops:
+  TargetRubyVersion: 2.1
+
+Documentation:
+  Enabled: false
+
+# They are idiomatic
+Lint/AssignmentInCondition:
+  Enabled: false
+
+Lint/RescueException:
+  Enabled: false
+
+Lint/StringConversionInInterpolation:
+  Enabled: false
+
+Lint/UselessAssignment:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+Lint/HandleExceptions:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 120
+  AllowURI: true
+  URISchemes:
+    - http
+    - https
+
+# Arbitrary max lengths for classes simply do not work and enabling this will
+# lead to a never ending stream of annoyance and changes.
+Metrics/ClassLength:
+  Enabled: false
+
+# Arbitrary max lengths for modules simply do not work and enabling this will
+# lead to a never ending stream of annoyance and changes.
+Metrics/ModuleLength:
+  Enabled: false
+
+# Arbitrary max lengths for methods simply do not work and enabling this will
+# lead to a never ending stream of annoyance and changes.
+Metrics/MethodLength:
+  Enabled: false
+
+# No enforced convention here.
+Metrics/BlockNesting:
+  Enabled: false
+
+# It will be obvious which code is complex, Rubocop should only lint simple
+# rules for us.
+Metrics/AbcSize:
+  Enabled: false
+
+# It will be obvious which code is complex, Rubocop should only lint simple
+# rules for us.
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+# It will be obvious which code is complex, Rubocop should only lint simple
+# rules for us.
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/SignalException:
+  EnforcedStyle: only_raise
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/EmptyLines:
+  Exclude:
+    - 'test/test_helper.rb'
+
+Style/FileName:
+  Exclude:
+    - 'examples/*.rb'
+
+Style/GlobalVars:
+  Enabled: false
+
+# Should have `EnforcedStyle: hash_rockets`, because that’s the only consistent style,
+# but that incorrectly flags keyword arguments as well.
+Style/HashSyntax:
+  Enabled: false
+
+Style/IfInsideElse:
+  Enabled: false
+
+Style/IndentHash:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StructInheritance:
+  Enabled: false
+
+Style/TrailingBlankLines:
+  EnforcedStyle: final_blank_line
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: comma
+

data/Gemfile

@@ -1,9 +1,17 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-#gem 'http-2', :git => 'https://github.com/alloy/http-2.git', :branch => "apns"
+# gem "http-2", :git => "https://github.com/alloy/http-2.git", :branch => "apns"
+
+# Test on minimum required dependency for now.
+# gem "celluloid-io", "0.17.0"
 
 gemspec
 
+group :development do
+  gem "rubocop"
+end
+
 group :doc do
-  gem 'yard'
+  gem "yard"
 end
+

data/README.md

@@ -4,18 +4,29 @@
 
 [![Build Status](https://travis-ci.org/alloy/lowdown.svg?branch=master)](https://travis-ci.org/alloy/lowdown)
 
-Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification Service.
+NOTE: _This is not battle-tested yet. This will follow over the next few weeks._
 
-Multiple notifications are multiplexed for efficiency.
+Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification Service.
 
-If you need to cotinuously send notifications, it’s a good idea to keep an open connection. Managing that, in for
-instance a daemon, is beyond the scope of this library. We might release an extra daemon/server tool in the future that
-provides this functionality, but for now you should simply use the Client provided in this library without the block
-form (which automatically closes the connection) and build your own daemon/server setup, as required.
+For efficiency, multiple notification requests are multiplexed and a single client can manage a pool of connections.
 
-Also checkout [this library](https://github.com/alloy/time_zone_scheduler) for scheduling across time zones.
+```
+$ 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
+```
 
-NOTE: _It is not yet battle-tested. This will all follow over the next few weeks._
+_This example was run with a pool of 10 connections._
 
 ## Installation
 
@@ -25,19 +36,135 @@ Add this line to your application's Gemfile:
 gem 'lowdown'
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
+Or install it yourself, for instance for the command-line usage, as:
 
-    $ gem install lowdown
+```
+$ gem install lowdown
+```
 
 ## Usage
 
 You can use the `lowdown` bin that comes with this gem or for code usage see
 [the documentation](http://www.rubydoc.info/gems/lowdown).
 
+There are mainly two different modes in which you’ll typically use [this client][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]:
+
+```ruby
+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][notification].
+
+### 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:
+
+```ruby
+client = Lowdown::Client.production(true, File.read("path/to/certificate.pem")
+client.connect do |group|
+  # ...
+end
+```
+
+### Persistent connection
+
+The trick to creating a persistent connection is to specify the `keep_alive: true` option when creating the client:
+
+```ruby
+client = Lowdown::Client.production(true, 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][group] 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:
+
+```ruby
+group.send_notification(notification) do |response|
+  # ...
+end
+```
+
+But there’s another possiblity, which is to provide [a delegate object][delegate] which gets a message sent for each
+response:
+
+```ruby
+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 treading 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:
+
+```ruby
+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:
+
+```ruby
+Lowdown::Client.production(true, File.read("path/to/certificate.pem"), pool_size: 3)
+```
+
+## Related tool ☞
+
+Also checkout [this library](https://github.com/alloy/time_zone_scheduler) for scheduling across time zones.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/alloy/lowdown.
@@ -46,3 +173,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/alloy/
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+[client]: http://www.rubydoc.info/gems/lowdown/Lowdown/Client
+[notification]: http://www.rubydoc.info/gems/lowdown/Lowdown/Notification
+[group]: http://www.rubydoc.info/gems/lowdown/Lowdown/RequestGroup
+[delegate]: http://www.rubydoc.info/gems/lowdown/Lowdown/Connection/DelegateProtocol

data/Rakefile

@@ -1,8 +1,8 @@
 desc "Install all dependencies"
 task :bootstrap do
-  if system('which bundle')
+  if system("which bundle")
     sh "bundle install"
-    #sh "git submodule update --init"
+    # sh "git submodule update --init"
   else
     $stderr.puts "\033[0;31m[!] Please install the bundler gem manually: $ [sudo] gem install bundler\e[0m"
     exit 1
@@ -10,23 +10,30 @@ task :bootstrap do
 end
 
 begin
-  require 'bundler/gem_tasks'
+  require "bundler/gem_tasks"
 
   desc "Generate documentation"
   task :doc do
     sh "yard doc"
   end
 
+  desc "Run rubocop"
+  task :rubocop do
+    sh "rubocop"
+  end
+
   require "rake/testtask"
   Rake::TestTask.new(:test) do |t|
     t.options = "--verbose"
     t.libs << "test"
     t.libs << "lib"
-    t.test_files = FileList['test/**/*_test.rb']
+    t.test_files = FileList["test/**/*_test.rb"]
   end
 
-  task :default => :test
+  task :default => [:test, :rubocop]
 
 rescue LoadError
-  $stderr.puts "\033[0;33m[!] Disabling rake tasks because the environment couldn’t be loaded. Be sure to run `rake bootstrap` first.\e[0m"
+  $stderr.puts "\033[0;33m[!] Disabling rake tasks because the environment couldn’t be loaded. Be sure to run `rake " \
+               "bootstrap` first.\e[0m"
 end
+

data/bin/lowdown

@@ -6,17 +6,20 @@ include Lowdown
 require "json"
 require "optparse"
 
-options = { :payload => {}, :custom_data => {} }
+Celluloid.logger.level = Logger::WARN
+
+options = { :payload => {}, :custom_data => {}, :pool_size => 1 }
 
 OPTION_PARSER = OptionParser.new do |opts|
   opts.banner = "Usage: lowdown [options] <tokens …>"
 
-  opts.on("-v", "--version", "Print version") do |v|
+  opts.on("-v", "--version", "Print version") do
     puts VERSION
     exit
   end
 
-  opts.on("-m", "--alert ALERT", "Body of the alert to send in the push notification") do |alert|
+  opts.on("-m", "--alert ALERT", "Body of the alert to send in the push notification (the %d format code will be " \
+                                 "replaced by the notification ID)") do |alert|
     options[:alert] = alert
   end
 
@@ -37,7 +40,8 @@ OPTION_PARSER = OptionParser.new do |opts|
     options[:custom_data][key] = value
   end
 
-  opts.on("-P", "--payload PAYLOAD", "JSON payload for notifications, merged with --alert, --badge, --sound, and --data") do |payload|
+  opts.on("-P", "--payload PAYLOAD", "JSON payload for notifications, merged with --alert, --badge, --sound, and " \
+                                     "--data") do |payload|
     options[:payload] = JSON.parse(payload)
   end
 
@@ -45,7 +49,8 @@ OPTION_PARSER = OptionParser.new do |opts|
     options[:topic] = topic
   end
 
-  opts.on("-e", "--environment ENV", "Environment to send push notification (production or development), defaults to production if the certificate supports that or otherwise development") do |env|
+  opts.on("-e", "--environment ENV", "Environment to send push notification (production or development), defaults to " \
+                                     "production if the certificate supports that or otherwise development") do |env|
     options[:env] = env
   end
 
@@ -56,6 +61,19 @@ OPTION_PARSER = OptionParser.new do |opts|
   opts.on("-p", "--passphrase PASSPHRASE", "Certificate passphrase") do |passphrase|
     options[:certificate_passphrase] = passphrase
   end
+
+  opts.on("-n", "--connections NUMBER", "Number of simultaneous connections to make") do |pool_size|
+    options[:pool_size] = pool_size.to_i
+  end
+
+  opts.on("--debug", "Debug logging") do
+    Celluloid.logger.level = Logger::INFO
+  end
+
+  opts.on("--verbose", "Verbose logging") do
+    $CELLULOID_DEBUG = true
+    Celluloid.logger.level = Logger::DEBUG
+  end
 end
 
 OPTION_PARSER.parse!
@@ -70,13 +88,15 @@ end
 
 certificate = nil
 file, passphrase = options.values_at(:certificate_file, :certificate_passphrase)
+# rubocop:disable Style/RescueModifier
 unless file && File.exist?(file) && certificate = (Certificate.from_pem_data(File.read(file), passphrase) rescue nil)
+  # rubocop:enable Style/RescueModifier
   help! "A valid certificate path is required."
 end
 
 production = false
 if options[:env]
-  unless %w{ production development }.include?(options[:env])
+  unless %w( production development ).include?(options[:env])
     help! "Invalid environment specified."
   end
   production = options[:env] == "production"
@@ -89,7 +109,7 @@ else
 end
 
 begin
-  client = Client.production(production, certificate)
+  client = Client.production(production, certificate: certificate, pool_size: options[:pool_size])
 rescue ArgumentError => e
   help! e.message
 end
@@ -99,23 +119,22 @@ payload.merge!(options[:custom_data])
 payload["alert"] = options[:alert] if options[:alert]
 payload["badge"] = options[:badge] if options[:badge]
 payload["sound"] = options[:sound] if options[:sound]
-payload["content-available"] = options[:content_available] ? 1 : 0 if options.has_key?(:content_available)
-if payload.empty?
-  help! "No payload data specified."
-end
+payload["content-available"] = options[:content_available] ? 1 : 0 if options.key?(:content_available)
 
-if tokens.empty?
-  help! "No device tokens specified."
-end
+help! "No payload data specified." if payload.empty?
+help! "No device tokens specified." if tokens.empty?
 
-notifications = tokens.map.with_index do |token, index|
-  Notification.new(:token => token, :id => index+1, :payload => payload, :topic => options[:topic])
+notifications = tokens.map do |token|
+  Notification.new(:token => token, :payload => payload.dup, :topic => options[:topic]).tap do |notification|
+    notification.payload["alert"] = notification.payload["alert"] % notification.id
+  end
 end
 
-client.connect do
+client.connect do |group|
   notifications.each do |notification|
-    client.send_notification(notification) do |response|
-      puts "[#{notification.token} ##{notification.id}] #{response}"
+    group.send_notification(notification) do |response|
+      Celluloid.logger.unknown "[#{notification.token} ##{notification.id}] #{response}"
     end
   end
 end
+