Document the remote cache request limits and how LPM CLI waits them out

[tolgaergin]

Companion to tolgaergin/a-package-manager#233, which limits remote cache requests per account and caps artifacts at 100 MiB, and lpm-dev/rust-client#950, which makes LPM CLI wait limits out.

What changes

content/docs/infra/remote-cache.mdx:

• Archive limit: the LPM.dev Registry accepts archives up to 100 MiB (104,857,600 bytes); LPM CLI skips uploading a larger one and builds the task as usual. With a custom cache endpoint, LPM CLI uploads and restores archives up to 500 MiB.
• Request limits section: per Pro account or organization seat, Enterprise included:
  • every request whose token may use the account's cache for it: 3,000 a minute and 100,000 a day, misses and status checks included, and one per different artifact a batch query asks about, or one for a batch larger than the window has left, which is refused;
  • uploads: 300 a minute, 4,000 and 12 GiB a day;
  • cache hits: 2,000 a minute, 50,000 and 40 GiB of downloads a day, of which 5 GiB through the Registry;
  • LPM CLI and Turborepo download a cache hit from the cache's download host, cache-dl.lpm.dev, through a link the Registry answers with that works for a minute, so a CI firewall must allow that host; Turborepo downloads a signed artifact through the Registry, as do other clients and older LPM CLI releases; LPM CLI treats an artifact without a content hash, as Turborepo uploads one, as a miss and replaces it;
  • an upload of content the cache already holds isn't counted as an upload, unless the account's cache hits are spent;
  • an organization's daily limits scale with every seat, its minute limits with up to ten, and its uploads a minute with up to five;
  • 4 uploads in flight per seat, at least 8 and at most 16, across the Registry, and 8 uploads and downloads together per seat, 32 to 64, on each Registry server, which shares its places equally once half full, keeps a few for accounts using few, and answers as busy until a place frees when every place is taken; an upload the Registry refuses before receiving it, or of content the cache already holds (by the checksum LPM CLI sends), doesn't count as an upload, though checking that storage still holds that content counts as a cache hit, and content storage lost is stored again;
  • an upload, or a download through the Registry, slower than 10 seconds plus a second for every 128 KiB, or longer than 2 minutes, is cut off, LPM CLI's own 30 seconds aside; after an interrupted download the task runs as on a miss, and the hit still counts;
  • an upload that stops partway holds its artifact for at most 5 minutes;
  • an account without remote cache gets 30 requests a minute and 1,000 a day, counted apart from its requests before its plan changed; an organization whose billing lapsed gets HTTP 402 to everything but status checks, which report paused;
  • a request the Registry refuses, such as an upload with a read-only token or a request that isn't valid, is answered with why, and counts against limits of its own instead of the request limits: 30 a minute and 1,000 a day for its token, and 120 and 5,000 for its account, whatever the seats. Once one is spent, each request is still answered as before. A token reaches only its own account's cache: slug or teamId naming any other gets 403, whether or not that account exists, and a pair of which only one names the token's own account gets 400;
  • with a read-only token, Turborepo should run with --remote-cache-read-only, or it turns its remote cache off after the first refused upload. LPM CLI stops uploading for the run after a refused upload, and stops the remote cache for the run after a refused lookup or once the organization's billing lapses; an upload the cache has no room for is skipped on its own;
  • the Registry checks a token at most once a minute on each server, so a revoked token can keep working for up to a minute; when LPM CLI refreshes an lpm login session, the session's previous access token stops working within five minutes, and any older one at once, or within that minute on a server that checked it;
  • a token that isn't valid gets the same 401 for a minute; after 60 tokens from one address or IPv6 /64 in a minute that aren't valid or whose requests are refused or over their account's request limits, or 240 from one /48, the address gets 429 for the rest of the minute, though one token from it is still checked every 2 seconds, and one whose requests were served in the last 23 hours and not refused since passes; a status check serves a token only when its account's cache serves reads (enabled or over_limit);
  • windows start with their first request, not at a set time of day.
• How LPM CLI and Turborepo respond: HTTP 429 with Retry-After; LPM CLI skips that kind of request until then, pauses uploads during a lookup limit too, and warns once a run for each kind. A wait of 5 seconds or less usually means the Registry is busy for a moment, or a minute's window is about to reset: LPM CLI sends such a lookup or upload once more after the wait plus up to half again, unless that kind was paused meanwhile, and notes remote cache is busy; skipping some uploads for a moment (or lookups) once a run if it skips some anyway. Turborepo gets per-minute limits as 429 and daily limits as 403 remote_caching_over_limit.
• Credentials: lpm login credentials read and write the user's personal cache; an organization's cache needs one of its tokens.
• Troubleshooting: a new "A request limit is reached" entry, with ways to spend fewer requests; the 429 with Retry-After: 1 for uploads or downloads in flight, and Retry-After: 2 for a busy Registry server, with LPM CLI's notice and retry; and the 409 for an artifact another upload is storing, which LPM CLI leaves to that upload.

content/docs/infra/login.mdx says an account keeps up to 20 active lpm login sessions, and a sign-in past that ends the one used least recently. content/docs/infra/setup.mdx says an account holds up to 100 active tokens it created, that lpm setup local past that fails for a new project or one whose token has expired, while replacing a live project token works, and that expired and revoked ones are deleted 30 days later.

content/docs/lpm-dev-and-pro.mdx lists the daily uploads and cache hits (4,000 and 50,000) with the plans and links to the full limits, and labels plan sizes in binary units (100 MiB, 5 GiB, 25 GiB), as the LPM.dev Registry does after tolgaergin/a-package-manager#235.

Each content commit is followed by one that refreshes the content dates.

Testing

npm run check passes on 6a116c2, the content before its dates commit: content dates, SEO audit and lint, types, 91 unit and 22 component tests, and the build at 405 pages.

🤖 Generated with Claude Code

[tolgaergin]

Third review: ledger

Fixed in d3dbf4e. npm run check passes.

Finding	Outcome
P2, security (setup.mdx:192): "Revoking a token always works" was false	Fixed: revoking in Registry token settings is never limited, so no one holding a token can keep you from revoking it; lpm setup local's token changes can be refused with HTTP 429 before they change anything; and a revoked token can keep working for up to a minute until the Registry's caches drop it, while the first 20 revocations a minute per user also clear it from them at once.
P2 (remote-cache.mdx:323-341, 392): one bullet of about 293 words combined the download host, redirects, authorization, revocation delay, limits and retries	Fixed: split into sections for the download host (cache-dl.lpm.dev must be reachable), revoked tokens and failing tokens.
P3 (setup.mdx:192): a 144-word paragraph combined six contracts	Fixed: split.

[tolgaergin]

Rewrote this PR's changed passages in plain English (the simple-english skill, Plain mode): sentences of at most 20 words for steps and 25 for descriptions, active voice, can/will/must instead of other modals, no contractions, semicolons or em-dashes, each condition before its result, and cautions with the instruction first. Code, identifiers, quoted messages and facts are unchanged. npm run check passes. The login page also says lpm login tries again for up to 30 seconds when the Registry can't complete the sign-in at once (lpm-dev/rust-client#950).