Inside the Template's platform service

How the Template's PlatformService is built - its layers, the lint rules that keep HTTP in one file, a cache entry's lease, failures, cost, tests and adding a route.

Building on the platform

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.luau re-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, the ETag), Summaries (the own game's analytics, breakdowns, themes and key usage reduced for the Platform tab) and Cache (the shared entry: claim, cooldown, the lease).

  • src/core/server/Services/PlatformService/: init.luau holds the public calls and init(), Connection the secret and every request, Reads the shared cache and every read, Writes feedback, transfers and studio bans, and Status status(), the admin tabs and the platform command.

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 a Rules/Platform builder (gamesRequest, historyRequest…), which refuses a bad query as bad_query before anything is sent.

read() in Reads

The cache: this server's own copy first, then one atomic UpdateAsync on the shared MemoryStore hash map, deciding with Rules.claim whether to serve, wait or fetch.

send() in Connection

One Http.send per try with the Secret header, run by Util/Retry; after each try Rules.verdict says keep, retry (with the Retry-After wait) or stop, and Rules.answer turns the last status into a Result. Http also spends the server's request budget and counts the request by host for budgets.

decode()

HttpService:JSONDecode, then Rules.parse against 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 server Config/Overrides/Platform, merged in Connection only.

The layers of the platform service. Game code calls a public function such as games. A Rules builder makes and checks the request. The read first looks at this server's own copy; if that is not fresh, it claims the shared MemoryStore entry with Rules.claim. Only the server that takes the lease calls send, which makes the HTTP request with retries to the platform. Rules.verdict and Rules.answer read each status, and Rules.parse checks the answer before it is stored and returned.

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:GetAsync and PostAsync, and GetSecret outside src/core/server/Roblox/Http.luau, which budgets, retries and counts every request and never prints a secret. Its callers are PlatformService and ExperienceNotificationService.

memorystore-boundary

MemoryStoreService outside src/core/server/Roblox/MemoryStore.luau, which checks limits, retries and counts every call. DataStores and ProfileStore stay DataService'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 JobId and a counter, unique across servers and threads.

etag

The platform's ETag for 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.

A shared cache entry's states. An entry starts empty. A server that finds it empty takes the lease and fetches. A good answer makes it fresh. After its route's freshness, 60 or 300 seconds, it is stale, and the next read takes the lease again while keeping the old answer. A failed fetch lets go of the lease and keeps the older answer. A lease whose holder died lapses after 10 seconds. An entry expires twice its freshness after it was stored, within 600 to 3,600 seconds, and is empty again.

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. platform shows the error as Shared cache.

An outage

No answer, a 5xx or a 429: the entry is held as Rules/Platform.DOWN for outageSeconds (30), so nobody asks the platform for it again meanwhile, and an older answer up to 3,600 seconds old is served with stale = true. Without one, the read answers the reason. The reason is kept as Last error.

A refusal

401 or 403, 404, any other 4xx, or an answer of the wrong shape: never hidden behind an older answer. The entry is held with the refusal for refusalSeconds (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_down at once if the lease is an outage's, and otherwise looks every 0.5 seconds for up to 3 seconds, then answers busy.

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 UpdateAsync to 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, game and feedbackList, 300 for history, genres, market, limiteds, feedbackThemes and keyUsage, 600 for analytics and breakdowns, 1,800 for key.

  • Http and MemoryStore count every request and call for the staff budgets command.

  • 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.luau and Cache.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; the ETag. Beside them, Platform.ownGame.spec.luau covers the own-game requests and summaries.

tests/core/server/Services/PlatformService.spec.luau

With PlatformService.feedback.spec.luau and PlatformService.ownGame.spec.luau, over tests/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-Match and 304, 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; sharedMaxBytes fits 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:

  1. Build the request

    Add a builder to Rules/Platform/Requests that checks its parameters as the API does and returns a Request (route, method, path, query), and export it from Rules/Platform/init.luau.

  2. Describe the answer

    Add the route's shape to PARSERS in Rules/Platform/Responses, with ! on the fields that must be there.

  3. Set its freshness

    Add an entry to freshSeconds in Config/Platform, shorter than staleSeconds.

  4. Expose it

    Add the read to PlatformService/Reads, passing the built request to read, and assign it to the public table in PlatformService/init.luau.

  5. 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.

Updated