class Ably::Models::PresenceMessage

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

Constants

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.

@spec TP2

Public Class Methods

new(attributes, options = {}) click to toggle source

{PresenceMessage} initializer

@param attributes [Hash] object with the underlying presence message key value attributes @param [Hash] options an options Hash for this initializer @option options [ProtocolMessage] :protocol_message An optional protocol message to assocate the presence message with @option options [Logger] :logger An optional Logger to be used by {Ably::Modules::SafeDeferrable} if an exception is caught in a callback

# File lib/submodules/ably-ruby/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

Public Instance Methods

action() click to toggle source

The type of {Ably::Models::PresenceMessage::ACTION} the PresenceMessage is for.

@spec TP3b

@return [Ably::Models::PresenceMessage::ACTION]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 155
def action
  ACTION(attributes[:action])
end
as_json(*args) click to toggle source

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

# File lib/submodules/ably-ruby/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) click to toggle source

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

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 194
def assign_to_protocol_message(protocol_message)
  @protocol_message = protocol_message
end
assigned_to_protocol_message?() click to toggle source

True if this presence message is assigned to a ProtocolMessage for delivery to Ably, or received from Ably @return [Boolean] @api private

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 201
def assigned_to_protocol_message?
  !!@protocol_message
end
attributes() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 159
def attributes
  @attributes
end
client_id() click to toggle source

The ID of the client that published the PresenceMessage.

@spec TP3c

@return [String]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 78
def client_id
  attributes[:client_id]
end
connection_id() click to toggle source

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

@spec TP3d

@return [String]

# File lib/submodules/ably-ruby/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() click to toggle source

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

@spec TP3e

@return [Hash, nil]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 88
def data
  attributes[:data]
end
encoding() click to toggle source

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.

@spec TP3f

@return [String]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 100
def encoding
  attributes[:encoding]
end
id() click to toggle source

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

@spec TP3a

@return [String]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 110
def id
  attributes.fetch(:id) { "#{protocol_message.id!}:#{protocol_message_index}" }
end
member_key() click to toggle source

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.

@spec TP3h

@return [String]

# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 131
def member_key
  "#{connection_id}:#{client_id}"
end
protocol_message() click to toggle source

The optional ProtocolMessage this presence message is assigned to. If ProtocolMessage is nil, an error will be raised. @return [Ably::Models::ProtocolMessage] @api private

# File lib/submodules/ably-ruby/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 = {}) click to toggle source

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

# File lib/submodules/ably-ruby/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() click to toggle source

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

# File lib/submodules/ably-ruby/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() click to toggle source

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

@spec TP3g

@return [Integer]

# File lib/submodules/ably-ruby/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) click to toggle source
# File lib/submodules/ably-ruby/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

Private Instance Methods

logger() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 239
def logger
  return @logger if @logger
  protocol_message.logger if protocol_message
end
protocol_message_index() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 231
def protocol_message_index
  protocol_message.presence.index(self)
end
raw_hash_object() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 227
def raw_hash_object
  @raw_hash_object
end
set_attributes_object(new_attributes) click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/presence_message.rb, line 235
def set_attributes_object(new_attributes)
  @attributes = IdiomaticRubyWrapper(new_attributes.clone, stop_at: [:data])
end