Alchemists: Articles

Joy of the Craft

2026-10-01T13:59:52+00:00

Joy of the Craft

This collective was founded on a simple idea that you should enjoy the work you do including a strong sense of purpose in order to enrich the lives of your team and customers combined. Profit, while important to keep the lights on, is not the driving force. Building expertise and using software to make life more enjoyable for folks is much more rewarding. Plus, it feels good to wake up each morning knowing you are working in a code base that is well maintained, always up-to-date, a joy to use, and a benefit to society.

The Engineer’s Oath helps us never lose sight of our purpose while our Engineer’s Rigor keeps us honest because you can’t make an impact in life if your environment, codebase, and team is in constant disarray. This definitely takes work, which isn’t always fun but, as the saying goes, nothing in life worth achieving is easy.

This also means having grit to persevere when things get tough and integrity to do the right thing when no one is looking. For comparison, let’s look at the work of others who exhibit some or all of these qualities.

Table of Contents

Crafters
Sharpening the Saw
Expert Beginners
Conclusion

Crafters

Software engineering is both an art and a science. When expertly — and seamlessly — blended together, that’s where the magic exists.

You’ve probably seen or worked with people — if lucky — which are the embodiment of joy while also being extremely skilled at the craft. Jon Batiste, is one example, where his joy exudes from the stage, interviews, and especially in his music. Here’s a few others:

Leonardo da Vinci: Often cited as champion of the High Renaissance not to mention an accomplished artist and engineer known for being a perfectionist where some ideas didn’t see the light of day and while other ideas took years to complete.
Antoni Gaudí: Devoted much of his life to the Sagrada Família, sometimes living on-site in his final years. He designed structural solutions decades ahead of the engineering math that would later validate his ideas.
David Bowie: One of the greatest rock artists, and chameleon, that would constantly reinvent himself every few years (or less) to push the boundaries of what was possible. His last album, Blackstar, was released only a few days before his death.
Neal Pert: After being known as an excellent drummer in Rush, he relearned how to play the drums by practicing with jazz drummer Freddie Gruber in order to hone his skills further.
Sheel Joshi: An award winning, Michelin recognized, chef who is a master of the craft of Indian cuisine. Doesn’t take long, after experiencing his cooking and getting the chance to talk with him, to know that he cares about the craft and sharing that joy through food. To quote from his site: "A gathering place shaped by story and technique. A kitchen defined by heart."
Jiro Ono: Embodies shokunin (see below) ethics of duty and perfection while also known for a tough apprenticeship culture which even excluded his eldest son.

What each of the above have in common is a mastery of the craft through constant rigor. They held onto human ingenuity and inherit skill to achieve greatness while sharing the fruits of their labor in order to bring joy to millions of others. May we all strive for the same.

Sharpening the Saw

You’ll find, in many cultures, that rigor and grit are necessary to hone your craft in order to achieve expertise and a life worth living. The Japanese are especially well versed in this practice with many words representing various forms of this concept:

Shuhari (守破離): This has been discussed before but shuhari is the life long pursuit of improving your craft by starting as an apprentice, evolving as a journeyer, and finally gaining mastery as a crafter. While mortally impossible to gain complete mastery, journey is where the joy the resides, not the destination.
Shokunin (職人): Translates to artisan or craftsman which means one who endlessly pursues mastery of the craft with a strong sense of purpose and joy. This includes moral, ethical, and social consciousness to weld the craft for the benefit of others. Sound familiar? Yep, there’s the Engineer’s Oath again.
Kaizen (改善): Translates as improvement and is most notably attributed with The Toyota Way of working through constant improvement and refinement of processes. This includes a strong emphasis on quality including halting production if quality ever drops below a specific threshold. In terms of software, a good example of this is Ruby Code Quality.
Takumi (匠): Means artisan, master crafter, or skilled expert. This harkens back to shuhari which is someone who has achieved mastery of the craft through decades of unyielding practice.
Tatsujin (達人): An expert who has arrived at mastery and who has attained the deepest level of the craft through intuitive, tacit, and effortless skill.
Dojo (道場): Literally means place of the way which is where folks gather to form unions, guilds, and places of continuous learning.

Habits are the key to achieving the above but can take time to become instinctual. It would be amazing to be like Neo, in The Matrix, and instantly learn new skills with all the knowledge, experience, and wisdom necessary in only a few seconds but, unfortunately, that’s now how we gain experience. First we learn, then we apply, and slowly we gain experience by testing the limits of our knowledge in new and interesting ways to unlock new ideas. For example, the path to software engineering mastery might look like this:

Learning the basics of the language by first writing simple programs and then advancing to more complex architectures.
Adding linters, code quality checks, keyboard shortcuts, macros, and anything that augments your workflow while enforcing consistency across all codebases.
Learning patterns and antipatterns including when to apply them and when alter them in elegant ways.
Extracting hard problems, solved well, as gems for reuse in other projects.
Learning from and constantly evolving design choices which might mean refactoring large chunks of an application or multiple gems in order to maintain consistency. This can be painful but is critical to building experience and new learnings on what to do and what not to do.
Writing and sharing your learnings with others. If you can’t explain it, then you haven’t learned it.
Creating video tutorials to augment your writings.
Speaking at conferences and connecting with others to spread new ideas and ways of thinking.
Writing books and becoming a knowledge expert in general.
Advancing and constantly evolving to the point where most knowledge is tacit and intuitive. There will always be new challenges but they become faster to debug and solve. This is pure gold because it’s hard won and no one can take that away from you.

This is how you keep the saw sharp.

Expert Beginners

The antithesis of those who don’t practice or understand the joy of the craft are known as an Expert Beginner. These are people who hit a fork in the road and make the tragic mistake of heading down the path of supposed, or self-declared, mastery when they couldn’t be father from the truth.

In short, and much has been written on this already, Expert Beginners tend to stagnate with minimal to no growth. They also have minimal to no ambition. This includes farming out learning, understanding, and personal growth to Large Language Models (LLMs). In some cases, they willingly give up what little expertise they have in favor of handing everything over to an LLM (also known as brain rot). This is akin — and vastly simplified — to playing slot machines and hoping, this time, randomness favors your weakness. Worse, LLMs churn out the lowest common denominator of collective knowledge. This is because LLMs can’t think, can’t remember, and can’t experience growth like humans can. Lastly, Expert Beginners definitely don’t care about software architecture, code quality, maintenance, or team happiness.

Take the red pill, not the blue pill, to avoid becoming an Expert Beginner. Build upon what makes you unique and then share that joy with others.

Conclusion

There will always be liars, grifters, ghosters, fraudsters, and unsavory folk of weak constitution but this is a reminder that there is a better path in life. Harder, definitely, but much more rewarding and worth it in end.

If this appeals to you and you truly care about the craft and the joy of getting up each day to tackle new challenges, learn new skills, write elegant code, and share what you know with others then join our community or add your name to the list of Hand Crafted Coders. We’re constantly working to share the joy by building a better future. We only have one shot at this life, so let’s enjoy it!

Request for Comments (RFCs)

2026-09-01T12:06:06+00:00

Request For Comments (RFCs)

Request for Comments (RFCs) are the official guiding documents that shape the internet via technical standards, protocols, and procedures. This encompass the following:

HyperText Transfer Protocol (HTTP)
Transmission Control Protocol (TCP)
Internet Protocol (IP)
Domain Name System (DNS)
Transport Layer Security (TLS)

RFCs are also the primary output of the Internet Engineering Task Force (IETF) which was founded in 1986.

The following will help you stay on top of the ever changing RFC landscape.

Table of Contents

Highlights
Gems
Tools
Syndication
Conclusion

Highlights

There are a lot of RFCs to read through. At the time of this writing, there are 10,042 total. We don’t have time to go through them all. That said, here’s a few of my favorites (if not already aware, yourself):

RFC 5545 (Internet Calendaring and Scheduling Core Object Specification (iCalendar): While not the greatest specification, due to the complexity of the format used, this provides the specification for sharing of calender information.
RFC 6648 (Deprecating the "X-" Prefix and Similar Constructs in Application Protocols): Specifies avoiding the use of x- prefixes for custom HTTP headers. If you are using custom header like this, please stop.
RFC 8288 (Web Linking): Specifies how to provide links, especially, navigation which allows you to provide rich information in HTTP responses for any content, not only APIs.
RFC 8615 (Well-Known Uniform Resource Identifiers (URIs)): Specifies the files and formats in the /.well-known/ directory at the root of your site. These are authoritative and machine readable for discovery and information about your site. Sadly, some files don’t adhere to this specification and live at the root of your site. Examples: robots.txt, humans.txt, and sitemap.xml.
RFC 9110 (HTTP Semantics): Specifies all semantics for making HTTP requests/response especially all verbs and how to use them (see Section 9.3).
RFC 9113 (HTTP/2): Lots to read but important to note that header keys must be lower case (see Section 8.2).
RFC 9114 (HTTP/3): As mentioned with HTTP/2, above, header keys must be lower case (see Section 4.2).
RFC 9264 (Linkset: Media Types and a Link Relation Type for Link Sets): Compliments RFC 8288 by specifying a JSON set of links which is especially handy when the number of links might be large by pointing to a specific, cacheable, document.
RFC 9309 (Robots Exclusion Protocol): Specifics how to use robots.txt that must be at the root of your site (sadly, does not adhere to RFC 8615).
RFC 9457 (Problem Details for HTTP APIs): Specifies how to provide structured responses for API errors. If you’re not using this already, definitely start.
RFC 9745 (The Deprecation HTTP Response Header Field): Specifies how to indicate to clients that the endpoint is deprecated including a future date/time so you know how long you have to make changes on your end. Plays nice with RFC 8288 (mentioned above).
RFC 10008 (The HTTP QUERY Method): Adds the new HTTP QUERY verb which is a hybrid of GET and POST requests which allows you to make idempotent GET requests but with the power of POST to supply a body of search criteria that would otherwise be too much for a GET request.

Gems

Some RFCs can be quite involved in terms of what is needed for compliance. This is where a Ruby gem is a powerful solution in being able to provide an implementation for each specification. This allows you reuse a single implementation across multiple applications. A few of the following projects provide implementations to a couple of the RFCs mentioned above:

RFC API Problem: A RFC 9457 Problem Details for HTTP APIs implementation.
RFC Web Link: A RFC 8288 Web Linking implementation.

Definitely recommend adding to your stack to enhance your HTTP responses/requests further.

Tools

To augment your workflow, you’ll want tap into the following tools for quick information sourcing including staying on top of the latest changes within the industry:

RFC Editor: The primary source of information where you can search and read up on all RFCs as well as subscribe, via syndicated feed, for all of the latest news and information.
RFC Explorer: Provides a graphical interface to all RFCs as nodes linked to each other. This allows you to click on each RFC (node) to dive further, zoom in and out, etc. The main interface groups all material by areas of work. Unfortunately, there isn’t a way to quickly search by RFC number.
IETF Datatracker: The primary database for authors and maintainers of RFCs. The best part about this tool is a visual timeline at the top of each RFC which provides a clear and quick understanding of the RFC over time.
IETF Diff: Handy for comparing and contrasting the changes between document revisions.
Pennyworth: For Alfred fans, this gem allows you to quickly access the RFC Editor, search, and fuzzy type to lookup documentation on any RFC.

Syndication

Syndication is a powerful way to stay on top of the changes being introduced. You can subscribe via RSS or Atom by adding the RFC Editor URL to your feed reader and letting it do the work of informing you when new changes are posted.

Conclusion

As software engineer, especially in web development, staying on top of the latest RFCs news and information is critical. Even better, automatically getting the latest updates via syndication allows you to learn about changes within the industry with minimal effort.

Enjoy and may your stack be built upon the wisdom of others.

Big Sky Dev Con 2026

2026-08-01T16:10:18+00:00

Big Sky Dev Con 2026

After attending Big Sky Dev Con 2024, a couple years ago, and meeting some of the htmx team, I became interested in the conference and was eager to return as a speaker. In 2025, I submitted my Milestones talk but, sadly, wasn’t accepted. This is a shame because Milestoner is used to fully generate all versions and corresponding release notes for all projects. The UI uses htmx which is perfect for statically generated content. Can’t live without it! …but I digress.

This year, thankfully, my htmx View Transitions talk was accepted and glad it was because I had a great time presenting, talking to folks, and enjoying the conference. The conference organizers have definitely stepped up their game in terms of quality of presentations and venues.

The following are a few notes and learnings captured from the conference that might be of interest.

Table of Contents

Speakers Dinner
Talks
- Day 1
- Day 2
Conclusion

Speakers Dinner

Originally scheduled for Wednesday, the night before the conference kicked off, the dinner ended up taking place after the conference ended on the first day.

Most impressive was the work Duncan put into this and the team behind this. The crew drives out, each year, from Utah with frozen BBQ, rents an AirBnB, and then spends a couple days cooking and prepping the food. Everything was delicious with a fantastic spread.

Talks

This year the conference consisted of a day and a half of talks with things kicking off at ~3pm on Friday at The Rialto and running all day on Saturday at Montana State University.

Day 1

As mentioned above, the first day was at the The Rialto. I arrived at 1pm to double check my display and portable WiFi router worked properly. This proved wise since the macOS display bug cropped up again which yielded a black screen. Thankfully the video crew had an extra video converter which resolved the problem.

James Collins, Lazarus Morrison, and Carson Gross showed up shortly after. While chatting with Carson, I learned of Fil-C which might be of interest to folks that might want modern — and compatible — C/C++ tooling that is memory safe.

Executor, Orchestrator, Leader! by Jaron Jones

Jones kicked off the conference by discussing how ownership and quality of your work is so important. You can’t give up on the fundamentals and let the brain rot consume you in this Age of Slopware.

Falling in Love with SQL by Adam Rackis

Rackis spent the core of the talk looking at execution plans. These are good skills to have so make sure to watch the video. This talk also pairs well with Jerason Banes talk on using pure SQL in general.

htmx View Transitions by Brooke Kuhlmann

This was my talk which focused entirely on CSS View Transitions using htmx and Ruby. The slides and ePaper devices (passed out to the audience) were completely rendered live via Terminus. You can find the slides here: htmx View Transitions.

At the end of the talk, I suggested an improvement to the htmx library where you could provide a callback into the View Transitions API for more granular control and Carson Gross mentioned this Michael West who folded the change into htmx 4.0.0!

JavaScript? In This Economy? (A Love Letter to Tailwind and modern CSS) by Anthony Alaribe

This is the second time seeing Anthony speak. This time he had interesting insights into how you can use Tailwind to programmatically control behavior by using the :has and :is pseudo-classes along with the if() function.

I would never recommend Tailwind since the output always looks like someone barfed all over your source code. That said, using CSS to conditionally style a site based on which classes are present is worth knowing about. Alternative ways to tackle this would be via data attributes, hidden check boxes, and so forth. For example, this site uses a hidden checkbox to toggle a collapsed main menu when viewing on smaller devices. All using CSS, no JavaScript!

HTML is not just for the web by Lazarus Morrison

Morrison closed out the day by discussing his HypeApps project which provides enhanced HTML elements for building applications that can run on multiple platforms. Without having a chance to play with this more, this seems like a highly tailored, custom collection of web components without all of the JavaScript setup. The framework is built upon Flutter and pairs well with Marcus Twichel’s talk who also uses Flutter.

Day 2

The second day was held in the Strand Union Building on the Montana State University campus. I found this to be more enjoyable than The Rialto because you had more space to setup your laptop, take notes, enjoy better lighting. Enjoyed being on the college campus as well.

Getting off the Modernization Treadmill by Alexander Petros

Alexander kicked off the day by first mentioning the book Recoding America by Jennifer Pahlka which tied in well with the staggering numbers of government waste related to software development. Having tackled several government contracts in the past, I know this only too well. This is also a talk about software bloat and love that he emphasized the following:

Avoid JavaScript. Stick to pure HTML and CSS. Let the browsers upgrade for you in terms of performance and security fixes.
Avoid React entirely and lean in on native HTML and CSS support.

Agentic Engineering for JVM Developers by Thomas Schilling

Perhaps one of the only speakers who traveled the farthest distance by coming from Stuttgart, Germany to speak. This talk was entirely focused on AI automation via these four steps:

Tell, Watch, Steer
What To Do, How To Do It
Behavior - User Interaction
Sliced Loops

He also mentioned checking out Grill with Docs for further tweaking of your agents. Check out his site and slides for further details.

Your Business Doesn’t Fit on a Phone — Neither Should Your Flutter App by Marcus Twichel

This talk was all about using Flutter to run on iOS, macOS, Android, web, and other platforms with real-time communication and synchronization. This included a live demo which focused on a fake coffee store scenario where an audience member would order a beverage and we’d watch the transaction process in real-time across multiple platforms.

This was a good demo and definitely can see why folks would be attracted to using Flutter. The problem is Flutter is Google’s solution for this much like React is for Facebook and we all know how awful that has become especially for those that cargo cult these platforms — without thinking through the ramifications — by using a big hammer to solve the wrong problem.

This is why checking out Alexander Petros' talk is well worth your time because focusing on modern HTML and CSS can get you a long way including leaning into Progressive Web Apps. Minimizing your stack, reducing your dependencies, and avoiding complicated builds in order to release new versions of your software reduces your maintenance burdens. Not saying this is always the right solution but should definitely be the first thing you consider before going down the Flutter/React path.

I have no idea what I’m doing by Ronan Berder

During the speakers dinner I ended up driving Ronan home despite both of us staying at opposite ends of the city so was a chance to chat. His talk ended up being a self deprecating talk on entrepreneurship especially the failures and mistakes. This makes the talk unique since people don’t always share the missteps of success.

A couple insights worth noting from his talk:

Hacker News has a section where you can post about open source. Each submission must be prefixed with "Show HN: " followed by the project name and a brief description. A landing page, repository, or demo of your work is what is preferred. Keep it short but technical, no marketing.
Siddharta by Hermann Hesse might be worth a reading since it’s about a spiritual journey of self-discovery.

Check out Ronan’s writings and open source to learn more.

Lessons from our Hardware on the ISS: Running a Linux Stack Beyond the Cloud(s) by Mike Frandsen

Insightful talk on running code in Space with limited hardware, resources, and connectivity. This talk focuses on the Cambrian Works Gig Router and lessons learned such as:

Review your defaults.
Ensure your systems are idempotent.
Use structured logging.

Ended up talking to Mike a bit afterwards because I was curious about the structured logging hurdles they faced especially since I maintain the Cogger gem which supports structured logging.

Cognitive Vandalism: What I Learned by Mutilating a GPT by Barrett Breshears

This was a humorous talk, plus clever engineering, which focused on messing with pre-trained models by removing layers, duplicating them, injecting gibberish, and more. The results were rendered live producing ridiculous results in order to illustrate how the models function.

Worth checking out when the video for more.

Prompt Engineering Isn’t Enough: Building AI Agents You Can Steer by Sandhya Subramani

This was the only talk that didn’t land for me. The entire presentation was a lot like a marketing demo that had been given multiple times to companies and/or engineering teams. This would add up since Sandhya is a developer advocate which means traveling all over and talking about the same thing. Anyway, the talk was focused on using Strands Agents as an open source solution for building production agents.

ORMs are Killing Your Performance by Jerason Banes

This was a good talk about ditching the use of Object-Relational Mappers (ORMs), using functional transformer pipelines to manipulate key/value pars to produce the results you need, and streaming content from the database.

This also planted a seed for further exploration because I’d like to rip out Hanami's use of Ruby Object Mapper and explore pure SQL as well since there’s been very little progress with the Ruby Object Mapper stack for years.

Intro to Compression Techniques by Lance Fisher

Good talk — along with helpful visuals — on different compression techniques such as gzip, brotli and others. Worth checking out the video especially if you have an interest in the different compression algorithms.

Real-Time Hypermedia (the htmx way) by Christian Tanul

Christian is a member of the htmx Core team and traveled from Romania to speak so was a bit jet lagged. The talk was also a bit discombobulated as a result. That said, I loved learning about the multipart/mixed HTTP Content-Type header which allows you to stream mixed data via a single connection! This has been part of the HTML spec since 1992 but I’ve never seen anyone talk about this before.

Use of multipart/mixed is also more versatile than Server Sent Events, which I recently wrote about, so plan to explore and write about this more in the future.

By the way, Christian’s work is folded into the hx-multipart extension which you can use in htmx 4.0.0.

htmx 4: What’s New by Carson Gross

Carson closed out the conference with an overview of htmx 4.0.0 features. Here’s a few highlights:

A strong focus and return to established web standards.
As mentioned at Big Sky Dev Con 2024, Carson continues using social media to play the game while staying true the cause.
htmx 4.0.0
- Will include an upgrade helper.
- Will support declarative partial updates via the new hx-partial element (think template but enhanced).
- A new hx-action and hx-method methods which taps into Alexander Petros' Triptych project. Super cool!
- A new hx-alpine-compat attribute that smoothes out interaction with Alpine.js.
- Much more!

The best part — and epic ending to the entire conference — was when Carson mentioned the Gameboy game for htmx 4.0.0 and then handed the mic to Stephen Mitchell to explain the development of the game, the design, levels, and access to the source code. Even better, as conference attendees, we all got a copy of the game!

The only bad aspect of this is that the game is labeled as a Golden Master but — for all us that lived through that era and knows what this means — this isn’t a Golden Master, only a Beta. Use of Golden Master is incorrect and misleading.

Both Carson and Stephen were channeling a Steve Jobs kind of vibe with the release of the htmx 4.0.0 and the corresponding game (watch). Loved it and definitely made the conference special.

Stephen closed with "Don’t stop caring and love your craft". This resonates deeply because this site and my entire career has been focused on the Joy of the Craft. This also coincides with another great quote, above a bench, while walking the Montana State University campus:

I want our graduates to leave here with the clear understanding that ethical purpose and pursuit of knowledge are higher life goals than the pursuit of profit.

— Michael P. Malone

In the Age of Slopware, don’t forget what it means to create high quality, well architected, and maintainable code. Sweating the details of good quality software — both inside and outside — is important. Don’t lose that!

Conclusion

This, by far, has been the best conference of the year. Glad I was able to attend and speak. The entire team has stepped up their game since I was last here in 2024. Loved being on the college campus and being back in my home state. In some ways, this is a bit of a full circle for me by being able to share the joy of the craft with others that started several decades ago.

Looking forward to attending in 2027 and hope you consider this conference in the future as well!

Server Sent Events

2026-07-01T12:06:32+00:00

Server Sent Events

Server Sent Events (SSE) allows a server to push data, one way, to a client over a long lived HTTP connection without the client needing to make multiple requests. Even better, the client will automatically reconnect if the connection drops. Here’s a few use cases that SSE is great for:

Real-time notifications.
Live dashboards.
Live edits and rendering of updated content.
Progress updates of long running tasks.

Implementing SSE is fairly trivial in Ruby especially when using Rack 3.0.0 middleware and htmx on the front end so let’s explore further by diving into the code!

Table of Contents

Quick Start
Ruby
- Gems
- Dependencies
- Event Source
- Middleware
- Rack
HTML (htmx)
curl
Falcon
Running
Specs
Conclusion

Quick Start

If you’d prefer to have all of the code and start playing around, you only need these two files:

Ruby

Save as demo and run chmod 755 demo to make it executable.

#! /usr/bin/env ruby
# frozen_string_literal: true

# Save as `demo`, then `chmod 755 demo`, and run as `./demo`.

require "bundler/inline"

gemfile true do
  source "https://rubygems.org"

  gem "amazing_print"
  gem "cogger"
  gem "containable"
  gem "debug"
  gem "infusible"
  gem "initable"
  gem "puma"
  gem "rack"
  gem "rackup"
end

module Container
  extend Containable

  register(:logger) { Cogger.new id: :demo }
end

Dependencies = Infusible[Container]

class EventSource
  include Dependencies[:logger]
  include Initable[%i[req id], kernel: Kernel]

  def call stream
    write stream
  rescue Errno::EPIPE, Errno::ECONNRESET, IOError
    logger.debug { "Event stream disconnected." }
  ensure
    stream.close
  end

  private

  def write stream, count: 1
    kernel.loop do
      stream.write <<~CONTENT
        event: demo
        data: Found: #{id}, Count: #{count}

      CONTENT

      count += 1

      sleep 0.5
    end
  end
end

class Middleware
  include Initable[
    %i[req application],
    %i[keyreq pattern],
    headers: {
      "Cache-Control" => "no-cache",
      "Content-Type" => "text/event-stream",
      "X-Accel-Buffering" => "no"
    },
    event_source: EventSource
  ]

  def call environment
    request = Rack::Request.new environment
    path = request.path

    case path.match pattern
      in id: then [200, headers, event_source.new(id)]
      else application.call environment
    end
  end
end

application = Rack::Builder.new do
  use Middleware, pattern: %r(^/sse/(?<id>.+)$)
  use Rack::Static, urls: ["/"], root: ".", index: "index.html"

  run proc { [200, {"content-type" => "text/plain"}, ["Demonstration"]] }
end

Rackup::Server.start app: application

HTML

Save as index.html.

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">

    <title>Demo</title>

    <meta charset="utf-8">
    <meta name="description" content="A demo site.">
    <meta name="author" content="Alchemists">

    <style type="text/css">
    </style>

    <script src="https://unpkg.com/htmx.org@2.0.10"
            integrity="sha384-H5SrcfygHmAuTDZphMHqBJLc3FhssKjG7w/CeCpFReSfwBWDTKpkzPP8c+cLsK+V"
            crossorigin="anonymous">
    </script>

    <script src="https://unpkg.com/htmx-ext-sse@2.2.4"
            integrity="sha384-A986SAtodyH8eg8x8irJnYUk7i9inVQqYigD6qZ9evobksGNIXfeFvDwLSHcp31N"
            crossorigin="anonymous">
    </script>
  </head>

  <body>
    <p hx-ext="sse" sse-connect="/sse/1" sse-swap="demo">Loading...</p>
  </body>
</html>

Once you’ve saved the above to disk, you should have the following files:

index.html
demo

To launch the application, run: ./demo. The open http://localhost:9292 in your default web browser. The rest of this article will explain how all of this works.

Ruby

With the above, we are using a Bundler Inline script for demonstration purposes. Normally, you’d want to use Rubysmith to split the implementation into separate files but keeping all of this together, for now, allows you to quickly experiment with the code.

Gems

At the top of Bundler Inline script, several gems are installed for you. The following breaks down why each is used:

Ruby
- Amazing Print: For pretty printing of inspected objects.
- Cogger: For logging.
- Containable: For dependency injection containers.
- Debug: For debugging code.
- Infusible: For automatic dependency injection.
- Initable: For automatic initialization.
- Puma: For serving web content.
- Rack: For building modular web applications.
- Rackup: For launching rack middleware.
htmx: For sending HTML fragments over the wire.
- htmx SSE Extension: For processing and rendering SSE.

Dependencies

Next, we register and prepare our dependencies for automatic injection:

module Container
  extend Containable

  register(:logger) { Cogger.new id: :demo }
end

Dependencies = Infusible[Container]

This allows us to leverage dependency injection containers for dependency injection via Containable and Infusible respectively so we can register and inject Cogger for logging purposes.

Event Source

Next, we have our event source:

class EventSource
  include Dependencies[:logger]
  include Initable[%i[req id], kernel: Kernel]

  def call stream
    write stream
  rescue Errno::EPIPE, Errno::ECONNRESET, IOError
    logger.debug { "Event stream disconnected." }
  ensure
    stream.close
  end

  private

  def write stream, count: 1
    kernel.loop do
      stream.write <<~CONTENT
        event: demo
        data: Found: #{id}, Count: #{count}

      CONTENT

      count += 1

      sleep 0.5
    end
  end
end

The logger and kernel are injected as dependencies while the id is required for loading of a record associated with the ID. For demonstration purposes, we only print the ID to avoid setting up a persistence layer since you can do that on your own if you like.

In order to adhere to Rack 3.0.0 specification for event streaming, we only need make our event source callable by implementing the #call method which does the following:

Writes to the given stream.
Gracefully handles errors by logging them.
Ensures the stream is always closed.

You’ll notice the private #write method loops indefinitely on a 0.5 second sleep schedule. In order to make the output interesting, a counter is incremented but, again, you’d normally be loading or processing data to write to the stream instead of updating a simple counter.

When writing to the stream, you always need the following keys:

event: The event name (or identifier). In our case, demo is our name. We’ll look for this even in our htmx client shortly.
data: The actual data we want to return.

Both the event and data data keys must be on separate lines followed by two new lines. Example (with new lines included for demonstration purposes:

event: demo\n
data: Found 1, Count: 5\n
\n

It’s critical that you always adhere to this format or your events will be corrupted. It’s important to note that you can use multiple data keys if necessary. Example:

event: demo
data: Found 1
data: ,
data: Count: 5

The above will be automatically concatenated for you and is identical to the following:

event: demo
data: Found 1, Count: 5

If you need to keep writing to the stream in order to keep the stream alive, so-to-speak, you can drop the data key to use a colon:

event: demo
: A comment.

Some call this a pulse or a heartbeat to prevent the stream from disconnecting especially when your writes to the stream are infrequent. All comments are ignored by your client (basically a no operation). Again, only useful if your updates are infrequent in order to keep the connection open.

Middleware

In order to be compatible with Rack, our middleware must be callable:

class Middleware
  include Initable[
    %i[req application],
    %i[keyreq pattern],
    headers: {
      "Cache-Control" => "no-cache",
      "Content-Type" => "text/event-stream",
      "X-Accel-Buffering" => "no"
    },
    event_source: EventSource
  ]

  def call environment
    request = Rack::Request.new environment
    path = request.path

    case path.match pattern
      in id: then [200, headers, event_source.new(id)]
      else application.call environment
    end
  end
end

We also need to require application as the first positional parameter. Everything else is optional. Each, optional, keyword parameter is:

pattern: This allows us to match the request path based on regular expression pattern. This also makes this middleware reusable for different routes that need shared behavior.
headers: The first two headers are required for being in compliance with Server Sent Events. The X-Accel-Buffering is optional but aids in being compatible with Nginx load balancers.
event_source: This is our EventSource object, as discussed earlier, which aids in swapping in different implementations if desired.

It’s worth pointing out, depending on your situation, that you might want to modify the case statement as follows:

case path.match pattern
  in id:
    environment["puma.mark_as_io_bound"].then { it.call if it }
    environment["rack.session.options"].then { it[:skip] = true if it }
    [200, headers, event_source.new(id)]
  else application.call environment
end

The first line allows you to make use of the Puma feature that allows you to mark your Server Sent Event as I/0 bound so it can exceed the normal thread pool maximum for I/O operations that are usually slower. This pairs well with Puma’s max_io_threads configuration setting.

The second line allows you to skip sending your Rack session/authentication/cookie information with each event since you only need to send this once upon initial connection. Otherwise, you’ll see duplicate sessions pile up with each response which is definitely not what you want when streaming events.

Rack

The last part of our script uses Rack::Builder to add our middleware, serve static assets (especially our index page), and run our demonstration application.

application = Rack::Builder.new do
  use Middleware, pattern: %r(^/sse/(?<id>.+)$)
  use Rack::Static, urls: ["/"], root: ".", index: "index.html"

  run proc { [200, {"content-type" => "text/plain"}, ["Demonstration"]] }
end

Rackup::Server.start app: application

Again — and as mentioned earlier — you’d split all objects out to separate files and use a config.ru file to launch your Rack app but keeping all this logic in one file makes this easier to demonstrate.

That’s it for our Ruby code. Now let’s look at our htmx client.

HTML (htmx)

htmx is great for having a simple client for consuming our Server Sent Events:

<!DOCTYPE html>

<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">

    <title>Demo</title>

    <meta charset="utf-8">
    <meta name="description" content="A demo site.">
    <meta name="author" content="Alchemists">

    <style type="text/css">
    </style>

    <script src="https://unpkg.com/htmx.org@2.0.10"
            integrity="sha384-H5SrcfygHmAuTDZphMHqBJLc3FhssKjG7w/CeCpFReSfwBWDTKpkzPP8c+cLsK+V"
            crossorigin="anonymous">
    </script>

    <script src="https://unpkg.com/htmx-ext-sse@2.2.4"
            integrity="sha384-A986SAtodyH8eg8x8irJnYUk7i9inVQqYigD6qZ9evobksGNIXfeFvDwLSHcp31N"
            crossorigin="anonymous">
    </script>
  </head>

  <body>
    <p hx-ext="sse" sse-connect="/sse/1" sse-swap="demo">Loading...</p>
  </body>
</html>

With the above, we require the htmx library and associated htmx SSE Extension extension for consuming and rendering events. You’ll notice that our path (/sse/1) maps to the same path used to configure our middleware and the event name, demo, also maps to the name used in our EventSource implementation. This is what connects the client and server together.

curl

You’re not limited to viewing the output of your SSE via the web browser as you can use curl as follows:

curl -v http://localhost:9292/sse/1

The above should yield output similar to the following:

* Host localhost:9292 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:9292...
* Connected to localhost (::1) port 9292
> GET /sse/1 HTTP/1.1
> Host: localhost:9292
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< cache-control: no-cache
< content-type: text/event-stream
< x-accel-buffering: no
<
* no chunk, no close, no size. Assume close to signal end
event: demo
data: Found: 1, Count: 1

event: demo
data: Found: 1, Count: 2

event: demo
data: Found: 1, Count: 3

Falcon

If you’d perfer Falcon, instead of Puma, you can definitely do this by requiring the gem and using falcon as the server by changing the very last line of the Bundler Inline script as follows:

Rackup::Server.start app: application, server: :falcon

Running

As mentioned in the Quick Start section, to run the demonstration, you only need to run as follows:

./demo
open http://localhost:9292

💡 You can then launch the same URL in multiple browser tabs to get multiple streams running at once.

Specs

If using Puma, ensure you use two minimum and two maximum threads since you’ll need one thread for normal page requests and one for SSE connections since they are persisted and longer lived. Otherwise, you’ll have random spec failures with fewer threads. Here’s what you should have in your spec helper for your feature specs to get started:

Capybara.server = :puma, {Silent: true, Threads: "2:2"}

The threads value of 2:2 means a minimum of two threads (first number before the colon) and a maximum of two threads (second value after the colon). You can definitely tweak these numbers by making them smaller or larger but do recommend keeping the maximum number of threads two or higher.

Conclusion

As you can see, implementing SSE takes minimal effort. You only need an event stream, middleware, and a client to wire everything up. Even better, you’ve learned how to make all of your objects reusable and configurable should you need to introduce different behavior without complicating or reducing the maintenance of your architecture.

Enjoy and may your applications be lively!

Proactive Engineering

2026-06-01T12:07:18+00:00

Proactive Engineering

Proactive engineering is the practice — and rigor — of staying atop new technologies, designs, and changes in order to keep your software stack healthy, minimize risks, and keep technical debt low. This allows you to build a healthy team and well maintained code base that is a joy to work with.

Proactive engineering is also the exact opposite of reactive engineering (a.k.a. move fast and break things). The problem is most teams don’t have this kind of rigor. They work in a constant state of fire fighting, dealing with on-call issues, bombarded with interrupts, and/or sheer neglect. The goal is to get you into a healthy state in which you have time for Deep Work with the ability to maintain your application, research solutions, and focus on delivering a high quality product your customers enjoy.

Table of Contents

Notifications
News
Weekly Upkeep
Daily Habits
Culture
Conclusion

Notifications

First and foremost turn off all notifications or, at a minimum, silence them so they don’t interrupt your flow state. The kinds of notifications you want to disable is social media, syndicated feeds, email, group chat, source code issues/reviews, and so forth.

You might think you can tackle multiple things at once but the human brain isn’t wired to work like that. What’ll you end up doing is a lot of shallow work with a higher chance of introducing issues which could have been mitigated if given your full attention. This creates more work which is the opposite of the desired outcome you started with.

Your super power is to remain deeply focused on your task at hand, completing it, and moving on. Even better, this gives you the space to see connections to other aspects of your architecture which can be refactored or improved upon further because you have the time to think deeply, detect duplication, and optimize your code base further rather than trying to complete as many tasks in as little time as possible.

Any interrupts, while working in this flow state, should be immediately added to your second brain (example: Obsidian) so you can tackle after your task at hand is complete. Interrupts in this context, would be new discoveries, new solutions, refactorings, deletion of dead code, etc. Important to identify but better to address afterwards.

When you turn off notifications, you put all the power back in your hands. You dictate when and how you’ll tackle interrupts not the other way around. This is the first step in being proactive instead of reactive. Welcome, friend.

News

At one point, The Changelog used to sign off with the adage: "Open source moves fast, keep up!" They are correct because the minute you fall behind, the technical debt rises which makes updating your software projects that much harder.

The best way to stay abreast on what’s changing in the world is through Syndication. This empowers you to manage your own curated sources of information while your feed reader works tirelessly, in the background, to inform you of updates.

At a minimum, your feeds should be checked morning and noon every day via this simple workflow:

Open your feed reader to catch up on all updates.
Add next actions into you second brain, as necessary, to tackle after you’re caught up.
Finish by getting to Inbox Zero.
Close your feed reader when done to avoid it distracting you further.

As with notifications, you control when you catch up on the news, not the other way around. This allows you to fold in changes as you see them with minimal effort. For example, upgrading to the latest Ruby patch or gem update because it’s a lot easier to address changes as you see them rather than upgrade a bunch of gems at once. This is made even easier when your test suite is at or near 100% code coverage so you have even more confidence to upgrade early and often.

Weekly Upkeep

As done with personal hygiene, physical exercise, eating healthy foods, and getting plenty of sleep, your Machine Upkeep is equally critical to augmenting your mental and physical abilities. This means the upkeep of your machine should be performed every other day. On a weekly schedule, this means Monday, Wednesday, and Friday at a minimum. Do this before the start of your work day.

In addition to keeping your machine up-to-date, the same must be applied to all projects you maintain. Bash or Ruby scripts are extremely valuable in automating this workflow. For plenty of examples, feel free to pilfer from the following projects:

Dotfiles: Use to manage your Dotfiles and associated configurations including tapping into a wealth of aliases and functions that speed up your workflow.
macOS Configuration: Use to rebuild your machine(s) from scratch and keep them up to date as well.

Having this kind of automation in place reduces the friction of upgrading your projects so you can quickly resolve any issues and move on. This also means you’re more likely to perform upgrades, once detected, instead of pushing off until later. This is exactly the kind of workflow you need in order to prevent tech debt from building up.

To illustrate further, each RuboCop release almost always takes time to read through the release notes because the project doesn’t adhere to Milestones or always has documentation updated in lock step with each release. This then requires chasing down the source code to get better examples of what has changed and/or testing out each cop individually so you can make atomic commits to your own code to explain the what and and why of the change(s). Doing this work per version release is less time consuming than putting this off and tackling all changes at once which can take a day or more.

There is another benefit, not often discussed enough, which is retaining and attracting new talent because the joy of working in a well maintained codebase increases productivity due to less friction of fighting with broken aspects of your tech stack. Fixing a bug or adding a feature should be enjoyable and effortless as possible. This doesn’t mean the problem you are tackling isn’t a challenge or takes time to accomplish, only that you shouldn’t be constantly fighting against the software stack you are working in.

Daily Habits

As written in Atomic Habits by James Clear, ensure you turn all of the above into habits. Ideally, you don’t want to think about them but intrinsically do them as part of your daily flow. To aid in this endeavor, lean on your second brain (or task managing software in general). For example, consider using the following workflow at dawn and dusk each day:

Update (catch up and/or address feedback)
- Check mobile/watch notifications.
- Check communications (i.e. social media, email, group chat, etc).
- Check GitHub notifications.
- Check feeds.
Plan
- Review calendars.
- Review/plan next actions based on new information gleaned from above.
Clean (a.k.a. Inbox Zero)
- Clear your email.
- Clear your feed reader.
- Clear your voice memos.
- Clear your second brain inbox (i.e. OmniFocus, Obsidian, etc).
- Clear browser tabs.
- Close all communication and news apps.
Reflect on yesterday’s learnings and plan any final actions.

💡 At dusk, one key difference is not to reflect on yesterday’s learnings but the current day’s learnings instead. This is also a good chance to capture any further notes from the day in which to reflect upon tomorrow.

The above should be on a reoccurring schedule that appears at dawn (Example: 6am) and then again at dusk (Example: 5pm). Any task managing software (trusted system) can automate and ensure these actions are front and center.

The above framework puts you in control so you can do what you do best with a strong emphasis on high quality output. Most importantly, you are in control which means you are being calm, collected, and proactive in your actions rather than reacting without having time to think.

Culture

Once you have your daily habits in place, make this a core part of your culture. You do this by avoiding hiring anyone who doesn’t have (or can’t learn) these habits and fire anyone who can’t maintain this discipline. Remember, each person you add to your team should raise bar and reinforce the culture, not lower.

Conclusion

In this Age of Slopware, Enshittification, and lack of code quality in general, we need more engineers that show up day in and day out with professional etiquette that doesn’t tolerate anything less. Being proactive puts you in control by allowing you to tame the chaos and have a solid structure in which to build amazing cultures, teams, products, and services.

We can all do better and being proactive aids in this endeavor. Make this a priority so you can enjoy the work and the people you work with.

Blue Ridge Ruby 2026

2026-05-15T15:12:02+00:00

Blue Ridge Ruby 2026

I attended Blue Ridge Ruby for the first time and had a great time speaking and participating in the conference held in Asheville, North Carolina. The following are a learnings and experiences that might be of interest.

Table of Contents

Conference

Both my wife and I traveled together so she could work on her novel and I could focus on the conference then have time to explore the city and surrounding area afterwards.

Day 1 (Wednesday)

We woke at 5:30am to grab breakfast and then catch a cab, bus, and flight to Asheville. Thankfully, the Denver International Airport (DIA) has direct flights to Asheville.

It was 3pm, due to gaining two hours while flying East, before we landed in Asheville. The airport, while small, is modern and nicely laid out. There was some construction but simple enough to grab your luggage and catch a cab downtown (~30 minutes drive, roughly).

We stayed at the Aloft, as recommended by the conference, with easy walking distance to the YMI Cultural Center. We ended up on the fifth floor with beautiful, unfettered, views of the mountains due to being at the end of the building. Definitely nice to wake up to each morning.

Once unpacked, we walked over to the YMI Cultural Center to poke our heads in out of curiosity. This is where I met Burdette Lamar, a retired Rubyist, who works on Ruby Documentation. Even better, he’s working on Pathname documentation which warmed my heart because I see so many Rubyists who are not familiar with this Object API and only use File when they should be using Pathname. This is why I’ve put effort into Pathname Refinements so you can do even more with less in your implementations.

Afterwords we went to the Blackbird restaurant for the Speaker’s Dinner. I ended up spending most of the evening talking with fellow speaker, Joël Quenneville, along with Mark Locklear (conference organizer). With Joël, our discussion was all about Elm, Ruby, and functional programming general. I always love talking to folks that blend Object Oriented + Functional programming in Ruby. This is exactly what my unpublished book is about (which, yes, I need to publish).

Day 2 (Thursday)

This was the first full day of the conference so arrived at 8am to get my conference badge and a Ruby Passport which required filling out paperwork and tracking down a fellow attendee to notarize the document by drawing an impression of a random question they had to answer. A bit amusing since the paperwork also mimics a government document. This includes the texture and paper quality of the passport itself. Nice attention to detail. Once completed, I was able to get my passport officially stamped:

During this time, I met a bunch of new Rubyists before catching the first talk. The following are quick notes on what captured my attention. Definitely check out the videos when they land. The full schedule for the day can be found here.

State is the First Decision You Never Made by Joël Quenneville

The talk was a chapter from from Joël’s upcoming book, The Web as a Platform, and was well done in terms of the HTTP specification, the web in general, and managing state via an architecture that is stateless by nature. There’s even a nice callout to htmx which I emphasize in my talk as well. Here’s the slides.

Yes, and: Ruby’s Secret Talent for Improvisation by Ifat Ribon

We chatted, briefly, while in the lobby before the day kicked off so was interested to learn where she would take this. The functional aspects of Ruby, especially functional composition which I’ve also written and spoken about is always of particular interest to me. Even better is when people show how you can apply the Railway Pattern for fault tolerant pipelines.

Instead, this talk was about the basics of procs and lambdas told through the lens of improvisation. Good for people getting started but there was definitely a part of me wishing the audience could see the full spectrum of how far you can take this and how much better your implementations can become.

Lunch

For lunch, I ended up catching up with folks at the White Duck Taco Shop which was delicious. I was late getting there because I wanted to test my slides after the last talk only to discover I was getting no video from my macOS.

Turns out there was a macOS Tahoe bug, that I haven’t seen in previous versions, where your macOS can’t recognize external displays. I believe this is related to HDMI connections but not entirely sure. The workaround was:

Find a speaker (thanks Christine) who was running an older version of macOS and have them connect to the projector.
Enable AirPlay so you could send your mac’s video to the machine connected to the projector.

I wasn’t the only one effected by this as a few other speakers ran into this too. If you are running macOS 26.4.1, then this is something to pay attention to.

How To Finish What You Start: Lessons From Actually Shipping a Big Refactor by Annie Kiley

This is more of critique — but not of the speaker — of what happens in large organizations that aren’t adamant about code quality. What caught my eye, during this talk, was the lack of nested modules/namespaces. This is known as the Flat Modules Antipattern. As a consultant, I’ve run into this antipattern more times than I care to admit because this always causes unnecessary pain when improving or maintaining code bases (especially larger codebases).

You can avoid this pitfall by always nesting your models because this gives you more flexibility in using modules and classes. Ruby definitely allows you to use flat modules but wish it didn’t.

InstiLLMent of Successful Practices in an Agentic World by Kevin Murphy

The day ended with LLM dark humor which is both a cautionary take on slopware and not forgetting about the human connection that makes up great teams. It’s a well executed talk so give it a watch when it becomes available. Here are the slides.

Dinner

For dinner, I ended up at Birdie’s Pizza hanging out with a few folks from the Greenville, North Carolina area. The pizza was good, and with only two huge slices, was definitely filling.

Roundtable Discussion

I was most interested in this discussion but ended up leaving early because the discussion didn’t tap in to the thing I wanted most which is actionable next steps. Like how do we form unions, collectives, etc. and how do we band together to fight for a better future where the craft of software can be enjoyed instead of the race to the bottom through slopware.

Instead, this ended up being more of a alcoholics anonymous meeting where the mic went around the room where each person would start with some form of the following: "Hi, I’m Bob and I’m a recovering Rubyist of X years." Others would take the mic and then ramble on for what seemed like ages. I did enjoy that when Rachael Wright-Munn (fellow speaker) spoke, she was composed and to the point.

All of the sentiment, sharing of experiences, etc was definitely valid but not exactly what I was looking for. I didn’t end up speaking, only listening until I left after an hour in.

Day 3 (Friday)

The following is a capture of my notes from Day 3. Here’s the full schedule.

Terminus: A Hanami + htmx web application for ePaper devices

I ended up kicking off the second day. I also had the most complicated talk in terms of technology. Here’s the full setup:

Mudi Portable 4G LTE Router: My neighbor graciously let me borrow her Mudi for the trip because my Mudi 7 delivery was delayed. I needed this to create a private network that would have no interference from conference traffic because, when your whole presentation is built atop live running code, you want to reduce as many variables that can possibly go wrong.
Four TRMNL ePaper Devices: These were connected to the Mudi and my Terminus server. They were passed out to the audience and set at a one second refresh rate so folks to could view each slide on the device in real-time with a slight delay. Christine and Thomas, fellow speakers, helped me distribute these devices and then collect them after.
Terminus: This is my Hanami + htmx web application which was also serving and rendering my slides in real-time. All of this was running on the Mudi private network.

I had fun giving this talk which was on intermediate to advance Ruby (functional, object oriented, and, advanced patterns). It was also the most code heavy of all talks. I’ll let you judge whether I did a good job or not but hope folks are inspired to expand upon what’s possible in Ruby.

These talks always take a toll on me as my mouth tends to dry up when speaking and I had to pause, briefly, to get some water. I thought I had unscrewed the lid for quick access but, alas, it required an awkward moment to get back on track. Best laid plans as they say.

Your First Open-Source Contribution by Rachael Wright-Munn

Rachael is a very good speaker including elegantly bouncing back from technical hiccups. Her talk was on getting started in open source, contributions, guidelines, and so forth. Definitely good for beginners.

I’ve also thought a lot about this and put a bunch of effort into automating much of the process set forth in Rachael’s talk and would definitely recommend using these gems if setting up a new project which applies much of what Rachael is saying:

Rubysmith: For Ruby projects.
Gemsmith: For Ruby gems.
Hanamismith: For Hanami projects.

I never spin up a new project without the above. Hopefully, they help you too.

LLM Telemetry as a First-Class Rails Concern by David Paluy

David suffered some of the same display issues as me and wasn’t able to fully use his machine, which was a bummer, but he handled the hurdles well and gave an interesting look at LLM rubrics. I’m still chewing on all of this and still have it on my list to dig into this more and give feedback. We ended up talking afterwards which was enlightening. Super interesting and very positive person to talk to.

Here are his slides and recommended links to check out:

Lunch

Ended up at Pack’s Tavern, which was delicious, and talking to a lady interested in my hardware setup along with an old acquaintance, John Paul Ashenfelter, that I think I’ve known for over a decade and Mark Starkman. The discussions were mostly focused on the craft of software engineering. Always my favorite kind of discussion.

Lightning Talks

Lots of interesting talks and too much to detail here. Make sure to check out the video when they land. I managed to give a talk on Git Lint which, despite some rendering issues with my slides (fixed now), made it in at the end.

My lightning talk turned out to be serendipitous and a nice setup for Thomas as he would speak about the importance of good Git commit messages more in his talk that concluded the day. More people discussing how important this is is good for all of us.

5 ways to invest in yourself for the long haul by Thomas Cannon

This was a dense and jam packed talk that moved about as fast as my talk. I was delighted to see someone, as adamant as me, speaking about good Git etiquette and the power of Git Commit Anatomy. My favorite engineers are those that take the time to capture their thought process in their commits as it makes code reviews, learning the history of the project, and leveling up so much more enjoyable. Great writers make for great engineers.

There’s a lot to unpack in this talk so check out the slides to learn more.

Dinner

Funny enough, I ended back at Pack’s Tavern which, again, can’t complain. The food was great and a good excuse to explore more of their menu.

After Party

After dinner, I followed the group down to Burial at South Slope. My social battery was getting drained at this point. I’ve learned that two days of social interaction is about where I start to run out of steam. I stayed for an hour or so and then made my way back to the hotel. Tried to say goodbye to those I could and, of course, Jeremy who put all of this together.

Would have liked to have talked with Jeremy more but when, you’re running the entire conference, time is extremely limited.

Jeremy did an amazing job (including Mark and Joe). Definitely would like to come back in the future and hope Blue Ridge Ruby continues to gather fellow Rubyists to this location.

Asheville

With the conference behind, my wife and I were able to spend time together exploring the city and surrounding area. The following is a capture of the highlights.

City (Saturday)

To kick things off, we spent the day walking all over the city. This is one of my favorite things to do when new to a city. This ended up being:

Pack Square Park: Small but nice park. There’s several chairs you can sit and rest in while watching folks play with their pets and get views of the governmental buildings.
French Broad Chocolate: Only a short walk from Pack Square Park. Opens late but the hot dark cholocote and liquid truffle shot is well worth checking out.
Pritchard Park: A bunch of booths were setup for the weekend. Picked up a deck of cards, made of up of local art, that supports the local artists (especially those hit by the flood).
Grove Arcade: Lots of artists selling their wares, small shops, and eateries. Especially enjoyed the Battery Park Book Exchange & Champagne Bar where you can eat at while surrounded by books.

The Biltmore (Sunday)

We rented a car and took a short drive to The Biltmore. Spent the entire day there only getting home a little before midnight as we had tickets for the House, Gardens and Grounds, and the Luminere.

If I lived in the area, I’m pretty sure I’d want a season pass in order to walk and read in the gardens as often as possible.

Blue Ridge Parkway (Monday)

Started the day by having brunch at the Biscuit Head before driving the parkway. The place is easy to miss if not paying attention to as the sign is tucked away in a cottage like setting. Definitely worth checking out because the biscuits were fluffy and delicious. This included several kinds of jams and sauces you could spread on your biscuits as well. Would definitely go back.

After leaving Biscuit Head, we caught the Blue Ridge Parkway and initially headed to the North Carolina Arboretum but then headed North to the visitors center instead. It was a tough decision but had to skip since we were worried about maximizing our time on the parkway.

At the Visitor’s Center we met an astute park ranger who helped clarify what parts of the road were open and closed which allowed us to drive/hike to the top of Mount Mitchell and then turn back to cross over in to the Pisgah Forest and eventually over Mount Pisgah itself.

We spent the afternoon in the Pisgah Forest, enjoying the roads, and scenic views. We eventually caught I-40 back into Asheville to end the day.

The River Arts District (Tuesday)

We spent the day walking to, around, and back from the River Arts District. As chance would have it, this was also the worst day to be in the River Arts District since this seems to be their slowest day of the week so several places were closed. I was also curious to eat a Hole Doughnut but they were closed as well. Alas.

This area of the city was hit hard by the hurricane that struct about a year prior where whole houses were seen floating down the river. Hurricanes don’t normally travel this far inland but climate change is lashing out in extreme ways.

While enjoying the district, viewing creative works of art, and collecting a bunch of ideas we ended up assembling a list of our favorites:

The Rhu and Home

This ended up being a rainy day so we spent the morning working from The Rhu, popping over to the French Broad Chocolate one last time, and then grabbing lunch at Mela (I’d eat Indian or Ethiopian every day of the year if possible) before catching a cab and our flight back home.

Conclusion

Definitely glad I was accepted to speak, TRMNL to send me out, and have time to adventure with my wife afterwards.

Asheville is definitely has a lot to offer into terms of food and outdoor adventure. It’s not, sadly, a tech hub as I was hoping. The city’s major industry seems to be tourism and culinary. As for where some of the local Rubyists are, they seem to be farther out such as Greenville, South Carolina; Charlotte, North Carolina; Raleigh, North Carolina; and so forth.

A part of me is searching for city which has a lot of Rubyist that are pushing the boundary of what’s possible who are not Rails engineers. A lofty dream but only need one or two to start building something great.

Anyway, if you get a chance to speak or attend Blue Ridge Ruby, don’t hesitate. The single track days plus having lots of time to hang out and talk to folks is a great experience. Highly recommend.

Ruby Classes

2026-05-01T10:24:09+00:00

Ruby Classes

Classes are at the heart of Object-Oriented Programming and Ruby makes them effortless to use. They provide the following benefits:

Composition: Allow you to leverage the Dependency Inversion Principle (DIP) — the "D" in SOLID design — by injecting dependencies via your constructor or methods. Prefer composition over inheritance because this maximizes your ability to reuse your components to build robust architectures.
Inheritance: Allow you to subclass and inherit behavior from a superclass and/or use multiple inheritance to enhance your class with common functionality.
Encapsulation: Allows you to wrap data, state, and/or behavior (methods) within a single object. Additionally, you gain the ability to abstract common functionality without having to understand the intricate details.
Modularity: Promote module design which leads to improved testability and maintainability since your object is highly focused on doing one thing well. In other words, the Single Responsibility Principle (SRP) which is the "S" in SOLID design.
Reusability: Allow you to make multiple instances of your class without having to repeat yourself in terms of constantly writing the same implementation over and over.
Polymorphism: Allow you to use objects from different classes which can respond to the same method calls in their own appropriate ways, making your code more flexible and extensible (a.k.a. Duck Typing).

We’ll discuss the above in more detail but, before we do that, it’s important we take a moment to talk about the categories that classes fall into.

Table of Contents

Categories
Basic versus Functional
Composition
Inheritance
Encapsulation
Modularity
Reusability
Avoidances
Conclusion

Basic versus Functional

Basic classes are vast and encapsulate a wide range of creational, structural, and behavior patterns such as adapters, clients, presenters, factories, observers, visitors, and so much more. For example, consider the following presenter:

require "forwardable"

module Demo
  class Place
    extend Forwardable

    delegate %i[name created_at] => :record

    def initialize record
      @record = record
    end

    def label = name.capitalize

    def human_created_at = created_at.strftime "%B %d, %Y (%A) at %H:%M %Z"

    private

    attr_reader :record
  end
end

The above wraps a record object with additional behavior (i.e. decorations) for presentation purposes. You need this when you want to keep your data and presentation layers separate in your application. This allows you to avoid overloading your record with presentation logic that is only used by your views.

Functional classes, on the other hand, adhere to the Command Pattern by implementing the #call method. Example:

require "http"

module Demo
  class Pinger
    def initialize http: HTTP, kernel: Kernel
      @http = http
      @kernel = kernel
    end

    def call uri
      http.get(uri).then do |response|
        response.status.success? ? kernel.puts("Site is up.") : kernel.puts("Site is down.")
      end
    end

    private

    attr_reader :http, :kernel
  end
end

The key difference between these two objects is that the former has several methods which expose data and/or behavior while the latter is purely functional in that you message a single public method, call, and get a result. No mutations or side effects. Only data in, data out.

The above examples are definitely not exhaustive and only represent a small subset of what is possible. The goal isn’t to explain all patterns and styles, only for you to study the shape of these objects. We can now compare/contrast by walking through the benefits that classes provide.

Composition

With both examples, you see an adherence to DIP where all dependencies are injected via the constructor.

With the presenter, a record is required because you can’t build a presenter with nothing to wrap. That would defeat the purpose.

With the command, default dependencies are injected so you can construct an instance with minimal effort. This is important because you want to create an instance you can reuse for different URIs to ping. This doesn’t stop you from injecting http and kernel dependencies with different behavior either. This is most apparent when writing specs. For example, we can use RSpec to stub HTTP and spy on Kernal like so:

RSpec.describe Pinger do
  subject(:pinger) { described_class.new http:, kernel: }

  let(:http) { class_double HTTP }
  let(:kernel) { class_spy Kernel }

  describe "#call" do
    it "prints site is up" do
      allow(http).to receive(:get).and_return(HTTP::Response)

      expect(kernel).to have_received(:puts).with("Site is up.")
    end

    it "prints site is down" do
      allow(http).to receive(:get).and_return(HTTP::Response)

      expect(kernel).to have_received(:puts).with("Site is down.")
    end
  end
end

Notice, by allowing dependencies to be injected, we can inject a spy for testing purposes.

A common mistake is hard coding dependencies directly within the body of the class. This leads to a Connascence of Name (CoN) situation where the class becomes brittle and hard to test because you have to keep altering the implementation to adjust behavior. With dependency injection, you avoid CoN while providing room for different dependencies to alter behavior.

Inheritance

Inheritance is a double edged sword because subclassing, or worse, creating a deep hierarchy of subclasses, leads to highly coupled and brittle code. Same goes for multiple inheritance where too much behavior is injected into a class thus breaking SRP where the object has confusing behavior that is hard to test.

With the presenter, multiple inheritance is used to delegate messages to the injected record via the Forwardable module. This is a good use of multiple inheritance because we are enhancing the object without effecting the external behavior of the object or violating SRP.

We could lean into multiple inheritance further by using the Initable gem to clean up the examples as shown below:

Presenter

require "forwardable"
require "initable"

module Demo
  class Place
    include Initable[%i[req record]]
    extend Forwardable

    delegate %i[name created_at] => :record

    def label = name.capitalize

    def human_created_at = created_at.strftime "%B %d, %Y (%A) at %H:%M %Z"
  end
end

Command

require "http"
require "initable"

module Demo
  class Pinger
    include Initable[http: HTTP, kernel: Kernel]

    def call uri
      http.get(uri).then do |response|
        response.status.success? ? kernel.puts("Site is up.") : kernel.puts("Site is down.")
      end
    end
  end
end

Notice how the original implementations require less code by using Initable to automatically DRY up and apply the Barewords Pattern for us. With the presenter, we now have multiple inheritance via Forwardable and Initable. What’s significant is we are not violating SRP by exposing additional public behavior. Instead, we are privately simplifying the implementation while writing less code! This is a good example of multiple inheritance applied appropriately.

You can definitely take this to extremes by including, extending, and/or prepending multiple modules which leads to a form of Dissociative Identity Disorder with your objects due to confusing behavior that is hard to reason about and test. Please avoid this.

Encapsulation

Both examples adhere to the Barewords Pattern by ensuring the Object API is private by default to prevent leaky abstractions. When implementing classes — and this is important — always default to making your attributes private by default. Only expose data when you are absolutely certain it’s needed.

Did you notice you can’t access the record directly in the presenter above? Same goes for the command where you can’t access any of the injected primitives either. This is good encapsulation!

A properly encapsulated objects does two things:

Data: In the basic example, the record is the encapsulated data. In the functional example, the data is the URI passed in via the #call method. The only dependencies are HTTP and Kernel which can be swapped out with different implementations at object initialization.
State: Only the functional example has state — but it’s brief — in that it makes an HTTP request and, for a short moment, has a response object which contains the status. Upon subsequent requests, the response is created anew, only to check status, and then is scheduled for garbage collection after.

Modularity

In both the presenter and command examples, both are highly modular in that they one thing well: present or perform an action. That’s it.

With the presenter, yes, you have multiple methods you can interact with but they are all focused on presenting your record in manner that is visually pleasing within your views.

With the command, you have a single Object API: #call. You give it a URI and it answers with a messaging letting you know if your site is up or down. Even better, you can use Function Composition to pipe the output of this command to other commands for further manipulation as needed. This is the beauty of functional programming because, once you have the building blocks in place, you can mix and match in any order to build more sophisticated solutions.

Reusability

Both examples have varying degrees of reusability. With the presenter, you can wrap any record that has the same attributes without changing the original design of your presenter.

With the command example, you can always supply a different uri to the same instance since the uri is what will change the most, not your instance. Even better, you can inject different dependencies to create new instances with slightly different behavior with no change to your original implementation either.

Avoidances

The greatest strength, and weakness, of Ruby is extreme flexible. Ruby treats you with respect by assuming you know what you are doing. Unfortunately, many programmers don’t fully grasp this — or worse, are an Expert Beginner — which turns a beautiful language into an absolute abomination to read and maintain.

To paraphrase Uncle Ben from Spiderman: "With great power comes great responsibility." Use the following to avoid common pitfalls and wield your power responsibly:

The above will vastly improve the quality of your code and reduce your maintenance burden to boot.

Conclusion

You’ve learned the power of Ruby classes and the potentially they can bring to your design and architecture. This includes the power of functional programming in Ruby by blending object-oriented with functional programming for maximum effect.

Be diligent in your design, apply the right objects when appropriate, and you’ll have few regrets. Enjoy!

htmx Configuration

2026-04-01T12:01:25+00:00

htmx Configuration

Often, you’ll want to customize the default htmx configuration. There are a couple ways you can do this:

Globally.
Per page.

We’ll discuss each including how you can make short order of these configuration changes in your Ruby applications. For the purposes of this discussion, we’ll use Hanami as our web application but what you see here can be applied to your specific web stack.

With the above in mind, let’s get started by first setting up our htmx provider.

Table of Contents

Provider
Context
Layout
Conclusion

Provider

As documented in Hanami Containers, the best way to have access to the HTMX gem is to implement a corresponding provider. Here’s what this looks like:

# demo/config/providers/htmx.rb

Hanami.app.register_provider :htmx do
  prepare { require "htmx" }

  start do
    register :htmx, HTMX
    register :htmx_defaults,
             {"allowScriptTags" => false, "defaultSwapStyle" => "outerHTML"}.freeze
  end
end

This allows you to quickly inject htmx as a dependency while providing a default configuration which can be customized further if desired. There’s a lot of htmx Configuration settings you can tweak but what is shown above is a good starting point for a couple reasons:

allowScriptTags: Disabled as a security precaution to prevent random JavaScript being loaded and executed (especially if content is user created).
defaultSwapStyle: The default swap style is innerHTML which means content within the body of your HTML element will be swapped. In practice, this isn’t want you want as you generally want to swap out the entire element itself (including it’s content) when making htmx requests.

Context

With the above provider in hand, we can now inject our htmx dependencies into our view context, via include Deps[:htmx, :htmx_defaults], as shown below:

# demo/app/views/context.rb

# auto_register: false

require "hanami/view"

module Demo
  module Views
    class Context < Hanami::View::Context
      include Deps[:htmx, :htmx_defaults]

      def htmx? = htmx.request? request.env, :request, "true"

      def htmx_configuration
        content_for(:htmx_merge).then { it ? htmx_defaults.merge(it) : htmx_defaults }
                                .to_json
      end
    end
  end
end

Specification

The following illustrates how simple it is to test the implementation since you can use an instance of Hanami::Action::Request for requests and plain old hashes for configuration merging.

# demo/spec/app/views/context_spec.rb

# frozen_string_literal: true

require "hanami_helper"

RSpec.describe Demo::Views::Context do
  subject(:view_context) { described_class.new }

  describe "#htmx?" do
    it "answers true when htmx request" do
      request = Hanami::Action::Request.new env: {"HTTP_HX_REQUEST" => "true"}, params: {}
      view_context.instance_variable_set :@request, request

      expect(view_context.htmx?).to be(true)
    end

    it "answers false when not a htmx HTTP request" do
      request = Hanami::Action::Request.new env: {}, params: {}
      view_context.instance_variable_set :@request, request

      expect(view_context.htmx?).to be(false)
    end
  end

  describe "#htmx_configuration" do
    it "answers default configuration" do
      expect(view_context.htmx_configuration).to eq(
        {"allowScriptTags" => false, "defaultSwapStyle" => "outerHTML"}.to_json
      )
    end

    it "answers custom configuration" do
      view_context.content_for :htmx_merge, "defaultSwapStyle" => "innerHTML"

      expect(view_context.htmx_configuration).to eq(
        {"allowScriptTags" => false, "defaultSwapStyle" => "innerHTML"}.to_json
      )
    end
  end
end

The #htmx? method leverages the HTMX gem to check if the current HTTP request — especially handy within Hanami Actions — is an htmx request or not. This allows you have access to this information within your Hanami Views. Quite powerful.

The #htmx_configuration method leverages the htmx_defaults dependency by merging it with whatever is provided by the htmx_merge hash and then immediately converting this into JSON which is the format that htmx needs in order to configure itself. This allows you to use the content_for Hanami Views helper at the top of any template to alter htmx’s configuration for specific pages. For example, let’s say you need to alter the swap style for a specific page. You’d only need to add the following to the top of one of your HTML templates:

<%= content_for :htmx_merge, {defaultSwapStyle: "innerHTML"} %>

That’s a lot of power for a single line of code.

Layout

With all of the above in place, the only thing left to do is configure your application layout (i.e. app.html.erb) to load your custom htmx configuration for all pages:

<!-- demo/app/templates/layouts/app.html.erb -->

<!DOCTYPE html>

<html lang="en">
  <head>
    <!-- Truncated for brevity... -->
    <%= tag.meta name: "htmx-config", content: htmx_configuration %>
    <!-- Truncated for brevity... -->
  </head>

  <!-- Truncated for brevity... -->
</html>

The above will ensure htmx is properly configured for every page using your application layout (unless overwritten by the content_for helper with the htmx_merge key). 🎉

Conclusion

You’ve learned how to configure htmx that best suites the needs of your web application either globally (default) or per page (specific). Even better, you’ve learned how you can leverage the HTMX gem to check if you’re dealing with htmx requests which allows you to provide specialized behavior for htmx and non-htmx requests. Finally, you’ve learned how you can apply all of these configuration change via your application layout for federated behavior.

Enjoy!

htmx Infinite Scroll

2026-03-01T13:20:51+00:00

htmx Infinite Scroll

Pagination is always a feature you have to tackle in web application development in one form or another. A common approach is to use a gem, like Pagy, to provide the following capabilities:

Load records in batches (a.k.a. pages).
Previous and next links.
Numbered links to specific pages.
Bookmarkable links complete with browser history.

Definitely useful to decrease server load since you’re only loading a small subset of records per request. The problem with this approach is:

Most people bail after reading through the first couple of pages and not finding what they want.
Includes a lot visual information, design-wise, that not only consumes real-estate within your UI but is seldom utilized.

We can do better. With infinite scrolling, we can provide a better user experience through a killer combination of search coupled with endless scroll. This allows folks to:

Endlessly scroll until they find what they want or bail when coming up empty after a page or two.
Search plus scroll to further refine the results.

Let’s explore building a gallery of photos for browsing and searching by using an API client to obtain images from a remote resource. We’ll do this by using htmx to provide an infinite scrolling experience.

Table of Contents

Setup
Implementation
- Action
- View
- Template
Conclusion

Setup

To implement this functionality, add the htmx library and the HTMX gem to your stack. Both are compatible with whatever Ruby web framework you decide to use.

Additionally, the htmx team has an example if you need a visual primer. When you inspect the example’s DOM, you’ll see the following:

<tr hx-get="/contacts/?page=2" hx-trigger="revealed" hx-swap="afterend" data-hx-revealed="true">
  <td>Agent Smith</td>
  <td>void29@null.org</td>
  <td>A0GG98CEAC</td>
</tr>

This breaks down as follows:

hx-get: Contains the HTTP request for the next page of information.
hx-trigger: Triggers the GET request when the element is revealed in the viewport.
hx-swap: Describes swap behavior. In this case, new content from the HTTP response will be swapped in after the target element (i.e. the tr you see above).

That’s a lot of power for only a few lines of HTML!

Implementation

Our implementation will consist of a Hanami action, view, and template. For htmx, you can load either via a CDN, Node package, or an import map. The following sections will focus on the Ruby code.

Action

Now that you have an idea of the desired functionality on the frontend, let’s discuss how to implement this on the backend. For demonstration purposes, we’ll use a Hanami Actions index action. If using a different framework, the Ruby code should be trivial to adapt for your own implementation. Here’s the entire action:

Implementation

require "initable"

module Demo
  module Actions
    module Gallery
      class Index < Hanami::Action
        include Deps[:htmx, :client]
        include Initable[model: Demo::Models::Photo]

        params do
          optional(:query).filled :string
          optional(:page).filled :integer
        end

        def handle request, response
          parameters = request.params

          load(parameters).either -> photo { render request, photo, response },
                                  -> message { render_error parameters, message, response }
        end

        private

        def load parameters
          case parameters
            in query:, page: then client.photos(search: query, page:)
            in query: then client.photos search: query
            in page: then client.photos(page:)
            else client.photos
          end
        end

        def render request, photo, response
          query, page = request.params.to_h.values_at :query, :page

          if htmx.request(**request.env).request?
            htmx.response! response.headers,
                           push_url: routes.path(:gallery, query:, page:)
            response.render view, photo:, query:, page:, layout: false
          else
            response.render view, photo:, query:, page:
          end
        end

        def render_error parameters, message, response
          response.flash.now[:alert] = message
          response.render view, photo: model.empty, **parameters.to_h.slice(:query, :page)
        end
      end
    end
  end
end

Let’s explore each section/method of the action since this is worth explaining further. First, we start by injecting the htmx, API client, and model dependencies. We’ll use an API client to scroll through photos which has pagination built-in. We don’t need to understand the client implementation, only the interface. Here’s our dependencies:

include Deps[:htmx, :client]
include Initable[model: Demo::Models::Photo]

💡 The Initable gem is used to inject the model dependency without having to write an initializer since we only need access to the constant (we’ll make use of the model, later, when rendering errors).

Due to our index action being a HTTP GET request we can allow the following optional parameters and type casting:

params do
  optional(:query).filled :string
  optional(:page).filled :integer
end

The query parameter allows us to search for specific records while the page parameter limits the search results by page. Now we can handle the request and response:

def handle request, response
  parameters = request.params

  load(parameters).either -> photo { render request, photo, response },
                          -> message { render_error parameters, message, response }
end

The API client answers a monad (i.e. Dry Monads), so we’ll either have a Success or Failure which is an elegant way to handle the inevitable fork in the road when making a HTTP request that may pass or fail.

Next, we can leverage the power of Ruby Pattern Matching to determine what request we’ll make of our API client (ℹ️ All methods are private from this point forward):

def load parameters
  case parameters
    in query:, page: then client.photos(search: query, page:)
    in query: then client.photos search: query
    in page: then client.photos(page:)
    else client.photos
  end
end

Notice how pattern matching makes short work of how we construct our API request based on what parameters are supplied. The result of any of these requests will answer a monad that is either a Success or Failure. If you refer to the #handle method again, this means we’ll either render the HTML response or an error as implemented via these private methods. Example:

def render request, photo, response
  query, page = request.params.to_h.values_at :query, :page

  if htmx.request(**request.env).request?
    htmx.response! response.headers,
                   push_url: routes.path(:gallery, query:, page:)
    response.render view, photo:, query:, page:, layout: false
  else
    response.render view, photo:, query:, page:
  end
end

def render_error parameters, message, response
  response.flash.now[:alert] = message
  response.render view, photo: model.empty, **parameters.to_h.slice(:query, :page)
end

This flow breaks down as follows:

Success
- If a htmx request, add the appropriate headers (especially the push_url so browser history is preserved) and render without any layout information because you only want the HTML fragment — not the entire page — in order to keep your response as small as possible.
- Otherwise, when not a htmx request, render the full page as you’d normally do.
Failure
- Render the page with a flash message as to what went wrong along with an empty photo (i.e. no results found). This is made possible by the model dependency we injected earlier by sending the .empty message which answers an empty record which leverages the power of the Null Object Pattern.

View

For the view, we only need to expose the photo, query, and page to the template. This is done as follows:

module Demo
  module Views
    module Gallery
      class Index < Hanami::View
        expose :photo
        expose :query, decorate: false
        expose :page, decorate: false
      end
    end
  end
end

By default, Hanami will decorate all parts but for the query and page we only need the primitives.

Template

For the template, we only need to iterate over the photos and render each. Only when there are no photos do we need to display that none were found as shown below:

<% if photo.data.any? %>
  <ul>
    <% photo.data.each do |item| %>
      <%= render :item, item: %>
    <% end %>

    <% if photo.meta.more? %>
      <%= tag.li **HTMX[
                   get: routes.path(:gallery, page: photo.meta.next_page, query:),
                   select: ".card",
                   trigger: "revealed",
                   swap: "this",
                   push_url: true
                 ] do %>
        Loading...
      <% end %>
    <% end %>
  </ul>
<% else %>
  <div>
    <%= render "shared/empty", message: "No photos found." %>
  </div>
<% end %>

With the above we leverage the HTMX gem to build the htmx attributes for us. Additionally, use of the htmx select, swap attributes allow you to only select card element in the HTTP response then immediately swap the current element (i.e. this) with the new element. This not only keeps your DOM clean but ensures you are always using list items because the HTML specification doesn’t allow any other HTML element within a ordered or unordered list. To illustrate further, here’s what the resulting HTML looks like:

<ul>
  <li id="1" class="card">...</li>
  <li id="2" class="card">...</li>
  <li id="3" class="card">...</li>
  <li class="card"
      hx-get="/gallery?page=2&query=landscapes"
      hx-select=".card"
      hx-trigger="revealed"
      hx-swap="this"
      hx-push-url="true">
    Loading...
  </li>
</ul>

This means you can scroll down the page — and when the li element with the htmx attributes is revealed — a new HTTP request is made to replace that element and pull in new data ending with another li element with a hx-get request for the next page.

You also get a nice "Loading…" message while waiting for the HTTP request to complete. For bonus points, you could swap out the text message with a CSS loader class to enhance the user experience further.

Conclusion

Reducing the use of JavaScript within your application is a good in terms speed, reduced page size, and reduced complexity in your application. With htmx you are able to focus on HTML which is much easier to write and test. More importantly, you get all of the benefits of pagination, browser history, and a cleaner user interface. Enjoy!

Hanami with Rodauth

2026-02-01T13:17:41+00:00

Hanami with Rodauth

Security is an important part of web application engineering and a good solution for implementing authentication within your application, both in terms of UI and API, is Rodauth. That said, Rodauth does come with a learning curve. The following will walk you through setting up Rodauth in your Hanami application because, unless you are a security expert, you won’t want to do this yourself.

Table of Contents

Setup
Features
Database
Slice
Actions
RSpec
Tools
Conclusion

Setup

To get started, add the following gems to your application:

bundle add bcrypt jwt rodauth

Here’s what each provides:

Bcrypt: Necessary for authentication, passwords, and encryption in general.
JWT: Necessary for API authentication.
Rodauth: Necessary to implement authentication for both UI and API purposes.

We’ll use these gems to leverage the Rodauth features.

Features

While there are plenty of features you can enable, we’ll focus on the following in the order listed as a minimum to get you started:

Only the Base feature is automatic and provided for you by default. The rest you must manually add. You can definitely add or subtract from this list, based on your needs, but this is the feature set we’ll be working through together.

Database

You’ll want to spend the most time thinking through which Rodauth features you want to support and configure. Once you’ve mapped out your desired feature set, it’s helpful to add # Feature: <feature> code comments so you have a direct reference to the feature associated with each table you are creating. This same code comment can be reused when adding the middleware necessary for enabling and configuring this feature set (more on this soon). Here’s the associated database migrations based on the previously discussed feature set:

User Migration

Necessary to authenticate and manage users within the system. This supports multiple Rodauth features. A code comment denotes each enabled feature.

ROM::SQL.migration do
  up do
    extension :date_arithmetic

    deadline = lambda do |days|
      {null: false, default: Sequel.date_add(Sequel::CURRENT_TIMESTAMP, days:)}
    end

    # Feature (automatic): base
    create_table :user_status do
      primary_key :id

      column :name, String, unique: true, null: false
    end

    from(:user_status).import(%i[id name], [[1, "Unverified"], [2, "Verified"], [3, "Closed"]])

    create_table :user do
      primary_key :id, type: :Bignum
      foreign_key :status_id, :user_status, null: false, default: 1

      column :name, String
      citext :email, null: false
      column :settings, :jsonb, null: false, default: "{}"
      column :created_at, :timestamp, null: false, default: Sequel::CURRENT_TIMESTAMP
      column :updated_at, :timestamp, null: false, default: Sequel::CURRENT_TIMESTAMP

      constraint :valid_email, email: /^[^,;@ \r\n]+@[^,@; \r\n]+\.[^,@; \r\n]+$/

      index :email, unique: true, where: {status_id: [1, 2]}
      index :settings, type: :gin
    end

    # Feature: active_sessions
    create_table :user_active_session_key do
      foreign_key :user_id, :user, type: :Bignum

      column :session_id, String
      column :created_at, Time, null: false, default: Sequel::CURRENT_TIMESTAMP
      column :last_use, Time, null: false, default: Sequel::CURRENT_TIMESTAMP

      primary_key %i[user_id session_id]
    end

    # Feature: audit_logging
    create_table :user_authentication_audit_log do
      primary_key :id, type: :Bignum
      foreign_key :user_id, :user, null: false, type: :Bignum

      column :at, DateTime, null: false, default: Sequel::CURRENT_TIMESTAMP
      column :message, String, null: false
      column :metadata, :jsonb

      index %i[user_id at], name: :audit_user_at_idx
      index :at, name: :audit_at_idx
    end

    # Feature: jwt_refresh
    create_table :user_jwt_refresh_key do
      primary_key :id, type: :Bignum
      foreign_key :user_id, :user, null: false, type: :Bignum

      column :key, String, null: false
      column :deadline, DateTime, deadline.call(1)

      index :user_id, name: :user_jwt_refresh_key_user_id_idx
    end

    # Feature: recovery_codes
    create_table :user_recovery_code do
      foreign_key :id, :user, type: :Bignum

      column :code, String

      primary_key %i[id code]
    end

    # Feature: remember
    create_table :user_remember_key do
      foreign_key :id, :user, primary_key: true, type: :Bignum

      column :key, String, null: false
      column :deadline, DateTime, deadline.call(14)
    end

    run %(GRANT REFERENCES ON "user" TO CURRENT_USER)
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_status TO CURRENT_USER"
    run %(GRANT SELECT, INSERT, UPDATE, DELETE ON "user" TO CURRENT_USER)
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_active_session_key TO CURRENT_USER"
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_authentication_audit_log TO CURRENT_USER"
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_jwt_refresh_key TO CURRENT_USER"
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_recovery_code TO CURRENT_USER"
    run "GRANT SELECT, INSERT, UPDATE, DELETE ON user_remember_key TO CURRENT_USER"
  end

  down do
    drop_table :user_remember_key,
               :user_recovery_code,
               :user_jwt_refresh_key,
               :user_authentication_audit_log,
               :user_active_session_key,
               :user_status,
               :user
  end
end

User Hash Migration

Necessary to capture user password hashes. This is done as a separate table with different permissions in order to improve security as documented here.

require "rodauth/migrations"

ROM::SQL.migration do
  settings = {table_name: :user_password_hash}

  up do
    # Feature (automatic): base
    create_table :user_password_hash do
      foreign_key :id, :user, primary_key: true, type: :Bignum
      column :password_hash, String, null: false
    end

    Rodauth.create_database_authentication_functions self, **settings

    run "REVOKE ALL ON user_password_hash FROM public"
    run "REVOKE ALL ON FUNCTION rodauth_get_salt(int8) FROM public"
    run "REVOKE ALL ON FUNCTION rodauth_valid_password_hash(int8, text) FROM public"
    run "GRANT INSERT, UPDATE, DELETE ON user_password_hash TO CURRENT_USER"
    run "GRANT SELECT(id) ON user_password_hash TO CURRENT_USER"
    run "GRANT EXECUTE ON FUNCTION rodauth_get_salt(int8) TO CURRENT_USER"
    run "GRANT EXECUTE ON FUNCTION rodauth_valid_password_hash(int8, text) TO CURRENT_USER"
  end

  down { Rodauth.drop_database_authentication_functions self, **settings }
end

One of the most important aspects of the above code is that all tables are prefixed as user tables. This is because, by default, Rodauth assumes account prefixes. The reason for making these user based tables instead of account tables is because this allows you to scale to more sophisticated user/account management in terms of level of access. For example, this opens up the following possibilities:

Level 1 (users): Basic user login/logout and resource access.
Level 2 (accounts): The unit of ownership in terms of system resources for which a user can belong to an account for access.
Level 3 (memberships): The many to many relationship in which a user can belong to multiple accounts and an account can have multiple users.
Level 4 (roles): The roles (and permissions) associated with the account.
Level 5 (organizations): The ultimate super account (enterprise level) in which you group multiple accounts under a single organization.

For the purposes of this discussion, we’ll only focus on Level 1.

Slice

Due to Rodauth needing middleware; feature configuration; and multiple templates, it’s a good idea to encapsulate all of this functionality within an authentication slice. Here’s what this looks like structurally:

slices/authentication
├── assets
│   ├── css
│   │   └── portal.css
│   └── js
│       └── app.js
├── db
│   ├── relation.rb
│   ├── repository.rb
│   └── struct.rb
├── templates
│   ├── layouts
│   │   └── app.html.erb
│   ├── login.html.erb
│   ├── login_update.html.erb
│   ├── logout.html.erb
│   ├── password_update.html.erb
│   ├── register.html.erb
│   └── remember.html.erb
├── views
│   └── context.rb
├── feature.rb
├── middleware.rb
└── view.rb

Some of the above is boilerplate when generating a slice. That said, the following sections will detail the key files and ignore the boilerplate code.

Feature

Rodauth supports the ability to define custom features. In this case, we need a custom feature specific for bridging the gap between Hanami and Rodauth when we wire up our middleware (more on this shortly). In other words, a translation layer. In our case, we are swapping out Rodauth’s view rendering with Hanami’s view rendering but only if one of our Hanami templates exist. Otherwise, we fall back to Rodauth. Here’s what this looks like:

# slices/authentication/feature.rb

# auto_register: false

require "rodauth"

Rodauth::Feature.define :hanami do
  auth_value_method :hanami_view, nil

  def view(name, *)
    layout_path = view_base.class.layout_path view_base.config.layout
    scope = view_rendering.scope rodauth: self

    view_rendering.template(layout_path, scope) { render name }
  end

  def render name
    return super unless view_template? name

    view_rendering.template name, view_rendering.scope(rodauth: self)
  end

  private

  def view_template? name
    view_rendering.renderer.__send__ :lookup, name, view_base.config.default_format
  end

  def view_rendering
    @view_rendering ||= view_base.rendering format: view_base.config.default_format,
                                            context: view_context
  end

  def view_context
    @view_context ||= begin
                        action_request = Hanami::Action::Request.new(
                          env: request.env,
                          params: request.params,
                          session_enabled: true
                        )

                        view_base.config.default_context.class.new request: action_request
                      end
  end

  def view_base
    @view_base ||= hanami_view.call
  end
end

Middleware

The middleware layer allows you to inherit Rodauth functionality and configure behavior as Rack middleware for which you can wire into your application routes. Remember when we added the hanami feature above? Well, this is where you enable that feature along with all of the features provided by Rodauth. Here’s the implementation:

Implementation

# slices/authentication/middleware.rb

# auto_register: false

require "refinements/string"
require "roda"
require "rodauth"

require_relative "feature"

module Authentication
  # Specialized Roda middleware for authentication.
  class Middleware < Roda
    using Refinements::String

    plugin :middleware

    plugin :rodauth, json: true do
      enable :active_sessions,
             :audit_logging,
             :change_login,
             :change_password,
             :create_account,
             :disallow_common_passwords,
             :hanami,
             :jwt_refresh,
             :login,
             :logout,
             :remember,
             :recovery_codes

      db Authentication::Slice["db.gateway"].connection

      # Feature (automatic): base
      accounts_table :user
      after_login { remember_login }
      already_logged_in { redirect "/" }
      flash_error_key :alert
      hmac_secret Hanami.app[:settings].app_secret
      login_label "Email"
      password_hash_table :user_password_hash
      require_login_error_flash "Please log in to continue."
      template_opts layout: nil
      unverified_account_message "Unverified user, please verify before logging in."

      # Feature (automatic): login_password_requirements_base
      require_password_confirmation? false

      # Feature: active_sessions
      active_sessions_account_id_column :user_id
      active_sessions_table :user_active_session_key

      # Feature: audit_logging
      audit_logging_table :user_authentication_audit_log
      audit_logging_account_id_column :user_id

      # Feature: change_login
      change_login_route "me/login"
      change_login_view { view "login_update", nil }

      # Feature: change_password
      change_password_route "me/password"
      change_password_view { view "password_update", nil }
      change_password_button "Save"

      # Feature: create_account
      create_account_button "Create"
      create_account_link_text "Register."
      create_account_route "register"
      create_account_view { view "register", nil }
      change_login_button "Save"

      after_create_account do
        user_id = account[:id]
        user_name = param "name"
        account_id = db[:account].insert label: user_name, name: user_name.snakecase

        db[:user].where(id: user_id).update name: user_name
        db[:membership].insert user_id: user_id, account_id:
      end

      # Feature (custom): hanami
      hanami_view(proc { View.new })

      # Feature: jwt
      jwt_secret Hanami.app[:settings].app_secret
      jwt_refresh_route "api/jwt"

      # Feature: jwt_refresh
      jwt_access_token_not_before_period Hanami.app[:settings].api_access_token_period
      jwt_refresh_token_account_id_column :user_id
      jwt_refresh_token_table :user_jwt_refresh_key

      # Feature: login
      login_error_flash "There was an error signing in."
      login_form_footer_links_heading { nil }
      login_notice_flash "You have been logged in."
      login_return_to_requested_location? true
      multi_phase_login_view { view "login_multi_phase", nil }

      # Feature: logout
      logout_notice_flash "You have been logged out."
      logout_redirect "/"

      # Feature: remember
      remember_button "Save"
      remember_table :user_remember_key
      remember_route "me/remember"

      # Feature: recovery_codes
      recovery_codes_table :user_recovery_code
    end

    route do |request|
      env["rodauth"] = rodauth
      request.rodauth
    end
  end
end

The above might seem daunting, at first, but is mostly configuration logic. You can read it from top to bottom as follows:

Define the middleware plugin because we definitely want Rodauth to behave like middleware so we can wire into our routes.
Define the rodauth plugin and then enable all of the features you want (this includes our custom hanami feature).
Configure each feature. Once again, there is a code comment that helps you jump to the associated Rodauth documentation of that feature.

Definitely spend time reading through Rodauth’s feature documentation to customize further as you can adjust for your needs.

View Context

In order to not repeat yourself and leverage common styles from your main application, you’ll want to include your application’s main assets. This can be done with this view:

# authentication/views/context.rb

# auto_register: false

module Authentication
  module Views
    # The slice view context.
    class Context < Hanami::View::Context
      include Deps[main_assets: "main.assets"]
    end
  end
end

The above will allow you to use your application’s assets (mostly styles) within all templates associated with this slice.

Routes

Necessary to ensure all routes are properly authenticated by using the new Rodauth middleware at the top of our routes.

module Demos
  # The application routes.
  class Routes < Hanami::Routes
    slice(:authentication, at: "/") { use Authentication::Middleware }
  end
end

Layouts/Templates

While you can get by with Rodauth’s default layouts and templates, you’ll want to customize further. The following documents the layouts and templates used to customize the UI. These are listed by pure file structure only since providing source code for each would be slightly overkill. That said, there is a process for customization which looks like this:

Open the Rodauth gem in your default text editor. If using Gemsmith, this is as simple as running: gemsmith --edit rodauth.
Once in your editor, open the templates folder where you’ll see multiple *.str files. These, roughly, map to each feature you enabled and configured earlier. You can then take the source code and convert to ERB syntax that is compatible with Hanami Views.
Repeat this process for each file you need to customize further.

Here’s what the file structure looks like after using the above process:

# Layouts
app/templates/layouts/authentication.html.erb

# Templates
slices/authentication/templates/layouts/app.html.erb
slices/authentication/templates/login.html.erb
slices/authentication/templates/login_update.html.erb
slices/authentication/templates/logout.html.erb
slices/authentication/templates/password_update.html.erb
slices/authentication/templates/register.html.erb
slices/authentication/templates/remember.html.erb

In case it helps, here’s an example of converting the Rodauth logout.str template to a Hanami logout.html.erb template:

From Rodauth (logout.str)

<form method="post" class="rodauth" role="form" id="logout-form">
  #{rodauth.logout_additional_form_tags}
  #{rodauth.csrf_tag}
  #{rodauth.button(rodauth.logout_button, :class=>'btn btn-warning')}
</form>

To Hanami (logout.html.erb)

<form method="post" class="rodauth" role="form" id="logout-form">
  <%== rodauth.logout_additional_form_tags %>
  <%== rodauth.csrf_tag %>
  <%== rodauth.button rodauth.logout_button, class: "btn btn-warning" %>
</form>

Actions

With the Rodauth Authentication slice in place, you’ll want to update your root application Action so all subclasses can inherit authentication behavior. This can be done by defining a protected authorize method with a subsequent private handle_rodauth_redirect for wiring in flash and redirect support. Example:

# auto_register: false

require "hanami/action"

module Demo
  # The application base action.
  class Action < Hanami::Action
    before :authorize

    protected

    def authorize request, response
      rodauth = request.env["rodauth"]

      return unless rodauth

      handle_rodauth_redirect(rodauth, response) { rodauth.require_account }

      response[:current_user_id] = rodauth.account_id
    end

    private

    def handle_rodauth_redirect rodauth, response
      halted = catch(:halt) { yield }

      return unless halted

      code, headers, body = *halted

      rodauth.flash.next.each { |key, value| response.flash[key] = value }
      response.redirect headers["Location"], code

      throw :halt, [code, body]
    end
  end
end

The above works for all UI and API requests. In rare situations where you need to disable the authorize before callback, you can override authorize as follows in your subclass:

# frozen_string_literal: true

module Demo
  module Actions
    module API
      module Log
        # The create action.
        class Create < Action
          # Truncated for brevity...

          protected

          def authorize(*) = nil
        end
      end
    end
  end
end

The above will completely disable the authentication check for you API log request (POST) with minimal effort.

RSpec

Now that everything is wired up, you’ll want to add a couple RSpec shared contexts to aid in writing your feature and request specs. First, here’s the with login shared context you can use for all feature (UI) specs:

# demo/spec/support/shared_contexts/login.rb

RSpec.shared_context "with login" do
  let(:user) { Factory[:user, :verified] }

  before do
    Factory[:user_password_hash, id: user.id]

    visit "/login"
    fill_in "login", with: user.email
    click_button "Login"

    fill_in "Password", with: "password"
    click_button "Login"
  end
end

Second, here’s the with JWT shared context you can use for all request (API) specs:

# demo/spec/support/shared_contexts/jwt.rb

RSpec.shared_context "with JWT" do
  let(:user) { Factory[:user, :verified] }

  let :access_token do
    post "/login",
         {login: user.email, password: "password"}.to_json,
         {"CONTENT_TYPE" => "application/json"}

    JSON[last_response.body, symbolize_names: true].fetch :access_token
  end

  before { Factory[:user_password_hash, id: user.id] }
end

Feel free to customize a needed but the above will allow you to quickly authenticate, for testing purposes, when writing feature and request specs.

Tools

Due to Rodauth having a rich feature set, it quickly becomes tiresome jumping around the docomentation so, for Alfred fans, you might want to leverage the Pennyworth gem which provides a Rodauth Workflow for quick access to the documentation. Even better you can fuzzy type to quickly jump to any of the supported features.

Conclusion

As mentioned earlier, there is definitely a learning curve when folding Rodauth into your web application but is much faster/better than implementing this yourself. Plus, as you’ve seen, there’s plenty of opportunity to customize for your specific needs.

The core integration happens via the Rodauth feature and corresponding middleware. The rest is getting up to speed with all Rodauth’s feature then leveraging the power of Hanami slices, routes, views, layouts, and templates to customize as desired.

May your application be secure!