Class: ActionCable::Connection::Base

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::ActiveSupport::DescendantsTracker`
Instance Chain: self, `::ActiveSupport::Rescuable`, `Callbacks`, `::ActiveSupport::Callbacks`, `Authorization`, `InternalChannel`, `Identification`
Inherits:	Object
Defined in:	actioncable/lib/action_cable/connection/base.rb

Overview

For every WebSocket connection the Action Cable server accepts, a ::ActionCable::Connection object will be instantiated. This instance becomes the parent of all of the channel subscriptions that are created from there on. Incoming messages are then routed to these channel subscriptions based on an identifier sent by the Action Cable consumer. The Connection itself does not deal with any specific application logic beyond authentication and authorization.

Here's a basic example:

module ApplicationCable
  class Connection < ActionCable::Connection::Base
    identified_by :current_user

    def connect
      self.current_user = find_verified_user
      logger.add_tags current_user.name
    end

    def disconnect
      # Any cleanup work needed when the cable connection is cut.
    end

    private
      def find_verified_user
        User.find_by_identity(cookies.encrypted[:identity_id]) ||
          reject_unauthorized_connection
      end
  end
end

First, we declare that this connection can be identified by its current_user. This allows us to later be able to find all connections established for that current_user (and potentially disconnect them). You can declare as many identification indexes as you like. Declaring an identification means that an attr_accessor is automatically set for that key.

Second, we rely on the fact that the WebSocket connection is established with the cookies from the domain being sent along. This makes it easy to use signed cookies that were set when logging in via a web interface to authorize the WebSocket connection.

Finally, we add a tag to the connection-specific logger with the name of the current user to easily distinguish their messages in the log.

Constant Summary

`::ActiveSupport::Callbacks` - Included

CALLBACK_FILTER_TYPES

`::ActiveSupport::Rescuable` - Attributes & Methods

.rescue_handlers rw
#rescue_handlers rw
.rescue_handlers? ⇒ Boolean rw
#rescue_handlers? ⇒ Boolean rw

Class Method Summary

.new(server, socket) ⇒ Base constructor

`::ActiveSupport::DescendantsTracker` - self

descendants, subclasses, clear, disable_clear!, reject!

Instance Attribute Summary

#broadcast readonly
#config readonly
#env readonly
#executor readonly
#logger readonly
#perform_work readonly
#protocol readonly
#pubsub readonly
#request readonly
#subscriptions readonly
#server readonly private
#socket readonly private

`Callbacks` - Included

#__callbacks

Instance Method Summary

#beat
#close(reason: nil, reconnect: true)

Close the connection.
#connect

This method is called every time an Action Cable client establishes an underlying connection.
#disconnect

This method is called every time an Action Cable client disconnects.
#handle_channel_command(payload) (also: #handle_incoming)
#handle_close
#handle_incoming(payload)

Alias for #handle_channel_command.
#handle_open
#statistics

Return a basic hash of statistics for the connection keyed with identifier, started_at, #subscriptions, and request_id.
#cookies private

The cookies of the request that initiated the WebSocket connection.
#instance_variables_to_inspect private
#send_welcome_message private
#transmit(data) Internal use only

`::ActiveSupport::Rescuable` - Included

#rescue_with_handler	Delegates to the class method, but uses the instance as the subject for rescue_from handlers (method calls, `instance_exec` blocks).
#handler_for_rescue	Internal handler lookup.

`::ActiveSupport::Callbacks` - Included

#run_callbacks	Runs the callbacks for the given event.
#halted_callback_hook	A hook invoked every time a before callback is halted.

`Authorization` - Included

#reject_unauthorized_connection

Closes the WebSocket connection if it is open and returns an "unauthorized" reason.

`InternalChannel` - Included

#internal_channel, #process_internal_message, #subscribe_to_internal_channel, #unsubscribe_from_internal_channel

`Identification` - Included

#connection_identifier	Return a single connection identifier that combines the value of all the registered identifiers into a single gid.
#connection_gid

Constructor Details

.new(server, socket) ⇒ `Base`

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 68


def initialize(server, socket)
  @server = server
  @socket = socket

  @logger = socket.logger
  @subscriptions  = Subscriptions.new(self)

  @_internal_subscriptions = nil

  @started_at = Time.now
end

Class Attribute Details

.identifiers (rw)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/identification.rb', line 11


class_attribute :identifiers, default: Set.new

.identifiers? ⇒ `Boolean` (rw)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/identification.rb', line 11


class_attribute :identifiers, default: Set.new

.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: []

Instance Attribute Details

#broadcast (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 65


delegate :pubsub, :executor, :config, :broadcast, to: :server

#config (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 65


delegate :pubsub, :executor, :config, :broadcast, to: :server

#env (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 66


delegate :env, :request, :protocol, :perform_work, to: :socket, allow_nil: true

#executor (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 65


delegate :pubsub, :executor, :config, :broadcast, to: :server

#identifiers (rw)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/identification.rb', line 11


class_attribute :identifiers, default: Set.new

#identifiers? ⇒ `Boolean` (rw)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/identification.rb', line 11


class_attribute :identifiers, default: Set.new

#logger (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 63


attr_reader :subscriptions, :logger

#perform_work (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 66


delegate :env, :request, :protocol, :perform_work, to: :socket, allow_nil: true

#protocol (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 66


delegate :env, :request, :protocol, :perform_work, to: :socket, allow_nil: true

#pubsub (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 65


delegate :pubsub, :executor, :config, :broadcast, to: :server

#request (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 66


delegate :env, :request, :protocol, :perform_work, to: :socket, allow_nil: true

#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: []

#server (readonly, private)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 149


attr_reader :server, :socket

#socket (readonly, private)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 149


attr_reader :server, :socket

#subscriptions (readonly)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 63


attr_reader :subscriptions, :logger

Instance Method Details

#beat

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 142


def beat
  transmit type: ActionCable::INTERNAL[:message_types][:ping], message: Time.now.to_i
end

#close(reason: nil, reconnect: true)

Close the connection.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 121


def close(reason: nil, reconnect: true)
  transmit(
    type: ActionCable::INTERNAL[:message_types][:disconnect],
    reason: reason,
    reconnect: reconnect
  ) rescue nil
  socket.close
end

#connect

This method is called every time an Action Cable client establishes an underlying connection. Override it in your class to define authentication logic and populate connection identifiers.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 83


def connect
end

#cookies (private)

The cookies of the request that initiated the WebSocket connection. Useful for performing authorization checks.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 156


def cookies # :doc:
  request.cookie_jar
end

#disconnect

This method is called every time an Action Cable client disconnects. Override it in your class to cleanup the relevant application state (e.g., presence, online counts, etc.)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 88


def disconnect
end

#handle_channel_command(payload) Also known as: #handle_incoming

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 106


def handle_channel_command(payload)
  run_callbacks :command do
    subscriptions.execute_command payload
  end
rescue Exception => e
  rescue_with_handler(e) || raise
end

#handle_close

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 99


def handle_close
  subscriptions.unsubscribe_from_all
  unsubscribe_from_internal_channel

  disconnect
end

#handle_incoming(payload)

Alias for #handle_channel_command.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 114


alias_method :handle_incoming, :handle_channel_command

#handle_open

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 91


def handle_open
  connect
  subscribe_to_internal_channel
  send_welcome_message
rescue ActionCable::Connection::Authorization::UnauthorizedError
  close(reason: ActionCable::INTERNAL[:disconnect_reasons][:unauthorized], reconnect: false)
end

#instance_variables_to_inspect (private)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 151


def instance_variables_to_inspect
  [].freeze
end

#send_welcome_message (private)

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 160


def send_welcome_message
  # Send welcome message to the internal connection monitor channel. This ensures
  # the connection monitor state is reset after a successful websocket connection.
  transmit type: ActionCable::INTERNAL[:message_types][:welcome]
end

#statistics

Return a basic hash of statistics for the connection keyed with identifier, started_at, #subscriptions, and request_id. This can be returned by a health check against the connection.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 133


def statistics
  {
    identifier: connection_identifier,
    started_at: @started_at,
    subscriptions: subscriptions.identifiers,
    request_id: env["action_dispatch.request_id"]
  }
end

#transmit(data)

This method is for internal use only.

[ GitHub ]

# File 'actioncable/lib/action_cable/connection/base.rb', line 116


def transmit(data) # :nodoc:
  socket.transmit(data)
end

Class: ActionCable::Connection::Base

Overview

Constant Summary

::ActiveSupport::Callbacks - Included

Identification - Attributes & Methods

::ActiveSupport::Rescuable - Attributes & Methods

Class Method Summary

::ActiveSupport::DescendantsTracker - self

Instance Attribute Summary

Callbacks - Included

Instance Method Summary

::ActiveSupport::Rescuable - Included

::ActiveSupport::Callbacks - Included

Authorization - Included

InternalChannel - Included

Identification - Included

Constructor Details

.new(server, socket) ⇒ Base

Class Attribute Details

.identifiers (rw)

.identifiers? ⇒ Boolean (rw)

.rescue_handlers (rw)

.rescue_handlers? ⇒ Boolean (rw)

Instance Attribute Details

#broadcast (readonly)

#config (readonly)

#env (readonly)

#executor (readonly)

#identifiers (rw)

#identifiers? ⇒ Boolean (rw)

#logger (readonly)

#perform_work (readonly)

#protocol (readonly)

#pubsub (readonly)

#request (readonly)

#rescue_handlers (rw)

#rescue_handlers? ⇒ Boolean (rw)

#server (readonly, private)

#socket (readonly, private)

#subscriptions (readonly)

Instance Method Details

#beat

#close(reason: nil, reconnect: true)

#connect

#cookies (private)

#disconnect

#handle_channel_command(payload) Also known as: #handle_incoming

#handle_close

#handle_incoming(payload)

#handle_open

#instance_variables_to_inspect (private)

#send_welcome_message (private)

#statistics

#transmit(data)

`::ActiveSupport::Callbacks` - Included

`Identification` - Attributes & Methods

`::ActiveSupport::Rescuable` - Attributes & Methods

`::ActiveSupport::DescendantsTracker` - self

`Callbacks` - Included

`::ActiveSupport::Rescuable` - Included

`::ActiveSupport::Callbacks` - Included

`Authorization` - Included

`InternalChannel` - Included

`Identification` - Included

.new(server, socket) ⇒ `Base`

.identifiers? ⇒ `Boolean` (rw)

.rescue_handlers? ⇒ `Boolean` (rw)

#identifiers? ⇒ `Boolean` (rw)

#rescue_handlers? ⇒ `Boolean` (rw)