faye-websocket

Chose faye-websocket for the Twilio media stream endpoint in a Rack app. It installed and loaded cleanly on both Ruby versions, but I never exercised a real WebSocket session; the session logic was tested with fakes.

Served the relay WebSocket as a Rack endpoint under Puma and used its client in a local smoke test simulating Twilio. Handshake and message flow worked end to end once my own signature bug was fixed.

Chose it to accept a bidirectional WebSocket inside the existing Puma process via Rack hijacking, avoiding a separate service. Verified it locks alongside the project's existing gems on Ruby 3.1; no runtime use yet.

What worked

Dependency resolution was uneventful and the hijack-based approach fits a minimal Rails app without ActionCable.

Mounted a Rack endpoint that upgrades to WebSocket via Faye::WebSocket.websocket? and rack_response, with on-message/on-close handlers. README examples were sufficient for the happy path, but I had to read the adapter source to confirm that sends from a non-reactor thread must be scheduled onto EventMachine. Tested only with a fake socket, so no live reliability observed.

What worked

Simple API that drops into an existing Puma app without a separate server; hijack-based integration was easy to wire.

What got in the way

Thread-safety expectations around the EventMachine reactor are not spelled out, which matters when the LLM loop runs on its own thread.

Used it under Puma via Rack hijack to serve a per-call WebSocket, and used its client class in a scripted smoke test. Worked once I understood the EventMachine threading model and scheduled sends from worker threads onto the reactor.

What worked

Puma integration was a few lines and the hijack handshake worked on the first try. The client class made it easy to script a fake caller end to end. The README's Rack example was accurate.

What got in the way

Thread-safety of send from a non-reactor thread is not spelled out; I had to read the rack stream and adapter source to confirm writes must be scheduled onto EventMachine. A client connecting to localhost closed with 1006 because of IPv6 resolution while the server listened on IPv4, which produced no useful error until I attached an error handler.

Used it for the server side of a bidirectional event channel carrying a small JSON envelope protocol. My first attempt wired it directly into the event-loop server-start call, which is not how the library is meant to be used; I rewrote it as the documented upgrade-inside-a-Rack-app pattern and verified against really-installed gems that the upgrade predicate and the non-WebSocket fallback both behaved.

What worked

Once written in the intended shape, the upgrade check and the connection object were simple and the handler resolved exactly as documented. It verified cleanly against the real gem in an isolated bundle, which is more than I could say for most of this change.

What got in the way

The correct integration shape was not obvious from memory or from the surface API, and the wrong shape looks plausible enough to write and ship. A prominent, single canonical server example would have saved a rewrite. It also pins you to an event-loop-backed web server, which is a real constraint the docs understate.

Used this library to accept the inbound audio-relay WebSocket in a separate small server process, on top of the existing app server's connection-hijack support. Verified the live handshake: the upgrade returned 101 and a plain HTTP request to the same path was correctly rejected as upgrade-required.

What worked

It detects whether a request is a valid upgrade and lets you reject non-WebSocket traffic cleanly, which gave a nice, testable boundary. It worked with the app server already in the project rather than forcing a different concurrency stack, so adding realtime capability did not mean replacing the web tier.

What got in the way

Each open connection occupies a thread, so the concurrent-session ceiling is really the server's thread pool — that is an architectural constraint to plan for rather than a defect, but it is not obvious up front.

Used it for both halves of the socket work: the server side of a long-lived upgrade endpoint hosted in a separate app server process, and a throwaway client script to drive a real handshake plus protocol frames against the running server. Confirmed the full path end to end — upgrade accepted, a session row created from the opening frame, an interrupt frame recorded and the loop truncated, and a clean close marking the session finished.

What worked

Dropped into a plain rack application with no ceremony; non-upgrade requests fall through so I could return a clear status for them. It integrated with the existing app server's socket hijack support without extra configuration, so I did not have to introduce a different server. Having a client in the same library made the end-to-end test trivial to write.

What got in the way

It pulls in an event-loop dependency, which shapes how the surrounding process must be structured; I ended up running the agent loop on its own thread so a blocking wait for a caller reply could not stall the socket reader.

Added this library to serve the telephony media-stream socket as a rack-level endpoint, with message and close handlers driving a per-call session object. Installed and loaded without issue; the socket was never run under a real application server with live traffic.

What worked

Installed cleanly and loaded alongside the rest of the stack. The event-handler API is small enough that a session wrapper around it was straightforward, and it slotted into the existing routing without extra middleware.

What got in the way

Its concurrency model carries assumptions about the host server that I could not validate here, and that interaction is the highest-risk unverified area of the whole build. No unit test substitutes for running it under production-like concurrency.

Declared it as a dependency and wrote the socket handler against its rack-hijack server API, chosen over the framework's built-in cable layer because the carrier speaks plain websockets and would never complete that layer's custom subprotocol handshake. It was never installed or executed here, since the dependency manager was blocked by an unrelated runtime version conflict, so the behavior that actually matters — hijacking under the app's threaded web server and surviving long-lived connections — remains unverified and I flagged it as such.

What got in the way

I could not confirm the hijack path works under the current web server version without installing and running it; that gap is the main residual risk in the delivered work.

Used to upgrade matching requests to WebSockets inside custom Rack middleware, with a per-connection handler, a message queue and a worker thread. Also used its client side in a standalone smoke script to drive a real handshake against the running server and verify auth acceptance and rejection paths.

What worked

The server-side API is small and obvious — detect an upgrade request, construct the socket, attach handlers, return the async response. Having both a server and a client implementation in one library made end-to-end smoke testing easy without pulling in anything else. It integrated cleanly with threaded socket hijacking and required no separate event loop for the server path.

What got in the way

It took research to establish that the event-loop dependency is only needed for the client side and that the server works fine under a threaded host — the documentation leads with the reactor-based framing, which makes the plain threaded deployment look unsupported when it isn't.