Class: Ably::Rest::Channel

Inherits:
Object
  • Object
show all
Includes:
Modules::Conversions
Defined in:
lib/submodules/ably-ruby/lib/ably/rest/channel.rb

Overview

The Ably Realtime service organises the traffic within any application into named channels. Channels are the “unit” of message distribution; clients attach to channels to subscribe to messages, and every message broadcast by the service is associated with a unique channel.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

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

Initialize a new Channel object

Parameters:

  • client (Ably::Rest::Client)
  • name (String) —

    The name of the channel

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

    Channel options, currently reserved for Encryption options

Options Hash (channel_options):

  • :encrypted (Boolean) —

    setting this to true for this channel will encrypt & decrypt all messages automatically

  • :cipher_params (Hash) —

    A hash of options to configure the encryption. :key is required, all other options are optional. See Util::Crypto#initialize for a list of cipher_params options



25
26
27
28
29
30
31
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 25

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

  @client  = client
  @name    = name
  @options = channel_options.clone.freeze
end

Instance Attribute Details

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

Returns Ably client associated with this channel.

Returns:

  • (Ably::Realtime::Client) —

    Ably client associated with this channel



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 12

class Channel
  include Ably::Modules::Conversions

  attr_reader :client, :name, :options

  # Initialize a new Channel object
  #
  # @param client [Ably::Rest::Client]
  # @param name [String] The name of the channel
  # @param channel_options [Hash] Channel options, currently reserved for Encryption options
  # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
  # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
  #
  def initialize(client, name, channel_options = {})
    ensure_utf_8 :name, name

    @client  = client
    @name    = name
    @options = channel_options.clone.freeze
  end

  # Publish a message to the channel
  #
  # @param name [String] The event name of the message to publish
  # @param data [String] The message payload
  # @return [Boolean] true if the message was published, otherwise false
  def publish(name, data)
    ensure_utf_8 :name, name
    ensure_supported_payload data

    payload = {
      name: name,
      data: data
    }

    message = Ably::Models::Message.new(payload).tap do |message|
      message.encode self
    end

    response = client.post("#{base_path}/publish", message)

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

  # Return the message   of the channel
  #
  # @param [Hash] options   the options for the message history request
  # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
  # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
  # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
  # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
  #
  # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
  #
  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) }

    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 |message|
        decode_message message
      end
    end
  end

  # Return the {Ably::Rest::Presence} object
  #
  # @return [Ably::Rest::Presence]
  def presence
    @presence ||= Presence.new(client, self)
  end

  private
  def base_path
    "/channels/#{CGI.escape(name)}"
  end

  def decode_message(message)
    message.decode self
  rescue Ably::Exceptions::CipherError, Ably::Exceptions::EncoderError => e
    client.logger.error "Decoding Error on channel '#{name}', message event name '#{message.name}'. #{e.class.name}: #{e.message}"
  end
end

#name ⇒ String (readonly)

Returns channel name.

Returns:

  • (String) —

    channel name



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 12

class Channel
  include Ably::Modules::Conversions

  attr_reader :client, :name, :options

  # Initialize a new Channel object
  #
  # @param client [Ably::Rest::Client]
  # @param name [String] The name of the channel
  # @param channel_options [Hash] Channel options, currently reserved for Encryption options
  # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
  # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
  #
  def initialize(client, name, channel_options = {})
    ensure_utf_8 :name, name

    @client  = client
    @name    = name
    @options = channel_options.clone.freeze
  end

  # Publish a message to the channel
  #
  # @param name [String] The event name of the message to publish
  # @param data [String] The message payload
  # @return [Boolean] true if the message was published, otherwise false
  def publish(name, data)
    ensure_utf_8 :name, name
    ensure_supported_payload data

    payload = {
      name: name,
      data: data
    }

    message = Ably::Models::Message.new(payload).tap do |message|
      message.encode self
    end

    response = client.post("#{base_path}/publish", message)

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

  # Return the message   of the channel
  #
  # @param [Hash] options   the options for the message history request
  # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
  # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
  # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
  # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
  #
  # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
  #
  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) }

    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 |message|
        decode_message message
      end
    end
  end

  # Return the {Ably::Rest::Presence} object
  #
  # @return [Ably::Rest::Presence]
  def presence
    @presence ||= Presence.new(client, self)
  end

  private
  def base_path
    "/channels/#{CGI.escape(name)}"
  end

  def decode_message(message)
    message.decode self
  rescue Ably::Exceptions::CipherError, Ably::Exceptions::EncoderError => e
    client.logger.error "Decoding Error on channel '#{name}', message event name '#{message.name}'. #{e.class.name}: #{e.message}"
  end
end

#options ⇒ Hash (readonly)

Returns channel options configured for this channel, see #initialize for channel_options.

Returns:

  • (Hash) —

    channel options configured for this channel, see #initialize for channel_options



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
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
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 12

class Channel
  include Ably::Modules::Conversions

  attr_reader :client, :name, :options

  # Initialize a new Channel object
  #
  # @param client [Ably::Rest::Client]
  # @param name [String] The name of the channel
  # @param channel_options [Hash] Channel options, currently reserved for Encryption options
  # @option channel_options [Boolean]  :encrypted       setting this to true for this channel will encrypt & decrypt all messages automatically
  # @option channel_options [Hash]     :cipher_params   A hash of options to configure the encryption. *:key* is required, all other options are optional.  See {Ably::Util::Crypto#initialize} for a list of +cipher_params+ options
  #
  def initialize(client, name, channel_options = {})
    ensure_utf_8 :name, name

    @client  = client
    @name    = name
    @options = channel_options.clone.freeze
  end

  # Publish a message to the channel
  #
  # @param name [String] The event name of the message to publish
  # @param data [String] The message payload
  # @return [Boolean] true if the message was published, otherwise false
  def publish(name, data)
    ensure_utf_8 :name, name
    ensure_supported_payload data

    payload = {
      name: name,
      data: data
    }

    message = Ably::Models::Message.new(payload).tap do |message|
      message.encode self
    end

    response = client.post("#{base_path}/publish", message)

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

  # Return the message   of the channel
  #
  # @param [Hash] options   the options for the message history request
  # @option options [Integer,Time] :start      Ensure earliest time or millisecond since epoch for any messages retrieved is +:start+
  # @option options [Integer,Time] :end        Ensure latest time or millisecond since epoch for any messages retrieved is +:end+
  # @option options [Symbol]       :direction  +:forwards+ or +:backwards+, defaults to +:backwards+
  # @option options [Integer]      :limit      Maximum number of messages to retrieve up to 1,000, defaults to 100
  #
  # @return [Ably::Models::PaginatedResult<Ably::Models::Message>] First {Ably::Models::PaginatedResult page} of {Ably::Models::Message} objects accessible with {Ably::Models::PaginatedResult#items #items}.
  #
  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) }

    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 |message|
        decode_message message
      end
    end
  end

  # Return the {Ably::Rest::Presence} object
  #
  # @return [Ably::Rest::Presence]
  def presence
    @presence ||= Presence.new(client, self)
  end

  private
  def base_path
    "/channels/#{CGI.escape(name)}"
  end

  def decode_message(message)
    message.decode self
  rescue Ably::Exceptions::CipherError, Ably::Exceptions::EncoderError => e
    client.logger.error "Decoding Error on channel '#{name}', message event name '#{message.name}'. #{e.class.name}: #{e.message}"
  end
end

Instance Method Details

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

Return the message of the channel

Parameters:

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

    the options for the message history request

Options Hash (options):

  • :start (Integer, Time) —

    Ensure earliest time or millisecond since epoch for any messages retrieved is :start

  • :end (Integer, Time) —

    Ensure latest time or millisecond since epoch for any messages retrieved is :end

  • :direction (Symbol) —

    :forwards or :backwards, defaults to :backwards

  • :limit (Integer) —

    Maximum number of messages to retrieve up to 1,000, defaults to 100

Returns:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 66

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) }

  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 |message|
      decode_message message
    end
  end
end

#presence ⇒ Ably::Rest::Presence

Return the Presence object

Returns:



92
93
94
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 92

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

#publish(name, data) ⇒ Boolean

Publish a message to the channel

Parameters:

  • name (String) —

    The event name of the message to publish

  • data (String) —

    The message payload

Returns:

  • (Boolean) —

    true if the message was published, otherwise false



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/submodules/ably-ruby/lib/ably/rest/channel.rb', line 38

def publish(name, data)
  ensure_utf_8 :name, name
  ensure_supported_payload data

  payload = {
    name: name,
    data: data
  }

  message = Ably::Models::Message.new(payload).tap do |message|
    message.encode self
  end

  response = client.post("#{base_path}/publish", message)

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