mirrors
/
rails
mirror of https://github.com/rails/rails
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #40736 from jonathanhefner/guide-action_cable_overview-link-api 

Link to API docs in Action Cable Overview guide [ci-skip]
This commit is contained in:
Rafael França 2020-12-02 17:33:37 -05:00 committed by GitHub
parent be11d1b6e8 0e9530b053
commit 9f1623bd34
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 38 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
guides/source/action_cable_overview.md
View File

@ -88,7 +88,8 @@ logic beyond authentication and authorization. The client of a WebSocket
connection is called the connection *consumer*. An individual user will create connection is called the connection *consumer*. An individual user will create
one consumer-connection pair per browser tab, window, or device they have open. one consumer-connection pair per browser tab, window, or device they have open.
Connections are instances of `ApplicationCable::Connection`. In this class, you Connections are instances of `ApplicationCable::Connection`, which extends
[`ActionCable::Connection::Base`][]. In `ApplicationCable::Connection`, you
authorize the incoming connection, and proceed to establish it if the user can authorize the incoming connection, and proceed to establish it if the user can
be identified. be identified.
@ -116,7 +117,7 @@ module ApplicationCable
end end
``` ```
Here `identified_by` is a connection identifier that can be used to find the Here [`identified_by`][] designates a connection identifier that can be used to find the
specific connection later. Note that anything marked as an identifier will automatically specific connection later. Note that anything marked as an identifier will automatically
create a delegate by the same name on any channel instances created off the connection. create a delegate by the same name on any channel instances created off the connection.
@ -138,12 +139,14 @@ can use this approach:
verified_user = User.find_by(id: cookies.encrypted['_session']['user_id']) verified_user = User.find_by(id: cookies.encrypted['_session']['user_id'])
``` ```
[`ActionCable::Connection::Base`]: https://api.rubyonrails.org/classes/ActionCable/Connection/Base.html
[`identified_by`]: https://api.rubyonrails.org/classes/ActionCable/Connection/Identification/ClassMethods.html#method-i-identified_by
#### Exception Handling #### Exception Handling
By default, unhandled exceptions are caught and logged to Rails' logger. If you would like to By default, unhandled exceptions are caught and logged to Rails' logger. If you would like to
globally intercept these exceptions and report them to an external bug tracking service, for globally intercept these exceptions and report them to an external bug tracking service, for
example, you can do so with example, you can do so with [`rescue_from`][]:
[`rescue_from`](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from).
```ruby ```ruby
# app/channels/application_cable/connection.rb # app/channels/application_cable/connection.rb
@ -160,11 +163,13 @@ module ApplicationCable
end end
``` ```
[`rescue_from`]: https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from
### Channels ### Channels
A *channel* encapsulates a logical unit of work, similar to what a controller does in a A *channel* encapsulates a logical unit of work, similar to what a controller does in a
regular MVC setup. By default, Rails creates a parent `ApplicationCable::Channel` class regular MVC setup. By default, Rails creates a parent `ApplicationCable::Channel` class
for encapsulating shared logic between your channels. (which extends [`ActionCable::Channel::Base`][]) for encapsulating shared logic between your channels.
#### Parent Channel Setup #### Parent Channel Setup
@ -189,6 +194,8 @@ class AppearanceChannel < ApplicationCable::Channel
end end
``` ```
[`ActionCable::Channel::Base`]: https://api.rubyonrails.org/classes/ActionCable/Channel/Base.html
A consumer could then be subscribed to either or both of these channels. A consumer could then be subscribed to either or both of these channels.
#### Subscriptions #### Subscriptions
@ -209,7 +216,7 @@ end
#### Exception Handling #### Exception Handling
As with `ActionCable::Connection::Base`, you can also use `rescue_from` on a As with `ApplicationCable::Connection`, you can also use [`rescue_from`][] on a
specific channel to handle raised exceptions: specific channel to handle raised exceptions:
```ruby ```ruby
@ -300,9 +307,9 @@ consumer.subscriptions.create({ channel: "ChatChannel", room: "2nd Room" })
### Streams ### Streams
*Streams* provide the mechanism by which channels route published content *Streams* provide the mechanism by which channels route published content
(broadcasts) to their subscribers. The following example would (broadcasts) to their subscribers. For example, the following code uses
subscribe to the broadcasting `chat_Best Room` if the room parameter [`stream_from`][] to subscribe to the broadcasting named `chat_Best Room` when
is `Best Room`: the value of the `:room` parameter is `"Best Room"`:
```ruby ```ruby
# app/channels/chat_channel.rb # app/channels/chat_channel.rb
@ -313,10 +320,18 @@ class ChatChannel < ApplicationCable::Channel
end end
``` ```
If you have a stream that is related to a model, then the broadcasting used Then, elsewhere in your Rails application, you can broadcast to such a room by
can be generated from the channel and model. The following example would calling [`broadcast`][]:
subscribe to a broadcasting like `comments:Z2lkOi8vVGVzdEFwcC9Qb3N0LzE`,
where `Z2lkOi8vVGVzdEFwcC9Qb3N0LzE` is the GlobalID of the Post model. ```ruby
ActionCable.server.broadcast("chat_Best Room", body: "This Room is Best Room.")
```
If you have a stream that is related to a model, then the broadcasting name
can be generated from the channel and model. For example, the following code
uses [`stream_for`][] to subscribe to a broadcasting like
`comments:Z2lkOi8vVGVzdEFwcC9Qb3N0LzE`, where `Z2lkOi8vVGVzdEFwcC9Qb3N0LzE` is
the GlobalID of the Post model.
```ruby ```ruby
class CommentsChannel < ApplicationCable::Channel class CommentsChannel < ApplicationCable::Channel
@ -327,13 +342,18 @@ class CommentsChannel < ApplicationCable::Channel
end end
``` ```
You can then broadcast to this channel like this: You can then broadcast to this channel by calling [`broadcast_to`][]:
```ruby ```ruby
CommentsChannel.broadcast_to(@post, @comment) CommentsChannel.broadcast_to(@post, @comment)
``` ```
### Broadcasting [`broadcast`]: https://api.rubyonrails.org/classes/ActionCable/Server/Broadcasting.html#method-i-broadcast
[`broadcast_to`]: https://api.rubyonrails.org/classes/ActionCable/Channel/Broadcasting/ClassMethods.html#method-i-broadcast_to
[`stream_for`]: https://api.rubyonrails.org/classes/ActionCable/Channel/Streams.html#method-i-stream_for
[`stream_from`]: https://api.rubyonrails.org/classes/ActionCable/Channel/Streams.html#method-i-stream_from
### Broadcastings
A *broadcasting* is a pub/sub link where anything transmitted by a publisher A *broadcasting* is a pub/sub link where anything transmitted by a publisher
is routed directly to the channel subscribers who are streaming that named is routed directly to the channel subscribers who are streaming that named
@ -343,25 +363,6 @@ Broadcastings are purely an online queue and time-dependent. If a consumer is
not streaming (subscribed to a given channel), they'll not get the broadcast not streaming (subscribed to a given channel), they'll not get the broadcast
should they connect later. should they connect later.
Broadcasts are called elsewhere in your Rails application:
```ruby
WebNotificationsChannel.broadcast_to(
current_user,
title: 'New things!',
body: 'All the news fit to print'
)
```
The `WebNotificationsChannel.broadcast_to` call places a message in the current
subscription adapter's pubsub queue under a separate broadcasting name for each user.
The default pubsub queue for Action Cable is `redis` in production and `async` in development and
test environments. For a user with an ID of 1, the broadcasting name would be `web_notifications:1`.
The channel has been instructed to stream everything that arrives at
`web_notifications:1` directly to the client by invoking the `received`
callback.
### Subscriptions ### Subscriptions
When a consumer is subscribed to a channel, they act as a subscriber. This When a consumer is subscribed to a channel, they act as a subscriber. This
@ -745,10 +746,12 @@ in the development environment.
### Consumer Configuration ### Consumer Configuration
To configure the URL, add a call to `action_cable_meta_tag` in your HTML layout To configure the URL, add a call to [`action_cable_meta_tag`][] in your HTML layout
HEAD. This uses a URL or path typically set via `config.action_cable.url` in the HEAD. This uses a URL or path typically set via `config.action_cable.url` in the
environment configuration files. environment configuration files.
[`action_cable_meta_tag`]: https://api.rubyonrails.org/classes/ActionCable/Helpers/ActionCableHelper.html#method-i-action_cable_meta_tag
### Worker Pool Configuration ### Worker Pool Configuration
The worker pool is used to run connection callbacks and channel actions in The worker pool is used to run connection callbacks and channel actions in