DEV Community: Steve Polito

How to encrypt files with Ruby and Active Support

Steve Polito — Wed, 22 Mar 2023 12:54:54 +0000

In this tutorial, we will create a Ruby binstub that allows you to encrypt and
decrypt files using Active Support's EncryptedFile module. This script is
particularly useful for those who need to protect sensitive information within
their files.

Use Cases

Encrypt text files in open source projects so that they can be committed to your repository without exposing sensitive information.
Storing credentials in an encrypted file, similar to Rails Custom Credentials.
Taking secure personal notes.

Required Libraries

The script starts with the following lines, which load the required libraries
and set up the command line argument handling.

#!/usr/bin/env ruby
require "active_support/encrypted_file"
require "securerandom"

These lines import the necessary Ruby modules:
active_support/encrypted_file for encryption and decryption, and
securerandom for key generation

Parsing Arguments

The script expects one of three commands as the first argument: setup,
write, or read. If no command is provided, the script will print an error
message and exit.

command = ARGV.shift

if command.nil?
  puts "Please pass 'setup', 'write [FILE]', or 'read [FILE]'"
  exit 1
end

Helper Methods

The following build_encrypted_file method creates an instance of
ActiveSupport::EncryptedFile with the necessary configuration options.

def build_encrypted_file(file)
  ActiveSupport::EncryptedFile.new(
    content_path: file,
    key_path: "invisible_ink.key",
    env_key: "INVISIBLE_INK_KEY",
    raise_if_missing_key: true
  )
end

Next, we have two helper methods: handle_missing_key and
handle_missing_file_argument. These methods print error messages and exit the
script if a key or a file is missing, respectively.

Executing the Commands

The case statement is the main part of the script, handling the three possible
commands: write, read, and setup.

Encrypting a File

For the write command, the script ensures that a file argument is provided
and that a system editor is available to open the file. It then creates a new
encrypted file if it does not exist and opens the file in the system editor for
editing. When the editor is closed, the encrypted file is saved with the new
content.

when "write"
  file = ARGV.shift
  handle_missing_file_argument if file.nil?
  if ENV["EDITOR"].to_s.empty?
    puts "No $EDITOR to open file in"
    exit 1
  end
  begin
    encrypted_file = build_encrypted_file(file)
    encrypted_file.write(nil) unless File.exist?(file)
    encrypted_file.change do |tmp_path|
      system(ENV["EDITOR"], tmp_path.to_s)
    rescue Interrupt
      puts "File not saved"
    end
  rescue ActiveSupport::EncryptedFile::MissingKeyError => error
    handle_missing_key(error)
  end

Decrypting a File

For the read command, the script ensures that a file argument is provided and
then attempts to read the encrypted file, printing the decrypted contents to the
standard output.

when "read"
  begin
    file = ARGV.shift
    handle_missing_file_argument if file.nil?
    encrypted_file = build_encrypted_file(file)
    puts encrypted_file.read
  rescue ActiveSupport::EncryptedFile::MissingKeyError => error
    handle_missing_key(error)
  end

The Setup Script

Finally, the setup command generates a new encryption key and saves it to a
file named invisible_ink.key. It also adds the key file to the .gitignore
file to prevent it from being accidentally committed to a version control
system.

when "setup"
  if File.exist?("invisible_ink.key")
    puts "ERROR: invisible_ink.key already exists"
    exit 1
  else
    File.open(".gitignore", "a") { |file| file.puts("invisible_ink.key") }
    key = ActiveSupport::EncryptedFile.generate_key
    File.write("invisible_ink.key", key)
    puts "invisible_ink.key generated"
  end

The Final Script

By using this script, you can protect sensitive information from unauthorized
access and maintain the privacy of your data. With the setup, write, and
read commands, you can easily manage the encryption and decryption process,
making it a useful tool for various applications.

As an alternative, you can also use the invisible_ink gem, which provides
the same functionality as this script, with the added benefit of being easily
integrated into any Ruby project. This gem offers a more streamlined and
maintainable approach to file encryption and decryption in your Ruby
applications, without the need to implement the entire script yourself.

#!/usr/bin/env ruby
require "active_support/encrypted_file"
require "securerandom"

# ℹ️ Set the command from the first argument
command = ARGV.shift

# ℹ️ Return early if no command was passed
if command.nil?
  puts "Please pass 'setup', 'write [FILE]', or 'read [FILE]'"
  exit 1
end

# ℹ️ Create an encrypted file instance.
def build_encrypted_file(file)
  ActiveSupport::EncryptedFile.new(
    content_path: file,
    # ℹ️ The key will be generated during the 'setup' script
    key_path: "invisible_ink.key",
    # ℹ️ Alternatively use an environment variable to store the key
    env_key: "INVISIBLE_INK_KEY",
    raise_if_missing_key: true
  )
end

# ℹ️ Handle case where ActiveSupport::EncryptedFile::MissingKeyError is raised
def handle_missing_key(error)
  puts "ERROR: #{error}"
  puts ""
  puts "Did you run 'setup'?"
  exit 1
end

# ℹ️ Handle case where a file was not passed as an argument
def handle_missing_file_argument
  puts "Please pass a file"
  exit 1
end

case command
when "write"
  # ℹ️ Set the file from the second argument
  file = ARGV.shift
  # ℹ️ Ensure the file was passed as an argument
  handle_missing_file_argument if file.nil?
  # ℹ️ Return early if there is no system editor to edit the file
  if ENV["EDITOR"].to_s.empty?
    puts "No $EDITOR to open file in"
    exit 1
  end
  begin
    encrypted_file = build_encrypted_file(file)
    # ℹ️ Writing a blank file creates the file in cases where it does not yet
    # exist. We need a file before we can write to it.
    encrypted_file.write(nil) unless File.exist?(file)
    # ℹ️ Open the file in the system $EDITOR using a temporary path
    encrypted_file.change do |tmp_path|
      system(ENV["EDITOR"], tmp_path.to_s)
    # ℹ️ Handle case where the $EDITOR is closed before the file was saved
    rescue Interrupt
      puts "File not saved"
    end
  # ℹ️ Print message to user if the key is missing
  rescue ActiveSupport::EncryptedFile::MissingKeyError => error
    handle_missing_key(error)
  end
when "read"
  begin
  # ℹ️ Set the file from the second argument
    file = ARGV.shift
  # ℹ️ Ensure the file was passed as an argument
    handle_missing_file_argument if file.nil?
    encrypted_file = build_encrypted_file(file)
    # ℹ️ Print decrypted file contents to $STDOUT
    puts encrypted_file.read
  # ℹ️ Print message to user if the key is missing
  rescue ActiveSupport::EncryptedFile::MissingKeyError => error
    handle_missing_key(error)
  end
when "setup"
  # ℹ️ Return early if there is already a key
  if File.exist?("invisible_ink.key")
    puts "ERROR: invisible_ink.key already exists"
    exit 1
  else
    # ℹ️ Prevent key from being saved to version control
    File.open(".gitignore", "a") { |file| file.puts("invisible_ink.key") }
    # ℹ️ Generate key
    key = ActiveSupport::EncryptedFile.generate_key
    # ℹ️ Write the key to a file
    File.write("invisible_ink.key", key)
    puts "invisible_ink.key generated"
  end
end

How to click links in Rails Mailers when writing tests

Steve Polito — Mon, 13 Mar 2023 16:22:24 +0000

In this tutorial, you'll learn how to write a test that clicks a link in a Rails mailer. This is particularly useful when testing emails with links that require unique tokens or may expire, such as password reset emails. We'll cover the steps to create a helper method that uses Capybara to find and click the link in the email, allowing you to fully test the functionality of a passpord reset email.

Find the link using Nokogiri

To extract links from emails, we can use Nokogiri. Nokogiri converts the body of the email into a document object, which we can navigate to extract links based on their text.

# test/integration/password_reset_test.rb
require 'test_helper'

class PasswordResetTest < ActionDispatch::IntegrationTest
  test "resets password" do
    user = User.create!(email: "user@example.com")

    post user_password_path, params: { user: { email: "user@example.com"} }

    # ℹ️ Get the latest email
    email = ActionMailer::Base.deliveries.last
    # ℹ️ Parse the email's HTML with Nokogiri
    doc = Nokogiri::HTML(email.body.to_s)
    # ℹ️ Find the link using Nokogiri
    url = doc.at_css('a:contains("Change my password")')[:href]
    # => "http://www.example.com/users/password/edit?reset_password_token=123abc"

    get url

    assert_select "h1", text: "Change your password"
  end
end

Replace Nokogiri with Capybara

One way to improve the current implementation is by swapping out Nokogiri for Capybara. This would enhance the readability of the test and allow us to utilize Capybara's DSL to locate more email content.

# test/integration/password_reset_test.rb
require 'test_helper'

class PasswordResetTest < ActionDispatch::IntegrationTest
  test "resets password" do
    user = User.create!(email: "user@example.com")

    post user_password_path, params: { user: { email: "user@example.com"} }

    # ℹ️ Get the latest email
    email = ActionMailer::Base.deliveries.last
    # ℹ️ Parse the email's HTML with Capybara
    page = Capybara.string(email.body.to_s)
    # ℹ️ Find the link using Capybara
    url = page.find(:link, "Change my password")[:href]
    # => "http://www.example.com/users/password/edit?reset_password_token=123abc"

    get url

    assert_select "h1", text: "Change your password"
  end
end

Create a test helper to return the link

The Capybara implementation is helpful, but it could be made simpler. We can create a method that takes an email and a string, and uses Capybara to find and return the link with that text. This method could be extracted into a helper to hide the implementation details.

Since it’s best practice for mailers to use absolute URLs, we can take this opportunity to convert them to relative URLs. The reason for this is to avoid making requests to "example.com" which is the default test host for Rails action mailer. This isn't an issue for integration tests, but it can cause problems for system tests because Capybara may try to visit the external URL instead of staying on the localhost.

# test/test_helper.rb
class ActiveSupport::TestCase
  # ℹ️ Get the link from the email
  def email_link(email, string)
    document = Capybara.string(email.body.to_s)
    link = document.find(:link, string)[:href]

    # ℹ️ Return the relative link to ensure the request stays local
    localize_link(link)
  end

  private

  def localize_link(link)
    uri = URI.parse(link)

    if uri.query
      "#{uri.path}?#{uri.query}"
    else
      uri.path
    end
  end
end

# test/integration/password_reset_test.rb
require 'test_helper'

class PasswordResetTest < ActionDispatch::IntegrationTest
  test "resets password" do
    user = User.create!(email: "user@example.com")

    post user_password_path, params: { user: { email: "user@example.com"} }

    email = ActionMailer::Base.deliveries.last
    # ℹ️ Our helper hides the implementation and returns the relative url
    get email_link(email, "Change my password")

    assert_select "h1", text: "Change your password"
  end
end

Create a test helper to set the current email

To make our test easier to read, we can create another helper. This helper will find the most recent email sent to a specific email address and set it as the current_email. Without this helper, the current_email will just default to the last email sent, regardless of the recipient.

# test/test_helper.rb
class ActiveSupport::TestCase
  # ℹ️ Find the latest email sent to a particular email address
  def open_latest_email_for(email_address)
    @current_email = ActionMailer::Base.deliveries.reverse.detect do |email|
      email.to.include?(email_address)
    end
  end

  # ℹ️ If the @current_email is not set, default to the last email delivered
  def current_email
    @current_email ||= ActionMailer::Base.deliveries.last
  end

  def email_link(email, string)
    document = Capybara.string(email.body.to_s)
    link = document.find(:link, string)[:href]

    localize_link(link)
  end

  private

  def localize_link(link)
    uri = URI.parse(link)

    if uri.query
      "#{uri.path}?#{uri.query}"
    else
      uri.path
    end
  end
end

# test/integration/password_reset_test.rb
require 'test_helper'

class PasswordResetTest < ActionDispatch::IntegrationTest
  test "resets password" do
    user = User.create!(email: "user@example.com")

    post user_password_path, params: { user: { email: "user@example.com"} }

    # ℹ️ This will set the @current_email
    open_latest_email_for("user@example.com")
    # ℹ️ Now we can pass current_email to the method
    get email_link(current_email, "Change my password")

    assert_select "h1", text: "Change your password"
  end
end

Rails Setup Script Improvements

Steve Polito — Sat, 15 Jan 2022 18:43:09 +0000

Rails ships with a setup script that automates bootstrapping a new application, but did you know that you're free to edit this script? In this quick tutorial, I'll show you how you can improve the default Rails setup script to create a more consistent and helpful onboarding experience for folks on your team.

Demo

Simply clone this repo and run ./bin/setup.

Step 1. Update the Command That Prepares the Database

--- a/bin/setup
+++ b/bin/setup
@@ -23,7 +23,7 @@ FileUtils.chdir APP_ROOT do
   # end

   puts "\n== Preparing database =="
-  system! "bin/rails db:prepare"
+  system! "bin/rails db:reset"

   puts "\n== Removing old logs and tempfiles =="
   system! "bin/rails log:clear tmp:clear"

What's Going On Here?

Running bin/rails db:reset will do the following:

Run bin/rails db:drop.

Run bin/rails db:setup.

The bin/rails db:setup command will do the following:

Create the database.

Load the schema.

Seed the database.

This ensures the database will always be in the same state after running ./bin/setup. This is because bin/rails db:prepare will not seed the database if the database already exists which could result in inconsistent outcomes.

Step 2. Create a Job to Seed the Database

# app/jobs/database_seeder_job.rb
class DatabaseSeederJob < ApplicationJob
  queue_as :default

  DEFAULT_USER_EMAIL = "user@example.com"
  DEFAULT_USER_PASSWORD = "password"

  def perform
    ActiveRecord::Base.transaction do
      create_default_user
      create_users
      create_posts
    end
  end

  private

  def create_default_user
    User.create!(
      email: DEFAULT_USER_EMAIL,
      password: DEFAULT_USER_PASSWORD,
      password_confirmation: DEFAULT_USER_PASSWORD,
    )
  end

  def create_users
    10.times do |i|
      User.create!(
        email: "user-#{i}@example.com",
        password: DEFAULT_USER_PASSWORD,
        password_confirmation: DEFAULT_USER_PASSWORD,
      )
    end
  end

  def create_posts
    User.all.each_with_index do |user, index|
      Post.create!(
        title: "\"Title for post #{index}\","
        body: "Body for post #{index}",
        user: user
      )
    end
  end
end

# db/seeds.rb
puts "\n== Seeding database =="
DatabaseSeederJob.perform_now

What's Going On Here?

We could run all the commands from each method inline in db/seeds.rb, but that script is run in isolation. By abstracting this into a job, we can call it anywhere within our application. This is important because we'll need access to those constants when we print the instructions to the console.

Note that we call puts so that we'll know when this part of the setup script is being called.

Step 3. Print Instructions When Setup is Complete

# app/jobs/post_setup_instructions_job.rb
class PostSetupInstructionsJob < ApplicationJob
  queue_as :default

  def perform
    puts "\n== Setup complete! 🎉  =="
    puts "\n👉  Run \"rails s\" to start the development server."
    puts "\n== You can login with the following account  =="
    puts "\n🔗  #{Rails.application.routes.url_helpers.new_user_session_url(host: "localhost", port: 3000)}"
    puts "\📧  Email: #{DatabaseSeederJob::DEFAULT_USER_EMAIL}"
    puts "\🔐  Password: #{DatabaseSeederJob::DEFAULT_USER_PASSWORD}"
    puts "\n"
  end

end

# lib/tasks/post_setup_instructions.rake
namespace :post_setup_instructions do
  desc "Prints instructions once setup is complete."
  task perform: :environment do
    PostSetupInstructionsJob.perform_now
  end

end

--- a/bin/setup
+++ b/bin/setup
@@ -30,4 +30,6 @@ FileUtils.chdir APP_ROOT do

   puts "\n== Restarting application server =="
   system! "bin/rails restart"
+
+  system! "bin/rails post_setup_instructions:perform"
 end

What's Going On Here?

We create PostSetupInstructionsJob to print out the instructions for accessing our application. This allows us to access the constants we created in step 2.

Note that we have to call Rails.application.routes.url_helpers to gain access to the url_for method.

You'll also note that we pass in a host and port as options to avoid raising a Missing host to link to! error.

We create a post_setup_instructions task the calls the PostSetupInstructionsJob. This is so we can call it from ./bin/setup.

Rails Authentication From Scratch (A Complete Guide)

Steve Polito — Tue, 04 Jan 2022 13:33:53 +0000

If you're like me then you probably take Devise for granted because you're too intimidated to roll your own authentication system. As powerful as Devise is, it's not perfect. There are plenty of cases where I've reached for it only to end up constrained by its features and design, and wished I could customize it exactly to my liking.

Fortunately, Rails gives you all the tools you need to roll your own authentication system from scratch without needing to depend on a gem. The challenge is just knowing how to account for edge cases while being cognizant of security and best practices.

Previous Versions

This guide is continuously updated to account for best practices. You can view previous releases here.

Step 1: Build User Model

Generate User model.

rails g model User email:string

# db/migrate/[timestamp]_create_users.rb
class CreateUsers < ActiveRecord::Migration[6.1]
  def change
    create_table :users do |t|
      t.string :email, null: false

      t.timestamps
    end

    add_index :users, :email, unique: true
  end
end

Run migrations.

rails db:migrate

Add validations and callbacks.

# app/models/user.rb
class User < ApplicationRecord
  before_save :downcase_email

  validates :email, format: {with: URI::MailTo::EMAIL_REGEXP}, presence: true, uniqueness: true

  private

  def downcase_email
    self.email = email.downcase
  end
end

What's Going On Here?

We prevent empty values from being saved into the email column through a null: false constraint in addition to the presence validation.

We enforce unique email addresses at the database level through add_index :users, :email, unique: true in addition to a uniqueness validation.

We ensure all emails are valid through a format validation.

We save all emails to the database in a downcase format via a before_save callback such that the values are saved in a consistent format.

We use URI::MailTo::EMAIL_REGEXP that comes with Ruby to validate that the email address is properly formatted.

Step 2: Add Confirmation and Password Columns to Users Table

Create migration.

rails g migration add_confirmation_and_password_columns_to_users confirmed_at:datetime password_digest:string

Update the migration.

# db/migrate/[timestamp]_add_confirmation_and_password_columns_to_users.rb
class AddConfirmationAndPasswordColumnsToUsers < ActiveRecord::Migration[6.1]
  def change
    add_column :users, :confirmed_at, :datetime
    add_column :users, :password_digest, :string, null: false
  end
end

What's Going On Here?

The confirmed_at column will be set when a user confirms their account. This will help us determine who has confirmed their account and who has not.

The password_digest column will store a hashed version of the user's password. This is provided by the has_secure_password method.

Run migrations.

rails db:migrate

Enable and install BCrypt.

This is needed to use has_secure_password.

# Gemfile
gem 'bcrypt', '~> 3.1.7'

bundle install

Update the User Model.

# app/models/user.rb
class User < ApplicationRecord
  CONFIRMATION_TOKEN_EXPIRATION = 10.minutes

  has_secure_password

  before_save :downcase_email

  validates :email, format: {with: URI::MailTo::EMAIL_REGEXP}, presence: true, uniqueness: true

  def confirm!
    update_columns(confirmed_at: Time.current)
  end

  def confirmed?
    confirmed_at.present?
  end

  def generate_confirmation_token
    signed_id expires_in: CONFIRMATION_TOKEN_EXPIRATION, purpose: :confirm_email
  end

  def unconfirmed?
    !confirmed?
  end

  private

  def downcase_email
    self.email = email.downcase
  end
end

What's Going On Here?

The has_secure_password method is added to give us an API to work with the password_digest column.

The confirm! method will be called when a user confirms their email address. We still need to build this feature.

The confirmed? and unconfirmed? methods allow us to tell whether a user has confirmed their email address or not.

The generate_confirmation_token method creates a signed_id that will be used to securely identify the user. For added security, we ensure that this ID will expire in 10 minutes (this can be controlled with the CONFIRMATION_TOKEN_EXPIRATION constant) and give it an explicit purpose of :confirm_email. This will be useful when we build the confirmation mailer.

Step 3: Create Sign Up Pages

Create a simple home page since we'll need a place to redirect users to after they sign up.

rails g controller StaticPages home

Create Users Controller.

rails g controller Users

# app/controllers/users_controller.rb
class UsersController < ApplicationController

  def create
    @user = User.new(user_params)
    if @user.save
      redirect_to root_path, notice: "Please check your email for confirmation instructions."
    else
      render :new, status: :unprocessable_entity
    end
  end

  def new
    @user = User.new
  end

  private

  def user_params
    params.require(:user).permit(:email, :password, :password_confirmation)
  end
end

Build sign-up form.

<!-- app/views/shared/_form_errors.html.erb -->
<% if object.errors.any? %>
  <ul>
    <% object.errors.full_messages.each do |message| %>
      <li><%= message %></li>
    <% end %>
  </ul>
<% end %>

<!-- app/views/users/new.html.erb -->
<%= form_with model: @user, url: sign_up_path do |form| %>
  <%= render partial: "shared/form_errors", locals: { object: form.object } %>
  <div>
    <%= form.label :email %>
    <%= form.email_field :email, required: true %>
  </div>
  <div>
    <%= form.label :password %>
    <%= form.password_field :password, required: true %>
  </div>
  <div>
    <%= form.label :password_confirmation %>
    <%= form.password_field :password_confirmation, required: true %>
  </div>
  <%= form.submit "Sign Up" %>
<% end %>

Update routes.

# config/routes.rb
Rails.application.routes.draw do
  root "static_pages#home"
  post "sign_up", to: "users#create"
  get "sign_up", to: "users#new"
end

Step 4: Create Confirmation Pages

Users now have a way to sign up, but we need to verify their email address to prevent SPAM.

Create Confirmations Controller.

rails g controller Confirmations

# app/controllers/confirmations_controller.rb
class ConfirmationsController < ApplicationController

  def create
    @user = User.find_by(email: params[:user][:email].downcase)

    if @user.present? && @user.unconfirmed?
      redirect_to root_path, notice: "Check your email for confirmation instructions."
    else
      redirect_to new_confirmation_path, alert: "We could not find a user with that email or that email has already been confirmed."
    end
  end

  def edit
    @user = User.find_signed(params[:confirmation_token], purpose: :confirm_email)

    if @user.present?
      @user.confirm!
      redirect_to root_path, notice: "Your account has been confirmed."
    else
      redirect_to new_confirmation_path, alert: "Invalid token."
    end
  end

  def new
    @user = User.new
  end

end

Build confirmation pages.

This page will be used in the case where a user did not receive their confirmation instructions and needs to have them resent.

<!-- app/views/confirmations/new.html.erb -->
<%= form_with model: @user, url: confirmations_path do |form| %>
  <%= form.email_field :email, required: true %>
  <%= form.submit "Confirm Email" %>
<% end %>

Update routes.

# config/routes.rb
Rails.application.routes.draw do
  ...
  resources :confirmations, only: [:create, :edit, :new], param: :confirmation_token
end

What's Going On Here?

The create action will be used to resend confirmation instructions to an unconfirmed user. We still need to build this mailer, and we still need to send this mailer when a user initially signs up. This action will be requested via the form on app/views/confirmations/new.html.erb. Note that we call downcase on the email to account for case sensitivity when searching.

The edit action is used to confirm a user's email. This will be the page that a user lands on when they click the confirmation link in their email. We still need to build this. Note that we're looking up a user through the find_signed method and not their email or ID. This is because The confirmation_token is randomly generated and can't be guessed or tampered with unlike an email or numeric ID. This is also why we added param: :confirmation_token as a named route parameter.

You'll remember that the confirmation_token is a signed_id, and is set to expire in 10 minutes. You'll also note that we need to pass the method purpose: :confirm_email to be consistent with the purpose that was set in the generate_confirmation_token method.

Step 5: Create Confirmation Mailer

Now we need a way to send a confirmation email to our users for them to actually confirm their accounts.

Create a confirmation mailer.

rails g mailer User confirmation

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  default from: User::MAILER_FROM_EMAIL

  def confirmation(user, confirmation_token)
    @user = user
    @confirmation_token = confirmation_token

    mail to: @user.email, subject: "Confirmation Instructions"
  end
end

<!-- app/views/user_mailer/confirmation.html.erb -->
<h1>Confirmation Instructions</h1>

<%= link_to "Click here to confirm your email.", edit_confirmation_url(@confirmation_token) %>

<!-- app/views/user_mailer/confirmation.text.erb -->
Confirmation Instructions

<%= edit_confirmation_url(@confirmation_token) %>

Update User Model.

# app/models/user.rb
class User < ApplicationRecord
  ...
  MAILER_FROM_EMAIL = "no-reply@example.com"
  ...
  def send_confirmation_email!
    confirmation_token = generate_confirmation_token
    UserMailer.confirmation(self, confirmation_token).deliver_now
  end

end

What's Going On Here?

The MAILER_FROM_EMAIL constant is a way for us to set the email used in the UserMailer. This is optional.

The send_confirmation_email! method will create a new confirmation_token. This is to ensure confirmation links expire and cannot be reused. It will also send the confirmation email to the user.

We call update_columns so that the updated_at/updated_on columns are not updated. This is personal preference, but those columns should typically only be updated when the user updates their email or password.

The links in the mailer will take the user to ConfirmationsController#edit at which point they'll be confirmed.

Configure Action Mailer so that links work locally.

Add a host to the test and development (and later the production) environments so that urls will work in mailers.

# config/environments/test.rb
Rails.application.configure do
  ...
  config.action_mailer.default_url_options = { host: "example.com" }
end

# config/environments/development.rb
Rails.application.configure do
  ...
  config.action_mailer.default_url_options = { host: "localhost", port: 3000 }
end

Update Controllers.

Now we can send a confirmation email when a user signs up or if they need to have it resent.

# app/controllers/confirmations_controller.rb
class ConfirmationsController < ApplicationController

  def create
    @user = User.find_by(email: params[:user][:email].downcase)

    if @user.present? && @user.unconfirmed?
      @user.send_confirmation_email!
      ...
    end
  end

end

# app/controllers/users_controller.rb
class UsersController < ApplicationController

  def create
    @user = User.new(user_params)
    if @user.save
      @user.send_confirmation_email!
      ...
    end
  end

end

Step 6: Create Current Model and Authentication Concern

Create a model to store the current user.

# app/models/current.rb
class Current < ActiveSupport::CurrentAttributes
  attribute :user
end

Create a Concern to store helper methods that will be shared across the application.

# app/controllers/concerns/authentication.rb
module Authentication
  extend ActiveSupport::Concern

  included do
    before_action :current_user
    helper_method :current_user
    helper_method :user_signed_in?
  end

  def login(user)
    reset_session
    session[:current_user_id] = user.id
  end

  def logout
    reset_session
  end

  def redirect_if_authenticated
    redirect_to root_path, alert: "You are already logged in." if user_signed_in?
  end

  private

  def current_user
    Current.user ||= session[:current_user_id] && User.find_by(id: session[:current_user_id])
  end

  def user_signed_in?
    Current.user.present?
  end

end

Load the Authentication Concern into the Application Controller.

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  include Authentication
end

What's Going On Here?

The Current class inherits from ActiveSupport::CurrentAttributes which allows us to keep all per-request attributes easily available to the whole system. In essence, this will allow us to set a current user and have access to that user during each request to the server.

The Authentication Concern provides an interface for logging the user in and out. We load it into the ApplicationController so that it will be used across the whole application.

The login method first resets the session to account for session fixation.

We set the user's ID in the session so that we can have access to the user across requests. The user's ID won't be stored in plain text. The cookie data is cryptographically signed to make it tamper-proof. And it is also encrypted so anyone with access to it can't read its contents.

The logout method simply resets the session.

The redirect_if_authenticated method checks to see if the user is logged in. If they are, they'll be redirected to the root_path. This will be useful on pages an authenticated user should not be able to access, such as the login page.

The current_user method returns a User and sets it as the user on the Current class we created. We use memoization to avoid fetching the User each time we call the method. We call the before_action filter so that we have access to the current user before each request. We also add this as a helper_method so that we have access to current_user in the views.

The user_signed_in? method simply returns true or false depending on whether the user is signed in or not. This is helpful for conditionally rendering items in views.

Step 7: Create Login Page

Generate Sessions Controller.

rails g controller Sessions

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  before_action :redirect_if_authenticated, only: [:create, :new]

  def create
    @user = User.find_by(email: params[:user][:email].downcase)
    if @user
      if @user.unconfirmed?
        redirect_to new_confirmation_path, alert: "Incorrect email or password."
      elsif @user.authenticate(params[:user][:password])
        login @user
        redirect_to root_path, notice: "Signed in."
      else
        flash.now[:alert] = "Incorrect email or password."
        render :new, status: :unprocessable_entity
      end
    else
      flash.now[:alert] = "Incorrect email or password."
      render :new, status: :unprocessable_entity
    end
  end

  def destroy
    logout
    redirect_to root_path, notice: "Signed out."
  end

  def new
  end

end

Update routes.

# config/routes.rb
Rails.application.routes.draw do
  ...
  post "login", to: "sessions#create"
  delete "logout", to: "sessions#destroy"
  get "login", to: "sessions#new"
end

Add sign-in form.

<!-- app/views/sessions/new.html.erb -->
<%= form_with url: login_path, scope: :user do |form| %>
  <div>
    <%= form.label :email %>
    <%= form.email_field :email, required: true %>
  </div>
  <div>
    <%= form.label :password %>
    <%= form.password_field :password, required: true %>
  </div>
  <%= form.submit "Sign In" %>
<% end %>

What's Going On Here?

The create method simply checks if the user exists and is confirmed. If they are, then we check their password. If the password is correct, we log them in via the login method we created in the Authentication Concern. Otherwise, we render an alert.

We're able to call user.authenticate because of has_secure_password

Note that we call downcase on the email to account for case sensitivity when searching.

Note that we set the flash to "Incorrect email or password." if the user is unconfirmed. This prevents leaking email addresses.

The destroy method simply calls the logout method we created in the Authentication Concern.

The login form is passed a scope: :user option so that the params are namespaced as params[:user][:some_value]. This is not required, but it helps keep things organized.

Step 8: Update Existing Controllers

Update Controllers to prevent authenticated users from accessing pages intended for anonymous users.

# app/controllers/confirmations_controller.rb
class ConfirmationsController < ApplicationController
  before_action :redirect_if_authenticated, only: [:create, :new]

  def edit
    ...
    if @user.present?
      @user.confirm!
      login @user
      ...
    else
    end
    ...
  end
end

Note that we also call login @user once a user is confirmed. That way they'll be automatically logged in after confirming their email.

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  before_action :redirect_if_authenticated, only: [:create, :new]
  ...
end

Step 9: Add Password Reset Functionality

Update User Model.

# app/models/user.rb
class User < ApplicationRecord
  ...
  PASSWORD_RESET_TOKEN_EXPIRATION = 10.minutes
  ...
  def generate_password_reset_token
    signed_id expires_in: PASSWORD_RESET_TOKEN_EXPIRATION, purpose: :reset_password
  end
  ...
  def send_password_reset_email!
    password_reset_token = generate_password_reset_token
    UserMailer.password_reset(self, password_reset_token).deliver_now
  end
  ...
end

Update User Mailer.

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  ...
  def password_reset(user, password_reset_token)
    @user = user
    @password_reset_token = password_reset_token

    mail to: @user.email, subject: "Password Reset Instructions"
  end
end

<!-- app/views/user_mailer/password_reset.html.erb -->
<h1>Password Reset Instructions</h1>

<%= link_to "Click here to reset your password.", edit_password_url(@password_reset_token) %>

<!-- app/views/user_mailer/password_reset.text.erb -->
Password Reset Instructions

<%= edit_password_url(@password_reset_token) %>

What's Going On Here?

The generate_password_reset_token method creates a signed_id that will be used to securely identify the user. For added security, we ensure that this ID will expire in 10 minutes (this can be controlled with the PASSWORD_RESET_TOKEN_EXPIRATION constant) and give it an explicit purpose of :reset_password.

The send_password_reset_email! method will create a new password_reset_token. This is to ensure password reset links expire and cannot be reused. It will also send the password reset email to the user.

Step 10: Build Password Reset Forms

Create Passwords Controller.

rails g controller Passwords

# app/controllers/passwords_controller.rb
class PasswordsController < ApplicationController
  before_action :redirect_if_authenticated

  def create
    @user = User.find_by(email: params[:user][:email].downcase)
    if @user.present?
      if @user.confirmed?
        @user.send_password_reset_email!
        redirect_to root_path, notice: "If that user exists we've sent instructions to their email."
      else
        redirect_to new_confirmation_path, alert: "Please confirm your email first."
      end
    else
      redirect_to root_path, notice: "If that user exists we've sent instructions to their email."
    end
  end

  def edit
    @user = User.find_signed(params[:password_reset_token], purpose: :reset_password)
    if @user.present? && @user.unconfirmed?
      redirect_to new_confirmation_path, alert: "You must confirm your email before you can sign in."
    elsif @user.nil?
      redirect_to new_password_path, alert: "Invalid or expired token."
    end
  end

  def new
  end

  def update
    @user = User.find_signed(params[:password_reset_token], purpose: :reset_password)
    if @user
      if @user.unconfirmed?
        redirect_to new_confirmation_path, alert: "You must confirm your email before you can sign in."
      elsif @user.update(password_params)
        redirect_to login_path, notice: "Sign in."
      else
        flash.now[:alert] = @user.errors.full_messages.to_sentence
        render :edit, status: :unprocessable_entity
      end
    else
      flash.now[:alert] = "Invalid or expired token."
      render :new, status: :unprocessable_entity
    end
  end

  private

  def password_params
    params.require(:user).permit(:password, :password_confirmation)
  end
end

What's Going On Here?

The create action will send an email to the user containing a link that will allow them to reset the password. The link will contain their password_reset_token which is unique and expires. Note that we call downcase on the email to account for case sensitivity when searching.

You'll remember that the password_reset_token is a signed_id, and is set to expire in 10 minutes. You'll also note that we need to pass the method purpose: :reset_password to be consistent with the purpose that was set in the generate_password_reset_token method.

Note that we return Invalid or expired token. if the user is not found. This makes it difficult for a bad actor to use the reset form to see which email accounts exist on the application.

The edit action simply renders the form for the user to update their password. It attempts to find a user by their password_reset_token. You can think of the password_reset_token as a way to identify the user much like how we normally identify records by their ID. However, the password_reset_token is randomly generated and will expire so it's more secure.

The new action simply renders a form for the user to put their email address in to receive the password reset email.

The update also ensures the user is identified by their password_reset_token. It's not enough to just do this on the edit action since a bad actor could make a PUT request to the server and bypass the form.

If the user exists and is confirmed we update their password to the one they will set in the form. Otherwise, we handle each failure case differently.

Update Routes.

# config/routes.rb
Rails.application.routes.draw do
  ...
  resources :passwords, only: [:create, :edit, :new, :update], param: :password_reset_token
end

What's Going On Here?

We add param: :password_reset_token as a named route parameter so that we can identify users by their password_reset_token and not id. This is similar to what we did with the confirmations routes and ensures a user cannot be identified by their ID.

Build forms.

<!-- app/views/passwords/new.html.erb -->
<%= form_with url: passwords_path, scope: :user do |form| %>
  <%= form.email_field :email, required: true %>
  <%= form.submit "Reset Password" %>
<% end %>

<!-- app/views/passwords/edit.html.erb -->
<%= form_with url: password_path(params[:password_reset_token]), scope: :user, method: :put do |form| %>
  <div>
    <%= form.label :password %>
    <%= form.password_field :password, required: true %>
  </div>
  <div>
    <%= form.label :password_confirmation %>
    <%= form.password_field :password_confirmation, required: true %>
  </div>
  <%= form.submit "Update Password" %>
<% end %>

What's Going On Here?

The password reset form is passed a scope: :user option so that the params are namespaced as params[:user][:some_value]. This is not required, but it helps keep things organized.

Step 11: Add Unconfirmed Email Column To Users Table

Create and run migration.

rails g migration add_unconfirmed_email_to_users unconfirmed_email:string
rails db:migrate

Update User Model.

# app/models/user.rb
class User < ApplicationRecord
  ...
  attr_accessor :current_password
  ...
  before_save :downcase_unconfirmed_email
  ...
  validates :unconfirmed_email, format: {with: URI::MailTo::EMAIL_REGEXP, allow_blank: true}

  def confirm!
    if unconfirmed_or_reconfirming?
      if unconfirmed_email.present?
        return false unless update(email: unconfirmed_email, unconfirmed_email: nil)
      end
      update_columns(confirmed_at: Time.current)
    else
      false
    end
  end
  ...
  def confirmable_email
    if unconfirmed_email.present?
      unconfirmed_email
    else
      email
    end
  end
  ...
  def reconfirming?
    unconfirmed_email.present?
  end

  def unconfirmed_or_reconfirming?
    unconfirmed? || reconfirming?
  end

  private
  ...
  def downcase_unconfirmed_email
    return if unconfirmed_email.nil?
    self.unconfirmed_email = unconfirmed_email.downcase
  end

end

What's Going On Here?

We add a unconfirmed_email column to the users table so that we have a place to store the email a user is trying to use after their account has been confirmed with their original email.

We add attr_accessor :current_password so that we'll be able to use f.password_field :current_password in the user form (which doesn't exist yet). This will allow us to require the user to submit their current password before they can update their account.

We ensure to format the unconfirmed_email before saving it to the database. This ensures all data is saved consistently.

We add validations to the unconfirmed_email column ensuring it's a valid email address.

We update the confirm! method to set the email column to the value of the unconfirmed_email column, and then clear out the unconfirmed_email column. This will only happen if a user is trying to confirm a new email address. Note that we return false if updating the email address fails. This could happen if a user tries to confirm an email address that has already been confirmed.

We add the confirmable_email method so that we can call the correct email in the updated UserMailer.

We add reconfirming? and unconfirmed_or_reconfirming? to help us determine what state a user is in. This will come in handy later in our controllers.

Update User Mailer.

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer

  def confirmation(user, confirmation_token)
    ...
    mail to: @user.confirmable_email, subject: "Confirmation Instructions"
  end
end

Update Confirmations Controller.

# app/controllers/confirmations_controller.rb
class ConfirmationsController < ApplicationController
  ...
  def edit
    ...
    if @user.present?
      if @user.confirm!
        login @user
        redirect_to root_path, notice: "Your account has been confirmed."
      else
        redirect_to new_confirmation_path, alert: "Something went wrong."
      end
    else
      ...
    end
  end
  ...
end

What's Going On Here?

We update the edit method to account for the return value of @user.confirm!. If for some reason @user.confirm! returns false (which would most likely happen if the email has already been taken) then we render a generic error. This prevents leaking email addresses.

Step 12: Update Users Controller

Update Authentication Concern.

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  def authenticate_user!
    redirect_to login_path, alert: "You need to login to access that page." unless user_signed_in?
  end
  ...
end

What's Going On Here?

The authenticate_user! method can be called to ensure an anonymous user cannot access a page that requires a user to be logged in. We'll need this when we build the page allowing a user to edit or delete their profile.

Add destroy, edit and update methods. Modify create method and user_params.

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  before_action :authenticate_user!, only: [:edit, :destroy, :update]
  ...
  def create
    @user = User.new(create_user_params)
    ...
  end

  def destroy
    current_user.destroy
    reset_session
    redirect_to root_path, notice: "Your account has been deleted."
  end

  def edit
    @user = current_user
  end
  ...
  def update
    @user = current_user
    if @user.authenticate(params[:user][:current_password])
      if @user.update(update_user_params)
        if params[:user][:unconfirmed_email].present?
          @user.send_confirmation_email!
          redirect_to root_path, notice: "Check your email for confirmation instructions."
        else
          redirect_to root_path, notice: "Account updated."
        end
      else
        render :edit, status: :unprocessable_entity
      end
    else
      flash.now[:error] = "Incorrect password"
      render :edit, status: :unprocessable_entity
    end
  end

  private

  def create_user_params
    params.require(:user).permit(:email, :password, :password_confirmation)
  end

  def update_user_params
    params.require(:user).permit(:current_password, :password, :password_confirmation, :unconfirmed_email)
  end
end

What's Going On Here?

We call authenticate_user! before editing, destroying, or updating a user since only an authenticated user should be able to do this.

We update the create method to accept create_user_params (formerly user_params). This is because we're going to require different parameters for creating an account vs. editing an account.

The destroy action simply deletes the user and logs them out. Note that we're calling current_user, so this action can only be scoped to the user who is logged in.

The edit action simply assigns @user to the current_user so that we have access to the user in the edit form.

The update action first checks if their password is correct. Note that we're passing this in as current_password and not password. This is because we still want a user to be able to change their password and therefore we need another parameter to store this value. This is also why we have a private update_user_params method.

If the user is updating their email address (via unconfirmed_email) we send a confirmation email to that new email address before setting it as the email value.

We force a user to always put in their current_password as an extra security measure in case someone leaves their browser open on a public computer.

Update routes.

# config/routes.rb
Rails.application.routes.draw do
  ...
  put "account", to: "users#update"
  get "account", to: "users#edit"
  delete "account", to: "users#destroy"
  ...
end

Create an edit form.

<!-- app/views/users/edit.html.erb -->
<%= form_with model: @user, url: account_path, method: :put do |form| %>
  <%= render partial: "shared/form_errors", locals: { object: form.object } %>
  <div>
    <%= form.label :email, "Current Email" %>
    <%= form.email_field :email, disabled: true %>
  </div>
  <div>
    <%= form.label :unconfirmed_email, "New Email" %>
    <%= form.text_field :unconfirmed_email %>
  </div>
  <div>
    <%= form.label :password, "Password (leave blank if you don't want to change it)" %>
    <%= form.password_field :password %>
  </div>
  <div>
    <%= form.label :password_confirmation %>
    <%= form.password_field :password_confirmation %>
  </div>
  <hr/>
  <div>
    <%= form.label :current_password, "Current password (we need your current password to confirm your changes)" %>
    <%= form.password_field :current_password, required: true %>
  </div>
  <%= form.submit "Update Account" %>
<% end %>

What's Going On Here?

We disable the email field to ensure we're not passing that value back to the controller. This is just so the user can see what their current email is.

We require the current_password field since we'll always want a user to confirm their password before making changes.

The password and password_confirmation fields are there if a user wants to update their current password.

Step 13: Update Confirmations Controller

Update edit action.

# app/controllers/confirmations_controller.rb
class ConfirmationsController < ApplicationController
  ...
  def edit
    ...
    if @user.present? && @user.unconfirmed_or_reconfirming?
      ...
    end
  end
  ...
end

What's Going On Here?

We add @user.unconfirmed_or_reconfirming? to the conditional to ensure only unconfirmed users or users who are reconfirming can access this page. This is necessary since we're now allowing users to confirm new email addresses.

Step 14: Add Remember Token Column to Users Table

Create migration.

rails g migration add_remember_token_to_users remember_token:string

Update migration.

# db/migrate/[timestamp]_add_remember_token_to_users.rb
class AddRememberTokenToUsers < ActiveRecord::Migration[6.1]
  def change
    add_column :users, :remember_token, :string, null: false
    add_index :users, :remember_token, unique: true
  end
end

What's Going On Here?

We add null: false to ensure this column always has a value.

We add a unique index to ensure this column has unique data.

Run migrations.

rails db:migrate

Update the User model.

# app/models/user.rb
class User < ApplicationRecord
  ...
  has_secure_token :remember_token
  ...
end

What's Going On Here?

We call has_secure_token on the remember_token. This ensures that the value for this column will be set when the record is created. This value will be used later to securely identify the user.

Step 15: Update Authentication Concern

Add new helper methods.

# app/controllers/concerns/authentication.rb
module Authentication
  extend ActiveSupport::Concern
  ...
  def forget(user)
    cookies.delete :remember_token
    user.regenerate_remember_token
  end
  ...
  def remember(user)
    user.regenerate_remember_token
    cookies.permanent.encrypted[:remember_token] = user.remember_token
  end
  ...
  private

  def current_user
    Current.user ||= if session[:current_user_id].present?
      User.find_by(id: session[:current_user_id])
    elsif cookies.permanent.encrypted[:remember_token].present?
      User.find_by(remember_token: cookies.permanent.encrypted[:remember_token])
    end
  end
  ...
end

What's Going On Here?

The remember method first regenerates a new remember_token to ensure these values are being rotated and can't be used more than once. We get the regenerate_remember_token method from has_secure_token. Next, we assign this value to a cookie. The call to permanent ensures the cookie won't expire until 20 years from now. The call to encrypted ensures the value will be encrypted. This is vital since this value is used to identify the user and is being set in the browser.

The forget method deletes the cookie and regenerates a new remember_token to ensure these values are being rotated and can't be used more than once.

We update the current_user method by adding a conditional to first try and find the user by the session, and then fallback to finding the user by the cookie. This is the logic that allows a user to completely exit their browser and remain logged in when they return to the website since the cookie will still be set.

Step 16: Update Sessions Controller

Update the create and destroy methods.

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  ...
  before_action :authenticate_user!, only: [:destroy]

  def create
    ...
    if @user
      if @user.unconfirmed?
        ...
      elsif @user.authenticate(params[:user][:password])
        login @user
        remember(@user) if params[:user][:remember_me] == "1"
        ...
      else
        ...
      end
    else
      ...
    end
  end

  def destroy
    forget(current_user)
    ...
  end
  ...
end

What's Going On Here?

We conditionally call remember(@user) in the create method if the user has checked the "Remember me" checkbox. We still need to add this to our form.

We call forget(current_user) in the destroy method to ensure we delete the remember_me cookie and regenerate the user's remember_token token.

We also add a before_action to ensure only authenticated users can access the destroy action.

Add the "Remember me" checkbox to the login form.

<!-- app/views/sessions/new.html.erb -->
<%= form_with url: login_path, scope: :user do |form| %>
  ...
  <div>
    <%= form.label :remember_me %>
    <%= form.check_box :remember_me %>
  </div>
  <%= form.submit "Sign In" %>
<% end %>

Step 17: Add Friendly Redirects

Update Authentication Concern.

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  def authenticate_user!
    store_location
    ...
  end
  ...
  private
  ...
  def store_location
    session[:user_return_to] = request.original_url if request.get? && request.local?
  end

end

What's Going On Here?

The store_location method stores the request.original_url in the session so it can be retrieved later. We only do this if the request made was a get request. We also call request.local? to ensure it was a local request. This prevents redirecting to an external application.

We call store_location in the authenticate_user! method so that we can save the path to the page the user was trying to visit before they were redirected to the login page. We need to do this before visiting the login page otherwise the call to request.original_url will always return the url to the login page.

Update Sessions Controller.

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  ...
  def create
    ...
    if @user
      if @user.unconfirmed?
        ...
      elsif @user.authenticate(params[:user][:password])
        after_login_path = session[:user_return_to] || root_path
        login @user
        remember(@user) if params[:user][:remember_me] == "1"
        redirect_to after_login_path, notice: "Signed in."
      else
        ...
      end
    else
      ...
    end
  end
  ...
end

What's Going On Here?

The after_login_path variable it set to be whatever is in the session[:user_return_to]. If there's nothing in session[:user_return_to] then it defaults to the root_path.

Note that we call this method before calling login. This is because login calls reset_session which would deleted the session[:user_return_to].

Step 17: Account for Timing Attacks

Update the User model.

Note that this class method will be available in Rails 7.1

# app/models/user.rb
class User < ApplicationRecord
  ...
  def self.authenticate_by(attributes)
    passwords, identifiers = attributes.to_h.partition do |name, value|
      !has_attribute?(name) && has_attribute?("#{name}_digest")
    end.map(&:to_h)

    raise ArgumentError, "One or more password arguments are required" if passwords.empty?
    raise ArgumentError, "One or more finder arguments are required" if identifiers.empty?
    if (record = find_by(identifiers))
      record if passwords.count { |name, value| record.public_send(:"authenticate_#{name}", value) } == passwords.size
    else
      new(passwords)
      nil
    end
  end  
  ...
end

What's Going On Here?

This class method serves to find a user using the non-password attributes (such as email), and then authenticates that record using the password attributes. Regardless of whether a user is found or authentication succeeds, authenticate_by will take the same amount of time. This prevents timing-based enumeration attacks, wherein an attacker can determine if a password record exists even without knowing the password.

Update the Sessions Controller.

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  ...
  def create
    @user = User.authenticate_by(email: params[:user][:email].downcase, password: params[:user][:password])
    if @user
      if @user.unconfirmed?
        redirect_to new_confirmation_path, alert: "Incorrect email or password."
      else
        after_login_path = session[:user_return_to] || root_path
        login @user
        remember(@user) if params[:user][:remember_me] == "1"
        redirect_to after_login_path, notice: "Signed in."
      end
    else
      flash.now[:alert] = "Incorrect email or password."
      render :new, status: :unprocessable_entity
    end
  end
  ...
end

What's Going On Here?

We refactor the create method to always start by finding and authenticating the user. Not only does this prevent timing attacks, but it also prevents accidentally leaking email addresses. This is because we were originally checking if a user was confirmed before authenticating them. That means a bad actor could try and sign in with an email address to see if it exists on the system without needing to know the password.

Step 18: Store Session in the Database

We're currently setting the user's ID in the session. Even though that value is encrypted, the encrypted value doesn't change since it's based on the user id which doesn't change. This means that if a bad actor were to get a copy of the session they would have access to a victim's account in perpetuity. One solution is to rotate encrypted and signed cookie configurations. Another option is to configure the Rails session store to use mem_cache_store to store session data.

The solution we will implement is to set a rotating value to identify the user and store that value in the database.

Generate ActiveSession model.

rails g model active_session user:references

Update the migration.

class CreateActiveSessions < ActiveRecord::Migration[6.1]
  def change
    create_table :active_sessions do |t|
      t.references :user, null: false, foreign_key: {on_delete: :cascade}

      t.timestamps
    end
  end
end

What's Going On Here?

We update the foreign_key option from true to {on_delete: :cascade}. The on_delete option will delete any active_session record if its associated user is deleted from the database.

Run migration.

rails db:migrate

Update User model.

# app/models/user.rb
class User < ApplicationRecord
  ...
  has_many :active_sessions, dependent: :destroy
  ...
end

Update Authentication Concern

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  def login(user)
    reset_session
    active_session = user.active_sessions.create!
    session[:current_active_session_id] = active_session.id
  end
  ...
  def logout
    active_session = ActiveSession.find_by(id: session[:current_active_session_id])
    reset_session
    active_session.destroy! if active_session.present?
  end
  ...
  private

  def current_user
    Current.user = if session[:current_active_session_id].present?
      ActiveSession.find_by(id: session[:current_active_session_id]).user
    elsif cookies.permanent.encrypted[:remember_token].present?
      User.find_by(remember_token: cookies.permanent.encrypted[:remember_token])
    end
  end
  ...
end

What's Going On Here?

We update the login method by creating a new active_session record and then storing it's ID in the session. Note that we replaced session[:current_user_id] with session[:current_active_session_id].

We update the logout method by first finding the active_session record from the session. After we call reset_session we then delete the active_session record if it exists. We need to check if it exists because in a future section we will allow a user to log out all current active sessions.

We update the current_user method by finding the active_session record from the session, and then returning its associated user. Note that we've replaced all instances of session[:current_user_id] with session[:current_active_session_id].

Force SSL.

# config/environments/production.rb
Rails.application.configure do
  ...
  config.force_ssl = true
end

What's Going On Here?

We force SSL in production to prevent session hijacking. Even though the session is encrypted we want to prevent the cookie from being exposed through an insecure network. If it were exposed, a bad actor could sign in as the victim.

Step 19: Capture Request Details for Each New Session

Add new columns to the active_sessions table.

rails g migration add_request_columns_to_active_sessions user_agent:string ip_address:string
rails db:migrate

Update login method to capture request details.

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  def login(user)
    reset_session
    active_session = user.active_sessions.create!(user_agent: request.user_agent, ip_address: request.ip)
    session[:current_active_session_id] = active_session.id
  end
  ...
end

What's Going On Here?

We add columns to the active_sessions table to store data about when and where these sessions are being created. We are able to do this by tapping into the request object and returning the ip and user agent. The user agent is simply the browser and device.

Update Users Controller.

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  ...
  def edit
    @user = current_user
    @active_sessions = @user.active_sessions.order(created_at: :desc)
  end
  ...
  def update
    @user = current_user
    @active_sessions = @user.active_sessions.order(created_at: :desc)
    ...
  end
end

Create active session partial.

<!-- app/views/active_sessions/_active_session.html.erb -->
<tr>
  <td><%= active_session.user_agent %></td>
  <td><%= active_session.ip_address %></td>
  <td><%= active_session.created_at %></td>
</tr>

Update account page.

<!-- app/views/users/edit.html.erb -->
...
<h2>Current Logins</h2>
<% if @active_sessions.any? %>
  <table>
    <thead>
      <tr>
        <th>User Agent</th>
        <th>IP Address</th>
        <th>Signed In At</th>
      </tr>
    </thead>
    <tbody>
      <%= render @active_sessions %>
    </tbody>
  </table>
<% end %>

What's Going On Here?

We're simply showing any active_session associated with the current_user. By rendering the user_agent, ip_address, and created_at values we're giving the current_user all the information they need to know if there's any suspicious activity happening with their account. For example, if there's an active_session with a unfamiliar IP address or browser, this could indicate that the user's account has been compromised.

Note that we also instantiate @active_sessions in the update method. This is because the update method renders the edit method during failure cases.

Step 20: Allow User to Sign Out Specific Active Sessions

Generate the Active Sessions Controller and update routes.

rails g controller active_sessions

# app/controllers/active_sessions_controller.rb
class ActiveSessionsController < ApplicationController
  before_action :authenticate_user!

  def destroy
    @active_session = current_user.active_sessions.find(params[:id])

    @active_session.destroy

    if current_user
      redirect_to account_path, notice: "Session deleted."
    else
      reset_session
      redirect_to root_path, notice: "Signed out."
    end
  end

  def destroy_all
    current_user.active_sessions.destroy_all
    reset_session

    redirect_to root_path, notice: "Signed out."
  end
end

# config/routes.rb
Rails.application.routes.draw do
  ...
  resources :active_sessions, only: [:destroy] do
    collection do
      delete "destroy_all"
    end
  end
end

What's Going On Here?

We ensure only users who are logged in can access these endpoints by calling before_action :authenticate_user!.

The destroy method simply looks for an active_session associated with the current_user. This ensures that a user can only delete sessions associated with their account.

Once we destroy the active_session we then redirect back to the account page or to the homepage. This is because a user may not be deleting a session for the device or browser they're currently logged into. Note that we only call reset_session if the user has deleted a session for the device or browser they're currently logged into, as this is the same as logging out.

The destroy_all method is a collection route that will destroy all active_session records associated with the current_user. Note that we call reset_session because we will be logging out the current_user during this request.

Update views by adding buttons to destroy sessions.

<!-- app/views/users/edit.html.erb -->
...
<h2>Current Logins</h2>
<% if @active_sessions.any? %> 
  <%= button_to "Log out of all other sessions", destroy_all_active_sessions_path, method: :delete %>
  <table>
    <thead>
      <tr>
        <th>User Agent</th>
        <th>IP Address</th>
        <th>Signed In At</th>
        <th>Sign Out</th>
      </tr>
    </thead>
    <tbody>
      <%= render @active_sessions %>
    </tbody>
  </table>
<% end %>

<!-- app/views/active_sessions/_active_session.html.erb -->
<tr>
  <td><%= active_session.user_agent %></td>
  <td><%= active_session.ip_address %></td>
  <td><%= active_session.created_at %></td>
  <td><%= button_to "Sign Out", active_session_path(active_session), method: :delete %></td>
</tr>

Update Authentication Concern.

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  private

  def current_user
    Current.user = if session[:current_active_session_id].present?
      ActiveSession.find_by(id: session[:current_active_session_id])&.user
    elsif cookies.permanent.encrypted[:remember_token].present?
      User.find_by(remember_token: cookies.permanent.encrypted[:remember_token])
    end
  end
  ...
end

What's Going On Here?

This is a very subtle change, but we've added a safe navigation operator via the &.user call. This is because ActiveSession.find_by(id: session[:current_active_session_id]) can now return nil since we're able to delete other active_session records.

Step 21: Refactor Remember Logic

Since we're now associating our sessions with an active_session and not a user, we'll want to remove the remember_token token from the users table and onto the active_sessions.

Move remember_token column from users to active_sessions table.

rails g migration move_remember_token_from_users_to_active_sessions

# db/migrate/[timestamp]_move_remember_token_from_users_to_active_sessions.rb
class MoveRememberTokenFromUsersToActiveSessions < ActiveRecord::Migration[6.1]
  def change
    remove_column :users, :remember_token
    add_column :active_sessions, :remember_token, :string, null: false

    add_index :active_sessions, :remember_token, unique: true
  end
end

Run migration.

rails db:migrate

What's Going On Here?

We add null: false to ensure this column always has a value.

We add a unique index to ensure this column has unique data.

Update User Model.

 class User < ApplicationRecord
    ...
-   has_secure_token :remember_token
    ...
 end

Update Active Session Model.

# app/models/active_session.rb
class ActiveSession < ApplicationRecord
  ...
  has_secure_token :remember_token
end

What's Going On Here?

We call has_secure_token on the remember_token. This ensures that the value for this column will be set when the record is created. This value will be used later to securely identify the user.

Note that we remove this from the user model.

Refactor the Authentication Concern.

# app/controllers/concerns/authentication.rb
module Authentication
  ...
  def login(user)
    reset_session
    active_session = user.active_sessions.create!(user_agent: request.user_agent, ip_address: request.ip)
    session[:current_active_session_id] = active_session.id

    active_session
  end

  def forget_active_session
    cookies.delete :remember_token
  end
  ...
  def remember(active_session)
    cookies.permanent.encrypted[:remember_token] = active_session.remember_token
  end
  ...
  private

  def current_user
    Current.user = if session[:current_active_session_id].present?
      ActiveSession.find_by(id: session[:current_active_session_id])&.user
    elsif cookies.permanent.encrypted[:remember_token].present?
      ActiveSession.find_by(remember_token: cookies.permanent.encrypted[:remember_token])&.user
    end
  end
  ...
end

What's Going On Here?

The login method now returns the active_session. This will be used later when calling SessionsController#create.

The forget method has been renamed to forget_active_session and no longer takes any arguments. This method simply deletes the cookie. We don't need to call active_session.regenerate_remember_token since the active_session will be deleted, and therefor cannot be referenced again.

The remember method now accepts an active_session and not a user. We do not need to call active_session.regenerate_remember_token since a new active_session record will be created each time a user logs in. Note that we now save active_session.remember_token to the cookie.

The current_user method now finds the active_session record if the remember_token is present and returns the user via the safe navigation operator.

Refactor the Sessions Controller.

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  def create
    ...
    if @user
      if @user.unconfirmed?
        ...
      else
        ...
        active_session = login @user
        remember(active_session) if params[:user][:remember_me] == "1"
      end
    else
    ...
    end
  end

   def destroy
    forget_active_session
    ...
  end
end

What's Going On Here?

Since the login method now returns an active_session, we can take that value and pass it to remember.

We replace forget(current_user) with forget_active_session to reflect changes to the method name and structure.

Refactor Active Sessions Controller

# app/controllers/active_sessions_controller.rb
class ActiveSessionsController < ApplicationController
  ...
  def destroy
    ...
    if current_user
    ...
    else
      forget_active_session
      ...
    end
  end

  def destroy_all
    forget_active_session
    current_user.active_sessions.destroy_all
    ...
  end
end

Rails Remote Elements Tutorial

Steve Polito — Tue, 09 Nov 2021 15:26:21 +0000

Do you need to create real-time features in your Rails app, but either can't use Turbo or don't want to use a front end framework like React? Fortunately older versions of Rails actually provide this functionality of the box. In this tutorial I'll show you how to create a single page app in Rails from scratch using remote elements and Stimulus.

Formula

Stimulus Controller

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

export default class extends Controller {
  static targets = ["error", "form"];
  static values = {
    target: String,
    action: { type: String, default: "replace" },
  };

  connect() {
    this.target =
      this.hasTargetValue && document.querySelector(this.targetValue);
    this.action = this.hasActionValue && this.actionValue;
    this.actions = [
      "afterbegin",
      "afterend",
      "beforebegin",
      "beforeend",
      "remove",
      "replace",
      "update",
    ];
    this.element.addEventListener("ajax:error", (event) =>
      this.handleError(event)
    );
    this.element.addEventListener("ajax:success", (event) =>
      this.handleSuccess(event)
    );
  }

  actionIsPermitted(action) {
    if (this.actions.indexOf(action) == -1) {
      throw `data-request-action-value="${action}" is not one of ${this.actions.join(
        ", "
      )}`;
    } else {
      return true;
    }
  }

  clearForm() {
    this.hasFormTarget && this.formTarget.reset();
  }

  clearErrors() {
    this.hasErrorTarget && (this.errorTarget.innerHTML = "");
  }

  handleError(event) {
    const { response } = event.detail[2];

    this.errorTarget.innerHTML = response;
  }

  handleSuccess(event) {
    const { response } = event.detail[2];

    this.clearErrors();
    this.clearForm();
    this.actionIsPermitted(this.action) &&
      this.updateTarget(this.action, response);
  }

  updateTarget(action, response) {
    switch (action) {
      case "remove":
        this.target.remove();
        break;
      case "replace":
        const parser = new DOMParser();
        const doc = parser.parseFromString(response, "text/html");
        this.target.replaceWith(doc.body.firstChild);
        break;
      case "update":
        this.target.innerHTML = response;
        break;
      default:
        this.target.insertAdjacentHTML(this.action, response);
    }
  }
}

What's Going On Here?

Rails-ujs dispatches custom events on the element creating the request. In our case we specifically listen for ajax:error and ajax:success. Those responses are returned via event.detail[2].

If the request was successful we simply update the DOM with the response according to the value of this.actionValue. We limit what actions can be used with this.actionIsPermitted(). These values are inspired by Turbo's seven actions and are handled via this.updateTarget().

Since a request can come from a button, link, or form we need to conditionally handle rendering errors and clearing form data via this.clearErrors() and this.clearForm().

Remote Element Markup

Forms

<%= form_with(
  local: false,
  data: { 
    controller: "request",
    request_target: "form",
    request_target_value: "#some_dom_id",
    request_action_value: "afterbegin | afterend | beforebegin | beforeend | remove | replace | update"
  }) do |form| %>
  <div data-request-target="error"></div>
  ...
<% end %>

What's Going On Here?

We need to add local: false to ensure the form will make an AJAX request.

The request_target: "form" data attribute ensures the form will be cleared via this.clearForm().

The request_target_value data attribute references an element on the page that will be updated when the response from the server is successful.

The request_action_value data attribute determines how the request_target_value element will be updated when the response from the server is successful.

We add <div data-request-target="error"></div> so we can render any errors in the form if the object is not valid.

Buttons

<%= button_to(
  remote: true,
  form: { 
    data: { 
      controller: "request",
      request_target_value: "#some_dom_id",
      request_action_value: "afterbegin | afterend | beforebegin | beforeend | remove | replace | update"
    } 
  }
) do %>
  ...
<% end %>

What's Going On Here?

We need to add remote: true to ensure the form will make an AJAX request.

The request_target_value data attribute references an element on the page that will be updated when the response from the server is successful. Note that this is wrapped in form: { data: {} } since we need this value to be set on the form and not the button.

The request_action_value data attribute determines how the request_target_value element will be updated when the response from the server is successful. Note that this is wrapped in form: { data: {} } since we need this value to be set on the form and not the button.

Links

<%= link_to(
  task.title,
  task_path(task),
  remote: true,
  data: { 
    controller: "request",
    request_target_value: "#some_dom_id",
    request_action_value: "afterbegin | afterend | beforebegin | beforeend | remove | replace | update"
  }
) %>

What's Going On Here?

We need to add remote: true to ensure the request will make an AJAX request.

The request_target_value data attribute references an element on the page that will be updated when the response from the server is successful.

The request_action_value data attribute determines how the request_target_value element will be updated when the response from the server is successful.

Controller Responses

When Responding With a Partial

class TasksController < ApplicationController
  def create
    @task = Task.new(task_params)
    if @task.save
      render @task
    else
      render partial: "layouts/form_errors", locals: {object: @task}, status: :unprocessable_entity
    end
  end
end

What's Going On Here?

This action only returns partials instead of a full layout. If the @task is saved the server will respond with app/views/tasks/_task.html.erb. Otherwise it will respond with layouts/_form_errors.html.erb. In either case just the markup from the partial is returned instead of the full document.

When Responding With a Layout

class TasksController < ApplicationController
  def show
    render layout: !request.xhr?
  end
end

What's Going On Here?

This action will return the full page layout (in this case app/views/tasks/show.html.erb) unless the request was an xhr request. If the request was made with xhr then only the content of app/views/tasks/show.html.erb will be returned instead of the full document. We could have set layout: false but there could be a case where we actually visit the route (https://www.example.com/tasks/1). If we set layout: false then the response would be missing the actually page layout.

Example

Below is a real world example of how you can use remote elements to create a single page application in Rails.

Notes

Since it's a single page app, all requests are coming from the root path (tasks#index).
The back button won't work as expected. For example, if you click on a task and then click the back button, you won't be brought back to the tasks#index since you're technically already there. Instead you'll be brought back to whatever page you were on last. This is why there are client side routing libraries such as React Router.
In order to DRY up our code, we set the data attributes for some of the form partials in our controllers since we sometimes respond with a form partial. A good example of this is tasks#edit and app/views/tasks/_form.html.erb.

Routes

# config/routes.rb
Rails.application.routes.draw do
  root to: "tasks#index"
  resources :tasks, except: [:new] do
    resources :items do
      collection do
        put "mark_all_as_complete"
        put "mark_all_as_incomplete"
      end
    end
  end
end

Layout

<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
  <head>
    <title>Rails Remote Elements Tutorial</title>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">
  </head>

  <body>
    <main class="container-sm my-5">
      <div class="row justify-content-center">
        <div class="col col-5" id="content">
          <%= yield %>
        </div>
      </div>
    </main>
  </body>
</html>

<!--  app/views/layouts/_form_errors.html.erb -->
<div class="alert alert-danger" role="alert">
  <ul class="mb-0">
    <% object.errors.full_messages.each do |error| %>
      <li><%= error %></li>
    <% end %>
  </ul>
</div>

Task Controller and Views

# app/controllers/tasks_controller.rb
class TasksController < ApplicationController
  before_action :set_task, except: [:create, :index]
  before_action :set_new_item_data_attributes, only: [:show]
  before_action :set_edit_task_data_attributes, only: [:edit]
  before_action :set_new_task_data_attributes, only: [:index]

  def create
    @task = Task.new(task_params)
    if @task.save
      render @task
    else
      render partial: "layouts/form_errors", locals: {object: @task}, status: :unprocessable_entity
    end
  end

  def destroy
    @task.destroy
  end

  def edit
    render partial: "form", locals: {data_attributes: @edit_task_data_attributes}
  end

  def index
    @tasks = Task.all.order(created_at: :desc)
    @task = Task.new
    render layout: !request.xhr?
  end

  def show
    @items = @task.items.order(created_at: :desc)
    render layout: !request.xhr?
  end

  def update
    if @task.update(task_params)
      render @task
    else
      render partial: "layouts/form_errors", locals: {object: @task}, status: :unprocessable_entity
    end
  end

  private

  def set_new_item_data_attributes
    @new_item_data_attributes = {
      controller: "request",
      request_target: "form",
      request_target_value: "#items",
      request_action_value: "afterbegin"
    }
  end

  def set_new_task_data_attributes
    @new_task_data_attributes = {
      controller: "request",
      request_target: "form",
      request_target_value: "#tasks",
      request_action_value: "afterbegin"
    }
  end

  def set_edit_task_data_attributes
    @edit_task_data_attributes = {
      controller: "request",
      request_target: "form",
      request_target_value: "#task_#{@task.id}",
      request_action_value: "replace"
    }
  end

  def set_task
    @task = Task.find(params[:id])
  end

  def task_params
    params.require(:task).permit(:title)
  end
end

<!-- app/views/tasks/_form.html.erb -->
<%= form_with model: @task, local: false, data: data_attributes, class: "row align-items-center" do |form| %>
  <div data-request-target="error">
    <%= render partial: "layouts/form_errors", locals: { object: form.object } if form.object.errors.any? %>
  </div>
  <div class="col-9">
    <%= form.text_field :title, class: "form-control" %>
  </div>
  <div class="col-3">
    <%= form.submit class: "btn btn-primary" %>
  </div>
<% end %>

<!-- app/views/tasks/_task.html.erb -->
<li class="list-group-item list-group-item d-flex justify-content-between align-items-center" id="<%= dom_id(task) %>">
  <%= link_to task.title, task_path(task), class: "fs-5 link-dark", remote: true, data: { controller: "request", request_target_value: "#content", request_action_value: "update" } %>
  <div>
    <%= link_to "Edit", edit_task_path(task), class: "link-secondary", remote: true, data: { controller: "request", request_target_value: "##{dom_id(task)}", request_action_value: "update" } %>
    <%= link_to "Delete", task_path(task), class: "link-secondary", method: :delete, remote: true, data: { controller: "request", request_target_value: "##{dom_id(task)}", request_action_value: "remove" } %>  
  </div>
</li>

<!-- app/views/tasks/index.html.erb -->
<%= render partial: "form", locals: { data_attributes: @new_task_data_attributes } %>
<ul id="tasks" class="mt-4 list-group list-group-flush">
  <%= render @tasks %>
</ul>

<!-- app/views/tasks/show.html.erb -->
<%= link_to "Back to Tasks", tasks_path, remote: true, data: { controller: "request", request_target_value: "#content", request_action_value: "update" } %>
<h1><%= @task.title %></h1>
<div class="mb-4">
  <%= render partial: "items/form", locals: { object: [@task, @task.items.build], data_attributes: @new_item_data_attributes } %>
</div>
<div class="row gx-2">
  <%= button_to "Mark All As Complete", mark_all_as_complete_task_items_path(@task), method: :put, remote: true, form_class: "col-4", class: "btn btn-sm btn-outline-secondary", form: { data: { controller: "request", request_target_value: "#items-container", request_action_value: "update"  } }  %>
  <%= button_to "Mark All As Incomplete", mark_all_as_incomplete_task_items_path(@task), method: :put, remote: true, form_class: "col-4", class: "btn btn-sm btn-outline-secondary", form: { data: { controller: "request", request_target_value: "#items-container", request_action_value: "update"  } }  %>
</div>
<div id="items-container">
  <%= render partial: "items/items" %>
</div>

Item Controller and Views

# app/controllers/items_controller.rb
class ItemsController < ApplicationController
  before_action :set_item, only: [:destroy, :edit, :update]
  before_action :set_task
  before_action :set_edit_item_data_attributes, only: [:edit]

  def create
    @item = @task.items.build(item_params)
    if @item.save
      render @item
    else
      render partial: "layouts/form_errors", locals: {object: @item}, status: :unprocessable_entity
    end
  end

  def destroy
    @item.destroy
  end

  def edit
    render partial: "form", locals: {object: [@task, @item], data_attributes: @edit_item_data_attributes}
  end

  def mark_all_as_complete
    @items = @task.items.order(created_at: :desc)
    @items.update_all(complete: true)
    render partial: "items"
  end

  def mark_all_as_incomplete
    @items = @task.items.order(created_at: :desc)
    @items.update_all(complete: false)
    render partial: "items"
  end

  def update
    if @item.update(item_params)
      render @item
    else
      render partial: "layouts/form_errors", locals: {object: @item}, status: :unprocessable_entity
    end
  end

  private

  def item_params
    params.require(:item).permit(:title, :complete)
  end

  def set_edit_item_data_attributes
    @edit_item_data_attributes = {
      controller: "request",
      request_target: "form",
      request_target_value: "#item_#{@item.id}",
      request_action_value: "replace"
    }
  end

  def set_item
    @item = Item.find(params[:id])
  end

  def set_task
    @task = Task.find(params[:task_id])
  end
end

<!-- app/views/items/_form.html.erb -->
<%= form_with model: object, local: false, data: data_attributes, class: "row align-items-center" do |form| %>
  <div data-request-target="error">
    <%= render partial: "layouts/form_errors", locals: { object: form.object } if form.object.errors.any? %>
  </div>
  <div class="col-9">
    <%= form.text_field :title, class: "form-control" %>
  </div>
  <div class="col-3">
    <%= form.submit class: "btn btn-primary"%>
  </div>
<% end %>

<!--  app/views/items/_item.html.erb -->
<% unless item.new_record? %>
  <li class="list-group-item list-group-item d-flex justify-content-between align-items-center" id="<%= dom_id(item) %>">
    <div class="d-flex justify-content-between align-items-center">
      <%= item.title %>
      <%= button_to [item.task, item], class: "btn btn-link", method: :put, remote: true, params: { item: { complete: !item.complete } }, form: { data: { controller: "request", request_target_value: "##{dom_id(item)}", request_action_value: "replace" }  } do %>
        <%= item.complete? ? "Mark as incomplete" : "Mark as complete" %>
      <% end %>
    </div>
    <div>
      <%= link_to "Edit", edit_task_item_path(item.task, item), class: "link-secondary", remote: true, data: { controller: "request", request_target_value: "##{dom_id(item)}", request_action_value: "update" } %> 
      <%= link_to "Delete", task_item_path(item.task, item), class: "link-secondary", method: :delete, remote: true, data: { controller: "request", request_target_value: "##{dom_id(item)}", request_action_value: "remove" } %>  
    </div>
  </li>
<% end %>

<!-- app/views/items/_items.html.erb -->
<ul id="items" class="mt-4 list-group list-group-flush">
  <%= render @items %>
</ul>

Did you like this post? Follow me on Twitter to get even more tips.

Lazy Load Content in Rails from Scratch

Steve Polito — Sun, 17 Oct 2021 12:19:24 +0000

Lazy Load Content in Rails from Scratch

Are certain pages on your Rails app loading slowly? You might want to consider loading those requests in the background. It's easier than you think. In this tutorial I'll show you how to lazy load content in Rails without Hotwire.

References

Formula

Create an endpoint that does not return a layout.

class LazyLoad::PostsController < ApplicationController
  def index
    @posts = Post.all
    render partial: "lazy_load/posts/post", collection: @posts, layout: false
  end
end

Add a placeholder element onto the page that will represent where the content will be loaded.

<div data-controller="lazy-load" data-lazy-load-url-value="<%= lazy_load_posts_path %>">
  <div data-lazy-load-target="output" class="d-grid gap-3">
    <%= render partial: "shared/placeholder" %>
  </div>
</div>

Make a Fetch request to the endpoint and replace the placeholder with the response from the endpoint.

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

export default class extends Controller {
  static targets = ["output"];
  static values = { url: String };

  connect() {
    this.request = new Request(this.urlValue)
    this.fetchContent(this.request);
  }

  fetchContent(request) {
    fetch(request)
      .then((response) => {
        if (response.status === 200) {
          response.text().then((text) => (this.renderContent(text)));
        } else {
          this.renderContent("Could not load data");
        }
      })
      .catch((error) => {
        this.renderContent("Could not load data");
      });
  }

  renderContent(content) {
    this.outputTarget.innerHTML = content
    this.dispatchEvent("lazy_load:complete")
  }

  dispatchEvent(eventName) {
    const event = new Event(eventName);
    document.dispatchEvent(event);
  }

}

Example

Step 1: Create Endpoints

Generate namespaced controllers.

rails g controller lazy_load/posts
rails g controller lazy_load/users

Add namespaced routes with default values.

# config/routes.rb
Rails.application.routes.draw do
  ...
  namespace :lazy_load do
    defaults layout: false do
      resources :posts, only: [:index]
      resources :users, only: [:index]
    end
  end
end

Build controller actions.

# app/controllers/lazy_load/posts_controller.rb
class LazyLoad::PostsController < ApplicationController
  def index
    @posts = Post.all
    render partial: "lazy_load/posts/post", collection: @posts
  end
end

# app/controllers/lazy_load/posts_controller.rb
class LazyLoad::UsersController < ApplicationController
  def index
    @users = User.all
    render partial: "lazy_load/users/user", collection: @users
  end
end

Build views.

Card

# app/views/shared/_card.html.erb
<div class="card">
  <div class="card-body">
    <h5 class="card-title"><%= title %></h5>
    <p class="card-text"><%= body %></p>
    <p class="card-text"><small class="text-muted"><%= timestamp %></small></p>
  </div>
</div>

Placeholder Card Variant

# app/views/shared/_card.html+empty.erb
<div class="card mb-3">
  <div class="card-body">
    <p aria-hidden="true" class="d-grid gap-3 placeholder-glow">
      <span class="placeholder col-12 placeholder-lg"></span>
      <span class="placeholder col-6"></span>
      <span class="placeholder col-6 placeholder-xs"></span>
    </p>
  </div>
</div>

List Group

# app/views/shared/_list_group.html.erb
<li class="list-group-item d-flex justify-content-between align-items-start">
  <div class="ms-2 me-auto">
    <div class="fw-bold"><%= name %></div>
    <%= email %>
  </div>
  <a href="#" data-bs-toggle="tooltip" data-bs-placement="top" title="<%= tooltip %>">
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle" viewBox="0 0 16 16">
      <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
      <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
    </svg>
  </a>  
</li>

Post

# app/views/lazy_load/posts/_post.html.erb
<%= render partial: "shared/card", locals: { title: post.title, body: post.body, timestamp: time_ago_in_words(post.updated_at) } %>

User

# app/views/lazy_load/users/_user.html.erb
<%= render partial: "shared/list_group", locals: { name: user.name, email: user.email, tooltip: pluralize(user.posts.size, 'Post')  } %>

What's Going On Here?

We create a namespaced route and controller. This isn't required, but it helps keep our endpoints organized. We're also not limited to just index actions either.

We set a default for those endpoints to not render a layout. This means that just the raw HTML for the partials will be returned.

We choose to create custom views for each endpoint, but we could use the existing views or partials if we wanted to. This is just personal preference.

If you navigate to http://localhost:3000/lazy_load/users you should see that the content has loaded without a layout.

If you open the network tab you will see that the server responded with raw HTML without a layout.

Step 2: Build a Stimulus Controller

Create a Stimulus Controller to fetch data from the endpoints.

// app/javascript/controllers/lazy_load_controller.js
import { Controller } from "@hotwired/stimulus";

export default class extends Controller {
  static targets = ["output"];
  static values = { url: String };

  connect() {
    this.request = new Request(this.urlValue)
    this.fetchContent(this.request);
  }

  fetchContent(request) {
    fetch(request)
      .then((response) => {
        if (response.status === 200) {
          response.text().then((text) => (this.renderContent(text)));
        } else {
          this.renderContent("Could not load data");
        }
      })
      .catch((error) => {
        this.renderContent("Could not load data");
      });
  }

  renderContent(content) {
    this.outputTarget.innerHTML = content
    this.dispatchEvent("lazy_load:complete")
  }

  dispatchEvent(eventName) {
    const event = new Event(eventName);
    document.dispatchEvent(event);
  }

}

Use the following markup to connect to the Stimulus Controller.

<div data-controller="lazy-load" data-lazy-load-url-value="<%= lazy_load_users_path %>">
  <div data-lazy-load-target="output" class="d-grid gap-3">
    <% 5.times do |i| %>
      <%= render partial: "shared/card", variants: [:empty] %>
    <% end %>
  </div>
</div>

What's Going On Here?

We could just use vanilla JavaScript instead of Stimulus, but Stimulus pairs nicely with Rails and will make it easy to get up and running with this feature quickly.

When the Stimulus Controller first connects, it will make a fetch request to whatever value is stored in the data-lazy-load-url-value attribute. This keeps our Stimulus Controller flexible and reusable.

If the request was successful we replace the placeholder with the response. Note that we call response.text() in order to return the response into a String.

If the request was not successful, we simply replace the placeholder with an error message.

In all cases we dispatch a custom event on the document. We could call this event anything we want, but it's helpful to namespace it to avoid naming collisions with other libraries or specs. This is what Rails UJS does, and is helpful in cases where you need to re-initialize JavaScript for elements that were just added to the DOM. In our case this is helpful for re-initializing tooltips.

// app/javascript/controllers/application.js
document.addEventListener("lazy_load:complete", function() {
  initilizeToolTips();
});

function initilizeToolTips() {
  var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
  var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
    return new bootstrap.Tooltip(tooltipTriggerEl)
  });
}

Step 2: Putting it all Together

Create a new Controller.

rails g controller Homescreens show

Update the routes.

# config/routes.rb
Rails.application.routes.draw do
  root to: "homescreens#show"
  resource :homescreen, only: :show
  ...
end

Add markup to lazy load content users and posts.

# app/views/homescreens/show.html.erb
<div data-controller="lazy-load" data-lazy-load-url-value="<%= lazy_load_posts_path %>">
  <div data-lazy-load-target="output" class="d-grid gap-3">
    <% 5.times do |i| %>
      <%= render partial: "shared/card", variants: [:empty] %>
    <% end %>
  </div>
</div>

<% content_for :left_column do %>
  <div data-controller="lazy-load" data-lazy-load-url-value="<%= lazy_load_users_path %>">
    <ul data-lazy-load-target="output" class="list-group list-group-flush list-unstyled">
      <% 5.times do |i| %>
        <li><%= render partial: "shared/card", variants: [:empty] %></li>
      <% end %>
    </ul>
  </div>
<% end %>

Did you like this post? Follow me on Twitter to get even more tips.

I built a gem that makes it easy to automatically unsubscribe from emails in Rails.

Steve Polito — Tue, 28 Sep 2021 00:31:18 +0000

Source Code

https://github.com/stevepolitodesign/unsubscribe

Demo

Docs

📭 Unsubscribe

Automatically unsubscribe from emails in Rails.

🚀 Installation

Add this line to your application's Gemfile:

gem 'unsubscribe'

And then execute:

$ bundle

Or install it yourself as:

$ gem install unsubscribe

Then run the installation commands:

rails g unsubscribe:install
rails unsubscribe:install:migrations
rails db:migrate

📚 Usage

Unsubscribe::Owner

Add include Unsubscribe::Owner to a Model. The Model must have an email column.

class User < ApplicationRecord
  include Unsubscribe::Owner
end

Available Methods

User.first.mailer_subscriptions
# => #<ActiveRecord::Associations::CollectionProxy [#<Unsubscribe::MailerSubscription>, #<Unsubscribe::MailerSubscription>] >

User.first.subscribed_to_mailer? "MarketingMailer"
# => true/false

User.first.to_sgid_for_mailer_subscription
# => #<SignedGlobalID:123 ...>

Unsubscribe::Mailer

Add include Unsubscribe::Mailer to a Mailer.
Optionally call unsubscribe_settings to set a name and description. This will be used in the unsubscribe page.
Set mail to: to @recipient.email. The @recipient is an instance of whatever Class include Unsubscribe::Owner was added to.

class MarketingMailer < ApplicationMailer  
  include Unsubscribe::Mailer

  unsubscribe_settings name: "Marketing Emails", description: "Updates on promotions and sales."

  def promotion
    mail to: @recipient.email
  end  
end

Call the Mailer with a recipient parameter.

  MarketingMailer.with(
    recipient: User.first
  ).promotion.deliver_now

Available Methods

Unsubscribe::MailerSubscription.first.action
# => "Unsubscribe from"/"Subscribe to"

Unsubscribe::MailerSubscription.first.call_to_action
# => "Unsubscribe from Marketing Emails"/"Subscribe to Marketing Emails"

Unsubscribe::MailerSubscription.first.description
# => "Updates on promotions and sales."

Unsubscribe::MailerSubscription.first.name
# => "Marketing Emails"

Unsubscribe Link

Add the @unsubscribe_url link to the Mailer.

<%= link_to "Unsubscribe", @unsubscribe_url %>

⚙️ Customize Templates

Run rails g unsubscribe:views if you want to modify the existing templates.

🌐 I18n

The language used for Unsubscribe::MailerSubscription#action can be translated.

# config/locales/en.yml
en:
  unsubscribe:
    action:
      subscribe: "Subscribe to"
      unsubscribe: "Unsubscribe from"

🙏 Contributing

If you'd like to open a PR please make sure the following things pass:

bin/rails test
bundle exec standardrb

📜 License

The gem is available as open source under the terms of the MIT License.

Automatically Unsubscribe from Emails in Rails (and Control Email Preferences)

Steve Polito — Tue, 07 Sep 2021 10:07:12 +0000

In this tutorial, I'll show you how to add a link to any Rails Mailer that will allow a user to automatically unsubscribe from that email. As an added bonus, we'll build a page allowing a user to update their email preferences across all mailers.

Inspired by GoRails.

Step 1: Build Mailers

Generate mailers.

rails g mailer marketing promotion
rails g mailer notification notify

Update previews by passing a user into the mailer. This assumes your database has at least one user record.

# test/mailers/previews/marketing_mailer_preview.rb
class MarketingMailerPreview < ActionMailer::Preview

  def promotion
    MarketingMailer.with(
      user: User.first,
      ...
    ).promotion
  end

end

# test/mailers/previews/notification_mailer_preview.rb
class NotificationMailerPreview < ActionMailer::Preview

  def notify
    NotificationMailer.with(
      user: User.first
      ...
    ).notify
  end

end

Step 2: Build a Model to Save Email Preferences

Generate the model and migration.

rails g model mailer_subscription user:references subscribed:boolean mailer:string

Add a null constraint to the mailer column, and a unique index on the user_id and mailer columns. This will prevent duplicate records.

class CreateMailerSubscriptions < ActiveRecord::Migration[6.1]
  def change
    create_table :mailer_subscriptions do |t|
      t.references :user, null: false, foreign_key: true
      t.boolean :subscribed
      t.string :mailer, null: false

      t.timestamps
    end

    add_index(:mailer_subscriptions, [:user_id, :mailer], unique: true)
  end
end

What's Going On Here?

We add null: false to the mailer column to prevent empty values from being saved, since this column is required.

We add a unique index on the user_id and mailer columns to prevent a user from having multiple preferences for a mailer.

Run the migrations.

rails db:migrate

Build the MailerSubscription model.

# app/models/mailer_subscription.rb
class MailerSubscription < ApplicationRecord
  belongs_to :user

  MAILERS = OpenStruct.new(
    items: [
      {
        class: "MarketingMailer",
        name: "Marketing Emails",
        description: "Updates on promotions and sales."
      },
      {
        class: "NotificationMailer",
        name: "Notification Emails",
        description: "Notifications from the website."
      }
    ]
  ).freeze

  validates :subscribed, inclusion: [true, false], allow_nil: true
  validates :mailer, presence: true
  validates :mailer, inclusion: MAILERS.items.map{ |item|  item[:class] }
  validates :user, uniqueness: { scope: :mailer }

  # @mailer_subscription.details
  # => [{:class => "MarketingMailer", :name => "Marketing Emails", :description => "Updates on promotions and sales."}]
  def details
    MailerSubscription::MAILERS.items.select {|item| item[:class] == mailer }
  end

  # @mailer_subscription.name
  # => "Marketing Emails"
  def name
    details[0][:name]
  end

  # @mailer_subscription.name
  # => "Updates on promotions and sales."
  def description
    details[0][:description]
  end

  # @mailer_subscription.name
  # => "Subscribe to"
  def action
    subscribed? ? "Unsubscribe from" : "Subscribe to"
  end

  # @mailer_subscription.name
  # => "Subscribe to Marketing Emails"
  def call_to_action
    "#{action} #{name}"
  end

end

What's Going On Here

We add a constant to store a list of mailers a user will be able to subscribe/unsubscribe from. The class value must match the name of a Mailer class.

We use the values stored in the constant to constrain what values can be set on the mailer column. This prevents us from accidentally creating a record with an invalid mailer.

We add a uniqueness validator between the user and mailer. This is made possible by the unique index we created in the migration. This will ensure a user cannot have multiple preferences for the same mailer.

We use the values stored in the constant to create a variety of helper methods that can be used in views.

Add method to check if a user is subscribed to a specific mailer.

# app/models/user.rb
class User < ApplicationRecord
  has_many :mailer_subscriptions, dependent: :destroy

  # @user.subscribed_to_mailer? "MarketingMailer"
  # => true
  def subscribed_to_mailer?(mailer)
    MailerSubscription.find_by(
      user: self,
      mailer: mailer,
      subscribed: true
    ).present?
  end
end

What's Going On Here?

We add a method that checks if a user is subscribed to a particular mailer. If the method finds a matching record, then the user is subscribed. Otherwise, they are not. Note that this is an opt-in strategy. We're deliberately looking for records where subscribed is set to true. This means that if there is no record in the database, they'll be considered unsubscribed.

To make this an opt-out strategy, you could simply replace subscribed: true with subscribed: false.

Step 3: Allow a User to Automatically Unsubscribe from a Mailer

Generate a controller to handle automatic unsubscribes.

rails g controller mailer_subscription_unsubcribes

# config/routes.rb
Rails.application.routes.draw do
  ...
  resources :mailer_subscription_unsubcribes, only: [:show, :update]
end

Build the endpoints.

# app/controllers/mailer_subscription_unsubcribes_controller.rb
class MailerSubscriptionUnsubcribesController < ApplicationController
  before_action :set_user, only: [:show, :update]
  before_action :set_mailer_subscription, only: [:show, :update]

  def show
    if @mailer_subscription.update(subscribed: false)
      @message = "You've successfully unsubscribed from this email."
    else
      @message = "There was an error"
    end
  end

  def update
    if @mailer_subscription.toggle!(:subscribed)
      redirect_to root_path, notice: "Subscription updated."
    else
      redirect_to root_path, notice: "There was an error."
    end
  end

  private

    def set_user
      @user = GlobalID::Locator.locate_signed params[:id]
      @message =  "There was an error" if @user.nil?
    end

    def set_mailer_subscription
      @mailer_subscription = MailerSubscription.find_or_initialize_by(
        user: @user,
        mailer: params[:mailer]
      )
    end

end

Build the view.

<%# app/views/mailer_subscription_unsubcribes/show.html.erb %>
<h1>Unsubscribe</h1>
<p><%= @message %></p>

<%= button_to @mailer_subscription.call_to_action, mailer_subscription_unsubcribe_path, method: :patch, params: { mailer: params[:mailer] } if @mailer_subscription.present? %>

You can test this be getting the Global ID of a user and going to the endpoint.

User.first.to_sgid.to_s
# => "abc123..."

http://localhost:3000/mailer_subscription_unsubcribes/abc123...?mailer=MarketingMailer

What's Going On Here?

We create an endpoint that will automatically unsubscribe a user from a particular mailer. This is a little unconventional since we're creating a record on a GET request (instead of a POST request). We're forced to do this because a user will be clicking a link from an email to unsubscribe. If emails supported forms, we could create a POST request.

We add a button on that page that will allow the user to resubscribe to the mailer. Note that we don't redirect back to the show action because that would end up unsubscribing the user from the mailer again.

We find the user through their GlobalID in the URL which makes the URLs difficult to discover. Otherwise the URL would just accept the user's ID which is much easier to guess. This will prevent a bad actor from from unsubscribing a user from a mailer.

Step 4: Build a Page for User to Update Their Email Preferences

Generate a controller for the MailerSubscription model.

rails g controller mailer_subscriptions

# config/routes.rb
Rails.application.routes.draw do
  ...
  resources :mailer_subscription_unsubcribes, only: [:show, :update]
  resources :mailer_subscriptions, only: [:index, :create, :update]
end

Build the endpoints.

# app/controllers/mailer_subscriptions_controller.rb
class MailerSubscriptionsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_mailer_subscription, only: :update
  before_action :handle_unauthorized, only: :update

  def index
    @mailer_subscriptions = MailerSubscription::MAILERS.items.map do |item|
      MailerSubscription.find_or_initialize_by(mailer: item[:class], user: current_user)
    end
  end

  def create
    @mailer_subscription = current_user.mailer_subscriptions.build(mailer_subscription_params)
    @mailer_subscription.subscribed = true
    if @mailer_subscription.save
      redirect_to mailer_subscriptions_path, notice: "Preferences updated."
    else
      redirect_to mailer_subscriptions_path, alter: "#{@mailer_subscription.errors.full_messages.to_sentence}"
    end
  end

  def update
    if @mailer_subscription.toggle!(:subscribed)
      redirect_to mailer_subscriptions_path, notice: "Preferences updated."
    else
      redirect_to mailer_subscriptions_path, alter: "#{@mailer_subscription.errors.full_messages.to_sentence}"
    end
  end

  private

    def mailer_subscription_params
      params.require(:mailer_subscription).permit(:mailer)
    end

    def set_mailer_subscription
      @mailer_subscription = MailerSubscription.find(params[:id])
    end

    def handle_unauthorized
      redirect_to root_path, status: :unauthorized, notice: "Unauthorized." and return if current_user != @mailer_subscription.user
    end
end

What's Going On Here?

We create a page allowing a user to subscribe/unsubscribe from all possible mailers that are defined in MailerSubscription::MAILERS. We can't call @user.mailer_subscriptions because they may not have any records.

We create a handle_unauthorized method to prevent a user from subscribing/unsubscribing another user from mailers. We need to do this because we're passing in the ID of the MailerSubscription through the params hash which can be altered via the browser.

Build the views.

<%# app/views/mailer_subscriptions/index.html.erb %>
<ul style="list-style:none;">
  <%= render @mailer_subscriptions %>
</ul>

<%# app/views/mailer_subscriptions/_mailer_subscription.html.erb %>
<% if mailer_subscription.new_record? %>
  <li style="margin-bottom: 16px;">
    <p><%= mailer_subscription.description %></p>
    <%= button_to mailer_subscriptions_path, params: { mailer_subscription:  mailer_subscription.attributes } do %>
      <%= mailer_subscription.call_to_action %>
    <% end %>
    <hr/>
  </li>
<% else %>
  <li style="margin-bottom: 16px;">
    <p><%= mailer_subscription.description %></p>
    <%= button_to mailer_subscription_path(mailer_subscription), method: :put do %>
      <%= mailer_subscription.call_to_action %>
    <% end %>
    <hr/>
  </li>
<% end %>

What's Going On Here?

We loop through each MailerSubscription instance. If it's a new_record? we create a MailerSubscription. Otherwise, it's an existing record and we toggle! the subscribed value.

In either case we use a button_to to hit the correct endpoint. Note that when we're creating a new MailerSubscription we pass mailer_subscription.attributes as params, but we're only permitting the mailer value in our controller.

http://localhost:3000/mailer_subscriptions

Step 5: Add Unsubscribe Link to Mailer and Prevent Delivery if User Has Unsubscribed

Add shared logic to ApplicationMailer.

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  before_action :set_user
  before_action :set_unsubscribe_url, if: :should_unsubscribe?
  before_action :set_mailer_subscriptions_url, if: :should_unsubscribe?

  after_action :prevent_delivery_if_recipient_opted_out, if: :should_unsubscribe?

  default from: 'from@example.com'
  layout 'mailer'

  private

  def prevent_delivery_if_recipient_opted_out
    mail.perform_deliveries = @user.subscribed_to_mailer? self.class.to_s
  end

  def set_user
    @user = params[:user]
  end

  def set_unsubscribe_url
    @unsubscribe_url = mailer_subscription_unsubcribe_url(@user.to_sgid.to_s, mailer: self.class)
  end  

  def set_mailer_subscriptions_url
    @mailer_subscriptions_url = mailer_subscriptions_url
  end

  def should_unsubscribe?
    @user.present? && @user.respond_to?(:subscribed_to_mailer?)
  end
end

What's Going On Here?

We add several action mailer callbacks to the ApplicationMailer in order for this logic to be shared across all mailers.

We call prevent_delivery_if_recipient_opted_out which will conditionally prevent the mailer from being sent if the user is not subscribed to that mailer. This is accomplished by setting mail.perform_deliveries to true or false based on the return value of @user.subscribed_to_mailer? self.class.to_s. Note that calling self.class.to_s will return the name of the mailer (i.e. MarketingMailer).

We call @user.to_sgid.to_s to ensure the the URL is unique and does not contain the user's id. Otherwise a bad actor could unsubscribe any user from a mailer.

We conditionally call these callbacks with should_unsubscribe? to ensures we've passed a user to the mailer.

Conditionally render unsubscribe links in mailer layouts.

<%# app/views/layouts/mailer.html.erb %>
<!DOCTYPE html>
<html>
  ...
  <body>
    <%= yield %>
    <%= render "shared/mailers/unsubscribe_links" if @unsubscribe_url.present? %>
  </body>
</html>

<%# app/views/layouts/mailer.txt.erb %>
<%= yield %>
<%= render "shared/mailers/unsubscribe_links" if @unsubscribe_url.present? %>

Did you like this post? Follow me on Twitter to get even more tips.

Build an API in Rails with Authentication

Steve Polito — Sat, 31 Jul 2021 12:40:06 +0000

In this tutorial, we'll build a full-featured API in Rails with authentication. Below is what we'll cover.

Encrypting API keys.
Building a form to view and rotate the API key.
Versioning our API.
Returning the correct HTTP status code.
Authorizing requests.
Handling missing records.
Monitoring API usage.
Writing tests for the API.

A form allowing users to view and rotate their private API key

API as viewed from Postman.

Step 1: Add Encrypted Private API Key Column to Users Table

Install lockbox and blind_index.

bundle add lockbox
bundle add blind_index

Configure Lockbox for test, development, and production environments. You'll want to run the following code for each environment.

rails c 
Lockbox.generate_key
=> "123abc"
rails credentials:edit --environment=test

lockbox:
  master_key: "123abc"

Create migration.

rails g migration add_private_api_key_ciphertext_to_users private_api_key_ciphertext:text

# db/migrate/xxx_add_private_api_key_ciphertext_to_users.rb
class AddPrivateApiKeyToUsers < ActiveRecord::Migration[6.1]
  def change
    # encrypted data
    add_column :users, :private_api_key_ciphertext, :text

    # blind index
    add_column :users, :private_api_key_bidx, :string
    add_index :users, :private_api_key_bidx, unique: true
  end
end

rails db:migrate

Update User model.

# app/models/user.rb
class User < ApplicationRecord
  encrypts :private_api_key
  blind_index :private_api_key
end

Set private api key via a callback.

# app/models/user.rb
class User < ApplicationRecord
  encrypts :private_api_key
  blind_index :private_api_key

  before_create :set_private_api_key

  validates :private_api_key, uniqueness: true, allow_blank: true

  private

    def set_private_api_key
      self.private_api_key = SecureRandom.hex if self.private_api_key.nil?
    end
  end
end

What's Going On Here?

We use Lockbox as a means to encrypt the private API key because the key is essentially as sensitive as a username and password. If the database were ever compromised, the keys would not be exposed. This gem also allows us to reference the column as private_api_key and not private_api_key_ciphertext

We use Blink Index as a means to query against the key, as well as ensure its value is unique. We need Blink Index because the column is encrypted.

We add a validation ensuring the key is unique. This is because the key will be used to identify a user.

We use SecureRandom to generate a unique value for the key. This is necessary to make it difficult for someone to guess another user's key.

Step 2: Allow User to View and Rotate Private API Key

Create an endpoint for creating a new key.

rails g controller user/private_api_keys

# app/controllers/user/private_api_keys_controller.rb
class User::PrivateApiKeysController < ApplicationController
  before_action :authenticate_user!

  def update
    if current_user.update(private_api_key: SecureRandom.hex)
      redirect_to edit_user_registration_path, notice: "API Updated"
    else
      redirect_to edit_user_registration_path, alert: "There was an error: #{current_user.errors.full_messages.to_sentence}"
    end
  end
end

Update routes.

# config/routes.rb
Rails.application.routes.draw do
  namespace :user do
    resource :private_api_keys, only: :update
  end
end

Update views.

rails g devise:views

# app/views/devise/registrations/edit.html.erb
<%= form_for(resource, as: resource_name, url: registration_path(resource_name), html: { method: :put }) do |f| %>
...
<% end %>
...
<h3>API Key</h3>
<%= form_with model: current_user, url: user_private_api_keys_path do |f| %>
  <%= f.text_field :private_api_key, disabled: true %>
  <%= f.submit "Generate New Key" %>
<% end %>
...

What's Going On Here?

We create a namespaced endpoint allowing a user to update their API key. We don't need to namespace the route, but it helps keep things organized. We add a new form to the view generated by Devise. This form simply hits the endpoint and generates a new API key.

Note that we set the input to be disabled to ensure a user can't set their own key. We want this to happen server-side.

Step 3: Create Post Model

Create and run migration.

rails g model Post user:references title:string body:text
rails db:migrate

Add validations.

# app/models/post.rb
class Post < ApplicationRecord
  belongs_to :user

  validates :title, :body, presence: true
end

Associate with User.

# app/models/user.rb
class User < ApplicationRecord
  ...
  has_many :posts, dependent: :destroy
  ...
end

Seed data.

# db/seeds.rb
User.create(email: "user@example.com", password: "password")
10.times do |i|
  User.first.posts.create(title: "Post #{i+1}", body: "Body copy")    
end


User.create(email: "another_user@example.com", password: "password")

rails db:seed

Step 4: Create API Endpoints

Generate namespaced controllers

rails g controller api/v1/posts

Add routes.

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      defaults format: :json do
        resources :posts, only: [:index, :create, :show, :update, :destroy]
      end
    end
  end
end

Create base controller.

touch app/controllers/api/v1/base_controller.rb

# app/controllers/api/v1/base_controller.rb
class Api::V1::BaseController < ApplicationController
end

# app/controllers/api/v1/posts_controller.rb
class Api::V1::PostsController < Api::V1::BaseController
end

What's Going On Here?

We create a namespaced endpoint to encapsulate and version our API. This is best practice since we'll want to make a new version of our API each time we make changes to it while still maintaining older versions.

We set the default format to respond with JSON. This means all responses from the API will be sent as JSON.

We create a base controller that will be inherited by the API. This will make it easy to add shared logic in the API without affecting the web interface.

Note that our Api::V1::PostsController now inherits from Api::V1::BaseController and not ApplicationController.

Step 5: Authenticate Requests

Authenticate all requests to the API.

# app/controllers/api/v1/base_controller.rb
class Api::V1::BaseController < ApplicationController
  before_action :authenticate

  private

    def authenticate
      authenticate_user_with_token || handle_bad_authentication
    end

    def authenticate_user_with_token
      authenticate_with_http_token do |token, options|
        @user ||= User.find_by(private_api_key: token)
      end
    end

    def handle_bad_authentication
      render json: { message: "Bad credentials" }, status: :unauthorized
    end

end

What's Going On Here?

We use the authenticate_user_with_token method that ships with Rails to authenticate all requests to our API with a user's private API key that will be sent through an Authorization HTTP header. We could pass the private API key via a querystring, but we would not be able to use authenticate_user_with_token method to find the user which is more secure.

We handle bad requests by responding with a JSON payload containing a simple message and a status of 401. It's our responsibility to respond with the correct HTTP Status Code.

Step 6: Handle Missing Records

Handle missing records.

# app/controllers/api/v1/base_controller.rb
class Api::V1::BaseController < ApplicationController
  rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found

  before_action :authenticate

  private

    def authenticate
      authenticate_user_with_token || handle_bad_authentication
    end

    def authenticate_user_with_token
      authenticate_with_http_token do |token, options|
        @user ||= User.find_by(private_api_key: token)
      end
    end

    def handle_bad_authentication
      render json: { message: "Bad credentials" }, status: :unauthorized
    end

    def handle_not_found
      render json: { message: "Record not found" }, status: :not_found
    end

end

What's Going On Here?

We rescue_from any missing record with a custom JSON response. You can think of this as a custom 404 page, but for an API. We make sure to respond with the correct HTTP Status Code.

Step 7: Create Response Views

Generate response partials with Jbuilder.

rails g jbuilder api/v1/posts user:references title:string body:text --model-name=Post

Update paths.

# app/views/api/v1/posts/index.json.jbuilder
json.array! @posts, partial: "api/v1/posts/post", as: :post

# app/views/api/v1/posts/index.json.jbuilder
json.partial! "api/v1/posts/post", post: @post

# app/views/api/v1/posts/_post.json.jbuilder
json.url api_v1_post_url(post, format: :json)

What's Going On Here?

We use Jbuilder to create the views our API will respond with. Instead of creating .html.erb files, we're simply creating JSON files. We could render the data directly in the Api::V1::PostsController, but this keeps our controller lean by using Rails conventions.

Step 8: Create Endpoints

Add controller actions and filters.

# app/controllers/api/v1/posts_controller.rb
class Api::V1::PostsController < Api::V1::BaseController
  before_action :set_post, only: [:show, :update, :destroy] 

  def index
    @posts = @user.posts
  end

  def show
  end

  def create
    @post = @user.posts.build(post_params)
    if @post.save
      render :show, status: :created
    else
      render json: { message: @post.errors.full_messages }, status: :unprocessable_entity
    end
  end

  def update
    if @post.update(post_params)
      render :show, status: :ok
    else
      render json: { message: @post.errors.full_messages }, status: :unprocessable_entity
    end
  end

  def destroy
    @post.destroy
    render :show, status: :ok
  end 

  private

    def set_post
      @post = Post.find(params[:id])
    end

    def post_params
      params.require(:post).permit(:title, :body)
    end
end

What's Going On Here?

We create a traditional controller with endpoints to list posts, get a post, update a post, create a post and delete a post.

Since this controller inherits from Api::V1::BaseController all requests will need to be authenticated.

We make sure to always respond with JSON either through our Jbuilder views, or directly in the controller.

We pass any error message to a message key in the JSON response. We don't have to call this key message, nor do we have to respond with a message at all, but we want to make out API helpful.

We make sure to always respond with the correct HTTP Status Code.

If you use an API client like Postman you can test the API.

API as viewed from Postman.
A successful request to the index action.

A non authenticated request to the index action.

Step 9: Authorize Requests.

Authorize requests.

# app/controllers/api/v1/posts_controller.rb
class Api::V1::PostsController < Api::V1::BaseController
  ...
  before_action :authorize_post, only: [:show, :update, :destroy]
  ...
  private
    ...
    def authorize_post
      render json: { message: "Unauthorized" }, status: :unauthorized unless @user == @post.user
    end
    ...
end

A unauthorized request to the show action.

What's Going On Here?

We don't want other users to able to view, update or destroy another user's data. We create a simple method to ensure the current user is the same user in the record.

Note that we don't need to do this for the index or create action, since those actions are already scoped to the user.

Step 10: Handle Invalid Authenticity Token

Invalid Authenticity Token is raised when trying to create a post

Update Controller.

# app/controllers/api/v1/base_controller.rb
class Api::V1::BaseController < ApplicationController
  protect_from_forgery with: :null_session
  ...
end

What's Going On Here?

By default, Rails protects any request other than a GET request from Cross-Site Request Forgery (CSRF) attacks by including a token in the rendered HTML for your application. However since we're making a request from outside of the application, Rails will raise a ActionController::InvalidAuthenticityToken error.

We add a call to protect_from_forgery with: :null_session to allow for unverified requests to hit our API.

A successful POST request.

Step 11: Log API Requests

Create Request Model.

rails g model Request user:references requestable_type:string method:integer

# db/migrate/xxx_create_requests.rb
class CreateRequests < ActiveRecord::Migration[6.1]
  def change
    create_table :requests do |t|
      t.references :user, null: false, foreign_key: true
      t.string :requestable_type, null: false
      t.integer :method, null: false

      t.timestamps
    end
  end
end

Associate with User.

# app/models/user.rb
class User < ApplicationRecord
  ...
  has_many :requests, dependent: :destroy
  ...
end

Validate Model.

# app/models/request.rb
class Request < ApplicationRecord
  belongs_to :user

  # ArgumentError: You tried to define an enum named "method" on the model "Request",
  # but this will generate a class method "delete", which is already defined by Active Record.
  enum method: [:get, :post, :put, :patch, :delete], _suffix: true

  validates :method, :requestable_type, :user, presence: true
  validates :requestable_type, inclusion: { in: %w(Post) }
end

Update Controller to Log API requests.

# app/controllers/api/v1/posts_controller.rb
class Api::V1::PostsController < Api::V1::BaseController
  ...

  def index
    ...
    @user.requests.create(method: :get, requestable_type: "Post")
  end

  def show
    @user.requests.create(method: :get, requestable_type: "Post")
  end

  def create
    ...
    @user.requests.create(method: :post, requestable_type: "Post")
  end

  def update
    ...
    @user.requests.create(method: :put, requestable_type: "Post")
  end

  def destroy
    ...
    @user.requests.create(method: :delete, requestable_type: "Post")
  end 
  ...
end

What's Going On Here?

We make a model to store all requests made by the User. To make this as flexible as possible we add an enum column to store the request method and a requestable_type column to store the class name of the record in the original API request. This will allow us to see exactly what type of request was made and on what record. This can be helpful if we need to enforce different usage limits for any combination of request method and record type.

Note that we add set _suffix: true on the enum value. This is because one of the enum values we're setting is delete, which is a reserved method name.

We create a validation to limit the requestable_type column to only "Post". This will ensure we keep our records consistently formatted.

Note that we set a database constraint on the method and requestable_type columns to prevent null values.

We create a new Request request for each action in the Api::V1::PostsController. We make sure to pass the correct HTTP request to the method.

User.first.requests.count
User.first.requests.where(method: :get).count
User.first.requests.where(method: :get, requestable_type: "Post", created_at: 1.month.ago.beginning_of_day..Time.now.end_of_day).count

API Tests

Below are tests needed to cover our API.

# test/controllers/api/v1/posts_controller_test.rb
require "test_helper"

class Api::V1::PostsControllerTest < ActionDispatch::IntegrationTest
  setup do
    @user_one = User.create(email: "#{SecureRandom.hex}@example.com", password: "password")
    @user_two = User.create(email: "#{SecureRandom.hex}@example.com", password: "password")
    @user_one_post = @user_one.reload.posts.create(title: "User One Post", body: "Body")
    @user_two_post = @user_two.reload.posts.create(title: "User One Post", body: "Body")
  end

  class Authenticated < Api::V1::PostsControllerTest
    test "should get posts" do
      assert_difference("Request.count", 1) do
        get api_v1_posts_path, headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
        assert_equal "application/json; charset=utf-8", @response.content_type
        assert_match  @user_one_post.title, @response.body
        assert_response :ok
      end
    end

    test "should get post" do
      assert_difference("Request.count", 1) do
        get api_v1_post_path(@user_one_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
        assert_equal "application/json; charset=utf-8", @response.content_type
        assert_match  @user_one_post.title, @response.body
        assert_response :ok
      end
    end

    test "should handle 404" do
      get api_v1_post_path("does_not_exis"), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
      assert_equal "application/json; charset=utf-8", @response.content_type
      assert_response :not_found
    end

    test "should create post" do
      assert_difference(["Post.count", "Request.count"], 1) do
        post api_v1_posts_path, headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }, params: { post: { title: "title", body: "body" }  }
        assert_equal "application/json; charset=utf-8", @response.content_type
        assert_match  "title", @response.body
        assert_response :created
      end
    end

    test "should handle errors on create" do
      assert_no_difference("Post.count") do
        assert_difference("Request.count", 1) do
          post api_v1_posts_path, headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }, params: { post: { title: nil, body: nil }  }
          assert_equal "application/json; charset=utf-8", @response.content_type
          assert_match "message", @response.body
          assert_response :unprocessable_entity
        end
      end      
    end

    test "should update post" do
      put api_v1_post_path(@user_one_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }, params: { post: { title: "updated" }  }
      assert_equal "application/json; charset=utf-8", @response.content_type
      assert_match  "updated", @response.body
      assert_response :ok
    end

    test "should handle errors on update" do
      assert_difference("Request.count", 1) do
        put api_v1_post_path(@user_one_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }, params: { post: { title: nil }  }
        assert_equal "application/json; charset=utf-8", @response.content_type
        assert_match "message", @response.body
        assert_response :unprocessable_entity
      end
    end

    test "should delete post" do
      assert_difference(["Post.count"], -1) do
        assert_difference("Request.count", 1) do
          delete api_v1_post_path(@user_one_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
          assert_equal "application/json; charset=utf-8", @response.content_type
          assert_response :ok
        end
      end
    end
  end

  class Unauthorized < Api::V1::PostsControllerTest
    test "should not get posts" do
      get api_v1_posts_path
      assert_response :unauthorized
    end

    test "should not load another's post" do
      get api_v1_post_path(@user_two_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
      assert_equal "application/json; charset=utf-8", @response.content_type
      assert_response :unauthorized
    end

    test "should not update another's post" do
      put api_v1_post_path(@user_two_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }, params: { post: { title: "updated" }  }
      assert_equal "application/json; charset=utf-8", @response.content_type
      assert_response :unauthorized
    end

    test "should not delete another's post" do
      assert_no_difference(["Post.count", "Request.count"]) do
        delete api_v1_post_path(@user_two_post), headers: { "Authorization": "Token token=#{@user_one.private_api_key}" }
        assert_equal "application/json; charset=utf-8", @response.content_type
        assert_response :unauthorized
      end
    end
  end

end

Did you like this post? Follow me on Twitter to get even more tips.

Search Across Multiple Models in Rails

Steve Polito — Sun, 27 Jun 2021 03:15:32 +0000

In this tutorial you'll learn how to search across multiple models in Rails. Below is a demo of what we'll be building. Note how both Post and User records appear in the search. As an added bonus, we highlight the search query in the results.

Step 1: Set Up

Create a new Rails application.

rails new rails-search-across-multiple-models

Generate a Post and User Scaffold.

rails g scaffold Post title body:text
rails g scaffold User name biography:text

Step 2: Create a Model to Store Search Entries

Create a SearchEntry model and run migrations.

rails g model SearchEntry title body:text searchable:references{polymorphic}
rails db:migrate

Convert the SearchEntry model to a Delegated Type.

# app/models/search_entry.rb
class SearchEntry < ApplicationRecord
  delegated_type :searchable, types: %w[ Post User ]
end

What's Going On Here?

We give the model a title and a body to standardize what columns we will be able to search against. This is the actual model that will be searched.

The model will connect other models through a polymorphic association. This means we can make any model searchable.

We use a delegated type to connect the SearchEntry model with the Post and User models.

Create a Searchable Concern.

# app/models/concerns/searchable.rb
module Searchable
  extend ActiveSupport::Concern

  included do
    has_one :search_entry, as: :searchable, touch: true
  end    
end

# app/models/post.rb
class Post < ApplicationRecord
  include Searchable
end

# app/models/user.rb
class User < ApplicationRecord
  include Searchable
end

What's Going On Here?

We create a concern to be shared across the Post and User model. This is not required, but helps keep our code DRY.

The concern is simply connecting the Post and User models to the SearchEntry model. When the Post or User models are updated, the associated SearchEntry model will have its updated_at column updated. This is because we're calling touch: true. That part is not required, but helps keep things consistent between models.

Step 3: Prevent Duplicate SearchEntry Records

Add a uniquness scope to the SearchEntry model.

# app/models/search_entry.rb 
class SearchEntry < ApplicationRecord
  delegated_type :searchable, types: %w[ Post User ]

  validates :searchable_type, uniqueness: { scope: :searchable_id }
end

What's Going On Here?

We add a uniqueness scope to prevent a Post or User from having multiple SearchEntry records associated with them. This will prevent duplicate search results.

Step 4: Use Callbacks to Dynamically Create, Update and Destroy SearchEntry Records.

Add the following callbacks to the Post and User models.

# app/models/post.rb
class Post < ApplicationRecord
  include Searchable

  after_commit :create_search_entry, on: :create
  after_commit :update_search_entry, on: :update
  after_commit :destroy_search_entry, on: :destroy

  private

    def create_search_entry
      SearchEntry.create(title: self.title, body: self.body, searchable: self)
    end

    def update_search_entry
      self.search_entry.update(title: self.title, body: self.body) if self.search_entry.present?
    end

    def destroy_search_entry
      self.search_entry.destroy if self.search_entry.present?
    end
end

# app/models/user.rb
class User < ApplicationRecord
  include Searchable

  after_commit :create_search_entry, on: :create
  after_commit :update_search_entry, on: :update
  after_commit :destroy_search_entry, on: :destroy

  private

    def create_search_entry
      SearchEntry.create(title: self.name, body: self.biography, searchable: self)
    end

    def update_search_entry
      self.search_entry.update(title: self.name, body: self.biography) if self.search_entry.present?
    end

    def destroy_search_entry
      self.search_entry.destroy if self.search_entry.present?
    end    
end

What's Going On Here?

We use callbacks to create, update and destroy an associated SearchEntry record per Post and User. This ensures that the associated SearchEntry will always be in sync with the source model.

We set the title and body columns on the SearchEntry to whatever values make most sense. This allows us to have full control over what will be able to be searched. Note that we can pass whatever we want into the title and body columns.

Step 5: Create the Search Form

Create a SearchEntries Controller.

rails g controller SearchEntries index

Add a route for the search form and root path.

# config/routes.rb
Rails.application.routes.draw do
  root to: 'search_entries#index'
  get 'search_entries/index', as: 'search'
  ...
end

Build the search endpoint.

# app/controllers/search_entries_controller.rb
class SearchEntriesController < ApplicationController
  def index
    @search_entries = SearchEntry.where("title LIKE ? OR body LIKE ?", "%#{params[:query]}%", "%#{params[:query]}%") if params[:query]
  end
end

What's Going On Here?

We query for any SearchEntry record that has a title or body containing the search query.

We add the if params[:query] conditional to prevent any results from being rendered until a user makes a search query. This is optional.

Build the search form and search partial.

# app/views/search_entries/index.html.erb
<%= form_with url: :search, method: :get do |form| %>
  <%= form.label :query, "Search for:" %>
  <%= form.text_field :query %>
  <%= form.submit "Search" %>
  <%= link_to "Reset", search_path %>
<% end %>
<%= render partial: "search_entries/search_entry", collection: @search_entries %>

# app/views/search_entries/_search_entry.html.erb
<%= link_to polymorphic_path search_entry.searchable do %>
  <h2><%= highlight search_entry.title, params[:query] %></h2>
  <span><strong><%= search_entry.searchable_type %></strong></span>
  <p><%= highlight search_entry.body, params[:query] %></p>
  <hr/>
<% end %>

What's Going On Here?

We create a simple search form that will hit search_entries#index. The form.text_field :query field simply passes the correct parameter into the URL.

We create a simple partial to render the search result. We use the polymorphic_path method to link to the correct model (Post or User).

We use the highlight method to highlight the string being searched.

Did you like this post? Follow me on Twitter to get even more tips.

Use Pundit as a Rails Feature Flag System

Steve Polito — Mon, 21 Jun 2021 15:38:35 +0000

In this tutorial, I'll show you how to create a feature flag system in Rails using pundit and a features column on the users table.

Resources

Source Code

Step 1: Initial Setup

This tutorial assumes you are using devise and have a User model. However, you should still be able to follow along and implement this pattern even if that's not the case.

Create a Post scaffold.

rails g scaffold Post title:string user:references meta_description:text

Add a features column to the users table by running the following command.

rails g migration add_features_to_users features:jsonb

Set a default value on the features column.


class AddFeaturesToUsers < ActiveRecord::Migration[6.1]
  def change
    add_column :users, :features, :jsonb, default: {}
  end
end

What's Going On Here?

We add a JSONB Column to our users table. This will allow us to store multiple features in one column, compared to making a column for each feature.

We add default: {} simply to add a formatted default value to this column.

Run the migrations.

rails db:migrate

Set features on User model.

class User < ApplicationRecord
  ...  
  FEATURES = %i[enable_post_meta_description].freeze
  store :features, accessors: User::FEATURES
end

What's Going On Here?

We create a FEATURES constant that will store the names of our features as symbols by calling %i on the array. We call .freeze to ensure this constant cannot be updated anywhere else.

We use ActiveRecord::Store to interface with the features column. This will allow us to call @user.enable_post_meta_description instead of user.features.enable_post_meta_description. By passing User::FEATURES into the accessors parameter we can continue to add new features in the FEATURES constant.

Setting a features column on the users table will allow us to enable/disable features on a per-user basis.

Enable the enable_post_meta_description for a user. That way you have something to test.

User.last.update(enable_post_meta_description: true)

Step 2: Install Pundit and Build a Policy

Next, we'll need to install and configure pundit.

Install pundit.

bundle add pundit

Generate the base pundit files.

rails g pundit:install

Include pundit in the ApplicationController

class ApplicationController < ActionController::Base
  include Pundit
end

Step 3: Build a Feature Flag Policy

Generate a namespaced pundit policy.

rails g pundit:policy feature/enable_post_meta_description

Build the policy

class Feature::EnablePostMetaDescriptionPolicy < ApplicationPolicy
  def ceate?
    user.present? && (user.enable_post_meta_description == true)
  end

  def permitted_attributes
    if user.enable_post_meta_description == true
      [:title, :user_id, :meta_description]
    else
      [:title, :user_id]
    end
  end
  ...
end

What's Going On Here?

We generate a policy under the feature namespace. This is not required, but it helps keep things organized and will allow us to add new policies for new features later. We also name this policy to match the name of the feature in the User model.

We build a ceate? method that returns true or false based on whether or not that user has the enable_post_meta_description feature set to true. We could have called the method index?, new?, update?, edit? or destroy? but create? makes the most sense in this context. We're building a policy that enables a user to create a meta description on a post.

We used pundit's permitted_attributes method to return an array of paramters to be used in the PostsController. This will allow us to conditionally permit the meta_description parameter.

Step 4: Implement the Feature Flag

Update the post_params to hook into the permitted_attributes method.

class PostsController < ApplicationController
  before_action :authenticate_user!, except: %i[ show index ] 
  before_action :set_post, only: %i[ show edit update destroy ]

  private
    ...
    def post_params
      params.require(:post).permit(
        Feature::EnablePostMetaDescriptionPolicy.new(current_user, Post).permitted_attributes
      )
    end
end

What's Going On Here?

We instantiate a new instance of the Feature::EnablePostMetaDescriptionPolicy policy class and pass in the current_user and Post per pundit's API. Then we call permitted_attributes to load the correct parameters based on whether the user has access to the meta_description.

Note that we call authenticate_user! before all actions except show and index since the Feature::EnablePostMetaDescriptionPolicy relies on a user.

Conditionally show the meta_description in the post form partial.

# app/views/posts/_form.html.erb
<%= form_with(model: post) do |form| %>
  ...
  <% if Feature::EnablePostMetaDescriptionPolicy.new(current_user, post).create? %>
    <div class="field">
      <%= form.label :meta_description %>
      <%= form.text_area :meta_description %>
    </div> 
  <% end %>
  ...
<% end %>

What's Going On Here?

We wrap the meta_description field in a new instance of the Feature::EnablePostMetaDescriptionPolicy policy class. We call create? which returns true or false based on whether the user has access to the meta_description.

Did you like this post? Follow me on Twitter to get even more tips.

Create an infinite scrolling blog roll in Rails with Hotwire

Steve Polito — Tue, 23 Mar 2021 01:54:19 +0000

In this tutorial, I'll show you how to add an infinitely scrolling blog roll using Rails and Hotwire. Note that this is different than Chris Oliver's awesome infinite scroll tutorial, in that we're loading a new post once a user scrolls to the bottom of a current post. Below is a demo.

Step 1: Application Set-Up

rails new rails-infinite-scroll-posts -d-postgresql --webpacker=stimulus
rails db:setup
bundle add turbo-rails
rails turbo:install

Step 2: Create Post Scaffold

rails g scaffold post title body:text
rails db:migrate

Step 3: Add Seed Data

bundle add faker -g=development
Update db/seeds.rb

10.times do |i|
    Post.create(title: "Post #{i+1}", body: Faker::Lorem.paragraph(sentence_count: 500))
end

rails db:seed

Step 4. Create the ability to navigate between Posts

touch app/models/concerns/navigable.rb

module Navigable
    extend ActiveSupport::Concern

    def next
        self.class.where("id > ?", self.id).order(id: :asc).first
    end

    def previous
        self.class.where("id < ?", self.id).order(id: :desc).first
    end
end

Include Module in Post Model

class Post < ApplicationRecord
  include Navigable
end

Note: We could just add the next and previous methods directly in the Post model, but using a Module means we can use these methods in future models.

Update PostsController

class PostsController < ApplicationController
    ...
    def show
        @next_post = @post.next
    end
    ...
end

Step 5: Use Turbo Frames to lazy-load the next Post

Add frames to app/views/posts/show.html.erb

<p id="notice"><%= notice %></p>
<%= turbo_frame_tag dom_id(@post) do %>
  <p>
    <strong>Title:</strong>
    <%= @post.title %>
  </p>
  <p>
    <strong>Body:</strong>
    <%= @post.body %>
  </p>
  <%= link_to 'Edit', edit_post_path(@post), data: { turbo_frame: "_top" } %> |
  <%= link_to 'Back', posts_path, data: { turbo_frame: "_top" } %>
  <%= turbo_frame_tag dom_id(@next_post), loading: :lazy, src: post_path(@next_post) if @next_post.present? %>
<% end %>

What's going on?

We wrap the content in a turbo_frame_tag with an ID of dom_id(@post). For example, the dom_id(@post) call will evaluate to id="post_1"if the Post's ID is 1. This keeps the ID's unique.
We add another turbo_frame_tag within the outer turbo_frame_tag to lazy-load the next post. We can look for the next post thanks to our Navigable module that we created earlier.
- The loading attribute ensures that the frame will only load once it appears in the viewport.
We add data: { turbo_frame: "_top" } to override navigation targets and force those pages to replace the whole frame. Otherwise, we would need to add Turbo Frames to the edit and index views.
- This is only because those links are nested in the outermost turbo_frame_tag.

Step 6: Use Stimulus to update the path as new posts are loaded

touch app/javascript/controllers/infinite_scroll_controller.js

import { Controller } from "stimulus"

export default class extends Controller {
    static targets = ["entry"]
    static values = {
        path: String,
    }

  connect() {
    this.createObserver();
  }

  createObserver() {
    let observer;

    let options = {
      // https://github.com/w3c/IntersectionObserver/issues/124#issuecomment-476026505
      threshold: [0, 1.0]
    };

    observer = new IntersectionObserver(entries => this.handleIntersect(entries), options);
    observer.observe(this.entryTarget);
  }

  handleIntersect(entries) {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        // https://github.com/turbolinks/turbolinks/issues/219#issuecomment-376973429
        history.replaceState(history.state, "", this.pathValue);
      }
    });
  }

}

Update that markup in app/views/posts/show.html.erb

<p id="notice"><%= notice %></p>
<%= turbo_frame_tag dom_id(@post) do %>
  <div data-controller="infinite-scroll" data-infinite-scroll-path-value="<%= post_path(@post) %>" data-infinite-scroll-target="entry">
    <p>
      <strong>Title:</strong>
      <%= @post.title %>
    </p>
    <p>
      <strong>Body:</strong>
      <%= @post.body %>
    </p>
    <%= link_to 'Edit', edit_post_path(@post), data: { turbo_frame: "_top" } %> |
    <%= link_to 'Back', posts_path, data: { turbo_frame: "_top" }  %>
  </div>
  <%= turbo_frame_tag dom_id(@next_post), loading: :lazy, src: post_path(@next_post) if @next_post.present? %>
<% end %>

What's going on?

We use the Intersection Observer API to determine when the post has entered the viewport.
- We set the threshold to [0, 1.0] to account for elements that are taller than the viewport. This ensures that entry.isIntersecting will return true.
When entry.isIntersecting returns true, we use History.replaceState() to update the URL with the path for the post that entered the viewport.
- The value for the path is stored in the data-infinite-scroll-path-value attribute.
- We add history.state as the first argument to history.replaceState to account for an issue with Turbolinks.

Step 7: Add a loading state and styles (optional)

Add Bootstrap via CDN to app/views/layouts/application.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title>RailsInfiniteScrollPosts</title>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag 'https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta2/dist/css/bootstrap.min.css', integrity: 'sha384-BmbxuPwQa2lc/FVzBcNJ7UAyJxM6wuqIj61tLrc4wSX0szH/Ev+nYRRuWlolflfl', crossorigin: 'anonymous' %>
    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  </head>

  <body>
    <div class="container">
      <%= yield %>
    </div>
  </body>
</html>

Update markup and add a loader to app/views/posts/show.html.erb

<p id="notice"><%= notice %></p>
<%= turbo_frame_tag dom_id(@post) do %>
  <article data-controller="infinite-scroll" data-infinite-scroll-path-value="<%= post_path(@post) %>" data-infinite-scroll-target="entry">
    <h2><%= @post.title %></h2>
    <p><%= @post.body %></p>
    <%= link_to 'Edit', edit_post_path(@post), data: { turbo_frame: "_top" } %> |
    <%= link_to 'Back', posts_path, data: { turbo_frame: "_top" }  %>
  </article>
  <%= turbo_frame_tag dom_id(@next_post), loading: :lazy, src: post_path(@next_post) do %>
    <div class="d-flex justify-content-center">
      <div class="spinner-border" role="status">
        <span class="visually-hidden">Loading...</span>
      </div>
    </div>
  <% end if @next_post.present? %>
<% end %>

Did you like this post? Follow me on Twitter to get even more tips.