pubnub 3.4.1 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d36c99c090137e15da39515489f5487e3d07c028
-  data.tar.gz: a49d8b178508761e055c4105665e265fded9f1f7
+  metadata.gz: 823024dba735d78188dfb40014ad66a746ec1633
+  data.tar.gz: ee58ab64b1c20f62864edeaa36f76d5ba046b624
 SHA512:
-  metadata.gz: 9c25b97f6ee76a24ecb39a314f0499051d650ebf6f61a692291c15213190bca473a2cd3d994c9e551844593c791b292edd499c4f634b4ef4dca21ca4f7dadf20
-  data.tar.gz: ed0f70d2bdf78eb0091df1d61de33cdea41d46c2782d7a2c8e512f8829691dfbc990abb5a8edc43927948d3b8db0ba86fb23d32147e07a05c70102f8565b751f
+  metadata.gz: 28a9736826cd12c73c302bd94afcec9b22fda0785b849cb793a4aceb3cf1890e68bb604467748ae0110a2ad02035499e6bab25378cf3d2bee72229bd75c5cbb4
+  data.tar.gz: 016fc32654f807868280218ab34370054a75492b37f154a69f8c8900b41effa0b6f856c294548bf7334f77ab098cfc9830c9e383dd99d07dbe06544fd2b7e937

data/.gitignore

@@ -5,3 +5,4 @@ pubnub-*.gem
 .idea/
 log/*
 *.log
+examples/test.rb

data/CHANGELOG

@@ -1,3 +1,5 @@
-3.4.0
-- Async vs Sync
-- Block, Return, and Callback options
+3-17-14 - 3.5.1 Release
+. PAM Support!
+. extensive refactor, removed a lot of dependencies, such as Faraday for HTTP_SYNC mode
+. connection callback can be set per subscribe call
+. fixed issue where EM could silently fail after some time with Passenger

data/README.md

@@ -1,31 +1,27 @@
 ##### YOU MUST HAVE A PUBNUB ACCOUNT TO USE THE API.
 ##### http://www.pubnub.com/account
 
-## PubNub Gem version 3.4
+## PubNub Gem version 3.5.0
 
-www.pubnub.com - PubNub Real-time Push Service in the Cloud. 
+www.pubnub.com - PubNub Real-time Push Service in the Cloud.
 
-PubNub is a Real-time Network for Mobile App, Web Apps for pushing updates and enabling real-time notifications and even games!
+The PubNub Network is a blazingly fast Global Messaging Service for building real-time web and mobile apps. Thousands of apps and developers rely on PubNub for delivering human-perceptive real-time experiences that scale to millions of users worldwide. PubNub delivers the infrastructure needed to build amazing Mobile, MMO games, social apps, business collaborative solutions, and more.
 
 ### Upgrading from PubNub 3.3.x and Earlier
-PubNub 3.4 is NOT compatible with earlier versions of Pubnub Ruby Client.  If you are upgrading from 3.3.x, the changes you will need to make are minimal.
+PubNub 3.5.0 is NOT compatible with earlier than 3.4 versions of Pubnub Ruby Client.
 
-### New Features of 3.4
-There are a lot of cool features introduced in the 3.4 version of the gem. Notably:
-
-* Ability to carry out requests asynchronously or synchronously
-* Message handling via callback, block, and return
-* Heroku and JRuby Support (JRuby requires calls to be made synchronously)
+### Upgrading from PubNub 3.4
+PubNub 3.5.0 is compatible with 3.4 version.
 
 #### Asynchronous vs Synchronous Responses
-Feedback from prior versions of the gem demonstrated that some users would like to 'fire and forget' PubNub calls. Others wanted to block, and take specific action, based on server response.
-
-In 3.4, you can now have both, even on a per-call basis!
+Every event you will fire could be fired asynchronous ro synchonous just by passing 
+```ruby
+:http_sync
+```
+set to true to that event. Asynchronous events will not block your main thread and will be fired withing new thread.
 
 #### Message Handling: callback, block, return
-Feedback from users of prior versions demonstrated the need for flexibility in how received messages were handled. The general PubNub response pattern dictated that responses be sent to callbacks, however, there was also a non-addressed use case of simply assigning a variable on return.
-
-In 3.4, you can now have both, even on a per-call basis!
+You could pass to every even callback as callback or just by block that will get envelope with message. Callback will be fired for every message that will event get in response. Synchornous events will return array of envelopes (if you passed callback to sychronous event it will be called too!).
 
 ### Code Examples
 
@@ -35,10 +31,10 @@ require 'pubnub'
 ```
 
 #### Init and instantiate a new PubNub instance
-
 ```ruby
-
 # If you wish to override the default logger, create one and pass it in.
+# Default logger writes into pubnub.log file
+
 my_logger = Logger.new(STDOUT)
 
 pubnub = Pubnub.new(
@@ -46,7 +42,7 @@ pubnub = Pubnub.new(
     :publish_key      => 'demo',
     :origin           => origin,
     :error_callback   => lambda { |msg|
-      puts "SOMETHING TERRIBLE HAPPENED HERE: #{msg.inspect}"
+      puts "Error callback says: #{msg.inspect}"
     },
     :connect_callback => lambda { |msg|
       puts "CONNECTED: #{msg.inspect}"
@@ -66,7 +62,7 @@ There are a few different ways to make any given PubNub call. How to do it depen
 
 ##### Asynchronous (non-blocking) calling
 
-If you wish to make asyncronous calls (implemented via EM), you have a few different patterns you can follow:
+If you wish to make asyncronous calls (implemented via EventMachine), you have a few different patterns you can follow:
 
 ```ruby
 # Lets use a callback for the first example...
@@ -76,17 +72,17 @@ cb = lambda { |envelope| puts envelope.message }
 pubnub.publish(:message => msg, :channel => channel, :callback => cb)
 
 # You can also explicitly request async with :http_sync => false
-pubnub.publish(:message => msg, :channel => channel, :callback => cb, :http_sync => true)
+pubnub.publish(:message => msg, :channel => channel, :callback => cb, :http_sync => false)
 
 # Alternatively, you can pass in the callback as a block
 
 pubnub.publish(:message => msg, :channel => channel, &cb)
 
-pubnub.publish(:message => msg, :channel => channel) do |envelope| 
+pubnub.publish(:message => msg, :channel => channel) do |envelope|
     puts envelope.message
     puts envelope.channel
     puts envelope.status_code
-    puts envelope.timetoken 
+    puts envelope.timetoken
 end
 ```
 
@@ -105,14 +101,14 @@ pubnub.publish(:http_sync => true, :message => msg, :channel => channel, &cb)
 
 # Sync (blocking), with assignment via return
 myResponse = pubnub.publish(:http_sync => true, :message => msg, :channel => channel)
-puts "myR: #{myResponse}" 
+puts "myR: #{myResponse.inspect}"
 
 # Sync (blocking), with a block
-pubnub.publish(:http_sync => true, :message => msg, :channel => channel) do |envelope| 
+pubnub.publish(:http_sync => true, :message => msg, :channel => channel) do |envelope|
     puts envelope.message
     puts envelope.channel
     puts envelope.status_code
-    puts envelope.timetoken 
+    puts envelope.timetoken
 end
 ```
 
@@ -122,31 +118,37 @@ When you receive messages asynchronously from PubNub, your block or callback wil
 
 Conceptually, the callback or block is fired once for each message in the raw server response:
 
-```
-foreach (message in response)
-    callbackOrBlock(message)
+```ruby
+envelopes.each do |envelope|
+    callback.call envelope
+end
 ```
 
 
-#### The Envelope Object and Pubnub::Response
+#### The Envelope Object
 The callback (or block) will receive the message(s) in the form of an envelope hash. An envelope will contain the following keys:
 
-* message (aliased as 'msg') -> Holds message
+* message (aliased as 'msg') -> Holds message, if publish, holds published message
+* response_message -> as above, except that if publish holds server response (String "Send")
 * channel -> Holds channel for current message
 * timetoken -> Timetoken of server response
-* status_code -> Server response status code
+* status (aliased as 'status_code') -> Server response status code
 * response -> Whole and unmodified server response
+* first -> true if it's first envelope in single response messages array
+* last -> true if it's last envelope in single response messages array
+* And a bit more, specific to some events, you will find it in description of certain events
 
 Don't confuse the **message** with the **response**. In a given callback cycle, the **response** will always be the same, as its the raw server response. It may consist of one or more messages.
 
 Internally, the block or callback is iterates over the response array, similar to:
 
-```
-foreach (message in response)
-    callbackOrBlock(message)
+```ruby
+envelopes.each do |envelope|
+    callback.call envelope
+end
 ```
 
-In a given callback cycle, the **message** will be the currently iterated message item of the response.
+In a given callback cycle, the **envelope** will be the currently iterated envelopes item of the response.
 
 ### Simple Usage Examples
 
@@ -197,7 +199,7 @@ Optional start, end, and reverse option usage can be found in the tests.
 ```ruby
 pubnub.history(
     :channel  => channel,
-    :count    => 10, 
+    :count    => 10,
     :callback => @my_callback
 )
 ```
@@ -212,7 +214,7 @@ pubnub.presence(
 )
 ```
 
-#### Here_now 
+#### HereNow
 See who is "here now" in a channel at this very moment.
 
 ```ruby
@@ -233,16 +235,200 @@ pubnub.uuid
 If you wish to manually set a custom UUID, pass in a uuid key in the initializer. See "Init and instantiate a new PubNub instance" for an example.
 
 
-#### Time 
+#### Time
 Get the current PubNub time. This is great to use as a "PubNub Ping"
 
 ```ruby
 pubnub.time("callback" => @my_callback)
 ```
 
+### PAM
+
+Developers can grant fine-grained Publish/Subscribe permissions for their real-time apps and data, without hosting authentication services Access control can be granted at various levels.
+
+Envelopes returned by PAM events have additional :service and :payload keys.
+
+#### PAM Usage Examples
+
+##### Audit
+Audits auths for given parameters
+
+```ruby
+pubnub.audit(:channel => :forbidden_for_jim) do |envelope|
+  puts envelope.payload
+end
+
+pubnub.audit(:channel => :forbidden_for_jim, :auth_key => :jim) do |envelope|
+  puts envelope.payload
+end
+```
+
+##### Grant
+Grants auths for given parameters, you can pass :read and :write keys as parameters
+
+```ruby
+pubnub.grant(:channel => :forbidden_to_write, :read => true, :write => false) do |envelope|
+  puts envelope.payload
+end
+
+pubnub.grant(:channel => :forbidden_to_write, :read => true, :write => true, :auth_key => :admin) do |envelope|
+  puts envelope.payload
+end
+```
+
+##### Revoke
+Revokes right to read and write
+
+```ruby
+pubnub.revoke(:channel => :forbidden) do |envelope|
+  puts envelope.payload
+end
+
+pubnub.grant(:channel => :forbidden, :auth_key => :godzilla) do |envelope|
+  puts envelope.payload
+end
+```
+
+
 ### Advanced Usage Examples
 
-Advanced usage examples can be found in the examples directory.
+##### Init
+```ruby
+# Example below shows passing more options for client
+# Pubnub.new returns Pubnub::Client instance
+pubnub = Pubnub.new(
+  :error_callback             => custom_error_callback,
+  :connect_callback           => custom_connect_callback,
+  :ssl                        => true,
+  :uuid                       => 'newton',
+  :port                       => 80,
+  :origin                     => custom_origin,
+  :subscribe_timeout          => 310,
+  :non_subscribe_timeout      => 5,
+  :max_retries                => 10, # max retries if response got invalid json
+  :ttl                        => custom_default_ttl_for_pam,
+  :secret_key                 => 0
+)
+```
+
+##### Publish
+```ruby
+# Message could be any object that have .to_json method
+# You do not need to jsonify message before sending
+# This time publish event will block main thread until callback will finish as we set :http_sync to true
+pubnub.publish(
+  :messsage => message,
+  :channel  => :whatever,
+  :http_sync => true )
+```
+
+##### Subscribe
+```ruby
+# You can pass in :channel or :channels String, Symbol, Array of both, or csv separated with commas, remember, as space is valid channel part, there should not be any spaces between commas (unless you want them)
+# Some example of valid channels:
+# :example_symbol
+# 'example_string'
+# [:one, :two, 'three']
+# [:anything]
+# 'one,two,three'
+
+# Firing sync subscribe could lock your thread even for 5 minutes
+# When there's no traffic on channel server will send timetoken without
+# any messages every ~300s.
+# First sync subscribe will just update your timetoken, you will not get any messages
+# example:
+pubnub.subscribe(:channel => 'alerts', :http_sync => true) # just update timetoken
+pubnub.subscribe(:channel => 'alerts', :http_sync => true) # Will fire request with current timetoken and can possibly get messages
+
+# Async subscribe starts infinity loop in seperate thread (EM.periodic_timer precisely)
+# It will update your timetoken and will fire given callback for every message that it gets
+# example:
+pubnub.subscribe(
+  :channel => 'fight_log'
+) do |envelope|
+  puts envelope.message['attacker']
+  puts envelope.message['defender']
+  puts envelope.message['demage']
+end
+```
+
+##### History
+History returns :count messages from given channel.
+```ruby
+pubnub.history(
+  :channel  => :actions,
+  :count    => 10,
+  :start    => 13942156708212448,
+  :end      => 13942156908212448,
+  :callback => replay
+)
+```
+
+:reverse set to true will traverse the time line in reverse starting with the newest message first. Default is false.
+If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.
+
+```ruby
+pubnub.history(
+  :channel  => :actions,
+  :count    => 10,
+  :reverse  => true,
+  :callback => replay
+)
+```
+History envelope also contains .history_start and .history_end values
+
+##### Presence
+Presence works exactly the same way as subscribe, it just adds '-pnpres' to channel name.
+```ruby
+pubnub.subscribe(
+  :channel => :mars
+) do |envelope|
+  show_in_roster(envelope.uuid)
+end
+```
+
+##### HereNow
+HereNow shows us who is currently subscribing channel and how much clients are online on given channel.
+```ruby
+pubnub.here_now(
+  :channel => :pamam_moon_iv
+) do |envelope|
+  puts envelope.msg['uuids']
+  puts envelope.msg['occupancy']
+end
+```
+#### Pam
+PAM allows you to grant read and write access basing on channels and auth_keys.
+Every pam event requires :secret_key (Remember! You should set it while initializing pubnub)
+
+##### Audit
+```ruby
+pubnub.audit(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
+
+```
+
+##### Grant
+```ruby
+# Channel level
+pubnub.grant(:channel => 'hidden_system', :read => true, :write => false){ |envelope| puts envelope.msg }
+
+# Auth key level
+pubnub.grant(:channel => 'hidden_system', :read => true, :write => false, :auth_key => :lemon){ |envelope| puts envelope.msg }
+```
+
+##### Revoke
+Works like grant but revokes all previously given privilages
+```ruby
+# Channel level
+pubnub.revoke(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
+
+# Auth key level
+pubnub.revoke(:channel => 'hidden_system', :auth_key => :lemon){ |envelope| puts envelope.msg }
+```
+
+### Other
+
+Advanced usage examples can be found also in the examples directory.
 
 #### demo_console
 A demo console app which shows how to use just about every PubNub Ruby call, just about every possible way!
@@ -260,5 +446,45 @@ Sinatra demo.
 Mixing up some async pubs and subs, using blocks and callbacks.
 
 #### serial_publish
-Publish 1000 times with an explicit 0.25s delay between publishes
+Publish 10000 times with an explicit 0.05s delay between publishes
+
+## Comment on Passenger users
+Passenger is orphaning threads and it causes issues with EM which is need to run async pubnub events.
+Below is fix that worked with our tests. You should fire that code from your initializers.
+
+Some other environments could cause similar problems with EM, if you think you're affected, feel free to open issue and we will do our best to help.
+
+```ruby
+module Pubnub
+  # Taken from http://www.hiringthing.com/2011/11/04/eventmachine-with-rails.html
+  # Thanks Joshua!
+  def self.start
+    if defined?(PhusionPassenger)
+      PhusionPassenger.on_event(:starting_worker_process) do |forked|
+        # for passenger, we need to avoid orphaned threads
+
+        $my_logger.debug "=> Starting worker process"
+
+        if forked && EM.reactor_running?
+          $my_logger.debug "=> EventMachine stopped fork"
+          EM.stop
+        end
+        Thread.new {
+          EM.run do
+            $my_logger.debug "=> EventMachine started"
+          end
+        }
+        die_gracefully_on_signal
+      end
+    end
+  end
+
+  def self.die_gracefully_on_signal
+    $my_logger.debug "=> EventMachine stopped die"
+    Signal.trap("INT")  { EM.stop }
+    Signal.trap("TERM") { EM.stop }
+  end
+end
 
+Pubnub.start
+```