mwotton-apnd 0.1.8

data/README.markdown

@@ -0,0 +1,193 @@
+# APND
+
+APND (Apple Push Notification Daemon) is a ruby library to send Apple Push
+Notifications to iPhones.
+
+Apple recommends application developers create one connection to their
+upstream push notification server, rather than creating one per notification.
+
+APND acts as an intermediary between your application and Apple (see **APND
+Daemon** below). Your application's notifications are queued to APND, which
+are then sent to Apple over a single connection.
+
+Within ruby applications, `APND::Notification` can be used to send
+notifications to a running APND instance (see **APND Notification** below) or
+directly to Apple. The command line can be used to send single notifications
+for testing purposes (see **APND Client** below).
+
+
+## General Usage
+
+### APND Daemon
+
+APND receives push notifications from your application and relays them to
+Apple over a single connection as explained above. The `apnd` command line
+utility is used to start APND.
+
+    Usage:
+      apnd daemon [OPTIONS] --apple-cert </path/to/cert>
+
+    Required Arguments:
+            --apple-cert      [PATH]     PATH to APN certificate from Apple
+
+    Optional Arguments:
+            --apple-host      [HOST]     Connect to Apple at HOST (default is gateway.sandbox.push.apple.com)
+            --apple-port      [PORT]     Connect to Apple on PORT (default is 2195)
+            --apple-cert-pass [PASSWORD] PASSWORD for APN certificate from Apple
+            --daemon-port     [PORT]     Run APND on PORT (default is 22195)
+            --daemon-bind     [ADDRESS]  Bind APND to ADDRESS (default is 0.0.0.0)
+            --daemon-log-file [PATH]     PATH to APND log file (default is /var/log/apnd.log)
+            --daemon-timer    [SECONDS]  Set APND queue refresh time to SECONDS (default is 30)
+            --foreground                 Run APND in foreground without daemonizing
+
+    Help:
+            --help                       Show this message
+
+
+### APND Client
+
+APND includes a command line client which can be used to send notifications to
+a running APND instance. It is only recommended to send notifications via
+`apnd push` for testing purposes.
+
+    Usage:
+      apnd push [OPTIONS] --token <token>
+
+    Required Arguments:
+            --token  [TOKEN]             Set Notification's iPhone token to TOKEN
+
+    Optional Arguments:
+            --alert  [MESSAGE]           Set Notification's alert to MESSAGE
+            --sound  [SOUND]             Set Notification's sound to SOUND
+            --badge  [NUMBER]            Set Notification's badge number to NUMBER
+            --custom [JSON]              Set Notification's custom data to JSON
+            --host   [HOST]              Send Notification to HOST, usually the one running APND (default is 'localhost')
+            --port   [PORT]              Send Notification on PORT (default is 22195)
+
+    Help:
+            --help                       Show this message
+
+
+### APND Notification
+
+The `APND::Notification` class can be used within your application to send
+push notifications to APND.
+
+    require 'apnd'
+
+    # Set the host/port APND is running on
+    # (not needed if you're using localhost:22195)
+    # Put this in config/initializers/apnd.rb for Rails
+    APND::Notification.upstream_host = 'localhost'
+    APND::Notification.upstream_port = 22195
+
+
+    # Initialize some notifications
+    notification1 = APND::Notification.new(
+      :alert  => 'Alert!',
+      :token  => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
+      :badge  => 1
+    )
+
+    notification2 = APND::Notification.new(
+      :alert  => 'Red Alert!',
+      :token  => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
+      :badge  => 99
+    )
+
+
+    # Send multiple notifications at once to avoid overhead in
+    # opening/closing the upstream socket connection each time
+    #
+    # *IMPORTANT!* Use sock.puts as it appends a new line. If you don't,
+    # you'll only receive the first notification.
+
+    APND::Notification.open_upstream_socket do |sock|
+      sock.puts(notification1.to_bytes)
+      sock.puts(notification2.to_bytes)
+    end
+
+
+    # Send a notification to the upstream socket immediately
+    notification3 = APND::Notification.create(
+      :alert  => 'Alert!',
+      :token  => 'fe15a27d5df3c34778defb1f4f3880265cc52c0c047682223be59fb68500a9a2',
+      :badge  => 0
+    )
+
+
+### APND Feedback
+
+Apple Push Notification Service keeps a log when you attempt to deliver
+a notification to a device that has removed your application. A Feedback
+Service is provided which applications should periodically check to remove
+from their databases.
+
+The `APND::Feedback` class can be used within your application to retrieve
+a list of device tokens that you are sending notifications to but have
+removed your application.
+
+    APND::Feedback.upstream_host = 'feedback.push.apple.com'
+    APND::Feedback.upstream_port = 2196
+
+    # Block form
+    APND::Feedback.find_stale_devices do |token, removed_at|
+      device = YourApp::Device.find_by_token(token)
+      unless device.registered_at > removed_at
+        device.push_enabled = 0
+        device.save
+      end
+    end
+
+    # Array form
+    stale = APND::Feedback.find_stale_devices
+    stale.each do |(token, removed_at)|
+      device = YourApp::Device.find_by_token(token)
+      unless device.registered_at > removed_at
+        device.push_enabled = 0
+        device.save
+      end
+    end
+
+
+## Prerequisites
+
+You must have a valid Apple Push Notification Certificate for your iPhone
+application. Obtain your APN certificate from the iPhone Provisioning Portal
+at [developer.apple.com](http://developer.apple.com/).
+
+
+## Requirements
+
+* [EventMachine](http://github.com/eventmachine/eventmachine)
+* [Daemons](http://github.com/ghazel/daemons)
+* [JSON](http://github.com/flori/json)
+
+Ruby must be compiled with OpenSSL support.
+
+Tests use [Shoulda](http://github.com/thoughtbot/shoulda), and optionally
+[TURN](https://github.com/TwP/turn).
+
+
+## Installation
+
+RubyGems:
+
+    gem install apnd
+
+Git:
+
+    git clone git://github.com/itspriddle/apnd.git
+
+
+## Credit
+
+APND is based on [apnserver](http://github.com/bpoweski/apnserver) and
+[apn_on_rails](http://github.com/PRX/apn_on_rails). Either worked just how I
+wanted, so I rolled my own using theirs as starting points. If APND doesn't
+suit you, check them out instead.
+
+
+## Copyright
+
+Copyright (c) 2010-2011 Joshua Priddle. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,31 @@
+$:.unshift 'lib'
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << '.'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/apnd.rb -I ./lib"
+end
+
+require 'sdoc_helpers'
+desc "Push a new version to Gemcutter"
+task :publish do
+  require 'apnd/version'
+
+  ver = APND::Version
+
+  sh "gem build apnd.gemspec"
+  sh "gem push mwotton-apnd-#{ver}.gem"
+  sh "git tag -a -m 'APND v#{ver}' v#{ver}"
+  sh "git push origin v#{ver}"
+  sh "git push origin master"
+  sh "git clean -fd"
+  sh "rake pages"
+end

data/bin/apnd

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+ARGV << '--help' if ARGV.empty?
+
+if $0 == __FILE__
+  require 'rubygems'
+  $:.unshift File.join(File.dirname(__FILE__), *%w[.. lib])
+end
+
+require 'apnd'
+
+command = ARGV.shift
+
+case command
+when 'daemon'
+  APND::CLI.daemon(ARGV)
+when 'push'
+  APND::CLI.push(ARGV)
+when '--version', '-v'
+  puts "APND v#{APND::Version}"
+else
+  puts "Error: Invalid command" unless %w(-h --help).include?(command)
+  puts <<-HELP
+Usage: apnd COMMAND [ARGS]
+
+Command list:
+        daemon                       Start the APND Daemon
+        push                         Send a single push notification (for development use only)
+
+Help:
+        --version                    Show version
+        --help                       Show this message
+
+  HELP
+end

data/lib/apnd.rb

@@ -0,0 +1,33 @@
+require 'json'
+
+module APND
+  autoload :Version,      'apnd/version'
+  autoload :CLI,          'apnd/cli'
+  autoload :Errors,       'apnd/errors'
+  autoload :Settings,     'apnd/settings'
+  autoload :Daemon,       'apnd/daemon'
+  autoload :Notification, 'apnd/notification'
+  autoload :Feedback,     'apnd/feedback'
+
+  #
+  # Returns APND::Settings
+  #
+  def self.settings
+    @@settings ||= Settings.new
+  end
+
+  #
+  # Yields APND::Settings
+  #
+  def self.configure
+    yield settings
+  end
+
+  #
+  # Write message to stdout with date
+  #
+  def self.logger(message) #:nodoc:
+    puts "[%s] %s" % [Time.now.strftime("%Y-%m-%d %H:%M:%S"), message]
+  end
+
+end

data/lib/apnd/#notification.rb#

@@ -0,0 +1,193 @@
+require 'socket'
+
+module APND
+  #
+  # APND::Notification is the base class for creating new push notifications.
+  #
+  class Notification
+
+    class << self
+      #
+      # The host notifications will be written to, usually one
+      # running APND
+      #
+      attr_accessor :upstream_host
+
+      #
+      # The port to connect to upstream_host on
+      #
+      attr_accessor :upstream_port
+    end
+
+    #
+    # Set upstream host/port to default values
+    #
+    self.upstream_host = APND.settings.notification.host
+    self.upstream_port = APND.settings.notification.port.to_i
+
+    #
+    # The device token from Apple
+    #
+    attr_accessor :token
+
+    #
+    # The alert to send
+    #
+    attr_accessor :alert
+
+    #
+    # The badge number to set
+    #
+    attr_accessor :badge
+
+    #
+    # The sound to play
+    #
+    attr_accessor :sound
+
+    #
+    # Custom data to send
+    #
+    attr_accessor :custom
+
+    #
+    # Creates a new socket to upstream_host:upstream_port
+    #
+    def self.upstream_socket
+      @socket = TCPSocket.new(upstream_host, upstream_port)
+    end
+
+    #
+    # Opens a new socket upstream, yields it, and closes it
+    #
+    def self.open_upstream_socket(&block)
+      socket = upstream_socket
+      yield socket
+      socket.close
+    end
+
+    #
+    # Create a new APN
+    #
+    def self.create(params = {}, push = true)
+      notification = Notification.new(params)
+      notification.push! if push
+      notification
+    end
+
+    #
+    # Try to create a new Notification from raw data
+    # Used by Daemon::Protocol to validate incoming data
+    #
+    def self.valid?(data)
+      parse(data)
+    rescue => e
+      puts e.inspect
+      puts e.backtrace
+      false
+    end
+
+
+    def self.parse_from_handle(handle)
+
+    end
+    #
+    # Parse raw data into a new Notification
+    #
+    def self.parse(data)
+      buffer = data.dup
+      notification = Notification.new
+
+      header = buffer.slice!(0, 3).unpack('ccc')
+
+      if header[0] != 0
+        raise APND::Errors::InvalidNotificationHeader.new(header)
+      end
+
+      notification.token = buffer.slice!(0, 32).unpack('H*').first
+
+      json_length = buffer.slice!(0, 2).unpack('CC')
+
+      json = buffer.slice!(0, json_length.last)
+
+      payload = JSON.parse(json)
+
+      %w[alert sound badge].each do |key|
+        if payload['aps'] && payload['aps'][key]
+          notification.send("#{key}=", payload['aps'][key])
+        end
+      end
+
+      payload.delete('aps')
+
+      unless payload.empty?
+        notification.custom = payload
+      end
+
+      notification
+    end
+
+    #
+    # Create a new Notification object from a hash
+    #
+    def initialize(params = {})
+      @token  = params[:token]
+      @alert  = params[:alert]
+      @badge  = params[:badge]
+      @sound  = params[:sound]
+      @custom = params[:custom]
+    end
+
+    #
+    # Token in hex format
+    #
+    def hex_token
+      [self.token.delete(' ')].pack('H*')
+    end
+
+    #
+    # aps hash sent to Apple
+    #
+    def aps
+      aps = {}
+      aps['alert'] = self.alert      if self.alert
+      aps['badge'] = self.badge.to_i if self.badge
+      aps['sound'] = self.sound      if self.sound
+
+      output = { 'aps' => aps }
+
+      if self.custom
+        self.custom.each do |key, value|
+          output[key.to_s] = value
+        end
+      end
+      output
+    end
+
+    #
+    # Pushes notification to upstream host:port (default is localhost:22195)
+    #
+    def push!
+      self.class.open_upstream_socket { |sock| sock.write(to_bytes) }
+    end
+
+    #
+    # Returns the Notification's aps hash as json
+    #
+    def aps_json
+      return @aps_json if @aps_json
+      json = aps.to_json
+      raise APND::Errors::InvalidPayload.new(json) if json.size > 256
+      @aps_json = json
+    end
+
+    #
+    # Format the notification as a string for submission
+    # to Apple
+    #
+    def to_bytes
+      @bytes ||= "\0\0 %s\0%s%s" % [hex_token, aps_json.length.chr, aps_json]
+    end
+
+  end
+end