Class: Ably::Rest::Channel

Inherits:
Object
  • Object
show all
Includes:
Modules::Conversions
Defined in:
lib/ably/rest/channel.rb,
lib/ably/rest/channel/push_channel.rb

Overview

Enables messages to be published and historic messages to be retrieved for a channel.

Defined Under Namespace

Classes: PushChannel

Constant Summary collapse

IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH =

See spec RSL1k1

9

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, name, channel_options = {}) ⇒ Channel

Initialize a new Channel object

Parameters:



33
34
35
36
37
38
39
40
 
# File 'lib/ably/rest/channel.rb', line 33

def initialize(client, name, channel_options = {})
  name = (ensure_utf_8 :name, name)

  @options = Ably::Models::ChannelOptions(channel_options)
  @client  = client
  @name    = name
  @push    = PushChannel.new(self)
end

Instance Attribute Details

#client ⇒ Ably::Realtime::Client (readonly)

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.

Ably client associated with this channel

Returns:



11
12
13
 
# File 'lib/ably/rest/channel.rb', line 11

def client
  @client
end

#name ⇒ String (readonly)

The channel name.

Returns:

  • (String) 


15
16
17
 
# File 'lib/ably/rest/channel.rb', line 15

def name
  @name
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



17
18
19
 
# File 'lib/ably/rest/channel.rb', line 17

def options
  @options
end

#push ⇒ Ably::Rest::Channel::PushChannel (readonly)

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.

A PushChannel object

Returns:



23
24
25
 
# File 'lib/ably/rest/channel.rb', line 23

def push
  @push
end

Instance Method Details

#history(options = {}) ⇒ Ably::Models::PaginatedResult<Ably::Models::Message>

Retrieves a Models::PaginatedResult object, containing an array of historical Models::Message objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.

Parameters:

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

    the options for the message history request

Options Hash (options):

  • :start (Integer, Time) —

    The time from which messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1

  • :end (Integer, Time) —

    The time until messages are retrieved, specified as milliseconds since the Unix epoch. RSL2b1

  • :direction (Symbol) —

    The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards. RSL2b2

  • :limit (Integer) —

    An upper limit on the number of messages returned. The default is 100, and the maximum is 1000. RSL2b3

Returns:

Raises:

  • (ArgumentError) 


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/ably/rest/channel.rb', line 132

def history(options = {})
  url = "#{base_path}/messages"
  options = {
    :direction => :backwards,
    :limit     => 100
  }.merge(options)

  [:start, :end].each { |option| options[option] = as_since_epoch(options[option]) if options.has_key?(option) }
  raise ArgumentError, ":end must be equal to or after :start" if options[:start] && options[:end] && (options[:start] > options[:end])

  paginated_options = {
    coerce_into: 'Ably::Models::Message',
    async_blocking_operations: options.delete(:async_blocking_operations),
  }

  response = client.get(url, options)

  Ably::Models::PaginatedResult.new(response, url, client, paginated_options) do |message|
    message.tap do |msg|
      decode_message msg
    end
  end
end

#presence ⇒ Ably::Rest::Presence

A Presence object.

Returns:



159
160
161
 
# File 'lib/ably/rest/channel.rb', line 159

def presence
  @presence ||= Presence.new(client, self)
end

#publish(name, data = nil, attributes = {}) ⇒ Boolean

Publishes a message to the channel. A callback may optionally be passed in to this call to be notified of success or failure of the operation.

Examples:

# Publish a single message with (name, data) form
channel.publish 'click', { x: 1, y: 2 }

# Publish a single message with single Hash form
message = { name: 'click', data: { x: 1, y: 2 } }
channel.publish message

# Publish an array of message Hashes form
messages = [
  { name: 'click', data: { x: 1, y: 2 } },
  { name: 'click', data: { x: 2, y: 3 } }
]
channel.publish messages

# Publish an array of Ably::Models::Message objects form
messages = [
  Ably::Models::Message(name: 'click', data: { x: 1, y: 2 })
  Ably::Models::Message(name: 'click', data: { x: 2, y: 3 })
]
channel.publish messages

# Publish a single Ably::Models::Message object form
message = Ably::Models::Message(name: 'click', data: { x: 1, y: 2 })
channel.publish message

Parameters:

  • name (String, Array<Ably::Models::Message|Hash>, Ably::Models::Message, nil) —

    The event name of the message to publish, or an Array of [Ably::Model::Message] objects or [Hash] objects with :name and :data pairs, or a single Ably::Model::Message object

  • data (String, Array, Hash, nil) (defaults to: nil) —

    The message payload unless an Array of [Ably::Model::Message] objects passed in the first argument, in which case an optional hash of query parameters

  • attributes (Hash, nil) (defaults to: {}) —

    Optional additional message attributes such as :extras, :id, :client_id or :connection_id, applied when name attribute is nil or a string (Deprecated, will be removed in 2.0 in favour of constructing a Message object)

Returns:

  • (Boolean) —

    true if the message was published, otherwise false



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/ably/rest/channel.rb', line 77

def publish(name, data = nil, attributes = {})
  qs_params = nil
  qs_params = data if name.kind_of?(Enumerable) || name.kind_of?(Ably::Models::Message)

  messages = build_messages(name, data, attributes) # (RSL1a, RSL1b)

  if messages.sum(&:size) > (max_message_size = client.max_message_size || Ably::Rest::Client::MAX_MESSAGE_SIZE)
    raise Ably::Exceptions::MaxMessageSizeExceeded.new("Maximum message size exceeded #{max_message_size} bytes.")
  end

  payload = messages.map do |message|
    Ably::Models::Message(message.dup).tap do |msg|
      msg.encode client.encoders, options

      next if msg.client_id.nil?
      if msg.client_id == '*'
        raise Ably::Exceptions::IncompatibleClientId.new('Wildcard client_id is reserved and cannot be used when publishing messages')
      end
      unless client.auth.can_assume_client_id?(msg.client_id)
        raise Ably::Exceptions::IncompatibleClientId.new("Cannot publish with client_id '#{msg.client_id}' as it is incompatible with the current configured client_id '#{client.client_id}'")
      end
    end.as_json
  end.tap do |payload|
    if client.idempotent_rest_publishing
      # We cannot mutate for idempotent publishing if one or more messages already has an ID
      if payload.all? { |msg| !msg['id'] }
        # Mutate the JSON to support idempotent publishing where a Message.id does not exist
        idempotent_publish_id = SecureRandom.base64(IDEMPOTENT_LIBRARY_GENERATED_ID_LENGTH)
        payload.each_with_index do |msg, idx|
          msg['id'] = "#{idempotent_publish_id}:#{idx}"
        end
      end
    end
  end

  options = qs_params ? { qs_params: qs_params } : {}
  response = client.post("#{base_path}/publish", payload.length == 1 ? payload.first : payload, options)

  [201, 204].include?(response.status)
end

#set_options(channel_options) ⇒ Ably::Models::ChannelOptions Also known as: options=

Sets the Models::ChannelOptions for the channel.

Parameters:

Returns:



167
168
169
 
# File 'lib/ably/rest/channel.rb', line 167

def set_options(channel_options)
  @options = Ably::Models::ChannelOptions(channel_options)
end

#status ⇒ Ably::Models::ChannelDetails

Retrieves a Models::ChannelDetails object for the channel, which includes status and occupancy metrics.

Returns:



175
176
177
 
# File 'lib/ably/rest/channel.rb', line 175

def status
  Ably::Models::ChannelDetails.new(client.get(base_path).body)
end