lorkhan 0.0.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b8c3fb041b617f47b7301f48c86f41b06c0db14a
-  data.tar.gz: 56a83e2fff46bbf4499ec092bc8f367d2ec3f602
+  metadata.gz: c9d9e98e45358c0cd329ab15535946be86a84a2b
+  data.tar.gz: ad11e57d08eb593634f3f741a0d532a57673ab86
 SHA512:
-  metadata.gz: 869f5ce31fb9c8a52ff2b7cfbe851073072a04bf32aa3b02723d4a4779624bfdc97742a93b51e281d195ab824897f8497b3468f1c19826bce266444c5c4a4733
-  data.tar.gz: 214eecef306334378480d276d184b9e896072b356f9cc8e58c86d02bf8d93ffe8c2903ccb4d39edb04e0d225be86ab2b1ec03af2fb8bc75d6af29f78e705dfcc
+  metadata.gz: ff895526c5d9d028eedb0a6bc0c14bd3e864ed6bed44b11ae25ec92328c7e7896710ab670dccbac6b393e9e471d57ee492622d2b1a715cd03ebbb6d50634b0c1
+  data.tar.gz: e06ac2239cb27cbd11966f1566e721a1340d5b3521484432e4dfeb1593e2363de2cbeb2fc4efc93c1f5fabd33fe6b091bede2dc0d8deaab7cabb028dd9d1c0d9

data/.rubocop.yml

@@ -12,6 +12,12 @@ Metrics/LineLength:
 Metrics/MethodLength:
   Max: 16
 
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,7 +1,3 @@
-### 0.0.4
-
-- Added `Lorkhan::Notification::DEFAULT_SOUND_NAME`
-
 ### 0.0.3
 
 - Sending a `content_available` push, now excludes the `alert`, `badge`, `sound` keys.

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    lorkhan (1.0.0)
+      connection_pool (>= 2.0)
+      jwt (>= 1.5.6)
+      net-http2 (>= 0.14.1, < 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.1)
+    connection_pool (2.2.1)
+    diff-lcs (1.3)
+    http-2 (0.8.3)
+    jwt (1.5.6)
+    method_source (0.8.2)
+    net-http2 (0.14.1)
+      http-2 (~> 0.8.2)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.5.0)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    slop (3.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  lorkhan!
+  pry
+  rake (~> 10.0)
+  rspec (~> 3.5)
+
+BUNDLED WITH
+   1.13.6

data/README.md

@@ -1,3 +1,28 @@
-# THIS IS DEPRECATED
+## Lorkhan
 
-`gem 'lorkhan', '~> 1.0'`
+Apple Push Notification Services client using the HTTP/2 API and Provider Authentication Tokens
+
+### Getting Provider Authentication Tokens
+
+See: "Generate a universal provider token signing key" under "Configure push notifications." in [Xcode Help](http://help.apple.com/xcode)
+
+### Sending a Push Notification
+
+```ruby
+token = Lorkhan::ProviderToken.new(key_id: '<token key id>', team_id: '<developer team id>', secret: '<PAT secret>')
+connection = Lorkhan::Connection.new(production: true, token: token)
+
+notification = Lorkhan::Notification.new('<device token>')
+notification.topic = '<your app ID>'
+notification.alert = 'Hello from Lorkhan'
+
+connection.push(notification)
+```
+
+### Other Gotcha's
+
+- Your OpenSSL implementation __MUST__ support the `ES256` elliptical curve.
+
+### Extra reading
+
+##### [Local and Remote Notification Programming Guide](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW1)

data/lib/lorkhan/connection.rb

@@ -4,31 +4,53 @@ require 'openssl'
 module Lorkhan
   APNS_PRODUCTION_HOST  = 'api.push.apple.com'.freeze
   APNS_DEVELOPMENT_HOST = 'api.development.push.apple.com'.freeze
-  TOKEN_EXPIRE_TIME_SEC = 3300 # 55 minutes (Apple timeout in 60)
+  TOKEN_EXPIRE_TIME_SEC = 3300 # 55 minutes (Apple timeout is 60)
 
+  ##
+  # The Connection class manages the HTTP/2 connection to Apple's servers
+  #
+  # token: (Lorkhan::ProviderToken) Used to authenticate with Apple's servers
+  # production: (Boolean) Used to determine which endpoint to establish the connection
+  # timeout: (Int) Number of seconds to wait before timing out opening the connection
+  ##
   class Connection
     attr_reader :host, :token
 
     def initialize(token:, production: true, timeout: 30)
+      raise ArgumentError, 'Token must be a Lorkhan::ProviderToken' unless token.is_a?(Lorkhan::ProviderToken)
+
       @host    = production ? APNS_PRODUCTION_HOST : APNS_DEVELOPMENT_HOST
       @timeout = timeout
       @token   = token
       @client  = NetHttp2::Client.new(url, connect_timeout: @connect_timeout)
     end
 
+    ##
+    # Closes the connection to apple.
+    ##
     def close
       @client.close
     end
 
-    def join
-      @client.join
-    end
-
+    ##
+    # Closes the connection and resets the authentication token.
+    #
+    # This should happen automatically 55 minutes after the original token was generated.
+    ##
     def refresh_token
       @auth_token = nil
       close
     end
 
+    ##
+    # Deliver a Lorkhan::Notification to Apple's servers.
+    #
+    # If the connection is not open, this will attempt to establish the connection.
+    #
+    # notification: (Lorkhan::Notification) The notification to deliver.
+    #
+    # return: The HTTP response from Apple
+    ##
     def push(notification)
       check_token_should_refresh
       request = Request.new(notification)

data/lib/lorkhan/errors/apple_errors.rb

@@ -4,31 +4,87 @@ require 'lorkhan/errors/http_error'
 module Lorkhan
   module Errors
     module Apple
+      # The collapse identifier exceeds the maximum allowed size
       class BadCollapseId < Errors::HTTPError; end
+
+      # The specified device token was bad.
+      # Verify that the request contains a valid token and that the token matches the environment.
       class BadDeviceToken < Errors::HTTPError; end
+
+      # The apns-expiration value is bad.
       class BadExpirationDate < Errors::HTTPError; end
+
+      # The apns-id value is bad.
       class BadMessageId < Errors::HTTPError; end
+
+      # The apns-priority value is bad.
       class BadPriority < Errors::HTTPError; end
+
+      # The apns-topic was invalid.
       class BadTopic < Errors::HTTPError; end
+
+      # The device token does not match the specified topic.
       class DeviceTokenNotForTopic < Errors::HTTPError; end
+
+      # One or more headers were repeated.
       class DuplicateHeaders < Errors::HTTPError; end
+
+      # Idle time out.
       class IdleTimeout < Errors::HTTPError; end
+
+      # The device token is not specified in the request :path. Verify that the :path header contains the device token.
       class MissingDeviceToken < Errors::HTTPError; end
+
+      # The apns-topic header of the request was not specified and was required.
+      # The apns-topic header is mandatory when the client is
+      # connected using a certificate that supports multiple topics.
       class MissingTopic < Errors::HTTPError; end
+
+      # The message payload was empty.
       class PayloadEmpty < Errors::HTTPError; end
+
+      # Pushing to this topic is not allowed.
       class TopicDisallowed < Errors::HTTPError; end
+
+      # The provider token is stale and a new token should be generated.
       class ExpiredProviderToken < Errors::HTTPError; end
+
+      # The specified action is not allowed.
       class Forbidden < Errors::HTTPError; end
+
+      # The provider token is not valid or the token signature could not be verified
       class InvalidProviderToken < Errors::HTTPError; end
+
+      # No provider certificate was used to connect to APNs and Authorization
+      # header was missing or no provider token was specified.
+      # The specified :method was not POST.
       class MissingProviderToken < Errors::HTTPError; end
+
+      # The request contained a bad :path value.
       class BadPath < Errors::HTTPError; end
+
+      # The specified :method was not POST.
       class MethodNotAllowed < Errors::HTTPError; end
+
+      # The device token is inactive for the specified topic.
       class Unregistered < Errors::HTTPError; end
+
+      # The message payload was too large.
       class PayloadTooLarge < Errors::HTTPError; end
+
+      # The provider token is being updated too often.
       class TooManyProviderTokenUpdates < Errors::HTTPError; end
+
+      # Too many requests were made consecutively to the same device token.
       class TooManyRequests < Errors::HTTPError; end
+
+      # An internal server error occurred.
       class InternalServerError < Errors::HTTPError; end
+
+      # The service is unavailable.
       class ServiceUnavailable < Errors::HTTPError; end
+
+      # The server is shutting down.
       class Shutdown < Errors::HTTPError; end
 
       MAPPINGS = {

data/lib/lorkhan/notification.rb

@@ -2,18 +2,65 @@ require 'json'
 require 'securerandom'
 
 module Lorkhan
+  ##
+  # Describes a push notification
+  #
+  # Required attributes
+  #
+  #   - token: The device token to deliver the notification to
+  #   - apns_id: The APNS id for the notification.
+  #              This *must* be a UUID and is created when the instance is initialized.
+  #   - priority: The priority of the notification.  Apple will use this to determine how to deliver the notification.
+  #               See `PRIORITY_DELIVER_IMMEDIATELY` & `PRIORITY_DELIVER_BACKGROUND` for more info.
+  #   - expiration: A UNIX UTC epoch expressed in seconds for how long Apple will retain the notification,
+  #                 and attempt redelivery.  A 0 time will attempt a single delivery then disguard the message.
+  #   - topic: The topic of the remote notification, which is typically the bundle ID for your app.
+  #            The certificate you create in your developer account must include the capability for this topic.
+  #
+  # Optional attributes
+  #
+  #   - alert: The message displayed to the user.
+  #   - badge: The badge number displayed on the app icon.
+  #   - category: The category for the notification.  Used to provide direct notification actions.
+  #   - collapse_id: Used to group multiple notifications on the screen.
+  #   - content_available: A boolean if this should be a content available push.
+  #                        This will deliver a silent notification to the device.
+  #                        Your app's entitlements must be enabled.
+  #                        If the value for this is truthy, the alert, badge, sound will be ignored.
+  #   - custom_payload: A custom hash of data to send.  Must be JSON encodable.
+  #   - mutable_content: A `1` if the notificaiton is mutable.
+  #                      See `UNNotificationServiceExtension` (https://developer.apple.com/reference/usernotifications/unnotificationserviceextension)
+  #   - sound: The name of a bundled sound file to play.
+  #   - url_args: Used in conjunction with the `urlFormatString` in
+  #               the `website.json` file for sending web notifications.
+  ##
   class Notification
-    DEFAULT_SOUND_NAME = 'default'.freeze
+    ##
+    # Send the push message immediately.
+    # Notifications with this priority must trigger an alert, sound, or badge on the target device.
+    ##
+    PRIORITY_DELIVER_IMMEDIATELY = 10
+
+    ##
+    # Send the push message at a time that takes into account power considerations for the device.
+    # Notifications with this priority might be grouped and delivered in bursts.
+    ##
+    PRIORITY_DELIVER_BACKGROUND  = 5
 
     attr_reader :token, :apns_id
     attr_accessor :custom_payload, :alert, :badge, :sound, :category, :content_available, :url_args, :mutable_content
     attr_accessor :expiration, :priority, :topic, :collapse_id
 
+    ##
+    # Create a new notification
+    #
+    # token: The Device token that the notification will be delivered to
+    ##
     def initialize(token)
       @token      = token
       @apns_id    = SecureRandom.uuid
       @expiration = 0
-      @priority   = 10
+      @priority   = PRIORITY_DELIVER_IMMEDIATELY
     end
 
     def body
@@ -32,7 +79,7 @@ module Lorkhan
           end
           aps[:category] = category if category
           aps['url-args'] = url_args if url_args
-          aps['mutable-content'] = mutable_content if mutable_content
+          aps['mutable-content'] = 1 if mutable_content
         end
         root.merge!(custom_payload) if custom_payload
       end

data/lib/lorkhan/provider_token.rb

@@ -2,9 +2,22 @@ require 'jwt'
 require 'openssl'
 
 module Lorkhan
+  ##
+  # Wrapper for creating the authentication token for communicating with Apple's servers.
+  #
+  # See the "Provider Authentication Tokens" from Apple's "Local and Remote Notification Programming Guide"
+  # https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW1
+  ##
   class ProviderToken
     ALGORITHM = 'ES256'.freeze
 
+    ##
+    # Create a new token
+    #
+    # key_id: An alphanumeric string obtained from the developer portal.
+    # team_id: The team id for your developer account.  Obtained from the developer portal.
+    # secret: The content of the Authentication Token key file obtained from the developer portal.
+    ##
     def initialize(key_id:, team_id:, secret:)
       @key_id  = key_id
       @team_id = team_id

data/lib/lorkhan/response.rb

@@ -1,9 +1,13 @@
 require 'json'
 
 module Lorkhan
+  ##
+  # A wrapper around the HTTP/2 response from Apple
+  ##
   class Response
     attr_reader :headers, :body
 
+    # This class should never be instantiated directly.
     def initialize(raw)
       @headers = raw.headers
       @body    = JSON.parse(raw.body)
@@ -11,14 +15,23 @@ module Lorkhan
       @body = nil
     end
 
+    ##
+    # Convenience method to check if the status is 200
+    ##
     def ok?
       status == 200
     end
 
+    ##
+    # Get the HTTP status
+    ##
     def status
       headers[':status'].to_i
     end
 
+    ##
+    # Get the APNS id for the notification
+    ##
     def apns_id
       headers['apns-id']
     end

data/lib/lorkhan/version.rb

@@ -1,3 +1,3 @@
 module Lorkhan
-  VERSION = '0.0.4'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/lorkhan.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version               = Lorkhan::VERSION
   spec.licenses              = ['MIT']
   spec.authors               = ['Skylar Schipper']
-  spec.email                 = ['skylar@pco.bz']
+  spec.email                 = ['me@skylarsch.com']
   spec.summary               = 'APNS HTTP/2 Client'
-  spec.homepage              = 'http://github.com/ministrycentered/lorkhan'
+  spec.homepage              = 'http://github.com/skylarsch/lorkhan'
   spec.required_ruby_version = '>=2.3.0'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lorkhan
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Skylar Schipper
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-20 00:00:00.000000000 Z
+date: 2017-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http2
@@ -116,16 +116,16 @@ dependencies:
         version: '0'
 description: 
 email:
-- skylar@pco.bz
+- me@skylarsch.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - bin/console
@@ -144,7 +144,7 @@ files:
 - lib/lorkhan/response.rb
 - lib/lorkhan/version.rb
 - lorkhan.gemspec
-homepage: http://github.com/ministrycentered/lorkhan
+homepage: http://github.com/skylarsch/lorkhan
 licenses:
 - MIT
 metadata: {}
@@ -164,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: APNS HTTP/2 Client

data/.gitignore

@@ -1,3 +0,0 @@
-*.gem
-Gemfile.lock
-.DS_Store