Network
Remotes that are owned by the server and safe by default.
-- Server (inside a service)
local Network = Constella.Network
local Check = Network.Check
local server = context.Cleanup:Add(Network.Server.new("Shop"))
local purchase = server:Function("Purchase", {
Schema = { Check.literal("Sword", "Shield") },
RateLimit = { Count = 2, Per = 1 },
})
purchase:SetHandler(function(player, item)
return trySpend(player, PRICES[item])
end)
-- Client (inside a controller)
local shop = Constella.Network.Client.new("Shop")
local ok, result = shop:Function("Purchase", { Timeout = 5 }):Invoke("Sword")
Security model
The server never trusts the client. Every request from a client passes these checks, in this order, before your handler runs:
| # | Check | Rejection reason |
|---|---|---|
| 1 | The endpoint accepts client requests (it has a Schema) |
NotAccepted |
| 2 | Per-player, per-endpoint token bucket | RateLimited |
| 3 | Payload size (default 4096 bytes), nesting depth (8) and value count (512) | PayloadTooLarge |
| 4 | Schema validators. Extra arguments are rejected |
InvalidArguments |
| 5 | Your Authorize(player, ...) hook. Errors count as a rejection |
Unauthorized |
When a request is rejected:
- An event request is dropped.
- A function call gets a generic code back:
"RateLimited"or"Rejected". - If a handler fails, the client gets
"ServerError". The error text is never sent to the client. - The detailed reason stays on the server. It’s counted in
server:GetStats(), passed toOnReject, and logged when you provide aLogger.
Other rules:
- Only the server creates remotes. Each
Serverowns one namespace folder (ReplicatedStorage.ConstellaRemotes.<Namespace>). Creating a secondServerfor the same namespace is refused, so it’s always clear who owns a remote. - An event without a
Schemagoes from server to client only. Client fires on it are rejected. Functionrequires aSchema(use{}for no arguments).- The server never calls
InvokeClient, because a client could hang it. Use events to send data to clients. - Rate limiting is on by default (30 requests per second per player, per endpoint). Pass
RateLimit = falseonly for endpoints you rate-limit some other way. - Leaving and rejoining: per-player state is dropped on
PlayerRemoving, so a player who rejoins starts with a fresh bucket and nothing leaks. A request that arrives afterPlayerRemovingis dropped (a function answersUnavailable), so it can’t create new state for a player who is gone.
What the payload check protects (and what it doesn’t)
The size, depth and value-count check runs after Roblox has already received and decoded the request, because a remote’s arguments only reach Luau once the engine has deserialized them. So the check:
- does protect your server’s CPU time and logic: an oversized or deeply nested request is rejected before validators,
Authorizeor your handler touch it, and it can’t make them loop over huge tables; - doesn’t save bandwidth or decoding work: the bytes have already crossed the network, and Roblox has already decoded them. Roblox’s own remote limits and throttling cover that layer.
The size is Constella’s estimate of the decoded values, not the exact wire size (see Known limitations). If you need to shrink what’s sent over the network, encode it yourself, for example into a buffer, or use a dedicated serializer such as Zap or Blink for that traffic. Constella’s checks still apply to whatever reaches the handler.
Validators are your code too (custom functions, Check.refine predicates). If one throws, the error goes to OnError as a server bug and the request is rejected as InvalidArguments. The client never sees the error text.
Validation only checks that the shape of a request is acceptable. Your handler still decides whether it’s allowed in the game (for example, whether the player can afford the item). Never accept prices, rewards or outcomes from the client.
Client vs server API
Server (Network.Server) |
Client (Network.Client) |
|
|---|---|---|
| Create | Server.new(namespace, options?) creates the folder |
Client.new(namespace, options?) waits for the folder (default timeout 10s) |
| Events | server:Event(name, config?) |
client:Event(name) |
| Receive | event:Connect(function(player, ...) end). Only validated requests arrive |
event:Connect(function(...) end) |
| Send | event:Fire(player, ...), FireAll, FireList, FireExcept |
event:Fire(...) |
| Functions | server:Function(name, config) then fn:SetHandler(handler) |
client:Function(name, { Timeout?, MaxInFlight? }) |
| Call | Not available (the server never invokes clients) | fn:Invoke(...) returns (true, ...) or (false, code) |
| Errors | Handler and validator errors go to OnError. Rejections go to OnReject and GetStats |
Codes: Timeout, TooManyRequests, RateLimited, Rejected, Unavailable, ServerError, NetworkError |
| Cleanup | server:Destroy() removes the folder and every remote |
client:Destroy() disconnects handlers |
Server.new raises if it’s used on a client, and Client.new raises if it’s used on the server.
Invoke never hangs: it returns (false, "Timeout") after the timeout (default 10 seconds). Luau can’t cancel a timed-out InvokeServer, because the engine owns that wait, so its thread stays suspended until the server answers. To keep that bounded, each client function allows at most MaxInFlight calls (default 8) to be outstanding, counting timed-out ones that haven’t come back yet. Beyond that, Invoke returns (false, "TooManyRequests") straight away without contacting the server. fn:GetInFlight() reports the current count.
Endpoint config
| Field | Default | Description |
|---|---|---|
Schema |
none | An array of validators, one per argument |
RateLimit |
{ Count = 30, Per = 1 } |
{ Count, Per }, or false to disable |
MaxPayloadBytes |
4096 | Estimated size limit |
Authorize |
none | (player, ...) -> boolean |
Unreliable |
false |
Events only: creates an UnreliableRemoteEvent |
Server options: Parent, OnReject(player, endpoint, reason, detail), OnError(message), Logger (a Debug logger) and Clock (for tests).
Server options also include MaxInFlightPerPlayer (16), MaxInFlight (256) and RejectLogInterval (5 seconds). Concurrent request limits apply across every endpoint in the namespace, before validators or authorization can yield, and stay occupied until all handlers return. Excess events are dropped; functions return RateLimited. GetStats()[endpoint].Rejected.Busy counts concurrency rejections, and InFlight reports currently occupied requests. A player disconnect does not free slots still occupied by running work.
Logger warnings aggregate rejection counts per endpoint and reason. The first rejection logs immediately; subsequent warnings occur when another rejection arrives after the interval. Count includes rejections since the preceding warning. OnReject and GetStats still count every rejection. Set RejectLogInterval = 0 to log every rejection. Client MaxInFlight limits protect that client; enforce server limits independently.
Validators (Network.Check)
Each validator is a function (value) -> (ok, reason?), so you can write your own.
| Validator | Accepts |
|---|---|
Check.string(maxLength = 200) |
A valid UTF-8 string of at most maxLength bytes |
Check.number(min?, max?) |
A finite number (no NaN, no infinity) |
Check.integer(min?, max?) |
A finite whole number |
Check.boolean() |
true / false |
Check.literal(...) |
One of the listed values |
Check.optional(v) |
nil, or a value v accepts |
Check.union(...) |
A value any of the validators accepts |
Check.array(v, maxLength = 50) |
A dense array: no holes, no extra keys |
Check.record({ Key = v }) |
Exactly these string keys. Unknown keys are rejected |
Check.map(k, v, maxEntries = 50) |
A key/value table |
Check.instance(className?, ancestor?) |
An Instance of that class, optionally inside ancestor |
Check.vector3(maxMagnitude?) |
A Vector3 with finite components |
Check.cframe() |
A CFrame with finite components |
Check.enum(Enum.X) |
An EnumItem of that Enum |
Check.refine(v, predicate, reason?) |
A value v accepts that also passes predicate |
Check.any() |
Anything. Avoid this for client input |
Testing
tests/server/Network.spec.luau feeds stand-in players through the same internal entry points that remotes use. It covers malformed payloads, forged payloads, oversized payloads, rate limits, rejoining, authorization and handler errors.
The Play-mode integration test (tests/*/NetworkIntegration.*) acts as a hostile client against real remotes. The server then checks its own accept/reject counts.