pubnub 3.5.14 → 3.6.7

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of pubnub might be problematic. Click here for more details.

Files changed (108) hide show
  1. checksums.yaml +4 -4
  2. data/3.5_to_3.6_upgrade_notes.md +148 -0
  3. data/{CHANGELOG → CHANGELOG.txt} +15 -0
  4. data/Gemfile.lock +5 -4
  5. data/LICENSE.txt +28 -0
  6. data/README.md +164 -19
  7. data/Rakefile +1 -6
  8. data/examples/demo_console.rb +370 -329
  9. data/fixtures/vcr_cassettes/grant-multiple-channels-presence-multi-1.yml +44 -0
  10. data/fixtures/vcr_cassettes/grant-multiple-channels-presence-multi-2.yml +44 -0
  11. data/fixtures/vcr_cassettes/grant-multiple-channels-presence-multi-3.yml +44 -0
  12. data/fixtures/vcr_cassettes/grant-multiple-channels-presence-multi-4.yml +44 -0
  13. data/fixtures/vcr_cassettes/grant-multiple-channels-presence.yml +44 -0
  14. data/fixtures/vcr_cassettes/heartbeated-subscribe.yml +1 -1
  15. data/fixtures/vcr_cassettes/here_now-nonssl-block-valid-200-async.yml +1 -1
  16. data/fixtures/vcr_cassettes/here_now-nonssl-block-valid-200-sync.yml +1 -1
  17. data/fixtures/vcr_cassettes/here_now-nonssl-block-valid-non-200-async.yml +1 -1
  18. data/fixtures/vcr_cassettes/here_now-nonssl-block-valid-non-200-sync.yml +1 -1
  19. data/fixtures/vcr_cassettes/here_now-nonssl-parameter-valid-200-async.yml +1 -1
  20. data/fixtures/vcr_cassettes/here_now-nonssl-parameter-valid-200-sync.yml +1 -1
  21. data/fixtures/vcr_cassettes/here_now-nonssl-parameter-valid-non-200-async.yml +1 -1
  22. data/fixtures/vcr_cassettes/here_now-nonssl-parameter-valid-non-200-sync.yml +1 -1
  23. data/fixtures/vcr_cassettes/here_now-ssl-block-valid-200-async.yml +1 -1
  24. data/fixtures/vcr_cassettes/here_now-ssl-block-valid-200-sync.yml +1 -1
  25. data/fixtures/vcr_cassettes/here_now-ssl-block-valid-non-200-async.yml +1 -1
  26. data/fixtures/vcr_cassettes/here_now-ssl-block-valid-non-200-sync.yml +1 -1
  27. data/fixtures/vcr_cassettes/here_now-ssl-parameter-valid-200-async.yml +1 -1
  28. data/fixtures/vcr_cassettes/here_now-ssl-parameter-valid-200-sync.yml +1 -1
  29. data/fixtures/vcr_cassettes/here_now-ssl-parameter-valid-non-200-async.yml +1 -1
  30. data/fixtures/vcr_cassettes/here_now-ssl-parameter-valid-non-200-sync.yml +1 -1
  31. data/fixtures/vcr_cassettes/leave-nonssl-block-valid-200-async.yml +1 -1
  32. data/fixtures/vcr_cassettes/leave-nonssl-block-valid-200-sync.yml +1 -1
  33. data/fixtures/vcr_cassettes/leave-nonssl-block-valid-non-200-async.yml +1 -1
  34. data/fixtures/vcr_cassettes/leave-nonssl-block-valid-non-200-sync.yml +1 -1
  35. data/fixtures/vcr_cassettes/leave-nonssl-parameter-valid-200-async.yml +1 -1
  36. data/fixtures/vcr_cassettes/leave-nonssl-parameter-valid-200-sync.yml +1 -1
  37. data/fixtures/vcr_cassettes/leave-nonssl-parameter-valid-non-200-async.yml +1 -1
  38. data/fixtures/vcr_cassettes/leave-nonssl-parameter-valid-non-200-sync.yml +1 -1
  39. data/fixtures/vcr_cassettes/leave-ssl-block-valid-200-async.yml +1 -1
  40. data/fixtures/vcr_cassettes/leave-ssl-block-valid-200-sync.yml +1 -1
  41. data/fixtures/vcr_cassettes/leave-ssl-block-valid-non-200-async.yml +1 -1
  42. data/fixtures/vcr_cassettes/leave-ssl-block-valid-non-200-sync.yml +1 -1
  43. data/fixtures/vcr_cassettes/leave-ssl-parameter-valid-200-async.yml +1 -1
  44. data/fixtures/vcr_cassettes/leave-ssl-parameter-valid-200-sync.yml +1 -1
  45. data/fixtures/vcr_cassettes/leave-ssl-parameter-valid-non-200-async.yml +1 -1
  46. data/fixtures/vcr_cassettes/leave-ssl-parameter-valid-non-200-sync.yml +1 -1
  47. data/fixtures/vcr_cassettes/state-async-set-state-via-subbedclient-2.yml +140 -0
  48. data/fixtures/vcr_cassettes/state-async-set-state-via-subbedclient.yml +131 -0
  49. data/fixtures/vcr_cassettes/state-async-set-state-via-subscribe.yml +90 -0
  50. data/fixtures/vcr_cassettes/state-set-state-via-client-2.yml +140 -0
  51. data/fixtures/vcr_cassettes/state-set-state-via-client.yml +90 -0
  52. data/fixtures/vcr_cassettes/state-set-state-via-subscribe.yml +90 -0
  53. data/fixtures/vcr_cassettes/where_now-ssl-block-invalid-200-async.yml +49 -0
  54. data/fixtures/vcr_cassettes/where_now-ssl-block-invalid-200-sync.yml +49 -0
  55. data/fixtures/vcr_cassettes/where_now-ssl-block-invalid-non-200-async.yml +49 -0
  56. data/fixtures/vcr_cassettes/where_now-ssl-block-invalid-non-200-sync.yml +49 -0
  57. data/fixtures/vcr_cassettes/where_now-ssl-block-valid-200-async.yml +49 -0
  58. data/fixtures/vcr_cassettes/where_now-ssl-block-valid-200-sync.yml +49 -0
  59. data/fixtures/vcr_cassettes/where_now-ssl-block-valid-non-200-async.yml +49 -0
  60. data/fixtures/vcr_cassettes/where_now-ssl-block-valid-non-200-sync.yml +49 -0
  61. data/fixtures/vcr_cassettes/where_now-ssl-parameter-invalid-200-async.yml +49 -0
  62. data/fixtures/vcr_cassettes/where_now-ssl-parameter-invalid-200-sync.yml +49 -0
  63. data/fixtures/vcr_cassettes/where_now-ssl-parameter-invalid-non-200-async.yml +49 -0
  64. data/fixtures/vcr_cassettes/where_now-ssl-parameter-invalid-non-200-sync.yml +49 -0
  65. data/fixtures/vcr_cassettes/where_now-ssl-parameter-valid-200-async.yml +49 -0
  66. data/fixtures/vcr_cassettes/where_now-ssl-parameter-valid-200-sync.yml +49 -0
  67. data/fixtures/vcr_cassettes/where_now-ssl-parameter-valid-non-200-async.yml +49 -0
  68. data/fixtures/vcr_cassettes/where_now-ssl-parameter-valid-non-200-sync.yml +49 -0
  69. data/lib/pubnub.rb +1 -2
  70. data/lib/pubnub/client.rb +97 -21
  71. data/lib/pubnub/configuration.rb +1 -1
  72. data/lib/pubnub/envelope.rb +3 -2
  73. data/lib/pubnub/event.rb +9 -5
  74. data/lib/pubnub/events/audit.rb +1 -1
  75. data/lib/pubnub/events/grant.rb +1 -1
  76. data/lib/pubnub/events/heartbeat.rb +7 -3
  77. data/lib/pubnub/events/here_now.rb +7 -4
  78. data/lib/pubnub/events/history.rb +1 -1
  79. data/lib/pubnub/events/leave.rb +10 -4
  80. data/lib/pubnub/events/presence.rb +1 -1
  81. data/lib/pubnub/events/publish.rb +6 -2
  82. data/lib/pubnub/events/revoke.rb +1 -1
  83. data/lib/pubnub/events/set_state.rb +77 -0
  84. data/lib/pubnub/events/state.rb +63 -0
  85. data/lib/pubnub/events/subscribe.rb +7 -0
  86. data/lib/pubnub/events/where_now.rb +55 -0
  87. data/lib/pubnub/pam.rb +10 -16
  88. data/lib/pubnub/version.rb +2 -2
  89. data/pubnub.gemspec +21 -19
  90. data/spec/lib/channel_presence_concat_pam_spec.rb +94 -0
  91. data/spec/lib/client_spec.rb +3 -4
  92. data/spec/lib/heartbeat_spec.rb +16 -16
  93. data/spec/lib/integration/global_here_now_dpc_spec.rb +10 -10
  94. data/spec/lib/integration/global_here_now_spec.rb +8 -8
  95. data/spec/lib/integration/here_now_dpc_spec.rb +24 -24
  96. data/spec/lib/integration/here_now_spec.rb +24 -24
  97. data/spec/lib/integration/leave_dpc_spec.rb +24 -25
  98. data/spec/lib/integration/leave_spec.rb +24 -24
  99. data/spec/lib/integration/publish_spec.rb +5 -0
  100. data/spec/lib/integration/state_spec.rb +84 -0
  101. data/spec/lib/integration/where_now_spec.rb +312 -0
  102. metadata +108 -26
  103. data/LICENSE +0 -27
  104. data/VERSION +0 -1
  105. data/examples/demo_console_new.rb +0 -286
  106. data/fixtures/vcr_cassettes/heartbeat-non200.yml +0 -667
  107. data/spec/tools/pam-test-generator.rb +0 -367
  108. data/spec/tools/test-generator.rb +0 -310
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 660d6dd29b63df106cf2a7719c29e274283ba7a9
4
- data.tar.gz: 3141ecfc359a73510595e510726dba69a22e672f
3
+ metadata.gz: 7e82b13dec635b2feff43fb58315417272f47423
4
+ data.tar.gz: 441556a04bd5f8700c72b753c61d1264e2938d28
5
5
  SHA512:
6
- metadata.gz: 2494f66751ab071e70b5b8904ca1b0e747f5053bdfa6c2f98879a6c688a8ab10dfadadf6f37c14bc9c2772189dc12f7fdad2ce79669a20e9781cad0e7b444f16
7
- data.tar.gz: 3efc6edf1da10df62a38c24b40392806e4f9e4dda7dea7190191a00543a1bb0f1cbe5800c8e2101b6be7565173bf0399ae5a38e90da7827ffeefe356c43ec316
6
+ metadata.gz: a2c7681498fcb0da999db79d21d512b055a81452f5b0a3dc0b0ff9598c7c721f51715ab0958843ec0c5869a69dbafc57ec6397d9fc9d5437d3dc87ac3eeb3873
7
+ data.tar.gz: 5d8e97d9be45638f8b00f6f0226eb66877e1594ff63d8ee5a4becc8adfa46b0395c55b7068d44fe13f57a60fecabd4c7bebe92bfcc201583e07c1882cbcc3952
@@ -0,0 +1,148 @@
1
+
2
+ #### WhereNow
3
+ ```ruby
4
+ envelope = pubnub.where_now(uuid: :some_uuid, http_sync: true)
5
+
6
+ # Returns array with single envelope with:
7
+ # @message that holds message from server
8
+ # @parsed_response that holds parsed response form server
9
+ # @payload extracted payload from server response
10
+ # @response that holds unparsed response from server (String)
11
+ # @service that holds service name
12
+
13
+ # So getting back to example, we will get:
14
+ #[#<Pubnub::Envelope:0x007f9141c24e88
15
+ # .../cut/...
16
+ # @message="OK",
17
+ # @parsed_response={"status"=>200, "message"=>"OK", "payload"=>{"channels"=>[]}, "service"=>"Presence"},
18
+ # @payload={"channels"=>[]},
19
+ # @response="{\"status\": 200, \"message\": \"OK\", \"payload\": {\"channels\": []}, \"service\": \"Presence\"}",
20
+ # @service="Presence",
21
+ # .../cut/...
22
+ #]
23
+ #
24
+ # Old one envelope held just parsed_response as @message and @response_message
25
+ #
26
+
27
+ ```
28
+
29
+ #### Leave
30
+ ```ruby
31
+ envelope = pubnub.leave(channel: :some_channel, http_sync: true)
32
+
33
+ # Returns array with single envelope with:
34
+ # @message that holds message from server
35
+ # @parsed_response that holds parsed response form server
36
+ # @response that holds unparsed response from server (String)
37
+ # @service that holds service name
38
+
39
+ # So getting back to example, we will get:
40
+ #[#<Pubnub::Envelope:0x007fa3850184e0
41
+ # .../cut/...
42
+ # @message="OK",
43
+ # @parsed_response={"status"=>200, "action"=>"leave", "message"=>"OK", "service"=>"Presence"},
44
+ # @response="{\"status\": 200, \"action\": \"leave\", \"message\": \"OK\", \"service\": \"Presence\"}",
45
+ # @service="Presence",
46
+ # .../cut/...
47
+ #]
48
+ #
49
+ # Old one envelope held just parsed_response as @message and @response_message
50
+ #
51
+
52
+ ```
53
+
54
+ #### State
55
+ ```ruby
56
+ envelope = pubnub.state(channel: :some_channel, uuid: :some_uuid, http_sync: true)
57
+
58
+ # Returns array with single envelope with:
59
+ # @channel that holds channel name
60
+ # @message that holds message from server
61
+ # @parsed_response that holds parsed response form server
62
+ # @payload extracted payload from server response
63
+ # @response that holds unparsed response from server (String)
64
+ # @service that holds service name
65
+ #
66
+ # So getting back to example, we will get:
67
+ #[#<Pubnub::Envelope:0x007fa38542e098
68
+ # .../cut/...
69
+ # @channel="some_channel",
70
+ # @message="OK",
71
+ # @parsed_response={"status"=>200, "uuid"=>"some_uuid", "service"=>"Presence", "message"=>"OK", "payload"=>{"one"=>1}, "channel"=>"some_channel"},
72
+ # @payload={"one"=>1},
73
+ # @response="{\"status\": 200, \"uuid\": \"some_uuid\", \"service\": \"Presence\", \"message\": \"OK\", \"payload\": {\"one\": 1}, \"channel\": \"some_channel\"}",
74
+ # @service="Presence",
75
+ # @channel="some_channel",
76
+ # .../cut/...
77
+ #]
78
+ #
79
+ # Old one envelope held just @payload and @channel
80
+ #
81
+ ```
82
+ #### PAM operations
83
+
84
+ ##### Grant
85
+ ```ruby
86
+ envelope = pubnub.grant(channel: :some_channel, read: 1, write: 1, http_sync: true)
87
+
88
+ # Returns array with single envelope with:
89
+ # @message that holds message from server
90
+ # @parsed_response that holds parsed response form server
91
+ # @payload extracted payload from server response
92
+ # @response that holds unparsed response from server (String)
93
+ # @service that holds service name
94
+ #
95
+ # So getting back to example, we will get:
96
+ #[#<Pubnub::Envelope:0x007fa381a4f9f8
97
+ # .../cut/...
98
+ # @message="Success",
99
+ # @parsed_response=
100
+ # {"status"=>200,
101
+ # "service"=>"Access Manager",
102
+ # "message"=>"Success",
103
+ # "payload"=>{"channels"=>{"some_channel"=>{"r"=>1, "w"=>1}}, "subscribe_key"=>"sub-c", "ttl"=>1440, "level"=>"channel"}},
104
+ # @payload={"channels"=>{"some_channel"=>{"r"=>1, "w"=>1}}, "subscribe_key"=>"sub-c", "ttl"=>1440, "level"=>"channel"},
105
+ # @response=
106
+ # "{\"status\":200,\"service\":\"Access Manager\",\"message\":\"Success\",\"payload\":{\"channels\":{\"some_channel\":{\"r\":1,\"w\":1}},\"subscribe_key\":\"sub-c\",\"ttl\":1440,\"level\":\"channel\"}}",
107
+ # @service="Access Manager",
108
+ # .../cut/...
109
+ #]
110
+ #
111
+ # Old one envelope held just @payload, @channel and parsed_response as @message
112
+ #
113
+ ```
114
+
115
+ ##### Audit
116
+ ```ruby
117
+ envelope = pubnub.grant(channel: :some_channel, http_sync: true)
118
+
119
+ # Returns array with single envelope with:
120
+ # @message that holds message from server
121
+ # @parsed_response that holds parsed response form server
122
+ # @payload extracted payload from server response
123
+ # @response that holds unparsed response from server (String)
124
+ # @service that holds service name
125
+ #
126
+ # So getting back to example, we will get:
127
+ #[#<Pubnub::Envelope:0x007fa38517d740
128
+ # .../cut/...
129
+ # @message="Success",
130
+ # @parsed_response=
131
+ # {"status"=>200,
132
+ # "service"=>"Access Manager",
133
+ # "message"=>"Success",
134
+ # "payload"=>{"channels"=>{"some_channel"=>{"r"=>1, "w"=>1, "ttl"=>1435}}, "subscribe_key"=>"sub-c", "level"=>"channel"}},
135
+ # @payload={"channels"=>{"some_channel"=>{"r"=>1, "w"=>1, "ttl"=>1435}}, "subscribe_key"=>"sub-c", "level"=>"channel"},
136
+ # @response=
137
+ # "{\"status\":200,\"service\":\"Access Manager\",\"message\":\"Success\",\"payload\":{\"channels\":{\"some_channel\":{\"r\":1,\"w\":1,\"ttl\":1435}},\"subscribe_key\":\"sub-c\",\"level\":\"channel\"}}",
138
+ # @response_message=nil,
139
+ # @service="Access Manager",
140
+ # .../cut/...
141
+ #]
142
+ #
143
+ # Old one envelope held just @payload as parsed_response as @message and @channel
144
+ #
145
+ ```
146
+ ##### Revoke
147
+
148
+ Same as Grant.
@@ -1,3 +1,18 @@
1
+ 3.6.7 Release
2
+ . Envelopes formatting changes
3
+
4
+ 3.6.3 Release
5
+ . Fixed issues with PAM where grant/revoke/audit may not use the correct auth key (when explicitly provided)
6
+
7
+ 3.6.2 Release
8
+ . Added state functionality
9
+
10
+ 3.6.1 Release
11
+ . Added where_now event
12
+
13
+ 3.6.0 Release
14
+ . Exposed HTTP/S Proxy Support
15
+
1
16
  3.5.12 - d1054d
2
17
  . Fixed connect callback (error_callback was assigned due to typo)
3
18
  . Fixed EOFError
data/Gemfile.lock CHANGED
@@ -1,10 +1,10 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- pubnub (3.5.14)
5
- eventmachine
6
- json
7
- net-http-persistent
4
+ pubnub (3.6.7)
5
+ eventmachine (~> 1.0)
6
+ json (~> 1.8)
7
+ net-http-persistent (~> 2.9)
8
8
 
9
9
  GEM
10
10
  remote: https://rubygems.org/
@@ -44,6 +44,7 @@ PLATFORMS
44
44
 
45
45
  DEPENDENCIES
46
46
  awesome_print
47
+ bundler (~> 1.6)
47
48
  pry
48
49
  pubnub!
49
50
  rr
data/LICENSE.txt ADDED
@@ -0,0 +1,28 @@
1
+ PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
2
+ Copyright (c) 2013-2014 PubNub Inc.
3
+ http://www.pubnub.com/
4
+ http://www.pubnub.com/terms
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining
7
+ a copy of this software and associated documentation files (the
8
+ "Software"), to deal in the Software without restriction, including
9
+ without limitation the rights to use, copy, modify, merge, publish,
10
+ distribute, sublicense, and/or sell copies of the Software, and to
11
+ permit persons to whom the Software is furnished to do so, subject to
12
+ the following conditions:
13
+
14
+ The above copyright notice and this permission notice shall be
15
+ included in all copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24
+
25
+ PubNub Real-time Cloud-Hosted Push API and Push Notification Client Frameworks
26
+ Copyright (c) 2013-2014 PubNub Inc.
27
+ http://www.pubnub.com/
28
+ http://www.pubnub.com/terms
data/README.md CHANGED
@@ -1,26 +1,39 @@
1
1
  # Please direct all Support Questions and Concerns to Support@PubNub.com
2
2
 
3
+ ## PubNub Gem version 3.6.7
4
+
3
5
  ##### YOU MUST HAVE A PUBNUB ACCOUNT TO USE THE API.
4
6
  ##### http://www.pubnub.com/account
5
7
 
6
- ## PubNub Gem version 3.5.14
7
-
8
8
  www.pubnub.com - PubNub Real-time Push Service in the Cloud.
9
9
 
10
+
10
11
  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.
11
12
 
13
+ ### Upgrading from PubNub 3.5.x
14
+
15
+ 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.
16
+
17
+ Examples of affected operations can be found [here](3.5_to_3.6_upgrade_notes.md).
18
+
12
19
  ### Upgrading from PubNub 3.3.x and Earlier
13
- PubNub 3.5.14 is NOT compatible with earlier than 3.4 versions of Pubnub Ruby Client.
20
+ PubNub 3.6.7 is NOT compatible with earlier than 3.4 versions of Pubnub Ruby Client.
14
21
 
15
- ### Upgrading from PubNub 3.4
16
- PubNub 3.5.14 is compatible with 3.4 version.
22
+ ### Upgrading from PubNub 3.4 and higher versions
23
+ PubNub 3.6.7 is compatible with 3.4 version.
24
+
25
+ ## Important Notice about Blocking vs Non-Blocking Calls
26
+
27
+ #### Asynchronous vs Synchronous Requests
28
+ Every operation is by default asyncronous. Asynchronous operations will not block your main thread and will be fired within a new thread.
29
+
30
+ 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:
17
31
 
18
- #### Asynchronous vs Synchronous Responses
19
- Every event you will fire could be fired asynchronous or synchonous just by passing
20
32
  ```ruby
21
- :http_sync
33
+ :http_sync => true
22
34
  ```
23
- set to true to that event. Asynchronous events will not block your main thread and will be fired withing new thread.
35
+
36
+ Unless otherwise specified, this option is default implied false (all calls by default will be async).
24
37
 
25
38
  #### Message Handling: callback, block, return
26
39
  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|
126
139
  end
127
140
  ```
128
141
 
129
-
130
142
  #### The Envelope Object
131
143
  The callback (or block) will receive the message(s) in the form of an envelope hash. An envelope will contain the following keys:
132
144
 
@@ -142,7 +154,7 @@ The callback (or block) will receive the message(s) in the form of an envelope h
142
154
 
143
155
  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.
144
156
 
145
- Internally, the block or callback is iterates over the response array, similar to:
157
+ Internally, the block or callback iterates over the response array, similar to:
146
158
 
147
159
  ```ruby
148
160
  envelopes.each do |envelope|
@@ -150,7 +162,7 @@ envelopes.each do |envelope|
150
162
  end
151
163
  ```
152
164
 
153
- In a given callback cycle, the **envelope** will be the currently iterated envelopes item of the response.
165
+ In a given callback cycle, the **envelope** will be the current element of the response array.
154
166
 
155
167
  ### Simple Usage Examples
156
168
 
@@ -194,6 +206,40 @@ pubnub.subscribe(
194
206
  )
195
207
  ```
196
208
 
209
+ #### Leave
210
+ Unsubscribes from given channel and fires leave event. You need to be subscribed (only async counts) to channel that you want to leave
211
+
212
+ ```ruby
213
+ pubnub.subscribe(
214
+ :channel => :hello_world,
215
+ :callback => @my_callback
216
+ )
217
+
218
+ pubnub.leave(
219
+ :channel => :hello_world,
220
+ :callback => @my_callback
221
+ )
222
+ ```
223
+
224
+ If you want to force leave channel that you're not subscribed to, you can pass :force option to event
225
+
226
+ ```ruby
227
+ # Wrong
228
+ pubnub.leave(
229
+ :channel => :not_subbed_channel,
230
+ :callback => @my_callback
231
+ )
232
+ # We'll get error:
233
+ Pubnub::ArgumentError: You cannot leave channel that is not subscribed
234
+
235
+ # Good
236
+ p.leave(
237
+ :channel => :force_leave,
238
+ :force => true,
239
+ :callback => @my_callback
240
+ )
241
+ ```
242
+
197
243
  #### History
198
244
  Retrieve previously published messages (requires activation via admin.pubnub.com)
199
245
  Optional start, end, and reverse option usage can be found in the tests.
@@ -226,9 +272,19 @@ pubnub.here_now(
226
272
  )
227
273
  ```
228
274
 
275
+ #### WhereNow
276
+ See where is client with specific uuid
277
+
278
+ ```ruby
279
+ p.where_now(
280
+ :uuid => :my_friend,
281
+ :callback => @my_callback
282
+ )
283
+ ```
284
+
229
285
  #### UUID
230
286
 
231
- Session-UUID is automatic, so you will probably not end up ever using this. But if you need a UUID...
287
+ UUID is set in the initializer. A unique one is created, unless you specify one explicitly. To retrieve the current UUID:
232
288
 
233
289
  ```ruby
234
290
  pubnub.uuid
@@ -246,12 +302,31 @@ pubnub.time("callback" => @my_callback)
246
302
 
247
303
  ### PAM
248
304
 
249
- 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.
305
+ Developers can grant/revoke/audit fine-grained permissions for their real-time apps and data at various levels.
250
306
 
251
307
  Envelopes returned by PAM events have additional :service and :payload keys.
252
308
 
253
309
  #### PAM Usage Examples
254
310
 
311
+ When you issue a PAM operation, you can pass the `presence` key, the 'channel' key, or both.
312
+
313
+ ```ruby
314
+ # Will grant :r and :w permissions to demo-pnpres channel
315
+ pubnub.grant(:presence => :demo) do |envelope|
316
+ puts envelope.message
317
+ end
318
+
319
+ # Will grant :r and :w permissions to demo channel
320
+ pubnub.grant(:channel => :demo) do |envelope|
321
+ puts envelope.message
322
+ end
323
+
324
+ # Will grant :r and :w permissions to demo and demo-pnpres channels
325
+ pubnub.grant(:presence => :demo, :channel => :demo) do |envelope|
326
+ puts envelope.message
327
+ end
328
+ ```
329
+
255
330
  ##### Audit
256
331
  Audits auths for given parameters
257
332
 
@@ -279,7 +354,7 @@ end
279
354
  ```
280
355
 
281
356
  ##### Revoke
282
- Revokes right to read and write
357
+ Revokes right to read and write. Same as granting r:0 w:0.
283
358
 
284
359
  ```ruby
285
360
  pubnub.revoke(:channel => :forbidden) do |envelope|
@@ -291,7 +366,6 @@ pubnub.grant(:channel => :forbidden, :auth_key => :godzilla) do |envelope|
291
366
  end
292
367
  ```
293
368
 
294
-
295
369
  ### Advanced Usage Examples
296
370
 
297
371
  ##### Init
@@ -313,10 +387,14 @@ pubnub = Pubnub.new(
313
387
  )
314
388
  ```
315
389
 
390
+ ###### Custom logger
391
+ You can pass your custom logger as :logger key while creating new Pubnub instance. Logger invocations has set progname 'Pubnub'.
392
+
316
393
  ##### Publish
317
394
  ```ruby
318
395
  # Message could be any object that have .to_json method
319
- # You do not need to jsonify message before sending
396
+ # You do not need to jsonify message before sending!
397
+
320
398
  # This time publish event will block main thread until callback will finish as we set :http_sync to true
321
399
  pubnub.publish(
322
400
  :messsage => message,
@@ -379,10 +457,23 @@ pubnub.history(
379
457
  ```
380
458
  History envelope also contains .history_start and .history_end values
381
459
 
460
+ ##### Paged History
461
+
462
+ 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.
463
+
464
+ ```ruby
465
+ pubnub.paged_history(
466
+ :channel => :actions,
467
+ :limit => 10,
468
+ :page => 3,
469
+ :http_sync => true
470
+ )
471
+ ```
472
+
382
473
  ##### Presence
383
474
  Presence works exactly the same way as subscribe, it just adds '-pnpres' to channel name.
384
475
  ```ruby
385
- pubnub.subscribe(
476
+ pubnub.presence(
386
477
  :channel => :mars
387
478
  ) do |envelope|
388
479
  show_in_roster(envelope.uuid)
@@ -399,10 +490,43 @@ pubnub.here_now(
399
490
  puts envelope.msg['occupancy']
400
491
  end
401
492
  ```
493
+
494
+ You can also give no specific channel. Then you'll get global HereNow event response which holds all channels.
495
+
496
+ ```ruby
497
+ pubnub.here_now { |envelope| puts envelope.msg['channels'] }
498
+ ```
499
+
500
+
501
+ ##### Heartbeat
502
+
503
+ 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.
504
+
505
+ You normally will never need to touch this value, unless your Ruby client resides on a poor or mobile connection.
506
+
507
+ ```ruby
508
+ pubnub = Pubnub.new(:subscribe_key => 'demo', :heartbeat => 60)
509
+ ```
510
+
511
+ Update it via heartbeat= and set_heartbeat()
512
+ ```ruby
513
+ pubnub.heartbeat = 120
514
+ pubnub.set_heartbeat 240
515
+ ```
516
+
517
+ Read it via heartbeat and get_heartbeat()
518
+ ```ruby
519
+ pubnub.heartbeat
520
+ pubnub.get_heartbeat
521
+ ```
522
+
402
523
  #### Pam
403
524
  PAM allows you to grant read and write access basing on channels and auth_keys.
404
525
  Every pam event requires :secret_key (Remember! You should set it while initializing pubnub)
405
526
 
527
+ PAM actions could take :presence option, that will grant/revoke/audit permissions on given presence channel.
528
+ :presence option can be used along with :channel.
529
+
406
530
  ##### Audit
407
531
  ```ruby
408
532
  pubnub.audit(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
@@ -419,7 +543,7 @@ pubnub.grant(:channel => 'hidden_system', :read => true, :write => false, :auth_
419
543
  ```
420
544
 
421
545
  ##### Revoke
422
- Works like grant but revokes all previously given privilages
546
+ Revoke is equal to grant with w false, read false
423
547
  ```ruby
424
548
  # Channel level
425
549
  pubnub.revoke(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
@@ -428,6 +552,27 @@ pubnub.revoke(:channel => 'hidden_system'){ |envelope| puts envelope.msg }
428
552
  pubnub.revoke(:channel => 'hidden_system', :auth_key => :lemon){ |envelope| puts envelope.msg }
429
553
  ```
430
554
 
555
+ ### State
556
+ State is stored on the server for subscribed uuid, you can pass state in few ways and you can get it from server.
557
+
558
+ #### Setting state
559
+ ```ruby
560
+ # You can set state in a few ways
561
+ # Using subscribe
562
+ pubnub.subscribe(:channel => 'my_channel', :state => {:my_channel => {:key => :value}}){ |e| puts e.msg }
563
+ # Be aware that state have to be hash of hashes where keys are subscribed channel names
564
+
565
+ # Using event #set_state
566
+ pubnub.set_state(:state => {:key => :value}, :channel => :my_channel, :http_sync => true)
567
+
568
+ ```
569
+
570
+ #### Getting state
571
+ ```ruby
572
+ # All you need to know is just uuid and channel
573
+ pubnub.state(:uuid => 'uuid_client_that_i_am_searching_for', :http_sync => true)
574
+ ```
575
+
431
576
  ### Other
432
577
 
433
578
  Advanced usage examples can be found also in the examples directory.