lowdown 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fa2be0e57306efb793fb262856aa2a1bea16c03
-  data.tar.gz: 151af85c92ff4c4553244f78c70721bf41cc31a9
+  metadata.gz: 5ce849fce8cd7a90dc303f9f761d88b497c7d80a
+  data.tar.gz: 4c041b547386c1f591ac0a30326666f91f926b09
 SHA512:
-  metadata.gz: c6aab49b75690c5aac492d6d1ffd137bb5b548b2377e7f391e2bb7095b03661a80ba920388e89e24f1f2f24826946b81274e94d12cdf49bf9d737e80db539289
-  data.tar.gz: e0ccfd14e17cbe9b7e96b2401ea493396eab4a0acd72c472b4383dd95c3b20e0aab469ebdba38d663648dd09a26d2cd235ff95cd7d472f026a5e5cd91170ae0e
+  metadata.gz: abab9a4f67830d08411466d48c2ac48bcf6a9d5d4c91239096dcac04e418047ef2965ae7800311aa1e0a75554fc2e02f3b92269301fb0838e9c7d06c91b743e0
+  data.tar.gz: 5c8715d560ab305e3eca365f94f5f2458183dc3972b10608a1f39e7457b6aa9bf2f121b0ee8dd6b2ee2c408c52682470bfcc31a333817f2fcd0a5a9c8e9f89b5

data/.gitignore

@@ -1,5 +1,4 @@
 /.bundle/
-/.yardoc
 /Gemfile.lock
 /_yardoc/
 /coverage/

data/.travis.yml

@@ -1,4 +1,8 @@
 language: ruby
 rvm:
-  - 2.0.0
-before_install: gem install bundler -v 1.11.2
+  - 2.1.0
+  - 2.1
+  - 2.2
+  - 2.3.0
+before_install: gem install bundler
+install: bundle install --without doc

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--markup markdown
+--main README.md

data/Gemfile

@@ -3,3 +3,7 @@ source 'https://rubygems.org'
 #gem 'http-2', :git => 'https://github.com/alloy/http-2.git', :branch => "apns"
 
 gemspec
+
+group :doc do
+  gem 'yard'
+end

data/README.md

@@ -1,10 +1,14 @@
+![](https://raw.githubusercontent.com/alloy/lowdown/master/doc/lowdown.png)
+
 # Lowdown
 
+[![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.
 
 Multiple notifications are multiplexed for efficiency.
 
-NOTE: _It is not yet battle-tested and there is no documentation yet. This will all follow over the next few weeks._
+NOTE: _It is not yet battle-tested. This will all follow over the next few weeks._
 
 ## Installation
 
@@ -24,21 +28,8 @@ Or install it yourself as:
 
 ## Usage
 
-You can use the `lowdown` bin that comes with this gem or in code at its simplest:
-
-```ruby
-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
-```
+You can use the `lowdown` bin that comes with this gem or for code usage see
+[the documentation](http://www.rubydoc.info/gems/lowdown).
 
 ## Contributing
 

data/Rakefile

@@ -1,10 +1,31 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList['test/**/*_test.rb']
+desc "Install all dependencies"
+task :bootstrap do
+  if system('which bundle')
+    sh "bundle install"
+    #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
+  end
 end
 
-task :default => :test
+begin
+  require 'bundler/gem_tasks'
+
+  desc "Generate documentation"
+  task :doc do
+    sh "yard doc"
+  end
+
+  require "rake/testtask"
+  Rake::TestTask.new(:test) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList['test/**/*_test.rb']
+  end
+
+  task :default => :test
+
+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"
+end

data/lib/lowdown.rb

@@ -1,5 +1,26 @@
 require "lowdown/client"
 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.
+#
+# 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
+#
 module Lowdown
 end

data/lib/lowdown/certificate.rb

@@ -1,36 +1,75 @@
 require "openssl"
 
 module Lowdown
-  def self.Certificate(certificate_or_data)
-    if certificate_or_data.is_a?(Certificate)
-      certificate_or_data
-    else
-      Certificate.from_pem_data(certificate_or_data)
-    end
-  end
-
+  # This class is a wrapper around a certificate/key pair that returns values used by Lowdown.
+  #
   class Certificate
-    # http://images.apple.com/certificateauthority/pdf/Apple_WWDR_CPS_v1.13.pdf
-    DEVELOPMENT_ENV_EXTENSION       = "1.2.840.113635.100.6.3.1".freeze
-    PRODUCTION_ENV_EXTENSION        = "1.2.840.113635.100.6.3.2".freeze
-    UNIVERSAL_CERTIFICATE_EXTENSION = "1.2.840.113635.100.6.3.6".freeze
+    # @!group Constructor Summary
+
+    # @param  [Certificate, String] certificate_or_data
+    #         a configured Certificate or PEM data to construct a Certificate from.
+    #
+    # @return [Certificate]
+    #         either the originally passed in Certificate or a new Certificate.
+    #
+    def self.certificate(certificate_or_data)
+      if certificate_or_data.is_a?(Certificate)
+        certificate_or_data
+      else
+        from_pem_data(certificate_or_data)
+      end
+    end
 
+    # A convenience method that initializes a Certificate from PEM data.
+    #
+    # @param  [String] data
+    #         the PEM encoded certificate/key pair data.
+    #
+    # @param  [String] passphrase
+    #         a passphrase required to decrypt the PEM data.
+    #
+    # @return (see Certificate#initialize)
+    #
     def self.from_pem_data(data, passphrase = nil)
       key = OpenSSL::PKey::RSA.new(data, passphrase)
       certificate = OpenSSL::X509::Certificate.new(data)
       new(certificate, key)
     end
 
-    attr_reader :key, :certificate
-
+    # @param  [OpenSSL::X509::Certificate] certificate
+    #         the Apple Push Notification certificate.
+    #
+    # @param  [OpenSSL::PKey::RSA] key
+    #         the private key that belongs to the certificate.
+    #
     def initialize(certificate, key = nil)
       @key, @certificate = key, certificate
     end
 
+    # @!group Instance Attribute Summary
+
+    # @return [OpenSSL::X509::Certificate]
+    #         the Apple Push Notification certificate.
+    #
+    attr_reader :certificate
+
+    # @return [OpenSSL::PKey::RSA, nil]
+    #         the private key that belongs to the certificate.
+    #
+    attr_reader :key
+
+    # @!group Instance Method Summary
+
+    # @return [String]
+    #         the certificate/key pair encoded as PEM data. Only used for testing.
+    #
     def to_pem
       [@key, @certificate].compact.map(&:to_pem).join("\n")
     end
 
+    # @return [OpenSSL::SSL::SSLContext]
+    #         a SSL context, configured with the certificate/key pair, which is used to connect to the APN service.
+    #
     def ssl_context
       @ssl_context ||= OpenSSL::SSL::SSLContext.new.tap do |context|
         context.key = @key
@@ -38,18 +77,34 @@ module Lowdown
       end
     end
 
+    # @return [Boolean]
+    #         whether or not the certificate is a Universal Certificate.
+    #
+    # @see https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/AddingCapabilities/AddingCapabilities.html#//apple_ref/doc/uid/TP40012582-CH26-SW11
+    #
     def universal?
       !extension(UNIVERSAL_CERTIFICATE_EXTENSION).nil?
     end
 
+    # @return [Boolean]
+    #         whether or not the certificate supports the development (sandbox) environment (for development builds).
+    #
     def development?
       !extension(DEVELOPMENT_ENV_EXTENSION).nil?
     end
 
+    # @return [Boolean]
+    #         whether or not the certificate supports the production environment (for Testflight & App Store builds).
+    #
     def production?
       !extension(PRODUCTION_ENV_EXTENSION).nil?
     end
 
+    # @return [Array<String>]
+    #         a list of ‘topics’ that the certificate supports.
+    #
+    # @see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html
+    #
     def topics
       if universal?
         components = extension(UNIVERSAL_CERTIFICATE_EXTENSION).value.split(/0?\.{2,}/)
@@ -59,12 +114,20 @@ module Lowdown
       end
     end
 
+    # @return [String]
+    #         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]
     end
 
     private
 
+    # http://images.apple.com/certificateauthority/pdf/Apple_WWDR_CPS_v1.13.pdf
+    DEVELOPMENT_ENV_EXTENSION       = "1.2.840.113635.100.6.3.1".freeze
+    PRODUCTION_ENV_EXTENSION        = "1.2.840.113635.100.6.3.2".freeze
+    UNIVERSAL_CERTIFICATE_EXTENSION = "1.2.840.113635.100.6.3.6".freeze
+
     def extension(oid)
       @certificate.extensions.find { |ext| ext.oid == oid }
     end

data/lib/lowdown/client.rb

@@ -6,12 +6,36 @@ require "uri"
 require "json"
 
 module Lowdown
+  # The main class to use for interactions with the Apple Push Notification HTTP/2 service.
+  #
   class Client
+    # The details to connect to the development (sandbox) environment version of the APN service.
+    #
     DEVELOPMENT_URI = URI.parse("https://api.development.push.apple.com:443")
+
+    # The details to connect to the production environment version of the APN service.
+    #
     PRODUCTION_URI = URI.parse("https://api.push.apple.com:443")
 
+    # @!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
+    #         a configured Certificate or PEM data to construct a Certificate from.
+    #
+    # @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 = Lowdown.Certificate(certificate_or_data)
+      certificate = Certificate.certificate(certificate_or_data)
       if production
         unless certificate.production?
           raise ArgumentError, "The specified certificate is not usable with the production environment."
@@ -24,21 +48,78 @@ module Lowdown
       client(production ? PRODUCTION_URI : DEVELOPMENT_URI, certificate)
     end
 
+    # Creates a connection that connects to the specified `uri`.
+    #
+    # It then calls {Client.client_with_connection}.
+    #
+    # @param  [URI] uri
+    #         the endpoint details of the service to connect to.
+    #
+    # @param  [Certificate, String] certificate_or_data
+    #         a configured Certificate or PEM data to construct a Certificate from.
+    #
+    # @return (see Client#initialize)
+    #
     def self.client(uri, certificate_or_data)
-      certificate = Lowdown.Certificate(certificate_or_data)
+      certificate = Certificate.certificate(certificate_or_data)
       client_with_connection(Connection.new(uri, certificate.ssl_context), certificate)
     end
 
+    # 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  [Certificate] certificate
+    #         a configured Certificate.
+    #
+    # @return (see Client#initialize)
+    #
     def self.client_with_connection(connection, certificate)
       new(connection, certificate.universal? ? certificate.topics.first : nil)
     end
 
-    attr_reader :connection, :default_topic
-
+    # 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  [String] default_topic
+    #         the ‘topic’ to use if the Certificate is a Universal Certificate and a Notification doesn’t explicitely
+    #         provide one.
+    #
+    # @return [Client]
+    #         a new instance of Client.
+    #
     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.
+    #
+    attr_reader :connection
+
+    # @return [String, nil]
+    #         the ‘topic’ to use if the Certificate is a Universal Certificate and a Notification doesn’t explicitely
+    #         provide one.
+    #
+    attr_reader :default_topic
+
+    # @!group Instance Method Summary
+
+    # Opens the connection to the service. If a block is given the connection is automatically closed.
+    #
+    # @see Connection#open
+    #
+    # @yield  [client]
+    #         yields `self`.
+    #
+    # @return (see Connection#open)
+    #
     def connect
       @connection.open
       if block_given?
@@ -50,14 +131,41 @@ module Lowdown
       end
     end
 
+    # Flushes the connection.
+    #
+    # @see Connection#flush
+    #
+    # @return (see Connection#flush)
+    #
     def flush
       @connection.flush
     end
 
+    # Closes the connection.
+    #
+    # @see Connection#close
+    #
+    # @return (see Connection#close)
+    #
     def close
       @connection.close
     end
 
+    # Verifies the `notification` is valid and sends it to the remote service.
+    #
+    # @see Connection#post
+    #
+    # @param  [Notification] notification
+    #         the notification object whose data to send to the service.
+    #
+    # @yield  (see Connection#post)
+    # @yieldparam (see Connection#post)
+    #
+    # @raise  [ArgumentError]
+    #         raised if the Notification is not {Notification#valid?}.
+    #
+    # @return [void]
+    #
     def send_notification(notification, &callback)
       raise ArgumentError, "Invalid notification: #{notification.inspect}" unless notification.valid?
 

data/lib/lowdown/connection.rb

@@ -6,9 +6,13 @@ require "openssl"
 require "uri"
 require "socket"
 
-# Monkey-patch http-2 gem until this PR is merged: https://github.com/igrigorik/http-2/pull/44
 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
   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
@@ -21,13 +25,35 @@ if HTTP2::VERSION == "0.8.0"
 end
 
 module Lowdown
+  # The class responsible for managing the connection to the Apple Push Notification service.
+  #
+  # It manages both the SSL connection and processing of the HTTP/2 data sent back and forth over that connection.
+  #
   class Connection
-    attr_reader :uri, :ssl_context
-
+    # @param  [URI, String] uri
+    #         the details to connect to the APN service.
+    #
+    # @param  [OpenSSL::SSL::SSLContext] ssl_context
+    #         a SSL context, configured with the certificate/key pair, which is used to connect to the APN service.
+    #
     def initialize(uri, ssl_context)
       @uri, @ssl_context = URI(uri), ssl_context
     end
 
+    # @return [URI]
+    #         the details to connect to the APN service.
+    #
+    attr_reader :uri
+
+    # @return [OpenSSL::SSL::SSLContext]
+    #         a SSL context, configured with the certificate/key pair, which is used to connect to the APN service.
+    #
+    attr_reader :ssl_context
+
+    # Creates a new SSL connection to the service, a HTTP/2 client, and starts off a worker thread.
+    #
+    # @return [void]
+    #
     def open
       @socket = TCPSocket.new(@uri.host, @uri.port)
 
@@ -49,12 +75,19 @@ module Lowdown
       @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?
     end
 
-    # Terminates the worker thread and closes the socket. Finally it peforms one more check for pending jobs dispatched
-    # onto the main thread.
+    # Flushes the connection, terminates the worker thread, and closes the socket. Finally it peforms one more check for
+    # pending jobs dispatched onto the main thread.
+    #
+    # @return [void]
     #
     def close
       flush
@@ -70,6 +103,10 @@ module Lowdown
       @socket = @ssl = @http = @main_queue = @work_queue = @requests = @exceptions = @worker_thread = nil
     end
 
+    # Halts the calling thread until all dispatched requests have been performed.
+    #
+    # @return [void]
+    #
     def flush
       until @work_queue.empty? && @requests.zero?
         @main_queue.drain!
@@ -77,6 +114,25 @@ module Lowdown
       end
     end
 
+    # Sends the provided data as a `POST` request to the service.
+    #
+    # @param  [String] path
+    #         the request path, which should be `/3/device/<device-token>`.
+    #
+    # @param  [Hash] headers
+    #         the additional headers for the request. By default it sends `:method`, `:path`, and `content-length`.
+    #
+    # @param  [String] body
+    #         the (JSON) encoded payload data to send to the service.
+    #
+    # @yield  [response]
+    #         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.
+    #
+    # @return [void]
+    #
     def post(path, headers, body, &callback)
       request('POST', path, headers, body, &callback)
     end

data/lib/lowdown/mock.rb

@@ -3,7 +3,19 @@ require "lowdown/client"
 require "lowdown/response"
 
 module Lowdown
+  # Provides a collection of test helpers.
+  #
+  # This file is not loaded by default.
+  #
   module Mock
+    # Generates a self-signed Universal Certificate.
+    #
+    # @param  [String] app_bundle_id
+    #         the App ID / app Bundle ID to encode into the certificate.
+    #
+    # @return [Array<OpenSSL::X509::Certificate, OpenSSL::PKey::RSA>]
+    #         the self-signed certificate and private key.
+    #
     def self.ssl_certificate_and_key(app_bundle_id)
       key = OpenSSL::PKey::RSA.new(1024)
       name = OpenSSL::X509::Name.parse("/UID=#{app_bundle_id}/CN=Stubbed APNS Certificate: #{app_bundle_id}")
@@ -21,31 +33,68 @@ module Lowdown
       [cert, key]
     end
 
+    # Generates a Certificate configured with a self-signed Universal Certificate.
+    #
+    # @param  (see Mock.ssl_certificate_and_key)
+    #
+    # @return [Certificate]
+    #         a Certificate configured with a self-signed certificate/key pair.
+    #
     def self.certificate(app_bundle_id)
       Certificate.new(*ssl_certificate_and_key(app_bundle_id))
     end
 
+    # Generates a Client with a mock {Connection} and a self-signed Universal Certificate.
+    #
+    # @param  [URI, String] uri
+    #         the details to connect to the APN service.
+    #
+    # @param  [String] app_bundle_id
+    #         the App ID / app Bundle ID to encode into the certificate.
+    #
+    # @return [Client]
+    #         a Client configured with the `uri` and a self-signed certificate that has the `app_bundle_id` encoded.
+    #
     def self.client(uri: nil, app_bundle_id: "com.example.MockApp")
       certificate = certificate(app_bundle_id)
       connection = Connection.new(uri: uri, ssl_context: certificate.ssl_context)
       Client.client_with_connection(connection, certificate)
     end
 
+    # A mock object that can be used instead of a real Connection object.
+    #
     class Connection
+      # Represents a recorded request.
+      #
       Request = Struct.new(:path, :headers, :body, :response)
 
-      # Mock API
-      attr_reader :requests, :responses
+      # @!group Mock API: Instance Attribute Summary
 
-      # Real API
-      attr_reader :uri, :ssl_context
+      # @return [Array<Request>]
+      #         a list of requests that have been made in order.
+      #
+      attr_reader :requests
 
+      # @return [Array<Response>]
+      #         a list of stubbed responses to return in order.
+      #
+      attr_reader :responses
+
+      # @!group Mock API: Instance Method Summary
+
+      # @param (see Lowdown::Connection#initialize)
+      #
       def initialize(uri: nil, ssl_context: nil)
         @uri, @ssl_context = uri, ssl_context
         @responses = []
         @requests = []
       end
 
+      # @param  (see Response#unformatted_id)
+      #
+      # @return [Array<Notification>]
+      #         returns the recorded requests as Notification objects.
+      #
       def requests_as_notifications(unformatted_id_length = nil)
         @requests.map do |request|
           headers = request.headers
@@ -61,20 +110,56 @@ module Lowdown
         end
       end
 
+      # @!group Real API: Instance Attribute Summary
+
+      # @return (see Lowdown::Connection#uri)
+      #
+      attr_reader :uri
+
+      # @return (see Lowdown::Connection#ssl_context)
+      #
+      attr_reader :ssl_context
+
+      # @!group Real API: Instance Method Summary
+
+      # Yields stubbed {#responses} or if none are available defaults to success responses.
+      #
+      # @param (see Lowdown::Connection#post)
+      # @yield (see Lowdown::Connection#post)
+      # @yieldparam (see Lowdown::Connection#post)
+      # @return (see Lowdown::Connection#post)
+      #
       def post(path, headers, body)
         response = @responses.shift || Response.new(":status" => "200", "apns-id" => (headers["apns-id"] || generate_id))
         @requests << Request.new(path, headers, body, response)
         yield response
       end
 
+      # Changes {#open?} to return `true`.
+      #
+      # @return [void]
+      #
       def open
         @open = true
       end
 
+      # Changes {#open?} to return `false`.
+      #
+      # @return [void]
+      #
       def close
         @open = false
       end
 
+      # no-op
+      #
+      # @return [void]
+      #
+      def flush
+      end
+
+      # @return (see Lowdown::Connection#open?)
+      #
       def open?
         !!@open
       end

data/lib/lowdown/notification.rb

@@ -1,19 +1,64 @@
 module Lowdown
-  # For payload documentation see: https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/TheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH107-SW1
+  # A Notification holds the data and metadata about a Remote Notification.
+  #
+  # @see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html#//apple_ref/doc/uid/TP40008194-CH101-SW15
+  # @see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/TheNotificationPayload.html
   #
   class Notification
+    # @!visibility private
     APS_KEYS = %w{ alert badge sound content-available category }.freeze
 
-    attr_accessor :token, :id, :expiration, :priority, :topic, :payload
+    # @return [String]
+    #         a device token.
+    #
+    attr_accessor :token
+
+    # @return [Object, nil]
+    #         a object that uniquely identifies this notification and is coercable to a String.
+    #
+    attr_accessor :id
+
+    # @return [Time, nil]
+    #         the time until which to retry delivery of a notification. By default it is only tried once.
+    #
+    attr_accessor :expiration
+
+    # @return [Integer, nil]
+    #         the priority at which to deliver this notification, which may be `10` or `5` if power consumption should
+    #         be taken into consideration. Defaults to `10.
+    #
+    attr_accessor :priority
+
+    # @return [String, nil]
+    #         the ‘topic’ for this notification.
+    #
+    attr_accessor :topic
+
+    # @return [Hash]
+    #         the data payload for this notification.
+    #
+    attr_accessor :payload
 
+    # @param [Hash] params
+    #        a dictionary of keys described in the Instance Attribute Summary.
+    #
     def initialize(params)
       params.each { |key, value| send("#{key}=", value) }
     end
 
+    # @return [Boolean]
+    #         whether this notification holds enough data and metadata to be sent to the APN service.
+    #
     def valid?
       !!(@token && @payload)
     end
 
+    # Formats the {#id} in the format required by the APN service, which is in groups of 8-4-4-12. It is padded with
+    # leading zeroes.
+    #
+    # @return [String]
+    #         the formatted ID.
+    #
     def formatted_id
       if @id
         padded = @id.to_s.rjust(32, "0")
@@ -21,6 +66,14 @@ module Lowdown
       end
     end
 
+    # Unless the payload contains an `aps` entry, the payload is assumed to be a mix of APN defined attributes and
+    # custom attributes and re-organized according to the specifications.
+    #
+    # @see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/TheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH107-SW1
+    #
+    # @return [Hash]
+    #         the payload organized according to the APN specification.
+    #
     def formatted_payload
       if @payload.has_key?("aps")
         @payload

data/lib/lowdown/response.rb

@@ -1,6 +1,18 @@
 module Lowdown
+  # An object that represents a response from the Apple Push Notification service for a single notification delivery.
+  #
+  # @see https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html
+  #
+  #
+  # @attr   [Hash] headers
+  #         The HTTP response headers from the service.
+  #
+  # @attr   [String] raw_body
+  #         The JSON encoded response body from the service.
+  #
   class Response < Struct.new(:headers, :raw_body)
-    # https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html#//apple_ref/doc/uid/TP40008194-CH101-SW3
+    # The possible HTTP status codes and their associated messages.
+    #
     STATUS_CODES = {
       200 => "Success",
       400 => "Bad request",
@@ -13,44 +25,82 @@ module Lowdown
       503 => "The server is shutting down and unavailable"
     }
 
+    # @return [String]
+    #         either the {Notification#id} or, if none was provided, an ID generated by the service.
+    #
     def id
       headers["apns-id"]
     end
 
-    def unformatted_id(length = nil)
+    # Tries to convert the ID back to the Notification {Notification#id} by removing leading zeroes.
+    #
+    # @param  [Integer] unformatted_id_length
+    #         the expected length of an ID, which ensures that **required** leading zeroes are not removed.
+    #
+    # @return [String]
+    #         the ID that was assigned to the Notification.
+    #
+    def unformatted_id(unformatted_id_length = nil)
       id = self.id.tr('-', '')
-      length ? id[32-length,length] : id.gsub(/\A0*/, '')
+      unformatted_id_length ? id[32-unformatted_id_length,unformatted_id_length] : id.gsub(/\A0*/, '')
     end
 
+    # @return [Integer]
+    #         the HTTP status returned by the service.
+    #
+    # @see Response::STATUS_CODES
+    #
     def status
       headers[":status"].to_i
     end
 
+    # @return [String]
+    #         the message belonging to the {#status} returned by the service.
+    #
+    # @see Response::STATUS_CODES
+    #
     def message
       STATUS_CODES[status]
     end
 
+    # @return [Boolean]
+    #         whether or not the notification has been delivered.
+    #
     def success?
       status == 200
     end
 
+    # @return [Hash, nil]
+    #         the response payload from the service, which is empty in the case of a successful delivery.
+    #
     def body
       JSON.parse(raw_body) if raw_body
     end
 
+    # @return [String, nil]
+    #         the reason for a failed delivery.
+    #
     def failure_reason
       body["reason"] unless success?
     end
 
+    # @return [Boolean]
+    #         whether or not the delivery has failed due to a token no longer being valid.
+    #
     def invalid_token?
       status == 410
     end
 
-    # Only available when using an invalid token.
+    # @return [Time, nil]
+    #         in case of an invalid token, the time at which the service last checked it.
+    #
     def validity_last_checked_at
       Time.at(body["timestamp"].to_i) if invalid_token?
     end
 
+    # @return [String]
+    #         a formatted description of the response.
+    #
     def to_s
       s = "#{status} (#{message})"
       s << ": #{failure_reason}" unless success?
@@ -58,6 +108,9 @@ module Lowdown
       s
     end
 
+    # @return [String]
+    #         a formatted description of the response used for debugging.
+    #
     def inspect
       "#<Lowdown::Connection::Response #{to_s}>"
     end

data/lib/lowdown/threading.rb

@@ -1,26 +1,43 @@
 require "thread"
 
 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
+      # 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
@@ -30,31 +47,56 @@ module Lowdown
       end
     end
 
+    # A simple thread-safe counter.
+    #
     class Counter
+      # @param  [Integer] value
+      #         the initial count.
+      #
       def initialize(value = 0)
         @value = value
         @mutex = Mutex.new
       end
 
+      # @return [Integer]
+      #         the current count.
+      #
       def value
         value = nil
         @mutex.synchronize { value = @value }
         value
       end
 
+      # @return [Boolean]
+      #         whether or not the current count is zero.
+      #
       def zero?
         value.zero?
       end
 
+      # @param  [Integer] value
+      #         the new count.
+      #
+      # @return [Integer]
+      #         the input value.
+      #
       def value=(value)
         @mutex.synchronize { @value = value }
         value
       end
 
+      # Increments the current count.
+      #
+      # @return [void]
+      #
       def increment!
         @mutex.synchronize { @value += 1 }
       end
 
+      # Decrements the current count.
+      #
+      # @return [void]
+      #
       def decrement!
         @mutex.synchronize { @value -= 1 }
       end

data/lib/lowdown/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lowdown
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Eloy Durán
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-05 00:00:00.000000000 Z
+date: 2016-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http-2
@@ -77,11 +77,13 @@ files:
 - ".gitignore"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/lowdown
+- doc/lowdown.png
 - lib/lowdown.rb
 - lib/lowdown/certificate.rb
 - lib/lowdown/client.rb
@@ -117,3 +119,4 @@ signing_key:
 specification_version: 4
 summary: A Ruby client for the HTTP/2 version of the Apple Push Notification Service.
 test_files: []
+has_rdoc: