katafrakt’s garden

What if Hanami had templateless views?

2026-05-29T04:01:29+02:00

In the new glorous website of Hanakai there are two “getting started” guides for Hanami: one for a “web app” (meaning, a fullstack app) and one for an API app. Even though those two guides follow building the same application (bookshelf), they differ quite a bit in places. Sometimes it’s absolutely justified (you don’t have HTML templates in API app), sometimes it feels justified, but can also provoke a thought. This is one of these thoughts.

Let’s look about 30% in the guide at “Fetching books from database” subsection. It demonstrates how to get a books index page, paginated. This is how is looks for a fullstack app (combined into one listing for clarity):

# action
module Bookshelf
  module Actions
    module Home
      class Index < Bookshelf::Action
        def handle(request, response)
        end
      end
    end
  end
end

# view
module Bookshelf
  module Views
    module Books
      class Index < Bookshelf::View
        include Deps["repos.book_repo"]

        expose :books do
          book_repo.all_by_title
        end
      end
    end
  end
end

# template
<h1>Books</h1>

<ul>
  <% books.each do |book| %>
    <li><%= book[:title] %>, by <%= book[:author] %></li>
  <% end %>
</ul>

… and this is for API:

module Bookshelf
  module Actions
    module Books
      class Index < Bookshelf::Action
        include Deps["repos.book_repo"]

        def handle(request, response)
          books = book_repo.all_by_title

          response.format = :json
          response.body = books.map(&:to_h).to_json
        end
      end
    end
  end
end

I looked at these code listing probably dozens of times, until it hit me:
Why are actions so much different here?

The fullstack app action is empty. It does nothing. Okay, this is not true, it actually does something, but it’s hidden by the framework mechanics, but it does more or less that:

def handle(request, response)
  response.format = :html
  response.body = render_the_view_somehow
end

It looks more similar to the API version now, but there is one jarring difference now: the API action needs to know about a repository and how to call it. Or does it actually need that? The instinctive answer is: yes. We don’t render HTML so we don’t have the view layer, so there’s no other choice, it needs to go to the controller! This is we built JSON APIs in Rails and Sinatra for decades. Now as a long-time Phoenix user and its dead-viewFor those unfamiliar, “dead views” is a term coined in opposition to LiveView - in Ruby terms it’s just a regular server-rendered view. enjoyer, I dare to challenge that.

Without further ado, I think it could look like this:

# action
module Bookshelf
  module Actions
    module Books
      class Index < Bookshelf::Action
        def handle(request, response)
          response.format = :json 
        end
      end
    end
  end
end

# view
module Bookshelf
  module Views
    module Books
      class Index < Bookshelf::View
        include Deps["repos.book_repo"]

        expose :books do
          book_repo.all_by_title
        end
        
        render do
          { books: books.map(&:to_h) }
        end
      end
    end
  end
end

This way we keep original separation of concerns from the fullstack Hanami app - the action deals with request/response stuff, while the view is responsible for the shape and content of the response. In a large app both of them will grow, but they will grow independently. When we add permissions to see books index page, only action will change, indicating that the format of the response remains unchanged. Similarly, when we need to change the structure of the JSON, the change will be local to the view class.

Implemetation

Currently Hanami relies on Tilt and file-based templates to render views. In order to achieve what I described above, we would need to define custom Renderer and Rendering classes:

class InlineRenderer < Hanami::View::Renderer
  def initialize(config, render_proc)
    super(config)
    @render_proc = render_proc
  end

  def template(_name, _format, scope, &_block)
    @template ||= scope.instance_exec(&@render_proc).to_json
  end
end

class InlineRendering < Hanami::View::Rendering
  def initialize(config:, format:, context:, render_proc:)
    super(config:, format:, context:)
    @renderer = InlineRenderer.new(config, render_proc)
  end
end

The we use it in our application’s View class:

module Bookshelf
  class View < Hanami::View
    extend Dry::Core::ClassAttributes
    defines :render_proc

    def rendering(format: config.default_format, context: config.default_context)
      InlineRendering.new(config: config, format: format, context: context, render_proc: self.class.render_proc)
    end

    def self.render(&block)
      render_proc block
    end
  end
end

You can see it in action in this repo.

The doors it opens

Just to be clear, what I show here is the result of my experimentation, not a sneak peek into what Hanami will offer soon. This experiment was, however, quite important to me.

Even though currently Hanami is kind of coupled to Tilt and its HTML templates, it’s possible to change that in about 20 lines of code.
It opens up possibility to integrate Phlex into hanami-view, not replacing it
Many people think JSON responses are simple compared to HTML ones. For sure they tend to be more focused, but they definitely can grow a lot. Having the whole view layer at your disposal means that API application can have this pain eased by Hanami as much as fullstack apps.

Untimely feedback as a root cause of tech debt

2026-05-12T12:50:10+02:00

Have you ever worked on a brand new codebase with talented engineers, only to find out a year later that it turned into the same “archaeological strata of quick fixes” as your last legacy project? I know I have, and it happened many times.

My go-to blame target for this was usually micromanagement and imposed unrealistic deadlines. And I’m sure these play a significant role in it. But a recent conversation led me to understand another cause of this – untimely feedback. Or, to be precise, feedback that was requested or given too late.

I think many of us know the story. Someone starts working on a new capability. They spin off a feature branch and keep tinkering with it for a couple of days. Then they submit a PR. Thousands of lines, large diffs, the feeling of being overwhelmed and then the despair when you find a fundamental flaw in the design. The one that is not disqualifying, but one that would require a complete rewrite to do the thing correctly.

From there, there are two options. And neither of them is good.

First, you can point that out and request changes. This is also known as “being that person”. Nobody wants to have this label. Plus it frequently results in a heated back-and-forth when the author desperately wants to avoid spending another week on a full rewrite.

The other option is to let that pass. You reluctantly approve the PR and the code lands in the trunk. You know it will cause trouble in the future and it inevitably does. The codebase got worse, the tech debt increased. But you don’t want to be that person and don’t want to have “the talk” with your manager about The Velocity.

You might think that this could have been avoided if the author asked for feedback first. But why didn’t they? Is it because they like to work this fait accompli way? Most likely not. In fact, maybe they did ask for early feedback but nobody provided it.

This also happens a lot. Someone writes a high-level description of a solution and… no one bothers. It would require taking this description and translating it yourself into something more tangible. That’s the way to spot a problem from a high-level description. It constitutes an effort, often much bigger than just glossing over a ready-to-review solution. This creates a cycle that is hard to break:

People don’t ask for early feedback, because they don’t think they’ll receive it
Late feedback is not given, because it’s too late
Code with design flaws gets merged, not because of someone’s bad faith or inability to write a good one, but because two pairs of eyes are usually better than one

My takeaway from that is to ask for early feedback more often. Even if I don’t believe in receiving it, just creating a possibility of it might pay off in the future. And to try to push myself to give early feedback whenever it’s viable, even if I don’t feel like making this mental effort. As a side benefit, this would also make the development process more collaboration-based than sign-off-based, which is definitely a win.

Portable mruby binaries with Cosmopolitan

2026-01-04T14:16:49+01:00

One of my main interests with mruby is its ability to create standalone executables. As explored in this post, this is absolutely possible and works well. However, there is a classic issue of most standalone binaries: they can only be run on the same, or very similar, system as the one they were built on.

For example, if I take an executable from my mruby Hello World project, built on amd64 Linux, it won’t work on Silicon Mac:

$ ./hello
exec: Failed to execute process: './hello' the file could not be run by the operating system.
exec: Maybe the interpreter directive (#! line) is broken?

Mruby does have some cross-compilation capabilities, but I’ll be honest: it always felt intimidating, complected and I never actually got it working from Linux to MacOS. So, are we doomed here? Is it possible to build standalone binaries for MacOS without a MacOS docker image or something?

While reading the changelog of mruby I noticed one entry there that got me curious:

New Platform: Cosmopolitan Libc

I never heard about Cosmopolitan, but a quick search revealed that it is what might address the issue mentioned above. From the project’s website:

Cosmopolitan Libc makes C a build-anywhere run-anywhere language, like Java, except it doesn’t need an interpreter or virtual machine. Instead, it reconfigures stock GCC and Clang to output a POSIX-approved polyglot format that runs natively on Linux + Mac + Windows + FreeBSD + OpenBSD + NetBSD + BIOS on AMD64 and ARM64 with the best possible performance.

Alright, let’s give it a try then!

Building an mruby project with Cosmopolitan

The regular steps to build a standalone binary are as shown in the Rakefile:

Build mruby
Generate bytecode from the Ruby code, using mrbc built in step 1
Compile the binary using a C entry file and the bytecode generated in step 2

For Cosmopolitan, it’s simple, but we need some initial setup.

First, let’s download the Cosmopolitan toolkit from https://cosmo.zip/pub/cosmocc/. I extracted it to ~/Downloads/cosmocc for the purpose of this article.

Then we can build mruby using it:

COSMO_ROOT=~/Downloads/cosmocc rake MRUBY_CONFIG=cosmopolitan

At the time of writing, I needed to remove mirb (this line) from the config, because it failed to compile with Cosmopolitan.

Then we can generate the bytecode. Note the different executable name:

./mruby/bin/mrbc.com -Bhello_world hello.rb

Finally, compile the entry file:

~/Downloads/cosmocc/bin/cosmocc -std=c99 -Imruby/include main.c -o hello mruby/build/host/lib/libmruby.a -lm

After that we get a binary hello. And if I copy it over to my Mac, it just works there! The binary size is larger, of course, which is the understandable price. But if it is fine for the project you are working on, for sure this is a simpler way than providing multiple binaries targetting different platforms.

Using Elixir head version with Mise

2026-01-03T03:00:00+01:00

In 2025 I followed the direction many people headed in and switched my version manager to mise-en-place. It has been going really well for me, but recently I came across a problem which took me a bit to figure out (and few very frustrating conversations with LLM, which did not lead to anything). I wanted to test some code with unreleased version 1.20 of Elixir, straight from git.

How to do it? It’s really simple in retrospect. Here are the steps:

1. Build Elixir

$ git clone https://github.com/elixir-lang/elixir.git 
$ cd elixir
$ make

Verify it’s built correctly:

$ bin/elixir --version
> Elixir 1.20.0-dev (88cbabf) (compiled with Erlang/OTP 28)

2. Link it in mise

mise link elixir@head /path/to/elixir

3. Verify this works

$ mise x elixir@head -- elixir --version
> Elixir 1.20.0-dev (88cbabf) (compiled with Erlang/OTP 28)

And it’s done. Whenever you want to run something with Elixir head, you can just mise use elixir@head.

Of course, this should work in a similar way for everything that is handles by mise version control.

Integrating Pagy with Hanami (2025 edition)

2025-11-06T11:00:00+01:00

Back in 2018 I wrote a post about connecting Hanami (then 1.x) and Pagy gem together. My verdict was not that favorable. I had to write quite a lot of glue code to make it work and perhaps the worst thing was that I had to pass the request object to the template to make it work.

However, things have changed since then:

Hanami is now 2.3, its persistence layer is more mature, based on ROM and allows to fall back to almost-bare-Sequel via relationsLooking back, perhaps it was already possible in 2018, but I took the wrong approach? Hard to tell now. I don’t want to go back to these old versions to verify..
Pagy released version 43 this week. It’s advertised as a complete rewrite of its internals and APIs.

We needed a leap version to unequivocally signaling that it’s not just a major version: it’s a complete redesign of the legacy code at all levels, usage and API included.

There’s no better time to take it for another spin then!

The code

I quickly spun up a fresh Hanami app, created a migration:

ROM::SQL.migration do
  change do
    create_table :people do
      primary_key :id
      column :name, String, null: false
      column :email, String, null: false
      column :birth_date, Date, null: false
      column :added_at, DateTime, null: false
    end
  end
end

Then created a relation:

module Pagynation
  module Relations
    class People < Hanami::DB::Relation
      schema :people, infer: true
    end
  end
end

Next I generated the action and added Pagy to it.

require "pagy"

module Pagynation
  module Actions
    module People
      class List < Pagynation::Action
        include Deps["relations.people"]
        include Pagy::Method

        def handle(request, response)
          pagy, records = pagy(people.order(:name), request:, client_max_limit: 40)
          response.render view, pagy: pagy, people: records
        end
      end
    end
  end
end

This looks more or less like the tutorial code from the Pagy website. The only exception is that I have to pass the request directy. If not passed, Pagy expects self.request to be defined. This does not work with Hanami, where the request is passed as an argument (in a functional flavour), not burned into the controller instance.

Let’s now examine the view:

module Pagynation
  module Views
    module People
      class List < Pagynation::View
        expose :people, decorate: false

        expose :paginator, decorate: false do |pagy:|
          pagy
        end
      end
    end
  end
end

This is standard Hanami stuff. We passed :pagy and :people from the action via the render method, now we need to pass it on to the template. I used decorate: false here to keep the things as simple as possible (data is a simple hash, not objects). With people and paginator exposed, all that’s left is to craft a template using it.

<h1>People list</h1>

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Date of Birth</th>
    </tr>
  </thead>
  <tbody>
    <% people.each do |person| %>
      <tr>
        <td><%= person[:name] %></td>
        <td><%= person[:email] %></td>
        <td><%= person[:birth_date] %></td>
      </tr>
    <% end %>
  </tbody>
</table>

<div>
  <%= raw paginator.info_tag %>
</div>

<div>
  <%= raw paginator.series_nav %>
</div>

The paginator.info_tag and paginator.series_nav are Pagy’s HTML helper to render some status info and pagination links. They are, of course, quite barebones, but more than enough to test stuff.

This all led me to this beauty, with working limit URL params, working links etc.

New verdict

This is basically great.

Everything worked pretty much out-of-the-box. If I were to imagine how seamless a pagination library for Hanami could be, this would likely look like that. Great improvements from Pagy maintainer.

The repository to try it out yourself is available here on Codeberg.

Happy paginating!

Eglot, Ruby LSP and StandardRB

2025-11-04T00:01:00+01:00

I use Doom Emacs as my main coding editor, and eglot for language server shenanigans. My config is mainly optimized towards Elixir, so for Ruby I was mostly using the default Doom’s Ruby module. It worked pretty well for me.

The main hurdle was always projects not using Rubocop. I prefer StandardRB, because I don’t like bike-shedding, and their defaults are really good for me. But in the absence of .rubocop.yml file, Doom tried to use default Rubocop settings for linting, instead of detecting StandardRB. In the past, I worked around this by replacing rubocop-mode with standard-mode, but recently Doom’s maintainer decided to go full-on with Ruby LSP for formatting and linting, so I had to re-hack it.

Fortunately, Ruby LSP supports addons and there is one for StandardRB. Unfortunately, it’s not as easy as it sounds…

tl;dr

You need to put this in your .dir-locals.el:

((ruby-mode
  . ((eglot-server-programs
      . ((ruby-mode . ("ruby-lsp"
                       :initializationOptions
                       (:formatter "standard"
                        :linters ["standard"]
                        :enabledFeatures (:codeActions t
                                          :diagnostics t
                                          :formatting t)))))))))

How I got there

Using .dir-locals.el is what eglot suggests in its documentation. However, the suggested form did not work for me:

 ((nil
   . ((eglot-workspace-configuration
       . (:rubyLsp
          (:formatter "standard" :linters ["standard"]
           :enabledFeatures (:codeActions t :diagnostics t :formatting t)))))))

After examining the eglot-events-buffer, I realized that eglot was sending workspace/didChangeConfiguration event with my new config, including my chosen formatter and linter. But apparently, Ruby LSP server was not doing anything with that message.

Indeed, after going through the code, I found that workspace/didChangeConfiguration is not a supported message by Ruby LSP! I offered to add it and spent few days on implementation, only to find out that it would not help me. Why?

The issue here is that, upon initializing the language server connection, Ruby LSP checks for supported formatters and finds nothing. After that it, sets documentFormattingProvider to null, effectively telling the client that it does not support formatting. Period. eglot notes it down and whenever the user requests formatting, it just ignores the request, knowing it won’t be fulfilled.

So, the next task after implementing support for workspace/didChangeConfiguration would be to add server dynamically registering new capabilities, formatter in this case. While it sounded promising and after I did most of the work, I unfortunately realized that eglot does not support dynamic registrations :( I scraped the code and looked for another solution…

… which, in this case, is to simply shut down the LS connection and reinitialize it with standard formatter and linter from the start. At first I wasn’t really happy about it, but then I figured this is actually simple and efficient solution, much in line with Erlang’s philosophy of killing and restarting things, rather than using elaborate reconfiguration or healing techniques.

In any case, I now have a working formatter and linter and know a lot more about language servers.

Next stop: making StandardRB support region formatting (Rubocop does not support it either).

My OCaml-flavoured Elixir style

2025-09-23T00:01:00+02:00

Recently I’m finding myself leaning towards writing some Elixir code in a bit different way than the community standard. I call it, perhaps unjustly and a bit tongue-in-cheek, “OCaml-flavoured Elixir”. Now, I don’t really write OCaml well (or: at all), but I spent last 3 years working with a frontend written in ReScript. And I think in recent months it started to affect how I think about the Elixir code.

But to start the conversation, let me show you what I actually mean:

def close_ticket(ticket_id, actor_id) do
  fetch_ticket = fn ->
    Repo.get(Ticket, ticket_id)
    |> Result.wrap_not_nil(:ticket_not_found)
  end

  fetch_user = fn ->
    Repo.get(User, actor_id)
    |> Result.wrap_not_nil(:user_not_found)
  end

  with {:ok, ticket} <- fetch_ticket.(),
    {:ok, user} <- fetch_user.(),
    :ok <- TicketPolicy.can_close?(ticket, user) do
      Tickets.close(ticket)
      |> Result.map(&Map.from_struct/1)
      |> Result.map(&Map.put(&1, :closed_by, user))
  end
end

I see few eyebrows raised, perhaps even some pitchforks picked up, but allow me explain why I find this style of code easier to follow.

1. Self-containing

Traditional rules of writing Elixir code, stemming from Ruby, stemming probably from Java (?), would urge us to create private functions fetch_ticket and fetch_users, wrapping database calls in a result tuples ({:ok, user}). This is an understandable coding pattern, however it leads to “jumping around” the codebase. The private function will usually be defined below the public function using it, perhaps even at the end of a file. This leads to very “choppy” experience when reading the code.

Another problem is creating non-reusable private function, which serve only to encapsulate some code logic. They often receive a lot of arguments, same as the private function calling them. These, in my opinion, are signals of suboptimal design.

Defining anonymous functions inside the public function changes the reading dynamic a bit. When you read a function, you read it top-down. This means that upon getting to the with piipeline, you have at least skimmed over the fetch_ticket and fetch_user. If you want to go back to read what they do, they are here, at hand, not somewhere in the module.

Of course, this might get out of hand with multiple complex anonymous functions defined. I try to keep 3 of them at most, otherwise it obfuscates where the actual function “meat” begins.

2. Follows prepare-execute-format flow

Majority of code actions, especially the ones modeling business actions, follow a certain flow. First you prepare data, then you execute an action, then - optionally - you format the result. Here defining a functions serve as a preparation. The with pipeline is execution and we have some lightweight formatting as a map too. I could just take this code, print it, and then draw the line where the “preparation” step finishes and execution begins.

With private functions instead, I would have the preparation conflated with execution. It’s not bad, but it’s less explicit.

3. Using OCaml-like helpers

If you are wondering what Result.map is, it comes from my Fey library. I created and published it some time ago, but never really announce it. It contains multiple functions to work with result tuples (and introduces option tuples), inspired by OCaml/ReScript.

In the case above, it allows to simplify code that would often be a case statement:

case Tickets.close(ticket) do
  :ok ->
    ticket
    |> Map.from_struct()
    |> Map.put(:closed_by, user)
    |> then(&{:ok, &1})

  {:error, error} ->
    {:error, error}
end

My codebase is full of snippets like this. If the result is {:ok, something} then do some small transformation of something and wrap it back with {:ok, _}. If not, just pass the result through.

Fey.Result.map wraps it with a convenient helper, just as OCaml does. This is much more terse and concentrating on what’s important - modifying the result value.

Similarily, the Fey.Result.wrap_not_nil helps avoid repetitive boilerplate of

case Repo.get(Ticket, id) do
  nil -> {:error, :ticket_not_found}
  ticket -> {:ok, ticket}
end

That’s it

I’d love to hear where this breaks down for other people. I truly find this code easier to follow and maintain, but at the price of deviating from a community standard. Ultimately, we always need to decide what’s more important.

And by the way, I’m sure that there is a performance penalty of using anonymous functions over private functions. I haven’t measured it (yet). But for non-critical paths this should not matter that much.

Micro-slices in Hanami

2025-07-29T00:01:00+02:00

Slices are my favourite architectural feature in Hanami. They allude to the vertical slices architecture and let you host cross-functional “mini-apps” within your main Hanami projectThe feature itself is present from early days of Hanami, perhaps from the times when it was still called Lotus. Back then it was called apps..

A typical slice file structure (generated by Hanami slice generator) would look like this:

slices
└── admin
    ├── action.rb
    ├── actions
    ├── assets
    │   ├── css
    │   │   └── app.css
    │   ├── images
    │   │   └── favicon.ico
    │   └── js
    │       └── app.js
    ├── db
    │   ├── relation.rb
    │   ├── repo.rb
    │   └── struct.rb
    ├── operation.rb
    ├── relations
    ├── repos
    ├── structs
    ├── templates
    │   └── layouts
    │       └── app.html.erb
    ├── view.rb
    └── views
        └── helpers.rb

14 directories, 11 files

This is a great foundation to build a comprehensive, large slice, such as an admin panel. However, it feels a bit overwhelming for smaller-scope things.

Yesterday, while spelunking through Hanami internals, looking for a way to distribute a slice as a gemUnfortunately, I think it’s not easily done right now., I stumbled upon another way to define a slice. It is not described in the Guides, but is documented in the code - so I treat it as official.

The trick is this:

Drop a file into config/slices (a directory that doesn’t exist in a stock Hanami app)
That’s it. No subdirectory army required.

Let’s build one.

The tutorial part

We will start by creating a new Hanami app and creating a dir and a file.

hanami new myapp
cd myapp
mkdir config/slices
touch config/slices/healthcheck.rb

Now we will put an ultra-simple slice inside:

module Healthcheck
  class Slice < Hanami::Slice
  end
  
  class Routes < Hanami::Routes
    get "/", to: ->(_env) { [200, 
      {"Content-Type" => "application/json"}, 
      ['{"status": "ok"}']] }
  end
end

Finally, we mount this in our main app, in config/routes.rb:

module Myapp
  class Routes < Hanami::Routes
    slice :healthcheck, at: "/health"
  end
end

Now if we start the app, we can check that it works:

$ curl -i localhost:2300/health
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 16

{"status": "ok"}

Our micro-slice is up and running.

Why reach for micro-slices

As shown above, this is a great way to create a very focused, small slice, without all the ceremony of creating a directory in the slices directory. It might be useful if you mainly organize the slices by domain boundaries, but still need a couple of “technical” (non-domain) ones, for example to expose some metrics or to have an admin dashboard.

In absence of a good way to have externally packaged slices supported in Hanami… yet. I would like, at some point, to find time to try to solve this., it might pave the way to ship a “slice builder” in a gem.

Imagine shipping an “admin slice DSL” from a gem.

# config/slices/admin.rb
module Admin
  extend GemifiedAdminPanelSliceBuilder
  
  admin do
    section "E-Commerce" do
      page "Orders", schema: ECommerce::Schemas::Order
      page "Products", schema: ECommerce::Schemas::Product
      page "Shipping methods", schema: ECommerce::Schemas::ShippingMethod
    end
  end
end

The gem isn’t the admin slice — it just gives you a way to build one. This is still day-dreaming, but micro-slices show a legit path towards this goal.

Meanwhile, we can all enjoy our micro-slices, if needed.

Ecto, on_replace and deferred checks

2025-07-03T00:01:00+02:00

Today I learned a valuable lesson about how a seemingly simple task can have very rough edge cases, which take hours to solve. It involved Ecto, its associations and on_replace option, and uniqueness checks in the database. Here’s the story.

The problem

Let’s say you are modelling some kind of processes. These processes have steps and the steps have to be executed in a precise order. This is how a database structure for it would look like:

def change do
  create table(:processes) do
    add :name, :string, null: false
  end

  create table(:steps) do
    add :process_id, references(:processes)
    add :name, :string, null: false
    add :order, :integer, null: false
  end
end

It is fairly straightforward: the order of steps inside of a process is controlled by an order integer column. Since it is important to always have the order of steps precise, we would like to additionally ensure it by a uniqie index:

create unique_index(:steps, [:process_id, :order])

We also know that the steps are only edited via a parent process. There is a form in the application, where you can edit the process fields and add, change, delete steps for it. The payload sent to a server always includes all the steps. Armed with that knowledge we create Ecto schemas like this:

defmodule Core.Process do
  use Ecto.Schema
  import Ecto.Changeset

  schema "processes" do
    field :name, :string
    has_many :steps, Core.Step, on_replace: :delete, preload_order: [asc: :order]
  end

  def changeset(process, params) do
    process
    |> cast(params, [:name])
    |> cast_assoc(:steps)
  end
end

defmodule Core.Step do
  use Ecto.Schema
  import Ecto.Changeset

  schema "steps" do
    field :name, :string
    field :order, :integer
    belongs_to :process, Core.Process
  end

  def changeset(step, params) do
    step
    |> cast(params, [:name, :order])
  end
end

I did that, quite happily, tested a bit with adding, changing and removing some steps. Finally I merged the pull request.

It was only a few hours later when a colleague slacked me that something goes wrong. What he did was reordering the steps, or rather trying to do it. From this structure:

step 1, order: 1
step 2, order: 2

he wanted to go to

step 1, order: 2
step 2, order: 1

I quickly drafted code that replicated the issue:

proc =
  %Process{}
  |> Process.changeset(%{
    name: "Test",
    steps: [%{order: 1, name: "First"}, %{order: 2, name: "Second"}]
  })
  |> Repo.insert!()

proc = Repo.preload(proc, [:steps])
[s1, s2] = proc.steps

s1 = %{id: s1.id, name: s1.name, order: 2}
s2 = %{id: s2.id, name: s2.name, order: 1}

proc
|> Process.changeset(%{steps: [s1, s2]})
|> Repo.update!()

Attempt to run it resulted in an error:

** (Ecto.ConstraintError) constraint error when attempting to update struct:

    * "steps_process_id_order_index" (unique_constraint)

It took me a while to realize what’s going on: Ecto tried to update the existing steps, one by one. So the first operation was:

Update “order” of step 1 to 2

This left us with the following situation:

step 1, order: 2
step 2, order: 2

This, quite obviously in retrospect, triggered the unique index. You cannot have 2 steps for one process with the same order! It did not matter that right after you were going to update step 2’s order to 1. The index operates here and now, you cannot do that.

The solution

After discovering I was pretty close to writing my own hacky solution to update the steps, including inefficient approach with first deleting all and then creating all anew. Fortunately, in time, I vaguely remembered that there is something called deferrable constraints in PostgreSQL.

Deferrable constraint waits until the end of the transaction with checking if its condition is met. This was exactly what I was looking for! But an index cannot be deferrable in PostgreSQL. Luckily, another very similar construct - a uniqueness check - can.

In the migration above, I had to replace the index creation with this:

execute """
ALTER TABLE steps ADD CONSTRAINT unique_step UNIQUE (process_id, "order") DEFERRABLE INITIALLY DEFERRED
"""

With this statement we create a constraint on the steps table which checks uniqueness of two columns and not only is deferrable - it is deferred to be checked on transaction commit by default.

This is really all I had to do. The Ecto’s association replacing mechanism started working perfectly.

This proved once again a truth I knew: the database is not a dumb storage you can just gloss over. It always pays off to learn it, its capabilities and intricacies. Because then you end up with a simple change instead of rewriting part of Ecto, but poorly.

Putting Hanami in the browser via WASM

2025-06-23T00:01:00+02:00

The other day I was loosely listening to a Code and the Coding Coders who Code it podcast episode with Vladimir Dementyev. He was talking about his work around putting Ruby on Rails into the browser to lower the entry barrier for folks who just want to “feel” it, but witohut going through the struggle of choosing a correct Ruby version manager, installing dependencies for gems with C extensions etc.

And I thought: Wow, great!

And I also thought: If it’s (almost) possible with Rails, it should be even more possible with a truly modular framework, such as Hanami.

Despite not knowing a thing about WASM, I decided to give it a go. I had my first working version running in about half an hour. Then the reality struck and I spent another 6 hours figuring stuff, reading code by Vladimir and his e-book and banging my head against my keyboard.

Fortunately, after all this, I had a working version of a Hanami action (with validations) in the browser. You can get the code here.

Since the WASM package is 50MB in size, it does not fit Cloudflare Pages limits and I have read too many stories about putting large files on Netlify. So I bought a very cheap VPS and put the demo there. Here it is (I hope it still works when you are reading this post).

Some details and thoughts

This is a bit unstructured feed of my thoughts and learnings from this experiment:

Everything related to Ruby and WASM goes through the ruby.wasm repository, which is under Ruby official org on Github. It mainly (for me) contains a ruby_wasm tool, available via gem, which does all the heavy lifting.
However, things are not that simple when you need to have custom gems available in your WASM package. In my case the problem was with Hanami::Utils, which rely on BigDecimal at the time of writing this. BigDecimal is one of the gems known to not compile to WASM due to… something.
To resolve the above, I had to resort to a trick mentioned by Vladimir in the podcast - provide a dummy implementation of BigDecimal instead.
… and I also had to force WASM compiler to skip attempting to compile the gem by overriding its internals.
I learned a lot from Vladimir’s e-book Ruby on Rails on WebAssembly and probably even more from the code he wrote. These are excellent resources if you want to learn about Ruby and WASM. As my example proves, you can get started in quite short time.
Remember that this is just an action with validation (hanami-controller and hanami-validations gems), instrumented manually, not going through any router and not doing anything like and actual HTTP request. So this is quite far from putting the whole framework in WASM - also because of current limitations of WASM and its Ruby support.

Some code snippets

This is perhaps the most important part - fetching the WASM package and initializing a virtual machine with our gems and shims:

const wasmResponse = await fetch(wasmUrl);
const wasmBuffer = await wasmResponse.arrayBuffer();
console.log("WASM buffer size:", wasmBuffer.byteLength);

const module = await WebAssembly.compile(wasmBuffer);
const { vm } = await DefaultRubyVM(module);

console.log("Custom WASM loaded successfully!");

vm.eval(`
    $LOAD_PATH.unshift "/shims"
    require "/bundle/setup"
    require "hanami/controller"

    module WasmApp
      class Action < Hanami::Action
      end
    end

    def run_action(cls, request)
      action = cls.new
      response = action.call(request)
      response.body.first
    end
`);

return vm;

And this is the code taking contents from the editor and running it, using the run_action method defined above:

async function runRubyCode() {
    result = null;
    isRunning = true;
    if (!vm) vm = await initVM();

    const ruby = editor ? editor.getValue() : editorValue;
    const serializedParams = serializeParams();
    const paramsString = JSON.stringify(serializedParams);

    try {
        result = vm.eval(`
            ${ruby}
            run_action(TestAction, ${paramsString})
        `);
        isRunning = false;
    } catch (error) {
        console.error("Execution failed:", error.message);
        isRunning = false;
        result = error.message;
    }
}

This also provides very basic error handling and will put the error in the browser.

Finally, the builder script that assembles a WASM package to be used by frontend:

require "ruby_wasm"
require "ruby_wasm/packager"
require "ruby_wasm/cli"
require "fileutils"

RubyWasm::Packager::EXCLUDED_GEMS << 'bigdecimal'
cli = RubyWasm::CLI.new(stdout: $stdout, stderr: $stderr)
args = %W(build --ruby-version 3.4 -o ruby-web-temp.wasm --build-profile full --stdlib)
cli.run(args)

args = %w(pack ruby-web-temp.wasm --dir shims::/shims -o src/ruby-web.wasm)
cli.run(args)

FileUtils.rm "ruby-web-temp.wasm"

This is all I have. It was a fun experiment with a completely new (to me) technology. Apparently it’s not hard to start with, but there’s a lot of dragons and rough edges still. But I learned something new and it was worth it.