DEV Community: Ayush Newatia

Rack for Ruby: Socket Hijacking

Ayush Newatia — Wed, 04 Dec 2024 14:00:00 +0000

In the first part of this series, we set up a basic Rack app, learned how to process a request and send a response.

In this post, we'll take over connections from Rack and hold persistent connections to enable pathways such as WebSockets.

First, though, let's look at how an HTTP connection actually works.

HTTP Connections

As this diagram shows, a TCP socket is opened, and a request is sent to a server. The server responds and closes the connection. All communication is in plain text.

Using a technique called socket hijacking, we can take control of a socket from Rack when a request comes in. Rack offers two techniques for socket hijacking:

Partial hijack: Rack sends the HTTP response headers and hands over the connection to the application.
Full hijack: Rack simply hands over the connection to the client without writing anything to the socket.

Partial Hijacking

This is how you do a partial hijack:

class App
  def call(env)
    body = proc do |stream|
      5.times do
        stream.write "#{Time.now}\n\n"
        sleep 1
      end
    ensure
      stream.close
    end

    [200, { "content-type" => "text/plain", "rack.hijack" => body }, []]
  end
end

rack.hijack is a Rack header, set in the same Hash as the HTTP response headers. Rack will look for such headers and process them as per the specification, instead of writing them to the HTTP response.

Run the above app and curl to it. You'll see that it writes the time at one-second intervals.

$ curl -i localhost:9292

Full Hijacking

This is how you'd do a full hijack:

class App
  def call(env)
    headers = [
      "HTTP/1.1 200 OK",
      "Content-Type: text/plain"
    ]

    stream = env["rack.hijack"].call
    stream.write(headers.map { |header| header + "\r\n" }.join)
    stream.write("\r\n")
    stream.flush

    begin
      5.times do
        stream.write "#{Time.now}\n\n"
        sleep 1
      end
    ensure
      stream.close
    end

    [-1, {}, []]
  end
end

In this case, we call the proc passed to us using the rack.hijack key, instead of setting one ourselves in the response. This gives us complete control over the socket. At the end, we return an array with the status -1 only because Rack expects an array to be returned. The contents of this array are ignored since we've taken over the socket.

This is a bad practice, rife with gotchas and weird behavior. Don't do it. Samuel Williams, who is a maintainer of Rack, recommends against it as well.

Streaming Bodies in Rack for Ruby

While full hijacking is a terrible idea, partial hijacking is a useful tool. But it still feels hacky, so Rack 3 formally adopted that approach into the spec by introducing the concept of streaming bodies.

class App
  def call(env)
    body = proc do |stream|
      5.times do
        stream.write "#{Time.now}\n\n"
        sleep 1
      end
    ensure
      stream.close
    end

    [200, { "content-type" => "text/plain" }, body]
  end
end

Here we provide a block as the response body rather than an array. Rack keeps the connection open until the block finishes executing.

There's a huge gotcha here when using Puma. Puma is a multi-threaded server that assigns a thread to each incoming request. We're taking over the socket from Rack, but we're still tying up a Puma thread as long as the connection is open.

Puma concurrency can be configured, but threads are limited, and tying one up for long periods is not a good idea. Let's see this in action first.

$ bundle exec puma -w 1 -t 1:1

In two separate terminal windows, run the following command at the same time:

$ curl localhost:9292

One request is immediately served, but the other is held until the first one completes. This is because we started Puma with a single worker and single thread, meaning it can only serve a single request at a time.

We can get around this by creating our own thread.

class App
  def call(env)
    body = proc do |stream|
      Thread.new do
        5.times do
          stream.write "#{Time.now}\n\n"
          sleep 1
        end
      ensure
        stream.close
      end
    end

    [200, { "content-type" => "text/plain" }, body]
  end
end

Now if you try the above experiment again, you'll see both curl requests are served concurrently because they don't tie up a Puma thread.

Once again, I must warn against this approach, unless you know what you're doing. These demonstrations are largely academic, as systems programming is a deep and complex topic.

Falcon Web Server

Since the threading problem is specific to the Puma web server, let's look at another option: Falcon. This is a new, highly concurrent Rack-compliant web server built on the async gem. It uses Ruby Fibers instead of Threads, which are cheaper to create and have much lower overhead.

The async gem hooks into all Ruby I/O and other waiting operations, such as sleep, and uses these to switch between different Fibers (ensuring a program is never held up doing nothing).

Revert your app to the previous version where we're not spawning a new thread:

class App
  def call(env)
    body = proc do |stream|
      5.times do
        stream.write "#{Time.now}\n\n"
        sleep 1
      end
    ensure
      stream.close
    end

    [200, { "content-type" => "text/plain" }, body]
  end
end

Then remove Puma and install Falcon.

$ bundle remove puma
$ bundle add falcon

Run the Falcon server. We need to explicitly bind it because it only serves https traffic by default.

$ bundle exec falcon serve -n 1 -b http://localhost:9292

The server only uses a single thread, which you can confirm with the command below. You'll need to grab your specific pid from Falcon's logs.

$ top -pid <pid> -stats pid,th

The thread count printed by the above command will be 2 because the MRI uses a thread internally.

Try the earlier experiment again and run two curl requests simultaneously.

$ curl localhost:9292

You'll see they're both served at the same time, thanks to Ruby Fibers!

Falcon is relatively new. Ruby Fibers were only introduced in Ruby 3.0. Since Falcon is Rack-compliant, it can be used with Rails too, but the docs recommend using it with v7.1 or newer only. As such, it's a bit risky to use Falcon in production but it's a very exciting development in the Ruby world, in my opinion. I can't wait to see its progress in the next few years.

We've now learned how to create persistent connections in Rack and how to run them without blocking other requests, but the use cases so far have been academic and contrived. In the next and final part of this series, we'll examine how we can use this technique in a practical way.

Until then, happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

The Basics of Rack for Ruby

Ayush Newatia — Wed, 13 Nov 2024 14:06:53 +0000

Rack is the foundation for every popular Ruby web framework in existence. It standardizes an interface between a Ruby application and a web server. This mechanism allows us to pair any Rack-compliant web server (such as Puma, Unicorn, or Falcon) with any Rack-compliant web framework (like Rails, Sinatra, Roda, or Hanami).

Separating the concerns like this is immensely powerful and provides a lot of flexibility. It does, however, also come with limitations.

Rack 2 operated on the assumption that every request must provide a response and close the connection. It made no facility for persistent connections to enable pathways like WebSockets.

Developers had to make use of a hacky escape hatch to take over connections from Rack to implement WebSockets or similar persistent connections.

This all changed with Rack 3. But first, let's backtrack and take a closer look at Rack itself.

A Barebones Rack App

A basic Rack app looks like this:

class App
  def call(env)
    [200, { "Content-Type" => "text/plain" }, ["Hello World"]]
  end
end

run App.new

env is a hash containing request-specific information such as HTTP headers. When a request is made, the call method is called, and we return an array representing the response.

The first element is the HTTP response code, in this case 200. The second element is a hash containing any Rack and HTTP response headers we wish to send. Finally, the last element is an array of strings representing the response body.

Let's organize this app into a folder and run it.

$ mkdir rack-demo
$ cd rack-demo
$ bundle init
$ bundle add rack rackup
$ touch app.rb
$ touch config.ru

Fill in app.rb with the following:

class App
  def call(env)
    [200, { "content-type" => "text/plain" }, ["Hello World"]]
  end
end

And config.ru with:

require_relative "app"

run App.new

We can run this app using the default WEBrick server by running:

$ bundle exec rackup

The server will run on port 9292. We can verify this with a curl command.

$ curl localhost:9292
Hello World

That's got the basic app running!

Changing Web Servers

WEBrick is a development-only server, so let's swap it out for Puma:

$ bundle add puma

Now try running rackup again. You'll see it has automatically detected Puma in the bundle and started that instead of WEBrick!

$ bundle exec rackup
Puma starting in single mode...
* Puma version: 6.4.2 (ruby 3.2.2-p53) ("The Eagle of Durango")
*  Min threads: 0
*  Max threads: 5
*  Environment: development
*          PID: 45877
* Listening on http://127.0.0.1:9292
* Listening on http://[::1]:9292
Use Ctrl-C to stop

I recommend starting Puma directly instead of using rackup, as that allows us to pass configuration arguments should we want to. The -w 4 below starts Puma using 4 workers, meaning 4 instances of Puma are started up simultaneously.

$ bundle exec puma -w 4
[45968] Puma starting in cluster mode...
[45968] * Puma version: 6.4.2 (ruby 3.2.2-p53) ("The Eagle of Durango")
[45968] *  Min threads: 0
[45968] *  Max threads: 5
[45968] *  Environment: development
[45968] *   Master PID: 45968
[45968] *      Workers: 4
[45968] *     Restarts: (✔) hot (✔) phased
[45968] * Listening on http://0.0.0.0:9292
[45968] Use Ctrl-C to stop
[45968] - Worker 0 (PID: 45981) booted in 0.0s, phase: 0
[45968] - Worker 1 (PID: 45982) booted in 0.0s, phase: 0
[45968] - Worker 2 (PID: 45983) booted in 0.0s, phase: 0
[45968] - Worker 3 (PID: 45984) booted in 0.0s, phase: 0

This basic app demonstrates the Rack interface. An incoming HTTP request is parsed into the env hash and provided to the application. The application processes the request and supplies an array as the response that the server formats and sends to the client.

Rack Compliance In Frameworks

Every compliant web framework follows the Rack spec under the hood and provides an access point to go down to this level.

In Rails, we can send a Rack response in a controller:

class HomeController
  def index
    self.response = [200, {}, ["I'm Home!"]]
  end
end

Similarly, in Roda:

route do |r|
  r.on "home" do
    r.halt [200, {}, ["I'm Home!"]]
  end
end

Every Rack-compliant framework will have a slightly different syntax for accomplishing this, but since they're all sending Rack responses under the hood, they will have an API for you to access that response.

You can find the full, relatively accessible Rack specification on GitHub.

Wrapping Up

As this demo shows, Rack operates under the assumption that a request comes in, is processed by a web application, and a response is sent back. Throwing persistent connections into the mix totally breaks this model, yet Rack-compliant frameworks like Rails implement WebSockets.

In the next post, part two of a three-part series, we'll cover how to take over connections from Rack so we can hold persistent connections to enable pathways such as WebSockets.

Until then, happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Turbo Streaming Modals in Ruby on Rails

Ayush Newatia — Wed, 27 Mar 2024 15:00:00 +0000

In part one of this series, we used Hotwire's Stimulus and Turbo Frames to present modals in Rails.

Now, we'll dive into another method we can use to present modals: Turbo Streams.

What Are Turbo Streams in Ruby on Rails?

Turbo Streams is a subset of Turbo. It allows us to make fine-grained, targeted updates to a page. By default, it contains seven CRUD actions, but we're free to add more actions within our applications.

Now, we'll create a show_remote_modal action which renders and presents the <dialog> from our previous post.

Creating a Custom Action

Create a folder to place all custom Stream Actions in:

$ mkdir app/javascript/stream_actions
$ touch app/javascript/stream_actions/index.js

And a file for the Action:

$ touch app/javascript/stream_actions/show_remote_modal.js

Import the Stream Actions into the application:

// app/javascript/stream_actions/index.js

import "./show_remote_modal";

// app/javascript/application.js

// ...
import "stream_actions";

If you're using import maps, you'll need to update the config and restart the server:

# config/importmap.rb

# ...
pin_all_from "app/javascript/stream_actions", under: "stream_actions"

Change the global remote modal container to an HTML element instead of a Turbo Frame:

<%# app/views/layouts/application.html.erb %>

<!DOCTYPE html>
<html>
  <%# ... %>

  <body>
    <%= yield %>

    <remote-modal-container></remote-modal-container>
  </body>
</html>

The custom Stream Action can be implemented as:

// app/javascript/stream_actions/show_remote_modal.js

Turbo.StreamActions.show_remote_modal = function () {
  const container = document.querySelector("remote-modal-container");
  container.replaceChildren(this.templateContent);
  container.querySelector("dialog").showModal();
};

In the above snippet, this refers to StreamElement, which is the custom element underpinning <turbo-stream>. The templateContent getter is defined by this element.

Using the Action with a Rails Helper

Since this is a custom Action, we'll need to manually create a Rails helper to use it.

$ bin/rails generate helper TurboStreamActions

# app/helpers/turbo_stream_actions.rb

module TurboStreamActionsHelper
  def show_remote_modal(&block)
    turbo_stream_action_tag(
      :show_remote_modal,
      template: @view_context.capture(&block)
     )
  end
end

Turbo::Streams::TagBuilder.prepend(TurboStreamActionsHelper)

We can now use this helper in our views.

<%# app/views/support/tickets/new.html.erb %>

<%= turbo_stream.show_remote_modal do %>
  <dialog id="contact_form_modal" aria-labelledby="modal_title">
    <header>
      <h2 id="modal_title">
        Contact us
      </h2>
      <form method="dialog">
        <button aria-label="close">X</button>
      </form>
    </header>

    <%= form_with(url: support_tickets_path) do |form| %>
      <%= form.label :message, "Your message" %>
      <%= form.text_area :message, autofocus: true %>

      <%= form.button "Close", value: nil, formmethod: :dialog %>
      <%= form.button "Send" %>
    <% end %>
  </dialog>
<% end %>

Remember to remove the data-controller attribute: we don't need it anymore. In fact, we can delete the controller itself.

$ rm app/javascript/controllers/remote_modal_controller.js

We'll also need to change the template's name so it renders as a Turbo Stream.

$ mv \
    app/views/support/tickets/new.html.erb \
    app/views/support/tickets/new.turbo_stream.erb

Turbo Streams are disabled by default for GET requests, so we'll need to manually enable them for the link:

<%# app/views/support/show.html.erb %>

<%# ... %>

<%= link_to new_support_ticket_path, data: { turbo_stream: true } do %>
  Show contact form
<% end %>

<%# ... %>

Refresh the page and click Show contact form. It should still work as before, but now it's rendered using a custom Stream Action!

Wrapping Up

In this two-part series, we explored three different methods to present modals using Hotwire: Stimulus, Turbo Frames, and Turbo Streams. More importantly, the modals were presented with accessibility as the main consideration.

The web should be usable by everyone and it's important for us, as web developers, to put in the effort to make websites accessible.

Basecamp's accessibility guide is publicly available and a fantastic resource to learn the ropes.

I also recommend checking out the docs for Stimulus and Turbo to familiarise yourself with all their features and the APIs used in this series.

Happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Hotwire Modals in Ruby on Rails with Stimulus and Turbo Frames

Ayush Newatia — Wed, 06 Mar 2024 11:17:29 +0000

Modals are widely used on the web, but they are rarely built with accessibility in mind. When a modal is displayed, the background is dimmed visually but it's still visible to screen readers and keyboard-only users.

In this post, the first of a two-part series, we'll look at presenting accessible modals in Rails using two different approaches powered by Hotwire's Turbo and Stimulus libraries.

But first, let's see what we need to do to make modals accessible.

How Can We Make Modals Accessible?

To make modals accessible, we need to:

Hide the background from screen readers.
Implement "focus trapping" so keyboard users cannot focus on elements outside the modal.
Shift focus to the first focusable element in the modal (if there is one).
Dismiss the modal with the Esc key.

We could accomplish the first two by setting inert="true" on the background elements, but this attribute can't be set on an ancestor of the modal. We can do the last two with some more custom JavaScript. As you can imagine this is rather tedious.

The HTML <dialog> element gives us most of the above list for free, and is supported for 94.25% of global users, meaning it's ideal in most cases.

Let's look a bit more closely at the <dialog> element.

The `<dialog>` Element

According to MDN:

The HTML <dialog> element is used to create both modal and non-modal dialog boxes. Modal dialog boxes interrupt interaction with the rest of the page being inert, while non-modal dialog boxes allow interaction with the rest of the page.

This means that a <dialog> isn't necessarily a modal. It can be presented within the document flow as well.

Presenting a `<dialog>`

To present a dialog as a modal, we need to use JavaScript:

<dialog>Lorem ipsum ....</dialog>

const modal = document.querySelector("dialog");
modal.showModal();

When presenting a dialog this way, the background is made inert, focus is trapped in the modal, and it can be dismissed using the Esc key.

To present a <dialog> in a non-modal context, and hence make it visible by default, we use the open attribute:

<dialog open>Lorem ipsum ....</dialog>

We won't get the accessibility features using this method, though, as the dialog hasn't been presented "modally".

Dismissing a `<dialog>`

A modally presented <dialog> can be dismissed using JavaScript:

const modal = document.querySelector("dialog");
modal.showModal();
modal.close();

It can also be closed using a <form> with the dialog method. This is a great way to implement a "close" button.

<dialog>
  <header>
    <h2>A modal dialog</h2>
    <form method="dialog">
      <button type="submit">Close</button>
    </form>
  </header>

  Lorem ipsum...
</dialog>

That covers the basics of the <dialog> element, so let's look at using it with Hotwire.

Modal Presentation Using Stimulus in Ruby on Rails

Stimulus is a JavaScript library under the Hotwire umbrella. It allows us to attach pieces of JavaScript logic to HTML elements encapsulated in controllers. This post assumes a basic familiarity with its API.

Let's start with a Rails controller and view. As an example use case, we'll use a support page which has a button to display some contact details in a modal. Generate a controller and action using:

$ bin/rails generate controller support show

Amend the created route to a more user-friendly path:

# config/routes.rb
Rails.application.routes.draw do
  # ...

  get '/support', to: "support#show"
end

Sketch out a button and dialog in the newly generated view file:

<%# app/views/support/show.html.erb %>

<button>
  Show contact details
</button>

<dialog aria-labelledby="modal_title">
  <header>
    <h2 id="modal_title">
      Contact details
    </h2>
    <form method="dialog">
      <button aria-label="close">X</button>
    </form>
  </header>

  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
    incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
    nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  </p>
</dialog>

Run the Rails server and navigate to the /support path. You should see a button there, but it doesn't do anything at the moment. Let's create a Stimulus controller and wire it up.

The Stimulus Controller in Rails

Use the generator to create a Stimulus controller.

$ bin/rails generate stimulus modal

When the button is clicked, we need to get a reference to the <dialog> and call showModal() on it. To keep the controller generic, we'll pass in the element's id as a param.

// app/javascript/controllers/modal_controller.js

import { Controller } from "@hotwired/stimulus";

// Connects to data-controller="modal"
export default class extends Controller {
  show(event) {
    const dialog = document.getElementById(event.params.dialog);
    dialog.showModal();
  }
}

We can now decorate the button with the required data- attributes:

<%# app/views/support/show.html.erb %>

<button
  data-controller="modal"
  data-action="modal#show"
  data-modal-dialog-param="contact_details_modal">
  Show contact details
</button>

<dialog id="contact_details_modal" aria-labelledby="modal_title">
  <%# ... %>
</dialog>

Refresh the page and the button should now work!

There's an opportunity to remove some boilerplate code here. The modal controller should always be attached to a button that shows the modal. We can remove the data-action from the markup and set it in the controller:

// app/javascript/controllers/modal_controller.js

// ...
export default class extends Controller {
  connect() {
    this.element.dataset.action = "modal#show";
  }

  show(event) {
    // ...
  }
}

Styling the Modal

The dialog looks fairly basic, so let's add some styles:

/* app/assets/stylesheets/application.scss */

dialog {
  width: 80vw;
  margin: auto;

  &::backdrop {
    background: red;
    opacity: 0.2;
  }

  header {
    display: flex;
    align-items: center;

    h2 {
      flex: 0 1 100%;
    }
  }
}

The ::backdrop pseudo-element is a really great way to style the modal's background!

Try using the Tab key to navigate around the page and you'll see that the focus is trapped within the modal. It's worth reviewing the page with a screen reader as well.

This is the simplest way to modally present a <dialog>. Next, we'll look at a server-driven way to present modals: Turbo Frame.

Turbo Frame Powered Modals for Ruby

Turbo Frames are a subset of the Turbo library which is also under the Hotwire umbrella. It allows us to scope navigation to specific parts of a page, updating them in isolation from the rest of the page.

We can use Turbo Frames to present a modal rendered from the server.

Setting Up

Let's add another button to display a modal contact form. We'll need a controller and action to render the form:

$ bin/rails generate controller support/tickets new create

Replace the auto-generated routes with:

Rails.application.routes.draw do
  # ...

  namespace :support do
    resources :tickets, only: [:new, :create]
  end
end

We'll also need a global Turbo Frame to render modals, so let's put it in the main application layout:

<%# app/views/layouts/application.html.erb %>

<!DOCTYPE html>
<html>
  <%# ... %>

  <body>
    <%= yield %>

    <%= turbo_frame_tag :remote_modal %>
  </body>
</html>

Add a link to show the contact form:

<%# app/views/support/show.html.erb %>

<button
  data-controller="modal"
  data-modal-dialog-param="contact_details_modal">
  Show contact details
</button>

<%= link_to new_support_ticket_path, data: { turbo_frame: :remote_modal } do %>
  Show contact form
<% end %>

<%# ... %>

And you're done!

Rendering and Presenting the Form

Clicking the Show contact form link will expect a <turbo-frame> with id="remote_modal" in the response and update the global Turbo Frame with its content. Fill in the view with the form:

<%# app/views/support/tickets/new.html.erb %>

<%= turbo_frame_tag :remote_modal do %>
  <dialog id="contact_form_modal" aria-labelledby="modal_title">
    <header>
      <h2 id="modal_title">
        Contact us
      </h2>
      <form method="dialog">
        <button aria-label="close">X</button>
      </form>
    </header>

    <%= form_with(url: support_tickets_path) do |form| %>
      <%= form.label :message, "Your message" %>
      <%= form.text_area :message, autofocus: true %>

      <%= form.button "Close", value: nil, formmethod: :dialog %>
      <%= form.button "Send" %>
    <% end %>
  </dialog>
<% end %>

We've now got a text area in the modal which is a focusable element. For accessibility, it should be focused by default when the modal is presented. The autofocus attribute is used to accomplish this.

Refresh the page and try clicking Show contact form. Nothing will happen visually, but on inspecting the HTML, you'll notice the <dialog> has been rendered in the remote_modal Turbo Frame. We haven't presented it yet, which is why it's invisible.

We could render it with the open attribute, but that would defeat the purpose as it'd be presented in a non-modal context without the modal accessibility features.

Let's create another Stimulus controller to present the form:

$ bin/rails generate stimulus remote_modal

// app/javascript/controllers/remote_modal_controller.js

import { Controller } from "@hotwired/stimulus";

// Connects to data-controller="remote-modal"
export default class extends Controller {
  connect() {
    this.element.showModal();
  }
}

And hook it up to the dialog:

<%# app/views/support/tickets/new.html.erb %>

<%= turbo_frame_tag :remote_modal do %>
  <dialog
    id="contact_form_modal"
    aria-labelledby="modal_title"
    data-controller="remote-modal">
    <%# ... %>
  </dialog>
<% end %>

Refresh the page and try viewing the contact form again. This time it should work. We've just rendered a modal from the server!

While this is quite convenient, it's not ideal to create a new Stimulus controller just to present a modal. There's another method we can use as well: Turbo Streaming Modals. We'll take a look at those in part two of this series.

Up Next: Turbo Streaming Modals

In this post, we explored two different methods to present modals using Hotwire: Stimulus and Turbo Frames.

In part two, we'll look at another way to present modals: using Turbo Streams.

Until then, happy coding!

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

How I manage my git history

Ayush Newatia — Fri, 26 May 2023 11:28:19 +0000

I'm generally a rather pedantic person and this is supercharged when it comes to managing the git history on my projects. I used GitHub's squash and merge for a while before Chris Moore taught me a few tricks.

I'm not a fan of squash and merge because it squashes an entire Pull Request into a single commit, no matter how large it is. This means that rather large changes could live under a single commit. I believe the commit history should tell a linear story, as pretentious as that might sound.

A clean commit history also makes life easier for code reviewers. A glance at the commits should give an overview of the changes and viewing the diff for each individual commit should make logical sense, allowing the reviewer to peruse the PR in smaller chunks.

In the long term, it's useful to delve into a project's history and see how and why certain changes were main. A carefully curated git history makes this easier.

I primarily use two git features to manage my commit history: git reset --mixed and git rebase -i (interactive rebase).

Git reset

Let's say we're working on a branch called feature/dashboard which is based on the main branch. While I'm building out a feature, my git history is a complete mess. It's usually something like:

WIP
Some stuff
Fix shit
Complete dashboard

Yeah, really. That's definitely not shippable, so I run:

$ git fetch
$ git reset --mixed origin/main

This will reset the state of the branch to main and retain all my changes in the working copy (the branch needs to be up to date with main before this, use rebase or merge). I'll then commit them in a logical order to produce something like:

Add new dashboard layout
Add new assets
Stimulus controller for drawer animations
Create dashboard controller actions and views

That's more like it. A reviewer can just see the commit messages and instantly have an idea of what's changed. The diff for each individual commit also makes sense. Since we've rewritten the git history, we'll need to force push this branch using:

$ git push --force

At this point, I'll have invariably forgotten to run Rubocop and any other linters used on the project. After running those, I'd need to add another commit with the fixes but that messes up the linear story. This is when I use interactive rebase.

Interactive rebase

Interactive rebase lets us pick and choose which commits to retain on the branch, and also lets us squash multiple commits together. Running git rebase -i origin/main opens up a text editor containing the commits which exist on the current branch, but not on main:

pick 6246a52ba Add new dashboard layout
pick 0fd58314b Add new assets
pick 25d5bafa3 Stimulus controller for drawer animations
pick 1432fc34a Create dashboard controller actions and views
pick cbf35b39f Rubocop and ESlint

# Rebase e88d9298b..cbf35b39f onto e83d9294b (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# keep only this commit's message; -c is same as -C but
# opens the editor
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# create a merge commit using the original merge commit's
# message (or the oneline, if no original merge commit was
# specified); use -c <commit> to reword the commit message
# u, update-ref <ref> = track a placeholder for the <ref> to be updated
# to this position in the new commits. The <ref> is
# updated at the end of the rebase
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

All the available commands are conveniently documented within this file. I'd now use the fixup command to squash the linter fixes into one of the other commits where it makes logical sense. Closing the file completes the rebase. Once again, we've rewritten history so a force push is required: git push --force.

Other uses of interactive rebase

As a contractor, I often work on a fork of the main project, or off a separate branch rather than main depending on my client's requirements. This means sometimes the base branch I'm working off has been rebased.

For example, if I'm working off an integration branch and it was rebased to bring it up to date with main, I need to now bring my local integration branch in sync with the remote branch.

$ git fetch
$ git checkout integration
$ git reset --hard origin/integration

Ensure you don't have any changes on your local integration branch when you do this or you will lose them. Next, I need to rebase my feature branch to bring it up to date with integration. Since rebase rewrites history, there could be duplicate commits on the feature branch that have snuck in there because their hash changed after integration was rebased. These need to be excluded these from the feature branch as it should only contain changes related to that feature.

$ git fetch
$ git checkout feature/dashboard
$ git rebase -i integration

This might now produce something like:

pick 2342bcaf3 Fix CI
pick 6246a52ba Add new dashboard layout
pick 0fd58314b Add new assets
pick 25d5bafa3 Stimulus controller for drawer animations
pick 1432fc34a Create dashboard controller actions and views
pick cbf35b39f Rubocop and ESlint

# Rebase e88d9298b..cbf35b39f onto e83d9294b (3 commands)
#

# ...

Wait a sec, that Fix CI commit has nothing do to with this work. That's snuck in because it lives in integration and its hash changed during the rebase. To exclude it, delete that line and close the file so the branch is brought up to date and only contains the intended changes. It'll need a force push once again.

Conclusion

Rewriting git history is risky. If you're unsure about what you're doing, ALWAYS create a backup copy of your branch before attempting destructive changes.

Never ever force push to branches used by your entire team unless you're all aware that this is common practice and know how to deal with it. If you're working alongside another developer on a feature branch, ensure you're on the same page regarding force pushing and communicate force pushes promptly so neither of you accidentally lose any work.

Despite having used git for over 10 years now, and this particular workflow involving interactive rebase for 3 years or so, I still don't really understand it properly. I've developed a feel for it with extended use. If you're a bit confused, don't worry about it, it confused the hell out of me initially and it still does, just to a lesser degree. You'll get the hang of it with practice. It's a great power tool to have in your arsenal.

Directing Turbo Native apps from the server

Ayush Newatia — Thu, 01 Dec 2022 12:42:29 +0000

This post was extracted and adapted from The Rails and Hotwire Codex. It also assumes some familiarity with Turbo Native.

When developing for the web, we can send the user to any location during a web request using an HTTP redirect (3xx status codes). Turbo Native effectively wraps the website within native navigation. This means a redirect may not always do the trick.

Let's take an example. A Login screen is presented modally in the native apps. After a successful login, we want to redirect the user to the home page. In the app, we'd want to dismiss the modal to reveal the screen under it allowing the user to continue with whatever they were doing. A conventional redirect won't work, we need to tell the app to just dismiss the modal.

Server driven native navigation

The turbo-rails gem draws three routes which instruct the native app to do something. These routes don't return any meaningful content; the app is meant to intercept visit proposals to these routes and implement logic to execute the instruction. The routes, and what they instruct, are:

Route	Instruction
`/recede_historical_location`	The app should go back
`/resume_historical_location`	The app should do nothing in terms of navigation
`/refresh_historical_location`	The app should refresh the current page

Check out the source code to see the routes and the actions they point to.

These routes are exclusively for the native apps and have no meaning on web. To help with this, turbo-rails has methods to conditionally redirect a user if they're using the app. For example, instead of redirecting as below:

redirect_to root_path, status: :see_other

We would use:

recede_or_redirect_to root_path, status: :see_other

This will redirect to / on the web, and to /recede_historical_location in the native apps. Check out all the available redirect methods in the source code.

Using these methods, the app can be directed to dismiss the login modal after logging in while still redirecting to the root path on web.

Next, redirects to the aforementioned paths need to be intercepted and handled in the apps. We'll call these paths: path directives, since they direct the app to do something.

Intercept and handle path directives

Let's look at iOS. The following delegate method is triggered for every web request from the app.

extension RoutingController: SessionDelegate {
  func session(_ session: Session, didProposeVisit proposal: VisitProposal) {
    // ...
  }
}

In here, we can check if a visit is a path directive and act accordingly.

extension RoutingController: SessionDelegate {
  func session(_ session: Session, didProposeVisit proposal: VisitProposal) {
    if proposal.isPathDirective {
      executePathDirective(proposal)
    } else {
      visit(proposal)
    }
  }

  func executePathDirective(_ proposal: VisitProposal) {
    guard proposal.isPathDirective else { return }

    switch proposal.url.path {
    case "/recede_historical_location":
      dismissOrPopViewController()
    case "/refresh_historical_location":
      refreshWebView()
    default:
      ()
    }
  }

  private func dismissOrPopViewController() {
    // ...
  }

  private func refreshWebView() {
   // ...
  }
}

extension VisitProposal {
  var isPathDirective: Bool {
    return url.path.contains("_historical_location")
  }
}

That'll do the trick on iOS.

Building a Turbo Native navigation system is non-trivial, so I've had to omit a lot of surrounding code to keep this post on point. My book fills in all the gaps if you're interested in digging deeper.

Next, let's look at Android. Custom navigation is handled by creating an interface which inherits from TurboNavDestination. In this interface, the shouldNavigateTo(newLocation: String) method is called for every web request. We can handle path directives in here.

interface NavDestination: TurboNavDestination {

  override fun shouldNavigateTo(newLocation: String): Boolean {
    return when {
      isPathDirective(newLocation) -> {
        executePathDirective(newLocation)
        false
      }
      else -> true
    }
  }

  private fun executePathDirective(url: String) {
    val url = URL(url)
    when (url.path) {
      "/recede_historical_location" -> navigateUp()
      "/refresh_historical_location" -> refresh()
    }
  }

  private fun isPathDirective(url: String): Boolean {
    return url.contains("_historical_location")
  }

  // ...
}

Conclusion

That's how Turbo Native powered apps can be controller from the server! This gives us an immense amount of flexibility and extensibility without ever deploying app updates.

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills! It'll teach you how to build a Turbo Native navigation system and fills in the gaps in this blog post.

Turbo Streams meets Action Cable

Ayush Newatia — Wed, 16 Nov 2022 16:30:47 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

Turbo Streams are a great match-up for Action Cable as it makes it easy to broadcast DOM updates to the browser over WebSockets. The turbo-rails gem integrates with Action Cable to facilitate such updates.

In this blog post, we'll look at how this integration works. Starting with code examples to establish a connection and broadcast Turbo Streams, we'll then dig into the individual client and server components of the integration.

An overview

turbo-rails contains a JavaScript custom element which encapsulates the logic to create an Action Cable connection, subscribe to a channel and execute received Turbo Streams. On the server-side, it provides a default channel and a plethora of helper methods to broadcast data based on models.

On the client, an Action Cable connection and subscription is established using:

<%= turbo_stream_from @conversation %>

This will render a <turbo-cable-stream-source> element which subscribes to a stream for the @conversation object. Turbo Streams can then be broadcast to it using:

Turbo::StreamsChannel.broadcast_action_to(
  @conversation,
  action: :append,
  target: dom_id(@conversation, :messages),
  partial: "messages/message"
)

There are helper methods to broadcast the stock Turbo Stream actions. The above snippet can be rewritten as:

Turbo::StreamsChannel.broadcast_append_to(
  @conversation,
  target: dom_id(@conversation, :messages),
  partial: "messages/message"
)

You can also broadcast a Turbo Stream template containing multiple actions:

Turbo::StreamsChannel.broadcast_render_to(
  @conversation,
  template: "messages/create"
)

All the above examples render templates and broadcast them synchronously. This isn't usually desirable. It should be offloaded to a background job so the request-response cycle isn't held up.

# enqueues a `Turbo::Streams::ActionBroadcastJob`
Turbo::StreamsChannel.broadcast_append_later_to(
  @conversation,
  target: dom_id(@conversation, :messages),
  partial: "messages/message"
)

# enqueues a `Turbo::Streams::BroadcastJob`
Turbo::StreamsChannel.broadcast_render_later_to(
  @conversation,
  template: "messages/create"
)

Check out the docs for all available helpers: https://rubydoc.info/github/hotwired/turbo-rails/Turbo/Streams/Broadcasts.

In addition to this, there's also a Broadcastable concern which is included in Active Record. It applies Rails conventions to succinctly broadcast model-specific Turbo Streams. Some example use cases are:

# Broadcasts an `append` action containing the partial
# `conversations/conversation` targeted at the
# ID `conversations`.
Conversation.first.broadcast_append

# The update action targets the specific model's HTML element.
# In this case, it will target `conversation_1`. The content
# will be the partial `conversations/conversation`.
Conversation.first.broadcast_update

# The partial can be explicitly defined if required.
Conversation.first.broadcast_append(
  partial: "messages/message"
)

I recommend taking a peek at the docs to familiarize yourself with all the model-based broadcast methods: https://rubydoc.info/github/hotwired/turbo-rails/Turbo/Broadcastable.

The broadcast helpers in Turbo::StreamsChannel, which we looked at earlier, are all available in Broadcastable as well.

Under the hood, all the broadcast helpers use ActionCable.server.broadcast(...). Hence, they just provide some syntactic sugar on top of Action Cable.

Next, let's take a closer look at the custom element which receives and processes Turbo Streams.

Turbo Cable Stream Source element

As mentioned earlier, this element is rendered using:

<%= turbo_stream_from @conversation %>

This will render as:

<turbo-cable-stream-source
  channel="Turbo::StreamsChannel"
  signed-stream-name="...">
</turbo-cable-stream-source>

This element is underpinned by the class TurboCableStreamSourceElement.

The subscription is established using the two HTML attributes. We can specify a custom channel if the default one isn't suitable:

<%= turbo_stream_from @conversation,
      channel: "ConversationsChannel" %>

The signed stream name is generated from the @conversation object. You can use multiple arguments for this as well.

<%= turbo_stream_from @conversation, :messages,
      channel: "ConversationsChannel" %>

Let's dig into how the stream names are generated.

A closer look at stream names

Any type of object can used to generate the stream name as long as it responds to to_gid_param or to_param. Hence, it's usually an Active Record object, string or symbol.

to_gid_param generates the Global ID for a model and then Base64 encodes it. For strings, to_param returns the object itself. For symbols, it returns the object's string representation.

The stream name for a Conversation object would look something like:

Z2lkOi8vcGlhenphL0NvbnZlcnNhdGlvbi8x

Base64 decoding the above value will reveal the object's Global ID:

>> stream = "Z2lkOi8vcGlhenphL0NvbnZlcnNhdGlvbi8x"
>> Base64.urlsafe_decode64(stream)

# => "gid://piazza/Conversation/1"

The stream name is run through a MessageVerifier to obtain the signed stream name which is rendered in the HTML attribute. This ensures the stream name can't be tampered with on the client.

When using multiple arguments, each one will have to_gid_param or to_param called on it individually. The return values are then joined with a :. The stream name for:

<%= turbo_stream_from @conversation, :messages,
      channel: "ConversationsChannel" %>

will look like:

Z2lkOi8vcGlhenphL0NvbnZlcnNhdGlvbi8x:messages

Using the signed stream name and channel name, the custom element establishes an Action Cable connection and subscribes to the desired stream, ready to receive Turbo Streams over a WebSocket.

Processing Turbo Streams

The easiest way to execute Turbo Streams is by adding them to the DOM. Another way to is by using the connectStreamSource method.

import { connectStreamSource, disconnectStreamSource } from "@hotwired/turbo"

// ...

connectStreamSource(source)

// ...

disconnectStreamSource(source)

The source can be any object capable of dispatching MessageEvents. Turbo will listen for these events and execute the Turbo Streams they contain.

TurboCableStreamSourceElement connects itself as a stream source when it's connected to the DOM. When it receives a Turbo Stream over the WebSocket connection, it dispatches a MessageEvent containing it, which Turbo executes.

The default channel

turbo-rails has a default channel called Turbo::StreamsChannel to handle broadcasts and subscriptions. We briefly encountered it while discussing the broadcast helpers. It verifies the signed stream name and subscribes the client to the appropriate stream.

class Turbo::StreamsChannel < ActionCable::Channel::Base
  extend Turbo::Streams::Broadcasts, Turbo::Streams::StreamName
  include Turbo::Streams::StreamName::ClassMethods

  def subscribed
    if stream_name = verified_stream_name_from_params
      stream_from stream_name
    else
      reject
    end
  end
end

This is generic code and hence contains no authorization logic. I highly recommend writing your own channel based off Turbo::StreamsChannel where you run authorization checks before approving the stream.

Most of the channel's logic in encapsulated in concerns making it easy to reuse in your own channel.

Conclusion

That's the Turbo Streams integration with Action Cable in a nutshell. It packs in immense power with relatively little code. The docs for turbo-rails are sparse at best, but I recommend keeping the YARD docs handy for reference: https://rubydoc.info/gems/turbo-rails.

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

Testing controller concerns in Rails

Ayush Newatia — Fri, 28 Oct 2022 17:14:28 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

Concerns are a great way to organize and de-duplicate code in Rails.

One of my favorite use cases is to abstract everything out of the ApplicationController into concerns. This begs the question: how do you test these concerns?

The approach for testing concerns is a bit of a judgement call as they're always mixed in with a class and aren't used on their own. Ideally we'd write tests to verify the behavior of a class which would also test the concern in the bargain.

But what if the concern adds the same functionality to a large number of classes? For example, a concern which Authenticates every request. It isn't pragmatic to test each and every controller action for authentication logic. In such cases, I believe the best approach is to test the concern in isolation.

Test harness for controller concerns

Let's stick with the hypothetical example of a concern called Authenticate. It's usable only within a controller, so we'll need a test harness to test it independently.

Create a support/ folder under test/ and create some files for the test harness within it.

$ mkdir test/support
$ touch test/support/test_controller.rb
$ touch test/support/routes_helper.rb

The TestController doesn't need to do much by itself. It will be subclassed in individual tests. Each action will render the name of the controller and action which can then be asserted in the test cases.

class TestController < ActionController::Base
  def index; end
  def new; end
  def create; end
  def show; end
  def edit; end
  def update; end
  def destroy; end

  private

    def default_render
      render plain: "#{params[:controller]}##{params[:action]}"
    end
end

Next, we need a way to draw some test-only routes to point to TestController subclasses in test cases. The test routes will be scoped to /test so they don't clash with existing routes.

# test/support/routes_helper.rb

# Ensure you call `reload_routes!` in your test's `teardown`
# to erase all the routes drawn by your test case.

module RoutesHelpers
  def draw_test_routes(&block)
    # Don't clear routes when calling `Rails.application.routes.draw`
    Rails.application.routes.disable_clear_and_finalize = true

    Rails.application.routes.draw do
      scope "test" do
        instance_exec(&block)
      end
    end
  end

  def reload_routes!
    Rails.application.reload_routes!
  end
end

The draw_test_routes helper takes a block which is executed inside the context of Rails.application.routes.draw. In essence, it's doing the exact same thing as config/routes.rb, but in the context of the test suite.

Files under the test/ folder in Rails are not autoloaded, so these files need to be required and included manually.

# test/test_helper.rb

# ...

Dir[Rails.root.join("test", "support", "**", "*.rb")].each {
  |f| require f
}

# ...

class ActionDispatch::IntegrationTest
  include RoutesHelpers
end

With the test harness in place, we can now write some tests for the Authenticate concern.

$ touch test/controllers/concerns/authenticate_test.rb

require 'test_helper'

class AuthenticateTestsController < TestController
  include Authenticate

  def show
    # ...
  end
end

class AuthenticateTest < ActionDispatch::IntegrationTest
  setup do
    draw_test_routes do
      resource :authenticate_test, only: [:new, :create, :show, :edit]
    end
  end

  teardown do
    reload_routes!
  end

   # ...
   # Test cases go here ...
   # ...
end

The test-specific AuthenticateTestsController strips away any peripheral functionality and enables us to focus on testing the code in Authenticate. It can now be tested just like any other controller!

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

Rails system tests for multiple screen sizes

Ayush Newatia — Wed, 19 Oct 2022 14:41:10 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

Rails system tests simulate a user's actions in a web browser so it's akin to the app's real world usage. In a responsive app, this means testing on multiple screen sizes as well.

Capybara, the tool used by system tests under the hood, has a method to resize the current window during a test run. But, since the tests are not run in a set order, any test that resizes the window needs to restore the size after it's done. Otherwise, subsequent tests run in that window could fail.

Let's take a look at how to write a set of system tests for mobile screens.

Mobile system tests

Create a subclass of ApplicationSystemTestCase specifically for mobile. It will resize the window in the setup and teardown methods that are invoked before and after each test case.

require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  WINDOW_SIZE = [1400, 1400]
  driven_by :selenium, using: :chrome, screen_size: WINDOW_SIZE
end

class MobileSystemTestCase < ApplicationSystemTestCase
  setup do
    visit root_path
    current_window.resize_to(375, 812)
  end

  teardown do
    current_window.resize_to(*ApplicationSystemTestCase::WINDOW_SIZE)
  end
end

We can use this new base class to write tests aimed at mobile screens. Let's say the navigation bar shows a burger menu only on mobile. We can test that as:

require "application_system_test_case"

module Mobile
  class NavigationBarTest < MobileSystemTestCase
    test "can access sign up page via burger menu" do
      visit root_path

      find(".navbar-burger").click
      click_on "Sign Up"

      assert_current_path sign_up_path
    end

    test "can access login page via burger menu" do
      visit root_path

      find(".navbar-burger").click
      click_on "Log in"

      assert_current_path login_path
    end
  end
end

Running the system tests will now resize the window for the above two tests and restore the size back to desktop after they're done!

$ bin/rails test:system

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

Custom error pages in Rails

Ayush Newatia — Thu, 06 Oct 2022 13:07:10 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

When something goes wrong in Rails, the user sees a rather boring default error page.

This page lives in the /public folder and hence isn't rendered through the Rails stack.

To jazz up this page a bit, we'll create a controller to render errors so the Rails infrastructure can be used.

Setting up

A configuration change needs to be made so public facing errors are rendered in development rather than the exception and stack trace.



# config/environments/development.rb
require "active_support/core_ext/integer/time"

Rails.application.configure do
  # ...

  config.consider_all_requests_local = false
end

Create the controller.



$ bin/rails g controller errors --no-helper --no-test-framework

This controller will have a single show action where we'll extract the error code for the raised exception and render the appropriate view. Error codes 403, 404 and 500 will have dedicated error pages and we'll fall back to the 404 page for everything else.



class ErrorsController < ApplicationController
  layout "error"

  def show
    @exception = request.env["action_dispatch.exception"]
    @status_code = @exception.try(:status_code) ||
                   ActionDispatch::ExceptionWrapper.new(
                    request.env, @exception
                  ).status_code

    render view_for_code(@status_code), status: @status_code
  end

  private
    def view_for_code(code)
      supported_error_codes.fetch(code, "404")
    end

    def supported_error_codes
      {
        403 => "403",
        404 => "404",
        500 => "500"
      }
    end
end

As you can see, we're using a bespoke "error" layout as well. These pages will be simple and won't need the usual baggage from the application layout.

Create the new error layout.



$ touch app/views/layouts/error.html.erb



<%# app/views/layouts/error.html.erb %>

<!DOCTYPE html>
<html>
  <head>
    <%= render "layouts/head" %>
  </head>

  <body>
    <main>
      <%= yield %>
    </main>
  </body>
</html>

Create the views and fill them in as you wish.



$ touch app/views/errors/403.html.erb
$ touch app/views/errors/404.html.erb
$ touch app/views/errors/500.html.erb

We need to now tell Rails to use this controller to render errors.

Exceptions app

Rails provides a hook to render custom errors through a configuration property called exceptions_app. This property has to be assigned a Rack app which is invoked when an exception is raised.

Every Rails controller action is actually its own Rack application! The Rack endpoint is returned by the action method on a controller class.



# ...

module MyApp
  class Application < Rails::Application
    config.load_defaults 7.0

    config.exceptions_app = ->(env) {
      ErrorsController.action(:show).call(env)
    }
  end
end

Restart your server and then try visiting a page that doesn't exist. Or manually trigger an error in a controller action. You'll see your custom error pages in action!

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

Remote debugging in Rails 7

Ayush Newatia — Fri, 23 Sep 2022 15:04:11 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

Rails 7 includes the official Ruby debugger. It also uses Foreman to orchestrate multiple processes in development. This way you can run the Rails server along with processes to watch and compile your frontend assets using a single command.

Annoyingly, this makes debugging trickier. You can't just add a breakpoint in your app and run commands in the console. The same Terminal window is running multiple processes, so won't always be interactive.

The debug gem supports remote debugging which is useful in such cases. Using this setup, an external, independent debugger process attaches to another debuggee Ruby process.

Enable remote debugging in your Rails app by adding the below lines to your application.rb.

require "rails/all"

if defined?(Rails::Server) && Rails.env.development?
  require "debug/open_nonstop"
end

# ...

We verify the Rails environment is development and that the Rails::Server constant is defined before enabling remote debugging. The latter check ensures remote debugging is enabled only when the app runs in the context of a web server. It shouldn't be enabled in other contexts like the Rails console or a background job processor like Sidekiq.

Now when you start the Rails server in development, the debug gem will open a UNIX domain socket which the debugger process can connect to.

Start the server using bin/dev and in another Terminal window, run:

$ bundle exec rdbg -a

If the Rails server is the only debuggable process running (it should be), the debugger will connect. You can add then breakpoints in the app and run commands in the debugger process!

Ctrl+D will exit the debugger and leave the Rails server running. I recommend doing this after you've finished debugging. Check out the docs for the full list of available commands: https://github.com/ruby/debug#control-flow.

NOTE: You can also use the statement require "debug/open" instead of require "debug/open_nonstop". The downside here is the program will be paused on launch until you attach the debugger and continue it. This can get very fiddly given how often the server needs to be restarted during development.

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

HTTP redirects in a Turbo-Rails app

Ayush Newatia — Thu, 15 Sep 2022 12:39:27 +0000

This post was extracted and adapted from The Rails and Hotwire Codex.

In Rails, a conventional redirect in a controller action looks like:

def create
  # ...

  redirect_to root_path
end

This sends a response with an HTTP status code of 302 Found.

The Turbo docs, however, state that the response to a form submission must be 303 See Other unless something goes wrong.

The reason behind this is the spec for 302 Found states that the redirected request should use the same HTTP method as the original request. Due to legacy reasons, the fetch (used by Turbo under the hood) implementation in most browsers will respond to a 302 Found response from a POST request by issuing a GET request to the redirected path. For all other HTTP methods, it will use the same method as the original request when redirecting.

Responding with a 303 See Other status ensures that the method used for the redirect is always GET.

def create
  # ...

  redirect_to root_path, status: :see_other
end

This anomaly with redirect codes isn't a massive problem in Rails because Rails forms use the only two browser native methods: GET and POST. Forms with different methods are rendered to use POST with the method inserted as a hidden field which is then parsed by Rails before the request hits a controller.

For example:

<%= form_with(url: posts_path, method: :put) do |form| %>
  <%= form.text_field :name %>

  <%= form.submit %>
<% end %>

will render

<form action="/posts" accept-charset="UTF-8" method="post">  
  <input type="hidden" name="_method" value="put">
  <input type="hidden" name="authenticity_token" value="...">

  <input type="text" name="name" id="name">

  <input type="submit" name="commit" value="Save">
</form>

However, this could potentially change as Rails integrates more tightly with Turbo. There are already a couple of use cases where 302 redirects can be problematic.

Turbo submits the form using the method specified in the formmethod attribute when it's defined. The below form would submit using a PUT request.

<%= form_with(url: posts_path) do |form| %>
  <%= form.text_field :name %>

  <%= form.submit formmethod: :put %>
<% end %>

If your controller redirected using a 302 Found, that would result in another PUT request to the redirected path.

Since Turbo intercepts form submissions, you can use any HTTP method in a <form>'s method attribute, not just GET and POST. This form will also submit with a PUT:

<form action="/posts" accept-charset="UTF-8" method="put">  
  <input type="text" name="name" id="name">

  <input type="submit" value="Save">
</form>

Rails form helpers won't render this, but it's good to know what's possible!

As such, I believe it's good practice to ALWAYS redirect with a 303 See Other status code when using Turbo in a Rails app.

If you liked this post, check out my book, The Rails and Hotwire Codex, to level-up your Rails and Hotwire skills!

DEV Community: Ayush Newatia

Rack for Ruby: Socket Hijacking

HTTP Connections

Partial Hijacking

Full Hijacking

Streaming Bodies in Rack for Ruby

Falcon Web Server

The Basics of Rack for Ruby

A Barebones Rack App

Changing Web Servers

Rack Compliance In Frameworks

Wrapping Up

Turbo Streaming Modals in Ruby on Rails

What Are Turbo Streams in Ruby on Rails?

Creating a Custom Action

Using the Action with a Rails Helper

Wrapping Up

Hotwire Modals in Ruby on Rails with Stimulus and Turbo Frames

How Can We Make Modals Accessible?

The <dialog> Element

Presenting a <dialog>

Dismissing a <dialog>

Modal Presentation Using Stimulus in Ruby on Rails

The Stimulus Controller in Rails

Styling the Modal

Turbo Frame Powered Modals for Ruby

Setting Up

Rendering and Presenting the Form

Up Next: Turbo Streaming Modals

How I manage my git history

Git reset

Interactive rebase

Other uses of interactive rebase

Conclusion

Directing Turbo Native apps from the server

Server driven native navigation

Intercept and handle path directives

Conclusion

Turbo Streams meets Action Cable

An overview

Turbo Cable Stream Source element

A closer look at stream names

Processing Turbo Streams

The default channel

Conclusion

Testing controller concerns in Rails

Test harness for controller concerns

Rails system tests for multiple screen sizes

Mobile system tests

Custom error pages in Rails

Setting up

Exceptions app

Remote debugging in Rails 7

HTTP redirects in a Turbo-Rails app

The `<dialog>` Element

Presenting a `<dialog>`

Dismissing a `<dialog>`