Expose presence history and snapshot helpers in the Ruby server SDK

The Ruby server SDK now includes presence history and snapshot
helpers so backend callers can access the 4.2.0 presence APIs through
idiomatic client methods and specs.

Constraint: Ruby integrations expect first-class helper methods instead of manual request assembly
Rejected: Force callers onto raw request helpers | unnecessarily low-level API
Confidence: medium
Scope-risk: moderate
Directive: Keep the public Ruby client surface aligned with the documented HTTP endpoints and avoid vendoring runtime deps
Tested: Attempted bundle exec rspec
Not-tested: RSpec suite in this environment could not start because Bundler 4.0.8 is not installed

Author: countradooku

README.md

@@ -200,6 +200,26 @@ user_count = info[:user_count]
 # List channels (optionally filtered)
 result = sockudo.channels(filter_by_prefix: 'presence-')
 
+# Read channel history with newest-first pagination
+page = sockudo.channel_history('my-channel', limit: 50, direction: 'newest_first')
+next_cursor = page[:next_cursor]
+
+# Continue pagination with an opaque cursor
+page_2 = sockudo.channel_history('my-channel', cursor: next_cursor)
+
+# Read presence history for a presence channel
+presence_page = sockudo.channel_presence_history(
+  'presence-my-channel',
+  limit: 50,
+  direction: 'newest_first'
+)
+
+# Reconstruct effective members at a point in time
+snapshot = sockudo.channel_presence_snapshot(
+  'presence-my-channel',
+  at_serial: 4
+)
+
 # Users in a presence channel
 result = sockudo.channel_users('presence-my-channel')
 ```

lib/sockudo.rb

@@ -1,4 +1,4 @@
-autoload 'Logger', 'logger'
+require 'logger'
 require 'securerandom'
 require 'uri'
 require 'forwardable'
@@ -10,6 +10,8 @@
 # Used for configuring API credentials and creating Channel objects
 #
 module Sockudo
+  Signature = Pusher::Signature
+
   # All errors descend from this class so they can be easily rescued
   #
   # @example
@@ -44,7 +46,7 @@ class << self
     def_delegators :default_client, :timeout=, :connect_timeout=, :send_timeout=, :receive_timeout=, :keep_alive_timeout=
 
     def_delegators :default_client, :get, :get_async, :post, :post_async
-    def_delegators :default_client, :channels, :channel_info, :channel_users
+    def_delegators :default_client, :channels, :channel_info, :channel_history, :channel_users
     def_delegators :default_client, :trigger, :trigger_batch, :trigger_async, :trigger_batch_async
     def_delegators :default_client, :authenticate, :webhook, :channel, :[]
     def_delegators :default_client, :notify

lib/sockudo/channel.rb

@@ -98,6 +98,36 @@ def info(attributes = [])
       @client.channel_info(name, :info => attributes.join(','))
     end
 
+    # Request durable history for this channel.
+    #
+    # @param params [Hash] History API query params. Supported keys include:
+    #   :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms
+    # @return [Hash] History page payload for this channel
+    #
+    def history(params = {})
+      @client.channel_history(name, params)
+    end
+
+    # Request presence history for a presence channel.
+    #
+    # @param params [Hash] Presence history API query params. Supported keys include:
+    #   :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms
+    # @return [Hash] Presence history page payload for this channel
+    #
+    def presence_history(params = {})
+      @client.channel_presence_history(name, params)
+    end
+
+    # Request a reconstructed presence snapshot for a presence channel.
+    #
+    # @param params [Hash] Snapshot API query params. Supported keys include:
+    #   :at_time_ms, :at_serial
+    # @return [Hash] Presence snapshot payload for this channel
+    #
+    def presence_snapshot(params = {})
+      @client.channel_presence_snapshot(name, params)
+    end
+
     # Request users for a presence channel
     # Only works on presence channels (see: http://sockudo.com/docs/client_api_guide/client_presence_channels and https://sockudo.com/docs/rest_api)
     #

lib/sockudo/client.rb

@@ -260,6 +260,51 @@ def channel_info(channel_name, params = {})
       get("/channels/#{channel_name}", params)
     end
 
+    # Request durable history for a specific channel
+    #
+    # GET /apps/[id]/channels/[channel_name]/history
+    #
+    # @param channel_name [String] Channel name (max 200 characters)
+    # @param params [Hash] Hash of parameters for the API. Supported keys include:
+    #   :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms
+    #
+    # @return [Hash] See Sockudo history API docs
+    #
+    # @raise [Sockudo::Error] Unsuccessful response - see the error message
+    # @raise [Sockudo::HTTPError] Error raised inside http client. The original error is wrapped in error.original_error
+    #
+    def channel_history(channel_name, params = {})
+      get("/channels/#{channel_name}/history", params)
+    end
+
+    # Request presence history for a specific presence channel
+    #
+    # GET /apps/[id]/channels/[channel_name]/presence/history
+    #
+    # @param channel_name [String] Presence channel name (max 200 characters)
+    # @param params [Hash] Hash of parameters for the API. Supported keys include:
+    #   :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms
+    #
+    # @return [Hash] See Sockudo presence history API docs
+    #
+    def channel_presence_history(channel_name, params = {})
+      get("/channels/#{channel_name}/presence/history", params)
+    end
+
+    # Request a reconstructed presence snapshot for a specific presence channel
+    #
+    # GET /apps/[id]/channels/[channel_name]/presence/history/snapshot
+    #
+    # @param channel_name [String] Presence channel name (max 200 characters)
+    # @param params [Hash] Hash of parameters for the API. Supported keys include:
+    #   :at_time_ms, :at_serial
+    #
+    # @return [Hash] See Sockudo presence snapshot API docs
+    #
+    def channel_presence_snapshot(channel_name, params = {})
+      get("/channels/#{channel_name}/presence/history/snapshot", params)
+    end
+
     # Request info for users of a presence channel
     #
     # GET /apps/[id]/channels/[channel_name]/users

lib/sockudo/request.rb

@@ -103,9 +103,21 @@ def handle_response(status_code, body)
     end
 
     def symbolize_first_level(hash)
-      hash.inject({}) do |result, (key, value)|
-        result[key.to_sym] = value
-        result
+      hash.each_with_object({}) do |(key, value), result|
+        result[key.to_sym] = deep_symbolize(value)
+      end
+    end
+
+    def deep_symbolize(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested_value), result|
+          result[key.to_sym] = deep_symbolize(nested_value)
+        end
+      when Array
+        value.map { |item| deep_symbolize(item) }
+      else
+        value
       end
     end
   end

sockudo.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   s.add_dependency "multi_json", "~> 1.15"
   s.add_dependency 'pusher-signature', "~> 0.1.8"
   s.add_dependency "httpclient", "~> 2.8"
+  s.add_dependency "logger", "~> 1.7"
   s.add_dependency "jruby-openssl" if defined?(JRUBY_VERSION)
 
   s.add_development_dependency "rspec", "~> 3.9"

spec/channel_spec.rb

@@ -93,6 +93,36 @@ def stub_post_to_raise(e)
     end
   end
 
+  describe '#history' do
+    it "should call the Client#channel_history" do
+      expect(@client).to receive(:get)
+                           .with("/channels/mychannel/history", {:limit => 2, :direction => "newest_first"})
+                           .and_return({:items => [{:serial => 2}, {:serial => 1}]})
+      @channel = @client['mychannel']
+      @channel.history(limit: 2, direction: 'newest_first')
+    end
+  end
+
+  describe '#presence_history' do
+    it "should call the Client#channel_presence_history" do
+      expect(@client).to receive(:get)
+                           .with("/channels/presence-mychannel/presence/history", {:limit => 2, :direction => "newest_first"})
+                           .and_return({:items => [{:serial => 2}, {:serial => 1}]})
+      @channel = @client['presence-mychannel']
+      @channel.presence_history(limit: 2, direction: 'newest_first')
+    end
+  end
+
+  describe '#presence_snapshot' do
+    it "should call the Client#channel_presence_snapshot" do
+      expect(@client).to receive(:get)
+                           .with("/channels/presence-mychannel/presence/history/snapshot", {:at_serial => 4})
+                           .and_return({:member_count => 1})
+      @channel = @client['presence-mychannel']
+      @channel.presence_snapshot(at_serial: 4)
+    end
+  end
+
   describe "#authentication_string" do
     def authentication_string(*data)
       lambda { @channel.authentication_string(*data) }

spec/client_spec.rb

@@ -242,8 +242,8 @@
           })
           expect(@client.channels).to eq({
             :channels => {
-              "channel1" => {},
-              "channel2" => {}
+              :channel1 => {},
+              :channel2 => {}
             }
           })
         end
@@ -274,7 +274,89 @@
             })
           })
           expect(@client.channel_users('mychannel')).to eq({
-            :users => [{ 'id' => 1}]
+            :users => [{ :id => 1}]
+          })
+        end
+      end
+
+      describe '#channel_history' do
+        it "should call correct URL and symbolise response" do
+          api_path = %r{/apps/20/channels/mychannel/history}
+          stub_request(:get, api_path).with(
+            query: hash_including(
+              "direction" => "newest_first",
+              "limit" => "2"
+            )
+          ).to_return({
+            :status => 200,
+            :body => MultiJson.encode({
+              'items' => [
+                { 'serial' => 2 },
+                { 'serial' => 1 }
+              ],
+              'has_more' => false
+            })
+          })
+
+          expect(@client.channel_history('mychannel', direction: 'newest_first', limit: 2)).to eq({
+            :items => [
+              { :serial => 2 },
+              { :serial => 1 }
+            ],
+            :has_more => false
+          })
+        end
+      end
+
+      describe '#channel_presence_history' do
+        it "should call correct URL and symbolise response" do
+          api_path = %r{/apps/20/channels/presence-mychannel/presence/history}
+          stub_request(:get, api_path).with(
+            query: hash_including(
+              "direction" => "newest_first",
+              "limit" => "2"
+            )
+          ).to_return({
+            :status => 200,
+            :body => MultiJson.encode({
+              'items' => [
+                { 'serial' => 2, 'event' => 'member_removed' },
+                { 'serial' => 1, 'event' => 'member_added' }
+              ],
+              'has_more' => false
+            })
+          })
+
+          expect(@client.channel_presence_history('presence-mychannel', direction: 'newest_first', limit: 2)).to eq({
+            :items => [
+              { :serial => 2, :event => 'member_removed' },
+              { :serial => 1, :event => 'member_added' }
+            ],
+            :has_more => false
+          })
+        end
+      end
+
+      describe '#channel_presence_snapshot' do
+        it "should call correct URL and symbolise response" do
+          api_path = %r{/apps/20/channels/presence-mychannel/presence/history/snapshot}
+          stub_request(:get, api_path).with(
+            query: hash_including(
+              "at_serial" => "4"
+            )
+          ).to_return({
+            :status => 200,
+            :body => MultiJson.encode({
+              'channel' => 'presence-mychannel',
+              'members' => [{ 'user_id' => 'u-1' }],
+              'member_count' => 1
+            })
+          })
+
+          expect(@client.channel_presence_snapshot('presence-mychannel', at_serial: 4)).to eq({
+            :channel => 'presence-mychannel',
+            :members => [{ :user_id => 'u-1' }],
+            :member_count => 1
           })
         end
       end
@@ -439,12 +521,12 @@
           }
         end
 
-        it "should not include idempotency_key header when not provided" do
+        it "should auto-generate idempotency_key when not provided" do
           @client.trigger('mychannel', 'event', {'some' => 'data'})
           expect(WebMock).to have_requested(:post, @api_path).with { |req|
             parsed = MultiJson.decode(req.body)
-            expect(parsed).not_to have_key("idempotency_key")
-            expect(req.headers).not_to have_key('X-Idempotency-Key')
+            expect(parsed["idempotency_key"]).to match(/\A[\w-]+:\d+\z/)
+            expect(req.headers['X-Idempotency-Key']).to eq(parsed["idempotency_key"])
           }
         end
       end
@@ -470,12 +552,15 @@
           )
           expect(WebMock).to have_requested(:post, @api_path).with { |req|
             parsed = MultiJson.decode(req.body)
-            expect(parsed).to eq(
-              "batch" => [
-                { "channel" => "mychannel", "name" => "event", "data" => "{\"some\":\"data\"}"},
-                { "channel" => "mychannel", "name" => "event", "data" => "already encoded"}
-              ]
-            )
+            batch = parsed["batch"]
+            expect(batch[0]["channel"]).to eq("mychannel")
+            expect(batch[0]["name"]).to eq("event")
+            expect(batch[0]["data"]).to eq("{\"some\":\"data\"}")
+            expect(batch[0]["idempotency_key"]).to match(/\A[\w-]+:\d+:0\z/)
+            expect(batch[1]["channel"]).to eq("mychannel")
+            expect(batch[1]["name"]).to eq("event")
+            expect(batch[1]["data"]).to eq("already encoded")
+            expect(batch[1]["idempotency_key"]).to match(/\A[\w-]+:\d+:1\z/)
           }
         end
 
@@ -528,15 +613,15 @@
           }
         end
 
-        it "should preserve idempotency_key per event in batch" do
+        it "should preserve explicit idempotency_key and auto-generate missing ones in batch" do
           @client.trigger_batch(
             {channel: 'mychannel', name: 'event', data: 'foo', idempotency_key: 'key-1'},
             {channel: 'mychannel', name: 'event2', data: 'bar'},
           )
           expect(WebMock).to have_requested(:post, @api_path).with { |req|
             batch = MultiJson.decode(req.body)["batch"]
             expect(batch[0]["idempotency_key"]).to eq("key-1")
-            expect(batch[1]).not_to have_key("idempotency_key")
+            expect(batch[1]["idempotency_key"]).to match(/\A[\w-]+:\d+:1\z/)
           }
         end
       end
@@ -611,7 +696,7 @@
               :body => MultiJson.encode({'something' => {'a' => 'hash'}})
             })
             expect(call_api).to eq({
-              :something => {'a' => 'hash'}
+              :something => { :a => 'hash' }
             })
           end
 
@@ -743,7 +828,7 @@
                 })
                 call_api.callback { |response|
                   expect(response).to eq({
-                    :something => {'a' => 'hash'}
+                    :something => { :a => 'hash' }
                   })
                   EM.stop
                 }