lowdown 0.2.0 → 0.3.0

data/examples/long-running.rb

@@ -0,0 +1,63 @@
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require "lowdown"
+require "logger"
+
+cert_file, environment, device_token = ARGV.first(3)
+unless cert_file && environment && device_token
+  puts "Usage: #{$PROGRAM_NAME} path/to/cert.pem [production|development] device-token"
+  exit 1
+end
+
+# $CELLULOID_DEBUG = true
+# Celluloid.logger.level = Logger::DEBUG
+# Celluloid.logger.level = Logger::INFO
+Celluloid.logger.level = Logger::ERROR
+
+logger = Logger.new(STDOUT)
+
+client = Lowdown::Client.production(environment == "production",
+                                    certificate: File.read(cert_file),
+                                    pool_size: 3,
+                                    keep_alive: true) # This option is the key to long running connections
+client.connect
+
+loop do
+  begin
+    logger.info "Perform burst"
+    # Perform a burst of notifications from multiple concurrent threads to demonstrate thread safety.
+    #
+    Array.new(3) do
+      Thread.new do
+        client.group do |group|
+          10.times do
+            notification = Lowdown::Notification.new(:token => device_token)
+            notification.payload = { :alert => "Hello HTTP/2! ID=#{notification.id}" }
+            group.send_notification(notification) do |response|
+              if response.success?
+                logger.debug "Sent notification with ID: #{notification.id}"
+              else
+                logger.error "[!] (##{response.id}): #{response}"
+              end
+            end
+          end
+        end
+      end
+    end.each(&:join)
+
+    logger.info "Sleep for 5 seconds"
+    sleep(5)
+
+  rescue Interrupt
+    logger.info "[!] Interrupt, exiting"
+    break
+
+  rescue Exception => e
+    logger.error "[!] Exception occurred, re-trying in 1 second: #{e.inspect}\n\t#{e.backtrace.join("\n\t")}"
+    sleep 1
+    redo
+  end
+end
+
+client.disconnect
+puts "Finished!"
+

data/examples/simple.rb

@@ -0,0 +1,37 @@
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require "lowdown"
+
+cert_file, environment, device_token = ARGV.first(3)
+unless cert_file && environment && device_token
+  puts "Usage: #{$PROGRAM_NAME} path/to/cert.pem [production|development] device-token"
+  exit 1
+end
+
+production = environment == "production"
+
+# $CELLULOID_DEBUG = true
+# Celluloid.logger.level = Logger::DEBUG
+# Celluloid.logger.level = Logger::INFO
+Celluloid.logger.level = Logger::ERROR
+
+# Connection time can take a while, just count the time it takes to connect.
+start = nil
+
+# The block form of Client#connect flushes and closes the connection at the end of the block.
+Lowdown::Client.production(production, certificate: File.read(cert_file), pool_size: 2).connect do |group|
+  start = Time.now
+  600.times do
+    notification = Lowdown::Notification.new(:token => device_token)
+    notification.payload = { :alert => "Hello HTTP/2! ID=#{notification.id}" }
+    group.send_notification(notification) do |response|
+      if response.success?
+        puts "Sent notification with ID: #{notification.id}"
+      else
+        puts "[!] (##{response.id}): #{response}"
+      end
+    end
+  end
+end
+
+puts "Finished in #{Time.now - start} seconds"
+

data/lib/lowdown.rb

@@ -3,27 +3,8 @@ require "lowdown/version"
 
 # Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification Service.
 #
-# Multiple notifications are multiplexed and responses are yielded onto a different thread for efficiency.
-#
-# Note that it is thus _your_ responsibility to take the threading issue 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.
-#
-# The main classes you will interact with are {Lowdown::Client} and {Lowdown::Notification}. For testing purposes there
-# are some helpers available in {Lowdown::Mock}.
-#
-# @example At its simplest, you can send a notification like so:
-#
-#     notification = Lowdown::Notification.new(:token => "device-token", :payload => { :alert => "Hello World!" })
-#
-#     Lowdown::Client.production(true, File.read("path/to/certificate.pem")).connect do |client|
-#       client.send_notification(notification) do |response|
-#         if response.success?
-#           puts "Notification sent"
-#         else
-#           puts "Notification failed: #{response}"
-#         end
-#       end
-#     end
+# Refer to the README for usage instructions.
 #
 module Lowdown
 end
+

data/lib/lowdown/certificate.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "openssl"
 
 module Lowdown
@@ -36,6 +37,17 @@ module Lowdown
       new(certificate, key)
     end
 
+    # A convenience method that initializes a Certificate with the certificate and key from a SSL context object.
+    #
+    # @param  [OpenSSL::SSL::SSLContext] context
+    #         the context from which to initialize a Certificate.
+    #
+    # @return (see Certificate#initialize)
+    #
+    def self.from_ssl_context(context)
+      new(context.cert, context.key)
+    end
+
     # @param  [OpenSSL::X509::Certificate] certificate
     #         the Apple Push Notification certificate.
     #
@@ -67,6 +79,13 @@ module Lowdown
       [@key, @certificate].compact.map(&:to_pem).join("\n")
     end
 
+    # @return [Boolean]
+    #         whether or not this Certificate is equal in contents to another Certificate.
+    #
+    def ==(other)
+      other.is_a?(Certificate) && other.to_pem == to_pem
+    end
+
     # @return [OpenSSL::SSL::SSLContext]
     #         a SSL context, configured with the certificate/key pair, which is used to connect to the APN service.
     #
@@ -118,7 +137,7 @@ module Lowdown
     #         the App ID / app’s Bundle ID that this certificate is for.
     #
     def app_bundle_id
-      @certificate.subject.to_a.find { |key, *_| key == 'UID' }[1]
+      @certificate.subject.to_a.find { |key, *_| key == "UID" }[1]
     end
 
     private
@@ -133,3 +152,4 @@ module Lowdown
     end
   end
 end
+

data/lib/lowdown/client.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
+require "lowdown/client/request_group"
 require "lowdown/certificate"
 require "lowdown/connection"
+require "lowdown/connection/monitor"
 require "lowdown/notification"
 
 require "uri"
@@ -8,6 +12,9 @@ require "json"
 module Lowdown
   # The main class to use for interactions with the Apple Push Notification HTTP/2 service.
   #
+  # Important connection configuration options are `pool_size` and `keep_alive`. The former specifies the number of
+  # simultaneous connections the client should make and the latter is key for long running processes.
+  #
   class Client
     # The details to connect to the development (sandbox) environment version of the APN service.
     #
@@ -17,25 +24,37 @@ module Lowdown
     #
     PRODUCTION_URI = URI.parse("https://api.push.apple.com:443")
 
+    # The default timeout for {#group}.
+    #
+    DEFAULT_GROUP_TIMEOUT = 3600
+
     # @!group Constructor Summary
 
     # This is the most convenient constructor for regular use.
     #
-    # It then calls {Client.client}.
-    #
     # @param  [Boolean] production
     #         whether to use the production or the development environment.
     #
-    # @param  [Certificate, String] certificate_or_data
+    # @param  [Certificate, String] certificate
     #         a configured Certificate or PEM data to construct a Certificate from.
     #
+    # @param  [Fixnum] pool_size
+    #         the number of connections to make.
+    #
+    # @param  [Boolean] keep_alive
+    #         when `true` this will make connections, new and restarted, immediately connect to the remote service. Use
+    #         this if you want to keep connections open indefinitely.
+    #
+    # @param  [Class] connection_class
+    #         the connection class to instantiate, this can for instan be {Mock::Connection} during testing.
+    #
     # @raise  [ArgumentError]
     #         raised if the provided Certificate does not support the requested environment.
     #
     # @return (see Client#initialize)
     #
-    def self.production(production, certificate_or_data)
-      certificate = Certificate.certificate(certificate_or_data)
+    def self.production(production, certificate:, pool_size: 1, keep_alive: false, connection_class: Connection)
+      certificate = Certificate.certificate(certificate)
       if production
         unless certificate.production?
           raise ArgumentError, "The specified certificate is not usable with the production environment."
@@ -45,45 +64,59 @@ module Lowdown
           raise ArgumentError, "The specified certificate is not usable with the development environment."
         end
       end
-      client(production ? PRODUCTION_URI : DEVELOPMENT_URI, certificate)
+      client(uri: production ? PRODUCTION_URI : DEVELOPMENT_URI,
+             certificate: certificate,
+             pool_size: pool_size,
+             keep_alive: keep_alive,
+             connection_class: connection_class)
     end
 
-    # Creates a connection that connects to the specified `uri`.
-    #
-    # It then calls {Client.client_with_connection}.
+    # Creates a connection pool that connects to the specified `uri`.
     #
     # @param  [URI] uri
     #         the endpoint details of the service to connect to.
     #
-    # @param  [Certificate, String] certificate_or_data
+    # @param  [Certificate, String] certificate
     #         a configured Certificate or PEM data to construct a Certificate from.
     #
+    # @param  [Fixnum] pool_size
+    #         the number of connections to make.
+    #
+    # @param  [Boolean] keep_alive
+    #         when `true` this will make connections, new and restarted, immediately connect to the remote service. Use
+    #         this if you want to keep connections open indefinitely.
+    #
+    # @param  [Class] connection_class
+    #         the connection class to instantiate, this can for instan be {Mock::Connection} during testing.
+    #
     # @return (see Client#initialize)
     #
-    def self.client(uri, certificate_or_data)
-      certificate = Certificate.certificate(certificate_or_data)
-      client_with_connection(Connection.new(uri, certificate.ssl_context), certificate)
+    def self.client(uri:, certificate:, pool_size: 1, keep_alive: false, connection_class: Connection)
+      certificate = Certificate.certificate(certificate)
+      connection_class ||= Connection
+      connection_pool = connection_class.pool(size: pool_size, args: [uri, certificate.ssl_context, keep_alive])
+      client_with_connection(connection_pool, certificate: certificate)
     end
 
-    # Creates a Client configured with the `app_bundle_id` as its `default_topic`, in case the Certificate represents a
-    # Universal Certificate.
+    # Creates a Client configured with the `app_bundle_id` as its `default_topic`, in case the Certificate represents
+    # a Universal Certificate.
     #
-    # @param  [Connection] connection
-    #         a Connection configured to connect to the remote service.
+    # @param  [Connection, Celluloid::Supervision::Container::Pool<Connection>] connection
+    #         a single Connection or a pool of Connection actors configured to connect to the remote service.
     #
     # @param  [Certificate] certificate
     #         a configured Certificate.
     #
     # @return (see Client#initialize)
     #
-    def self.client_with_connection(connection, certificate)
-      new(connection, certificate.universal? ? certificate.topics.first : nil)
+    def self.client_with_connection(connection, certificate:)
+      new(connection: connection, default_topic: certificate.universal? ? certificate.topics.first : nil)
     end
 
     # You should normally use any of the other constructors to create a Client object.
     #
-    # @param  [Connection] connection
-    #         a Connection configured to connect to the remote service.
+    # @param  [Connection, Celluloid::Supervision::Container::Pool<Connection>] connection
+    #         a single Connection or a pool of Connection actors configured to connect to the remote service.
     #
     # @param  [String] default_topic
     #         the ‘topic’ to use if the Certificate is a Universal Certificate and a Notification doesn’t explicitely
@@ -92,14 +125,14 @@ module Lowdown
     # @return [Client]
     #         a new instance of Client.
     #
-    def initialize(connection, default_topic = nil)
+    def initialize(connection:, default_topic: nil)
       @connection, @default_topic = connection, default_topic
     end
 
     # @!group Instance Attribute Summary
 
-    # @return [Connection]
-    #         a Connection configured to connect to the remote service.
+    # @return [Connection, Celluloid::Supervision::Container::Pool<Connection>]
+    #         a single Connection or a pool of Connection actors configured to connect to the remote service.
     #
     attr_reader :connection
 
@@ -111,85 +144,148 @@ module Lowdown
 
     # @!group Instance Method Summary
 
-    # Opens the connection to the service. If a block is given the connection is automatically closed.
+    # Opens the connection to the service, yields a request group, and automatically closes the connection by the end of
+    # the block.
+    #
+    # @note   Don’t use this if you opted to keep a pool of connections alive.
     #
-    # @see Connection#open
+    # @see    Connection#connect
+    # @see    Client#group
     #
-    # @yield  [client]
-    #         yields `self`.
+    # @param  [Numeric] group_timeout
+    #         the maximum amount of time to wait for a request group to halt the caller thread. Defaults to 1 hour.
     #
-    # @return (see Connection#open)
+    # @yieldparam (see Client#group)
     #
-    def connect
-      @connection.open
-      if block_given?
+    # @return [void]
+    #
+    def connect(group_timeout: nil, &block)
+      if @connection.respond_to?(:actors)
+        @connection.actors.each { |connection| connection.async.connect }
+      else
+        @connection.async.connect
+      end
+      if block
         begin
-          yield self
+          group(timeout: group_timeout, &block)
         ensure
-          close
+          disconnect
         end
       end
     end
 
-    # Flushes the connection.
+    # Closes the connection to the service.
     #
-    # @see Connection#flush
+    # @see    Connection#disconnect
     #
-    # @return (see Connection#flush)
+    # @return [void]
     #
-    def flush
-      @connection.flush
+    def disconnect
+      @connection.disconnect
+    rescue Celluloid::DeadActorError
+      # Rescue this exception instead of calling #alive? as that only works on an actor, not a pool.
     end
 
-    # Closes the connection.
+    # Use this to group a batch of requests and halt the caller thread until all of the requests in the group have been
+    # performed.
+    #
+    # It proxies {RequestGroup#send_notification} to {Client#send_notification}, but, unlike the latter, the request
+    # callbacks are provided in the form of a block.
+    #
+    # @note   Do **not** share the yielded group across threads.
+    #
+    # @see    RequestGroup#send_notification
+    # @see    Connection::Monitor
     #
-    # @see Connection#close
+    # @param  [Numeric] timeout
+    #         the maximum amount of time to wait for a request group to halt the caller thread. Defaults to 1 hour.
     #
-    # @return (see Connection#close)
+    # @yieldparam [RequestGroup] group
+    #         the request group object.
     #
-    def close
-      @connection.close
+    # @raise  [Exception]
+    #         if a connection in the pool has died during the execution of this group, the reason for its death will be
+    #         raised.
+    #
+    # @return [void]
+    #
+    def group(timeout: nil)
+      group = nil
+      monitor do |condition|
+        group = RequestGroup.new(self, condition)
+        yield group
+        if !group.empty? && exception = condition.wait(timeout || DEFAULT_GROUP_TIMEOUT)
+          raise exception
+        end
+      end
+    ensure
+      group.terminate
+    end
+
+    # Registers a condition object with the connection pool, for the duration of the given block. It either returns an
+    # exception that caused a connection to die, or whatever value you signal to it.
+    #
+    # This is automatically used by {#group}.
+    #
+    # @yieldparam [Connection::Monitor::Condition] condition
+    #         the monitor condition object.
+    #
+    # @return [void]
+    #
+    def monitor
+      condition = Connection::Monitor::Condition.new
+      if defined?(Mock::Connection) && @connection.class == Mock::Connection
+        yield condition
+      else
+        begin
+          @connection.__register_lowdown_crash_condition__(condition)
+          yield condition
+        ensure
+          @connection.__deregister_lowdown_crash_condition__(condition)
+        end
+      end
     end
 
-    # Verifies the `notification` is valid and sends it to the remote service.
+    # Verifies the `notification` is valid and then sends it to the remote service. Response feedback is provided via
+    # a delegate mechanism.
     #
-    # @see Connection#post
+    # @note   In general, you will probably want to use {#group} to be able to use {RequestGroup#send_notification},
+    #         which takes a traditional blocks-based callback approach.
     #
-    # @note (see Connection#post)
+    # @see    Connection#post
     #
     # @param  [Notification] notification
     #         the notification object whose data to send to the service.
     #
-    # @yield  [response, notification]
-    #         called when the request is finished and a response is available.
-    #
-    # @yieldparam [Response] response
-    #         the Response that holds the status data that came back from the service.
+    # @param  [Connection::DelegateProtocol] delegate
+    #         an object that implements the connection delegate protocol.
     #
-    # @yieldparam [Notification] notification
-    #         the originally passed in notification object.
+    # @param  [Object, nil] context
+    #         any object that you want to be passed to the delegate once the response is back.
     #
     # @raise  [ArgumentError]
     #         raised if the Notification is not {Notification#valid?}.
     #
     # @return [void]
     #
-    def send_notification(notification, &callback)
+    def send_notification(notification, delegate:, context: nil)
       raise ArgumentError, "Invalid notification: #{notification.inspect}" unless notification.valid?
 
       topic = notification.topic || @default_topic
       headers = {}
       headers["apns-expiration"] = (notification.expiration || 0).to_i
-      headers["apns-id"]         = notification.formatted_id if notification.id
+      headers["apns-id"]         = notification.formatted_id
       headers["apns-priority"]   = notification.priority     if notification.priority
       headers["apns-topic"]      = topic                     if topic
 
       body = notification.formatted_payload.to_json
 
-      # No need to keep a strong reference to the notification object, unless the user really wants it.
-      actual_callback = callback.arity < 2 ? callback : lambda { |response| callback.call(response, notification) }
-
-      @connection.post("/3/device/#{notification.token}", headers, body, &actual_callback)
+      @connection.async.post(path: "/3/device/#{notification.token}",
+                             headers: headers,
+                             body: body,
+                             delegate: delegate,
+                             context: context)
     end
   end
 end
+