Class: Ably::Models::PresenceMessage

Inherits:
Object
  • Object
show all
Extended by:
Ably::Modules::Enum
Includes:
Ably::Modules::Conversions, Ably::Modules::Encodeable, Ably::Modules::ModelCommon, Ably::Modules::SafeDeferrable
Defined in:
lib/ably/models/presence_message.rb

Overview

A class representing an individual presence message to be sent or received via the Ably Realtime service.

Constant Summary collapse

ACTION =

Describes the possible actions members in the presence set can emit.

ABSENT	    TP2	A member is not present in the channel.
PRESENT	    TP2	When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered.
ENTER	      TP2	A new member has entered the channel.
LEAVE	      TP2	A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present.
UPDATE	    TP2	An already present member has updated their member data. Being notified of member data updates can be very useful, for example, it can be used to update the status of a user when they are typing a message.

ruby_enum('ACTION',
  :absent,
  :present,
  :enter,
  :leave,
  :update
)

Instance Attribute Summary

Attributes included from Ably::Modules::ModelCommon

#hash

Instance Method Summary collapse

Methods included from Ably::Modules::SafeDeferrable

#callback, #errback, #fail, #succeed

Methods included from Ably::Modules::ModelCommon

#==, #[], included, #to_s

Methods included from Ably::Modules::MessagePack

#to_msgpack

Methods included from Ably::Modules::Encodeable

#decode, #encode, included, #original_encoding

Constructor Details

#initialize(attributes, options = {}) ⇒ PresenceMessage

Ably::Models::PresenceMessage initializer

Parameters:

  • attributes (Hash) —

    object with the underlying presence message key value attributes

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

    an options Hash for this initializer

Options Hash (options):



58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/ably/models/presence_message.rb', line 58

def initialize(attributes, options = {})
  @logger           = options[:logger] # Logger expected for SafeDeferrable
  @protocol_message = options[:protocol_message]
  @raw_hash_object  = attributes

  set_attributes_object attributes

  self.attributes[:client_id] = ensure_utf_8(:client_id, client_id, allow_nil: true) if client_id
  self.attributes[:connection_id] = ensure_utf_8(:connection_id, connection_id, allow_nil: true) if connection_id
  self.attributes[:encoding] = ensure_utf_8(:encoding, encoding, allow_nil: true) if encoding

  self.attributes.freeze
end

Instance Method Details

#action ⇒ Ably::Models::PresenceMessage::ACTION

The type of ACTION the PresenceMessage is for.

Returns:



155
156
157
 
# File 'lib/ably/models/presence_message.rb', line 155

def action
  ACTION(attributes[:action])
end

#as_json(*args) ⇒ Object

Return a JSON ready object from the underlying #attributes using Ably naming conventions for keys



164
165
166
167
168
169
170
 
# File 'lib/ably/models/presence_message.rb', line 164

def as_json(*args)
  attributes.dup.tap do |presence_message|
    presence_message['action'] = action.to_i
  end.as_json.reject { |key, val| val.nil? }
rescue KeyError
  raise KeyError, ':action is missing or invalid, cannot generate a valid Hash for ProtocolMessage'
end

#assign_to_protocol_message(protocol_message) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Assign this presence message to a ProtocolMessage before delivery to the Ably system



194
195
196
 
# File 'lib/ably/models/presence_message.rb', line 194

def assign_to_protocol_message(protocol_message)
  @protocol_message = protocol_message
end

#assigned_to_protocol_message? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True if this presence message is assigned to a ProtocolMessage for delivery to Ably, or received from Ably

Returns:

  • (Boolean) 


201
202
203
 
# File 'lib/ably/models/presence_message.rb', line 201

def assigned_to_protocol_message?
  !!@protocol_message
end

#attributes ⇒ Object 



159
160
161
 
# File 'lib/ably/models/presence_message.rb', line 159

def attributes
  @attributes
end

#client_id ⇒ String

The ID of the client that published the PresenceMessage.

Returns:

  • (String) 


78
79
80
 
# File 'lib/ably/models/presence_message.rb', line 78

def client_id
  attributes[:client_id]
end

#connection_id ⇒ String

The ID of the connection associated with the client that published the Ably::Models::PresenceMessage.

Returns:

  • (String) 


120
121
122
 
# File 'lib/ably/models/presence_message.rb', line 120

def connection_id
  attributes.fetch(:connection_id) { protocol_message.connection_id if assigned_to_protocol_message? }
end

#data ⇒ Hash?

The payload of the Ably::Models::PresenceMessage.

Returns:

  • (Hash, nil) 


88
89
90
 
# File 'lib/ably/models/presence_message.rb', line 88

def data
  attributes[:data]
end

#encoding ⇒ String

This will typically be empty as all presence messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.

Returns:

  • (String) 


100
101
102
 
# File 'lib/ably/models/presence_message.rb', line 100

def encoding
  attributes[:encoding]
end

#id ⇒ String

A unique ID assigned to each Ably::Models::PresenceMessage by Ably.

Returns:

  • (String) 


110
111
112
 
# File 'lib/ably/models/presence_message.rb', line 110

def id
  attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
end

#member_key ⇒ String

Combines clientId and connectionId to ensure that multiple connected clients with an identical clientId are uniquely identifiable. A string function that returns the combined clientId and connectionId.

Returns:

  • (String) 


131
132
133
 
# File 'lib/ably/models/presence_message.rb', line 131

def member_key
  "#{connection_id}:#{client_id}"
end

#protocol_message ⇒ Ably::Models::ProtocolMessage

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The optional ProtocolMessage this presence message is assigned to. If ProtocolMessage is nil, an error will be raised.

Returns:

Raises:

  • (RuntimeError) 


208
209
210
211
 
# File 'lib/ably/models/presence_message.rb', line 208

def protocol_message
  raise RuntimeError, 'Presence Message is not yet published with a ProtocolMessage. ProtocolMessage is nil' if @protocol_message.nil?
  @protocol_message
end

#shallow_clone(new_attributes = {}) ⇒ Object

Create a static shallow clone of this object with the optional attributes to overide existing values Shallow clones have no dependency on the originating ProtocolMessage as all field values are stored as opposed to calculated Clones are useful when the original PresenceMessage needs to be mutated, such as storing in a PresenceMap with action :present



216
217
218
219
220
221
222
223
224
 
# File 'lib/ably/models/presence_message.rb', line 216

def shallow_clone(new_attributes = {})
  new_attributes = IdiomaticRubyWrapper(new_attributes.clone.freeze, stop_at: [:data])

  self.class.new(attributes.to_hash.merge(
    id: new_attributes[:id] || id,
    connection_id: new_attributes[:connection_id] || connection_id,
    timestamp: new_attributes[:timestamp] || as_since_epoch(timestamp)
  ).merge(new_attributes.to_hash))
end

#size ⇒ Object

The size is the sum over data and clientId in bytes (TO3l8a)



180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/ably/models/presence_message.rb', line 180

def size
  %w(data client_id).map do |attr|
    if (value = attributes[attr.to_sym]).is_a?(String)
      value.bytesize
    elsif value.nil?
      0
    else
      value.to_json.bytesize
    end
  end.sum
end

#timestamp ⇒ Integer

The time the Ably::Models::PresenceMessage was received by Ably, as milliseconds since the Unix epoch.

Returns:

  • (Integer) 


141
142
143
144
145
146
147
 
# File 'lib/ably/models/presence_message.rb', line 141

def timestamp
  if attributes[:timestamp]
    as_time_from_epoch(attributes[:timestamp])
  else
    protocol_message.timestamp
  end
end

#to_json(*args) ⇒ Object 



172
173
174
175
176
 
# File 'lib/ably/models/presence_message.rb', line 172

def to_json(*args)
  as_json(*args).tap do |presence_message|
    decode_binary_data_before_to_json presence_message
  end.to_json
end