Skip to content

Recording each play exactly once with Redis SET NX

An idempotency key per play in Redis, claimed with SET NX EX alongside a rate-limit check, released when the request is refused, so retries and duplicate clients never double-count listening stats.

3 min read

Listening stats in Melodius are only worth anything if each play is counted once. Clients retry on flaky networks, apps resend on resume, and the web and desktop can both report the same session. Here is the small pattern that keeps the numbers honest.

Duplicates are normal

A play report that times out on the client may have succeeded on the server. The client cannot know, so it retries. Any endpoint that records events must assume it will see the same event more than once.

An idempotency key per play

A play is identified by who, what, when it started, and which report it is (the start or the end):

typescript
const key = idempotencyKeys.request(
  "log_play",
  `${userId}:${trackId}:${startedAtMs}:${isInitialLog ? "start" : "end"}`,
);
const claimed = await redis.set(key, "1", "EX", 86_400, "NX"); // null if it already existed

SET … NX succeeds only for the first writer, atomically. The key expires after a day, long enough to absorb any realistic retry, short enough that Redis does not grow forever.

Claim and rate limit together

Each report also passes a per-user token-bucket rate limit. Both checks run in parallel, and the order of consequences matters:

  • Rate limited, but the key was claimed: delete the key. Otherwise the real retry, which is allowed later, would be dropped as a duplicate.
  • Key not claimed: a duplicate. Do nothing.
  • Redis unavailable for the claim: treat it as not claimed rather than risk double counting.

Never let the request choose the user

The recording function takes a user id from the authenticated caller, the web action or the apps API, and is deliberately not a server action itself, so no request body can name whose history to write to. The payload is validated against a schema before anything else. The Discord bot uses the same idea when it records plays from voice, in counting plays from a voice channel.

Illustrated avatar of Kumar Manas

Written by Kumar Manas

Full-stack developer in India. I build Melodius and Krypton.

Related projectMelodius: music streaming platform