Mouad Imam
All articles

10 min read

Roda next to a nine-year-old Rails app: where it earns its place

A simulated nine-year-old Rails monolith and a small, high-volume endpoint: add a controller, mount Roda inside Rails, or run a separate Roda service?

To keep this concrete without exposing anyone's code, this article works through a simulated codebase: a nine-year-old Rails monolith that a lot of people and systems depend on. It is a composite I made up, not a description of any employer's project, and every detail about it below belongs to the simulation.

In the simulation the app has hundreds of models. It boots slowly, the test suite takes a long time, and every request goes through middleware that most requests do not need. Deploys carry the whole thing every time.

Then a small need arrives: a webhook receiver, or an ingestion endpoint, or a health and status API, or an internal callback. It has few routes and almost no domain logic, and it may receive a lot of traffic. There are three ways to build it.

  1. Add one more controller to the monolith.
  2. Mount a Roda app inside the monolith's routes.
  3. Run a separate Roda service beside it.

For most features in that app, the answer is still option 1. The rest of the article is about the narrow kind of endpoint where it is not.

What Roda is

Roda is a Ruby web toolkit built on Rack1. Its README says it has "a very small core, providing only the essentials" and that everything else is added through plugins2. Routing is a tree: r.on splits it into branches, r.is finalizes the path, and r.get and r.post handle specific methods. You can act on the request at any point while routing2.

Here is the simulated ingestion endpoint. EventStore stands in for whatever persists the data.

require "roda"

class Ingest < Roda
  plugin :json
  plugin :json_parser, content_type_regexp: /\Aapplication\/json\b/i
  plugin :typecast_params
  plugin :all_verbs
  plugin :halt

  route do |r|
    r.get "health" do
      { status: "ok" }
    end

    r.on "events" do
      r.is do
        r.post do
          account_id = typecast_params.pos_int!("account_id")
          EventStore.record(account_id, r.params["payload"])
          response.status = 202
          { status: "queued" }
        end
      end

      r.on Integer do |id|
        r.is do
          r.get { EventStore.find(id) }
          r.delete do
            EventStore.remove(id)
            r.halt(204)
          end
        end
      end
    end
  rescue Roda::RodaPlugins::TypecastParams::Error => e
    r.halt(400, [{ "error" => "invalid #{e.param_name}" }])
  end
end

What the plugins do, from their documentation:

  • json serializes Hash and Array return values and sets the content type. Strings are not converted3.
  • json_parser parses JSON request bodies into r.POST, so the data also shows up in r.params. Set content_type_regexp, or it falls back to a loose pattern and prints a warning4.
  • typecast_params converts untrusted parameters and raises a TypecastParams::Error that you turn into a 4xx5.
  • all_verbs adds delete, put, patch and the other verbs next to get and post6.
  • halt lets r.halt take a status, headers and a body7.

The README recommends freezing the app in production and in tests, with App.freeze.app in config.ru. Frozen apps cannot have their settings changed at runtime, and the README says this removes thread-safety problems2.

What I have built, as opposed to what I am simulating

Everything above and below about the nine-year-old monolith is invented. This paragraph is real: I built a small log-ingestion API with Roda and Sequel as a personal project. With Roda you choose each plugin, and anything Rails would have handed you, such as request authentication or parameter handling, you write and maintain yourself. That cost shapes the rest of this article.

Option 1: one more controller

# config/routes.rb
resources :events, only: %i[create show destroy]

resources :photos, the routing guide's example, creates seven routes mapped to controller actions8. You get the controller conventions, the test setup, the deploy pipeline and the error tracker that already exist.

The costs in the simulation are the ones we started with. The endpoint boots with the whole app, runs behind the full middleware stack, and ships in the same deploy as everything else. If the endpoint receives a burst, it competes for the same processes as the product. Rails has an API mode with fewer middleware, but for an existing app the guide switches it on with config.api_only = true for the whole application9, so it does not help a monolith that also serves HTML.

For an endpoint that is low-traffic and tied to existing models, this is still the right answer.

Option 2: mount Roda inside Rails

A Roda app is a Rack app, and the Rails routing guide shows mount for Rack apps, with mount AdminApp, at: "/admin" as its example8. The guide introduces mount for a Rack app that should "receive requests at the root path" of its mount point8:

# config/routes.rb
mount Ingest.freeze.app, at: "/ingest"

What this shares and what it skips:

  • Shared: the process, the boot, the memory and the deploy. The Rails on Rack guide shows the middleware stack ending with the application's routes, so a mounted app sits behind the same middleware as everything else10.
  • Skipped: controllers, ApplicationController filters, strong parameters and the rest of Action Controller.
  • Reloading: the autoloading guide says not to cache reloadable classes11. The router holds a mounted app, so keep it outside reloadable paths or restart in development.

The Roda README says its own r.run can mount Rack apps, and that an :add_script_name setting exists for apps mounted under a path2. It does not discuss mounting Roda under Rails, so I would test the path handling in your version.

So mounting removes controller overhead. It does not touch slow boot, the middleware stack, or deploys that carry everything, which were the reasons for looking at Roda in the first place. I would use it when the endpoint needs the monolith's process and data, and a controller would do the job but the routing tree is cleaner. That is a small set.

Option 3: a separate Roda service

Now the endpoint boots in its own time, loads the plugins it uses, and deploys without the monolith. A burst on the endpoint no longer slows the product. This is the case where Roda's small core pays off. The costs are all integration.

The database

You can reuse the monolith's Active Record models, or read and write the same schema with Sequel.

  • Active Record models: the endpoint gets the validations and callbacks the monolith already has. It also pulls in the app, which brings back the slow boot and the coupling you left to escape.
  • Sequel on the same schema: Sequel.connect takes a database URL, DB[:events] gives you a dataset, and a Sequel::Model reads the table's schema from the database12. Boot stays small. The business rules in the old models do not come along, so you have duplicated knowledge.
DB = Sequel.connect(ENV.fetch("DATABASE_URL"))

module EventStore
  def self.record(account_id, payload)
    DB[:events].insert(account_id: account_id, payload: payload.to_json, created_at: Time.now.utc)
  end
end

The way I would limit the damage: the service writes to narrow tables it owns, the monolith keeps the migrations so the schema has one owner, and anything that needs the old rules happens later in a job on the monolith side.

Authentication and sessions

The monolith has its own login, Devise or hand-rolled, and it does not matter which. The new endpoints do not use it. A webhook is authenticated by a signature, an internal callback by a token. Roda has a sessions plugin that stores encrypted cookies under its own secret13, so treat the two session systems as unrelated and do not try to share cookies. If the service is machine-to-machine only, it needs none.

Jobs

The Active Job guide describes it as a Rails framework that runs jobs on a queuing backend14, and the Sidekiq wiki says the Active Job adapter must be set to :sidekiq15. A service outside Rails has no Active Job, so it pushes to the backend directly, for example with a plain Sidekiq job class. Check how your queue backend wraps Active Job payloads before enqueuing from outside Rails; the simpler route is a plain worker on the monolith side that the service enqueues, and which then calls into Rails code.

Shared rules

If both sides need the same validation or pricing rule, put it in a plain Ruby library or a gem with no Rails dependency, and require it from both. It is worth doing even if you never build the Roda service.

Logs, errors and deploys

The new service must appear in the same logs, error tracker and pipeline as the monolith. If it does not, nobody watches it. This is more work than the routing tree.

The failure mode

The usual failure is a second stack that only one person understands. When that person leaves, the service is either rewritten in Rails or left untouched until it breaks. Rails gives a new hire conventions and a large hiring pool. A Roda service gives them your choices. Plan for this before you start: write down why the service exists, how it runs, and what would justify folding it back.

Decision table

FactorAdd to monolithMount Roda insideSeparate Roda service
Boot and deployShared with the monolithShared with the monolithIndependent
Middleware per requestFull stackFull stackOnly what you add
Existing models and rulesAvailableAvailableVia Sequel or a shared library
AuthenticationExisting login or tokensSkips controller filtersSignatures or tokens you write
JobsActive JobActive JobBackend's own client
ObservabilityAlready thereAlready thereYou wire it
Who can maintain itAny Rails developerNeeds Roda knowledgeNeeds Roda knowledge and ops
FitsMost featuresA small set of tidy endpointsIsolated, high-volume endpoints

The questions that decide it

  • Does the endpoint need the monolith's models and rules, or only a table to write to?
  • Would a burst on this endpoint hurt the product if they share processes?
  • Can the new service appear in the same logs, error tracker and pipeline from day one?
  • Do two people understand the service well enough to keep it running?
  • Is the rule you would need to share small enough to live in a gem?

If the answers are "only a table", "yes, it would hurt", "yes", "yes" and "yes", a separate Roda service is a reasonable choice. Otherwise add the controller.

References

  1. J. Evans, "Roda: Routing Tree Web Toolkit," roda.jeremyevans.net. [Online]. Available: https://roda.jeremyevans.net/. Accessed: 19 Nov. 2026. ↩

  2. J. Evans, "README.rdoc," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/files/README_rdoc.html. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3 ↩4

  3. J. Evans, "Roda::RodaPlugins::Json," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Json.html. Accessed: 19 Nov. 2026. ↩

  4. J. Evans, "Roda::RodaPlugins::JsonParser," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/JsonParser.html. Accessed: 19 Nov. 2026. ↩

  5. J. Evans, "Roda::RodaPlugins::TypecastParams," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/TypecastParams.html. Accessed: 19 Nov. 2026. ↩

  6. J. Evans, "Roda::RodaPlugins::AllVerbs," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/AllVerbs.html. Accessed: 19 Nov. 2026. ↩

  7. J. Evans, "Roda::RodaPlugins::Halt," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Halt.html. Accessed: 19 Nov. 2026. ↩

  8. Ruby on Rails, "Rails Routing from the Outside In," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/routing.html. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3

  9. Ruby on Rails, "Using Rails for API-only Applications," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/api_app.html. Accessed: 19 Nov. 2026. ↩

  10. Ruby on Rails, "Rails on Rack," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/rails_on_rack.html. Accessed: 19 Nov. 2026. ↩

  11. Ruby on Rails, "Autoloading and Reloading Constants," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/autoloading_and_reloading_constants.html. Accessed: 19 Nov. 2026. ↩

  12. J. Evans, "README.rdoc," Sequel Documentation. [Online]. Available: https://sequel.jeremyevans.net/rdoc/files/README_rdoc.html. Accessed: 19 Nov. 2026. ↩

  13. J. Evans, "Roda::RodaPlugins::Sessions," Roda Documentation. [Online]. Available: https://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Sessions.html. Accessed: 19 Nov. 2026. ↩

  14. Ruby on Rails, "Active Job Basics," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/active_job_basics.html. Accessed: 19 Nov. 2026. ↩

  15. Sidekiq, "Active Job," Sidekiq Wiki, GitHub. [Online]. Available: https://github.com/sidekiq/sidekiq/wiki/Active-Job. Accessed: 19 Nov. 2026. ↩

Discuss your project

What are you trying to build or decide? A short description of your product, who uses it and where you need help is enough to start.

In our first conversation we can work out whether you need a hands-on engineer, a technical review or a pilot, then agree on scope and timing.