ensure と rescue を取り違えた話

I recently had the opportunity to contribute to the Ruby web framework Rage. Unlike Rails running on top of Puma, Rage runs on the Iodine server and processes work asynchronously through fibers internally. It recently gained support for Server-Sent Events (SSE), and while reading through that code I noticed something that bothered me a little. Chasing that small detail led me through a wrong first attempt, a kind correction from the maintainer, and eventually a fix that got merged in the right shape. My first fix passed both locally and in CI, yet the maintainer told me it was a breaking change. What he pointed out is exactly what I want to convey in this post: in an asynchronous world, choosing between ensure and rescue is not a matter of style but of correctness itself.

The file in question is lib/rage/sse/application.rb. The SSE Application class handles two kinds of streams.

The first is the Enumerator stream via start_formatted_stream, which pulls events one by one and writes them. This is synchronous: when the each-loop returns, the stream really is finished, so it already had an ensure block that closed the connection.

The second is the Proc / raw stream via start_raw_stream, which calls a user-supplied proc together with a ConnectionProxy. This one had no cleanup at all. If the proc raised an exception, the connection was never closed and would linger until Iodine hit its socket timeout. Within the same file, one path cleaned up with ensure while the other did nothing. That asymmetry was what first caught my eye.

The fix looked obvious. Just mirror start_formatted_stream and add an ensure block to start_raw_stream as well. The local tests passed and CI was green. Confident it was fine, I opened a pull request (#248) with commit 14bf349. Looking back, this is where I mistook “the tests pass” for “this is correct.”

The maintainer’s original comment:

Thank you for the contribution! Unfortunately, this commit is a breaking change as it makes a reasonable but incorrect assumption about the synchronous nature of raw SSE streams. It is a completely valid approach to run the stream on a separate fiber or thread. In such case, the proc that is passed to render sse: finishes executing almost immediately but long before the background fiber/thread has a chance to do the work and write to the connection. […] Adding the ensure block means the connection is closed before anything has been written to it. However, if we focus on closing the connection when the SSE stream RAISES, your idea makes sense and actually fixes the existing issue. We just need to ensure the connection is closed only on exception.

The phrase “reasonable but incorrect assumption” pinpointed my mistake exactly. I had implicitly assumed that raw streams were synchronous.

This is the heart of the post. Raw SSE streams are frequently written asynchronously. The user’s proc spawns a background fiber (for example via Fiber.schedule) and returns immediately. After that, the spawned fiber keeps writing events to the connection.

An ensure block runs the moment the proc returns — whether or not an exception was raised. So with ensure: the proc spawns the fiber and returns immediately, ensure fires and calls connection.close, and only then does the background fiber start running, by which point the connection is already closed. Adding ensure closes the connection before anything is written. This is not just about the error case; it breaks the normal, success path of every async stream. The Datastar SDK drives SSE in exactly this pattern.

By contrast, start_formatted_stream legitimately uses ensure, because the Enumerator path is synchronous: when its each-loop returns, the work truly is done, so closing there is correct. The same ensure keyword is right in one place and breaking in the other. The difference lay not in how the code looked, but in the execution model beneath it.

As the maintainer pointed out, what we actually wanted was to close the connection only when the stream raises. On a normal return we must do nothing, leaving the connection open so the background fiber can keep writing. That is a job for rescue, not ensure. The merged fix is commit 819f747 (shown above).

• rescue => e runs only when the proc raises. On a normal return (the async pattern where the fiber is still running) we never enter this branch, so the connection is left open for the background fiber.
• connection.close if connection.open? closes the connection, but the open? guard prevents a double close, in case the proc had already closed the connection before raising.
• raise e re-raises the original exception. We are only adding cleanup, not swallowing the error, so the original error still surfaces in the logs.

Believing the reasoning was correct was not enough, so I wanted to confirm it against a real asynchronous consumer. I pointed the Gemfile of the rage-rb/datastar-example project at the fix branch. The Datastar SDK drives SSE asynchronously, so it exercises exactly the pattern my ensure version would have broken and the rescue version should protect.

The Datastar SDK then streamed all 13 SSE events correctly (H, He, Hel, Hell, Hello, … , Hello, world!). The connection stayed open while background fibers wrote, and closed normally after completion. I reported this back in the PR. With the original ensure version, none of those 13 events would have arrived.

For tests, I added three cases in spec/sse/application_spec.rb using a small MockSSEConnection helper (with write / close / open?): (a) the proc raises → the connection is closed; (b) the proc returns without closing (the async pattern) → the connection stays open; (c) the proc closes the connection itself → no interference, no double close.

Case (b) matters most. Under the original ensure version, this is the very test that would have exposed the connection being closed when it must not be. The review came on March 27th, the revision and verification on March 28th, and on March 30th rsamoilov approved and merged it into rage-rb:master.

The biggest takeaway from this experience is a simple rule of judgment. In fiber-based or asynchronous Ruby, “the block returned” is not the same as “the work is done.”

• If the work is genuinely finished when the block exits (synchronous), use ensure for cleanup.
• If the resource may outlive the block (asynchronous) and you only want to clean up on failure, use rescue.

Picking between them is not a style question. Choosing ensure here means silently breaking every async consumer.

The same trap lurks anywhere Ruby touches fiber-based async: Falcon, the Async gem, Roda + Async, ActionCable and WebSocket lifecycles, any server driven by Iodine, libev, or io_uring. Wherever a resource’s lifetime stops matching the block’s scope, the same judgment is required.

Connection leaks do not crash production all at once. They slowly exhaust file descriptors until someone notices the server getting sluggish. That is exactly why I was lucky to have this caught in review early.

To be honest, the most interesting part of this story is where I was wrong. Because the tests passed and CI was green, I stopped questioning my own premise. But tests only protect the cases I imagined. The asynchronous use of raw streams, a usage I did not know about, simply did not appear in my tests.

Rather than just rejecting my change, rsamoilov acknowledged that the core idea, “close on exception,” was right, and then guided it into the correct shape. A good review teaches more than the corrected code does. In this case, what I gained was not a few lines of patch but a way of seeing asynchronous resource management, an understanding I could not have gotten from just reading the docs.

If anyone is hesitating to take their first step into open source out of fear that their contribution will be rejected, I would say this: as long as you are willing to verify your own fix properly, a mistake becomes an entry point for learning. The part where I was wrong turned out to be the most interesting part. Do not be afraid to be wrong, and send the PR.