Mustermann: one string matcher behind Sinatra, Hanami and Grape

A matching library that most Ruby routers depend on

Mustermann describes itself as your personal string matching expert, and the repository contains two projects, each installable as a separate gem. The first is the mustermann gem, and the README is explicit that this is probably what you are looking for. The second is mustermann-contrib, a gem with additional pattern types and extensions. The reason this library matters beyond its own README is adoption. Mustermann is typically used by other frameworks and libraries, primarily but not exclusively for handing HTTP requests, and the list includes Sinatra, Hanami, Grape, Padrino, which is built on Sinatra, Praxis, Webspicy, Alchemrest, the HTTP Fake test implementation, the OpenAPI parsers oas_parser and oas_parser_reborn, Pendragon for Rack routing, Wayferer for crawling and apiculture for REST APIs on Rack. So a Ruby developer who has ever written a route in one of those frameworks has used Mustermann, usually without knowing it, and that is the case this article is about.

Pattern types are the API, not an implementation detail

The design centres on the pattern type. The identity, regexp, rails and sinatra types are included in the mustermann gem, and every other type listed in the README belongs to the mustermann-contrib gem. Third-party gems supply further types, with mustermann-grape as the named example, which is the mechanism by which Grape's syntax exists at all. Each type comes with a dialect it is compatible with. The cake type uses a prefix parameter with a catch-all suffix and is compatible with CakePHP. The express type uses /:prefix+/:id(\d+) and matches Express and pillar.js. The flask type uses /<prefix>/<int:id> and matches Flask and Werkzeug. The pyramid type uses /{prefix:.*}/{id}. The rails type uses /:slug(.:ext) and is compatible with Ruby on Rails, Journey, HTTP Router, Hanami and Scalatra when configured. The simple type uses /:slug.:ext and matches Sinatra 1.x, Scalatra, Dancer, Finatra and Spark. One API, many dialects, and a declared compatibility list for each.

Not every type can expand templates

The table carries a notes column, and two of its entries define the boundary of the library. The regexp type is created when you pass a regular expression to Mustermann.new, and it does not support expanding or generating templates. The shell type, which uses a glob-like file pattern with a brace list of extensions and is compatible with bash and zsh, carries the same limitation. Everything else, in particular the sinatra, rails, express, flask and pyramid types, is template capable, which is what makes them usable for route generation and reverse routing rather than only for matching incoming paths. The identity type is the other end of the spectrum. It uses /image.png, it is compatible with any software using strings, and it performs exact string matching with no parameter parsing at all. So the library is not one thing. It contains a literal string comparator, a regular expression wrapper, a set of template languages, and a compatibility layer for other frameworks' route syntaxes, and a caller has to pick the right type for the job.

Using the git version through Bundler

Both gems are published on RubyGems, which is where the gem version badge points, and for the edge version from GitHub the README gives a Bundler snippet. Add the repository as a GitHub source and name the two gems inside the block:

github 'sinatra/mustermann' do
  gem 'mustermann'
  gem 'mustermann-contrib'
end

The block form matters because the repository contains both projects, and a plain source declaration would pull the whole repository without telling Bundler which of the two gems to install. If you only need the base gem, you can ask for that one alone and leave the contrib gem out, which is the smaller dependency set. The repository itself is a standard Ruby gem layout with a Gemfile and a Rakefile at the root, an .rspec file for the RSpec configuration, a .yardopts file for the documentation tool, a CHANGELOG.md, a CODE_OF_CONDUCT.md and a CONTRIBUTING.md. The two gem directories sit side by side as mustermann/ and mustermann-contrib/, each with its own README, and the remaining top level directories are bench/, bin/, docs/ and support/.

Who depends on it and what they use it for

The projects list is also a good map of how pattern matching is used in the wild. Sinatra is described as a DSL for quickly creating web applications with minimal effort, and Hanami as a flexible framework for maintainable Ruby apps. Grape is an opinionated framework for creating REST-like APIs in Ruby, and Praxis focuses on both the design and the implementation aspects of creating APIs. Webspicy is a technology agnostic specification and test framework that yields better coverage for less testing effort, and it is the clearest example of Mustermann used outside web routing. Alchemrest is a library for building integrations with third party APIs, HTTP Fake is an HTTP fake implementation for test suites, and the OpenAPI parsers use it to read API definitions. Pendragon provides an HTTP router and its toolkit for use in Rack, apiculture is a toolkit for building REST APIs on top of Rack by WeTransfer, and Wayferer is a web crawling framework based on ActiveJob. The common thread is a need to match a path against a pattern, whatever dialect that pattern is written in.

A hand written regexp is the alternative, and it is not equivalent

The obvious alternative is to skip the dependency and match paths with regular expressions yourself, which is what most small routers do. The difference in approach is not that the results differ, it is about where the complexity lives. With a hand written expression, every route is a separate little parser that you maintain, and the templates that a framework style route needs, turning /users/:id back into a URL, are extra work you write yourself. Mustermann centralises that. It also gives you dialects you would otherwise have to reimplement: a rails style pattern in a Sinatra application, an express style pattern in a Rack app, a flask style pattern with typed parameters. The counter-argument is dependency weight and abstraction. Once you adopt it you are inside its type system, and a type you pick badly will not do what you expected, for example a regexp pattern that quietly cannot generate templates. The other alternative is a different route compiler entirely, such as the Journey router that the rails type is designed to be compatible with, which is the right choice if you are already inside Rails.

Licence, versioning and where the work happens

Mustermann is MIT licensed, and the badge in the README points at a licence badge service, with the licence text in the LICENSE file at the repository root. The project is hosted under the sinatra organisation, which matches its role as shared infrastructure for the Ruby web stack rather than a product of its own. On versioning, the repository publishes no GitHub releases, so there is no tag list to consult and the CHANGELOG.md in the tree is the version history. The default branch is main and the last push to it was on 2026-10-10, so the library is being changed. That combination, an active branch with no release tags, means a production dependency should be pinned to a released gem version rather than tracked to the branch, and the bundled gems are the practical route to check what a given release contains. The bench/ directory at the root also tells you the project treats matching speed as something worth measuring, and the docs/ directory holds the documentation that the README only summarises.

Editorial conclusion

Mustermann suits anyone writing a router, a route matching library or a test harness in Ruby who wants the pattern dialects of several frameworks behind one API, and it is a sensible default for new Ruby routing work. It is the wrong dependency when you need only literal matching, since the identity type and plain regular expressions cover that case without the type system. Before adopting it, decide which pattern types you actually need, because the regexp and shell types come with the explicit limitation that they cannot expand or generate templates, and remember the repository publishes no GitHub releases, so the changelog in the tree is your version history.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. sinatra/mustermann on GitHub