websocket-driver

I read the library README and added the gem so the app could accept the relay WebSocket on a hijacked connection, reading frames on a side thread instead of adding an event-loop framework. The install succeeded. I did not observe a live socket session.

What worked

The README was enough to build a driver on hijacked IO and run the relay message loop without pulling in an event machine. The gem installed cleanly through the existing Ruby dependency workflow.

What got in the way

The README did not settle what the app should return after a hijack so the server does not also write a response. That had to be inferred from the application server. No end-to-end socket run was observed.

I used websocket-driver 0.8.2, already present via the realtime stack, as a Ruby websocket client against the local app server. The client API can set Cookie and Origin before the handshake, but the socket object has to supply its own URL method, which I only learned by reading the gem. A threaded reader received the welcome frame and then missed the subscription confirmation even though the server had accepted it. I could not tell a library race from a bug in the reader, so I switched to a single-threaded read loop. Delivery checks passed only after that rewrite.

What worked

The handshake and welcome frame succeeded when Cookie and Origin were set on the driver before start, which matched the session-based connection.

What got in the way

Frames after the welcome were not visible to the threaded reader, with no error from the driver. The client interface assumes a URL method that a plain socket does not provide, and that requirement was only in the source.

Used the already-present gem in a throwaway Ruby script to open real WebSocket connections as three users, subscribe to channels, and observe confirm/reject frames and live broadcasts. Gave the definitive answer curl could not.

What worked

Low-level enough to attach a session cookie to the handshake and read every frame, including pings, without extra dependencies.

Used the Rack driver to complete the handshake over a hijacked IO, parse incoming frames and send text/close frames, and used the client driver in tests to drive the server through a socket pair. Framing and close handling were correct in both unit tests and the Puma smoke test.

What worked

Pure framing with no IO assumptions fit the hijack model perfectly, and it is the same library ActionCable relies on. The client driver made realistic protocol tests possible without a browser.

What got in the way

Guidance on constructing the Rack env for the server driver and on which IO errors to expect on close (EPIPE when the peer has gone) had to be pieced together from source; an initial test fed raw handshake bytes to the frame parser and got a cryptic reserved-bits error.

Used it on both sides of the audio path: server-side to accept an upgraded media-stream connection inside a Rack app, and client-side over a TLS socket to talk to a streaming transcription service. Verified that a non-upgrade request is correctly rejected so the app falls through to a normal response; no live socket session was exercised.

What worked

It is protocol-only and transport-agnostic, which is exactly right for embedding in an existing Rack process and for driving a raw TLS socket. Detecting whether a request is an upgrade attempt is a single clean call. Being already present transitively meant no new heavyweight dependency.

What got in the way

Using it as a client requires hand-writing a small socket adapter and your own read pump, plus wiring custom handshake headers and query parameters yourself. The low-level design is defensible but the documentation assumes you already know that shape, so getting from zero to a working client is more guesswork than it should be.