I'd suggest to drop the DSL, at the end of the day, a good old class with a constructor stored in a constant is much more more transparent:

    class PaymentService
      STRIPE_CIRCUIT = BreakerMachines::Circuit.new(
        threshold: { failures: 3, within: 1.minute },
        reset_after: 30.seconds,
        fallback: ->{ { error: "Payment queued for later" } }
      )

      def charge(amount)
        STRIPE_CIRCUIT.wrap do
          Stripe::Charge.create(amount: amount)
        end
      end
    end

You are correct to point out the mismatch on the image caption, i generated a few and copied the wrong one. That one's on me, i will update it later.

And while AI might correct a typo or help rephrase a sentence here or there (I’m not a native English speaker), everything in that README—tone, structure, content, rants, and lore—is 100% me. It's my style. Love it or leave it.

As for scaring people off ? That’s not a bug, that’s a feature. This is an open source circuit breaker, not a SaaS onboarding funnel. If someone decides not to use a well-tested library because the README isn’t sterile enough for their corporate taste, that is their loss. I'm not here trying to win two potential enterprise clients who expect a PDF pitch deck and a hug.

The circuit breaker pattern itself isn’t new, I didn't invent it, it has even its own wikipedia page. But the Ruby ecosystem? Still treating it like a nice to have.

Existing circuit breaker gems like Circuitbox, Semian, etc., are stuck in the past. They rely on patterns and syntax from the Ruby 2.6 era, and integrating them into a modern codebase often means a painful refactor or bending your architecture backwards. BreakerMachines is built for 2025, fully async, fiber-safe, and designed to work with modern Ruby without dragging a legacy ball and chain. It's don't even support version of ruby that is 1 version behind. Upgrade then use.

If someone is going to get frustrated by a long README or AI-generated images, they’re welcome to go pay someone to write them a handcrafted if/else block and call it resilience.

The code is clean. The tests are good. And if just that MD file makes them walk away from that—again, their loss. They don't even read it.

I maintain a ton of gems. And I’ll be honest: my enthusiasm for open source has been repeatedly drained by the "please make this more corporate-friendly" crowd. Not talking about you specifically—but there’s a whole wave of people who want everything politically polished and personality-free. That’s not why Ruby was created.

Ruby was made for joy. And this gem? It reflects that.

Cheers for actually reading and for giving honest feedback. You’re rare for that. Just don’t expect me to dress up like a SaaS salesperson anytime soon.

PS: Speaking of "bit of feedback" for the parent commenter, it's losing not loosing.

I think it's a massive improvement that it's been broken down into chapters in a docs folder. I can take or leave the writing style but do miss the old whimsy of _why and his poignant guide to ruby. The examples are great and quite thorough.

BreakerMachines focuses specifically on failure protection rather than rate limiting. Circuit breakers and token buckets solve different problems:

- Circuit breakers: Reactive failure protection (stop calling broken services)

- Token buckets: Proactive rate control (smooth request throttling)

They're complementary patterns. I actually have a rate limiter gem with token buckets, sliding windows, and distributed rate limiting, but I will open source it when my ship lands on a planet or a moon. Still navigating hyperspace.

Thanks for the feedback