Skip to content

perf(api): refresh cached skins in the background after a day - #1014

Open
ugcodrr wants to merge 8 commits into
fix/skin-name-lookupfrom
fix/skin-background-refresh
Open

ugcodrr wants to merge 8 commits into
fix/skin-name-lookupfrom
fix/skin-background-refresh

Conversation

@ugcodrr

@ugcodrr ugcodrr commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

Description: A skin expired after three hours, and the next request waited on Mojang's session server, which rate limits by address.

  1. A new skin or a rename can take up to a day to show.
  2. getSkin no longer falls back to a cached skin when the session server fails.

After #1011 squash-merges, rebase with git rebase --onto origin/main f811f3cb fix/skin-background-refresh.

Testing: set a skin's expiresAt to 0 and request /skin/head?uuid=<uuid>. It comes back right away, and its expiresAt moves a day out.

Depends on #1011

A cached skin was used for 3 hours; after that, the next request waited for
Mojang's session server before it could draw a head or a render. Every
player seen again after 3 hours cost a Mojang call, and the session server
rate limits by address.

A cached skin is now always served at once. Once it's a day old, the
request that finds it starts a refresh in the background, and the next
request gets the new skin. Requests that arrive while a refresh is running
share it, so a stale skin costs one call however many heads are drawn. A
failed refresh keeps the cached skin and is tried again after an hour. It
only moves the skin's refresh time, so it can't write an older copy back
over anything saved meanwhile, such as the usernameToLower backfill.

A player with no cached skin still waits for Mojang, as before.

This drops getSkin's fallback to the cached skin when the session server
fails, along with its check that a skin found by name belongs to the uuid
Mojang gave for that name. No request path falls back anymore: a cached
skin is served before Mojang is asked, and its refresh asks for the skin's
own uuid. save() replaces the document with the skin's own uuid, so it
can't hit the duplicate key error (E11000) that the check guarded against.
After a rename, a lookup by the name can still serve the previous owner's
skin until that copy is refreshed; from then on the name finds the new
owner.
@vercel

vercel Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
statsify Ignored Ignored Nov 5, 2026 8:19am UTC

@github-actions github-actions Bot added the api label Oct 21, 2026
@ugcodrr
ugcodrr added this pull request to stack #1064 October 31, 2026 21:11
@vercel

vercel Bot commented Nov 3, 2026

Copy link
Copy Markdown

Deployment failed for project statsify with the following error:

Too many requests - try again in 5 minutes (more than 60, code: "api-deployments-flood").

Learn More: https://vercel.com/docs/limits#rate-limits

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant