Broadcasting to Resources

stream_for and broadcast_to
Up until now, we've been broadcasting CableReady operations to Channels using string-based stream identifiers like "sailors". 30 Helens agree: "sailors" will get you to your chosen port of call.
ActionCable - and by extension, CableReady - also support broadcasting to a Rails resource, like Helen.find(30) or current_user. It does this using the Global ID functionality in Rails, which allows you to create a unique string that can identify an ActiveRecord model.
Instead of stream_from, we're going to use the stream_for method:
1
class HelensChannel < ApplicationCable::Channel
2
  def subscribed
3
    stream_for Helen.find(params[:id])
4
  end
5
end
Copied!
There is also stream_or_reject_for, which is intended for scenarios where you're looking up a record based on params, as in the example above. If you're dealing with sensitive information, stream_or_reject_for is a solid practice.
On the client, we subscribe to the Channel in the exact same way as you would with stream_from:
1
consumer.subscriptions.create(
2
  {
3
    channel: 'HelensChannel',
4
    id: 30
5
  },
6
  {
7
    received (data) { if (data.cableReady) CableReady.perform(data.operations) }
8
  }
9
)
Copied!
Now, we're able to broadcast_to the Channel so that anyone currently subscribed to that resource will receive the operations:
1
helen = Helen.find(30)
2
cable_ready[HelensChannel].dispatch_event.broadcast_to(helen)
Copied!
As you can see, we have traded our string-based stream identifiers for constant-based identifiers; specifically, the Channel class constant. This is paired up with the broadcast_to method, which requires that you pass a resource to it.
This allows us to shift our mental model away from "who are we broadcasting to?" to "what is each individual user interested in?"
broadcasting_for: worth it?
A quick digression: ActionCable::Channel provides a class method, broadcasting_for, which provides another way to build string identifiers. If you have a HelensChannel, you can:
1
HelensChannel.broadcasting_for(Post.first)
2
=> "helens:Z2lkOi8vcHJvZ2VuaXRvci9Vc2VyLzE"
Copied!
This is a perfectly valid way to generate a string identifer for a resource, instead of using the stream_for/broadcast_to magic that we discuss on this page.
The argument to be made against it is that it is completely dumb: it has no knowledge of your Channel class or what kind of data or purpose it represents. It doesn't matter if HelensChannel knows what a Post is or not; it's just joining strings together.
The author's opinion is that broadcasting_for is not bad, but stream_for/broadcast_to is more powerful and presents more interesting creative possibilities.
Why is this awesome?
stream_from and broadcast make it easy to develop reactive interfaces with Rails.
stream_for and broadcast_to actually unlock new feature and UX design possibilities.
A brief refresher on why SPAs are even a thing, and not just the punch-line to a cautionary tale
React was created to address the technical challenges involved in the syncronization of notifications, likes and comments on different parts of a user's page, in real-time.
When you scroll through your unique newsfeed, everything you see on your screen (or within a few dozen pixels of being on your screen) is a carefully orchestrated close-up magic trick. Our brains are fooled into perceiving that newsfeed as one long, living document.
What's really happening is that each item on your feed has been pre-cached, with a minimum viable DOM structure and just enough meta-data to allow it to subscribe itself to a firehose of scoped updates pertaining to that item. If the item is scrolled off the page far enough or the tab is inactive for more than a minute or three, the subscription is discarded and the item purges itself from the DOM.
We don't need React to do this anymore
With CableReady, it's possible to present your users with composable, reactive interface elements that subscribe to their own real-time event stream with a few dozen lines of code.
This is not hyperbole. Do you remember the first time you saw ActiveRecord working and thought, "I must be missing something, because this is impossible?"
This is the same level of black magic. ⚗️
Setting up this pattern [which Facebook broke the web to implement] with CableReady requires about the same effort as updating a ActiveRecord model attribute with an Ajax fetch call:
1.Generate a CRUD resource and matching ActionCable Channel, e.g. stream_for Helen.find(params[:id])
2.Add a Stimulus controller that is also an ActionCable subscription consumer and a CableReady performer to the outermost element of the item partial or ViewComponent
3.Set the consumer to subscribe to its own Channel with model id metadata from the rendered markup
4.Allow users to add/remove specific resource instances, perhaps via a has_many relationship or even an integer array attribute
5.Everyone who changes attributes of the item (think Likes) triggers a broadcast_to that morphs the markup of the resource for anyone who has that instance displayed on their screen
Fewer promises, more consciousness-expanding code samples plz
1. Configure channel
app/channels/helens_channel.rb
1
class HelensChannel < ApplicationCable::Channel
2
  def subscribed
3
    stream_or_reject_for Helen.find(params[:id])
4
  end
5
end
Copied!
2. Setup partial
app/views/helens/_helen.html.erb
1
<div data-controller="helen"
2
     data-helen-id-value="<%= helen.id %>"
3
     id="<%= dom_id(helen) %>">I am Helen #<%= helen.id %>.
4
</div>
Copied!
3. Prepare subscriber
app/javascript/controllers/helen_controller.js
1
import { Controller } from 'stimulus'
2
import CableReady from 'cable_ready'
3
​
4
export default class extends Controller {
5
  static values = { id: Number }
6
​
7
  connect() {
8
    this.channel = this.application.consumer.subscriptions.create(
9
      {
10
        channel: 'HelensChannel',
11
        id: this.idValue
12
      },
13
      {
14
        received (data) { if (data.cableReady) CableReady.perform(data.operations) }
15
      }
16
    )
17
  }
18
​
19
  disconnect() {
20
    this.channel.unsubscribe()
21
  }
22
}
Copied!
4. Create UI for users to select and render their favorite Helens: left as an exercise for the developer 👵
5. Give each Helen the power to automatically broadcast updates to every subscribed client instance
app/models/helen.rb
1
class Helen < ApplicationRecord
2
  after_update do
3
    cable_ready[HelensChannel].morph(
4
      selector: dom_id(self),
5
      html: render(self)
6
    ).broadcast_to(self)
7
  end
8
end
Copied!
Victory lap: use StimulusReflex to celebrate Helen's birthday 🎂
app/views/helens/_helen.html.erb
1
<div data-controller="helen"
2
     data-helen-id-value="<%= helen.id %>"
3
     data-reflex="click->Helen#birthday"
4
     id="<%= dom_id(helen) %>">Helen #<%= helen.id %> is <%= helen.age %>.
5
</div>
Copied!
app/reflexes/helen_reflex.rb
1
class HelenReflex < ApplicationReflex
2
  def birthday
3
    Helen.find(element["data-helen-id-value"]).age.increment!
4
    morph :nothing
5
  end
6
end
Copied!
Step 3 assumes that this.application.consumer is coming from the controller index.
Step 5 assumes that render is delegated to ApplicationController.
With easily implemented, many-to-many reactive morph primatives available, developers can start structuring their interfaces differently while making bolder feature scope decisions.
For example, this pattern blurs the distinction between (and justification for) the traditional separation betwen "index" and "show" views. Instead of demanding page-based navigation into detail views, next-generation Rails interfaces can use an IntersectionObserver and a CSS framework with a responsive grid to just drill into the available data, complete with a slick, faceted search UI mixed in as a concern.
Since all websocket traffic is moved through one Connection and Channel subscription overhead is cheaper than unsorted recycling, it means that developers will be free to build interfaces where it's no more computationally expensive to use components that update themselves - immediately after server-side state changes - than it is to just render static HTML.
Helens
One of the few ways that the future is likely to be similar to the past is that when fundamentally new tools become available, smart young people quickly start building things that simply didn't and likely couldn't have existed before.
Ironically, Facebook could only make React do all of the real-time magic because they have some of the smartest developers on the planet working on the back-end of their UI.
With CableReady, what Facebook spent tens of millions of dollars engineering not so long ago is available to every Rails developer, for free.
broadcast_to current_user
Many of us use the current_user pattern so often that we can almost forget that it's a resource. You know what doesn't forget? CableReady.
Assuming that you have your Connection class set up to be identified by the current user...
app/channels/application_cable/connection.rb
1
module ApplicationCable
2
  class Connection < ActionCable::Connection::Base
3
    identified_by :current_user
4
​
5
    def connect
6
      reject_unauthorized_connection unless self.current_user = env["warden"].user
7
    end
8
  end
9
end
Copied!
... you can run rails g channel users to create a UsersChannel.
Set up UsersChannel to stream_for current_user:
1
class UsersChannel < ApplicationCable::Channel
2
  def subscribed
3
    stream_for current_user
4
  end
5
end
Copied!
The cool thing about this is that there's no client code changes necessary. Just let your standard client-side app/javascript/channels/users_channel.js connect, and ActionCable will pull in the current_user reference from your Connection class, no params required.
1
cable_ready[UsersChannel].text_content().broadcast_to(current_user)
Copied!
You can broadcast to the current_user from anywhere in your app.
You can clone and experiment with the "streamfor" sample application that demonstrates using broadcast_to to send updates to current_user.
broadcast_to multiple resources
Like broadcast, broadcast_to supports streaming to multiple constant-based identifiers at once, as well as holding back the purging of the queues with clear: false. When called without any identifiers, it will broadcast all queues with constant-based stream names.
1
cable_ready[SweetChannel].morph
2
cable_ready[SourChannel].inner_html
3
cable_ready.broadcast_to(current_user, SweetChannel, SourChannel, clear: false)
4
cable_ready.broadcast_to(current_user, SweetChannel, clear: false)
5
cable_ready.broadcast_to(current_user, SourChannel)
6
cable_ready.broadcast_to(current_user)
Copied!
This sent operations to: SweetChannel, SourChannel, SweetChannel, SourChannel, SweetChannel. That last line would have also broadcast SourChannel, but that queue was cleared on line 5.
Broadcasting to multiple resources is a more useful power tool than the equivalent broadcast to multiple people. Many times, a user takes an action that will update elements that represent several resources, located in different parts of the DOM.
For example, hitting "Publish" or flipping a resource from Public to Private with a toggle button could update counts, prompt notifications and change background colors.
broadcast_to allows the developer to queue up all required interface updates on their respective Channels before delivering them with a single, brutal command.
Using Signed Global ID for lookups
It's a solid practice to obscure potentially sensitive model id metadata in your views. For some applications, slugs are a good approach. Other times, Signed Global IDs (aka sgid) are a powerful choice because you cannot reverse engineer the model or id from the resulting string. You can even generate sgids which are use-limited.
If you set up your ApplicationRecord as we suggested in CableReady Everywhere, you can just use the sgid method on your model:
app/views/helens/_helen.html.erb
1
<div data-controller="helen" 
2
     data-helen-sgid-value="<%= helen.sgid %>"
3
     id="<%= helen.sgid %>">
4
</div>
Copied!
Modify your Stimulus controller to process a string-based sgid instead of an id:
app/javascript/controllers/helen_controller.js
1
import { Controller } from 'stimulus'
2
import CableReady from 'cable_ready'
3
​
4
export default class extends Controller {
5
  static values = { sgid: String }
6
​
7
  connect() {
8
    this.subscription = this.application.consumer.subscriptions.create(
9
      {
10
        channel: 'HelensChannel',
11
        sgid: this.sgidValue
12
      },
13
      {
14
        received (data) { if (data.cableReady) CableReady.perform(data.operations) }
15
      }
16
    )
17
  }
18
​
19
  disconnect() {
20
    this.subscription.unsubscribe()
21
  }
22
}
Copied!
Instead of using find, just hand the parameter off to GlobalID::Locator:
app/channels/helens_channel.rb
1
class HelensChannel < ApplicationCable::Channel
2
  def subscribed
3
    stream_for GlobalID::Locator.locate_signed params[:sgid]
4
  end
5
end
Copied!
We will have to provide our own selector string, with a # prepended to the sgid:
app/models/helen.rb
1
class Helen < ApplicationRecord
2
  after_update do
3
    cable_ready[HelensChannel].morph(
4
      selector: "##{self.sgid}",
5
      html: render(self)
6
    ).broadcast_to(self)
7
  end
8
end
Copied!
If you are using Signed Global IDs to do lookups, use of the dom_id helper becomes impossible as it reveals the model and id. Use the sgid as your id and you won't compromise the security you get with Signed Global IDs.
Broadcasting to new resources
Combining stream_for and stream_from
Building on the "Multiple Identifiers" and "Stream Identifiers with logic" sections on the Stream Identifiers page, it is possible to stream_for multiple resources in one Channel, making use of ternary logic operators and any other decision making structure that might be applicable to your application. After all, if you have instantiated a model instance, you've ready used a substantial amount of logic that is hidden away behind syntactic magic.
broadcast_to is designed to enable shared experiences around resources. A resource that doesn't exist yet is fundamentally difficult to collaborate on. Yet, when you create an empty Google Doc and share editing rights, the document already exists in every meaningful way. If we want a similar outcome, we have to find creative ways to operate on resources that aren't persisted and might not pass validations.
In many cases, the best solution would be to save the new resource before displaying it to the user(s). You can delete unused stub resources with a recurring cleanup job.
If pre-saving is not feasible for your application, perhaps you could generate a UUID on the client and use that to create a temporarily subscription. If a UUID param arrives, establish the subscription and then create the model instance you need. Send the id of that model back to the client:
app/channels/helens_channel.rb
1
class HelensChannel < ApplicationCable::Channel
2
  def subscribed
3
    if params[:id]
4
      stream_for(Helen.find(params[:id]))
5
    else
6
      stream_from(params[:uuid])
7
      helen = Helen.create # sure, why not
8
      ActionCable.server.broadcast(params[:uuid], helen.id)
9
    end
10
  end
11
end
Copied!
Seeing that there is no initial id value, we create a temporary UUIDv4 for the new resource and send that to the server. When the server sends us an integer back, we can set the idValue before unsubscribing from the channel and forcing another controller connect method. After all, it really is just a method:
app/javascript/controllers/helen_controller.js
1
import { Controller } from 'stimulus'
2
import CableReady from 'cable_ready'
3
​
4
const uuidv4 = () => {
5
  const crypto = window.crypto || window.msCrypto
6
  return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, c =>
7
    (
8
      c ^
9
      (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (c / 4)))
10
    ).toString(16)
11
  )
12
}
13
​
14
export default class extends Controller {
15
  static values = { id: Number }
16
​
17
  initialize() {
18
    this.uuid = uuidv4()
19
  }
20
​
21
  connect() {
22
    this.channel = this.application.consumer.subscriptions.create(
23
      {
24
        channel: 'HelensChannel',
25
        id: this.hasIdValue ? this.idValue : null,
26
        uuid: this.uuid
27
      },
28
      {
29
        received (data) {
30
          if (data.cableReady) CableReady.perform(data.operations)
31
          else {
32
            this.idValue = data
33
            this.channel.unsubscribe()
34
            this.connect()
35
          }
36
        }
37
      }
38
    )
39
  }
40
​
41
  disconnect() {
42
    this.channel.unsubscribe()
43
  }
44
}
Copied!
This was a pretty wacky example but it's here to get you thinking about how to use the standard ActionCable primatives alongside the abstractions that Stimulus and CableReady make possible.
Anyhow, let's wrap up with a few important details to keep in mind when combining stream_from and stream_for together:
cable_ready["helen-fans"] and cable_ready[HelensChannel] are separate operation queues
broadcast can only work with string-based stream identifiers
broadcast_to can only work with constant-based stream identifiers
if you use them both at the same time, you might have a brain tumor; good luck 🧠
if you come up with an alternative approach for unpersisted records, tell us about it​