I’m usually weary of long readmes with too much styling as that indicates to me a high likelihood that they were written by ai and the author might not have even read all of it. The use of generic ai images also gives a bad impression - for example, there’s an image captioned “The green lines? Those are your CPU cycles escaping.” without anything green pictured.
I’m not saying your gem is bad. It’s nice to se an attempt at a circuit breaker that is based on the state machines gem, I will certainly look into the actual code if I have a need for it in the future.
Just wanted to give you this bit of feedback about maybe cutting down on length and loosing the ai images in the readme as I think it might be a turnoff for others as well.
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.
I mean no offense, but your writing style gives the LLM vibe, this comment included. They all start with saying the user is right and thanking for their input, then wall of text, then a hook to incentivise further discussion. All well formatted and split into logical paragraphs. It is good and correct, but you may wish to not sound like chatbot
In fact, I even added an em dash shortcut to my Logitech POP keyboard. That’s dedication. See? — — — — —
I’m not just writing like this—I’ve industrialized it.
If it sounds like a chatbot, maybe it's because I have spent too much time training them and not enough time pretending to be a chaos monkey in HN threads.
Appreciate the feedback though.
Now excuse me while I reboot into Windows just to add and to my custom shortcuts.
I have still got one more slot—what do you think I should add?
Go wild. Bonus points if it makes someone uninstall the gem out of pure emotional confusion.
As someone else who appreciates em dashes—deploying them judiciously for many years, I too am plagued by people suddenly perceiving my natural writing style as suspect.
I'm sure I saw this gem posted a few days ago (maybe not on HN?) and at the time all the docs were in one mahoosive README.
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.
Reading this I expected the README to be unreadable, filled with images and emojis, but found them to be very detailed with lots of code examples (Which I often miss in Gems) and explanations which was obviously a lot of work to do. Thanks for that!
PS: Speaking of "bit of feedback" for the parent commenter, it's losing not loosing.
The post is about how webhook requests are usually signed and api responses are not.
For me it seems clear that the reason for this different approach is that api requests are already authenticated. Signing them would yield little additional security. Diminishing returns like the debate over long lived (manually refreshed) api keys versus short lived access tokens with long lived refresh tokens - or, annoyingly, single use refresh tokens that you have to keep track of along with the access token.
Webhooks are unauthenticated post requests that anyone could send if they know the receiving url, so they inherently need sender verification.
> Signing requests does give extra security points, but why do we collectively place higher security requirements on webhook requests than API requests?
TFA is exploring the juxtaposition of signed web-hook requests vs bearer token api requests, both of which provide authentication but one of which is arguably superior and in common enough use to question why it hasn't become common practice at large.
To flip the question: if there aren’t meaningful benefits to signing requests, why don’t web-hooks just use bearer token authentication?
Both are http requests from client to server. Servers are already authenticated through TLS. The difference is who takes the role of the client.
With API requests the customer takes the client role. The endpoint is the same, eg api.stripe.com. This means, an API key (shared secret) is the minimal config needed to avoid impersonation. You could sign with a private key too but it would also require configuration (uploading the public key to stripe) so there’s not much security gained.
With webhooks, the vendor is the client and needs to authenticate itself. But since it’s always the same vendor, no shared secret is needed. They can sign it with the same private key for all customers. You can bake the public key into client libraries and avoid the extra config. Thus, it’s reasonable to believe the use of public key cryptography is not because it’s more secure, but simply more convenient. Signing is kind of beautiful for these types of problems.
Signing alone creates a potential security issue (confused deputy? Not sure if it has a name): if Eve creates a stripe account and tells stripe that her webhook lives on alice.example.com, ie Alice’s server, stripe could send real verified webhook events to Alice, and if she doesn’t check which account it belongs to, she might provision resources (eg product purchases) if Eve is able to replicate the product ids etc that Alice uses.
Edit: now that I think of it, eve doesn’t even need to point stripe to Alice’s server. She can just store and replay the same signed messages from stripe and directly attack Alice’s server, since the HTTPS connections are not authenticated (only the contents are). To mitigate, the client library should contain some account id in the configuration, in order to correctly discard messages intended for someone else.
I suspected as much. It would have been too obvious of an attack vector for something so sensitive. Then obviously my argument falls apart, since it’s no longer saves any config.
That said, you can still benefit from pub keys by having good infra and key rotations to prevent some attacks like message replay after months. Putting such a requirement on customers is pretty doomed because of the workload, processes and infra required.
Because then the client would need to host token vending infrastructure just to accept a webhook request.
As designed, the webhook receiver only has to implement the one endpoint.
[edit: in addition, bearer tokens are not the only authentication system. By moving authentication onto the webhook holder, the caller now has to satisfy any authentication system and have implementations for all of them. Some authentication systems are manual and thereby introduce friction. By providing the authentication materials themselves, they reduce friction and reduce their implementation to having only one mechanism.]
Some do, but it either involves an additional secret specific for this purpose, or it burdens the client with controlling access and exposure of incoming request headers (in logs and middleware) since they would include the token that can actually make api calls to the vendor.
Nevertheless, your question would have yielded a better article.
> but why do we collectively place higher security requirements on webhook requests than API requests?
We really don’t, signing is just more convenient in the webhook scenario. And it’s also completely optional to check a signature, leading even to many implementations not doing so.
Well put. I assume this is because big players make things as easy as possible to consume. APIs are probably more widely used that web hooks, so made easier for consumers to work with.
Some do; Gitlab, Otka, and Pipedrive come to mind. I think this is more about the expectations set over the last decade. If you do things differently, there's a need to justify it, and it's just perceived as less secure, regardless of whether it's true or not (the pros and cons are well articulated in the article).
This post (2019) by David Bryant Copeland about npm security goes into some of the complications that arise when multiple versions of a dependency are allowed to be loaded simultaneously:
The subtitle “A reference manual for people who design and build software” seems at odds with the description:
> This book won’t teach you how to actually make software […] It’s a manual that explains how the things you use everyday actually work.
You don’t need to be technical to read this - there are a lot of pictures and diagrams to do the heavy lifting. You just need to be curious.
It's like there was a shift in goals after the author made the title. Maybe explaining the basics was so much fun, that the initial idea got lost... I also don't think knowing how a crt monitor works is instrumental for people who want to make software. The domain is cool, but it doesn't match the content. whatissoftware.com might be better.
when it is explained how pixel, gpu or llm work, I would at least expect some intro to Von-Neumann-Architecture.
It’s nice that the phone app is free and works without the device. I’m curious about how “Hardcore Mode (optional)” could work, which the page describes as “Locks apps for the entire focus session with no way to bypass it. The only way to unlock them is a full phone reset.”
I could not find this in the app, maybe it’s Android only, an upcoming feature, or requires the Busy Bar hardware device.
In NileRed’s video “Does cyanide actually smell like almonds?”[0] he purchases some bitter almonds to measure the amount of cyanide in them. He is also worried about the baseless health benefits claims.
I love that channel. Especially turning (I believe) nitrile gloves into hot sauce. Some of the chemistry he performs, I would never think of even existing. It's like people that say margarine is one molecule away from plastic, without understanding that all of chemistry works like that.
Naturally occuring polymers like https://en.wikipedia.org/wiki/Fatty_acid are indeed very similar to synthetic ones, in that they both contain long hydrocarbon chains of varying length.
I’m not saying your gem is bad. It’s nice to se an attempt at a circuit breaker that is based on the state machines gem, I will certainly look into the actual code if I have a need for it in the future.
Just wanted to give you this bit of feedback about maybe cutting down on length and loosing the ai images in the readme as I think it might be a turnoff for others as well.