PlatformService is two layers: a pure rules module, Rules/Platform, that decides everything (what to send, what an answer must look like, what a status means, whether to fetch or wait), and the service itself, which does only the Roblox half (the secret, the request, JSON and the shared cache). Both are folder modules, each required by its folder's name:
src/core/shared/Rules/Platform/:init.luaure-exports every name of its parts,Requests(each route's request, the canonical query, the cache key),Responses(each answer's shape, status to refusal, retries, theETag),Summaries(the own game's analytics, breakdowns, themes and key usage reduced for the Platform tab) andCache(the shared entry:claim,cooldown, the lease).src/core/server/Services/PlatformService/:init.luauholds the public calls andinit(),Connectionthe secret and every request,Readsthe shared cache and every read,Writesfeedback, transfers and studio bans, andStatusstatus(), the admin tabs and theplatformcommand.
The service makes no engine call of its own: requests and the secret go through server/Roblox/Http and the cache through server/Roblox/MemoryStore. This page is for a developer changing or extending it; using it is on The Template's platform service. Its decision is a line in the Template's ARCHITECTURE.md Decisions: one service calls the platform, and its reads share one MemoryStore cache across servers.
The layers of the platform service
A read goes down through the layers and stops at the first that can answer it.
- Public calls
key(),games(query),game(id),history(id, range),genres(),market(range), the own-game reads,limiteds(query)and the writes (sendFeedback,sendTransfer,claimTransfer,studioBan). Each builds its request with aRules/Platformbuilder (gamesRequest,historyRequest…), which refuses a bad query asbad_querybefore anything is sent.- read() in Reads
The cache: this server's own copy first, then one atomic
UpdateAsyncon the shared MemoryStore hash map, deciding withRules.claimwhether to serve, wait or fetch.- send() in Connection
One
Http.sendper try with the Secret header, run byUtil/Retry; after each tryRules.verdictsays keep, retry (with theRetry-Afterwait) or stop, andRules.answerturns the last status into aResult.Httpalso spends the server's request budget and counts the request by host forbudgets.- decode()
HttpService:JSONDecode, thenRules.parseagainst the route's shape.- Config/Platform
Every number: base URL, secret name, tries, backoff, freshness,
staleSeconds, the outage and refusal holds, the lease, the wait,sharedMaxBytes. A game's own values go in its serverConfig/Overrides/Platform, merged inConnectiononly.
Why the platform rules are pure
Rules/Platform uses no Roblox API, so every decision runs in Lune tests without Studio: the request each call builds, canonical queries and cache keys, every refused query, Retry-After, which statuses retry, status to reason, every answer's shape, and the lease. The service decides nothing the rules do not. A field the platform adds later passes through unchecked, so a new field never breaks an old game; a missing required field, or one of the wrong type, is bad_answer.
The lint rules that keep HTTP in one file
The Template's boundary linter (.lune/lint-boundaries.luau) refuses, anywhere under src/:
- http-boundary
RequestAsync,HttpService:GetAsyncandPostAsync, andGetSecretoutsidesrc/core/server/Roblox/Http.luau, which budgets, retries and counts every request and never prints a secret. Its callers arePlatformServiceandExperienceNotificationService.- memorystore-boundary
MemoryStoreServiceoutsidesrc/core/server/Roblox/MemoryStore.luau, which checks limits, retries and counts every call. DataStores and ProfileStore stayDataService's alone.
Game code therefore never calls the platform directly: it calls PlatformService, which is why the key, the retries and the shared cache need no per-game code. Http and MemoryStore are not services: they have no lifecycle and the Loader never loads them.
How a server starts the platform service
The Loader skips the service while Config/Features.platform is off. Otherwise init() reads the secret once with Http.secret("BlockoutApiKey", …) and adds the Bearer prefix, keeping it a Secret that is never a string; the cache uses the MemoryStore hash map BlockoutPlatform; Writes answers feedback.requestSubmit and Status the admin panel's two requests; and the platform command is registered. A missing secret is reported once by Http and leaves every call answering unavailable; a MemoryStore map that fails leaves the service on this server's own cache. The startup diagram is on What happens when the secret is missing.
A shared cache entry and its lease
Each route and canonical query is one entry in the MemoryStore hash map. Its key is the path and the query sorted by name; a key over 120 characters becomes the path and a 64-bit hash of it, and the entry keeps the full key, compared on every read, so two queries never share an answer.
- key
The full route and canonical query.
- body
The platform's answer as JSON text, as fetched.
- storedAtos.time() seconds
When the answer was fetched.
- leaseUntilos.time() seconds
Until when one fetch holds the entry: now plus
leaseSeconds(10).- leaseBy
Which fetch holds it: the server's
JobIdand a counter, unique across servers and threads.- etag
The platform's
ETagfor the body, so any server can revalidate an answer another fetched.
Every write sets the entry to expire after twice its route's freshness, at least sharedMinSeconds (600) and at most staleSeconds (3,600): the experience's MemoryStore memory is small. Rules.claim makes the one decision inside the atomic update: a fresh answer is served; a live lease held by another fetch means wait; anything else takes the lease, keeping the older body to fall back on. A slow fetch renews its own lease every half lease, never one another fetch took meanwhile.
How a read falls back when something fails
- MemoryStore fails
Throttled, or Studio without a published place: the same steps run on this server's own table, so each server fetches once per interval.
platformshows the error as Shared cache.- An outage
No answer, a
5xxor a429: the entry is held asRules/Platform.DOWNforoutageSeconds(30), so nobody asks the platform for it again meanwhile, and an older answer up to 3,600 seconds old is served withstale = true. Without one, the read answers the reason. The reason is kept as Last error.- A refusal
401or403,404, any other4xx, or an answer of the wrong shape: never hidden behind an older answer. The entry is held with the refusal forrefusalSeconds(30), which every server answers meanwhile, so a staff Refresh cannot spend the key's 120 a minute re-asking it.- Another server holds the lease
A server with an older answer serves it at once, flagged stale. Without one it answers
platform_downat once if the lease is an outage's, and otherwise looks every 0.5 seconds for up to 3 seconds, then answersbusy.- The answer is too big to share
Over 30,000 bytes: kept on this server only, and the shared entry's lease is let go with its older body, so other servers fetch their own.
- The answer has the wrong shape
bad_answer: never cached and never returned to game code.
This server's copies too old to serve even stale are dropped whenever a new answer is stored, so its table stays as small as the queries in use.
What a read costs in MemoryStore and in requests
A read this server's copy answers costs nothing.
Any other read costs one
UpdateAsyncto claim, one more to store the answer if this server fetched, and one per 0.5-second look while it waits on another server's lease (at most 6).Each distinct query costs the key at most one request per freshness interval for the whole game: 60 seconds for
games,gameandfeedbackList, 300 forhistory,genres,market,limiteds,feedbackThemesandkeyUsage, 600 foranalyticsandbreakdowns, 1,800 forkey.HttpandMemoryStorecount every request and call for the staffbudgetscommand.Feedback is never cached: one request per send, plus its retries, and a server's players together send at most
feedbackPerServerMinute(10) a minute.
The tests of the platform service
Run with lune run test Platform in the Template.
- tests/core/shared/Rules/Platform/
Requests.spec.luau,Responses.spec.luauandCache.spec.luau: every route's request; canonical queries and cache keys, hashed when long; every refused query; feedback bodies and length in characters; Retry-After; which statuses retry; status to reason; which refusals are outages; every answer's shape; fresh, stale and empty; claim, wait, a lapsed lease, release; theETag. Beside them,Platform.ownGame.spec.luaucovers the own-game requests and summaries.- tests/core/server/Services/PlatformService.spec.luau
With
PlatformService.feedback.spec.luauandPlatformService.ownGame.spec.luau, overtests/lib/platform.luau: the real service over HttpService, secret, MemoryStore and scheduler doubles: a missing secret, the key sent as a Secret, one fetch for two servers, waiting on another's lease, stale answers while down, 429 Retry-After, a refused key never served stale, 401 and 404 not retried, MemoryStore failing, answers too big to share,If-None-Matchand304, feedback's one idempotency key across retries and the player limits, the Platform and Feedback tabs, the admin output.- tests/core/server/Config/Platform.spec.luau
The base URL is the studio's domain; every read route's freshness is shorter than
staleSeconds;sharedMaxBytesfits a MemoryStore item; the five categories.
Adding a read route to the platform service
A route the developer API serves but the Template does not call yet:
Build the request
Add a builder to
Rules/Platform/Requeststhat checks its parameters as the API does and returns aRequest(route, method, path, query), and export it fromRules/Platform/init.luau.Describe the answer
Add the route's shape to
PARSERSinRules/Platform/Responses, with!on the fields that must be there.Set its freshness
Add an entry to
freshSecondsinConfig/Platform, shorter thanstaleSeconds.Expose it
Add the read to
PlatformService/Reads, passing the built request toread, and assign it to the public table inPlatformService/init.luau.Test it
Add specs for the request, the refusals and the shape under
tests/core/shared/Rules/Platform/.
Another HTTP destination does not go here: it needs its own service, calling server/Roblox/Http, and its own decision record.
Why the Template caches platform reads this way
The alternatives the Template turned down
Per-server caches only: simpler, but N servers make N requests per interval, and a large game
exceeds 120 a minute on its first read. The cache inside DataService: keeps the old
MemoryStore boundary, but puts a network cache into the module that owns saves and session locks.
A generic HTTP service any module can call: one more layer, every caller would need the
platform's rules, and the boundary would no longer say where requests go. The key in server
config: a key in source reaches every copy of the repository and every place file; a secret is
per experience and cannot be printed. The Template later moved the request itself, and the secret,
into server/Roblox/Http for every caller; the platform's rules and cache stayed here.
The Template's platform service
Switching it on, every call and its reasons.
The platform's side of the same budget.
Updated