🌊 undertow

Rails apps often have models that represent a composition of data from multiple sources. A product listing might pull from categories, sellers, and inventory. A search document might aggregate fields from a dozen associations. A cache entry might depend on records several joins away. When any of those sources change, the composed record is stale and something downstream needs to react.

The usual approach is to add callbacks to the upstream models and fan out from there. That works for simple cases, but it gets messy fast. It's easy to miss associations, it creates hidden coupling between models that have no business knowing about each other, and it breaks down entirely when the relationship is indirect, through a join table or a scope.

Relational databases solve a version of this with materialized views: a precomputed result that tracks its own staleness and refreshes lazily when sources change. Undertow brings that pattern to ActiveRecord. Dependencies are declared on the root model, undertow resolves which records are affected when upstream data changes, and the affected IDs are buffered in a configurable store and delivered in batches to a handler you define, off the write path.

You don’t “update” derived state.

You declare how to rebuild it.. and let Undertow pull it back into consistency.

Like an undertow under the surface, it quietly keeps everything aligned.

• Ruby >= 3.0
• ActiveRecord ~> 7.0
• ActiveSupport ~> 7.0
• ActiveJob ~> 7.0

Add Undertow to your Gemfile:

gem "undertow"

If you want to use Redis or Valkey as the backing store, also add:

gem "redis"

Then run:

bundle install

Create config/initializers/undertow.rb:

Undertow.configure do |c|
  c.store          = Undertow::Store::MemoryStore.new
  c.queue_name     = :undertow
  c.max_batch      = 1_000
  c.drain_lock_key = "undertow:drain:lock"
end

MemoryStore is the default, so setting c.store is optional unless you want a different backend.

MemoryStore keeps state in process memory and is intended for tests and single process development. Use RedisStore for multi process or multi dyno deployments.

For Redis or Valkey:

Undertow.configure do |c|
  c.store = Undertow::Store::RedisStore.new(
    Redis.new(url: ENV["REDIS_URL"])
  )
end

RedisStore is compatible with Redis and Valkey servers that support standard Redis set and lock commands. It accepts a direct Redis client or a pooled client that responds to with.

Call Undertow.tick from your scheduler on each interval:

every(1.second, "undertow") { Undertow.tick }

Undertow starts from the root model, the model that owns derived or aggregated state and needs to know when upstream data changes.

The root model defines:

• what it depends on
• which columns matter
• what to do when affected IDs are ready

Upstream models need no configuration. Undertow wires their callbacks automatically at boot when a root model declares a dependency on them.

That’s the point.

The model that owns the derived state defines the contract.

Here’s the whole shape:

class Post < ApplicationRecord
  belongs_to :author
  has_many :post_tags
  has_many :tags, through: :post_tags

  undertow_skip %w[view_count updated_at]

  undertow_depends_on :author,
    foreign_key: :author_id,
    watched_columns: %w[name bio]

  undertow_depends_on :tag,
    resolver: ->(tag) {
      Post.joins(:post_tags).where(post_tags: { tag_id: tag.id })
    },
    watched_columns: %w[name slug]

  undertow_on_drain ->(model_name, ids, deleted_ids) {
    PostSyncJob.perform_later(ids, deleted_ids)
  }
end

Declare what affects the root model. Undertow figures out which root records are stale and delivers the IDs in batches.

Use foreign_key: when the root model directly references the upstream model:

undertow_depends_on :author,
  foreign_key: :author_id,
  watched_columns: %w[name bio]

Use resolver: when there is no direct foreign key from the root model to the upstream model:

undertow_depends_on :tag,
  resolver: ->(tag) {
    Post.joins(:post_tags).where(post_tags: { tag_id: tag.id })
  },
  watched_columns: %w[name slug]

Use watched_columns: when only certain upstream changes matter:

undertow_depends_on :author,
  foreign_key: :author_id,
  watched_columns: %w[name bio]

Use undertow_skip for columns on the root model that should not trigger downstream work.

undertow_skip %w[view_count updated_at]

Use undertow_on_drain to define what happens when a batch is ready.

undertow_on_drain ->(model_name, ids, deleted_ids) {
  PostSyncJob.perform_later(ids, deleted_ids)
}

Undertow.without_tracking do
  Author.find_each { |author| author.update!(legacy: true) }
end

Undertow::DrainJob is enqueued by Undertow.tick when pending work exists and the drain lock can be acquired.

• releases the lock immediately on start
• drains in batches (max_batch)
• restores IDs and emits an error event when the handler raises
• continues draining on next tick if capped or after an error

The drain lock has a default TTL of 30 seconds.

Undertow publishes ActiveSupport::Notifications events:

ActiveSupport::Notifications.subscribe("drain.undertow") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  Rails.logger.info(event.payload)
end

ActiveSupport::Notifications.subscribe("error.undertow") do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  Rails.logger.error(event.payload)
end

See UPGRADING.md for version migration steps.

MIT. See LICENSE.

See CONTRIBUTING.md.