DEV Community: Anton Kopylov

dataforseo-ruby: A Client That Respects the Bill

Anton Kopylov — Wed, 28 Oct 2026 10:19:00 +0000

Two of my apps call DataForSEO: ExtensionDash for keyword volumes and Google positions, and the workspace I run my own SEO from. Each had grown its own copy of the HTTP code, and the copies had started to disagree about what an error looks like. So I pulled them out into a gem, dataforseo-ruby.

gem "dataforseo-ruby"

client = DataForSeo::Client.new(login: ENV["DATAFORSEO_LOGIN"], password: ENV["DATAFORSEO_PASSWORD"])

response = client.google_ads_search_volume(keywords: ["reverse image search"], language_code: "en")
response.items  # => [{"keyword" => "reverse image search", "search_volume" => 1500000, ...}]
response.cost   # => 0.09

It has no runtime dependencies: net/http, json and zlib from the standard library, Ruby 3.4 or newer. Most of it is about one fact: every request costs money, including the ones that fail. That fact explains most of the decisions below.

A 200 is not a success

DataForSEO answers almost everything with HTTP 200 and puts the real outcome in a status_code inside the body: once for the request, then once for each task in it. A client that only checks the HTTP status will hand you an empty result as if it were an answer.

So every envelope is checked, top level and per task, and any failure becomes a DataForSeo::Error: AuthenticationError, PaymentRequired, RateLimitError, TransientError, or a plain ApiError carrying the code, message, path and task id. Timeouts, TLS failures and unparseable bodies become ConnectionError. If you send three tasks and get two back, that raises too. A missing task is not an empty one.

Save what you paid for

The bulk endpoints take up to a thousand inputs per request, so the client slices your list and sends it one slice at a time. Pass a block and you get each slice's response before the next request goes out:

client.bulk_spam_score(targets: domains) do |slice|
  SpamScore.upsert_all(slice.items)   # already paid for; keep it even if the next slice fails
end

Each response carries requested, the inputs sent in that request. That is how a caller tells "the API left this target out" from "we never got to asking", which are opposite facts and look the same in an empty result.

No retries, on purpose

The client does not retry and does not pace. That sounds lazy, but the reason is that a timeout after the API accepted a request can still be charged, and retrying pays again. Whether a second attempt is worth the money depends on the caller, so the error is the caller's to handle.

The queue endpoints follow the same rule. Google organic tasks are billed when they are accepted, so google_organic_task_post returns rejected tasks in tasks[] instead of raising. Raising there would throw away the ids of the tasks you have already paid for.

The rest

client.post(path, tasks) reaches any other Live endpoint, with the same envelope checks.
DataForSeo::Testing::FakeTransport queues bodies, or exceptions, for your own tests and records every call.
The README lists the surprises I paid to learn. Google Ads Live allows 12 requests a minute. A keyword over 80 characters or 10 words is rejected. One malformed domain voids a whole bulk_spam_score request, for zero items and zero cost.

It is unofficial, MIT licensed, and on RubyGems. It covers the endpoints I use. If you need another one typed, open an issue or a pull request on GitHub.

Decibel Meter: A Sound Level Meter in the Browser

Anton Kopylov — Mon, 26 Oct 2026 08:42:31 +0000

A lot of people type "decibel meter" into the Chrome Web Store, and the most installed result is rated three stars. That was the whole brief. Decibel Meter is my answer: press Start, allow the microphone once, and see how loud the room is in dB(A), with min, max, the average since you began, a 60-second chart and the current level on the toolbar badge.

A PRO switch adds what a handheld meter has: Fast and Slow response, flat dB(Z) next to dB(A), calibration against a reference device, a noise alert and a CSV log of the session. The alert is what turns it into a classroom noise monitor. It watches the average over a window you pick, from five seconds to five minutes, so one slammed door does not set it off.

Three things that are easy to get wrong

Check the level now and then, and you miss sound. The obvious way to build a meter is to read the microphone level each time the screen redraws. Redraws do not come at a steady pace, so some sound gets counted twice and some not at all. And when the window is in the background, the browser stops redrawing it, which is exactly when a noise monitor is supposed to be working. Decibel Meter instead measures every bit of sound as it comes in from the microphone, in the part of the browser that handles audio and keeps running in the background. Every 50 ms it hands the page a total, and the page only draws it.

An average of decibels is not an average. Ten minutes at 50 dB and ten at 80 dB do not average to 65. Decibels are a log scale, so the average has to be taken over energy and converted back, and the honest answer is about 77: the loud half dominates, as it does for your ears. That is Leq, and it is what the meter shows as the average.

Your microphone is not flat. It hears bass and treble differently from people, which is what A-weighting corrects for. The meter applies the standard A-weighting curve, and it stays within 0.3 dB of it up to 2 kHz. What no filter fixes is that a laptop microphone has no absolute scale. The meter adds a fixed offset that puts a quiet room at 30–40 dB, and PRO lets you calibrate against a real meter if you have one. It is a good guide to how loud a room is. It is not a certified instrument, and it does not pretend to be one.

Why it opens a window

The toolbar popup is where an extension's UI normally lives, and it does not work here: a popup cannot show the microphone permission prompt, and it closes the moment it loses focus, which would stop the measurement. So the icon opens the meter in a small window of its own and focuses it on the next click instead of opening a second one. It keeps measuring while you work in other tabs.

Try it

Decibel Meter is free in the Chrome Web Store, with no account. If your reading disagrees with a real meter, or the alert fires when it should not, I would like to hear about it at anton@kopylov.net.

ExtensionDash: tracking a browser extension from your agent

Anton Kopylov — Wed, 02 Sep 2026 17:03:41 +0000

After shipping two browser extensions this year — Reverse Image Search Anywhere and Stackpeek — I still could not answer the simplest question about a listing: is it working?

Both stores tell you how many people installed the thing. Neither tells you the number that decides whether anyone installs it at all: where you appear when someone searches the words they would actually type. The Chrome Web Store developer dashboard has no notion of search position. Firefox's is no better. So the honest answer to "did last week's title change help?" was to open an incognito window, type the keyword, and count down the results with my finger. In three languages.

So I built ExtensionDash. It scrapes both stores nightly and records installs, ratings, category rank, keyword positions, competitors and listing copy — and keeps the history.

The decision that mattered

Not the scraper. It was making the agent a first-class reader rather than an export button.

POST /mcp speaks the Model Context Protocol over stateless HTTP, authenticated with a per-user token. Fifteen tools; eleven read, and the four that write cannot delete recorded history. Everything the dashboard renders, an agent can read.

That part mostly just works. What took actual thought is that an agent needs absence to be legible, and a web page does not.

A human seeing a blank cell reads it from context: still loading, new row, or genuinely nothing. An agent gets a JSON document with a null in it, and a null is a wonderfully confident thing to summarize as a zero. "Your extension does not rank for this keyword" and "nobody has looked yet" are opposite facts, and a tool that returns the same shape for both will get one narrated as the other to a user who believes it.

So three states stay distinct: never scanned, scanned and found, scanned but absent. add_keyword reports whether a fetch was actually enqueued and names the tools to poll. list_scrape_runs surfaces a failed fetch as a failure rather than as a position that silently never arrives.

Same instinct behind the field I am most attached to: every position travels with the depth it was scanned to. #1 of 9 and #1 of 50 are different results. Reporting "you rank #12" while omitting that the scan stopped at 50 is how a tool lies by arithmetic rather than by mistake.

History you did not pay for

Every nightly keyword search already scans fifty results, so all fifty are recorded. add_competitor promotes one — which earns it a listing fetch, and therefore a description, installs and a rating — but the ranks are already there. A competitor you add today arrives with rank history going back to the day you started tracking the keyword. You get to ask "when did they pass me?" about someone you had not thought about until this morning.

Stack is unremarkable on purpose: Rails 8, Postgres, Solid Queue with browser work on its own single-threaded queue, Nokogiri and Ferrum for Chrome, the public AMO API for Firefox. Kamal from a laptop.

The beta

Open, free, no card, at extensiondash.com. Limits are three extensions per account and fifteen keywords per extension, because a keyword is a nightly browser session in perpetuity — not because there is a paid tier behind them.

What I would most like people to try is the part I cannot evaluate alone: connect it to your agent and ask it something real.

claude mcp add --transport http extensiondash https://extensiondash.com/mcp \
  --header "Authorization: Bearer <your token>"

The token and a ready-to-paste command are on the Help page. Then ask your agent why an extension slipped last week, or what a competitor changed — and tell me where it stalls, what it guesses at, and what it reaches for that is not there. I designed those fifteen tools by reasoning about what an agent would need. Reasoning about it is not the same as watching it happen.

Anything else you find, I want too: anton@kopylov.net.

Reverse image search breaks on Instagram. Here's the fallback ladder that fixes it.

Anton Kopylov — Tue, 28 Jul 2026 18:10:04 +0000

Every one-click reverse image search extension works the same way, and it is not the way you'd guess. It doesn't upload anything. It builds a URL:

const ENGINES = {
  google: (u: string) => `https://lens.google.com/uploadbyurl?url=${encodeURIComponent(u)}`,
  bing:   (u: string) => `https://www.bing.com/images/searchbyimage?cbir=sbi&imgurl=${encodeURIComponent(u)}`,
  yandex: (u: string) => `https://yandex.com/images/search?rpt=imageview&url=${encodeURIComponent(u)}`,
  tineye: (u: string) => `https://tineye.com/search?url=${encodeURIComponent(u)}`,
};

Right-click an image, read info.srcUrl, open four tabs. The engine fetches the image itself, server-side. It's twenty lines and it's genuinely elegant — the extension never touches image bytes, never needs a backend, never sees your data.

It also fails on a large fraction of the web, and it fails silently: you get a results page that says "no matches," which is indistinguishable from a real no-match.

I hit this building Reverse Image Search Anywhere, and digging out took four distinct fallback tiers. This is what's under each one.

Problem zero: you don't even get a URL

Before the redirect can fail, something more basic breaks.

chrome.contextMenus only populates info.srcUrl when the right-click actually landed on an <img> element. Instagram, Pinterest, and Facebook all lay a transparent element over each photo — an interaction shield for their own gesture handling. Your right-click hits the shield. Chrome reports a page context with no image at all, and your extension's image menu item doesn't even appear.

The fix is to stop asking the browser and look yourself. A content script listens for contextmenu in the capture phase (so the page can't stopPropagation() you out of it) and walks the element stack under the cursor:

document.addEventListener('contextmenu', (e) => {
  lastRightClickSrc = pickImageUrl(document.elementsFromPoint(e.clientX, e.clientY));
}, true); // ← capture

export function pickImageUrl(elements: Element[]): string | null {
  for (const el of elements) {
    if (el.tagName === 'IMG') {
      const img = el as HTMLImageElement;
      // currentSrc, not src — with srcset, `src` is the fallback the browser
      // may never have loaded.
      const src = img.currentSrc || img.src;
      if (src) return src;
    }
  }
  for (const el of elements) {
    const url = backgroundImageUrl(el); // computed style, first url(...)
    if (url) return url;
  }
  return null;
}

document.elementsFromPoint() returns the whole stack, topmost first, so the shield is element 0 and the real <img> is usually element 1 or 2. Two details earn their keep: currentSrc over src (with srcset, src is a fallback the browser may never have fetched), and the CSS background-image pass, which catches the surprising number of sites that render photos as div backgrounds.

Now the background worker can ask the content script "what was under the cursor?" and get an answer where Chrome had none.

The URL you got may still be useless

Having a URL isn't the same as having one an engine can fetch. It's useless when it's:

blob: or data: — page-scoped. blob:https://example.com/abc-123 is meaningless outside that document.
hotlink-protected — the CDN checks Referer and serves a 403 to Google's fetcher.
cookie-gated — a signed URL on an authenticated CDN. Google isn't logged in.
drawn on a <canvas> — there is no URL. There was never a URL.

So for those cases you need the actual bytes. Which is where it gets interesting, because no single mechanism can grab them all, and the reasons are unrelated to each other.

Four tiers, each covering the one above it

Tier	Mechanism	Reaches	Blind to
0	It's already a `data:` URL	inline images	everything else
1	`fetch` in the background worker	most CDNs, hotlink-protected	`blob:`, cookie-gated
2	`fetch` in the content script	`blob:`, cookie-gated, private	cross-origin without CORS
3	Rasterize the `<img>` to a canvas	same-origin, CORS-enabled, canvas	tainted canvases

Tier 1 — the background worker. This is the one people miss. A Manifest V3 service worker holding <all_urls> host permissions makes fetches that are not subject to page CORS. The extension's origin is privileged; no preflight, no opaque response. That single property gets you the bytes of most CDN images that the redirect method can't hand to an engine:

export async function grabImageBlobFromBackground(srcUrl: string): Promise<Blob | null> {
  // Page-scoped schemes are unreachable from here, by construction.
  if (srcUrl.startsWith('blob:') || srcUrl.startsWith('data:')) return null;
  try {
    const res = await fetch(srcUrl, { credentials: 'omit' });
    if (!res.ok) return null;
    const blob = await res.blob();
    if (blob.size === 0 || !blob.type.startsWith('image/')) return null;
    return blob;
  } catch {
    return null;
  }
}

Note credentials: 'omit'. The worker has no useful session for a third-party site anyway, and sending what it does have to arbitrary origins is not a thing you want to do by default.

Tier 2 — inside the page. Tier 1 returns null for exactly two situations, and the content script is the answer to both. A blob: URL only resolves in the document that created it. And an in-page fetch with credentials: 'include' carries the site's session cookies and a same-origin Referer, so it reaches cookie-gated and private images — the ones on an authenticated CDN that no external fetcher can touch.

Same request, different execution context, completely different reachability. That's the whole trick.

Tier 3 — the canvas. If even an in-page fetch fails (cross-origin, no CORS headers), the image is still rendered on screen. Those pixels exist:

function elementToDataUrl(srcUrl: string): string {
  const img = Array.from(document.images).find(
    (el) => el.currentSrc === srcUrl || el.src === srcUrl,
  );
  if (!img || !img.complete || img.naturalWidth === 0) throw new Error('image element not found');

  const canvas = document.createElement('canvas');
  canvas.width = img.naturalWidth;
  canvas.height = img.naturalHeight;
  canvas.getContext('2d')!.drawImage(img, 0, 0);

  // Throws SecurityError if the canvas is tainted (cross-origin, no CORS).
  return canvas.toDataURL('image/png');
}

And here the ladder honestly ends. Drawing a cross-origin image without CORS headers taints the canvas, and toDataURL() throws SecurityError. That's not a bug to route around — it's the same-origin policy doing its job. The extension shows a toast and stops. A tool that claims to work everywhere is lying about this tier.

The chain, cheapest first:

if (srcUrl.startsWith('data:')) return searchImageByUpload(srcUrl, ids);

const blob = await grabImageBlobFromBackground(srcUrl);
if (blob) return searchImageBlob(blob, ids);

// blob: / cookie-gated — only the page can reach it
await sendToTab(tabId, { type: MSG.GRAB_IMAGE, srcUrl, engineIds: ids });

Bytes in hand. The engines still want a URL.

Google Lens has no public "here are some bytes" endpoint. So the bytes need to briefly become a URL: upload to private S3, hand each engine a short-lived presigned GET.

The presign is minted by a small Rails endpoint, and it contains the single most useful thing I learned on this project:

A presigned PUT cannot cap upload size. S3 does not enforce a signed Content-Length.

I verified this empirically after assuming otherwise. If you hand out a presigned PUT, whoever holds that URL can write an object of any size, up to S3's limits, and you pay for it. A presigned POST with content_length_range is different — the constraint is in the signed policy document, so S3 itself rejects an oversized body with EntityTooLarge:

class S3Presigner
  PUT_TTL   = 300              # 5 min to complete the upload
  GET_TTL   = 900              # 15 min for the engines to fetch
  MAX_BYTES = 15 * 1024 * 1024 # enforced by S3, not by us

  def self.presign(content_type:)
    key = "u/#{SecureRandom.uuid}"

    post = Aws::S3::PresignedPost.new(
      client.config.credentials, REGION, BUCKET,
      key: key,
      content_type: content_type,
      content_length_range: 1..MAX_BYTES,
      signature_expiration: Time.now + PUT_TTL
    )

    { upload: { url: post.url, fields: post.fields },
      get_url: object(key).presigned_url(:get, expires_in: GET_TTL),
      max_bytes: MAX_BYTES }
  end
end

Three more things that cost me time:

Field order in the multipart body is load-bearing. The file field must come last, after every signed policy field. S3 stops parsing at file — anything after it is ignored, and you get a signature error that says nothing about ordering:

const form = new FormData();
for (const [k, v] of Object.entries(upload.fields)) form.append(k, v);
form.append('file', blob, 'image'); // ← must be last

The upload has to run in the worker too. A content script POSTing to S3 hits page CORS. Same reasoning as tier 1 — the privileged context is the one that can talk to arbitrary origins.

Rate-limit the presign endpoint. No bytes pass through the server, so it's cheap and easy to forget — but every success hands out an S3 write grant. Rails 8 ships this built in:

rate_limit to: 20, within: 1.minute,
  with: -> { render json: { error: "rate limited" }, status: :too_many_requests }

The bucket has Block Public Access on and never serves anything publicly. The GET URL is unguessable and expires in 15 minutes; a one-day lifecycle rule sweeps objects regardless of what the app does.

The fallback I deliberately didn't build

When the whole ladder fails, there's an obvious-looking last resort: give up on the bytes and just open the raw srcUrl in the engines. Something is better than nothing.

It isn't. Consider the case that lands there most often — a cookie-gated image on an authenticated CDN, say a generated image in a ChatGPT conversation. That URL is signed and tied to your session. Handing it to four search engines doesn't work, because they can't fetch it either. What it does do is leak an authenticated link to four third parties.

So the extension doesn't. This path is reached only when the user explicitly chose "search by upload," or on an overlay site where they implicitly chose not to hand over the image's URL. Quietly falling back to the exact behavior they opted out of would be a bad trade dressed up as a graceful degradation.

Failing loudly with a toast is the right answer. Not every fallback is worth having.

The part that matters most

All of the above — the four tiers, the S3 bucket, the presign endpoint, the rate limiter — is the slow path. It runs only when the fast path can't.

On a normal site with a plain, fetchable image URL, the extension builds four engine URLs and opens four tabs. No bytes are read, no server is contacted, nothing is uploaded. Same twenty elegant lines it started with.

That ordering wasn't an optimization, it was the design constraint. The expensive path is also the privacy-sensitive one, and building it as an explicit fallback rather than the default means the common case stays fully client-side — and I can say exactly which right-click sends an image anywhere, because it's the only branch that can.

Ladders are worth building. Just make sure you're on the bottom rung as rarely as possible.

The extension is Reverse Image Search Anywhere — free, in the Chrome Web Store, and installable on Edge, Brave, Opera and other Chromium browsers from there. A Firefox build is in AMO review. Built with WXT and TypeScript, with a small Rails backend. If you've found a site that defeats all four tiers, I'd like to hear about it.

HTTP/3 on Kamal, and a PR to Basecamp

Anton Kopylov — Thu, 02 Jul 2026 15:28:15 +0000

A few days ago I read a good writeup on how much HTTP/3 can shave off page loads — QUIC drops a round trip on connection setup and survives network changes without renegotiating. I wanted it on my own sites.

All of them deploy with Kamal, which fronts each app with kamal-proxy. The good news: kamal-proxy already speaks HTTP/3 — it has an --http3 flag. The bad news: Kamal gave me no way to turn it on.

Two things were missing, and the second is the subtle one:

Kamal never passes --http3 to the proxy.
The proxy container only publishes TCP 80 and 443. HTTP/3 runs over QUIC, which is UDP — so even with the flag set, the UDP 443 listener would sit there unreachable.

Someone had already filed a feature request, so I wasn't alone in wanting this. I forked Kamal and added a proxy.run.http3 option that does both halves of the job: it passes --http3 to kamal-proxy run, and it publishes the HTTPS port over UDP as well (443:443/udp). There's a guard, too — you can't enable HTTP/3 when ports aren't published, since there'd be nothing to listen on.

Turning it on is one line:

# config/deploy.yml
proxy:
  run:
    http3: true

Until the PR lands, the Gemfile points at the fork:

gem "kamal", github: "tonic20/kamal", branch: "proxy-http3", require: false

I shipped it on watchbrandindex.com and confirmed the negotiation — browser and proxy now agree on h3.

Now to see if DHH merges it upstream. 🤞

P.S. — While running other sites through that checker, it flagged this one too. This blog isn't on Kamal; it's a static site on S3 + CloudFront, which already serves HTTP/3. But browsers were discovering it the slow way: connect over h2, read the Alt-Svc header, then upgrade to h3 on a later connection. The fix here lives in DNS, not the server — an HTTPS resource record (RFC 9460) at the apex:

kopylov.net.  HTTPS  1 . alpn="h3,h2"

Now browsers learn h3 is available during the DNS lookup and try QUIC on the very first connection. One more round trip saved, no server involved.