Proposal for Turbo8: rename Turbo Streams to Turbo Actions

[drnic]

Proposal

• naming around "sending changes to the browser" are renamed "Turbo Actions"
• <turbo-stream> changed to <turbo-action>
• format.turbo_stream renamed to format.turbo or format.turbo_action

Conceived by @drnic and @marcoroth

Why

There is somehow an incredible cognitive load to remembering how "Turbo" works. I believe renaming the collectible concepts around "Turbo Streams" towards "Turbo Actions" would help.

"Streams" infers websockets, actioncable, or perhaps a flow of something in two directions.

But it is Turbo Broadcasting that performs the websocket behaviour. What does TB do? It sends actions to the browser. What are these actions called? Oddly, they are called Streams.

Instead, the principle of Turbo Streams is to make a change to the DOM. Perhaps it's the DOM of the caller of a controller action. Perhaps it's the DOM of a broadcast recipient.

We'd like to consider renaming Turbo Streams to Turbo Actions.

[dhh]

Before settling on Turbo Streams, we considered just calling it Turbo Actions. But ultimately decided to go with streams because it both worked better as container concept for something that could include multiple actions, and to imply the use as page updates that were flowing in response to controller actions and model changes.

Here's how we currently describe what Turbo Streams are on the home page:

Turbo Streams deliver page changes over WebSocket, SSE or in response to form submissions using just HTML and a set of CRUD-like actions.

And here's the longer description in the guide:

Turbo Streams deliver page changes as fragments of HTML wrapped in self-executing <turbo-stream> elements. Each stream element specifies an action together with a target ID to declare what should happen to the HTML inside it. These elements are delivered by the server over a WebSocket, SSE or other transport to bring the application alive with updates made by other users or processes.

How would you write that using just Turbo Action as the name in a way that would be a big step up in clarity, as to warrant the name and API change? I'm struggling a bit to conceive on something that's so much simpler as to justify that.

Re:

But it is Turbo Broadcasting that performs the websocket behaviour. What does TB do? It sends actions to the browser. What are these actions called? Oddly, they are called Streams.

You broadcast actions that are delivered over streams. The stream is the pipe, the action is what goes in the pipe.

Very open to continue to improving our documentation! We should have more examples, in particular. More fleshed out tutorials too. I think getting started on these parts of the equation are probably going to do more for teaching people how to use Turbo than renaming would. Not that the two have to necessarily be in conflict, but I think it does suggest where we'd gain the most.

[drnic]

Thanks David.

Yes it is a huge ask to say "I think I'd grok the distinct parts of this thing; how it all works; what I get for free, what I can do etc if we renamed a component."

In part I guess this discussion is one person's cry for help. I've relearned Turbo/Hotwired numerous times. I go away from solving problems with Turbo, come back, and it's confusing to me again. Maybe I've never truly read the docs end to end for all the components. Yeah, that doesn't sound like something I'd have done.

Proposing renaming Streams to Actions was a bite sized attempt to tease out a part of cognitive challenge I've had. To abbreviate a conversation with @marcoroth "Oh a 'stream' is an action to change something on the DOM? Got it. Let's rename it."

I'm not yet clever enough/learned enough to state clearly the other challenges I have. And some are probably embarrassing to write in public :)

I'm sorry that this suggestion is too much change for the unknown benefit.

It has helped me at least to figure out that I will call them Turbo Stream Actions inside my own head from now on.

Thanks.

[dhh]

It's a fair point to bring up! Nothing should ever be beyond for reconsideration. But obviously it's a pretty substantial change, including API changes, so the win has to be equally substantial! And alternatives considered as well.

And maybe the missing bit here, in part, is describing the streams concept as the pipe or the transport layer and the actions as the bits or the packages going over it.

Either way, happy to keep this open for consideration for Turbo 8. Which is a bit off anyway. And hopefully we can see how far we can get improving overall documentation before then 👍

[tobyzerner]

I too found the "stream" terminology confusing at first. Having worked with Turbo a fair bit I've wrapped my head around it now, but it still doesn't feel overly intuitive. A significant chunk of my use of streams has been in response to form submissions, where the terminology feels misplaced, because you're not "streaming" changes, you're kind of just sending them back in a HTTP response...

I think the issue is, as you've pointed out, the "stream" is the transport and the "action" is the payload. And perhaps the focus needs to be placed more on the "action" part as the main concept, because that's really where the money is. The transport is secondary, whether it comes over a stream or just in a plain HTTP response.

Here's how I'd imagine that paragraph rewritten:

Turbo Actions are instructions for patching the DOM which can be delivered by the server over a WebSocket, SSE or in response to form submissions. They are fragments of HTML wrapped in self-executing <turbo-action> elements. Each action element specifies an operation together with a target ID to declare what should happen to the HTML inside it.

[tleish]

I've seen this misunderstanding over and over from developers I work with and in the Hotwire Discussion. Developers immediately understand turbo-frame from the name, but get confused from turbo-stream. The majority seem to initially think turbo-streams only work with streaming content over web sockets and do now know it also works via HTTP request. It is spelled out in the documentation, but we know how well others read all documentation.

I think turbo-element, turbo-dom or turbo-node makes it easier to explain. These alternative suggestions echo familiar terms used in manipulating DOM. Just like turbo-frame echos the familiar iframe HTML concept.

I would consider an alias (instead of completely replacing turbo-stream) for backwards compatibility.

customElements.define("turbo-element", StreamElement)

[tleish]

I've seen this misunderstanding over and over from developers I work with and in the Hotwire Discussion.

• https://discuss.hotwired.dev/t/how-to-delete-a-specific-frame/4130/5
• https://discuss.hotwired.dev/t/finally-understanding-turbo-stream/1964
• https://discuss.hotwired.dev/t/tip-turbo-stream-with-http-responses-including-get/3393

[brentgreeff]

I recommend "Turbo Templates"

create.tt.erb

Having built a Rails 6 app using create.js.erb approach, I have been very confused by:

• as TURBO_STREAM
  in the log. - it did take me quite a bit of time to realise that I needed create.turbo_stream.erb - I think this is awesome - brilliant really - but it does break all my existing forms.

• later on - I realise that I dont need a template at all for turbo_streams.

Excuse the "stream" of consciousness, but the learning path might be revealing.

This is my controller code, and its the code that seems logical to me. - in the case of having a "turbo-template"

@spaceship = Spaceship.new( safe_params )

if @spaceship.save
  flash.now[:success] = 'New spaceship added!'
else
  flash.now[:error] = 'Error adding spaceship'
end

Why do we get Completed 204 No Content and not template missing - add create.turbo_stream.erb?
Maybe it's just me, but if I got this descriptive error, or a message in the log - some hint that I needed to add this file, - that would have been enough to get the rest of the info from google.

I did lie in bed and think - OMG - I didnt have redis running - thats why it wasnt working.

After some research today I realise that turbo-streams works with html returned from the controller, or turbo_stream.erb templates.

I might be wrong, but I dont think the blog example here : https://rubyonrails.org/ contains a turbo_stream.erb template.

I have read everything here: https://turbo.hotwired.dev/handbook/introduction
and googled for ages, but I cant find how to switch my form - from using stream.erb back to the rails6 default of js.erb - I dont want to rewrite all my forms right now.

My RJS, - same code worked in rails-6.

I can see that this is a great upgrade, but I really think the handbook needs a chapter on upgrading from rails 6 to 7 - or maybe RJS in Rails 7. - sure - its has been superseded now, but this has probably been the hardest rails version upgrade I have done. - Rails6 was easy. - RJS - I know what that looks like.

This page - https://turbo.hotwired.dev/handbook/introduction delves first into Turbo Frames and then into Turbo Streams - that seems like the wrong way round - If I am building a form, it has various aspects.

• it has a new state, - a success state, and a error state.
• the error state is composed of the flash error and the model validation error messages.
• the success just has a flash message.

I think an example like this would be most useful in the introduction - since at least to me, it seems like the bedrock of "normal" rails apps.

Maybe this could be done as a "Quick start Guide" - something more cookbook and less theoretical.

For instance, in that example of a basic form - would I use Turbo Streams or Turbo Frames or a combination of both, - would I need a splash of Stimulus - I don't know. -
After more research today, It might be nice to start with a controller that returns html, - then add a turbo_stream.erb - explain what that gives us above the generic html response, and then add some turbo-frames, - explaining what extra that gives us, and then add stimulus - and explain what that gives us.

ie a journey of discovering comparing each way of doing a form.

• update - I have got a few forms now that use turbo_stream.erb and a few that dont - and I can see how the controllers must differ - but I think that this is too clever.

• I have been stuck now on a form for 2 hours, - I am trying local: false - remote: false - I have no template in this case.

These options seem to have no effect - I always get Processing by PasswordResetsController#update as TURBO_STREAM

How do I turn this off?

In the controller I haverender :edit, status: :unprocessable_entity - but there is some kind of weird magic redirect.

I, [2022-05-31T18:24:08.061211 #34675]  INFO -- : Completed 422 Unprocessable Entity in 306ms (ActiveRecord: 40.1ms | Allocations: 6877)

F, [2022-05-31T18:24:08.063116 #34675] FATAL -- :   
ActiveRecord::RecordInvalid (Validation failed: Password confirmation doesn't match Password, Password confirmation can't be blank):
  
app/controllers/password_resets_controller.rb:50:in `update'
D, [2022-05-31T18:24:08.355944 #34675] DEBUG -- :   Rendering layout /Users/brentgreeff/.rvm/gems/ruby-3.0.4@axs-new/gems/actionpack-7.0.3/lib/action_dispatch/middleware/templates/rescues/layout.erb
D, [2022-05-31T18:24:08.356135 #34675] DEBUG -- :   Rendering /Users/brentgreeff/.rvm/gems/ruby-3.0.4@axs-new/gems/actionpack-7.0.3/lib/action_dispatch/middleware/templates/rescues/diagnostics.html.erb within rescues/layout
2022-05-31 18:24:08 +0200
I, [2022-05-31T18:24:08.470062 #34675]  INFO -- : Processing by PasswordResetsController#edit as HTML

I found out eventually that the method - in a gem I am calling - raises an exception. - why are we redirecting? Whats wrong with a good ole exception message and stack trace in development?

I feel like I have lost control of my rails application - its like some kind of AI - trying to intuit what I am trying to do - and getting it wrong some of the time - but when it guesses wrong - it really - gets it wrong.

I am sure - in a few weeks, I will be comfortable with this - but just going from rails 6 to 7 - the number of... (expletive deleted) - moments is pretty high.

[koenhandekyn]

I'm a seasoned dev/arch/cto - aka old guy - and i have to add that i made the same mistake. i basically misunderstood turbo streams, assuming it was a websocket thingie, jumping to conclusions. the fact that you easily find content where turbo streams is used over websockets kept me locked in that wrong state of mind for way to long :) Boy I went 'aha' when I started using it in the basic request/response form.

We know the joke about naming things, but yes it's hard. documentation can help but I don't think you can easily fix this purely with documentation. we are all 'trained' to quickly scan information because we have such an overload of it, making assumptions all the time. We read things with prejudice, and we can't really help it.

Rename or not, I can't tell.
Just gather the 'statistics' i'd say :)

[TastyPi]

I'm a seasoned dev/arch/cto - aka old guy - and i have to add that i made the same mistake. i basically misunderstood turbo streams, assuming it was a websocket thingie, jumping to conclusions. the fact that you easily find content where turbo streams is used over websockets kept me locked in that wrong state of mind for way to long :) Boy I went 'aha' when I started using it in the basic request/response form.

I keep seeing this confusion come up in #138. I really thing it should be renamed, maybe like "Turbo Mutations" or something, to make it clear they update the page.

[nemesit]

how about turbo operations

[fxn]

In HTML, <p> is for paragraph, <a> for anchor, and <img> is for image. Users expect <turbo-stream> to be a stream, but that is not a stream as defined by Turbo. It is an action, so it should read <turbo-action>.

Before settling on Turbo Streams, we considered just calling it Turbo Actions. But ultimately decided to go with streams because it both worked better as container concept for something that could include multiple actions

You broadcast actions that are delivered over streams. The stream is the pipe, the action is what goes in the pipe.

Exactly.

[fxn]

The vocabulary around Turbo Streams is extremely confusing in general. I just read in the documentation of the Broadcastable module:

Turbo streams can be broadcast directly from models

No, you do not broadcast streams, you broadcast actions, you send actions to clients (as @dhh said above). This is a symptom of the general issue. I believe this needs a pass to make the terminology and markup more clear.