pubnub 3.5.14 → 3.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 660d6dd29b63df106cf2a7719c29e274283ba7a9
-  data.tar.gz: 3141ecfc359a73510595e510726dba69a22e672f
+  metadata.gz: 7e82b13dec635b2feff43fb58315417272f47423
+  data.tar.gz: 441556a04bd5f8700c72b753c61d1264e2938d28
 SHA512:
-  metadata.gz: 2494f66751ab071e70b5b8904ca1b0e747f5053bdfa6c2f98879a6c688a8ab10dfadadf6f37c14bc9c2772189dc12f7fdad2ce79669a20e9781cad0e7b444f16
-  data.tar.gz: 3efc6edf1da10df62a38c24b40392806e4f9e4dda7dea7190191a00543a1bb0f1cbe5800c8e2101b6be7565173bf0399ae5a38e90da7827ffeefe356c43ec316
+  metadata.gz: a2c7681498fcb0da999db79d21d512b055a81452f5b0a3dc0b0ff9598c7c721f51715ab0958843ec0c5869a69dbafc57ec6397d9fc9d5437d3dc87ac3eeb3873
+  data.tar.gz: 5d8e97d9be45638f8b00f6f0226eb66877e1594ff63d8ee5a4becc8adfa46b0395c55b7068d44fe13f57a60fecabd4c7bebe92bfcc201583e07c1882cbcc3952

data/3.5_to_3.6_upgrade_notes.md

@@ -0,0 +1,148 @@
+
+#### WhereNow
+```ruby
+envelope = pubnub.where_now(uuid: :some_uuid, http_sync: true)
+
+# Returns array with single envelope with:
+# @message that holds message from server
+# @parsed_response that holds parsed response form server
+# @payload extracted payload from server response
+# @response that holds unparsed response from server (String)
+# @service that holds service name
+
+# So getting back to example, we will get:
+#[#<Pubnub::Envelope:0x007f9141c24e88
+#  .../cut/...
+#  @message="OK",
+#  @parsed_response={"status"=>200, "message"=>"OK", "payload"=>{"channels"=>[]}, "service"=>"Presence"},
+#  @payload={"channels"=>[]},
+#  @response="{\"status\": 200, \"message\": \"OK\", \"payload\": {\"channels\": []}, \"service\": \"Presence\"}",
+#  @service="Presence",
+#  .../cut/...
+#]
+#
+# Old one envelope held just parsed_response as @message and @response_message
+#
+
+```
+
+#### Leave
+```ruby
+envelope = pubnub.leave(channel: :some_channel, http_sync: true)
+
+# Returns array with single envelope with:
+# @message that holds message from server
+# @parsed_response that holds parsed response form server
+# @response that holds unparsed response from server (String)
+# @service that holds service name
+
+# So getting back to example, we will get:
+#[#<Pubnub::Envelope:0x007fa3850184e0
+#  .../cut/...
+#  @message="OK",
+#  @parsed_response={"status"=>200, "action"=>"leave", "message"=>"OK", "service"=>"Presence"},
+#  @response="{\"status\": 200, \"action\": \"leave\", \"message\": \"OK\", \"service\": \"Presence\"}",
+#  @service="Presence",
+#  .../cut/...
+#]
+#
+# Old one envelope held just parsed_response as @message and @response_message
+#
+
+```
+
+#### State
+```ruby
+envelope = pubnub.state(channel: :some_channel, uuid: :some_uuid, http_sync: true)
+
+# Returns array with single envelope with:
+# @channel that holds channel name
+# @message that holds message from server
+# @parsed_response that holds parsed response form server
+# @payload extracted payload from server response
+# @response that holds unparsed response from server (String)
+# @service that holds service name
+#
+# So getting back to example, we will get:
+#[#<Pubnub::Envelope:0x007fa38542e098
+#  .../cut/...
+#  @channel="some_channel",
+#  @message="OK",
+#  @parsed_response={"status"=>200, "uuid"=>"some_uuid", "service"=>"Presence", "message"=>"OK", "payload"=>{"one"=>1}, "channel"=>"some_channel"},
+#  @payload={"one"=>1},
+#  @response="{\"status\": 200, \"uuid\": \"some_uuid\", \"service\": \"Presence\", \"message\": \"OK\", \"payload\": {\"one\": 1}, \"channel\": \"some_channel\"}",
+#  @service="Presence",
+#  @channel="some_channel",
+#  .../cut/...
+#]
+#
+# Old one envelope held just @payload and @channel
+#
+```
+#### PAM operations
+
+##### Grant
+```ruby
+envelope = pubnub.grant(channel: :some_channel, read: 1, write: 1, http_sync: true)
+
+# Returns array with single envelope with:
+# @message that holds message from server
+# @parsed_response that holds parsed response form server
+# @payload extracted payload from server response
+# @response that holds unparsed response from server (String)
+# @service that holds service name
+#
+# So getting back to example, we will get:
+#[#<Pubnub::Envelope:0x007fa381a4f9f8
+#  .../cut/...
+#  @message="Success",
+#  @parsed_response=
+#   {"status"=>200,
+#    "service"=>"Access Manager",
+#    "message"=>"Success",
+#    "payload"=>{"channels"=>{"some_channel"=>{"r"=>1, "w"=>1}}, "subscribe_key"=>"sub-c", "ttl"=>1440, "level"=>"channel"}},
+#  @payload={"channels"=>{"some_channel"=>{"r"=>1, "w"=>1}}, "subscribe_key"=>"sub-c", "ttl"=>1440, "level"=>"channel"},
+#  @response=
+#   "{\"status\":200,\"service\":\"Access Manager\",\"message\":\"Success\",\"payload\":{\"channels\":{\"some_channel\":{\"r\":1,\"w\":1}},\"subscribe_key\":\"sub-c\",\"ttl\":1440,\"level\":\"channel\"}}",
+#  @service="Access Manager",
+#  .../cut/...
+#]
+#
+# Old one envelope held just @payload, @channel and parsed_response as @message
+#
+```
+
+##### Audit
+```ruby
+envelope = pubnub.grant(channel: :some_channel, http_sync: true)
+
+# Returns array with single envelope with:
+# @message that holds message from server
+# @parsed_response that holds parsed response form server
+# @payload extracted payload from server response
+# @response that holds unparsed response from server (String)
+# @service that holds service name
+#
+# So getting back to example, we will get:
+#[#<Pubnub::Envelope:0x007fa38517d740
+#  .../cut/...
+#  @message="Success",
+#  @parsed_response=
+#   {"status"=>200,
+#    "service"=>"Access Manager",
+#    "message"=>"Success",
+#    "payload"=>{"channels"=>{"some_channel"=>{"r"=>1, "w"=>1, "ttl"=>1435}}, "subscribe_key"=>"sub-c", "level"=>"channel"}},
+#  @payload={"channels"=>{"some_channel"=>{"r"=>1, "w"=>1, "ttl"=>1435}}, "subscribe_key"=>"sub-c", "level"=>"channel"},
+#  @response=
+#   "{\"status\":200,\"service\":\"Access Manager\",\"message\":\"Success\",\"payload\":{\"channels\":{\"some_channel\":{\"r\":1,\"w\":1,\"ttl\":1435}},\"subscribe_key\":\"sub-c\",\"level\":\"channel\"}}",
+#  @response_message=nil,
+#  @service="Access Manager",
+#  .../cut/...
+#]
+#
+# Old one envelope held just @payload as parsed_response as @message and @channel
+#
+```
+##### Revoke
+
+Same as Grant.

data/{CHANGELOG → CHANGELOG.txt}

@@ -1,3 +1,18 @@
+3.6.7 Release
+. Envelopes formatting changes
+
+3.6.3 Release
+. Fixed issues with PAM where grant/revoke/audit may not use the correct auth key (when explicitly provided)
+
+3.6.2 Release
+. Added state functionality
+
+3.6.1 Release
+. Added where_now event
+
+3.6.0 Release
+. Exposed HTTP/S Proxy Support
+
 3.5.12 - d1054d
 . Fixed connect callback (error_callback was assigned due to typo)
 . Fixed EOFError

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    pubnub (3.5.14)
-      eventmachine
-      json
-      net-http-persistent
+    pubnub (3.6.7)
+      eventmachine (~> 1.0)
+      json (~> 1.8)
+      net-http-persistent (~> 2.9)
 
 GEM
   remote: https://rubygems.org/
@@ -44,6 +44,7 @@ PLATFORMS
 
 DEPENDENCIES
   awesome_print
+  bundler (~> 1.6)
   pry
   pubnub!
   rr

data/LICENSE.txt

@@ -0,0 +1,28 @@
+PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
+Copyright (c) 2013-2014 PubNub Inc.
+http://www.pubnub.com/
+http://www.pubnub.com/terms
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
+Copyright (c) 2013-2014 PubNub Inc.
+http://www.pubnub.com/
+http://www.pubnub.com/terms

data/README.md

@@ -1,26 +1,39 @@
 # Please direct all Support Questions and Concerns to Support@PubNub.com
 
+## PubNub Gem version 3.6.7
+
 ##### YOU MUST HAVE A PUBNUB ACCOUNT TO USE THE API.
 ##### http://www.pubnub.com/account
 
-## PubNub Gem version 3.5.14
-
 www.pubnub.com - PubNub Real-time Push Service in the Cloud.
 
+
 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.5.x
+
+We've made the response format compatible across all operations. This may break existing parsing of whereNow, leave, state, and PAM responses. So if you are monitoring these operation responses, please be sure to modify your code accordingly.
+
+Examples of affected operations can be found [here](3.5_to_3.6_upgrade_notes.md).
+
 ### Upgrading from PubNub 3.3.x and Earlier
-PubNub 3.5.14 is NOT compatible with earlier than 3.4 versions of Pubnub Ruby Client.
+PubNub 3.6.7 is NOT compatible with earlier than 3.4 versions of Pubnub Ruby Client.
 
-### Upgrading from PubNub 3.4
-PubNub 3.5.14 is compatible with 3.4 version.
+### Upgrading from PubNub 3.4 and higher versions
+PubNub 3.6.7 is compatible with 3.4 version.
+
+## Important Notice about Blocking vs Non-Blocking Calls
+
+#### Asynchronous vs Synchronous Requests
+Every operation is by default asyncronous. Asynchronous operations will not block your main thread and will be fired within a new thread.
+
+This can cause issues under certain situations, depending on your implementation. To work around this, you can force an operation to run syncronously (block) via the :http_sync option:
 
-#### Asynchronous vs Synchronous Responses
-Every event you will fire could be fired asynchronous or synchonous just by passing 
 ```ruby
-:http_sync
+:http_sync => true
 ```
-set to true to that event. Asynchronous events will not block your main thread and will be fired withing new thread.
+
+Unless otherwise specified, this option is default implied false (all calls by default will be async).
 
 #### Message Handling: callback, block, return
 Results are provided via block, callback, and return, depending on how you structure the call. 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!).
@@ -126,7 +139,6 @@ envelopes.each do |envelope|
 end
 ```
 
-
 #### 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:
 
@@ -142,7 +154,7 @@ The callback (or block) will receive the message(s) in the form of an envelope h
 
 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:
+Internally, the block or callback iterates over the response array, similar to:
 
 ```ruby
 envelopes.each do |envelope|
@@ -150,7 +162,7 @@ envelopes.each do |envelope|
 end
 ```
 
-In a given callback cycle, the **envelope** will be the currently iterated envelopes item of the response.
+In a given callback cycle, the **envelope** will be the current element of the response array.
 
 ### Simple Usage Examples
 
@@ -194,6 +206,40 @@ pubnub.subscribe(
 )
 ```
 
+#### Leave
+Unsubscribes from given channel and fires leave event. You need to be subscribed (only async counts) to channel that you want to leave
+
+```ruby
+pubnub.subscribe(
+    :channel  => :hello_world,
+    :callback => @my_callback
+)
+
+pubnub.leave(
+    :channel => :hello_world,
+    :callback => @my_callback
+)
+```
+
+If you want to force leave channel that you're not subscribed to, you can pass :force option to event
+
+```ruby
+# Wrong
+pubnub.leave(
+    :channel => :not_subbed_channel,
+    :callback => @my_callback
+)
+# We'll get error:
+Pubnub::ArgumentError: You cannot leave channel that is not subscribed
+
+# Good
+p.leave(
+    :channel => :force_leave,
+    :force => true,
+    :callback => @my_callback
+)
+```
+
 #### History
 Retrieve previously published messages (requires activation via admin.pubnub.com)
 Optional start, end, and reverse option usage can be found in the tests.
@@ -226,9 +272,19 @@ pubnub.here_now(
 )
 ```
 
+#### WhereNow
+See where is client with specific uuid
+
+```ruby
+p.where_now(
+    :uuid => :my_friend,
+    :callback => @my_callback
+)
+```
+
 #### UUID
 
-Session-UUID is automatic, so you will probably not end up ever using this. But if you need a UUID...
+UUID is set in the initializer. A unique one is created, unless you specify one explicitly. To retrieve the current UUID:
 
 ```ruby
 pubnub.uuid
@@ -246,12 +302,31 @@ 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.
+Developers can grant/revoke/audit fine-grained permissions for their real-time apps and data at various levels.
 
 Envelopes returned by PAM events have additional :service and :payload keys.
 
 #### PAM Usage Examples
 
+When you issue a PAM operation, you can pass the `presence` key, the 'channel' key, or both. 
+
+```ruby
+# Will grant :r and :w permissions to demo-pnpres channel
+pubnub.grant(:presence => :demo) do |envelope|
+  puts envelope.message
+end
+
+# Will grant :r and :w permissions to demo channel
+pubnub.grant(:channel => :demo) do |envelope|
+  puts envelope.message
+end
+
+# Will grant :r and :w permissions to demo and demo-pnpres channels
+pubnub.grant(:presence => :demo, :channel => :demo) do |envelope|
+  puts envelope.message
+end
+```
+
 ##### Audit
 Audits auths for given parameters
 
@@ -279,7 +354,7 @@ end
 ```
 
 ##### Revoke
-Revokes right to read and write
+Revokes right to read and write. Same as granting r:0 w:0.
 
 ```ruby
 pubnub.revoke(:channel => :forbidden) do |envelope|
@@ -291,7 +366,6 @@ pubnub.grant(:channel => :forbidden, :auth_key => :godzilla) do |envelope|
 end
 ```
 
-
 ### Advanced Usage Examples
 
 ##### Init
@@ -313,10 +387,14 @@ pubnub = Pubnub.new(
 )
 ```
 
+###### Custom logger
+You can pass your custom logger as :logger key while creating new Pubnub instance. Logger invocations has set progname 'Pubnub'.
+
 ##### Publish
 ```ruby
 # Message could be any object that have .to_json method
-# You do not need to jsonify message before sending
+# 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,
@@ -379,10 +457,23 @@ pubnub.history(
 ```
 History envelope also contains .history_start and .history_end values
 
+##### Paged History
+
+Paginate through your history. You can pass `:channel`, `:page`, `:limit`, `:callback`, `:http_sync`, `:start` and `:end` options, all of them works like in history event.
+
+```ruby
+pubnub.paged_history(
+  :channel   => :actions,
+  :limit     => 10,
+  :page      => 3,
+  :http_sync => true
+)
+```
+
 ##### Presence
 Presence works exactly the same way as subscribe, it just adds '-pnpres' to channel name.
 ```ruby
-pubnub.subscribe(
+pubnub.presence(
   :channel => :mars
 ) do |envelope|
   show_in_roster(envelope.uuid)
@@ -399,10 +490,43 @@ pubnub.here_now(
   puts envelope.msg['occupancy']
 end
 ```
+
+You can also give no specific channel. Then you'll get global HereNow event response which holds all channels.
+
+```ruby
+pubnub.here_now { |envelope| puts envelope.msg['channels'] }
+```
+
+
+##### Heartbeat
+
+Heartbeat (expressed in seconds) is used to signal to the server that the client is still online. If the client disconnects without a leave event, others observing presence on the channel will not notice that this client has left the channel until a maximum of heartbeat interval seconds.
+
+You normally will never need to touch this value, unless your Ruby client resides on a poor or mobile connection.
+
+```ruby
+pubnub = Pubnub.new(:subscribe_key => 'demo', :heartbeat => 60)
+```
+
+Update it via heartbeat= and set_heartbeat()
+```ruby
+pubnub.heartbeat = 120
+pubnub.set_heartbeat 240
+```
+
+Read it via heartbeat and get_heartbeat()
+```ruby
+pubnub.heartbeat
+pubnub.get_heartbeat
+```
+
 #### 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)
 
+PAM actions could take :presence option, that will grant/revoke/audit permissions on given presence channel.
+:presence option can be used along with :channel.
+
 ##### Audit
 ```ruby
 pubnub.audit(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
@@ -419,7 +543,7 @@ pubnub.grant(:channel => 'hidden_system', :read => true, :write => false, :auth_
 ```
 
 ##### Revoke
-Works like grant but revokes all previously given privilages
+Revoke is equal to grant with w false, read false
 ```ruby
 # Channel level
 pubnub.revoke(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
@@ -428,6 +552,27 @@ pubnub.revoke(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
 pubnub.revoke(:channel => 'hidden_system', :auth_key => :lemon){ |envelope| puts envelope.msg }
 ```
 
+### State
+State is stored on the server for subscribed uuid, you can pass state in few ways and you can get it from server.
+
+#### Setting state
+```ruby
+# You can set state in a few ways
+# Using subscribe
+pubnub.subscribe(:channel => 'my_channel', :state => {:my_channel => {:key => :value}}){ |e| puts e.msg }
+# Be aware that state have to be hash of hashes where keys are subscribed channel names
+
+# Using event #set_state
+pubnub.set_state(:state => {:key => :value}, :channel => :my_channel, :http_sync => true)
+
+```
+
+#### Getting state
+```ruby
+# All you need to know is just uuid and channel
+pubnub.state(:uuid => 'uuid_client_that_i_am_searching_for', :http_sync => true)
+```
+
 ### Other
 
 Advanced usage examples can be found also in the examples directory.