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] 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 77
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 87
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 241
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 110
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 155
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 250
def as_json(*args)
  raise TypeError, ':action is missing, cannot generate a valid Hash for ProtocolMessage' unless action

  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 245
def attributes
  @hash_object
end
auth() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 234
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 230
def connection_details
  @connection_details ||= Ably::Models::ConnectionDetails(attributes[:connection_details])
end
count() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 130
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 116
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 174
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 211
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 226
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 216
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 206
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 221
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 186
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 191
def has_channel_resumed_flag?
  flags & 4 == 4 # 2^2
end
has_channel_serial?() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 141
def has_channel_serial?
  channel_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 196
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 135
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 181
def has_presence_flag?
  flags & 1 == 1
end
has_transient_flag?() click to toggle source

@api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 201
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 105
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 Used for validating incoming protocol messages, so no need to add unnecessary checks @return [Boolean] @api private

# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 279
def invalid?
  action_enum = action rescue nil
  !action_enum
end
message_serial() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 124
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 166
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 147
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 170
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 159
def presence
  @presence ||=
    Array(attributes[:presence]).map do |message|
      Ably::Models.PresenceMessage(message, protocol_message: self)
    end
end
timestamp() click to toggle source
# File lib/submodules/ably-ruby/lib/ably/models/protocol_message.rb, line 120
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 260
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