class Ably::Models::ProtocolMessage

A message sent and received over the Realtime protocol. A ProtocolMessage always relates to a single channel only, but can contain multiple individual Messages or PresenceMessages. ProtocolMessages are serially numbered on a connection. See the {ably.com/docs/client-lib-development-guide/protocol/ Ably client library developer documentation} for further details on the members of a ProtocolMessage

@!attribute [r] action

@return [ACTION] Protocol Message action {Ably::Modules::Enum} from list of {ACTION}. Returns nil if action is unsupported by protocol

@!attribute [r] auth

@return [Ably::Models::AuthDetails] Authentication details used to perform authentication upgrades over an existing transport

@!attribute [r] count

@return [Integer] The count field is used for ACK and NACK actions. See {http://ably.com/docs/client-lib-development-guide/protocol/#message-acknowledgement message acknowledgement protocol}

@!attribute [r] error

@return [ErrorInfo] Contains error information

@!attribute [r] channel

@return [String] Channel name for messages

@!attribute [r] channel_serial

@return [String] Contains a serial number for a message on the current channel

@!attribute [r] connection_id

@return [String] Contains a string private connection key used to recover this connection

@!attribute [r] connection_serial

@return [Bignum] Contains a serial number for a message sent from the server to the client

@!attribute [r] message_serial

@return [Bignum] Contains a serial number for a message sent from the client to the server

@!attribute [r] timestamp

@return [Time] An optional timestamp, applied by the service in messages sent to the client, to indicate the system time at which the message was sent (milliseconds past epoch)

@!attribute [r] messages

@return [Array<Message>] A {ProtocolMessage} with a `:message` action contains one or more messages belonging to the channel

@!attribute [r] presence

@return [Array<PresenceMessage>] A {ProtocolMessage} with a `:presence` action contains one or more presence updates belonging to the channel

@!attribute [r] flags

@return [Integer] Flags indicating special ProtocolMessage states

@!attribute [r] attributes

@return [Hash] Access the protocol message Hash object ruby'fied to use symbolized keys

Constants

ACTION

Actions which are sent by the Ably Realtime API

The values correspond to the ints which the API understands.

ATTACH_FLAGS_MAPPING

Attributes

logger[R]

@!attribute [r] logger @api private

Public Class Methods

ack_required?(for_action) click to toggle source

Indicates this protocol message action will generate an ACK response such as :message or :presence @api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 79
def self.ack_required?(for_action)
  ACTION(for_action).match_any?(ACTION.Presence, ACTION.Message)
end
new(hash_object, options = {}) click to toggle source

{ProtocolMessage} initializer

@param hash_object [Hash] object with the underlying protocol message data @param [Hash] options an options Hash for this initializer @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/protocol_message.rb, line 89
def initialize(hash_object, options = {})
  @logger = options[:logger] # Logger expected for SafeDeferrable

  @raw_hash_object = hash_object
  @hash_object     = IdiomaticRubyWrapper(@raw_hash_object.clone)

  raise ArgumentError, 'Invalid ProtocolMessage, action cannot be nil' if @hash_object[:action].nil?
  @hash_object[:action] = ACTION(@hash_object[:action]).to_i unless @hash_object[:action].kind_of?(Integer)

  @hash_object.freeze
end

Public Instance Methods

ack_required?() click to toggle source

Indicates this protocol message will generate an ACK response when sent Examples of protocol messages required ACK include :message and :presence @api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 263
def ack_required?
  self.class.ack_required?(action)
end
action() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 112
def action
  ACTION(attributes[:action])
rescue KeyError
  raise KeyError, "Action '#{attributes[:action]}' is not supported by ProtocolMessage"
end
add_message(message) click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 177
def add_message(message)
  messages << message
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/protocol_message.rb, line 272
def as_json(*args)
  raise TypeError, ':action is missing, cannot generate a valid Hash for ProtocolMessage' unless action
  raise TypeError, ':msg_serial or :connection_serial is missing, cannot generate a valid Hash for ProtocolMessage' if ack_required? && !has_serial?

  attributes.dup.tap do |hash_object|
    hash_object['action']   = action.to_i
    hash_object['messages'] = messages.map(&:as_json) unless messages.empty?
    hash_object['presence'] = presence.map(&:as_json) unless presence.empty?
  end.as_json
end
attributes() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 267
def attributes
  @hash_object
end
auth() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 256
def auth
  @auth ||= Ably::Models::AuthDetails(attributes[:auth])
end
connection_details() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 252
def connection_details
  @connection_details ||= Ably::Models::ConnectionDetails(attributes[:connection_details])
end
connection_serial() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 132
def connection_serial
  Integer(attributes[:connection_serial])
rescue TypeError
  raise TypeError, "connection_serial '#{attributes[:connection_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
end
count() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 138
def count
  [1, attributes[:count].to_i].max
end
error() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 118
def error
  @error ||= ErrorInfo.new(attributes[:error]) if attributes[:error]
end
flags() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 196
def flags
  Integer(attributes[:flags])
rescue TypeError
  0
end
has_attach_presence_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 233
def has_attach_presence_flag?
  flags & ATTACH_FLAGS_MAPPING[:presence] == ATTACH_FLAGS_MAPPING[:presence] # 2^16
end
has_attach_presence_subscribe_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 248
def has_attach_presence_subscribe_flag?
  flags & ATTACH_FLAGS_MAPPING[:presence_subscribe] == ATTACH_FLAGS_MAPPING[:presence_subscribe] # 2^19
end
has_attach_publish_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 238
def has_attach_publish_flag?
  flags & ATTACH_FLAGS_MAPPING[:publish] == ATTACH_FLAGS_MAPPING[:publish] # 2^17
end
has_attach_resume_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 228
def has_attach_resume_flag?
  flags & ATTACH_FLAGS_MAPPING[:resume] == ATTACH_FLAGS_MAPPING[:resume] # 2^5
end
has_attach_subscribe_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 243
def has_attach_subscribe_flag?
  flags & ATTACH_FLAGS_MAPPING[:subscribe] == ATTACH_FLAGS_MAPPING[:subscribe] # 2^18
end
has_backlog_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 208
def has_backlog_flag?
  flags & 2 == 2 # 2^1
end
has_channel_resumed_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 213
def has_channel_resumed_flag?
  flags & 4 == 4 # 2^2
end
has_connection_serial?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 150
def has_connection_serial?
  connection_serial && true
rescue TypeError
  false
end
has_local_presence_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 218
def has_local_presence_flag?
  flags & 8 == 8 # 2^3
end
has_message_serial?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 143
def has_message_serial?
  message_serial && true
rescue TypeError
  false
end
has_presence_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 203
def has_presence_flag?
  flags & 1 == 1
end
has_serial?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 165
def has_serial?
  has_connection_serial? || has_message_serial?
end
has_transient_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 223
def has_transient_flag?
  flags & 16 == 16 # 2^4
end
id!() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 107
def id!
  raise RuntimeError, 'ProtocolMessage #id is nil' unless id
  id
end
invalid?() click to toggle source

True if the ProtocolMessage appears to be invalid, however this is not a guarantee @return [Boolean] @api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 301
def invalid?
  action_enum = action rescue nil
  !action_enum || (ack_required? && !has_serial?)
end
message_serial() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 126
def message_serial
  Integer(attributes[:msg_serial])
rescue TypeError
  raise TypeError, "msg_serial '#{attributes[:msg_serial]}' is invalid, a positive Integer is expected for a ProtocolMessage"
end
message_size() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 188
def message_size
  presence.map(&:size).sum + messages.map(&:size).sum
end
messages() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 169
def messages
  @messages ||=
    Array(attributes[:messages]).map do |message|
      Ably::Models.Message(message, protocol_message: self)
    end
end
params() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 192
def params
  @params ||= attributes[:params].to_h
end
presence() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 181
def presence
  @presence ||=
    Array(attributes[:presence]).map do |message|
      Ably::Models.PresenceMessage(message, protocol_message: self)
    end
end
serial() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 156
def serial
  if has_connection_serial?
    connection_serial
  else
    message_serial
  end
end
timestamp() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 122
def timestamp
  as_time_from_epoch(attributes[:timestamp]) if attributes[:timestamp]
end
to_s() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 283
def to_s
  json_hash = as_json

  # Decode any binary data to before converting to a JSON string representation
  %w(messages presence).each do |message_type|
    if json_hash[message_type] && !json_hash[message_type].empty?
      json_hash[message_type].each do |message|
        decode_binary_data_before_to_json message
      end
    end
  end

  json_hash.to_json
end