C.W.K.
Stream
More →
Lesson 04 of 05 · published

When the Platform Says No

~14 min · wss-broken, hybrid-transport, pivot, war-story, long-polling

Level 0Tool Renter
0 XP0/33 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"The cleanest design in the world loses to a four-year-old platform bug. When the platform says no, you don't argue — you find the door that's actually open."

The Plan That Should Have Worked

The clean design was push everywhere: a secure WebSocket from the plugin to the backend, a secure WebSocket from the workspace to the backend, real-time bidirectional messaging across the board. WebSockets are the right tool for live, pushy, low-latency communication, and the architecture was elegant. Then the plugin's outbound secure WebSocket simply didn't connect — on the target operating system, it failed silently, with no server-side connection attempt and no useful error.

The Diagnosis: It's Not You, It's the Platform

A spike isolated the cause: the plugin sandbox on that OS rejects outbound secure WebSocket connections entirely, at a layer below the application's control. It wasn't a bug in the code, a wrong flag, or a missing permission — it was a long-standing, still-open platform-level defect, documented in a vendor issue that had been open for years. No amount of clever client code would fix it, because the failure was happening below where any client code could reach.

Spend the spike to locate the failure's layer before you spend days fixing the wrong layer. A failure in your code and a failure in the platform look similar from your seat. A focused experiment that isolates where the failure lives — your code, a config, or the platform itself — is the highest-leverage debugging you can do. Fixing the wrong layer is infinite; knowing the layer ends the search.

The Door That Was Open

The same spike confirmed the way through: while the plugin's secure WebSocket was blocked, the plugin's HTTPS requests worked perfectly normally. So the bridge between plugin and backend moved off WebSocket and onto HTTPS request/response. The plugin POSTs its captures and state to the backend; for backend-to-plugin messages, the plugin holds open a long-poll request that the backend answers the instant it has a command. That preserves push-like delivery over plain request/response plumbing.

Long-polling buys push semantics over request/response plumbing. When you can't hold a real push channel but you can make requests, a held-open request the server answers on-event delivers near-real-time messages without a persistent socket. It's not as clean as a true push channel, but it gets you push behavior through the one transport the platform actually permits.

Hybrid, Not Uniform

The result is deliberately asymmetric: the plugin-to-backend link is HTTPS (because that's what works there), while the workspace-to-backend link stays a secure WebSocket (because that works fine there). Two links, two transports, each chosen for its actual environment rather than forced into one uniform answer. The temptation to make everything the same transport for tidiness is exactly the wrong instinct when the environments genuinely differ.

Uniformity for its own sake fails when the environments aren't uniform. Forcing one transport everywhere is satisfying on a diagram and wrong in reality when one endpoint lives in a restrictive sandbox and another doesn't. Let each boundary use the transport its environment actually supports. A hybrid that matches reality beats a uniform design that fights it.

Leave the Door Marked for the Future

One last discipline: the workaround is documented as a workaround, tied to the specific platform bug, with a note not to reintroduce the blocked transport without re-running the spike. The bug might be fixed in a future platform release — and when it is, you want to know exactly why the hybrid exists and how to test whether you can simplify back. A workaround with no memory of why it exists becomes permanent cruft nobody dares touch.

I wanted to fight the platform. I was sure it was my code — wrong cert, wrong flag, something I'd missed — and I kept poking at my own side. Dad pushed me to run the isolating spike instead of guessing, and it pointed straight at the platform, not me. The humbling part was how long I'd have kept debugging code that was already correct. And the grown-up part was accepting the hybrid: not the design I wanted, but the design that actually runs on the platform I actually have. Elegance that doesn't connect is just a diagram.

Code

Intended vs spike finding vs shipped·text
INTENDED (uniform push) -- failed on the target OS:
  plugin    --[secure WebSocket]-->  backend     (BLOCKED: sandbox rejects it)
  workspace --[secure WebSocket]-->  backend     (works)

SPIKE FINDING:
  plugin secure WebSocket  -> silently rejected below app control
                              (years-old, still-open platform defect)
  plugin HTTPS fetch       -> works perfectly normally

SHIPPED (hybrid, matches reality):
  plugin    --[HTTPS POST]----------->  backend   (captures, state)
  plugin    <--[HTTPS long-poll]------  backend   (commands; held-open
                                                   request, answered on-event
                                                   -> push semantics)
  workspace <--[secure WebSocket]---->  backend   (full bidirectional push)

Each link uses the transport its environment actually permits.
Documented as a workaround tied to the platform bug -- revisit if it's fixed.

External links

Exercise

Recall a time something didn't work and you assumed it was your code. How long did you debug before checking whether the platform/library/environment was the cause? Design the spike you wish you'd run first: the smallest experiment that would have isolated the failing layer. Then look up whether the issue had a known vendor bug.
Hint
The ideal isolating spike changes exactly one variable: same operation, minimal context (does it fail in a bare 10-line repro?), or adjacent operation (does the sibling call that should work, work?). The answer points at the layer without you having to fix anything first.

Progress

Progress is local-only — sign in to sync across devices.
← PreviousCapture Without MutatingNext →The Window That Wouldn't Come Forward
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.