
# When Your SDK Does Too Much (And Not Enough)

## What I Was Working On

We have a shared SDK gem that multiple apps use to talk to a third-party assessment API. The main app needed to start creating assessments directly (instead of routing through another service), so I needed to add write operations to the SDK client.

Sounds simple enough, right? Add some methods, ship it. But when I actually looked at the existing client, things got interesting.

## The Problem

The old client was doing two things at once — signing the API request (authentication) and sending it — all crammed into one method. There was no way to control what "action" (read vs. write) the request was signed with, because it was hardcoded. The HTTP layer was raw `Net::HTTP` with zero retry logic, so if the API rate-limited us (HTTP 429), we'd just... fail silently.

For read-only operations, this worked fine. Nobody noticed because reads are forgiving. But now that we needed writes, the lack of control over the signing action was a real problem — signing a write request as a read meant the API would reject it, and signing a read as a write could accidentally mutate data.

## How I Found It

I started by just trying to add the write methods. The first attempt was to bolt them onto the existing client, but I immediately hit a wall: the single `post()` method was signing everything with a hardcoded `'get'` action. There was no way to say "this is a write, sign it as `'set'`" without changing the method signature.

That led me down a rabbit hole of "wait, what else is wrong here?" and I found:
- No retry on rate limits (the API docs literally say "you will get 429'd, handle it")
- No structured error handling — errors were swallowed or raised as generic exceptions
- The HTTP transport and payload signing were tightly coupled — you couldn't test one without the other
- A scoring endpoint that explicitly requires a `'get'` action was being called with `'set'` after refactoring, which broke it with a cryptic 404

That last one was fun to debug. The API returned "Route not found" for a valid path, which made zero sense until I read the docs more carefully and found that the action parameter actually affects routing, not just auth.

## The Fix

I split the client into two clear responsibilities:

1. **`sign(data, action)`** — takes your payload and an explicit action (`'get'` or `'set'`), returns a signed request with security parameters. That's it. No HTTP, no side effects.

2. **`post(path, signed_data)`** — takes the path and the already-signed data, sends it via HTTP. Handles retry, rate limiting, error parsing.

For the HTTP layer, I swapped `Net::HTTP` for Faraday with middleware:
- Automatic retry on 429 with exponential backoff (2s, 4s, 8s, up to 3 retries)
- `raise_error` middleware so HTTP failures become proper exceptions
- JSON response parsing built in

The tricky part was backward compatibility. There were already a bunch of callers using the old pattern: `client.post(path, raw_unsigned_data)`. If I just shipped the new client, all those callers would break because they weren't signing first.

The solution: in `post()`, check if the incoming request already has a `security` key (meaning it's been signed). If not, auto-sign it with `'get'` — which matches what the old client was doing implicitly. Added a comment marking it for removal once all callers migrate.

```ruby
def post(path, request)
  request['consumer_key'] ||= @credentials[:consumer_key]
  # backward compat: auto-sign if caller hasn't signed yet
  request = sign(request, 'get') unless request.key?('security')
  conn.post(path, request)
end
```

This way, old code keeps working, and new code explicitly calls `sign()` first with the correct action.

## Results

| Aspect | Before | After |
|--------|--------|-------|
| Rate limit handling | None (silent failure) | Auto-retry 3x with backoff |
| Signing control | Hardcoded `'get'` | Explicit `'get'` or `'set'` per call |
| Read/write separation | Not possible | Caller chooses action |
| Error handling | Raw exceptions | Faraday errors + structured logging |
| Backward compatibility | N/A | Old callers work unchanged |

Tested both the new explicit-sign pattern and the old raw-data pattern against the live API via console — all methods (reads, writes, scoring, duplicating) passed.

## What I Learned

- **Separate signing from transport.** These are two different concerns. When they're coupled, you can't control either one properly. The caller should decide *what* action to sign with, and the client should handle *how* to send it.

- **Backward compatibility isn't optional for shared libraries.** If your gem is used by multiple apps, you can't just change the API and expect everyone to update simultaneously. Build a bridge, document it, plan for removal.

- **Read the API docs on actions, not just endpoints.** Some APIs use the "action" parameter for more than just auth scoping — it can affect routing, validation, and what the endpoint actually does. A 404 on a valid path might mean your *action* is wrong, not your URL.

- **Faraday middleware order matters.** `raise_error` before `json` means you get raw error bodies. `json` before `raise_error` means errors are parsed before being raised. Small difference, big impact on debugging. Match your test middleware stack to production or you'll chase phantom bugs.

- **Auto-sign fallbacks should match the old default.** When I first added the backward-compat auto-sign, I used `'set'` as the default action (because the new methods were writes). Broke every existing read caller. The old client implicitly used `'get'` — so the fallback had to match that.

## TL;DR

Refactored a shared API client to separate payload signing from HTTP transport, added Faraday with retry/rate-limiting, and built backward compatibility into the breaking change so existing callers keep working during migration.

---

*The scariest part of refactoring a shared library isn't the refactoring — it's all the callers you can't see.*


When Your SDK Does Too Much (And Not Enough)

# When Turbo Stream Replace Kills Your Search Input

## What I Was Working On

I was adding some summary statistics to a data table page — think averages displayed at the top of a list of records. The page already had a search bar and sort controls, and the table updated dynamically via Turbo Streams whenever you searched, sorted, or changed a filter.

The feature itself was straightforward: compute some averages on the backend, render them above the table. Sounds simple enough, right?

## The Problem

After shipping the first version, I noticed something maddening: every time you typed a character in the search bar, the cursor would jump back to the beginning. You'd type "Jo" looking for "John" and end up with "oJ" because the cursor reset after each keystroke.

The search was working — results were filtering correctly — but the typing experience was completely broken. Every keypress triggered a debounced form submission (Turbo Stream request), and when the response came back... the search input got nuked and replaced with a fresh one.

## How I Found It

The culprit was obvious once I looked at the Turbo Stream template:

```erb
<%= turbo_stream.replace "big_container" do %>
  
<% end %>
```

One big `turbo_stream.replace` was swapping out an entire container that held three things:
1. The summary metrics
2. The search form (with the text input)
3. The data table

When the response came back, the browser replaced the entire DOM subtree — including the `<input>` the user was actively typing in. New input, no cursor position, no selection state. Gone.

This was actually a consequence of a refactoring decision. Previously, the metrics and search controls lived in a separate header partial rendered by a different controller. To consolidate everything under one controller (so the data didn't need to be loaded in two places), I moved the search form and metrics inside the same container as the table. Good for architecture, bad for the DOM.

## The Fix

The fix was to **stop replacing everything in one big chunk** and instead target only the parts that actually change:

1. **Extract the table** into its own partial with its own DOM id
2. **Wrap the metrics** in a stable container div with its own DOM id
3. **Leave the search form in between** — not targeted by any Turbo Stream action

The Turbo Stream response went from this:

```erb
<%= turbo_stream.replace "big_container" do %>
  
<% end %>
```

To this:

```erb
<%= turbo_stream.update "metrics_container" do %>
  
<% end %>

<%= turbo_stream.replace "data_table" do %>
  
<% end %>
```

The search form sits in the DOM between `metrics_container` and `data_table`, untouched by either Turbo Stream action. Type away — the cursor stays put.

I also used `turbo_stream.update` (not `replace`) for the metrics container. The difference matters: `replace` swaps the entire element including its attributes, while `update` only changes the innerHTML. Since the metrics container had Stimulus `data-*` target attributes on it, using `replace` would have stripped those attributes and broken the JavaScript behavior. `update` preserves the outer element.

## Results

| Before | After |
|--------|-------|
| Cursor resets on every keystroke | Cursor stays in place |
| One `replace` for entire container | Two targeted stream actions |
| Search form re-rendered on every update | Search form never touched |

The initial HTML page load still renders everything together (metrics + form + table) from one controller action. Only the Turbo Stream response is granular — updating just the pieces that change.

## What I Learned

- **Turbo Stream `replace` replaces the entire element** — including any form inputs the user is interacting with. If your user is typing in something inside the replace target, their input state is gone.

- **Design your DOM ids around what changes independently.** If metrics update but the search form doesn't, they need separate containers. Don't group unrelated UI into one replaceable chunk just because they're visually adjacent.

- **`update` vs `replace` matters for Stimulus.** `replace` swaps the whole element, so any `data-*` attributes (including Stimulus targets) disappear. `update` only changes innerHTML and preserves the outer element's attributes.

- **Consolidating controllers doesn't mean consolidating DOM targets.** It's fine to have one controller serve all the data, but the Turbo Stream response should be surgical — update only what changed.

- **Extract partials along replacement boundaries.** If you're going to `turbo_stream.replace "some_id"`, there should be a partial that renders exactly that `some_id` element. This makes the initial render and the stream update use the same partial, keeping them in sync.

## TL;DR

If your search input loses cursor position during Turbo Stream updates, you're probably replacing a container that includes the input. Split your Turbo Stream targets so the search form is never inside a `replace` boundary — update the metrics and table separately, leave the form alone.

---

*The architectural instinct to consolidate is usually right. But the DOM doesn't care about your architecture — it cares about which nodes get swapped.*

When Turbo Stream Replace Kills Your Search Input


# The Unbounded Query That Took Down an Endpoint

## What I Was Working On

We have a feature where users can upload photos to their profile. There's a "See All" button that takes you to a page listing all the photos for that profile. Simple enough — click a link, see your photos.

Except the page was crashing in production with 504 gateway timeouts.

## The Problem

I pulled up the trace in our APM tool and saw the endpoint was taking over 30 seconds — way past the gateway timeout. The response never even made it back to the user.

When I looked at the controller code, I found this gem:

```ruby
def index
  @items = Item.all
end
```

That's it. No scoping. No filtering. Every single item in the entire database, loaded into memory, on every request. The table had thousands of rows across all accounts, and the view was rendering each one with its associated file attachments — triggering an avalanche of N+1 queries.

The local dev logs told the story clearly:

```
Number of queries: 228
  72 times ran query called "Attachment Load"
  71 times ran query called "ReadableItem Exists?"
  60 times ran query called "Blob Load"
Completed 200 OK in 3109ms
```

228 queries for a page that should show maybe 3-5 photos. Classic.

## How I Found It

The APM trace pointed directly at the endpoint — it showed a 504 timeout with the resource path clearly in the URL. From there, I checked the controller and immediately spotted `Item.all`. The funny thing is, the "See All" link that navigates to this page *already passes* a `profile_id` parameter in the URL. The controller just... never used it.

So the data was being sent, but nobody was listening.

## The Fix

The fix was straightforward — actually use the parameter that's already being passed:

```ruby
def index
  @items = if params[:profile_id].present?
               @profile = Profile.find(params[:profile_id])
               Item.where(folder: @profile.folders)
                   .includes(:folder, file_attachment: :blob)
                   .order(position: :asc)
             else
               Item.none
             end
end
```

Three key changes:
1. **Scope the query** — only load items belonging to the requested profile's folders
2. **Eager load associations** — `.includes(:folder, file_attachment: :blob)` eliminates the N+1 queries for attachments and blobs
3. **Safe default** — return nothing when no profile is specified, instead of everything

But fixing the controller surfaced two more issues I didn't expect:

**Orphaned file attachments:** Some items had attachment records pointing to blobs that no longer existed. The old code assumed every non-PDF file had a valid blob and tried to generate a thumbnail, which blew up with `Nil location provided. Can't build URI.` I added a guard to check both `file.attached?` AND `file.blob.present?` before rendering.

**Turbo Frame mismatch:** The "See All" link lived inside a Turbo Frame on the profile page. When clicked, Turbo intercepted the request and expected the response to contain a matching frame — but the items index page didn't have one. The fix was adding `data-turbo-frame="_top"` to tell Turbo to do a full page navigation instead of trying to swap frame content.

## Results

| Metric | Before | After |
|--------|--------|-------|
| Total queries | 228 | 30 |
| N+1 attachment loads | 72 | 2 |
| N+1 blob loads | 60 | 0 |
| ActiveRecord time | 240ms | 167ms |
| Total response time | 3,109ms | 2,296ms |
| Production result | 504 timeout | Fast load |

And remember — this was on a small local dataset. In production with thousands of items, the before case was exceeding 30 seconds.

## What I Learned

- **Always check if an "all" query is actually what you want.** If a page is designed to show a subset of data, make sure the query reflects that. `Model.all` in a controller should be a red flag.
- **Parameters being passed doesn't mean they're being used.** The scoping parameter was right there in the URL the whole time. Someone built the link correctly but never updated the controller to use it.
- **Fixing one thing often surfaces others.** The scoping fix was clean, but testing it revealed orphaned data and a Turbo Frame issue. Always manually test the full flow after a fix.
- **Eager loading and scoping are a package deal.** Scoping gets you fewer rows. Eager loading gets you fewer queries per row. You usually want both.
- **Turbo Frames are invisible until they break.** If a link inside a Turbo Frame navigates to a page that doesn't have the matching frame, Turbo silently discards the response. The `_top` directive is the escape hatch.

## TL;DR

An endpoint was loading every row in a table because the controller used `Model.all` instead of scoping by the profile parameter that was already being passed in the URL. Fixed by scoping the query, adding eager loading, and handling two secondary issues (orphaned file attachments and a Turbo Frame mismatch). Went from 228 queries and production timeouts to 30 queries and fast page loads.

---

*Sometimes the fix is just... using the parameter that's already there.*


Sam Lee.

I create things for the web.

Latest Posts

When Your SDK Does Too Much (And Not Enough)

When Turbo Stream Replace Kills Your Search Input

The Unbounded Query That Took Down an Endpoint