Alchemists: News

Metapath Project

2026-10-08T22:31:01+00:00

Metapath

Dynamically parses and enriches paths metadata so you can obtain information from directories and files with minimal effort. Having metadata for each directory and/or file — no matter how nested your directory structure is — allows you to perform additional processing on your file structure for analysis, transformation, import, and so much more.

Table of Contents

Features

Dynamically obtains metadata about a directory or a file.
Supports an optional, per directory, configuration.
Supports nested directory structures.
Answers an array of paths with associated metadata.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install metapath --trust-policy HighSecurity

To install without security, run:

gem install metapath

You can also add the gem directly to your project:

bundle add metapath

Once the gem is installed, you only need to require it:

require "metapath"

Usage

Getting started is as quick as creating an instance and then pointing it at a directory structure:

metapath = Metapath.new
metapath.call Pathname.pwd

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      errors = {},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >,
    #<data Metapath::Model:0x00002780
      attributes = {},
      errors = {},
      label = "Flaming Gorge",
      name = "flaming_gorge",
      path = #<Pathname:/Users/demo/Scratch/photos/Flaming_Gorge.jpeg>,
      position = 0,
      tags = []
    >,
    #<data Metapath::Model:0x000027f0
      attributes = {},
      errors = {},
      label = "Grand Canyon",
      name = "grand_canyon",
      path = #<Pathname:/Users/demo/Scratch/photos/Grand_Canyon.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

Roots

When calling a metapath, you must always supply a root path for processing. In the earlier example, this was Pathname.pwd (current path):

metapath.call Pathname.pwd

Strings, if supplied, will be automatically converted into pathnames and auto-expanding into absolute paths. Examples:

metapath.call "~/photos"
# Expands to: #<Pathname:/Users/<your user>/photos>

metapath.call "photos"
# Expands to: #<Pathname:<current working directory>/photos>

metapath.call "/Users/demo/photos"
# Identical: "#<Pathname:/Users/demo/photos>"

All directories and files will be processed within the root path supplied (no matter how deeply nested).

Directories and Files

Each directory and file can have it’s own metadata using any of the following characters:

0-9: Any number is valid.
a-z: Any lowercase letter is valid. This includes Unicode.
A-Z: Any uppercase letter is valid. This includes Unicode.
- (hyphen): Translates to " - " when building the label. Example:
- Before: A-Demo.
- After: A - Demo.
_ (underscore): Translates to " " when building the label. Example:
- Before: A_Demo.
- After: A Demo.
+ (plus): Marks the start of tag or attribute information. See examples below for details.
, (comma): Specifies an array of tag or attribute metdata. See examples below for details.
= (equals): Delimits the key and value of an attribute. For example kind=demo, where kind is the key and demo is the value.
% (percent): Reserved for token replacement as commonly found in Rubysmith for processing of templates where you want to dynamically replace each placeholder (example: %demo%) with a dynamic value that matches the demo key (in this example). Currently meant for post-processing.
. (dot): Reserved for file extensions or multiple formats. Example: demo.html, demo.html.erb, etc.
~ (tilde): Reserved but currently not used.
@ (at): Reserved but currently not used.
^ (carrot): Reserved but currently not used.

All of the characters shown above allow you to have files and directories that don’t require special quoting which works well across multiple operating systems.

Positions

Prefix your directories or files with a number immediately followed by a dash to keep them organized but also for sequential processing order.

Format: <position>-<name>
Example 01-demo

The position is always 0 when none is given.

Attributes

Use attributes to provide additional metadata about your directories and files (use a comma to separate multiple values).

Format (single): <name>+<key>=<value>
Example (single): demo+album=panoramas
Format (multiple): <name>+<key>=<value>,<key>=<value>,<key>=<value>
Example (multiple): demo+album=panoramas,kind=landscapes,location=snow_peak

💡 Use a directory configuration (meta.yml) to extract common metadata if your metadata gets too long and unwieldy.

Configurations

You can configure common metadata per directory by placing a meta.yml in the root of any directory. The following is an example of what this file might contain:

tags:
  - demo
  - photos
attributes:
  album: panoramas
  kind: landscapes

With the above, you can supply as many tags and attributes as necessary which will then be inherited as common metadata when processing files within the directory. This includes inheriting configurations from parent directories. Keep in mind that any file with it’s own metdata will take precedence.

Only the tag and attributes keys are honored, all other top level keys are ignored.

Priority

Metadata is resolved by merging each of the following in order listed (lowest to highest):

Directory
meta.yml
File

Resolution of the above happens by merging metadata from the lowest level into the next level until all levels are merged as one. This means you can set defaults at the lowest level which will be inherited, or overwritten, at the highest level. In pseudo code, it looks like this:

directory.deep_merge(meta).deep_merge file

Monads

Every time you call your metapath instance, you’ll get either a Success or Failure as provided by Dry Monads. This allows you to use the Railway Pattern pattern to build fault tolerant functional pipelines for robust error processing.

When results are a success, you’ll get an array of models. Example:

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

You can get a success when errors are detected with metadata associated with your directories or files. For example, let’s say your meta.yml has the following content:

attributes:

Success(
  [
    #<data Metapath::Model:0x00002710
      attributes = {},
      errors = {attributes: ["must be filled"]},
      label = "Crested Butte",
      name = "crested_butte",
      path = #<Pathname:/Users/demo/Scratch/photos/Crested_Butte.jpeg>,
      position = 0,
      tags = []
    >
  ]
)

If a failure does occur, this usually means errors with your configuration. For example, let’s say your meta.yml has the following content:

Danger!

This means you’ll get the following result:

Failure "Invalid content: Danger."

Models

Each model is a Data object. Additionally, the following methods are also provided for you:

model = Metapath::Model[
  name: "demo",
  label: "Demo",
  tags: %w[demo photos],
  attributes: {
    "album" => "panoramas",
    "kind" => "landscapes"
  }
]

model.fetch "album"                  # "panoramas"
model.fetch "bogus", "fallback"      # "fallback"
model.fetch("bogus") { "fallback" }  # "fallback"
model.fetch "bogus"                  # KeyError

model.key? "album"                   # true
model.key? "bogus"                   # false

model.tag? "photos"                  # true
model.tag? "bogus"                   # false

other = Metapath::Model[name: "other", path: Pathname("_demo.html")]

other.partial?                       # true
model.partial?                       # false

other = Metapath::Model[name: "other", path: Pathname("demo.html"), errors: {message: "Danger!"}]

other.errors?                       # true
model.errors?                       # false

Development

To contribute, run:

git clone https://github.com/bkuhlmann/metapath
cd metapath
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

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.

Superfluid Project

2026-08-30T20:54:20+00:00

Superfluid

Enhances Liquid by smoothing out the rough edges with a strong focus on object composition and functional design. This includes a fully functional filter and tag registry so you can reuse lower level filters and tags within all aspects of your view layer.

Table of Contents

Features

Uses a customizable default environment with a cleaner Object API.
Uses Containable for filter and tag registries.
Registers filters via a Module, Functionable, commands (see Command Pattern for details), or containers (see Containable for details).
Registers tags via classes or containers (see Containable for details).
Provides a default renderer for quick rendering of templates and associated data.

Requirements

Ruby.
Liquid.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install superfluid --trust-policy HighSecurity

To install without security, run:

gem install superfluid

You can also add the gem directly to your project:

bundle add superfluid

Once the gem is installed, you only need to require it:

require "superfluid"

Usage

The quickest way to get started is to create a new instance:

renderer = Superfluid.new

Then you can render your template and associated data:

renderer.call "Hi, this is a {{ value }}.", "value" => "demo"

The above will yield the following output:

"Hi, this is a demo."

The following sections detail how you can configure your environment, register filters, and register tags.

Configuration

The configuration is used by the environment. This is created for you automatically but if you want an instance of the default configuration, use:

configuration = Superfluid::Configuration.new

#<Struct:Superfluid::Configuration:0x00001780
  default_resource_limits = {},
  error_mode = :strict,
  exception_renderer = #<Proc:0x0000000131200ee0 (lambda)>,
  file_system = #<data Superfluid::Systems::Memory:0x000017b0 templates = {}>,
  filter_registry = #<Superfluid::Registries::Filter:0x000000012f5a1290 @container=Superfluid::Filters::Container, @mode=:strict>,
  tag_registry = #<Superfluid::Registries::Tag:0x000000012f5860d0 @container=Superfluid::Tags::Container>
>

As you can see, the configuration is a Struct which means you can customize using any of these attributes:

default_resource_limits: Limits the resources that a template can consume. Default: {}.
error_mode: The error mode (details). Default: :strict.
exception_renderer: The function used to render error messages. Default: Core::Identity (see Core).
file_system: The file system. Default: Superfluid::Systems::Memory.new.
filter_registry: The filter registry. Default: Superfluid::Registries::Filter.new.
tag_registry: The tag registry. Default: Superfluid::Registries::Tag.new.

Environments

To build the default environment, use:

environment = Superfluid.build

To build the default environment directly (which is what the above does), use:

environment = Superfluid::Environment.new

If you’d like to build a custom environment, you can do this several ways. For demonstration purposes, only the error_mode is used below but all configuration attributes are accepted:

environment = Superfluid.build error_mode: :lax
environment = Superfluid::Environment.for error_mode: :lax
environment = Superfluid::Environment.new Superfluid::Configuration[error_mode: :lax]

You can also freeze the environment — which also freezes the filter and tag registries — once you’ve registered any/all filters and tags as follows:

environment.freeze

Systems

These are the file systems used to obtain templates for use within your custom tags. By default, an in memory system is provided for you: Superfluid::Systems::Memory. Liquid also provides it’s own systems as well. Each are described below.

Memory

Provided by this gem. Use to access templates via an in memory file system. This is enabled for you be default when using Superfluid.new and works in conjunction with the template tag which is also provided by this gem (see below for details). Again, this system is provided for you but you can be explicit if desired:

environment = Superfluid.build file_system: Superfluid::Systems::Memory.new
renderer = Superfluid.new(environment:)

template = <<~CONTENT
  {% template demo %}
    Hi, this is a {{ subject }}.
  {% endtemplate %}

  {% render "demo", subject: "demo" %}
CONTENT

renderer.call template
# "Hi, this is a demo."

Local

Provided by Liquid. Use to access templates via your local file system within a specific root folder. Usage:

Pathname("templates").tap(&:mkdir).join("_demo.liquid").tap { it.write "{{ salutation }}" }

environment = Superfluid.build file_system: Liquid::LocalFileSystem.new(Pathname("templates"))
renderer = Superfluid.new(environment:)

renderer.call(%({% include "demo" %}, this is a demo), {"salutation" => "Hi"})
# "Hi, this is a demo"

The above configures the local system to look for partials (templates) within the templates folder. You then reference them via the include tag.

By default, this system uses Kernel#format syntax to find your partials (i.e. "_%s.liquid"). If you don’t like this pattern, you can configure differently when creating a new instance. Example:

Liquid::LocalFileSystem.new "/a/path", "%s.html"

Blank

Provided by Liquid. This is an abstract class — meant for subclassing — because it will fail with a FileSystemError when read_template_file isn’t implemented. Usage:

environment = Superfluid.build file_system: Liquid::BlankFileSystem.new(Pathname("templates"))
renderer = Superfluid.new(environment:)

The above does nothing and is benign.

Filters

By default, Liquid only allows registration of filters as instance methods on a namespace (Module). Unfortunately, this leads to terrible design, bad practices, and unnecessarily hard to test objects. You can still register namespaces but this gem encourages the use of commands (see Command Pattern for further details) and containers via Containable which allows you tap into Functional Programming by using procs, lambdas, and any object that responds to #call. This allows you to build — and reuse — more powerful filters. The following details the different kinds of filters you can use, each broken down by category.

Defaults

Default filters are provided for you automatically and can be viewed via your environment. Example:

environment = Superfluid.build
environment.filter_registry.names

The above will produce a list of all registered filters. These including all filters provided by Liquid and those unique to this gem which are:

`jsonify`

Renders objects as JSON. Example:

renderer.call(%({{ data | jsonify }}), {"data" => {"a" => 1}})
# "{\"a\":1}"

`parse_json`

Parses JSON as a primitive. Example:

renderer.call(
  "{% assign data = payload | parse_json %}{{ data.one }}",
  {"payload" => %({"one": 1, "two": 2})}
)

# "1"

`pluralize`

Renders a plural string. Example:

renderer.call(%({{ text | pluralize: 0 }}), {"text" => "apple"})
# "0 apples"

renderer.call(%({{ text | pluralize: 1 }}), {"text" => "apple"})
# "1 apple"

renderer.call(%({{ text | pluralize: 2 }}), {"text" => "apple"})
# "2 apples"

renderer.call(%({{ text | pluralize: 3, "i", "us" }}), {"text" => "octopus"})
# "3 octopi"

`singularize`

Renders a singular string. Example:

renderer.call(%({{ text | singularize: 0 }}), {"text" => "apples"})
# "0 apples"

renderer.call(%({{ text | singularize: 1 }}), {"text" => "apples"})
# "1 apple"

renderer.call(%({{ text | singularize: 2 }}), {"text" => "apples"})
# "2 apples"

renderer.call(%({{ text | singularize: 1, "i", "us" }}), {"text" => "octopi"})
# "1 octopus"

`trim_end`

Renders string with trimmed end. Example:

renderer.call(%({{ text | trim_end: 10 }}), {"text" => "A demo."})
# "A demo."

renderer.call(%({{ text | trim_end: 10 }}), {"text" => "This is a demo."})
# "This is..."

renderer.call(%({{ text | trim_end: 10, "", "---" }}), {"text" => "This is a demo."})
# "This is---"

renderer.call(%({{ text | trim_end: 10, "", "" }}), {"text" => "This is a demo."})
# "This is a"

`trim_middle`

Renders string with trimmed middle. Example:

renderer.call(%({{ text | trim_middle: 20 }}), {"text" => "This is a demo."})
# "A demo."

renderer.call(%({{ text | trim_middle: 13 }}), {"text" => "This is a demo."})
# "This...demo."

renderer.call(%({{ text | trim_middle: 13, "--" }}), {"text" => "This is a demo."})
# "This--demo."

Modules

Module instance methods are what Liquid supports by default. You only need to define instance methods within a module and then register your module. Example:

# Namespaces
module Primary
  def echo(text) = text
end

module Secondary
  def capitalize(text) = text.capitalize

  def suffix(text, count = 1) = "#{text}-#{count}"
end

# Renderer
renderer = Superfluid.new { it.register_filters Primary, Secondary }

# Results
renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

As you can see, all three methods via the two namespaces are properly registered and immediately available for use. You’ll also notice multiple namespaces were registered at once but you can register them individually and/or chain them. Examples:

Superfluid.new do |environment|
  # Single.
  environment.register_filter Primary

  # Multiple.
  environment.register_filters Primary, Secondary

  # Chained.
  environment.register_filter(Primary)
             .register_filter(Secondary)
             .register_filters(Primary, Secondary)
end

Functionables

Functionable modules are identical to the module examples, as shown above, except you require and extend instead. Example:

require "functionable"

# Namespaces
module Primary
  extend Functionable

  def echo(text) = text
end

module Secondary
  extend Functionable

  def capitalize(text) = text.capitalize

  def suffix(text, count = 1) = "#{text}-#{count}"
end

This allows you to use purely functionable methods (see Functionable documentation for details). At this point, you can register your functionable namespaces as follows:

# Renderer
renderer = Superfluid.new { it.register_filters Primary, Secondary }

# Results
renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration is identical to modules:

Superfluid.new do |environment|
  # Single.
  environment.register_filter Primary

  # Multiple.
  environment.register_filters Primary, Secondary

  # Chained.
  environment.register_filter(Primary)
             .register_filter(Secondary)
             .register_filters(Primary, Secondary)
end

Procs and Lambdas

Procs and lambdas are not supported by Liquid but are via this gem. Example:

# Setup

echo = proc { it }
capitalize = -> text { text.capitalize }
suffix = -> text, count = 1 { "#{text}-#{count}" }

# Renderer
renderer = Superfluid.new { it.register_filters echo:, capitalize:, suffix: }

# Results

renderer.call %({{ "demo" | echo }})        # "demo"
renderer.call %({{ "demo" | capitalize }})  # "Demo"
renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration can be singular, plural, or chained:

renderer = Superfluid.new do |environment|
  # Single.
  environment.register_filter(echo:)

  # Multiple.
  environment.register_filters(echo:, capitalize:, suffix:)

  # Chained.
  environment.register_filter(echo:)
             .register_filter(capitalize:)
             .register_filters(echo:, capitalize:, suffix:)
end

Classes

Classes, especially composable classes, are not supported by Liquid but are via this gem. You only need to ensure you include Core::Composable and implement the #call method. Example:

require "core"

class Suffixer
  include Core::Composable

  def initialize default: 1
    @default = default
  end

  def call(text, suffix = default) = "#{text}-#{suffix}"

  private

  attr_reader :default
end

Now you can register and render with the above class as follows:

# Renderer
renderer = Superfluid.new { it.register_filters suffix: Suffixer.new }

# Results

renderer.call %({{ "demo" | suffix }})      # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"

Registration can be singular, plural, or chained:

suffix = Suffixer.new

renderer = Superfluid.new do |environment|
  # Single.
  environment.register_filter(suffix:)

  # Multiple.
  environment.register_filters(suffix:)

  # Chained.
  environment.register_filter(suffix:)
             .register_filters(suffix:)
end

Containers

Containers are not supported by Liquid but are via this gem using Containable. To use, create a container and then register your dependencies:

require "containable"

module Container
  extend Containable

  register(:echo) { |text| text }
  register(:suffix) { |text, count = 1| "#{text}-#{count}"  }
end

Now you can merge the container as follows:

renderer = Superfluid.new { it.merge_filters Container }

You can also selectively merge by supplying only the filters you care about from the container:

renderer = Superfluid.new { it.merge_filters Container, :suffix }

Once registered, then you can use as follows:

renderer.call %({{ "demo" | echo }})       # "demo"
renderer.call %({{ "demo" | suffix }})     # "demo-1"
renderer.call %({{ "demo" | suffix: 2 }})  # "demo-2"

With containers, you have the full capabilities of the Containable. The above only scratches the surface of what’s possible.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/superfluid
cd superfluid
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

RFC API Problem Project

2026-08-22T20:29:24+00:00

RFC API Problem

RFC API Problem implements RFC 9457: Problem Details for HTTP APIs. This allows you to produce HTTP error responses that are structured, machine readable, and consistent.

Table of Contents

Features

Provides JSON and XML serialization and deserialization.
Provides HTTP header and media type support.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rfc-api-problem --trust-policy HighSecurity

To install without security, run:

gem install rfc-api-problem

You can also add the gem directly to your project:

bundle add rfc-api-problem

Once the gem is installed, you only need to require it:

require "rfc/api/problem"

Usage

The quickest way to get started is to create a new instance and then cast as JSON or XML:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/timeout",
  status: 413,
  detail: "You've exceeded the 5MB upload limit.",
  instance: "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
]

payload.to_json

# {
#   "type" => "https://demo.io/problem_details/timeout",
#   "title" => "Content Too Large",
#   "status" => 413,
#   "detail" => "You've exceeded the 5MB upload limit.",
#   "instance" => "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
# }

payload.to_xml

# <?xml version='1.0' encoding='UTF-8'?>
# <problem xmlns='urn:ietf:rfc:7807'>
#   <type>https://demo.io/problem_details/timeout</type>
#   <title>Content Too Large</title>
#   <status>413</status>
#   <detail>You&apos;ve exceeded the 5MB upload limit.</detail>
#   <instance>/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3</instance>
# </problem>

💡 You can also use RFC::API::Problem.new to create instances if you don’t like RFC::API::Problem.[], as shown above, but .[] is preferred.

Members

As briefly shown above, the minimum members (attributes) that make up problem details are:

type (optional): The full (or relative) URI that links to additional documentation. Default: "about:blank".
status (optional): The HTTP status code (or symbol) that must match your HTTP status code. Default: nil.
title (optional): The HTTP status label that must match your HTTP status code label. Default: HTTP status label (dynamically computed based on code unless overwritten).
detail (optional): The human readable reason for the error (should not include debugging information). Default: nil.
instance (optional): The full (or relative) URI that represents the cause of the error. Default: nil.
extensions (optional): A free form hash of additional details. Default: {}.

Media Types

For convenience, you can obtain the necessary media types for your HTTP headers as follows:

RFC::API::Problem::MEDIA_TYPE_JSON  # "application/problem+json"
RFC::API::Problem::MEDIA_TYPE_XML   # "application/problem+xml"

RFC::API::Problem.media_type_for :json  # "application/problem+json"
RFC::API::Problem.media_type_for :xml   # "application/problem+xml"

Payload

You’ll always get a RFC::API::Problem::Payload object answered back when using RFC::API::Problem.[] or RFC::API::Problem.new for which you can cast to JSON, XML, and other types. There are few conveniences provided for you when constructing a new payload. For instance, you can also use status to set default title:

RFC::API::Problem[status: 413]

# #<data RFC::API::Problem::Payload:0x00002950
#   detail = nil,
#   extensions = {},
#   instance = nil,
#   status = 413,
#   title = "Content Too Large",
#   type = "about:blank"
# >

Notice that standard HTTP 413 title of "Content Too Large" is provided for you but only if you don’t supply a title. This works for symbols too. Example:

RFC::API::Problem[status: :bad_request]

# #<data RFC::API::Problem::Payload:0x00002970
#   detail = nil,
#   extensions = {},
#   instance = nil,
#   status = 400,
#   title = "Bad Request",
#   type = "about:blank"
# >

This is similar to the above, but notice the status is cast to an integer while the title is also populated for you. Using either an integer or symbol for the HTTP status is handy for situations where you don’t need a custom title and prefer the default HTTP title.

Due to the payload being a Data object, you have all of the standard methods available to you which are frozen by default. That said, you can still add or check for extensions after the fact. Example:

payload = RFC::API::Problem[status: :forbidden]

payload.add_extension(:account, "/accounts/1")
       .add_extension(:balance, 50)

# #<data RFC::API::Problem::Payload:0x000029a0
#   detail = nil,
#   extensions = {
#     account: "/accounts/1",
#     balance: 50
#   },
#   instance = nil,
#   status = 403,
#   title = "Forbidden",
#   type = "about:blank"
# >

Given the above, you can also check if an extension exists:

payload.extension? :account  # true
payload.extension? :bogus    # false

JSON

Both serialization and deserialization of JSON is supported. For example, given the following payload:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/out_of_credit",
  title: "You do not have enough credit.",
  status: 403,
  detail: "Your current balance is 30, but that costs 50.",
  instance: "/accounts/1",
  extensions: {
    balance: 30,
    accounts: %w[/accounts/1 /accounts/10]
  }
]

This means you can serialize as follows:

payload.to_json

# "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"

payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"

# {
#   "type": "https://demo.io/problem_details/out_of_credit",
#   "title": "You do not have enough credit.",
#   "status": 403,
#   "detail": "Your current balance is 30, but that costs 50.",
#   "instance": "/accounts/1",
#   "balance": 30,
#   "accounts": [
#     "/accounts/1",
#     "/accounts/10"
#   ]
# }

💡 All of the JSON output options are available to you when casting to JSON.

You can also deserialize by taking the result of the above and turning the raw JSON back into a RFC::API::Problem::Payload:

RFC::API::Problem.from_json "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"

# #<data RFC::API::Problem::Payload:0x00002d10
#   detail = "Your current balance is 30, but that costs 50.",
#   extensions = {
#      balance: 30,
#     accounts: [
#       "/accounts/1",
#       "/accounts/10"
#     ]
#   },
#   instance = "/accounts/1",
#   status = 403,
#   title = "You do not have enough credit.",
#   type = "https://demo.io/problem_details/out_of_credit"
# >

XML

XML is supported too but isn’t as robust as JSON support, at the moment. This is mostly due to the fact that extensions can be deeply nested so your mileage may vary. For example, given the following payload:

payload = RFC::API::Problem[
  type: "https://demo.io/problem_details/out_of_credit",
  title: "You do not have enough credit.",
  status: 403,
  detail: "Your current balance is 30, but that costs 50.",
  instance: "/accounts/1",
  extensions: {
    balance: 30,
    accounts: %w[/accounts/1 /accounts/10]
  }
]

This means you can serialize as follows:

payload.to_xml
# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://demo.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"

payload.to_xml indent: 2
# <?xml version='1.0' encoding='UTF-8'?>
# <problem xmlns='urn:ietf:rfc:7807'>
#   <type>
#     https://demo.io/problem_details/out_of_credit
#   </type>
#   <title>
#     You do not have enough credit.
#   </title>
#   <status>
#     403
#   </status>
#   <detail>
#     Your current balance is 30, but that costs 50.
#   </detail>
#   <instance>
#     /accounts/1
#   </instance>
#   <balance>
#     30
#   </balance>
#   <accounts>
#     <i>
#       /accounts/1
#     </i>
#     <i>
#       /accounts/10
#     </i>
#   </accounts>
# </problem>

💡 All of the REXML::Document.write output options are available to you when casting to XML.

You can also deserialize by taking the result of the above and turning the raw JSON back into a RFC::API::Problem::Payload:

payload = RFC::API::Problem.from_xml <<~XML
  <?xml version='1.0' encoding='UTF-8'?>
  <problem xmlns='urn:ietf:rfc:7807'>
    <type>https://demo.io/problem_details/out_of_credit</type>
    <title>You do not have enough credit.</title>
    <status>403</status>
    <detail>Your current balance is 30, but that costs 50.</detail>
    <instance>/accounts/1</instance>
    <balance>30</balance>
    <accounts>
      <i>/accounts/1</i>
      <i>/accounts/10</i>
    </accounts>
  </problem>
XML

# #<data RFC::API::Problem::Payload:0x00000940
#   detail = "Your current balance is 30, but that costs 50.",
#   extensions = {
#      balance: "30",
#     accounts: [
#       "/accounts/1",
#       "/accounts/10"
#     ]
#   },
#   instance = "/accounts/1",
#   status = 403,
#   title = "You do not have enough credit.",
#   type = "https://demo.io/problem_details/out_of_credit"
# >

Examples

There is a lot of useful information you can provide in your problem details depending on the context you are working in. Some have been shown above but here’s a few more that might be of interest.

HATEOAS

With HATEOAS, you can provide additional information and links for which the client can understand what next actions are available. The below example shows how you can provide additional resources for clients to adjust accordingly:

RFC::API::Problem[
  type: "https://demo.io/problem_details/rate_limit",
  title: "Rate limit exceeded",
  status: 429,
  detail: "You have exceeded your rate limit of 150 requests per minute",
  instance: "/articles",
  extensions: {
    retry_after: 5,
    links: [
      {
        ref: "self",
        href: "/articles"
      },
      {
        rel: "retry",
        href: "/articles",
        title: "Retry after five minutes"
      },
      {
        rel: "status",
        href: "/statuses/rate_limit",
        title: "Check current rate limit usage"
      }
    ]
  }
]

Semantic Structure

In other situations, you might need a different structure in order to aid clients that might be AI driven which needs a semantically structured response in order to course correct. Example:

RFC::API::Problem[
  type: "https://demo.io/problem_details/invalid_field",
  title: "Invalid field value",
  status: 400,
  detail: "The category requested doesn't exist",
  instance: "/categories",
  extensions: {
    parameters: {
      category_id: 123
    },
    suggestions: [
      "ruby",
      "git",
      "htmx"
    ]
  }
]

With the above, the client now knows what parameters where invalid along with relevant suggestions for proceeding. Even better, the suggestions implicitly show the types of IDs that are required.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rfc-api-problem
cd rfc-api-problem
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Resources

You can find additional resources here:

IANA Hypertext Transfer Protocol (HTTP) Problem Types: A registered list of problem types you can use.
HTTP Problem Type Registration Requests: Where you can register new problem types.

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

RFC Web Link Project

2026-08-22T17:22:35+00:00

RFC Web Link

RFC Web Link implements RFC 8288: Web Linking. This allows you to process links via the HTTP link header when processing HTTP responses. For example, the following demonstrates a HTTP link header which links to a previous and next article:

link: <https://demo.io/articles?page=1>; rel="previous"; title="Previous",
      <https://demo.io/articles?page=3>; rel="next"; title="Next"

The above parses each line, delimited by a comma (,), and then each pair (attribute) in the line as delimited by a semicolon (;). This is not something you want to reinvent for each application you maintain so this gem handles the parsing (and creation) of HTTP link headers so you can stay focused on your own business logic.

Table of Contents

Features

Implements RFC 8288.
Parses web link headers into whole value objects for processing and/or inspection.
Provides explicit or implicit casting of whole value objects into a web links.

Requirements

Ruby.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install rfc-web-link --trust-policy HighSecurity

To install without security, run:

gem install rfc-web-link

You can also add the gem directly to your project:

bundle add rfc-web-link

Once the gem is installed, you only need to require it:

require "rfc/web/link"

Usage

The fastest way to get started is to create a new instance of the parser that you can reuse upon each HTTP request. Example:

parser = RFC::Web::Link.new "https://demo.io"

Then you can use the parser instance to parse HTTP headers and build lists you can interact with:

parser.call({"link" => "</articles>; rel=index"})

The above will yield the following set of links (in this case, only with a single link):

#<data RFC::Web::Link::Models::List:0x00000900
  links = [
    #<data RFC::Web::Link::Models::Link:0x00000920
      pairs = [                                                                                                                                                                                  #<data RFC::Web::Link::Models::Pair:0x00000940
          delimiter = "=",
          encoding = nil,
          key = "rel",
          language = nil,
          value = "index"
        >
      ],
      uri = "https://demo.io/articles"
    >
  ]
>

As you can see, you get an immutable Data (whole value) object for which you can directly access all attributes.

Root URI

A root URI (root_uri) must be supplied in order to resolve all relative URIs as absolute URIs. Generally, the root_uri is your host (i.e. primary domain). There are a few ways you can supply the root URI:

Initialization

The following sets the root URI globally so you only have to define it once:

parser = RFC::Web::Link.new "https://demo.io"

Call

The following sets the root URI per call.

parser = RFC::Web::Link.new
parser.call({"link" => "</articles>; rel=index"}, root_uri: "https://demo.io")

Call (override)

The following sets the root URI globally but also allows you to override the global value with a custom value per call.

parser = RFC::Web::Link.new "https://demo.io"

parser.call({"link" => "</articles>; rel=index"}, root_uri: "https://alt.io")

Delimiters

Each delimiter provides the following behavior:

Semicolon (;): Delimits each pair associated with a line.
Comma (,): Delimits each line of a link.

They must be quoted when not used as delimiters.

Attributes

There are six RFC 8288 registered target attributes:

anchor
hreflang
media
rel
title
type

Each is described in detail below.

anchor

Optional but, when supplied, can be a single string, quoted with special characters, a relative URI, or an absolute URI. Here’s a few examples:

Fragment: #footer
Quoted (special characters): "#overview,body,footer"
Relative URI: /policies
Absolute URI: https://demo.io/about

Relative URIs will automatically be expanded into an absolute URIs when parsed. This means if the root_uri is https://demo.io and the anchor’s value is /policies (relative), then the resulting URI will be: https://demo.io/polices. Examples:

Fragment

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=#footer"})

# #<data RFC::Web::Link::Models::List:0x000016f0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00001710
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001730
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "#footer"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
>

list.to_s

# "<https://demo.io/articles>; anchor=#footer"

Quoted

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => %(</articles>; anchor="#overview,body,footer")})

# #<data RFC::Web::Link::Models::List:0x00001660
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00001680
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000016a0
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "\"#overview,body,footer\""
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=\"#overview,body,footer\""

Relative URI

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=/policies"})

# #<data RFC::Web::Link::Models::List:0x000017c0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000017e0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001800
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "https://demo.io/policies"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=https://demo.io/policies"

Absolute URI

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; anchor=https://demo.io/about"})

# #<data RFC::Web::Link::Models::List:0x00001890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000018b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000018d0
#           delimiter = "=",
#           encoding = nil,
#           key = "anchor",
#           language = nil,
#           value = "https://demo.io/about"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; anchor=https://demo.io/about"

hreflang

Optional but, when supplied, is a hint indicating the language of the associated link. This does not override the value of the content-language header. Example:

Single

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; hreflang=en"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "en"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hreflang=en"

Multiple

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; hreflang=en; hreflang=de"})

# #<data RFC::Web::Link::Models::List:0x000016c0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000016e0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001700
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "en"
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00001740
#           delimiter = "=",
#           encoding = nil,
#           key = "hreflang",
#           language = nil,
#           value = "de"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hreflang=en; hreflang=de"

media

Optional but, when supplied, is a hint indicating the kind of media associated with the link. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; media=print"})

# #<data RFC::Web::Link::Models::List:0x000017d0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000017f0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00001810
#           delimiter = "=",
#           encoding = nil,
#           key = "media",
#           language = nil,
#           value = "print"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; media=print"

rel

Required and must be first defined. Example:

Single

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; rel=index"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "index"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; rel=index"

Shorthand

Short hand, for multiple relations, is supported as well. To use, each relation must be delimited by a space within a single quoted string. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => %(</articles>; rel="one two three")})

# #<data RFC::Web::Link::Models::List:0x00000960
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000980
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000009a0
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "one"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >,
#     #<data RFC::Web::Link::Models::Link:0x000009f0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000a10
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "two"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >,
#     #<data RFC::Web::Link::Models::Link:0x00000a60
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000a80
#           delimiter = "=",
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = "three"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; rel=one, <https://demo.io/articles>; rel=two, <https://demo.io/articles>; rel=three"

Notice that the original relation short hand of "one two three" produced three unique links for each relation which allows you to type less while still producing three distinct links.

title

Optional but, when supplied, allows you to provide a human readable label for the associated link. This includes being able to encode and decode the value based on the delimiter used. For example, notice the difference in delimiters used below:

Plain (=): title=Demo (example)
Encoded (*=): title*=UTF-8'en'd%C3%A9j%C3%A0%20vu (example)

The title must not appear more than once. If multiple occurrences are detected then only the first is honored. Also, if = and *= is used then *= takes precedence. Examples:

Without Encoding

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; title=Demo"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "title",
#           language = nil,
#           value = "Demo"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; title=Demo"

With Encoding

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; title*=UTF-8'en'd%C3%A9j%C3%A0%20vu"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "*=",
#           encoding = "UTF-8",
#           key = "title",
#           language = "en",
#           value = "déjà vu"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; title*=UTF-8'en'd%C3%A9j%C3%A0%20vu"

type

Optional but, when supplied, is a hint indicating the MIME Type of the associated link. This does not override the value of the content-type header. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; type=text/html"})

# #<data RFC::Web::Link::Models::List:0x00000890
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000008d0
#           delimiter = "=",
#           encoding = nil,
#           key = "type",
#           language = nil,
#           value = "text/html"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; type=text/html"

Extensions

Extensions allow you to extend your implementation beyond the registered target attributes, described above, with your own custom attributes. For example, maybe you want to use the following attributes which are specific to your application: hint, errata, copyright. You can do this as follows:

parser = RFC::Web::Link.new "https://demo.io"

list = parser.call(
  {"link" => %(</articles>; hint="A demo."; errata="For demonstration only."; copyright=2025)}
)

# #<data RFC::Web::Link::Models::List:0x00000980
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000009a0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x000009c0
#           delimiter = "=",
#           encoding = nil,
#           key = "hint",
#           language = nil,
#           value = "\"A demo.\""
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00000a00
#           delimiter = "=",
#           encoding = nil,
#           key = "errata",
#           language = nil,
#           value = "\"For demonstration only.\""
#         >,
#         #<data RFC::Web::Link::Models::Pair:0x00000a40
#           delimiter = "=",
#           encoding = nil,
#           key = "copyright",
#           language = nil,
#           value = "2025"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; hint=\"A demo.\"; errata=\"For demonstration only.\"; copyright=2025"

You can also encode your extensions by using the *= delimiter. Example:

parser = RFC::Web::Link.new "https://demo.io"
list = parser.call({"link" => "</articles>; demo*=UTF-8'en'd%C3%A9j%C3%A0%20vu"})

# #<data RFC::Web::Link::Models::List:0x00000ad0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000af0
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000b10
#           delimiter = "*=",
#           encoding = "UTF-8",
#           key = "demo",
#           language = "en",
#           value = "déjà vu"
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

list.to_s

# "<https://demo.io/articles>; demo*=UTF-8'en'd%C3%A9j%C3%A0%20vu"

Models

You’ve already seen all of the models (whole value objects) used in the examples above but this section details what you can do with each model individually.

List

This model has both Data and Enumerable behavior because it encapsulates the list of links parsed from an HTTP link header or created by you. A list can be created multiple ways:

All At Once

list = RFC::Web::Link::Models::List[
  links: Set[
    RFC::Web::Link::Models::Link[
      uri: "https://demo.io",
      pairs: Set[
        RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
      ]
    ]
  ]
]

💡 Ensure you use a Set when adding your links and pairs.

Separately

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
list = RFC::Web::Link::Models::Link[uri: "https://demo.io"].add(pair)
list = RFC::Web::Link::Models::List.new.add(link)

Once you have a list, you can send the following messages including Data and Enumerable messages:

list.add line
list.clear
list.empty?
list.size
list.to_s
list.to_str

You’ll notice you can explicitly and implicitly cast your list to a string. This makes the following quite handy:

"link: #{list}"
# link: <https://demo.io>; title=Demo

Link

This model encapsulates a single HTTP link header. A link can be created multiple ways:

All At Once

link = RFC::Web::Link::Models::Link[
  uri: "https://demo.io",
  pairs: Set[
    RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
  ]
]

💡 Ensure you use a Set when adding your pairs.

Separately

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]
link = RFC::Web::Link::Models::Link[uri: "https://demo.io"].add(pair)

Once you have a link, you can then send the following messages (including Data messages):

link.empty?
link.include? pair
link.add pair
link.append :relation, "index"
link.append :title,
            "déjà vu",
            delimiter: "*=",
            encoding: "UTF-8",
            language: "en"
link.find_pair key: "title", value: "Demo"
link.find_pair key: "title", value: /dem/i
link.find_pair key: "title", delimiter: /\*=/, value: "Demo"
link.pair? key: "title"
link.pair? key: "title", value: "Demo"
list.to_s
list.to_str

You’ll notice you can explicitly and implicitly cast your link to a string. This makes the following quite handy:

"link: #{link}"
# link: <https://demo.io>; title=Demo"

Pair

This models encapsulates a single HTTP link header pair (i.e. key/value). A pair can be created as follows:

Basic

pair = RFC::Web::Link::Models::Pair[key: :title, value: "Demo"]

# #<data RFC::Web::Link::Models::Pair:0x00001e90
#   delimiter = "=",
#   encoding = nil,
#   key = "title",
#   language = nil,
#   value = "Demo"
# >

pair.encoded?  # false

Encoded

pair = RFC::Web::Link::Models::Pair[
  key: :title,
  delimiter: "*=",
  value: "Demo",
  encoding: "UTF-8",
  language: "en"
]

# #<data RFC::Web::Link::Models::Pair:0x00001ec0
#   delimiter = "*=",
#   encoding = "UTF-8",
#   key = "title",
#   language = "en",
#   value = "Demo"
# >

pair.encoded?  # true

The key can be either a symbol or a string but is always stored as a string, internally. When using = as your delimiter (default), #encoded? will be false but when using *= as your delimiter, #encoded? will be true.

As with List and Link, you have full access to all Data messages and can explicitly and implicitly cast to a string. Example:

"Pair: #{pair}"
# Pair: title=Demo

Error Handling

As per RFC 8288, this implementation is designed to safely ignore malformed web links. To illustrate, we’ll start with an initialized parser:

parser = RFC::Web::Link.new "https://demo.io"

The following examples show the result of parsing different malformed URIs:

With Nil Value

parser.call({"link" => nil})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

With Empty Value

parser.call({"link" => ""})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

With No Leading Less Than Sign For URI

parser.call({"link" => "/articles; rel=index"})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = []
# >

Without Attributes

parser.call({"link" => "</articles>"})

# #<data RFC::Web::Link::Models::List:0x00000880
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x000008b0
#       pairs = [],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

With Missing Attribute Value

parser.call({"link" => "</articles>; rel"})

# #<data RFC::Web::Link::Models::List:0x000008a0
#   links = [
#     #<data RFC::Web::Link::Models::Link:0x00000910
#       pairs = [
#         #<data RFC::Web::Link::Models::Pair:0x00000930
#           delimiter = nil,
#           encoding = nil,
#           key = "rel",
#           language = nil,
#           value = nil
#         >
#       ],
#       uri = "https://demo.io/articles"
#     >
#   ]
# >

Development

To contribute, run:

git clone https://github.com/bkuhlmann/rfc-web-link
cd rfc-web-link
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Developer Certificate of Origin

Versions

Community

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

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!

htmx View Transitions Talk

2026-07-24T16:13:09+00:00

Summary

Learn about the power of CSS View Transitions using only HTML and CSS with a tiny amount of JavaScript to tie everything together while Ruby is used to render all slides in real-time both via the web UI and on ePaper devices. You'll learn the technical details of how all this works while gaining new knowledge to apply to your own tech stack!

Details

Ratio: 16:9
Slides: 60

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!

Docker Debian Ruby Project

2026-06-14T23:06:10+00:00

Docker Debian Ruby

Provides a Ruby focused Debian Docker image with current tooling for development purposes. Great for local development and/or continuous integration builds using the most up-to-date tooling.

Table of Contents

Features
Requirements
Setup
Usage
Development
Tests
License
Security
Code of Conduct
Contributions
Developer Certificate of Origin
Versions
Community
Credits

Features

Installs jemalloc.
Installs Ruby with YJIT.
Updates RubyGems.

Requirements

Docker.

Setup

To set up the project, run:

git clone https://github.com/bkuhlmann/docker-debian-ruby.git
cd docker-debian-ruby
git checkout:0.3.0

Usage

All versions of this image can be found on Docker Hub. The image can be pulled as follows:

docker pull bkuhlmann/debian-ruby:latest  # <= Pull latest version.
docker pull bkuhlmann/debian-ruby:0.3.0   # <= Pull specific version.

You can also build on top of this image via your Dockerfile:

FROM bkuhlmann/debian-ruby:latest  # <= Latest version.
FROM bkuhlmann/debian-ruby:0.3.0   # <= Specific version.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/docker-debian-ruby.git
cd docker-debian-ruby

To build, run:

bin/build

To use the console, run:

bin/console

To deploy the latest version, run:

bin/deploy

To automatically calculate the next logical version and deploy it, run:

bin/deploy p

Versions are calculated and created via the Milestoner gem. Best practice is to deploy both the latest version and next version. Example:

bin/deploy
bin/deploy p

The above will ensure new images are created with the following tags:

latest: This is the most recent stable version which may or may not be ahead of the last version released.
<major>.<minor>.<patch>: This the next logical version as calculated and created by Milestoner.

Tests

To test, run:

bin/console
ruby --version

Credits

Built with Rubysmith.
Engineered by Brooke Kuhlmann.