lowdown 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ce849fce8cd7a90dc303f9f761d88b497c7d80a
-  data.tar.gz: 4c041b547386c1f591ac0a30326666f91f926b09
+  metadata.gz: 3bae6b12ffe8101e10ab41c87a7e58f191d1c9e6
+  data.tar.gz: c34a58e8561c4c65c2292b207800b63237fcd038
 SHA512:
-  metadata.gz: abab9a4f67830d08411466d48c2ac48bcf6a9d5d4c91239096dcac04e418047ef2965ae7800311aa1e0a75554fc2e02f3b92269301fb0838e9c7d06c91b743e0
-  data.tar.gz: 5c8715d560ab305e3eca365f94f5f2458183dc3972b10608a1f39e7457b6aa9bf2f121b0ee8dd6b2ee2c408c52682470bfcc31a333817f2fcd0a5a9c8e9f89b5
+  metadata.gz: 13de1cb6266a8a507228b3ded7443c098fd7582d4df3c52c6dfaaba71c6cd1ec7b7db31d365a441187d3ecf88bbbe9485379d68377ae0b1563fc17373f857c4a
+  data.tar.gz: 32b3ae325cf9029554044f7bc63e5dd2a84b00a529b861c430084eb3d0904e2f30fc8d6ffacaeb2547457d972619aefbefbb7299124072ae175b329223c95bb0

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
 rvm:
-  - 2.1.0
+  - 2.1.1
   - 2.1
   - 2.2
   - 2.3.0

data/README.md

@@ -8,6 +8,13 @@ Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification S
 
 Multiple notifications are multiplexed for efficiency.
 
+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.
+
+Also checkout [this library](https://github.com/alloy/time_zone_scheduler) for scheduling across time zones.
+
 NOTE: _It is not yet battle-tested. This will all follow over the next few weeks._
 
 ## Installation

data/lib/lowdown.rb

@@ -3,7 +3,10 @@ require "lowdown/version"
 
 # Lowdown is a Ruby client for the HTTP/2 version of the Apple Push Notification Service.
 #
-# Multiple notifications are multiplexed for efficiency.
+# 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}.

data/lib/lowdown/client.rb

@@ -155,6 +155,8 @@ module Lowdown
     #
     # @see Connection#post
     #
+    # @note (see Connection#post)
+    #
     # @param  [Notification] notification
     #         the notification object whose data to send to the service.
     #

data/lib/lowdown/connection.rb

@@ -2,17 +2,20 @@ require "lowdown/threading"
 require "lowdown/response"
 
 require "http/2"
+
 require "openssl"
-require "uri"
 require "socket"
+require "timeout"
+require "uri"
 
 if HTTP2::VERSION == "0.8.0"
   # @!visibility private
   #
-  # Monkey-patch http-2 gem until this PR is merged: https://github.com/igrigorik/http-2/pull/44
+  # This monkey-patch ensures that we send the HTTP/2 connection preface before anything else.
+  #
+  # @see https://github.com/igrigorik/http-2/pull/44
+  #
   class HTTP2::Client
-    # This monkey-patch ensures that we send the HTTP/2 connection preface before anything else.
-    #
     def connection_management(frame)
       if @state == :waiting_connection_preface
         send_connection_preface
@@ -22,6 +25,22 @@ if HTTP2::VERSION == "0.8.0"
       end
     end
   end
+
+  # @!visibility private
+  #
+  # These monkey-patches ensure that data added to a buffer has a binary encoding, as to not lead to encoding clashes.
+  #
+  # @see https://github.com/igrigorik/http-2/pull/46
+  #
+  class HTTP2::Buffer
+    def <<(x)
+      super(x.force_encoding(Encoding::BINARY))
+    end
+
+    def prepend(x)
+      super(x.force_encoding(Encoding::BINARY))
+    end
+  end
 end
 
 module Lowdown
@@ -55,33 +74,9 @@ module Lowdown
     # @return [void]
     #
     def open
-      @socket = TCPSocket.new(@uri.host, @uri.port)
-
-      @ssl = OpenSSL::SSL::SSLSocket.new(@socket, @ssl_context)
-      @ssl.sync_close = true
-      @ssl.hostname = @uri.hostname
-      @ssl.connect
-
-      @http = HTTP2::Client.new
-      @http.on(:frame) do |bytes|
-        @ssl.print(bytes)
-        @ssl.flush
-      end
-
-      @main_queue    = Threading::DispatchQueue.new
-      @work_queue    = Threading::DispatchQueue.new
-      @requests      = Threading::Counter.new
-      @exceptions    = Queue.new
-      @worker_thread = start_worker_thread!
-    end
-
-    # @return [Boolean]
-    #         whether or not the Connection is open.
-    #
-    # @todo   Possibly add a HTTP/2 `PING` in the future.
-    #
-    def open?
-      !@ssl.nil? && !@ssl.closed?
+      raise "Connection already open." if @worker
+      @requests = Threading::Counter.new
+      @worker = Worker.new(@uri, @ssl_context)
     end
 
     # Flushes the connection, terminates the worker thread, and closes the socket. Finally it peforms one more check for
@@ -90,17 +85,33 @@ module Lowdown
     # @return [void]
     #
     def close
+      return unless @worker
       flush
+      @worker.stop
+      @worker = @requests = nil
+    end
 
-      @worker_thread[:should_exit] = true
-      @worker_thread.join
-
-      @ssl.close
-
-      sleep 0.1
-      @main_queue.drain!
-
-      @socket = @ssl = @http = @main_queue = @work_queue = @requests = @exceptions = @worker_thread = nil
+    # This performs a HTTP/2 PING to determine if the connection is actually alive.
+    #
+    # @param  [Numeric] timeout
+    #         the maximum amount of time to wait for the service to reply to the PING.
+    #
+    # @return [Boolean]
+    #         whether or not the Connection is open.
+    #
+    def open?(timeout = 5)
+      return false unless @worker
+      Timeout.timeout(timeout) do
+        caller_thread = Thread.current
+        @worker.enqueue do |http|
+          http.ping('12345678') { caller_thread.run }
+        end
+        Thread.stop
+      end
+      # If the thread was woken-up before the timeout was reached, that means we got a PONG.
+      true
+    rescue Timeout::Error
+      false
     end
 
     # Halts the calling thread until all dispatched requests have been performed.
@@ -108,14 +119,14 @@ module Lowdown
     # @return [void]
     #
     def flush
-      until @work_queue.empty? && @requests.zero?
-        @main_queue.drain!
-        sleep 0.1
-      end
+      return unless @worker
+      sleep 0.1 until !@worker.alive? || @worker.empty? && @requests.zero?
     end
 
     # Sends the provided data as a `POST` request to the service.
     #
+    # @note The callback is performed on a different thread, dedicated to perfoming these callbacks.
+    #
     # @param  [String] path
     #         the request path, which should be `/3/device/<device-token>`.
     #
@@ -141,11 +152,11 @@ module Lowdown
 
     def request(method, path, custom_headers, body, &callback)
       @requests.increment!
-      @work_queue.dispatch do
+      @worker.enqueue do |http, callbacks|
         headers = { ":method" => method.to_s, ":path" => path.to_s, "content-length" => body.bytesize.to_s }
         custom_headers.each { |k, v| headers[k] = v.to_s }
 
-        stream = @http.new_stream
+        stream = http.new_stream
         response = Response.new
 
         stream.on(:headers) do |response_headers|
@@ -158,7 +169,7 @@ module Lowdown
         end
 
         stream.on(:close) do
-          @main_queue.dispatch do
+          callbacks << lambda do
             callback.call(response)
             @requests.decrement!
           end
@@ -167,54 +178,131 @@ module Lowdown
         stream.headers(headers, end_stream: false)
         stream.data(body, end_stream: true)
       end
-
-      # The caller might be posting many notifications, so use this time to also dispatch work onto the main thread.
-      @main_queue.drain!
     end
 
-    def start_worker_thread!
-      Thread.new do
-        until Thread.current[:should_exit] || @ssl.closed?
-          # Run any dispatched jobs that add new requests.
-          #
-          # Re-raising a worker exception aids the development process. In production there’s no reason why this should
-          # raise at all.
-          if exception = @work_queue.drain!
-            exception_occurred_in_worker(exception)
-          end
+    # @!visibility private
+    #
+    # Creates a new worker thread which maintains all its own state:
+    # * SSL connection
+    # * HTTP2 client
+    # * Another thread from where request callbacks are ran
+    #
+    class Worker < Thread
+      def initialize(uri, ssl_context)
+        @uri, @ssl_context = uri, ssl_context
 
-          # Try to read data from the SSL socket without blocking. If it would block, catch the exception and restart
-          # the loop.
-          begin
-            data = @ssl.read_nonblock(1024)
-          rescue IO::WaitReadable
-            data = nil
-          rescue EOFError => exception
-            exception_occurred_in_worker(exception)
-            Thread.current[:should_exit] = true
-            data = nil
-          end
+        # Because a max size of 0 is not allowed, create with an initial max size of 1 and add a dummy job. This is so
+        # that any attempt to add a new job to the queue is going to halt the calling thread *until* we change the max.
+        @queue = SizedQueue.new(1)
+        @queue << lambda { |*_| }
+
+        # Setup the consumer that performs the callbacks passed to Connection#request
+        @callback_queue = Queue.new
+        @callback_thread = Thread.new(@callback_queue) { |q| loop { q.pop.call } }
+
+        # Store the caller thread to be able to resume it once connected and to send exceptions to.
+        @caller_thread = Thread.current
+        # Start the worker thread.
+        super(&method(:main))
+        # Put caller thread into sleep until connected.
+        Thread.stop
+      end
+
+      # @yield  [http, callbacks_queue]
+      #
+      # @yieldparam [HTTP2::Client] http
+      #         the HTTP2 client instance.
+      #
+      # @yieldparam [Queue] callbacks_queue
+      #         the queue on which request callbacks should be performed.
+      #
+      # @return [void]
+      #
+      def enqueue(&job)
+        @queue << job
+      end
+
+      # @return [Boolean]
+      #         whether or not the work queue is empty.
+      #
+      def empty?
+        @queue.empty?
+      end
+
+      # Tells the runloop to stop and halts the caller until finished.
+      #
+      # @return [void]
+      #
+      def stop
+        self[:should_exit] = true
+        join
+      end
+
+      private
 
-          # Process incoming HTTP data. If any processing exception occurs, fail the whole process.
-          if data
+      def main
+        connect
+        runloop
+      rescue Exception => exception
+        # Send any unexpected exceptions back to the thread that started the loop.
+        @caller_thread.raise(exception)
+      ensure
+        cleanup
+      end
+
+      def cleanup
+        @callback_thread.kill
+        @ssl.close
+      end
+
+      def connect
+        @ssl = OpenSSL::SSL::SSLSocket.new(TCPSocket.new(@uri.host, @uri.port), @ssl_context)
+        @ssl.sync_close = true
+        @ssl.hostname = @uri.hostname
+        @ssl.connect
+
+        @http = HTTP2::Client.new
+        @http.on(:frame) do |bytes|
+          # This is going to be performed on the worker thread and thus does *not* write to @ssl from another thread than
+          # the thread it’s being read from.
+          @ssl.print(bytes)
+          @ssl.flush
+        end
+      end
+
+      def change_to_connected_state
+        @queue.max = @http.remote_settings[:settings_max_concurrent_streams]
+        @connected = true
+        @caller_thread.run
+      end
+
+      # @note Only made into a method so it can be overriden from the tests, because our test setup doesn’t behave the
+      #       same as the real APNS service.
+      #
+      def http_connected?
+        @http.state == :connected
+      end
+
+      # Start the main IO and HTTP processing loop.
+      def runloop
+        until self[:should_exit] || @ssl.closed?
+          # Once connected, add requests while the max stream count has not yet been reached.
+          if !@connected
+            change_to_connected_state if http_connected?
+          elsif @http.active_stream_count < @queue.max
             begin
-              @http << data
-            rescue Exception => exception
-              @ssl.close
-              exception_occurred_in_worker(exception)
+              # Run dispatched jobs that add new requests.
+              @queue.pop(true).call(@http, @callback_queue)
+            rescue ThreadError
             end
           end
+          # Try to read data from the SSL socket without blocking and process it.
+          begin
+            @http << @ssl.read_nonblock(1024)
+          rescue IO::WaitReadable
+          end
         end
       end
     end
-
-    # Raise the exception on the main thread and reset the number of in-flight requests so that a potential blocked
-    # caller of `Connection#flush` will continue.
-    #
-    def exception_occurred_in_worker(exception)
-      @exceptions << exception
-      @main_queue.dispatch { raise @exceptions.pop }
-      @requests.value = @http.active_stream_count
-    end
   end
 end

data/lib/lowdown/threading.rb

@@ -4,49 +4,6 @@ module Lowdown
   # A collection of internal threading related helpers.
   #
   module Threading
-    # A queue of blocks that are to be dispatched onto another thread.
-    #
-    class DispatchQueue
-      def initialize
-        @queue = Queue.new
-      end
-
-      # Adds a block to the queue.
-      #
-      # @return [void]
-      #
-      def dispatch(&block)
-        @queue << block
-      end
-
-      # @return [Boolean]
-      #         whether or not the queue is empty.
-      #
-      def empty?
-        @queue.empty?
-      end
-
-      # Performs the number of dispatched blocks that were on the queue at the moment of calling `#drain!`. Unlike
-      # performing blocks _until the queue is empty_, this ensures that it doesn’t block the calling thread too long if
-      # another thread is dispatching more work at the same time.
-      #
-      # By default this will let any exceptions bubble up on the main thread or catch and return them on other threads.
-      #
-      # @param  [Boolean] rescue_exceptions
-      #         whether or not to rescue exceptions.
-      #
-      # @return [Exception, nil]
-      #         in case of rescueing exceptions, this returns the exception raised during execution of a block.
-      #
-      def drain!(rescue_exceptions = (Thread.current != Thread.main))
-        @queue.size.times { @queue.pop.call }
-        nil
-      rescue Exception => exception
-        raise unless rescue_exceptions
-        exception
-      end
-    end
-
     # A simple thread-safe counter.
     #
     class Counter

data/lib/lowdown/version.rb

@@ -1,5 +1,3 @@
 module Lowdown
-  # The currect version of the Lowdown library.
-  #
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lowdown.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # This is currently set to >= 2.0.0 in the http-2 gemspec, which is incorrect, as it uses required keyword arguments.
-  spec.required_ruby_version = '>= 2.1.0'
+  spec.required_ruby_version = '>= 2.1.1'
 
   spec.add_runtime_dependency "http-2", ">= 0.8"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lowdown
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Eloy Durán
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-08 00:00:00.000000000 Z
+date: 2016-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-2
@@ -106,7 +106,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.1.0
+      version: 2.1.1
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A Ruby client for the HTTP/2 version of the Apple Push Notification Service.