push_kit-apns 1.0.0.pre.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81a37cc16b4ed2fa5d99091530b2352cfce87b8329b7573c2a57cd66c8f951c6
+  data.tar.gz: d7d6b80348f17dec42e2ba44cc1c2b8e9348a4cd5979b63e4194d0aa728f7d5a
+SHA512:
+  metadata.gz: c3bf44f4cd9d0935ed1ed3ea76f5ae5d7407ec9723946f8086e262a5184f8e92f62ba69268585c706c66bf21e5a3fab6529858e9af2c57f03139a859a0772747
+  data.tar.gz: 39b9bf33159a6a53669515700f169d9865c8442aa8d05d625c34032bfc9b46b9c14571cc2fd3bd190992c5eade594dbd029fc9c7f638aa75c0429c5fd039a37e

data/.gitignore

@@ -0,0 +1,46 @@
+# Packages #
+############
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+
+# Logs #
+########
+*.log
+
+# Databases #
+#############
+*.sql
+*.sqlite
+
+# OS Files #
+############
+.DS_Store
+.Trashes
+ehthumbs.db
+Icon?
+Thumbs.db
+
+# Vagrant #
+###########
+.vagrant
+
+# Ruby Files #
+##############
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+/vendor/bundle/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  Exclude:
+    - 'bin/**/*'
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -0,0 +1,118 @@
+# PushKit
+
+PushKit makes it easy to create and deliver push notifications.
+
+## PushKit::APNS
+
+PushKit::APNS provides an easy-to-use API for creating and then delivering notifications via the Apple Push Notification service.
+It uses the new HTTP/2 API and tokens so no more yearly certificate renewals!
+
+## Installation
+
+You can install **PushKit::APNS** using the following command:
+
+    $ gem install push_kit-apns
+
+### Usage
+
+You'll need to grab a few things in order to send push notifications:
+
+  - A key from the Apple Developer portal, one which has the push notification option enabled.
+  - The ID of the key you're going to use.
+  - The ID of the team that generated the key.
+  - The bundle identifier of your application, which is used as the APNS topic.
+
+Once you've obtained all of the above, you can create a new client like this:
+
+```ruby
+client = PushKit::APNS.client(
+  key: PushKit::APNS.load_key('/path/to/APNsAuthKey_XXXXXXXXXX.p8'),
+  key_id: 'XXXXXXXXXX',
+  team_id: 'XXXXXXXXXX',
+  topic: 'com.example.app'
+)
+```
+
+Ideally, you should create the client when your app boots and keep it until your app is rebooted.
+This allows us to maintain a connection to the Apple Push Notification service and quickly deliver notifications without the overhead of establishing a connection.
+
+See [Communicating with APNs - Best Practices for Managing Connections](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW8) for more info on this.
+
+### Additional Options
+
+There are a few additional options you can specify when creating a client.
+
+##### :host
+
+You can provide the full hostname (or IP address) as a String. For example: 'api.push.apple.com'
+
+Because this option's value is rarely set to anything other than the standard hostnames, we've added
+a couple of convenience Symbols. These are *:development* and *:production* which sets the hostname
+to the appropriate hostname for that environment.
+
+The default value of this option is *:development*.
+
+##### :port
+
+You can also provide the port number as an Integer. For example: 443
+This also has a couple of convenience Symbols, *:default* and *:alternative*.
+
+The default value of this option is *:default*.
+
+---
+
+Creating a notification is easy with PushKit and there are quite a few different options you can set.
+For a full list, checkout the documentation for `PushKit::APNS::Notification`.
+
+For now, let's just create a simple notification:
+
+```ruby
+notification = PushKit::APNS::Notification.new
+notification.title = 'Hello, World!'
+notification.body = 'How are you today?'
+notification.sound = :default
+notification.device_token = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+```
+
+Then using our `PushKit::APNS` instance we created earlier, deliver the notification:
+
+```ruby
+apns.deliver(notification)
+```
+
+EXPLAIN_ASYNC_NEEDS_WAIT
+
+---
+
+The `PushKit::APNS::Notification` instance has a *:device_token* attribute which needs to be set to the token of the device you're sending the notification to.
+
+It's common to want to send the same notification to a bunch of devices. When you want to do this, leave the initial notification's *:device_token* attribute blank and instead use the helper method *:for_tokens*:
+
+```ruby
+notification = PushKit::APNS::Notification.new
+notification.title = 'Hello, World!'
+notification.body = 'How are you today?'
+notification.sound = :default
+
+tokens = %w[
+  1111111111111111111111111111111111111111111111111111111111111111
+  2222222222222222222222222222222222222222222222222222222222222222
+  3333333333333333333333333333333333333333333333333333333333333333
+]
+
+notifications = notification.for_tokens(*tokens)
+```
+
+When you're ready, you can just deliver the array of notifications:
+
+```ruby
+client.deliver(notifications) do |notification, result|
+  # ...
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle exec rake spec` to run the tests.
+
+To install this gem onto your machine, run `bundle exec rake install`.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'push_kit/apns'
+require 'irb'
+
+IRB.start

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/lib/push_kit/apns.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'http/2'
+require 'json'
+require 'jwt'
+require 'openssl'
+require 'securerandom'
+require 'uri'
+
+require 'push_kit/apns/constants'
+require 'push_kit/apns/notification/localization'
+require 'push_kit/apns/notification'
+require 'push_kit/apns/http_client'
+require 'push_kit/apns/token_generator'
+require 'push_kit/apns/push_client'
+
+module PushKit
+  # PushKit::APNS provides an easy-to-use API for creating and then delivering notifications via the
+  # Apple Push Notification service.
+  #
+  module APNS
+    # Read the key from the file at the specified path.
+    #
+    # @param  path [String]            Path to a key file.
+    # @return      [OpenSSL::PKey::EC] The loaded key.
+    #
+    def self.load_key(path)
+      raise ArgumentError, "The key file does not exist: #{path}" unless File.file?(path)
+
+      OpenSSL::PKey::EC.new(File.read(path))
+    end
+
+    # Create a new PushClient instance.
+    #
+    # @param options [Hash]              The APNS options:
+    #        host    [String|Symbol]     The host (can also be :production or :development).
+    #        port    [Integer|Symbol]    The port number (can also be :default or :alternative).
+    #        topic   [String]            The APNS topic (matches the app's bundle identifier).
+    #        key     [OpenSSL::PKey::EC] The elliptic curve key to use for authentication.
+    #        key_id  [String]            The identifier for the elliptic curve key.
+    #        team_id [String]            The identifier for the Apple Developer team.
+    #        topic   [String]            The topic for your application (usually the bundle identifier).
+    #
+    def self.client(options = {})
+      options = {
+        host: :development,
+        port: :default
+      }.merge(options)
+
+      token_generator = TokenGenerator.new(
+        key: options[:key],
+        key_id: options[:key_id],
+        team_id: options[:team_id]
+      )
+
+      PushClient.new(
+        host: options[:host],
+        port: options[:port],
+        topic: options[:topic],
+        token_generator: token_generator
+      )
+    end
+  end
+end

data/lib/push_kit/apns/constants.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PushKit
+  module APNS
+    # @return [String] The gem's semantic version number.
+    #
+    VERSION = '1.0.0-beta1'
+  end
+end

data/lib/push_kit/apns/http_client.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module PushKit
+  module APNS
+    # The HTTPClient class provides a minimal HTTP/2 client.
+    #
+    class HTTPClient
+      # @return [String] The ALPN protocol required by HTTP/2.
+      #
+      ALPN_PROTOCOL = 'h2'
+
+      # @return [URI] The URI which indicates the scheme, host and port of the remote server.
+      #
+      attr_reader :uri
+
+      # Creates a new HTTPClient.
+      #
+      # @param uri [String|URI] A URI which indicates the scheme, host and port of the remote server.
+      #
+      def initialize(uri)
+        case uri
+        when String then @uri = URI(uri)
+        when URI    then @uri = uri
+        else             raise 'Expected the :uri attribute to be a String or a URI.'
+        end
+      end
+
+      # Perform a HTTP request.
+      #
+      # @param method  [String|Symbol] The request method (:get, :post, etc).
+      # @param path    [String]        The request path.
+      # @param headers [Hash]          The request headers.
+      # @param body    [String]        The request body.
+      # @param block   [Proc]          A block to call once the request has completed.
+      #
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      #
+      def request(method: nil, path: nil, headers: nil, body: nil, &block)
+        raise 'The :method should be a String or a Symbol' unless method.is_a?(String) || method.is_a?(Symbol)
+        raise 'The :path should be a String'               unless path.is_a?(String)
+        raise 'The :headers should be a Hash'              unless headers.nil? || headers.is_a?(Hash)
+        raise 'The :body should be a String'               unless body.nil? || body.is_a?(String)
+        raise 'The completion block must be provided.'     unless block.is_a?(Proc)
+
+        requests.push(method: method, path: path, headers: headers, body: body, completion: block)
+
+        perform_requests
+
+        nil
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      private
+
+      # @return [Mutex] The semaphore used to ensure only one #perform_requests method call executes at a time.
+      #
+      def perform_requests_mutex
+        @perform_requests_mutex ||= Mutex.new
+      end
+
+      # @return [Queue] The queue containing requests that need to be processed.
+      #
+      def requests
+        @requests ||= Queue.new
+      end
+
+      # @return [OpenSSL::SSL::SSLSocket|TCPSocket] An SSL or TCP socket.
+      #
+      def socket
+        ssl_socket || tcp_socket
+      end
+
+      # Reset the client and sockets if the connection is broken.
+      #
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+      #
+      def reset_if_required!
+        socket = @ssl_socket || @tcp_socket
+
+        return unless socket.nil? || socket.closed? || @client.nil? || @client.closed?
+
+        @ssl_socket.close unless @ssl_socket.nil? || @ssl_socket.closed?
+        @tcp_socket.close unless @tcp_socket.nil? || @tcp_socket.closed?
+
+        @ssl_socket = nil
+        @tcp_socket = nil
+        @client = nil
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # @return [HTTP2::Client] An HTTP/2 client.
+      #
+      def client
+        reset_if_required!
+
+        return @client unless @client.nil? || @client.closed?
+
+        @client = HTTP2::Client.new
+
+        @client.on(:frame) do |bytes|
+          next if socket.closed?
+
+          socket.print(bytes)
+          socket.flush
+        end
+
+        @client.send_connection_preface
+
+        # The @client instance variable must exist before calling this method!
+        spawn_input_thread
+
+        @client
+      end
+
+      # @return [TCPSocket] The TCP socket.
+      #
+      def tcp_socket
+        return @tcp_socket unless @tcp_socket.nil? || @tcp_socket.closed?
+
+        @tcp_socket = TCPSocket.new(uri.host, uri.port)
+      end
+
+      # @return [OpenSSL::SSL::SSLSocket] An SSL socket.
+      #
+      def ssl_socket
+        return @ssl_socket unless @ssl_socket.nil? || @ssl_socket.closed?
+
+        # Only create the SSLSocket if the URI requires a secure connection.
+        return nil unless uri.scheme == 'https'
+
+        socket = OpenSSL::SSL::SSLSocket.new(tcp_socket, ssl_context)
+        socket.sync_close = true
+        socket.hostname = uri.host
+        socket.connect
+
+        if socket.alpn_protocol != ALPN_PROTOCOL
+          raise "Expected ALPN protocol '#{ALPN_PROTOCOL}' but received '#{socket.alpn_protocol}'."
+        end
+
+        @ssl_socket = socket
+      end
+
+      # @return [OpenSSL::SSL::SSLContext] An SSL context.
+      #
+      def ssl_context
+        context = OpenSSL::SSL::SSLContext.new
+        context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        context.alpn_protocols = [ALPN_PROTOCOL]
+        context.alpn_select_cb = lambda do |protocols|
+          ALPN_PROTOCOL if protocols.include?(ALPN_PROTOCOL)
+        end
+
+        context
+      end
+
+      # Loop over the requests in the queue, performing them until we've emptied the queue or we've hit
+      # the concurrent stream limit.
+      #
+      def perform_requests
+        return unless perform_requests_mutex.try_lock
+
+        loop do
+          begin
+            request = requests.pop(true)
+            perform_request(request)
+          rescue HTTP2::Error::StreamLimitExceeded
+            requests.push(request)
+            break
+          rescue ThreadError
+            break
+          end
+        end
+
+        perform_requests_mutex.unlock
+      end
+
+      # @param request [Hash] The request.
+      #
+      def perform_request(request)
+        stream = client.new_stream
+
+        if (block = request[:completion])
+          handle_response(stream, &block)
+        end
+
+        headers = headers(request)
+        body = request[:body]
+
+        if body.is_a?(String)
+          stream.headers(headers, end_stream: false)
+          stream.data(body, end_stream: true)
+        else
+          stream.headers(headers, end_stream: true)
+        end
+      end
+
+      # @param stream [HTTP2::Stream] The unique stream for the request.
+      # @param block  [Proc]          A block to call once the request has completed.
+      #
+      def handle_response(stream, &block)
+        return unless block.is_a?(Proc)
+
+        response_headers = {}
+        response_body = String.new
+
+        stream.on(:headers) do |headers|
+          response_headers.merge!(Hash[headers])
+        end
+
+        stream.on(:data) do |data|
+          response_body.concat(data)
+        end
+
+        stream.on(:close) do
+          perform_requests
+
+          status = response_headers[':status']
+          status = status.to_i if status.is_a?(String)
+          status = nil unless status.is_a?(Integer)
+
+          block.call(status, response_headers, response_body)
+        end
+      end
+
+      # @param  request [Hash] The request.
+      # @return         [Hash] The request headers.
+      #
+      def headers(request)
+        return nil unless request.is_a?(Hash)
+        return nil unless (method = request[:method])
+        return nil unless (path = request[:path])
+
+        headers = {
+          ':scheme' => uri.scheme,
+          ':authority' => [uri.host, uri.port].join(':'),
+          ':method' => method.to_s.upcase,
+          ':path' => path.to_s
+        }
+
+        body = request[:body]
+        headers['content-length'] = body.length.to_s if body.is_a?(String)
+
+        headers.merge!(request[:headers]) if request[:headers].is_a?(Hash)
+
+        headers
+      end
+
+      # Spawn a thread to wrap the #input_loop method.
+      #
+      def spawn_input_thread
+        return if @input_thread&.alive?
+
+        @input_thread = Thread.new { input_loop }
+      end
+
+      # Start a continuous loop, reading bytes from the socket and passing them to the HTTP/2 client.
+      #
+      def input_loop
+        loop do
+          break if @client.nil? || @client.closed? || socket.closed? || socket.eof?
+
+          begin
+            @client << socket.read_nonblock(1024)
+          rescue StandardError
+            socket.close
+
+            raise
+          end
+        end
+      end
+    end
+  end
+end