Class: Sockudo::Channel

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/sockudo/channel.rb

Overview

Delegates operations for a specific channel from a client

Constant Summary collapse

INVALID_CHANNEL_REGEX = 
/[^A-Za-z0-9_\-=@,.;:]/.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils

#_authentication_string, #validate_socket_id

Constructor Details

#initialize(_, name, client = Sockudo) ⇒ Channel

Returns a new instance of Channel.



13
14
15
16
17
18
19
20
21
22
 
# File 'lib/sockudo/channel.rb', line 13

def initialize(_, name, client = Sockudo)
  if Sockudo::Channel::INVALID_CHANNEL_REGEX.match(name)
    raise Sockudo::Error, "Illegal channel name '#{name}'"
  elsif name.length > 200
    raise Sockudo::Error, "Channel name too long (limit 164 characters) '#{name}'"
  end

  @name = name
  @client = client
end

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



9
10
11
 
# File 'lib/sockudo/channel.rb', line 9

def name
  @name
end

Instance Method Details

#append_message(message_serial, params = {}) ⇒ Object

Apply a mutable-message append.



156
157
158
 
# File 'lib/sockudo/channel.rb', line 156

def append_message(message_serial, params = {})
  @client.append_message(name, message_serial, params)
end

#authenticate(socket_id, custom_data = nil) ⇒ Hash

Generate the expected response for an authentication endpoint. See sockudo.com/docs/authenticating_users for details.

Examples:

Private channels

render :json => Sockudo['private-my_channel'].authenticate(params[:socket_id])

Presence channels

render :json => Sockudo['presence-my_channel'].authenticate(params[:socket_id], {
  :user_id => current_user.id, # => required
  :user_info => { # => optional - for example
    :name => current_user.name,
    :email => current_user.email
  }
})

Parameters:

  • socket_id (String)
  • custom_data (Hash) (defaults to: nil) —

    used for example by private channels

Returns:

  • (Hash)

Raises:



232
233
234
235
236
237
238
 
# File 'lib/sockudo/channel.rb', line 232

def authenticate(socket_id, custom_data = nil)
  custom_data = MultiJson.encode(custom_data) if custom_data
  auth = authentication_string(socket_id, custom_data)
  r = { auth: auth }
  r[:channel_data] = custom_data if custom_data
  r
end

#authentication_string(socket_id, custom_string = nil) ⇒ String

Compute authentication string required as part of the authentication endpoint response. Generally the authenticate method should be used in preference to this one

Parameters:

  • socket_id (String) —

    Each Sockudo socket connection receives a unique socket_id. This is sent from sockudo.js to your server when channel authentication is required.

  • custom_string (String) (defaults to: nil) —

    Allows signing additional data

Returns:

  • (String)

Raises:



202
203
204
205
206
 
# File 'lib/sockudo/channel.rb', line 202

def authentication_string(socket_id, custom_string = nil)
  string_to_sign = [socket_id, name, custom_string].compact.join(':')

  _authentication_string(socket_id, string_to_sign, @client.authentication_token, custom_string)
end

#delete_annotation(message_serial, annotation_serial, params = {}) ⇒ Object

Delete an annotation from a versioned message.



166
167
168
 
# File 'lib/sockudo/channel.rb', line 166

def delete_annotation(message_serial, annotation_serial, params = {})
  @client.delete_annotation(name, message_serial, annotation_serial, params)
end

#delete_message(message_serial, params = {}) ⇒ Object

Apply a mutable-message delete.



151
152
153
 
# File 'lib/sockudo/channel.rb', line 151

def delete_message(message_serial, params = {})
  @client.delete_message(name, message_serial, params)
end

#get_message(message_serial) ⇒ Object

Fetch the latest visible version of a mutable message.



136
137
138
 
# File 'lib/sockudo/channel.rb', line 136

def get_message(message_serial)
  @client.get_message(name, message_serial)
end

#get_message_versions(message_serial, params = {}) ⇒ Object

Fetch preserved versions of a mutable message.



141
142
143
 
# File 'lib/sockudo/channel.rb', line 141

def get_message_versions(message_serial, params = {})
  @client.get_message_versions(name, message_serial, params)
end

#history(params = {}) ⇒ Hash

Request durable history for this channel.

Parameters:

  • params (Hash) (defaults to: {}) —

    History API query params. Supported keys include: :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms

Returns:

  • (Hash) —

    History page payload for this channel



111
112
113
 
# File 'lib/sockudo/channel.rb', line 111

def history(params = {})
  @client.channel_history(name, params)
end

#info(attributes = []) ⇒ Hash

Request info for a channel

Examples:

Response

[{:occupied=>true, :subscription_count => 12}]

Parameters:

  • info (Array) —

    Array of attributes required (as lowercase strings)

Returns:

  • (Hash) —

    Hash of requested attributes for this channel

Raises:

  • (Sockudo::Error) —

    on invalid Sockudo response - see the error message for more details

  • (Sockudo::HTTPError) —

    on any error raised inside http client - the original error is available in the original_error attribute



101
102
103
 
# File 'lib/sockudo/channel.rb', line 101

def info(attributes = [])
  @client.channel_info(name, info: attributes.join(','))
end

#list_annotations(message_serial, params = {}) ⇒ Object

List raw annotation events for a versioned message.



171
172
173
 
# File 'lib/sockudo/channel.rb', line 171

def list_annotations(message_serial, params = {})
  @client.list_annotations(name, message_serial, params)
end

#presence_history(params = {}) ⇒ Hash

Request presence history for a presence channel.

Parameters:

  • params (Hash) (defaults to: {}) —

    Presence history API query params. Supported keys include: :limit, :direction, :cursor, :start_serial, :end_serial, :start_time_ms, :end_time_ms

Returns:

  • (Hash) —

    Presence history page payload for this channel



121
122
123
 
# File 'lib/sockudo/channel.rb', line 121

def presence_history(params = {})
  @client.channel_presence_history(name, params)
end

#presence_snapshot(params = {}) ⇒ Hash

Request a reconstructed presence snapshot for a presence channel.

Parameters:

  • params (Hash) (defaults to: {}) —

    Snapshot API query params. Supported keys include: :at_time_ms, :at_serial

Returns:

  • (Hash) —

    Presence snapshot payload for this channel



131
132
133
 
# File 'lib/sockudo/channel.rb', line 131

def presence_snapshot(params = {})
  @client.channel_presence_snapshot(name, params)
end

#publish_annotation(message_serial, params = {}) ⇒ Object

Publish an annotation for a versioned message.



161
162
163
 
# File 'lib/sockudo/channel.rb', line 161

def publish_annotation(message_serial, params = {})
  @client.publish_annotation(name, message_serial, params)
end

#shared_secret(encryption_master_key) ⇒ Object 



240
241
242
243
244
245
246
247
 
# File 'lib/sockudo/channel.rb', line 240

def shared_secret(encryption_master_key)
  return unless encryption_master_key

  secret_string = @name + encryption_master_key
  digest = OpenSSL::Digest.new('SHA256')
  digest << secret_string
  digest.digest
end

#trigger(event_name, data, socket_id = nil) ⇒ Object

Note:

CAUTION! No exceptions will be raised on failure

Trigger event, catching and logging any errors.

Deprecated

This method will be removed in a future gem version. Please

switch to Sockudo.trigger or Sockudo::Client#trigger instead

Parameters:



84
85
86
87
88
89
 
# File 'lib/sockudo/channel.rb', line 84

def trigger(event_name, data, socket_id = nil)
  trigger!(event_name, data, socket_id)
rescue Sockudo::Error => e
  Sockudo.logger.error("#{e.message} (#{e.class})")
  Sockudo.logger.debug(e.backtrace.join("\n"))
end

#trigger!(event_name, data, socket_id = nil) ⇒ Object

Trigger event

Deprecated

This method will be removed in a future gem version. Please

switch to Sockudo.trigger or Sockudo::Client#trigger instead

Examples:

begin
  Sockudo['my-channel'].trigger!('an_event', {:some => 'data'})
rescue Sockudo::Error => e
  # Do something on error
end

Parameters:

Raises:

  • (Sockudo::Error) —

    on invalid Sockudo response - see the error message for more details

  • (Sockudo::HTTPError) —

    on any error raised inside http client - the original error is available in the original_error attribute



67
68
69
70
71
72
73
74
 
# File 'lib/sockudo/channel.rb', line 67

def trigger!(event_name, data, socket_id = nil)
  params = {}
  if socket_id
    validate_socket_id(socket_id)
    params[:socket_id] = socket_id
  end
  @client.trigger(name, event_name, data, params)
end

#trigger_async(event_name, data, socket_id = nil) ⇒ EM::DefaultDeferrable

Trigger event asynchronously using EventMachine::HttpRequest

Deprecated

This method will be removed in a future gem version. Please

switch to Sockudo.trigger_async or Sockudo::Client#trigger_async instead

Parameters:

Returns:

  • (EM::DefaultDeferrable) —

    Attach a callback to be notified of success (with no parameters). Attach an errback to be notified of failure (with an error parameter which includes the HTTP status code returned)

Raises:

  • (LoadError) —

    unless em-http-request gem is available

  • (Sockudo::Error) —

    unless the eventmachine reactor is running. You probably want to run your application inside a server such as thin



38
39
40
41
42
43
44
45
 
# File 'lib/sockudo/channel.rb', line 38

def trigger_async(event_name, data, socket_id = nil)
  params = {}
  if socket_id
    validate_socket_id(socket_id)
    params[:socket_id] = socket_id
  end
  @client.trigger_async(name, event_name, data, params)
end

#update_message(message_serial, params = {}) ⇒ Object

Apply a mutable-message update.



146
147
148
 
# File 'lib/sockudo/channel.rb', line 146

def update_message(message_serial, params = {})
  @client.update_message(name, message_serial, params)
end

#users(params = {}) ⇒ Hash

Request users for a presence channel Only works on presence channels (see: sockudo.com/docs/client_api_guide/client_presence_channels and sockudo.com/docs/rest_api)

Examples:

Response

[{:id=>"4"}]

Parameters:

  • params (Hash) (defaults to: {}) —

    Hash of parameters for the API - see REST API docs

Returns:

  • (Hash) —

    Array of user hashes for this channel

Raises:

  • (Sockudo::Error) —

    on invalid Sockudo response - see the error message for more details

  • (Sockudo::HTTPError) —

    on any error raised inside Net::HTTP - the original error is available in the original_error attribute



186
187
188
 
# File 'lib/sockudo/channel.rb', line 186

def users(params = {})
  @client.channel_users(name, params)[:users]
end