Sri Writes

Notes on Idempotency

Srivaths Aripirala — Sat, 01 Aug 2026 00:00:00 GMT

Every outage post-mortem I have ever written has the same villain: a retry that was not safe to retry. A payment fires twice. A webhook double-processes. A queue redelivers a message the consumer already handled, and the consumer handles it again with enthusiasm.

The fix is rarely cleverness. It is making the operation idempotent, so that retrying it is a no-op instead of a hazard.

The shape of the fix

An idempotency key is just a promise from the caller: this request and the one I sent nine seconds ago are the same request, and you should only honour one of them. The server’s side of the bargain is to remember what it answered.

handlers/payment.jsjs

async function handlePayment(req, res) {
  const key = req.headers['idempotency-key'];
  const seen = await store.get(key);
  if (seen) return res.json(seen);

  const result = await charge(req.body);
  await store.set(key, result, { ttl: '24h' });
  return res.json(result);
}

That costs one extra lookup per request. In exchange, every client, proxy and load balancer between you and the caller is allowed to be a little bit sloppy about delivery — which, in practice, they always are.

Where it gets subtle

The naive version above has a race: two concurrent requests with the same key both miss the cache, and both charge. The store needs to be the thing that serialises them, not an afterthought.

migrations/003_idempotency.sqlsql

create table idempotency (
  key         text primary key,
  response    jsonb,
  created_at  timestamptz not null default now()
);

-- The insert is the lock. Whoever wins goes on to charge; the loser waits
-- and reads the winner's response.
insert into idempotency (key) values ($1)
on conflict (key) do nothing
returning key;

If the insert returns no row, someone else is already working. The correct behaviour then is to poll briefly and return their answer — not to charge, and not to error.

Write it while you still might be wrong. That is when it is useful to someone else who is wrong the same way.

The part nobody writes down

Idempotency keys need a retention policy. Keep them forever and the table becomes the largest thing in your database; expire them too eagerly and a client retrying after a long network partition gets charged twice, which is the exact failure you built this to prevent.

Twenty-four hours is the number I keep landing on. It is longer than any sane client retry window and short enough that the table stays small. It is not a principled answer. It is just one that has not bitten me yet.

A Static Blog for a Dollar a Month

Srivaths Aripirala — Thu, 30 Jul 2026 00:00:00 GMT

The brief I gave myself: host a static blog for less than a coffee a month, without babysitting it every week. No Kubernetes. No CDN I do not need yet. No managed database for content that is just files on disk.

What I ended up with has two moving parts, and neither of them moves very often.

The shape

Markdown lives in Git. A build turns it into HTML. The HTML goes into a private S3 bucket, and CloudFront serves it. There is no origin server to overwhelm, because there is no origin server.

The bucket is private — genuinely private, with Block Public Access fully on. CloudFront reaches it through Origin Access Control, which signs every origin request with SigV4.

infra/bucket-policy.jsonjson

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipalReadOnly",
      "Effect": "Allow",
      "Principal": { "Service": "cloudfront.amazonaws.com" },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::example-blog/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::111122223333:distribution/E1EXAMPLE"
        }
      }
    }
  ]
}

The AWS:SourceArn condition is the part people leave out. Without it the policy trusts the CloudFront service, which means any CloudFront distribution in any account can read your bucket. With it, only yours can.

The part that will catch you

An S3 REST origin does not resolve directory indexes. Request /posts/something/ and S3 looks for an object with that literal key, finds nothing, and returns 404. The static website endpoint would handle this, but using it forces the bucket public and drops HTTPS to the origin.

So the rewrite moves to the edge:

infra/viewer-request.jsjs

function handler(event) {
    var request = event.request;
    var uri = request.uri;

    if (uri.charAt(uri.length - 1) === '/') {
        request.uri = uri + 'index.html';
    } else if (uri.lastIndexOf('.') <= uri.lastIndexOf('/')) {
        return {
            statusCode: 301,
            statusDescription: 'Moved Permanently',
            headers: { location: { value: uri + '/' } }
        };
    }

    return request;
}

A CloudFront Function, not Lambda@Edge. It runs in about a millisecond, costs a sixth as much, and this logic is never going to outgrow the runtime.

Cache headers earn their keep

Two rules do almost all the work. Fingerprinted assets are immutable forever; HTML must always be revalidated, or a deploy takes a day to become visible.

Path	Cache-Control
`/_astro/*`	`max-age=31536000, immutable`
`*.html`	`max-age=0, must-revalidate`
`/feed.xml`	`max-age=3600`

Get this backwards — long TTLs on HTML — and you will spend the rest of the site’s life issuing invalidations to work around it.

The bill

Storage is under ten cents. Requests are negligible, because CloudFront only touches the origin on a cache miss. Transfer is dominated by images, and there are not many. The Route 53 hosted zone is fifty cents a month flat, and is genuinely the largest line item.

Call it a dollar. It has not moved in three months, including the week a post reached the front page of a link aggregator and served forty thousand people — which cost nothing extra, because serving cached bytes from an edge is what the whole arrangement is for.

Why I'm Leaving Medium

Srivaths Aripirala — Tue, 28 Jul 2026 00:00:00 GMT

For a few years, Medium was the path of least resistance. Write, hit publish, let their distribution do the rest. It worked, until the friction started outweighing the convenience.

A paywall that turns away the readers I actually want to reach. A partner programme that pays out by algorithmic mood. An editor that fights me every time I want a code block that does not look like stock art.

None of that is a scandal. It is just someone else’s platform, run for someone else’s incentives.

A blog you do not control is a rented apartment. Nice view, no say in the renovations.

What “owning it” actually means

It is not really about the hosting. It is about three things that only work if you hold them yourself:

The URLs. If a post’s address can be taken away or rewritten, every link anyone ever made to it is on loan.
The format. Markdown in a Git repository will still open in twenty years. A proprietary editor’s export button is a promise, not a guarantee.
The reader. No interstitial, no “you have two free articles left”, no sign-in wall between what I wrote and the person who came to read it.

The migration is the boring part

Export the archive, convert the HTML to Markdown, download the images out of Medium’s CDN instead of hotlinking them, and keep the original publication dates so the archive still reads chronologically.

The one step that is easy to skip and expensive to skip: set canonicalUrl on every migrated post to its Medium address first, so search engines do not see two copies of the same article while both exist. Then, once the new site is indexed, reverse it — point Medium at the new URLs and drop the field.

Leave the canonicals pointing at Medium permanently and the traffic keeps accruing to Medium, which defeats the entire point of moving. I have a calendar reminder six weeks out. I recommend one.

So this is post one on the new setup: a domain I already owned, a static site, and a few dollars of infrastructure. The next post covers exactly how cheap that ended up being.

A Small Caching Layer for a Slow API

Srivaths Aripirala — Fri, 24 Jul 2026 00:00:00 GMT

A dashboard I maintain calls a third-party API for exchange rates on every page load. The endpoint is slow — 800 to 900 milliseconds — and the data changes maybe once an hour. There was no reason to pay that latency tax on every request.

lib/rates-cache.jsjs

const TTL_SECONDS = 3600;

export async function getRates() {
  const cached = await redis.get('rates:latest');
  if (cached) return JSON.parse(cached);

  const fresh = await fetchRatesFromUpstream();
  await redis.set('rates:latest', JSON.stringify(fresh), 'EX', TTL_SECONDS);
  return fresh;
}

p95 on that route dropped from 910ms to 4ms. The cache miss — once an hour, when the TTL expires — still costs the full round trip, but every other request rides on data that is at most sixty minutes stale, which the dashboard’s users have never once noticed.

The miss is not free

The version above has a stampede problem. When the key expires, every concurrent request misses at once and they all call upstream together. At low traffic you will never see it. At the moment you most want the cache working, you will.

A single-flight lock fixes it:

lib/rates-cache.jsjs

export async function getRates() {
  const cached = await redis.get('rates:latest');
  if (cached) return JSON.parse(cached);

  // Whoever wins the lock refreshes; everyone else serves the stale copy
  // rather than piling onto an already-slow upstream.
  const won = await redis.set('rates:lock', '1', 'NX', 'EX', 30);
  if (!won) {
    const stale = await redis.get('rates:stale');
    if (stale) return JSON.parse(stale);
  }

  const fresh = await fetchRatesFromUpstream();
  await redis.set('rates:latest', JSON.stringify(fresh), 'EX', TTL_SECONDS);
  await redis.set('rates:stale', JSON.stringify(fresh));
  return fresh;
}

The second key has no expiry. It exists purely so there is always something to serve while the refresh is in flight. Serving data that is seventy minutes old beats serving a spinner for nine hundred milliseconds, and it beats hammering an upstream that is already struggling.

When not to bother

If the upstream is fast, caching adds a failure mode and buys nothing. If the data must be current to the second, a cache is a correctness bug wearing a performance costume.

This one was worth it because the numbers were lopsided: a slow call, data that changes hourly, and users who genuinely cannot tell. That combination is rarer than the number of caches in the average codebase would suggest.