Class: ActionCable::Channel::Base
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
|
|
Instance Chain:
|
|
Inherits: | Object |
Defined in: | actioncable/lib/action_cable/channel/base.rb |
Overview
The channel provides the basic structure of grouping behavior into logical units when communicating over the WebSocket connection. You can think of a channel like a form of controller, but one that’s capable of pushing content to the subscriber in addition to simply responding to the subscriber’s direct requests.
::ActionCable::Channel
instances are long-lived. A channel object will be instantiated when the cable consumer becomes a subscriber, and then lives until the consumer disconnects. This may be seconds, minutes, hours, or even days. That means you have to take special care not to do anything silly in a channel that would balloon its memory footprint or whatever. The references are forever, so they won’t be released as is normally the case with a controller instance that gets thrown away after every request.
Long-lived channels (and connections) also mean you’re responsible for ensuring that the data is fresh. If you hold a reference to a user record, but the name is changed while that reference is held, you may be sending stale data if you don’t take precautions to avoid it.
The upside of long-lived channel instances is that you can use instance variables to keep reference to objects that future subscriber requests can interact with. Here’s a quick example:
class ChatChannel < ApplicationCable::Channel
def subscribed
@room = Chat::Room[params[:room_number]]
end
def speak(data)
@room.speak data, user: current_user
end
end
The #speak
action simply uses the Chat::Room
object that was created when the channel was first subscribed to by the consumer when that subscriber wants to say something in the room.
Action processing
Unlike subclasses of ::ActionController::Base
, channels do not follow a RESTful constraint form for their actions. Instead, Action Cable operates through a remote-procedure call model. You can declare any public method on the channel (optionally taking a data
argument), and this method is automatically exposed as callable to the client.
Example:
class AppearanceChannel < ApplicationCable::Channel
def subscribed
@connection_token = generate_connection_token
end
def unsubscribed
current_user.disappear @connection_token
end
def appear(data)
current_user.appear @connection_token, on: data['appearing_on']
end
def away
current_user.away @connection_token
end
private
def generate_connection_token
SecureRandom.hex(36)
end
end
In this example, the subscribed and unsubscribed methods are not callable methods, as they were already declared in Base
, but #appear
and #away
are. #generate_connection_token
is also not callable, since it’s a private method. You’ll see that appear accepts a data parameter, which it then uses as part of its model call. #away
does not, since it’s simply a trigger action.
Also note that in this example, current_user
is available because it was marked as an identifying attribute on the connection. All such identifiers will automatically create a delegation method of the same name on the channel instance.
Rejecting subscription requests
A channel can reject a subscription request in the #subscribed callback by invoking the #reject method:
class ChatChannel < ApplicationCable::Channel
def subscribed
@room = Chat::Room[params[:room_number]]
reject unless current_user.can_access?(@room)
end
end
In this example, the subscription will be rejected if the current_user
does not have access to the chat room. On the client-side, the Channel#rejected
callback will get invoked when the server rejects the subscription request.
Constant Summary
::ActiveSupport::Callbacks
- Included
Broadcasting
- Attributes & Methods
- #broadcast_to readonly
- #broadcasting_for readonly
Naming
- Attributes & Methods
- #channel_name readonly
PeriodicTimers
- Attributes & Methods
::ActiveSupport::Rescuable
- Attributes & Methods
Class Method Summary
-
.action_methods
A list of method names that should be considered actions.
- .new(connection, identifier, params = {}) ⇒ Base constructor
-
.clear_action_methods!
private
action_methods are cached and there is sometimes need to refresh them.
-
.method_added(name)
private
Refresh the cached action_methods when a new action_method is added.
::ActiveSupport::DescendantsTracker
- self
descendants | See additional method definition at line 104. |
subclasses | See additional method definition at line 100. |
Instance Attribute Summary
- #connection readonly
- #identifier readonly
- #logger readonly
- #params readonly
- #defer_subscription_confirmation? ⇒ Boolean readonly private
- #subscription_confirmation_sent? ⇒ Boolean readonly private
- #subscription_rejected? ⇒ Boolean readonly private
Streams
- Included
Callbacks
- Included
Instance Method Summary
-
#perform_action(data)
Extract the action name from the passed data and process it via the channel.
-
#subscribe_to_channel
This method is called after subscription has been added to the connection and confirms or rejects the subscription.
- #defer_subscription_confirmation! private
- #ensure_confirmation_sent private
- #reject private
-
#subscribed
private
Called once a consumer has become a subscriber of the channel.
-
#transmit(data, via: nil)
private
Transmit a hash of data to the subscriber.
-
#unsubscribed
private
Called once a consumer has cut its cable connection.
::ActiveSupport::Rescuable
- Included
#rescue_with_handler | Delegates to the class method, but uses the instance as the subject for rescue_from handlers (method calls, |
Streams
- Included
#stop_all_streams | Unsubscribes all streams associated with this channel from the pubsub queue. |
#stop_stream_for | Unsubscribes streams for the |
#stop_stream_from | Unsubscribes streams from the named |
#stream_for | Start streaming the pubsub queue for the |
#stream_from | Start streaming from the named |
#stream_or_reject_for | Calls stream_for with the given |
::ActiveSupport::Callbacks
- Included
#run_callbacks | Runs the callbacks for the given event. |
Constructor Details
.new(connection, identifier, params = {}) ⇒ Base
# File 'actioncable/lib/action_cable/channel/base.rb', line 147
def initialize(connection, identifier, params = {}) @connection = connection @identifier = identifier @params = params # When a channel is streaming via pubsub, we want to delay the confirmation # transmission until pubsub subscription is confirmed. # # The counter starts at 1 because it's awaiting a call to #subscribe_to_channel @defer_subscription_confirmation_counter = Concurrent::AtomicFixnum.new(1) @reject_subscription = nil @subscription_confirmation_sent = nil delegate_connection_identifiers end
Class Attribute Details
.periodic_timers (rw)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/periodic_timers.rb', line 9
class_attribute :periodic_timers, instance_reader: false, default: []
.periodic_timers? ⇒ Boolean
(rw)
[ GitHub ]
# File 'actioncable/lib/action_cable/channel/periodic_timers.rb', line 9
class_attribute :periodic_timers, instance_reader: false, default: []
.rescue_handlers (rw)
[ GitHub ]# File 'activesupport/lib/active_support/rescuable.rb', line 15
class_attribute :rescue_handlers, default: []
.rescue_handlers? ⇒ Boolean
(rw)
[ GitHub ]
# File 'activesupport/lib/active_support/rescuable.rb', line 15
class_attribute :rescue_handlers, default: []
Class Method Details
.action_methods
A list of method names that should be considered actions. This includes all public instance methods on a channel, less any internal methods (defined on Base
), adding back in any methods that are internal, but still exist on the class itself.
Returns
-
Set
- A set of all methods that should be considered actions.
# File 'actioncable/lib/action_cable/channel/base.rb', line 120
def action_methods @action_methods ||= begin # All public instance methods of this class, including ancestors methods = (public_instance_methods(true) - # Except for public instance methods of Base and its ancestors ActionCable::Channel::Base.public_instance_methods(true) + # Be sure to include shadowed public instance methods of this class public_instance_methods(false)).uniq.map(&:to_s) methods.to_set end end
.clear_action_methods! (private)
action_methods are cached and there is sometimes need to refresh them. .clear_action_methods!
allows you to do that, so next time you run action_methods, they will be recalculated.
# File 'actioncable/lib/action_cable/channel/base.rb', line 136
def clear_action_methods! # :doc: @action_methods = nil end
.method_added(name) (private)
Refresh the cached action_methods when a new action_method is added.
# File 'actioncable/lib/action_cable/channel/base.rb', line 141
def method_added(name) # :doc: super clear_action_methods! end
Instance Attribute Details
#broadcast_to (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/broadcasting.rb', line 11
delegate :broadcasting_for, :broadcast_to, to: :class
#broadcasting_for (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/broadcasting.rb', line 11
delegate :broadcasting_for, :broadcast_to, to: :class
#channel_name (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/naming.rb', line 23
delegate :channel_name, to: :class
#connection (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 108
attr_reader :params, :connection, :identifier
#defer_subscription_confirmation? ⇒ Boolean
(readonly, private)
[ GitHub ]
# File 'actioncable/lib/action_cable/channel/base.rb', line 237
def defer_subscription_confirmation? # :doc: @defer_subscription_confirmation_counter.value > 0 end
#identifier (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 108
attr_reader :params, :connection, :identifier
#logger (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 109
delegate :logger, to: :connection
#params (readonly)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 108
attr_reader :params, :connection, :identifier
#rescue_handlers (rw)
[ GitHub ]# File 'activesupport/lib/active_support/rescuable.rb', line 15
class_attribute :rescue_handlers, default: []
#rescue_handlers? ⇒ Boolean
(rw)
[ GitHub ]
# File 'activesupport/lib/active_support/rescuable.rb', line 15
class_attribute :rescue_handlers, default: []
#subscription_confirmation_sent? ⇒ Boolean
(readonly, private)
[ GitHub ]
# File 'actioncable/lib/action_cable/channel/base.rb', line 241
def subscription_confirmation_sent? # :doc: @subscription_confirmation_sent end
#subscription_rejected? ⇒ Boolean
(readonly, private)
[ GitHub ]
# File 'actioncable/lib/action_cable/channel/base.rb', line 249
def subscription_rejected? # :doc: @reject_subscription end
Instance Method Details
#defer_subscription_confirmation! (private)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 233
def defer_subscription_confirmation! # :doc: @defer_subscription_confirmation_counter.increment end
#ensure_confirmation_sent (private)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 227
def ensure_confirmation_sent # :doc: return if subscription_rejected? @defer_subscription_confirmation_counter.decrement transmit_subscription_confirmation unless defer_subscription_confirmation? end
#perform_action(data)
Extract the action name from the passed data and process it via the channel. The process will ensure that the action requested is a public method on the channel declared by the user (so not one of the callbacks like #subscribed).
# File 'actioncable/lib/action_cable/channel/base.rb', line 167
def perform_action(data) action = extract_action(data) if processable_action?(action) payload = { channel_class: self.class.name, action: action, data: data } ActiveSupport::Notifications.instrument("perform_action.action_cable", payload) do dispatch_action(action, data) end else logger.error "Unable to process #{action_signature(action, data)}" end end
#reject (private)
[ GitHub ]# File 'actioncable/lib/action_cable/channel/base.rb', line 245
def reject # :doc: @reject_subscription = true end
#subscribe_to_channel
This method is called after subscription has been added to the connection and confirms or rejects the subscription.
# File 'actioncable/lib/action_cable/channel/base.rb', line 182
def subscribe_to_channel run_callbacks :subscribe do subscribed end reject_subscription if subscription_rejected? ensure_confirmation_sent end
#subscribed (private)
Called once a consumer has become a subscriber of the channel. Usually the place to set up any streams you want this channel to be sending to the subscriber.
# File 'actioncable/lib/action_cable/channel/base.rb', line 202
def subscribed # :doc: # Override in subclasses end
#transmit(data, via: nil) (private)
Transmit a hash of data to the subscriber. The hash will automatically be wrapped in a JSON envelope with the proper channel identifier marked as the recipient.
# File 'actioncable/lib/action_cable/channel/base.rb', line 214
def transmit(data, via: nil) # :doc: logger.debug do status = "#{self.class.name} transmitting #{data.inspect.truncate(300)}" status += " (via #{via})" if via status end payload = { channel_class: self.class.name, data: data, via: via } ActiveSupport::Notifications.instrument("transmit.action_cable", payload) do connection.transmit identifier: @identifier, message: data end end
#unsubscribed (private)
Called once a consumer has cut its cable connection. Can be used for cleaning up connections or marking users as offline or the like.
# File 'actioncable/lib/action_cable/channel/base.rb', line 208
def unsubscribed # :doc: # Override in subclasses end