DEV Community: julianrubisch

Deploying a Rails + SQLite App to a Synology NAS

julianrubisch — Fri, 13 Mar 2026 09:43:26 +0000

I built a small CRM for my consulting business using Avo on Rails 8. It tracks contacts, companies, deals, and follow-ups — nothing fancy, but shaped exactly to how I work. Single user. No team access needed.

The question was where to run it. A $7/month VPS felt wrong for a tool only I use. I don't need uptime guarantees or global availability — I need it accessible from my laptop, phone, and tablet, wherever I am.

The answer was already sitting in my office: a Synology NAS on my Tailscale network. Rails 8's Solid stack (Cache, Queue, Cable — all SQLite-backed) means the entire app is one process with one database file. That's NAS-friendly. And Tailscale means every device I own can reach it without exposing anything to the public internet.

Here's how I set it up.

The Setup

Synology DS918+ — Intel Celeron J3455 (x86_64, quad-core 1.5GHz), 4GB RAM
DSM 7.2.2-72806 — Container Manager ships Docker daemon 24.0.2
Tailscale installed from Package Center
SSH access enabled (Control Panel → Terminal & SNMP)
A Rails app with a working Dockerfile (Rails 7.1+ generates one by default)

Rails + Ruby in a container typically consumes 200–400MB. DSM uses around 1–1.5GB. With 4GB total, there's plenty of headroom.

Part 1: Prepare the NAS

Create a deploy user

Create a dedicated user via Control Panel → User & Group → Create.

Add to the administrators group (required for SSH access on Synology)
Shared folders: Read/Write on docker only, No Access on everything else
Application permissions: Deny all — this user only needs SSH, which comes from the administrators group membership

Set up SSH key authentication

Enable home directories first — without this, ssh-copy-id fails because there's nowhere to put authorized_keys. Go to Control Panel → User & Group → Advanced tab, check Enable user home service.

ssh-copy-id deploy@hal.local
ssh deploy@hal.local  # verify passwordless login

Fix the Docker PATH problem

This is the single biggest Synology gotcha. Non-interactive SSH commands (how deployment scripts work) get a limited PATH: /usr/bin:/bin:/usr/sbin:/sbin. Docker lives at /usr/local/bin/docker. It won't be found.

SSH into your NAS interactively:

# Edit sshd_config
sudo vi /etc/ssh/sshd_config
# Find PermitUserEnvironment and set it to: PermitUserEnvironment PATH

# Save the full interactive PATH to your SSH environment file
env | grep PATH | tee ~/.ssh/environment

Reboot the NAS (simplest way to restart sshd cleanly), then verify from your local machine:

ssh deploy@hal.local docker -v
# Should output: Docker version 24.0.2, build 610b8d0

Heads up: DSM updates can reset /etc/ssh/sshd_config. After any major update, re-verify with ssh deploy@hal.local docker -v and re-apply if needed.

Create directories for your app

sudo mkdir -p /volume1/docker/myapp/db
sudo mkdir -p /volume1/docker/myapp/storage

# UID 1000 matches the rails user inside the container
sudo chown -R 1000:1000 /volume1/docker/myapp/db /volume1/docker/myapp/storage

Enable passwordless sudo for Docker commands

The deploy script runs Docker commands over non-interactive SSH, which can't prompt for a password:

ssh deploy@hal.local
sudo sh -c 'echo "deploy ALL=(ALL) NOPASSWD: /usr/local/bin/docker-compose, /usr/local/bin/docker" > /etc/sudoers.d/deploy'
sudo chmod 440 /etc/sudoers.d/deploy
exit

This limits passwordless sudo to just Docker commands — no blanket access.

Set up a local Docker registry

A local registry means images never leave your network.

ssh deploy@hal.local "sudo mkdir -p /volume1/docker/registry/data"

Create the compose file on the NAS:

ssh deploy@hal.local "cat > /volume1/docker/registry/docker-compose.yml << 'EOF'
services:
  registry:
    image: registry:2
    container_name: registry
    ports:
      - \"5050:5000\"
    volumes:
      - /volume1/docker/registry/data:/var/lib/registry
    restart: unless-stopped
EOF"

Port 5000 is used by DSM, so the registry maps to 5050. Start it:

ssh deploy@hal.local "cd /volume1/docker/registry && sudo docker-compose up -d"

Verify:

curl http://<nas-tailscale-ip>:5050/v2/
# Should return: {}

Now configure your local Docker client to trust this HTTP registry. The registry runs plain HTTP, but Docker defaults to HTTPS.

OrbStack — edit ~/.orbstack/config/docker.json:

{
  "insecure-registries": ["<nas-tailscale-ip>:5050"]
}

Docker Desktop — Settings → Docker Engine, add the same entry.

Restart after the change. This is safe — traffic runs over Tailscale, which is already encrypted.

Confirm Tailscale is working

tailscale status

Note your NAS's Tailscale IP. That's the address you'll use to access the app.

Part 2: Prepare Your Rails App

Configure the database for persistent storage

In config/database.yml, point the production database to a path that will be mounted from the host:

production:
  <<: *default
  database: /data/production.sqlite3

/data as an absolute path (not relative to /rails) ensures the database lives on the mounted volume and survives container replacements.

Update the Dockerfile

The Rails-generated Dockerfile needs a few modifications.

In the build stage, add Node.js and Yarn for asset compilation (skip this if you're not using Vite/esbuild):

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y \
      build-essential git libyaml-dev pkg-config nodejs npm && \
    npm install -g yarn && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

After COPY . ., install JS dependencies:

RUN yarn install --frozen-lockfile

In the final stage, create the /data directory before switching to the non-root user. This is the part that tripped me up — mkdir /data and chown must happen while still root:

RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
    mkdir /data && \
    chown rails:rails /data

# Copy built artifacts BEFORE switching user
COPY --chown=rails:rails --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --chown=rails:rails --from=build /rails /rails

USER 1000:1000

If USER 1000:1000 comes before mkdir /data, the non-root user won't have permission to create it.

Build and push the image

# Build for linux/amd64 (DS918+ uses Intel Celeron)
docker build --platform linux/amd64 -t <nas-tailscale-ip>:5050/myapp:latest .

# Push to the local registry
docker push <nas-tailscale-ip>:5050/myapp:latest

The --platform linux/amd64 flag is essential if you're building on Apple Silicon. Without it, you'll get an exec format error when the container starts on the NAS.

Part 3: Deploy to the NAS

The compose file

Create docker-compose.production.yml in your repo:

services:
  web:
    image: localhost:5050/myapp:latest
    container_name: myapp
    ports:
      - "3000:8080"
    environment:
      RAILS_ENV: production
      RAILS_MASTER_KEY: ${RAILS_MASTER_KEY}
      RAILS_SERVE_STATIC_FILES: "true"
      HTTP_PORT: "8080"
    volumes:
      - /volume1/docker/myapp/db:/data
      - /volume1/docker/myapp/storage:/rails/storage
    restart: unless-stopped

The port mapping: Rails 8 includes Thruster, a small Go proxy that handles asset caching and gzip. Inside the container, Thruster listens on HTTP_PORT (8080) and proxies to Puma on 3000. Docker maps external 3000 to Thruster's 8080. Thruster can't use its default port 80 because the container runs as a non-root user.

The image address: localhost:5050 because the NAS pulls from its own registry. Your Mac pushes to the Tailscale IP — same registry, different address. Docker trusts localhost by default, so no insecure registry config is needed on the NAS side.

Create the .env file on the NAS

One-time setup — this file stays on the NAS and is never committed:

ssh deploy@hal.local "echo 'RAILS_MASTER_KEY=<your-master-key>' > /volume1/docker/myapp/.env"

The deploy script

Add bin/deploy to your repo:

#!/usr/bin/env bash
set -e

NAS_HOST="deploy@hal.local"
REGISTRY="<nas-tailscale-ip>:5050"
IMAGE="$REGISTRY/myapp:latest"
APP_DIR="/volume1/docker/myapp"

echo "==> Building image..."
docker build --platform linux/amd64 -t $IMAGE .

echo "==> Pushing to local registry..."
docker push $IMAGE

echo "==> Copying compose file to NAS..."
cat docker-compose.production.yml | ssh $NAS_HOST "cat > $APP_DIR/docker-compose.yml"

echo "==> Pulling image and restarting..."
ssh $NAS_HOST "cd $APP_DIR && sudo docker-compose pull && sudo docker-compose up -d"

echo "==> Done! App is live."

chmod +x bin/deploy
bin/deploy

On the first run, the Docker entrypoint runs db:prepare automatically — creates the database and runs migrations. Subsequent deploys run pending migrations on container startup.

Confirm that the container is up and running in Container Manager:

Open http://<nas-tailscale-ip>:3000 from any device on your Tailscale network.

Backups

This is where running on a NAS pays off.

HyperBackup

The database lives at /volume1/docker/myapp/db/ as a regular file on the NAS filesystem. Include it in any HyperBackup task — to an external drive, another NAS, or a cloud destination.

This is a real advantage over Docker named volumes, which are hidden in /volume1/@docker/volumes/ and invisible to File Station and backup tools.

Btrfs Snapshots

The DS918+ supports Btrfs. Use Snapshot Replication for point-in-time recovery — especially useful as a safeguard before running migrations.

Manual backup

sudo cp /volume1/docker/myapp/db/production.sqlite3 \
       /volume1/docker/myapp/db/production.sqlite3.backup.$(date +%Y%m%d)

The whole deploy cycle is bin/deploy — build, push to the local registry, restart the container. No CI pipeline, no cloud provider, no monthly bill. The NAS handles backups through the same tools you're already using for everything else on it.

If you're building small Rails apps for yourself or a handful of users, this is a setup worth considering. The Solid stack made the architecture possible. The NAS makes the operations trivial.

You Know Hotwire Basics. Now What?

julianrubisch — Tue, 10 Mar 2026 16:00:26 +0000

There's no shortage of "Getting Started with Hotwire" content. Install Turbo, add a <turbo-frame>, watch the page update without a full reload. Great. You've done the tutorial.

But then you're back in your app, staring at a real problem — optimistic UI updates, race conditions on rapid clicks, progressive image loading — and the tutorial didn't cover any of that.

That gap is why I started the Hotwire Club.

What It Is

A biweekly coding challenge series. Every two weeks, a new challenge goes up. Each one isolates a single problem — the kind you'd actually run into building a production app — and strips it down to first principles.

No video courses. No 40-part curriculum. Just a focused problem, a live coding environment on StackBlitz, and your brain.

We've published 45+ challenges since April 2023, covering Turbo Drive, Turbo Frames, Turbo Streams, and Stimulus.

What a Challenge Looks Like

Every challenge follows the same structure: Premise, Starting Point, Challenge.

The Premise frames the problem. Take our most popular challenge, Optimistic UI with Turbo 8 Morphs. It opens with a bit of napkin math:

Let's assume our server lives in Chicago, and the client is in Amsterdam. That's 6,604 km. Taking the speed of light into account, the lowest possible latency is 22ms, one way. Round it up to 50ms. Where does that put us?

User clicks a button → 50ms until it reaches the server

Server calculates response → 100ms (fast)

Answer is returned → again 50ms

That's 200ms already. Way beyond the "perceived as instant" limit of 100ms.

The Starting Point gives you a pre-built scaffold on StackBlitz — a working app with a deliberate gap. You don't build from scratch. You fill in the missing piece.

The Challenge tells you exactly what to implement. In this case: render an inline <turbo-stream> to swap the UI immediately on click, then let Turbo 8's morph reconcile the DOM when the server responds. The favorite button updates instantly. The server catches up in the background.

Another popular one: Progressive Image Loading with Blurhash. It takes a real performance problem — images tanking your Largest Contentful Paint — and turns it into a Stimulus controller challenge. Paint a blurhash to a canvas, fade in the real image when it loads. Practical, visual, and you walk away with a pattern you can drop into a real app.

No Rails Required

Here's a thing that gets lost in the discourse: Turbo and Stimulus are JavaScript libraries. They're not welded to Rails.

All our challenges run on StackBlitz with a Node.js backend. You don't need a Ruby environment. You don't need to set up a Rails app. Open the link, read the challenge, write code. If you use Django, Laravel, Phoenix, or plain HTML — the patterns still apply.

We do use Rails conventions as reference points (you have to imagine that the Node handler is a Rails controller), but the actual code you write is JavaScript and HTML.

Who It's For

You already know what <turbo-frame> does. You've read the Stimulus handbook. You want to go deeper.

As Teddy Valente, CTO at Wobee, put it:

"The Hotwire Club is a fantastic resource for anyone who already has a good knowledge of Hotwire and wants to deepen their mastery. The exercises are always interesting and very well written. The answers are always detailed and to the point. You can even find exercises that will be useful in your work and for new features."

If that sounds like where you're at, this is for you.

Free Challenges, Optional Extras

Every challenge is free. The write-up, the StackBlitz environment, the problem — all open. About 2/3 of all solutions are free too.

If you want sample solutions and access to a private Discord where people discuss approaches, there's a Patreon starting at $5/month. But the challenges themselves? Those are yours.

Try One

Pick a challenge and see if it clicks:

Optimistic UI with Turbo 8 Morphs — make a favorite button feel instant using inline Turbo Streams and morph reconciliation
Progressive Image Loading with Blurhash — improve LCP with placeholder blurhashes and a Stimulus controller
Browse all challenges — 45+ and counting

See you in the club.

Measuring the Impact of Feature Flags in Ruby on Rails with AppSignal

julianrubisch — Wed, 16 Oct 2024 14:07:00 +0000

Feature flags are a powerful tool in software development, allowing developers to control the behavior of an application at runtime without deploying new code. They enable teams to test new features, perform A/B testing, and roll out changes gradually.

In Ruby on Rails, feature flags can be managed using diverse tools, the most popular being the Flipper gem. This article will explore implementing and measuring the impact of feature flags in a Solidus storefront using Flipper and AppSignal's custom metrics.

What Are Feature Flags in Rails, Again?

If you are looking for an introduction to the subject, check out the post Add Feature Flags in Ruby on Rails with Flipper.

In a nutshell, though, feature flags are a way to influence how your application behaves at runtime, without having to deploy new code. The simplest type of feature flags are environment variables. Every Ruby on Rails application uses them out of the box. One example is the configuration of application server concurrency using ENV['WEB_CONCURRENCY'].

However, there are other ways to manage feature flags, such as using a persistence layer like ActiveRecord or Redis. A comprehensive way to do this is offered by the Flipper gem.

The following snippet exemplifies how the performance_improvement feature flag is evaluated for a given user:

@categories = if Flipper.enabled?(:performance_improvement, user)
  Category.all.includes(:products)
else
  Category.all
end

Next, we will set up a Solidus storefront to start experimenting with feature flags.

Our Example App: A Solidus Storefront

To measure the impact of feature flags in a somewhat realistic scenario, let's quickly bootstrap a Solidus store:

rails new coder_swag_store && cd coder_swag_store
bundle add solidus
bin/rails g solidus:install

This generator will guide you through the process and ask you a few setup questions.

Choose the starter frontend when queried for the frontend type.
Skip setting up a payment method.
Choose to mount your Solidus application at /, since we are using it as a standalone app.

Afterward, run bin/dev from your terminal and you should be good to go. When you go to http://localhost:3000, you'll see this screen:

Implement Feature Flags with Flipper

Now let's implement two exemplary use cases for feature flags:

A performance improvement.
An attempt at conversion rate optimization.

First of all, though, we have to add the flipper gem along with its active_record storage adapter:

bundle add flipper
bundle add flipper-active_record
bin/rails g flipper:setup
bin/rails db:migrate

This will set up the required database tables to look up Flipper "gates", i.e., concrete conditionals to evaluate when checking a feature flag.

Testing a Performance Improvement

To assess this scenario, we will simulate a slow request in the storefront by adding a sleep 1 call for the unoptimized case:

# app/controllers/products_controller.rb

def index
  @searcher = build_searcher(params.merge(include_images: true))
  @products = @searcher.retrieve_products

  if Flipper.enabled?(:performance_improvement)
    # 🚅
  else
    sleep 1
  end
end

Now, we will use a "percentage of time" strategy to roll out the optimization across a random set of requests. Open a Rails console and key in the following:

Flipper.enable_percentage_of_time(:performance_improvement, 50)

Using the oha load testing tool, we can confirm that indeed half of the requests take one second longer than the others:

$ oha http://localhost:3000/products -z 30s -q 2
Summary:
  Success rate: 100.00%
  Total:        30.0037 secs
  Slowest:      1.2662 secs
  Fastest:      0.1049 secs
  Average:      0.6260 secs
  Requests/sec: 2.0664

  Total data:   2.59 MiB
  Size/request: 44.24 KiB
  Size/sec:     88.47 KiB

Response time histogram:
  0.105 [1]  |■
  0.221 [24] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.337 [8]  |■■■■■■■■■■
  0.453 [0]  |
  0.569 [0]  |
  0.686 [0]  |
  0.802 [0]  |
  0.918 [0]  |
  1.034 [0]  |
  1.150 [6]  |■■■■■■■■
  1.266 [21] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■

Testing Conversion Rate Optimization

When dealing with user-facing features, for example, changes in the UI, it's often advisable to use a "percentage of actors" strategy to roll out flags. This way, every user is consistently offered the same experience.

So to start, we'll create two users for our e-commerce application. Fire up a Rails console and issue the following commands:

Spree::User.create(email: "test1@example.com", login: "test1@example.com", password: "super_safe_password", password_confirmation: "super_safe_password")
Spree::User.create(email: "test2@example.com", login: "test2@example.com", password: "super_safe_password", password_confirmation: "super_safe_password")
Flipper.enable_percentage_of_actors(:conversion_rate_optimization, 50)

This creates two sample users and ensures that the feature flag is consistently enabled for one of them.

To simulate a feature attempting to drive conversion rates up, we'll make the checkout button pulsate:

<!-- app/views/carts/_cart_footer.html.erb -->
<% order = order_form.object %>

<footer class="cart-footer">
  <%= render 'carts/cart_adjustments' %>
  <p class="cart-footer__total flex justify-between mb-3 text-body-20 p-2">
    <%= t('spree.total') %>: <span class="font-sans-md"><%= order.display_total %></span>
  </p>
  <div class="cart-footer__primary-action">
    <%= order_form.button(
      I18n.t('spree.checkout'),
      class: "button-primary w-full #{'animate-pulse' if Flipper.enabled?(:conversion_rate_optimization, spree_current_user)}",
      id: 'checkout-link',
      name: :checkout
    ) %>
  </div>
</footer>

If we log in with both users and arrange the browser windows side by side, we can observe that indeed the effect is active for one (the left) user.

Use AppSignal Custom Metrics to Measure the Impact of Feature Flags

The best feature flag system is useless if there's no way to evaluate its impact. In our example scenario, we simply want to know:

Has the performance improvement led to a significant latency reduction?
Has our pulsating checkout button led to a significantly higher conversion rate?

We will use AppSignal's custom metrics to measure the pay-off of these optimizations.

First of all, create a new application in your AppSignal organization and connect it to your app by following the instructions:

bundle add appsignal
bundle exec appsignal install YOUR_APPSIGNAL_UUID

Measuring Latency with a Measurement Metric

We have verified how effective our improvement is with the oha CLI above, but to make valid judgments we'll install server-side telemetry that reports latency to AppSignal. A measurement metric allows for exactly that: we will send over response times in milliseconds, and add a metric tag indicating whether our performance optimization was active for a specific request.

There's a small gotcha here: because we're employing the "Percentage of Time" metric, we have to capture the flag's state in an instance variable so that the same value is used for execution and for reporting:

# app/controllers/products_controller.rb

class ProductsController < StoreController
  around_action :measure_response_time, only: :index

  # ...

  def index
    @searcher = build_searcher(params.merge(include_images: true))
    @products = @searcher.retrieve_products

    @performance_improvement_enabled = Flipper.enabled?(:performance_improvement)

    if @performance_improvement_enabled
      # 🚅
    else
      sleep 1
    end
  end

  # ...

  private

  # ...

  def measure_response_time
    response_time = Benchmark.realtime { yield }
    Appsignal.add_distribution_value("products_response_time", response_time * 1000, performance_improvement_enabled: @performance_improvement_enabled)
  end
end

Now let's repeat the local load testing from above:

$ oha http://localhost:3000/products -z 30s -q 2

We'll look at charting and evaluating this metric in a bit. Before that, let's turn to our second feature flag.

Tallying Conversions with a Count Metric

We'll use a counter metric to count conversions. This is a great choice if all you want to do is just keep a tally of an event.

To do this, we'll have to open CartsController, and, for demonstration purposes, add an increment_counter call if the checkout button is clicked:

# app/controllers/carts_controller.rb

def update
  authorize! :update, @order, cookies.signed[:guest_token]
  if @order.contents.update_cart(order_params)
    # ...

    Appsignal.increment_counter("checkout_count", 1, optimization_active: Flipper.enabled?(:conversion_rate_optimization, spree_current_user))

    # ...
  else
    render action: :show
  end
end

Now let's test this by manually opening respective browser windows and clicking the "Checkout" button 3 times, and in another case only once. In this way, we can see if the optimization flag is active.

Set Up Custom Dashboards in AppSignal

Our final step is to create informative graphics to make data-informed business decisions. We'll use AppSignal's dashboards to achieve this. Let's go through this step by step:

In the left sidebar, click "Add dashboard" and name it "Feature Flag Evaluation".

Click "Add Graph" and the products_response_time metric. Select "mean" to display only averages and apply the performance_improvement_enabled tag.

Click "Add new Graph" to add a chart for the checkout counts. Again, apply the optimization_active tag.

Now your custom dashboard is ready. In the line graph on the left, you can assert that your performance improvement was effective. On the right, observe how the higher count of checkouts in the optimized case was recorded.

And that's it!

Wrapping Up

We've seen how feature flags offer a flexible and efficient way to manage and deploy new features in a Ruby on Rails application. By using tools like the Flipper gem and AppSignal's custom metrics, developers can not only control feature rollouts, but also measure their impact on performance and user behavior.

This approach ensures that new features are thoroughly tested and optimized before being fully deployed, ultimately leading to a more stable and user-friendly application. Finally, it can lead to more informed business decisions when gauging the effectiveness of alternative approaches.

Happy coding!

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

An Introduction to HTTP Caching in Ruby On Rails

julianrubisch — Wed, 28 Aug 2024 11:12:14 +0000

It's 2024, and the HyperText Transfer Protocol (HTTP) is 35 years old. The fact that the vast majority of web traffic still relies on this simple, stateless form of communication is a marvel in itself.

A first set of content retrieval optimizations were added to the protocol when v1.0 was published in 1996. These include the infamous caching instructions (aka headers) that the client and server use to negotiate whether content needs refreshing.

28 years later, many web developers still avoid using it like the plague. A great deal of traffic and server load (and thus, latency) can be avoided, though, by using the built-in caching mechanism of the web. Not only does this result in a greatly improved user experience, it can also be a powerful lever to trim down your server bill. In this post, we'll take a look at:

The basic concepts around HTTP caching.
What cache layers we can leverage.
How web caching is configured and controlled.
How simple it is to cache in Ruby on Rails.

Let's get started!

Concepts

Before we dive deep into the mechanics of web caching, let's get some definitions out of the way.

Fresh Vs. Stale

Let's assume we have a shared cache server in place that stores responses from our app server for reuse. Later, a client issues a request to our app server. The stored response in our cache is now in one of two states:

Fresh: The response is still valid (we'll see what that means in a second) and will be used to fulfill the request.
Stale: The response isn't valid anymore. A new response has to be calculated and served by the upstream server.

HTTP Cache Layers

The HTTP Caching spec defines two types of cache — shared and private.

Shared Caches

Shared caches store responses that are reusable among a group of users. Typically, shared caches are implemented at intermediaries, e.g., Nginx, Caddy, or other reverse proxies. Of course, commercial edge caches like Cloudflare or Fastly also implement shared caches.

Another flavor of shared caches can be implemented in service workers using the Cache API.

We can control which responses are eligible for caching with the Cache-Control header.

Private Caches

Private caches are allotted to a single user. You are most likely to encounter a private cache as a browser component. The main feature here is that the stored responses are not shared with other clients. Any content that the server renders containing personalized data must only be stored in a private cache. In general, this will be the case for any authenticated route in your Rails app, but there might be exceptions.

You can force a response to be cached privately using the Cache-Control: private header.

Controlling Caching Via the `Cache-Control` Header

Although, historically, other headers have been in use (like Expires or Pragma), we will focus on the Cache-Control header here. The specification has an exhaustive description, but we'll focus on the salient parts.

The Cache-Control header sets one or several comma-separated directives that can be further divided into request and response directives.

Request Directives

When requesting a resource from the server, the client (browser) can specify one of the following directives to negotiate how caching should behave:

no-cache - Advises the cache to revalidate the response against the origin server. Typically this happens when you force reload a page or disable caching in the browser's developer tools.
no-store - Indicates that no cache must store any part of this request or any response.
max-age - In seconds, indicates the timespan for which a response from the server is considered fresh. For example, Cache-Control: max-age=3600 would tell the server that any response older than an hour cannot be reused.

Response Directives

Essentially, response directives consist of what's above, with different semantics, plus a few more. A cache must obey these directives coming from the origin server:

no-cache - A bit counterintuitively, this directive does not imply that the response cannot be cached. Rather, each cache must revalidate the response with the origin server for each reuse. This is the normal case for a response from a Rails application.
no-store - No cache of any type (shared or private) must store this response.
max-age - Indicates the period into the future for which the response should count as fresh. So, Cache-Control: max-age=3600 would specify a period of one hour from the moment of generation on the origin server. Afterwards, a cache cannot reuse it.
private - This directive specifies that the response can only be stored in a private cache (i.e., the browser). This should be set for any user-personalized content, especially when a session cookie is required to access a resource.
public - Indicates that a response can be stored in a shared cache.
must-revalidate - An edge case worth noting: HTTP allows the reuse of stale responses when caches are disconnected from the origin server. This directive prevents that and forces a fresh response or a 504 gateway timeout error.

(In)validation

Let's say a response has become stale for some reason (it's expired, for example). Even so, there's a chance that it is still valid, but we have to ask the origin server if this is the case. This process is called validation and is performed using a conditional request in one of two ways: by expiration or based on the response content.

By Expiration

The client sends an If-Modified-Since header in the request, and the cache uses this header to determine if the respective response has to be revalidated. Let's consider this response.

HTTP/1.1 200 OK
...
Date: Fri, 29 Mar 2024 10:30:00 GMT
Last-Modified: Fri, 29 Mar 2024 10:00:00 GMT
Cache-Control: max-age=3600
...

It was retrieved at 10:30 and is stored on the client. The combination of Last-Modified and max-age tells us that this response becomes stale at 11:30. If the client sends a request at 11:31, it includes an If-Modified-Since header:

GET /index.html HTTP/1.1
Host: example.com
Accept: text/html
If-Modified-Since: Fri, 29 Mar 2024 10:00:00 GMT

The server now calculates the content of the response and, if it hasn't changed, sends a 304 Not Modified response:

HTTP/1.1 304 Not Modified
...
Date: Fri, 29 Mar 2024 11:31:00 GMT
Last-Modified: Fri, 29 Mar 2024 10:00:00 GMT
Cache-Control: max-age=3600

Because it's a redirect, this response has no payload. It merely tells the client that the stale response has been revalidated and can revert to a fresh state again. Its new expiry time is now 12:31.

Based On the Response Content

Timing is a problematic matter: servers and clients can drift out of sync or file system timestamps may not be appropriate. This is solved by using an ETag header. This can be an arbitrary value, but most frequently, it is a digest of the response body. Picking up the example from above, we swap Last-Modified for an ETag header:

HTTP/1.1 200 OK
...
Date: Fri, 29 Mar 2024 10:30:00 GMT
ETag: "12345678"
Cache-Control: max-age=3600
...

If this response is stored in a private cache and becomes stale, the client now uses the last known ETag value and asks the server to revalidate it:

GET /index.html HTTP/1.1
Host: example.com
Accept: text/html
If-None-Match: "12345678"

Now, the server will return a 304 Not Modified response if the values of a freshly computed ETag and the requested If-None-Match header match. Otherwise, it will respond with 200 OK and a new version of the content.

I will not go into the details here, but the Rails docs explain weak vs. strong ETags.

Implementation In Rails

We're now ready to implement this knowledge in a Rails app. The relevant module is wired into ActionController and is called ActionController::ConditionalGet. Let's examine the interface it uses to emit the Cache-Control directives discussed above.

`expires_in`

This method sets the max-age directive, overwriting all others. You can pass it ActiveSupport::Duration and options such as public and must_revalidate, which will set the respective directives.

When would you want to use this? Typically, when you need to balance cache effectiveness and freshness. For example:

class ProductsController < ApplicationController
  def index
    # Set the response to expire in 15 minutes
    expires_in 15.minutes, public: true

    @products = Product.all
  end
end

This exemplifies the compromise you might make between the probability that a new product is added, changed, or removed in the course of 15 minutes and somebody seeing a stale response. Every application will have its own limitations here, but it's a good idea to have application monitoring like AppSignal for Ruby built into your production environment. This will enable you to query how often an endpoint is accessed by the same user vs the data manipulation frequency.

`expires_now` and `no_store`

This will set Cache-Control to no-cache and no-store, respectively. Look above for the implications.

`http_cache_forever`

http_cache_forever sets a max-age of 100 years internally and caches the response. It will consult stale?, though (see below), to determine if a fresh response should be rendered. You call it like this:

class StaticController < ApplicationController
  def about
    http_cache_forever(public: true) do
      # Your logic to render the about page goes here
      render :about
    end
  end
end

This renders the about view and allows intermediary shared caches to store it (because public is set in Cache-Control).

`fresh_when` and `stale?`

These methods are siblings and are both concerned with setting appropriate ETag and Last-Modified headers. Thus, they form the heart of Rails' conditional GET implementation. Let's look at each of them now:

class ArticlesController < ApplicationController
  def show
    @article = Article.find(params[:id])
    fresh_when(@article)
  end

  def index
    @articles = Articles.all
    fresh_when(@articles)
  end
end

The show action exhibits the simplest way to enable conditional GET requests on an endpoint. If it's passed an ActiveRecord instance, it will extract the update_at timestamp, reuse it as Last-Modified, and ETag will be computed from the record as a hex digest.

When working with relations, like in the index action, fresh_when will check for the most recent updated_at in the collection using the maximum method.

If desired, you can override this behavior using explicit options. These match the directives discussed above (the only outlier being the template option, which allows you to specify the template used to calculate the ETag digest). This is useful when your controller action uses a different template than the default.

In either case, before rendering a response, fresh_when will check if a stored response is still fresh and return a 304 in this case.

On the other hand, stale? is a predicate method that falls back to fresh_when internally and returns true or false based on its evaluation. You can use it to guard against expensive method calls, analogously to the above examples:

class ArticlesController < ApplicationController
  def show
    @article = Article.find(params[:id])

    expires_in 15.minutes

    if stale?(@article)
      @article.refresh_counters!
      render @article
    end
  end
end

In this example, since it uses the same internal semantics as fresh_when, it would automatically send a 304 Not Modified response unless the article is stale. If it is stale, though (i.e., if 15 minutes have passed since it was generated), the counters are refreshed and return a fresh response. Updating low-priority data in your responses only infrequently, based on a "timeout", is a typical use case.

The `etag` Class Method

How can caches, even private ones, deal with personalized information? The answer is that data identifying the session in some way has to be included in the ETag. This is exactly what the etag controller class method does: it provides the necessary information to differentiate between private responses to individual users.

Continuing with the example above, imagine that some users are administrators who are served "edit" buttons for the articles in the UI. You don't want that information to spill over to an anonymous user, so you can prevent that:

class ArticlesController < ApplicationController
  etag { current_user&.id }

  def show
    @article = Article.find(params[:id])
    fresh_when(@article)
  end

  def index
    @articles = Articles.all
    fresh_when(@articles)
  end
end

Assuming that current_user is a method returning the currently logged-in user, his/her id is now added to the ETag before digesting, preventing the leak of sensitive data to unauthorized visitors.

Takeaways

Given all we have learned above, do you feel confident adding HTTP caching to your controllers? I would cautiously assume that you still have some leftover anxiety regarding the leakage of sensitive data. But all in all, using Turbo Frames and personalizing a UI can provide some valuable insights.

Rigorously Decompose into Turbo Frames

If you are using Turbo in your frontend, you can leverage eager or lazy-loaded Turbo Frames. A lot of applications comprise personalized sections of the UI, while others do not. By detaching the non-personalized parts into separate endpoints that employ HTTP caching individually, you not only gain performance benefits but also a clearer application architecture.

Apply Personalized Bits of the UI After the Fact

Another way to deal with user-dependent data is to apply JavaScript after a page has loaded. This is only viable if the amount of personalized data on a page is small. In essence, you'd query an endpoint for a current user's data in JSON format, then use a Stimulus controller to apply it to the relevant bits of the UI.

Wrapping Up

In this post, we demystified HTTP caching. We looked at some basic concepts, cache layers, and configuration, including how to use the Cache-Control header and validation. We also examined the elegant solution that Rails provides in the form of the ActionController::ConditionalGet module.

Until next time, happy coding!

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

The Crumbling Codebase

julianrubisch — Thu, 11 Apr 2024 06:53:40 +0000

Does the following sound familiar?

🤔

Back when I extracted this module, it seemed like a good idea. What did I think I was doing?

🤹

The models in this namespace are so tightly coupled, it feels like I can't move them an inch. Where's Houdini when you need him?

🩺

The team that developed this feature is gone, and with them all the knowledge about it. Where do I start cleaning it up before I add more functionality?

If any of these quotes resonate with you, you are not alone. Here's a harsh truth: Over time things tend to degrade. Memory, structure, cohesion are all subject to decay and attrition.

I've covered the subject of entropy elsewhere, and why you cannot escape it. The real question is, if disorder is inevitable, why bother?

🤕 For one, it hurts. It slows you down and can directly make the difference between success and failure of your business.
💸 On the other hand, upkeep incurs a cost. This is often not directly quantifiable, but a hidden item in your payroll costs.

The tension between having to keep everything shipshape in order to stay agile, and the real, monetary cost it causes maneuvers many decision makers into a difficult situation. How many developer hours should we allocate to dealing with tech debt? How can we measure how well we are faring? What percentage of our opportunity costs is devoted to maintenance? Where do we even start?

Let me share the good news last: Attractor can help answer many of these questions:

a transparent scoring system allows you to track your progress as you're restoring order. You'll have data available to gauge the development.
alarm bells ring when a part of your codebase is degrading faster than the others. No more worries about "tech debt creep".
analysis tools identify the worst offending modules where repair has the highest impact on the health of your application. No more stabbing in the darkness of code complexity.

How To Reduce Tech Debt to Keep Your Ruby on Rails Application Effortlessly Adaptable

julianrubisch — Wed, 27 Mar 2024 21:20:28 +0000

Learn how the Second Law of Thermodynamics affects your codebase, and what tidying your workshop has to do with it.

Entropy, or Why the Pile in the Workshop Keeps Growing

Entropy measures the level of disorder or randomness within a system. It's a fundamental concept in physics that explains why things tend to move from order to disorder over time, without external intervention. Picture a workshop: this principle manifests as the inevitable clutter that accumulates---tools left out, materials strewn around, each item slightly out of place.

Just like in a workshop, in software development, particularly with Ruby on Rails, technical debt represents this drift towards disorder. It's the buildup of quick fixes and outdated code that, if not managed, makes our applications harder to adapt and maintain. Managing this technical debt is as crucial as keeping a workshop tidy for efficiency.

The Second Law of Thermodynamics and Your Codebase

The Second Law of Thermodynamics states that, in any closed system, entropy, or disorder, will always increase over time if no energy is applied to maintain order. This law, a cornerstone of physics, can be applied to software development as well. A codebase, much like any system, naturally tends towards disorder. Without deliberate effort to refactor, update, and clean up, it accumulates technical debt---outdated practices, redundant code, and inefficiencies.

A critical insight for every engineering manager and CTO can be extrapolated: This buildup is a fundamental principle at play. Just as energy must be invested to keep a system in order and counteract entropy, consistent effort is required to maintain and improve a codebase, keeping it efficient and adaptable.

Tidy Up Your Workshop: Strategies for Reducing Code Complexity

If we revisit the workshop metaphor from above, it becomes clear that once entropy kicks in, our tools become harder and harder to find. We have to pick up every gadget, look at it and decide where to put it. This is a tedious process that very closely resembles what we have to do to reduce tech debt and improve adaptability:

sift through classes for unnecessary coupling and blurred responsibilities
divide them into more fitting abstractions if applicable, and write tests to verify

But where do you start? This is where Attractor can help you with its approachable complexity visualizations and code vital signs.

But there's more. One epiphany that struck me while recently cleaning up my own workshop is: The solution to finding things is owning less stuff. So I went ahead and threw away any excess material and leftover components that I saved for "later use" (which never happened)---until my workbench was clean:

How does that translate to code? Well, one proxy metric to measure the amount of clutter is code complexity. Use it as a lens to find the most salient places in your codebase to clean up. It's the dust cover on that pile of junk over there---right in front of your favorite sonic screwdriver that you've been missing for so long.

What Can Attractor Do For You?

In a nutshell, Attractor covers three distinct use cases:

Ongoing Accompaniment of Development

This is the marquee scenario: By providing continuous reporting and flagging tech debt as it emerges, it helps establish a steady culture of grooming. You reap the profits in the form of a sustained development velocity 🚀.

That requires an already pretty tidy environment, though. It might be that you need help cleaning up first 👇.

Gradual Tech Debt Removal

Chances are, you went the "ship fast, clean up later" route. That's fair! It doesn't make much sense to polish an app before it makes money, I get it.

Slowly, though, you start to feel growing pain. Your domain model feels wrong in this spot, because you can't add an association here. This form over there feels clunky, but what can you do about it?

Attractor points you to the most painful spots to get a bird's-eye view of where to start weeding.

Whole-App Refactoring Guide

Maybe you're a consultant being tasked with tidying up the mess that others made. Don't fret!

Attractor helps you split up your refactoring endeavor into manageable chunks and spotlights the most powerful levers to get your app in shape again.

Full-Text Search for Ruby on Rails with Litesearch

julianrubisch — Wed, 28 Feb 2024 14:34:40 +0000

In this post, we'll turn to the last piece of the puzzle in LiteStack: Litesearch.

As an example, we will equip a prompts index page with a search bar to query a database for certain prompts. We will generate a couple of fake records to test our search functionality against.

Let's get to it!

What Is Litesearch?

Litesearch is a convenience wrapper built around FTS5, SQLite's virtual table-based full-text search module.

We'll dive into the mechanics a bit later. For now, we will assume that Litesearch is a Ruby module providing a simple API to perform text searches against a SQLite database. This works in standalone mode, but we will focus on the ActiveRecord integration, of course.

Configure the `Prompt` Model for Litesearch

The single addition we must make to our prompt model is a search index schema definition. To do this, we have to include the Litesearch::Model module in our model and call the litesearch class method to add fields to the schema:

  class Prompt < ApplicationRecord
    include AccountScoped
+   include Litesearch::Model

    # ...

+   litesearch do |schema|
+     schema.fields [:title]
+   end

    # ...
  end

You can also target associations like so, and change the tokenizer used for indexing:

litesearch do |schema|
  schema.field :account_name, target: "accounts.name"
  schema.tokenizer :porter
end

Note: Currently, ActionText fields are not supported.

Let's quickly try this out in the Rails console:

> Current.account = Account.first
> Prompt.search("teddy")
  Prompt Load (7.4ms)  SELECT prompts.*, -prompts_search_idx.rank AS search_rank FROM "prompts" INNER JOIN prompts_search_idx ON prompts.id = prompts_search_idx.rowid AND rank != 0 AND prompts_search_idx MATCH 'teddy' WHERE "prompts"."account_id" = ? ORDER BY prompts_search_idx.rank  [["account_id", 1]]
=>
[#<Prompt:0x0000000105f80fb0
  id: 1,
  title: "A cute teddy bear",
  prompt_image: <...>,
  account_id: 1,
  created_at: Fri, 12 Jan 2024 10:47:08.604031000 UTC +00:00,
  updated_at: Fri, 12 Jan 2024 10:47:41.321896000 UTC +00:00,
  content_type: "image/jpeg",
  search_rank: 1.0e-06>]

Remember to set Current.account, because our prompt model is scoped to an account, otherwise we get an empty result set.

Impressive! By changing only 4 lines of code, we already have a crude working version of full-text search.

Add a Typeahead Search Bar to Our Ruby on Rails Application

Next up, we'll combine a few of the techniques we've reviewed to implement snappy typeahead searching. Before we do that, though, let's generate more sample data. I will use the popular faker gem to do that:

$ bundle add faker --group development
$ bin/rails console

Drop into a Rails console and create 50 sample prompts. I'm re-using the first prompt's image data here. Also, note that I'm again setting the Current.account first.

> Current.account = Account.first
* 50.times do
*   Prompt.create(title: "a #{Faker::Adjective.positive} #{Faker::Creature::Animal.name}", content_type: "image/png", prompt_image: Prompt.first.prompt_image)
> end

To prepare our user interface for reactive searching, we will wrap the prompts grid in a Turbo frame. This frame will be replaced every time the search query changes.

  <!-- app/views/prompts/index.html.erb -->
  <h1>Prompts</h1>

+ <%= turbo_frame_tag :prompts, class: "grid" do %>
- <div id="prompts" class="grid">
    <% @prompts.each do |prompt| %>
      <%= link_to prompt do %>
        <%= render "index", prompt: prompt %>
      <% end %>
    <% end %>
+ <% end %>
- </div>

  <%= link_to "New prompt", new_prompt_path %>

The PromptsController needs to be updated to filter prompts if a query parameter is passed in:

  # app/controllers/prompts_controller.rb
  class PromptsController < ApplicationController
    # ...

    def index
      @prompts = Prompt.all
+
+     @prompts = @prompts.search(params[:query]) if params[:query].present?
    end

    # ...
  end

Next, let's rig up the search bar in the prompt index view. For this, we'll use a shoelace input component:

  <!-- app/views/prompts/index.html.erb -->
  <h1>Prompts</h1>

+ <section>
+   <sl-input name="search" type="search" placeholder="Search for a prompt title" clearable>
+     <sl-icon name="search" slot="suffix"></sl-icon>
+   </sl-input>
+ </section>

  <div id="prompts" class="grid">
    <% @prompts.each do |prompt| %>
      <%= link_to prompt do %>
        <%= render "index", prompt: prompt %>
      <% end %>
    <% end %>
  </div>

  <%= link_to "New prompt", new_prompt_path %>

To implement typeahead searching, we must add a bit of custom JavaScript to app/javascript/application.js:

  // app/javascript/application.js

  // Entry point for the build script in your package.json
  import "@hotwired/turbo-rails";
  import "./controllers";
  import "trix";
  import "@rails/actiontext";

  import { setBasePath } from "@shoelace-style/shoelace";

  setBasePath("/");
+
+ document
+   .querySelector("sl-input[name=search]")
+   .addEventListener("keyup", (event) => {
+     document.querySelector(
+       "#prompts"
+     ).src = `/prompts?query=${encodeURIComponent(event.target.value)}`;
+   });

This tiny JavaScript snippet does little more than place a keyup listener on our search field, and update the Turbo Frame's src attribute afterward. The input's value is added as the query parameter. Turbo Frame's default behavior performs the rest of the magic: reloading when the src attribute changes, with the updated content fetched from the server.

Here's what this looks like.

Excursus: Highlighting Search Results Using a Turbo Event in Rails

Currently, Litesearch doesn't feature a native highlighting solution like pg_search, but it is pretty easy to build this ourselves using the before-frame-render event:

  // Entry point for the build script in your package.json
  import "@hotwired/turbo-rails";
  import "./controllers";
  import "trix";
  import "@rails/actiontext";

  import { setBasePath } from "@shoelace-style/shoelace";

  setBasePath("/");

  document
    .querySelector("sl-input[name=search]")
    .addEventListener("keyup", (event) => {
      document.querySelector(
        "#prompts"
      ).src = `/prompts?query=${encodeURIComponent(event.target.value)}`;
    });

+ document
+   .querySelector("turbo-frame#prompts")
+   .addEventListener("turbo:before-frame-render", (event) => {
+     event.preventDefault();
+
+     const newHTML = event.detail.newFrame.innerHTML;
+
+     const query = document.querySelector("sl-input[name=search]").value;
+     if (!!query) {
+       event.detail.newFrame.innerHTML = newHTML.replace(
+         new RegExp(`(${query})`, "ig"),
+         "<em>$1</em>"
+       );
+     }
+
+     event.detail.resume();
+   });

This leverages a nifty, somewhat hidden Turbo feature: intercepting rendering. The Turbo before-render and before-frame-render events support pausing rendering and mangling returned HTML from the server. Here, we use this to wrap each occurrence of a search query in an <em> tag.

Under the Hood: Litesearch for Ruby on Rails Explained

We've covered the basics of activating and configuring Litesearch for your LiteStack-powered Ruby on Rails application. As you might have guessed, there's a lot more potential hidden here.

So let's briefly examine how Litesearch wraps around and leverages SQLite's built-in full-text search module, FTS5.

Virtual Tables in SQLite

First, let's discuss the notion of virtual tables in SQLite. Since there's no direct counterpart in the PostgreSQL or MySQL realm, it pays off to learn about these.

From the vantage point of a user issuing an SQL statement against the database, a virtual table is a transparent proxy that adheres to the interface of a table. In the background, however, every query or manipulation invokes a callback of the virtual table structure instead of writing to disk.

In short, a virtual table is something you reach for when you want to access "foreign" data without leaving the domain of your database connection. Apart from full-text search, other examples include geospatial indices or accessing a different file format, such as CSV.

SQLite's FTS5 Full-Text Search Extension

At its core, SQLite's full-text search engine is a virtual table.

The table definition used by Litesearch in ActiveRecord mode looks like this:

"CREATE VIRTUAL TABLE #{name} USING FTS5(#{col_names}, content='', contentless_delete=1, tokenize='#{tokenizer_sql}')"

name is the index name (it defaults to "#{table_name}_search_idx"), and col_names are the fields we set in our Litesearch schema definition.

We will now briefly look at tokenizers.

Tokenizers

To allow for efficient indexing, a full-text search engine employs a helper utility to split the payload into tokens: a tokenizer. FTS5 has three built-in tokenizers you can choose from:

unicode61 (default): All punctuation and whitespace characters (i.e. ",", "." etc.) are considered separators. Text is split at those characters, and the resulting list of connected characters (usually, words) are the tokens. In the wild, you might encounter the remove_diacritics option. This option specifies how to treat glyphs added to letters, like "á", "à", etc. The default is to remove these "diacritics", so these characters are regarded as equivalent.
ascii: Similar to unicode61, but all non-ASCII characters are always considered token characters. There is no remove_diacritics option.
porter: A tokenizer that employs porter stemming for tokenization. This essentially means that you can do similarity searches, i.e., "search", "searchable", and "searching" will be considered related.

FTS5 Search Interface

To enable a convenient experience, Litesearch exposes a search class method. Essentially, this method joins the model's table to the associated search index and issues a MATCH query. Results are then ordered according to the search rank and returned:

def search(term)
  self.select(
    "#{table_name}.*"
  ).joins(
    "INNER JOIN #{index_name} ON #{table_name}.id = #{index_name}.rowid AND rank != 0 AND #{index_name} MATCH ", Arel.sql("'#{term}'")
  ).select(
    "-#{index_name}.rank AS search_rank"
  ).order(
    Arel.sql("#{index_name}.rank")
  )
end

Currently, Litesearch doesn't expose more of FTS5's search syntax, but you can learn more about it in FTS5's documentation.

Up Next: Deployment and Monitoring of your LiteStack-powered Ruby on Rails Application

In this post, we discovered Litesearch, the full-text search engine built into LiteStack. We learned how to configure an ActiveRecord model to expose search fields and other options to an SQLite text search index.

We then flexed our Hotwire muscles to build a simple reactive search interface into our UI.

Finally, we explored some of the inner workings of full-text search in SQLite to get a better understanding of what powers it, its benefits, and its limitations.

Our upcoming article marks the conclusion of this seven-part journey through LiteStack, the unique and powerful way to build a single-machine Rails application. We will deal with deployment, reliability, and monitoring using built-in and external tools.

Until then, happy coding!

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

Configuring Incoming Webhook Queues in Bullet Train

julianrubisch — Fri, 16 Feb 2024 17:11:55 +0000

Attractor is a pretty background-job intensive app. If you think about it, every commit's changes have to be analyzed, and the results stored, to keep track of code quality and emerging tech debt.

Since it's based on Bullet Train, it makes sense to handle most of these workloads in incoming webhooks. Broadly speaking, there are three groups of incoming webhooks at work:

webhook handlers for processing code analytics data being reported back from sandbox containers,
webhook handlers for webhooks sent from GitHub (e.g. when a new pull request is created),
everything else, e.g. webhooks coming from Paddle, my payment provider.

Webhook Processing

Each incoming webhook in Bullet Train is processed by a controller that is created by super scaffolding.

It might look like this:

class Webhooks::Incoming::SandboxWebhooksController < Webhooks::Incoming::WebhooksController
  before_action :authenticate_token!

  def create
    Webhooks::Incoming::SandboxWebhook.create(data: JSON.parse(request.body.read))
      .process_async
    render json: {status: "OK"}, status: :created
  end

  # ...
end

The created model file contains the processing logic:

class Webhooks::Incoming::SandboxWebhook < ApplicationRecord
  include Webhooks::Incoming::Webhook

  def process
    # logic goes here
  end
end

The actual processing is done by a generic Webhooks::Incoming::WebhookProcessingJob that's part of Bullet Train and calls back to this process method. In other words, in a vanilla Bullet Train app, Sidekiq is responsible for working off your incoming webhooks.

So, let's look at the respective sidekiq.yml file:

:concurrency: 5
staging:
  :concurrency: 5
production:
  :concurrency: 5
:queues:
  - critical
  - default
  - mailers
  - low
  - action_mailbox_routing

There are 5 Sidekiq queues configured. A pretty nasty issue is hidden here in plain sight, though: All incoming webhooks are processed in the default queue.

Dynamically Configuring the Webhook Queue

Why is this a problem? Let's walk through a scenario where a new customer signs up.

she authenticates the Attractor GitHub app, and connects two pretty large repositories,
she enters her credit card information and wants to conclude the sign-up,
nothing happens, she is stuck.

What's happening here? It took me a while to find out.

As pointed out above, all incoming webhooks are processed in the default queue, which in this case means:

all analysis jobs (which can be hundreds or even thousands) are queued up there,
the one incoming webhook responsible for processing the payment, too - right at the bottom.

In other words, the payment would be processed only after all analysis jobs (and not only hers, maybe a couple of other customers did sign up simultaneously) have concluded. An unbearable situation, to have a customer hanging in a state of uncertainty whether her payment did successfully activate her subscription of Attractor.

To remedy this, I could have changed the sign up flow to first require potential customers to check out, then allow them to connect the GitHub app. That would have been a pretty large effort, though, so I opted to try something else.

We can reopen the Webhooks::Incoming::WebhookProcessingJob and have the queue_as method decide dynamically where to queue the webhook it's meant to process:

Webhooks::Incoming::WebhookProcessingJob.queue_as do
  webhook = arguments.first

  case webhook
  when Webhooks::Incoming::PaddleWebhook
    :critical
  when Webhooks::Incoming::SandboxWebhook
    :low
  else
    :default
  end
end

The only remaining question was where to put this small monkey patch. Placing it into an initializer didn't work, because your app's constants (such as the Webhooks::Incoming::WebhookProcessingJob class) haven't loaded at this time.

So the only option is to run it after the app has finished initializing, i.e. in an after_initialize block in your config/application.rb:

require_relative "boot"

require "rails/all"

# ...

module MyApp
  class Application < Rails::Application
    # more config

    config.after_initialize do
      Webhooks::Incoming::WebhookProcessingJob.queue_as do
        webhook = arguments.first

        case webhook
        when Webhooks::Incoming::PaddleWebhook
          :critical
        when Webhooks::Incoming::SandboxWebhook
          :low
        else
          :default
        end
      end
    end
  end
end

With this tweak, all webhooks coming in from the code analysis sandbox are placed in the low job queue, keeping others in the default one. Subsequently, when a webhook comes in from GitHub indicating a new pull request, it is processed before any potentially waiting SandboxWebhooks.

Even more importantly, incoming webhooks from Paddle are placed in the critical queue, making sure subscription changes are always processed first.

Thanks to Kasper Timm Hansen for pointing me in the right direction! 🙏

Speed Up Your Ruby on Rails Application with LiteCache

julianrubisch — Wed, 31 Jan 2024 15:00:00 +0000

In this series, we have looked at the "musts" (databases) and "shoulds" (asynchronous jobs, websockets) of a web application. Now we turn to one of the "coulds" (that is nonetheless recommended for scaling businesses): caching. In particular, we mean caching HTML fragments and other snippets of data, as referred to in Rails Guides. We are not concerned with HTTP or SQL query caching.

In this part, we'll see how to speed up our Rails app using LiteCache. But first, we'll touch on Russian doll caching and how it comes in handy.

Russian Doll Caching in Ruby on Rails

At first glance, it might seem counterintuitive to employ the same technology for the main database as well as the cache. After all, what speed improvements will that engender? This is where a technique called "Russian doll caching" comes in, which we will briefly shine a light on now.

In one sentence, the gist of this caching approach boils down to:

The fastest database query is no query.

What do I mean by that? Let's turn to the Rails Guides definition of fragment caching first:

Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in.

In other words, when you wrap a piece of view code in a cache helper, the rendered HTML fragment is put into the cache store, with a unique, expirable cache key. This key is constructed to expire whenever either the entities of which the cache key is composed, or the underlying view template, change.

An Example

That may sound very unwieldy. Let's look at an example in the context of our app:

  <!-- app/views/prediction/_prediction.html.erb -->

+ <% cache prediction do %>
    <div id="<%= dom_id(prediction) %>">
      <%= turbo_stream_from prediction %>

      <% if prediction.prediction_image.present? %>
        <%= image_tag prediction.data_url %>
      <% else %>
        <sl-spinner style="font-size: 8rem;"></sl-spinner>
      <% end %>
    </div>
+ <% end %>

Here, we have wrapped our _prediction partial in a cache block. This generates a cache key in the fashion of:

view path                     template digest                  identifier
|                             |                                |
views/predictions/_prediction:9695008de61cf58325bbf974443f54bc/predictions/3

As we can see, this key comprises:

The view path, containing the cache block.
A digest of the template (i.e., if you change the partial, the cache entry will be invalidated).
A unique identifier — in other words, our prediction — see the ActiveRecord documentation.

Stored with this key is a timestamp (the updated_at column of our prediction) and the HTML fragment, in our case also the complete image's data URL. Whenever this partial is rendered again, and a matching cache key is found, rendering is bypassed. Instead, the stored HTML is returned.

Making Use of Russian Doll Caching

What's that "Russian doll" piece about, though? To answer this, let's jump a layer higher into a view that renders this _prediction partial:

  <!-- app/views/prompts/_prompt.html.erb -->
+ <% cache prompt do %>
    <sl-card class="card-header card-prompt" id="<%= dom_id prompt %>">
      <div slot="header">
        <!-- header content omitted -->
      </div>

      <%= turbo_stream_from :predictions %>
      <div class="grid">
        <div>
          <%= image_tag prompt.data_url %>
        </div>
        <div id="<%= dom_id(prompt, :predictions) %>">
          <%= render prompt.predictions %>
        </div>
      </div>

      <div slot="footer">
        <%= prompt.description.presence || "No Description" %>
      </div>
    </sl-card>
+ <% end %>

We can apply the same technique to the _prompt partial, which, in turn, renders a _prediction partial for every prediction associated with it. This will result in a single HTML fragment comprising all the child fragments. We just saved one SQL query for each prediction!

There's a catch, though: When the list of predictions associated with a prompt changes (for example, a new one is added), the top fragment doesn't know about this and will serve stale content (without the newly added image).

In other words, we have to expire its cache key and construct a fresh fragment. This is where the timestamp stored with each cache entry comes in handy. We can invalidate the cache simply by updating this timestamp. In ActiveRecord, luckily, there's a shorthand for this:

  # app/models/prediction.rb
  class Prediction < ApplicationRecord
    # callbacks omitted

-   belongs_to :prompt
+   belongs_to :prompt, touch: true

    # methods omitted
  end

Using the touch flag on the belongs_to association, every time a child record (a prediction) is updated, deleted, or added, the updated_at timestamp of the parent (a prompt) is refreshed. This marks the cache fragment as stale, and it is reconstructed upon the next render cycle.

The term "Russian doll caching" in this context refers to the fact that all the valid child fragments can still be pulled from the cache, thus speeding up the rendering process.

Now that we have reviewed how fragment caching works and what benefits it yields, let's discuss how to enable and configure LiteCache.

LiteCache Configuration in Rails

In config/environments/development.rb, add this configuration snippet:

config.cache_store = :litecache, {
  path: Litesupport.root.join("cache.sqlite3")
}

This will resolve the root database path depending on your environment (in this case, db/development) and create a cache.sqlite3 file there. There are more configuration options worth considering, though:

size: the total allowed size of the cache database (the default being 128MB)
expiry: cache record expiry in days (the default is one month)
mmap_size: how large a portion of the database to hold in memory (default: 128MB)
min_size: the minimum size of the database's journal (default: 32KB)
sleep_interval: duration of sleep between cleanup runs (default: one second)
metrics: boolean flag to indicate whether to gather metrics

The ones you will likely want to tweak to your liking are size, expiry, and (potentially) sleep_interval.

Note: To enable caching in development, you have to run:

$ bin/rails dev:cache

Although LiteCache has many benefits, it comes with some drawbacks too. Let's first look at some optimizations, and then a few of LiteCache's limitations.

Optimizations and Limitations of LiteCache for Your Ruby App

LiteCache connects to the SQLite database in a way that's optimized for use as a cache store. First, it's important to reiterate that LiteCache is configured to use a separate cache database, so all these optimizations only affect an isolated environment.

With this disclaimer in place, let's look at how LiteCache optimally utilizes SQLite.

First, LiteCache sets the pragma statement synchronous to 0, so there is no sync after a commit to the database. This results in a tremendous speedup at the expense of data safety. In very rare cases, such as a power loss or operating system crashes, data loss might occur. However, considering that cache entries are seen as ephemeral in most cases, this is a sensible tradeoff. Needless to say, you can also override this setting in your configuration.

LiteCache also uses a least recently used (LRU) eviction policy with a special index, but it delays updating it. Instead, it will buffer the updates in memory, and flush them as a single transaction every few seconds.

What about limitations? At the time of writing this article, one crucial piece of the ActiveSupport::Cache interface isn't implemented yet: The ability to do multiple reads, writes, and deletes against the cache database. Why is that so important? Because other cache backends like Redis demonstrate how significant speedups can be achieved by batching these operations. Indeed, the implicit performance gain built into rendering a collection of partials is the most impressive feat of Rails fragment caching.

Speaking of performance speed, let's now quickly look at some benchmarks before we wrap up.

Benchmarks: LiteCache Vs. Redis

The benchmarks for LiteCache are impressive, with a small caveat. While LiteCache outperforms a local Redis installation for every read operation, it seems like there's still room for improvement, especially for large write payloads.

Considering the increased benefits of caching large HTML fragments, this is a worthwhile limitation that will hopefully be tackled in the future.

Up Next: Built-In Full-Text Search with LiteSearch

In this post, we illuminated Russian doll caching as a technique to speed up Rails applications by avoiding unnecessary database calls.

Through practical examples, we’ve seen how nested cache fragments operate in harmony — each layer independent, yet interconnected — thus ensuring efficient rendering.

We also delved into the practicalities of configuring LiteCache to your liking and looked at important built-in optimizations. With that in mind, the missing support for multiple read and write operations is bearable, and perhaps is a feature that might soon arrive on the horizon.

In the next post of this series, we will take a tour through the latest addition to LiteStack: A SQLite-based full-text search engine called LiteSearch.

Until then, happy coding!

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

Divergent Change

julianrubisch — Fri, 19 Jan 2024 21:47:02 +0000

One of the lesser known code smells, Divergent Change is one of the strongest multipliers of tech debt. Fixing it has high leverage, so we'll explore how to spot and remediate it.

What Is Divergent Change?

Divergent Change belongs to the code smells class of Change Preventers. As such, it is a major impediment for your development velocity, which is why it should be treated swiftly when you spot it.

In one sentence, you are likely dealing with this smell if one class changes often, but for unrelated reasons. Another hint is the necessity to change a class in multiple places when altering it or a dependency. It is the mirror-universe counterpart of Shotgun Surgery, in which many classes change for the same reason.

I am going to demonstrate this with an Alert ViewComponent:

class AlertComponent < ViewComponent::Base
  def initialize(state:, message:)
    @state = state
    @message = message
  end

  def color
    {
      success: "green",
      info: "blue",
      error: "red"
    }
  end

  def icon
    {
      success: "check",
      info: "info",
      error: "exclamation"
    }
  end

  def message
    prefix = case state
      when :success then "YIPPEE!"
      when :info then "Listen up:"
      when :error then "Oh Dear."
    end

    "#{prefix} #{@message}"
  end
end

Suppose we want to add a new type of status, warning, we now have to edit three individual methods. This example is trivial, but imagine these methods are actually spread out between several modules. Suddenly a single change turns into a bug chasing contest.

What Makes Divergent Change So Harmful?

Every "change preventer" is malign, but Divergent Change is often harder to spot than its colleagues. That's especially the case if a class' behavior is scattered between various modules, for example Rails' ActiveSupport concerns.

That's why extracting a concern solely to include it in a single class - albeit reducing perceived complexity - is itself considered a smell. It disguises that a class doesn't follow the Single Responsibility Principle, and should be better treated with other techniques, for example composition.

Often, divergent change starts out pretty innocent: "Oh, I'll just use a hash as a lookup table", or "one case statement won't hurt". A simple enough choice in the YAGNI spirit - fair enough. The problem is one of setting an example, i.e. culture. The next developer who needs to program a feature in this class sees the pattern and does the next best thing under deadline pressure - add another conditional. Thus, gradually the class becomes a God Class with far too many concerns mixed into its responsibility - another way of circumscribing Divergent Change. What's worse, such a static structure of conditionals and constants makes it hard to refactor and employ a behavioral design pattern like Strategy or Visitor, which allow to dynamically attach behavior at runtime.

How Do I Detect Divergent Change in My Codebase?

In contrast to Shotgun Surgery, which is easier to spot (you just have to grep a certain method or class in your codebase), Divergent Change is a master of camouflage. Chances are you already have many such offenses in your codebase which are hiding in plain sight. Let's look at a strategy to detect it by first narrowing down the potential offenders, then looking for specific symptoms.

Conveniently, Attractor already equips you with the relevant code metrics to filter your classes in search of Divergent Change:

Churn (how often a class has changed)
Complexity (how hard it is to understand what the class is doing)

If you restrict your search to those files exhibiting both a high churn count and complexity, you are likely to come across a couple of God Classes that display the symptoms outlined above.

That's of course only narrowing down the search space. We have to do a bit of detective work to tease out the offenses. Here are a few indicators that you should be familiar with:

Looking through the version control log, you see many changes that aren't related to each other
If you skim through these commits, you notice that more than one class or module was modified
The class has a lot of control flow logic (i.e. conditionals)

How Do I Treat Divergent Change?

As a general heuristic, you should strive that each class only serves one purpose. Ideally you can describe what it does in a single sentence. That, of course, is only a very general guideline.

I will start out with a simple refactoring that introduces composition by extracting a class (hierarchy). Bear with me, I'm deliberately taking this step by step.

class Alert
  def initialize(message:)
    @message = message
  end
end

class SuccessAlert < Alert
  def color = "green"
  def icon = "check"
  def message = "YIPPEE! #{@message}"
end

class InfoAlert < Alert
  def color = "blue"
  def icon = "info"
  def message = "Listen up: #{@message}"
end

class ErrorAlert < Alert
  def color = "red"
  def icon = "exclamation"
  def message = "Oh Dear. #{@message}"
end

class AlertComponent < ViewComponent::Base
  VALID_ALERTS_BY_STATE = {
    success: SuccessAlert,
    info: InfoAlert,
    error: ErrorAlert
  }

  def initialize(state:, message:)
    @state = VALID_ALERTS_BY_STATE[state].new(message: message)
  end

  delegate :color, :icon, :message, to: :state
end

Note how this simple refactoring has already reduced the changes that have to be made to add a new type of alert from 3 to 2: Instead of altering 3 methods, I now only have to add one class, and add it to the VALID_ALERTS_BY_STATE hash.

We can do better though. We harness Rails' developers dearest paradigm - Convention over Configuration - to simplify the class lookup:

class AlertComponent < ViewComponent::Base
  def initialize(state:, message:)
    @state = "#{state.classify}Alert".safe_constantize.new(message: message)
  end

  delegate :color, :icon, :message, to: :state
end

Now we've also gotten rid of the lookup hash and simply assume that the class name adheres to a certain naming scheme. Note that both these approaches still require that you know which are valid states to pass into the component. As we will see in a moment, there's a yet better way to go about this.

How Can I Prevent It?

There are two SOLID principles that should be your yardsticks here: The Open/Closed Principle, and Dependency Inversion.

Open/Closed Principle

Paraphrased a bit, it goes like this:

Software entities should be open for extension, but closed for modification.

We have seen in the above example that adding a new type of alert would have meant tinkering with the internals of AlertComponent quite a bit. You should always strive to see classes as "finished" entities and not interfere with their implementation if possible. Of course, this requires discipline and often quick iteration in the product development lifecycle exacerbates the situation.

With refactorings like the above we have already improved the situation. Still, there's a bit of concern regarding the alert class lookup: If the naming convention was ever to change, we'll have to touch a lot of classes, again. It would be better if the AlertComponent didn't have to bother with that at all and were extensible by design. This is where the next principle comes in.

Dependency Inversion

In short, this principle demands that the software inverts control. Lower level modules (our Alert classes) should be passed into higher level modules (our AlertComponent) instead of the latter depending on the former. Rather, they should be treated as abstractions. What does this mean? Let's take a look:

class AlertComponent < ViewComponent::Base
  def initialize(alert:)
    @alert = alert
  end

  delegate :color, :icon, :message, to: :alert
end

Now the AlertComponent class is completely decoupled. We have inverted control, i.e. the component simply relies upon the passed in alert to understand color, icon, and message. It would be called like this:

render AlertComponent.new(alert: SuccessAlert.new(message: "You have successfully inverted control"))

Notably, the component now isn't concerned with adding a new type of alert at all anymore. All we'd have to do is implement it as a class and inject it:

class WarningAlert < Alert
  def color = "yellow"
  def icon = "triangle-exclamation"
  def message = "Yikes. #{@message}"
end

render AlertComponent.new(alert: WarningAlert.new(message: ""))

References

Stream Updates to Your Users with LiteCable for Ruby on Rails

julianrubisch — Wed, 10 Jan 2024 14:00:00 +0000

So far in this series, we have been exploring the capabilities of SQLite for classic HTTP request/response type usage. In this post, we will push the boundary further by also using SQLite as a Pub/Sub adapter for ActionCable, i.e., WebSockets.

This is no small feat: WebSocket adapters need to handle thousands of concurrent connections performantly. The emergence of alternatives to ActionCable — read AnyCable — bears witness to the fact that this is a pressing concern for modern web applications. We'll take a look at how SQLite performs under these conditions.

But first, let's set up our app to broadcast streaming updates to users via Turbo Streams.

Configure Your Ruby on Rails App to Use LiteCable for Websockets

Configuring your application to use LiteCable for WebSocket connections is as easy as specifying the adapter in config/cable.yml:

development:
  adapter: litecable

test:
  adapter: test

staging:
  adapter: litecable

production:
  adapter: litecable

Preparing Our Rails App for Live Updates

Before we dive deep into how to broadcast model updates using Turbo Rails, we need to rework the mechanics of creating a prediction.

First, we'll create an empty prediction in GenerateImageJob to display a placeholder in our _prompt partial. This has the added benefit of forwarding the actual prediction's SGID to the webhook. Note, though, that we also have to pass the account's SGID, because the incoming webhook doesn't have any session information about the currently active user.

  # app/jobs/generate_image_job.rb

  class GenerateImageJob < ApplicationJob
    include Rails.application.routes.url_helpers

    queue_as :default

    def perform(prompt:)
+     empty_prediction = prompt.predictions.create

      model = Replicate.client.retrieve_model("stability-ai/stable-diffusion-img2img")
      version = model.latest_version
      version.predict({prompt: prompt.title, image: prompt.data_url},
        replicate_rails_url(host: Rails.application.config.action_mailer.default_url_options[:host],
-         params: {sgid: prompt.to_sgid.to_s}))
+         params: {prediction: empty_prediction.to_sgid.to_s,
+         account: prompt.account.to_sgid.to_s}))
    end
  end

In parallel, in our ReplicateWebhook, we can locate and simply update the prediction. Note that we have to set the Current.account because Prompt is scoped to an account and would otherwise end up empty (due to the way AccountScoped is set up).

  # config/initializers/replicate.rb

  class ReplicateWebhook
    def call(prediction)
      query = URI(prediction.webhook).query

-     sgid = CGI.parse(query)["sgid"].first
+     prediction_sgid = CGI.parse(query)["prediction"].first
+     account_sgid = CGI.parse(query)["account"].first

-     prompt = GlobalID::Locator.locate_signed(sgid)
+     located_prediction = GlobalID::Locator.locate_signed(sgid)
+     Current.account = GlobalID::Locator.locate_signed(account_sgid)

-     prompt.predictions.create(
+     located_prediction.update(
        prediction_image: URI.parse(prediction.output.first).open.read,
        replicate_id: prediction.id,
        replicate_version: prediction.version,
        logs: prediction.logs
      )
    end
  end

This change entails that the created prediction is empty, i.e., has no prediction image (obviously). Let's cater for this by adding a conditional to our _prompt.html.erb partial. When the image is missing, we display a spinner:

  <!-- app/views/prompts/_prompt.html.erb -->

  <p>
    <strong>Generated images:</strong>
    <% prompt.predictions.each do |prediction| %>
+     <% if prediction.prediction_image.present? %>
        <%= image_tag prediction.data_url %>
+     <% else %>
+       <sl-spinner style="font-size: 8rem;"></sl-spinner>
+     <% end %>
    <% end %>
  </p>

Great, we're done preparing our app to deliver live updates. Let's implement Turbo-Rails model broadcasts to finish this proof of concept.

Delivering Prediction Updates Live with Turbo-Rails

To test the WebSocket capabilities of LiteStack, we are going to use Turbo::Broadcastable. We'd like to show the spinner and the generated image once it has been created.

The way to do that is quite idiomatic: We tie this to after_create_commit and after_update_commit model callbacks invoking one of Turbo::Broadcastable's broadcast methods. Before we can do that, though, let's separate out a model partial for Prediction:

<!-- app/views/predictions/_prediction.html.erb -->
<%= turbo_stream_from prediction %>

<div id="<%= dom_id(prediction) %>">
  <% if prediction.prediction_image.present? %>
    <%= image_tag prediction.data_url %>
  <% else %>
    <sl-spinner style="font-size: 8rem;"></sl-spinner>
  <% end %>
</div>

Observe that I added a turbo_stream_from tag to the partial, containing the stream identifier and subscribing to the channel. We can now simply call render from the prompt partial and add another turbo_stream_from to listen for changes to the prediction list:

  <!-- app/views/prompts/_prompt.html.erb -->

  <p>
    <strong>Generated images:</strong>
-   <% prompt.predictions.each do |prediction| %>
-     <% if prediction.prediction_image.present? %>
-       <%= image_tag prediction.data_url %>
-     <% else %>
-       <sl-spinner style="font-size: 8rem;"></sl-spinner>
-     <% end %>
-   <% end %>
+   <%= turbo_stream_from :predictions %>
+   <div id="<%= dom_id(prompt, :predictions) %>">
+     <%= render prompt.predictions %>
+   </div>
  </p>

Now we're ready to set up model broadcasts. In the Prediction class, we add two model callbacks, invoking two Turbo Stream actions.

  # app/models/prediction.rb

  class Prediction < ApplicationRecord
+   include ActionView::RecordIdentifier

+   after_create_commit -> { broadcast_append_later_to :predictions,
+     target: dom_id(prompt, :predictions) }
+   after_update_commit -> { broadcast_replace_later_to self }

    belongs_to :prompt

    def data_url
      encoded_data = Base64.strict_encode64(prediction_image)

      "data:image/png;base64,#{encoded_data}"
    end
  end

What's Happening Here?

First, when a prediction is created, we append it to the predictions list. This will show our loading spinner once GenerateImageJob has run.

Then, every update to the record will trigger a replace of the prediction partial. Once the prediction is updated in ReplicateWebhook, the image returned from Replicate displays.

Here's what this looks like - note that I'm using Shoelace components for styling purposes.

Benchmarks: LiteCable Vs. Redis

So far, this article has shown that it's possible to run ActionCable with LiteCable as its adapter. This is a nice proof of concept, but we're here to check how LiteStack compares to other adapters as well.

Luckily, the official LiteStack benchmarks include measurements for LiteCable against Redis, which I am going to quote here.

Here's a small but important caveat: All these measurements were performed on the same machine. In typical production setups with managed Redis, you'll have to factor in additional network latency.

Let's look at the requests per second metric first. This captures how many Pub/Sub requests the Redis and SQLite processes are able to serve.

Requests	Redis requests/second	LiteStack requests/second
1,000	2611	3058
10,000	3110	5328
100,000	3403	5385

Note that LiteStack is able to process more requests per second, but tapers off with higher loads. Though not representative, this might be an issue for loads of 1M requests and beyond — but that's when you'll typically reach for faster solutions like AnyCable over stock ActionCable anyway.

Furthermore, there are some latency tests included in the benchmarks.

Requests	Redis p90 Latency	LiteStack p90 Latency	Redis p99 Latency	LiteStack p99 Latency
1,000	34	27	153	78
10,000	81	40	138	122
100,000	41	36	153	235

Allowing for some inaccuracy of measurement, both perform equivalently in this regard, maybe with the exception of the 99 percentile. Here, SQLite's locking model interferes with the amount of concurrent requests.

Again keep in mind, though, that you'll have to add a couple of milliseconds of latency once Redis runs on a different machine (LiteCable always runs on the same machine by design).

Limitations of SQLite for Rails

It is fair to assume that once you hit a certain level of Pub/Sub activity, you'll reach the ceiling of what's possible with a single SQLite database. That's the moment when you'll have to think about sharding, and here other technologies like Redis have a head start — though it will be interesting to see what LiteFS will have to offer.

Continuous monitoring of your app's WebSocket performance metrics using tools like AppSignal is your friend here. Reusing the ActionCable consumer on the client side is also advisable, as it will prevent wasting Pub/Sub connections.

LiteCable is tailored for vertical scaling by a tight integration of components. If you extract maximum performance from the SQLite engine, the limits of this approach are pushed a lot further. Once you observe that your latencies start to explode, though, I would suggest researching options like AnyCable, which inherently provide better strategies for horizontal scaling.

Up Next: Speed Up Rails App Rendering with LiteCache

In this post, we explored using SQLite as a Pub/Sub adapter for ActionCable to enable real-time updates in a Rails application via WebSockets. Configuring LiteCable was straightforward, requiring just a simple adapter specification. Leveraging Turbo::Broadcastable model callbacks made our implementation clean, tying broadcasts to creation and updates.

Though powerful, LiteCable is not designed to scale across multiple processes or servers. But for single-machine deployments, it unlocks real-time features in Rails without requiring a separate Redis instance.

Our next post will look at the next puzzle piece in LiteStack: the ActiveSupport cache store it provides. We'll test out how it can help us to lower server response times, and look at some benchmarks again.

See you then!

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

Handle Incoming Webhooks with LiteJob for Ruby on Rails

julianrubisch — Wed, 22 Nov 2023 15:18:01 +0000

In parts one and two of this series, we only dealt with the pure CRUD aspects of using SQLite as a production database.

In this post, we will explore the world of queue mechanisms, using SQLite as the pub/sub adapter for ActiveJob.

Let's make use of LiteJob to handle incoming webhooks in our Rails application.

Our Ruby on Rails Use Case

Our use case is the image generation that we are currently doing synchronously in the PromptsController:

model = Replicate.client.retrieve_model("stability-ai/stable-diffusion-img2img")
version = model.latest_version
version.predict({prompt: prompt_params[:title], image: @prompt.data_url}, replicate_rails_url)

Clearly, there are some long-running processes here that should be deferred to a background job: the loading of the model, and the prediction itself.

Configuration

In your environment configuration files, ensure you reference LiteJob as the queue adapter:

# config/environments/development.rb
# config/environments/production.rb
Rails.application.configure do
  # ...

  config.active_job.queue_adapter = :litejob

  # ...
end

Now we're all set to continue our investigation. Don't forget to restart your development server, though!

If you like, you can add more ActiveJob configuration in config/litejob.yml — for example, queue priorities:

queues:
  - [default, 1]
  - [urgent, 5]
  - [critical, 10, "spawn"]

Please refer to the README for further details.

That's set up, so let's move on to generating our images asynchronously.

Generating Images Asynchronously in Our Ruby on Rails Application

We'll start by scaffolding our job with the usual Rails generator command:

$ bin/rails g job GenerateImage

Let's move the image generation code from PromptsController into the perform method of this job:

class GenerateImageJob < ApplicationJob
  include Rails.application.routes.url_helpers

  queue_as :default

  def perform(prompt:)
    model = Replicate.client.retrieve_model("stability-ai/stable-diffusion-img2img")
    version = model.latest_version
    version.predict({prompt: prompt.title, image: prompt.data_url}, replicate_rails_url(host: Rails.application.config.action_mailer.default_url_options[:host]))
  end
end

Note that we have to include the URL helpers module here to access replicate_rails_url (as opposed to controllers, where this happens automatically). Furthermore, we also need to explicitly specify the host — we grab it off ActionMailer's default_url_options, in this case. Look at Andy Croll's excellent 'Use Rails URL helpers outside views and controllers' post for more sophisticated uses.

To make this work with the incoming webhook, make sure you also reference your ngrok URL in your app's configuration:

# config/environments/development.rb
config.action_mailer.default_url_options = { host: "YOUR_NGROK_URL", port: 3000 }

As the final step on the requesting side of our call to Replicate, we have to actually call the job from PromptsController:

  # app/controllers/prompts_controller.rb

  def create
    # ...
-   model = Replicate.client.retrieve_model("stability-ai/stable-diffusion-img2img")
-   version = model.latest_version
-   version.predict({prompt: prompt_params[:title],
-     image: @prompt.data_url}, replicate_rails_url)

    respond_to do |format|
      if @prompt.save
+       GenerateImageJob.perform_later(prompt: @prompt)
+
        format.html { redirect_to prompt_url(@prompt), notice: "Prompt was successfully created." }
        format.json { render :show, status: :created, location: @prompt }
      else
        format.html { render :new, status: :unprocessable_entity }
        format.json { render json: @prompt.errors, status: :unprocessable_entity }
      end
    end
  end

Persisting Replicate.com Predictions

Now it's time to take a look at the receiving end of our prediction request, i.e., the incoming webhook.

Right now, generated predictions are handed back to us, but we don't do anything with them. Since images are purged from Replicate's CDN periodically, we want to store them locally.

Let's start by generating a new child model, Prediction. We'll prepare it to store the generated image as a binary blob again:

$ bin/rails g model Prediction prompt:references replicate_id:string replicate_version:string prediction_image:binary logs:text
$ bin/rails db:migrate

On top of that, we create columns to store some metadata returned from Replicate.com: id, version, and logs — see the API docs.

Finally, we also have to register this new association in the Prompt model:

  # app/models/prompt.rb

  class Prompt < ApplicationRecord
    include AccountScoped

    belongs_to :account
+   has_many :predictions, dependent: :destroy

    # ...
  end

Now we just have to process the incoming predictions in our webhook, but we face an issue. We have to find a way to identify the specific Prompt instance the prediction was created for. We can circumvent this problem by adding a query param to the incoming webhook URL:

  # app/jobs/generate_image_job.rb

  class GenerateImageJob < ApplicationJob
    include Rails.application.routes.url_helpers

    queue_as :default

    def perform(prompt:)
      model = Replicate.client.retrieve_model("stability-ai/stable-diffusion-img2img")
      version = model.latest_version
-     version.predict({prompt: prompt.title, image: prompt.data_url}, replicate_rails_url(host: Rails.application.config.action_mailer.default_url_options[:host]))
+     version.predict({prompt: prompt.title, image: prompt.data_url}, replicate_rails_url(host: Rails.application.config.action_mailer.default_url_options[:host], params: {sgid: prompt.to_sgid.to_s}))
    end
  end

This will effectively send our incoming webhook to YOUR_NGROK_URL/replicate/webhook?sgid=YOUR_RECORD_SGID, making it easy to identify the prompt.

Obtain the `sgid` in Ruby

Sadly, the replicate-rails gem's default controller doesn't pass the query parameters to the webhook handler, but it does pass the exact webhook URL.

So we can flex our Ruby standard library muscles to obtain the sgid from it:

# config/initializers/replicate.rb

# ...

require "open-uri"

class ReplicateWebhook
  def call(prediction)
    query = URI(prediction.webhook).query

    sgid = CGI.parse(query)["sgid"].first

    prompt = GlobalID::Locator.locate_signed(sgid)

    prompt.predictions.create(
      prediction_image: URI.parse(prediction.output.first).open.read,
      replicate_id: prediction.id,
      replicate_version: prediction.version,
      logs: prediction.logs
    )
  end
end

# ...

Let's dissect this:

First, we pluck the exact webhook URL off the incoming prediction object and parse it, returning the query string.
Next, we invoke CGI.parse to convert the query string into a hash. Accessing the "sgid" key returns a one-element array, which is why we have to send first to it.
Then, we can use the obtained sgid to locate the prompt instance.
Finally, we append a new prediction to our prompt using the properties returned from Replicate.com. We also download the prediction image and save it in SQLite. Note that we can skip resizing because the generated image will already have the correct dimensions.

There's one final bit we have to tend to: we have to make sure our webhook handler works in an idempotent way. Webhooks can arrive duplicated or out of order, so we have to prepare for this case.

Luckily, we can use the ID returned by replicate to ensure idempotency. All we have to do is add a unique index to the replicate_id column. This will make it impossible to add a duplicate prediction to our database:

$ bin/rails g migration AddUniqueIndexToPredictions

class AddUniqueIndexToPredictions < ActiveRecord::Migration[7.0]
  def change
    add_index :predictions, :replicate_id, unique: true
  end
end

$ bin/rails db:migrate

Keep in mind that you typically would still want to store your assets and attachments in object storage buckets like Amazon S3 or DigitalOcean spaces. To get a glimpse of what SQLite can do, we have opted to store and render them directly from the database here.

To complete our picture — pun intended — we again have to find a way to display our stored predictions as children of a prompt. We can do this using a data URL:

  class Prediction < ApplicationRecord
    belongs_to :prompt

+   def data_url
+     encoded_data = Base64.strict_encode64(prediction_image)
+
+     "data:image/png;base64,#{encoded_data}"
+   end
  end

  <!-- app/views/prompts/_prompt.html.erb -->
  <div id="<%= dom_id prompt %>">
    <p>
      <strong>Title:</strong>
      <%= prompt.title %>
    </p>

    <p>
      <strong>Description:</strong>
      <%= prompt.description %>
    </p>

    <p>
      <strong>Prompt image:</strong>
      <%= image_tag prompt.data_url %>
    </p>

+   <p>
+     <strong>Generated images:</strong>
+     <% prompt.predictions.each do |prediction| %>
+       <%= image_tag prediction.data_url %>
+     <% end %>
+   </p>
  </div>

A Look Behind the Scenes of LiteJob for Ruby on Rails

Let's quickly look into how LiteJob uses SQLite to implement a job queueing system. In essence, the class Litequeue interfaces with the SQLite queue table. This table's columns, like id, name, fire_at, value, and created_at, store and manage job details.

The push and repush methods of the Litequeue class add jobs to the queue, interfacing with their respective SQL statements. When it's time for a job's execution, the pop method in the same class retrieves and removes a job based on its scheduled time. The delete method allows for specific job removal.

The Litejobqueue class is a subclass of Litequeue, which, upon initialization, is tasked with creating the worker/s. These workers contain the main run loop that oversees the actual job execution, continuously fetching and running jobs from the queue.

Limitations of LiteJob

Now that we've broken down how to use LiteJob for asynchronous job processing, let's look at some of the potential drawbacks ensuing from this approach.

While an SQLite-based architecture provides simplicity and reduces the need for external dependencies, it also introduces several limitations.

Firstly, LiteJob's reliance on SQLite inherently restricts its horizontal scaling capabilities. Unlike other databases, SQLite is designed for single-machine use, making it challenging to distribute workload across multiple servers. This can certainly be done using novel technologies like LiteFS, but it is far from intuitive.

Additionally, even on the same machine, concurrency contends with your web server (e.g., Puma) because LiteJob spawns threads or fibers that compete with those handling the web requests.

On the other hand (and crucially, for the majority of smaller apps), you might never need such elaborate scaling concepts.

LiteJob's Performance in Benchmarks

On a more positive note, LiteJob seems to allow for a lot of overhead before you have to scale horizontally: at least the benchmarks put me in a cautiously euphoric mood. Granted, the benchmarks don't carry a realistic payload, but they demonstrate that LiteJob makes very efficient use of threads and fibers.

Up Next: Streaming Updates with LiteCable

In this installment of our series, we delved deeper into the intricacies of using SQLite with LiteJob to handle asynchronous image generation and incoming webhooks in Rails applications.

To recap, while the SQLite-based architecture of LiteJob offers simplicity and reduced external dependencies, it also presents challenges in horizontal scaling. However, for smaller applications, LiteJob's efficiency with threads and fibers suggests it can handle a significant workload before necessitating more complex scaling solutions.

In the next post of this series, we'll look at providing reactive updates to our users using Hotwire powered by LiteCable.

Until then, happy coding!

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

DEV Community: julianrubisch

Deploying a Rails + SQLite App to a Synology NAS

The Setup

Part 1: Prepare the NAS

Create a deploy user

Set up SSH key authentication

Fix the Docker PATH problem

Create directories for your app

Enable passwordless sudo for Docker commands

Set up a local Docker registry

Confirm Tailscale is working

Part 2: Prepare Your Rails App

Configure the database for persistent storage

Update the Dockerfile

Build and push the image

Part 3: Deploy to the NAS

The compose file

Create the .env file on the NAS

The deploy script

Backups

HyperBackup

Btrfs Snapshots

Manual backup

You Know Hotwire Basics. Now What?

What It Is

What a Challenge Looks Like

No Rails Required

Who It's For

Free Challenges, Optional Extras

Try One

Measuring the Impact of Feature Flags in Ruby on Rails with AppSignal

What Are Feature Flags in Rails, Again?

Our Example App: A Solidus Storefront

Implement Feature Flags with Flipper

Testing a Performance Improvement

Testing Conversion Rate Optimization

Use AppSignal Custom Metrics to Measure the Impact of Feature Flags

Measuring Latency with a Measurement Metric

Tallying Conversions with a Count Metric

Set Up Custom Dashboards in AppSignal

Wrapping Up

An Introduction to HTTP Caching in Ruby On Rails

Concepts

Fresh Vs. Stale

HTTP Cache Layers

Shared Caches

Private Caches

Controlling Caching Via the Cache-Control Header

Request Directives

Response Directives

(In)validation

By Expiration

Based On the Response Content

Implementation In Rails

expires_in

expires_now and no_store

http_cache_forever

fresh_when and stale?

The etag Class Method

Takeaways

Rigorously Decompose into Turbo Frames

Apply Personalized Bits of the UI After the Fact

Wrapping Up

The Crumbling Codebase

🤔

🤹

🩺

How To Reduce Tech Debt to Keep Your Ruby on Rails Application Effortlessly Adaptable

Entropy, or Why the Pile in the Workshop Keeps Growing

The Second Law of Thermodynamics and Your Codebase

Tidy Up Your Workshop: Strategies for Reducing Code Complexity

What Can Attractor Do For You?

Ongoing Accompaniment of Development

Gradual Tech Debt Removal

Whole-App Refactoring Guide

Full-Text Search for Ruby on Rails with Litesearch

What Is Litesearch?

Configure the Prompt Model for Litesearch

Add a Typeahead Search Bar to Our Ruby on Rails Application

Excursus: Highlighting Search Results Using a Turbo Event in Rails

Controlling Caching Via the `Cache-Control` Header

`expires_in`

`expires_now` and `no_store`

`http_cache_forever`

`fresh_when` and `stale?`

The `etag` Class Method

Configure the `Prompt` Model for Litesearch

Obtain the `sgid` in Ruby