@rbxts/scribe 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/NOTICE +21 -0
- package/README.md +100 -0
- package/Scribe-source-map.json +1 -0
- package/licenses/ProfileStore-Apache-2.0.txt +201 -0
- package/package.json +32 -0
- package/src/Client/DebugHook.luau +457 -0
- package/src/Client/init.luau +1607 -0
- package/src/Internal/Addons.luau +68 -0
- package/src/Internal/Big.luau +582 -0
- package/src/Internal/Budget.luau +377 -0
- package/src/Internal/Clock.luau +75 -0
- package/src/Internal/Config.luau +17 -0
- package/src/Internal/Conform.luau +400 -0
- package/src/Internal/Datatypes.luau +653 -0
- package/src/Internal/Defaults.luau +12 -0
- package/src/Internal/Derived.luau +428 -0
- package/src/Internal/Exchange.luau +556 -0
- package/src/Internal/ExchangeLeg.luau +1368 -0
- package/src/Internal/ExchangeVerdict.luau +179 -0
- package/src/Internal/Failure.luau +148 -0
- package/src/Internal/Health.luau +320 -0
- package/src/Internal/LeaderboardDiagnostics.luau +36 -0
- package/src/Internal/Log.luau +378 -0
- package/src/Internal/Marker.luau +76 -0
- package/src/Internal/Metrics.luau +152 -0
- package/src/Internal/Node.luau +3954 -0
- package/src/Internal/Profile.luau +69 -0
- package/src/Internal/Rng.luau +83 -0
- package/src/Internal/Sched.luau +56 -0
- package/src/Internal/Signal.luau +199 -0
- package/src/Internal/Store/ProfileStore.luau +3019 -0
- package/src/Internal/Store/init.luau +18 -0
- package/src/Internal/StudioCodec.luau +155 -0
- package/src/Internal/Template.luau +1848 -0
- package/src/Internal/Transport.luau +169 -0
- package/src/Internal/Util.luau +517 -0
- package/src/Internal/Version.luau +4 -0
- package/src/Internal/Wire.luau +1283 -0
- package/src/Server/Analytics.luau +223 -0
- package/src/Server/Commands.luau +728 -0
- package/src/Server/DebugHook.luau +1490 -0
- package/src/Server/Exchanges.luau +737 -0
- package/src/Server/Leaderboards.luau +2143 -0
- package/src/Server/Monetization.luau +3212 -0
- package/src/Server/Persistence.luau +3775 -0
- package/src/Server/Replication.luau +1253 -0
- package/src/Server/ServerStore.luau +81 -0
- package/src/Server/Timed.luau +579 -0
- package/src/Server/init.luau +672 -0
- package/src/Types.luau +480 -0
- package/src/init.luau +2231 -0
- package/types/api.d.ts +252 -0
- package/types/common.d.ts +355 -0
- package/types/index.d.ts +226 -0
- package/types/schema.d.ts +276 -0
|
@@ -0,0 +1,728 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Server-authoritative command RPC: named, validated, rate-limited client to
|
|
3
|
+
-- server calls over the buffer channel. Sender identity is always the player the
|
|
4
|
+
-- transport callback provided, never payload contents.
|
|
5
|
+
|
|
6
|
+
local Internal = script.Parent.Parent.Internal
|
|
7
|
+
local Wire = require(Internal.Wire)
|
|
8
|
+
local Log = require(Internal.Log)
|
|
9
|
+
local Metrics = require(Internal.Metrics)
|
|
10
|
+
local Marker = require(Internal.Marker)
|
|
11
|
+
local Clock = require(Internal.Clock)
|
|
12
|
+
local Util = require(Internal.Util)
|
|
13
|
+
|
|
14
|
+
local Commands = {}
|
|
15
|
+
|
|
16
|
+
local MAX_ARGS = Wire.MAX_COMMAND_ARGS
|
|
17
|
+
local MAX_RETURNS = 8
|
|
18
|
+
-- Nesting cap for an opt-in table-argument shape (see specMatches).
|
|
19
|
+
local MAX_SHAPE_DEPTH = 8
|
|
20
|
+
-- Declarator kinds meaningful for a command argument. The rest describe storage or
|
|
21
|
+
-- replication (Timed, ServerOnly, Shared, Session, Dynamic) or carry a value the wire
|
|
22
|
+
-- cannot represent (Datatype, Big), so accepting them would promise a check that fails.
|
|
23
|
+
local ARG_MARKERS: { [string]: boolean } = {
|
|
24
|
+
Int = true,
|
|
25
|
+
Number = true,
|
|
26
|
+
String = true,
|
|
27
|
+
Enum = true,
|
|
28
|
+
Flags = true,
|
|
29
|
+
Optional = true,
|
|
30
|
+
ArrayOf = true,
|
|
31
|
+
SetOf = true,
|
|
32
|
+
DictOf = true,
|
|
33
|
+
MapOf = true,
|
|
34
|
+
}
|
|
35
|
+
-- Rate-limited frames still cost a log line and an outbound reply each, so a flood is
|
|
36
|
+
-- throttled: one log per interval per player, and past a sustained-flood cutoff the
|
|
37
|
+
-- reply is dropped too. The count decays after a quiet window.
|
|
38
|
+
local RATE_LOG_INTERVAL = 1 -- seconds between COMMAND_RATE_LIMITED logs per player
|
|
39
|
+
local RATE_RESET_WINDOW = 10 -- seconds of no rate-limiting that resets the counter
|
|
40
|
+
-- Seconds between COMMAND_ERROR lines: log the first, count and report the rest.
|
|
41
|
+
local COMMAND_ERROR_LOG_INTERVAL = 5
|
|
42
|
+
local lastCommandErrorLog: number? = nil
|
|
43
|
+
local commandErrorsSinceLog = 0
|
|
44
|
+
|
|
45
|
+
local RATE_LIMIT_MAX = 256 -- sustained rate-limited frames before replies stop
|
|
46
|
+
|
|
47
|
+
local MAX_IDEMPOTENCY_KEY_BYTES = Wire.MAX_IDEMPOTENCY_KEY_BYTES
|
|
48
|
+
-- Live idempotency records held per player. The cache is the protection, so evicting an
|
|
49
|
+
-- unexpired record means a retry under that key runs the handler again. Bounded anyway:
|
|
50
|
+
-- unlike a Data.Purchase key this one is client-named, so without a ceiling a player at
|
|
51
|
+
-- the full CommandRateLimit mints records forever.
|
|
52
|
+
local MAX_IDEMPOTENT_RECORDS = 64
|
|
53
|
+
-- Duplicates parked on one in-flight call. Client-driven, so bounded.
|
|
54
|
+
local MAX_IDEMPOTENT_WAITERS = 32
|
|
55
|
+
|
|
56
|
+
type Handler = (player: Player, ...any) -> ...any
|
|
57
|
+
type Registered = {
|
|
58
|
+
Handler: Handler,
|
|
59
|
+
Args: { any }?, -- type strings and/or shape tables
|
|
60
|
+
Idempotent: boolean, -- requires a per-call key, and runs at most once per key
|
|
61
|
+
ActiveMetric: string,
|
|
62
|
+
DurationMetric: string,
|
|
63
|
+
ErrorMetric: string,
|
|
64
|
+
}
|
|
65
|
+
-- Open calls per name, across bundles: the gauge is one metric per name.
|
|
66
|
+
local activeByName: { [string]: number } = {}
|
|
67
|
+
-- One in-flight or settled call under an idempotency key.
|
|
68
|
+
type IdemRecord = {
|
|
69
|
+
CacheKey: string,
|
|
70
|
+
At: number, -- Clock.Monotonic() at creation; drives expiry and eviction order
|
|
71
|
+
Done: boolean,
|
|
72
|
+
Ok: boolean,
|
|
73
|
+
Reply: buffer?, -- the encoded reply, re-sent on a replay
|
|
74
|
+
Waiters: { number }, -- correlations of duplicates that arrived while in flight
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function Commands.new(ctx: any)
|
|
78
|
+
local self = {} :: any
|
|
79
|
+
local options = ctx.Options
|
|
80
|
+
local rateLimit: number = options.CommandRateLimit or 20
|
|
81
|
+
-- How long a settled idempotency record answers repeats. Derived rather than
|
|
82
|
+
-- configured: the window only has to outlast the client's own retry window, which
|
|
83
|
+
-- RequestTimeout defines. The floor keeps a short RequestTimeout from undercutting it.
|
|
84
|
+
local idempotencyTTL: number = math.max(120, (tonumber(options.RequestTimeout) or 10) * 4)
|
|
85
|
+
|
|
86
|
+
local registry: { [string]: Registered } = {}
|
|
87
|
+
-- The longest name any command is registered under, floored so an ordinary typo still
|
|
88
|
+
-- reaches the registry and answers `unknown-command` rather than being charged as
|
|
89
|
+
-- malformed. It bounds the one attacker-sized read the rate limit does not cover: the
|
|
90
|
+
-- name is read above takeToken, so it runs at the raw frame rate.
|
|
91
|
+
local COMMAND_NAME_FLOOR = 64
|
|
92
|
+
local maxNameBytes = COMMAND_NAME_FLOOR
|
|
93
|
+
|
|
94
|
+
local function register(name: string, specOrHandler: any, handler: Handler?)
|
|
95
|
+
if type(name) ~= "string" or name == "" then
|
|
96
|
+
error("Scribe: command name must be a non-empty string", 2)
|
|
97
|
+
end
|
|
98
|
+
if registry[name] then
|
|
99
|
+
error(`Scribe: command "{name}" is already registered`, 2)
|
|
100
|
+
end
|
|
101
|
+
local spec: { Args: { any }?, Idempotent: boolean? }? = nil
|
|
102
|
+
local fn: Handler
|
|
103
|
+
if handler ~= nil then
|
|
104
|
+
spec = specOrHandler
|
|
105
|
+
fn = handler
|
|
106
|
+
else
|
|
107
|
+
fn = specOrHandler
|
|
108
|
+
end
|
|
109
|
+
if type(fn) ~= "function" then
|
|
110
|
+
error(`Scribe: command "{name}" handler must be a function`, 2)
|
|
111
|
+
end
|
|
112
|
+
-- Rejected at register time: a truthy-but-not-boolean value reads as opted in on
|
|
113
|
+
-- one line and out on the `== true` below, showing up as commands running twice.
|
|
114
|
+
local idempotent = if spec then spec.Idempotent else nil
|
|
115
|
+
if idempotent ~= nil and type(idempotent) ~= "boolean" then
|
|
116
|
+
error(`Scribe: command "{name}" Idempotent must be a boolean`, 2)
|
|
117
|
+
end
|
|
118
|
+
local args = if spec then spec.Args else nil
|
|
119
|
+
if args ~= nil then
|
|
120
|
+
if type(args) ~= "table" then
|
|
121
|
+
error(`Scribe: command "{name}" Args must be an array of type strings or shapes`, 2)
|
|
122
|
+
end
|
|
123
|
+
-- Reject a malformed spec at register time: a spec that never matches turns
|
|
124
|
+
-- every request into "bad-args", which reads as a client bug.
|
|
125
|
+
local function checkSpec(entry: any, where: string, depth: number)
|
|
126
|
+
if type(entry) == "string" then
|
|
127
|
+
return
|
|
128
|
+
end
|
|
129
|
+
if type(entry) ~= "table" then
|
|
130
|
+
error(
|
|
131
|
+
`Scribe: command "{name}" {where} must be a type string, a Scribe declarator, or a shape table`,
|
|
132
|
+
3
|
|
133
|
+
)
|
|
134
|
+
end
|
|
135
|
+
if depth > MAX_SHAPE_DEPTH then
|
|
136
|
+
error(`Scribe: command "{name}" {where} nests deeper than {MAX_SHAPE_DEPTH}`, 3)
|
|
137
|
+
end
|
|
138
|
+
local kind, default, meta = Marker.inspect(entry)
|
|
139
|
+
if kind ~= nil then
|
|
140
|
+
if not ARG_MARKERS[kind] then
|
|
141
|
+
-- Name the kind: without it the recursion walks the marker's internals
|
|
142
|
+
-- and reports "Args[1].Meta.Min", leaking Scribe's own structure.
|
|
143
|
+
error(
|
|
144
|
+
`Scribe: command "{name}" {where} is a Scribe.{kind}, which describes stored data rather `
|
|
145
|
+
.. `than a wire argument. Command arguments accept `
|
|
146
|
+
.. `Int/Number/String/Enum/Flags/Optional/ArrayOf/SetOf/DictOf/MapOf.`,
|
|
147
|
+
3
|
|
148
|
+
)
|
|
149
|
+
end
|
|
150
|
+
if kind == "Optional" then
|
|
151
|
+
checkSpec(default, `{where} (Optional inner)`, depth + 1)
|
|
152
|
+
elseif meta ~= nil and meta.Element ~= nil then
|
|
153
|
+
checkSpec(meta.Element, `{where} (element)`, depth + 1)
|
|
154
|
+
end
|
|
155
|
+
return
|
|
156
|
+
end
|
|
157
|
+
if entry[1] ~= nil then
|
|
158
|
+
checkSpec(entry[1], `{where}[1]`, depth + 1)
|
|
159
|
+
for key in entry do
|
|
160
|
+
if key ~= 1 then
|
|
161
|
+
error(
|
|
162
|
+
`Scribe: command "{name}" {where} mixes an array element spec at [1] with the key `
|
|
163
|
+
.. `"{tostring(key)}"; a shape is either an array or a set of named fields`,
|
|
164
|
+
3
|
|
165
|
+
)
|
|
166
|
+
end
|
|
167
|
+
end
|
|
168
|
+
return
|
|
169
|
+
end
|
|
170
|
+
for key, field in entry do
|
|
171
|
+
checkSpec(field, `{where}.{tostring(key)}`, depth + 1)
|
|
172
|
+
end
|
|
173
|
+
end
|
|
174
|
+
-- A gap leaves that position decoded but never type-checked: the arity check reads
|
|
175
|
+
-- `#` while the loops below skip what is missing. "any" accepts anything instead.
|
|
176
|
+
local gap = Util.firstGap(args)
|
|
177
|
+
if gap ~= nil then
|
|
178
|
+
error(
|
|
179
|
+
`Scribe: command "{name}" Args[{gap}] is nil, which would leave that argument `
|
|
180
|
+
.. `unvalidated; use "any" to accept anything at that position`,
|
|
181
|
+
2
|
|
182
|
+
)
|
|
183
|
+
end
|
|
184
|
+
for i, entry in args do
|
|
185
|
+
checkSpec(entry, `Args[{i}]`, 0)
|
|
186
|
+
end
|
|
187
|
+
end
|
|
188
|
+
maxNameBytes = math.max(maxNameBytes, #name)
|
|
189
|
+
registry[name] = {
|
|
190
|
+
Handler = fn,
|
|
191
|
+
Args = args,
|
|
192
|
+
Idempotent = idempotent == true,
|
|
193
|
+
-- Built once; names are bounded by registration.
|
|
194
|
+
ActiveMetric = `CommandActive:{name}`,
|
|
195
|
+
DurationMetric = `CommandDuration:{name}`,
|
|
196
|
+
ErrorMetric = `CommandErrors:{name}`,
|
|
197
|
+
}
|
|
198
|
+
end
|
|
199
|
+
|
|
200
|
+
function self.Register(name: string, specOrHandler: any, handler: Handler?)
|
|
201
|
+
if name == Wire.PURCHASE_PROMPT_COMMAND then
|
|
202
|
+
error(`Scribe: command "{name}" is reserved for purchase prompts`, 2)
|
|
203
|
+
end
|
|
204
|
+
register(name, specOrHandler, handler)
|
|
205
|
+
end
|
|
206
|
+
|
|
207
|
+
-- An ordinary rate-limited, typed command, bound to the sender supplied by the
|
|
208
|
+
-- transport. Only its registration is internal; it never grants a purchase.
|
|
209
|
+
register(Wire.PURCHASE_PROMPT_COMMAND, { Args = { "string" } }, function(player: Player, name: string)
|
|
210
|
+
return ctx.Monetization.PromptPurchase(player, name)
|
|
211
|
+
end)
|
|
212
|
+
|
|
213
|
+
local function encodeReply(correlation: number, ok: boolean, results: { any }): buffer
|
|
214
|
+
local w = Wire.NewWriter(64)
|
|
215
|
+
Wire.U8(w, Wire.Frames.CommandReply)
|
|
216
|
+
Wire.U32(w, correlation)
|
|
217
|
+
Wire.U8(w, if ok then 1 else 0)
|
|
218
|
+
-- results.n is the true count and survives an embedded nil that `#` stops short
|
|
219
|
+
-- at; fall back to `#` for the plain-array callers, which have no holes.
|
|
220
|
+
local n = math.min((results :: any).n or #results, MAX_RETURNS)
|
|
221
|
+
Wire.U8(w, n)
|
|
222
|
+
for i = 1, n do
|
|
223
|
+
Wire.EncodeGeneric(w, results[i])
|
|
224
|
+
end
|
|
225
|
+
return Wire.Finish(w)
|
|
226
|
+
end
|
|
227
|
+
|
|
228
|
+
-- Send one reply frame; returns the bytes sent.
|
|
229
|
+
local function reply(entry: any, correlation: number, ok: boolean, results: { any }): buffer
|
|
230
|
+
-- encodeReply clamps to MAX_RETURNS, and the caller just sees trailing nils, so
|
|
231
|
+
-- say so. Only meaningful on success; failure replies are single-value.
|
|
232
|
+
local resultCount = (results :: any).n or #results
|
|
233
|
+
if ok and resultCount > MAX_RETURNS then
|
|
234
|
+
Log.Warn(
|
|
235
|
+
"Commands",
|
|
236
|
+
"COMMAND_REPLY_TRUNCATED",
|
|
237
|
+
`handler returned {resultCount} values; only the first {MAX_RETURNS} are sent`,
|
|
238
|
+
{ Player = entry.Player }
|
|
239
|
+
)
|
|
240
|
+
end
|
|
241
|
+
local encoded, bytes = pcall(encodeReply, correlation, ok, results)
|
|
242
|
+
if not encoded then
|
|
243
|
+
-- The handler returned something the wire can't carry. Fail cleanly instead
|
|
244
|
+
-- of stranding the client until its timeout.
|
|
245
|
+
Log.Warn("Commands", "COMMAND_REPLY_ENCODE_FAIL", tostring(bytes), { Player = entry.Player })
|
|
246
|
+
bytes = encodeReply(correlation, false, { "reply-encode-failed" })
|
|
247
|
+
end
|
|
248
|
+
ctx.Replication.SendTo(entry, bytes)
|
|
249
|
+
return bytes
|
|
250
|
+
end
|
|
251
|
+
|
|
252
|
+
-- A copy of a settled reply with the header's correlation overwritten.
|
|
253
|
+
local function replay(entry: any, correlation: number, bytes: buffer)
|
|
254
|
+
local copy = buffer.create(buffer.len(bytes))
|
|
255
|
+
buffer.copy(copy, 0, bytes)
|
|
256
|
+
buffer.writeu32(copy, 1, correlation)
|
|
257
|
+
ctx.Replication.SendTo(entry, copy)
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
-- Idempotency cache --------------------------------------------------------
|
|
261
|
+
--
|
|
262
|
+
-- Per entry, in memory, deliberately not the persisted claim Data.Purchase takes
|
|
263
|
+
-- through Timed.Claim: a command key is client-named, so persisting it lets a player
|
|
264
|
+
-- push their own profile past the DataStore ceiling and fail every save. Session scope
|
|
265
|
+
-- is honest anyway: the correlation id, parked thread and RequestTimeout are all
|
|
266
|
+
-- session-lived, so the cache dies with the session. The cached reply has nowhere
|
|
267
|
+
-- durable to go either: a handler may return values the wire carries and a DataStore
|
|
268
|
+
-- refuses.
|
|
269
|
+
local function idemStore(entry: any): { [string]: IdemRecord }
|
|
270
|
+
local store = entry.CommandIdem
|
|
271
|
+
if not store then
|
|
272
|
+
store = {}
|
|
273
|
+
entry.CommandIdem = store
|
|
274
|
+
end
|
|
275
|
+
return store
|
|
276
|
+
end
|
|
277
|
+
|
|
278
|
+
-- Finish an in-flight record: answer every duplicate parked on it, and decide
|
|
279
|
+
-- whether it survives to answer later retries.
|
|
280
|
+
local function settleIdempotent(entry: any, record: IdemRecord?, ok: boolean, bytes: buffer)
|
|
281
|
+
if record == nil then
|
|
282
|
+
return
|
|
283
|
+
end
|
|
284
|
+
local waiters = record.Waiters
|
|
285
|
+
record.Waiters = {}
|
|
286
|
+
record.Done = true
|
|
287
|
+
record.Ok = ok
|
|
288
|
+
record.Reply = bytes
|
|
289
|
+
if not ok then
|
|
290
|
+
-- Dropped before the parked duplicates are answered. A handler that threw did
|
|
291
|
+
-- not happen, so the key stays retryable, and a synchronous transport can
|
|
292
|
+
-- re-enter this path mid-replies and answer that retry from the cache.
|
|
293
|
+
local store = entry.CommandIdem
|
|
294
|
+
if store then
|
|
295
|
+
store[record.CacheKey] = nil
|
|
296
|
+
end
|
|
297
|
+
end
|
|
298
|
+
for _, correlation in waiters do
|
|
299
|
+
replay(entry, correlation, bytes)
|
|
300
|
+
end
|
|
301
|
+
end
|
|
302
|
+
|
|
303
|
+
local function takeToken(entry: any): boolean
|
|
304
|
+
local now = Clock.Monotonic()
|
|
305
|
+
local elapsed = now - entry.RateLast
|
|
306
|
+
entry.RateLast = now
|
|
307
|
+
entry.RateTokens = math.min(rateLimit, entry.RateTokens + elapsed * rateLimit)
|
|
308
|
+
if entry.RateTokens >= 1 then
|
|
309
|
+
entry.RateTokens -= 1
|
|
310
|
+
return true
|
|
311
|
+
end
|
|
312
|
+
return false
|
|
313
|
+
end
|
|
314
|
+
|
|
315
|
+
-- Warn at most once per interval per player per code. These fire on client input under
|
|
316
|
+
-- the rate limit, so unthrottled an exploiter could evict the whole diagnostic ring.
|
|
317
|
+
local function throttledWarn(entry: any, code: any, message: string, context: { [string]: any })
|
|
318
|
+
local now = Clock.Monotonic()
|
|
319
|
+
local seen = entry.LastCommandWarnAt
|
|
320
|
+
if not seen then
|
|
321
|
+
seen = {}
|
|
322
|
+
entry.LastCommandWarnAt = seen
|
|
323
|
+
end
|
|
324
|
+
if now - (seen[code] or -math.huge) < RATE_LOG_INTERVAL then
|
|
325
|
+
return
|
|
326
|
+
end
|
|
327
|
+
seen[code] = now
|
|
328
|
+
Log.Warn("Commands", code, message, context)
|
|
329
|
+
end
|
|
330
|
+
|
|
331
|
+
-- Does one argument match its spec? A spec is one of three things:
|
|
332
|
+
--
|
|
333
|
+
-- "string", "number?", "any" a type string
|
|
334
|
+
-- Scribe.Int(0, { Min = 0, Max = 99 }) a declarator, with its constraints
|
|
335
|
+
-- { Id = "string", Qty = "number?" } a shape, nestable, mixable with both
|
|
336
|
+
--
|
|
337
|
+
-- Declarators are accepted so their constraints come along (Min/Max, MaxLength, Enum
|
|
338
|
+
-- members, MaxItems/MaxKeys). All opt-in: a bare "table" stays as permissive as typeof.
|
|
339
|
+
local markerMatches: (string, any, Marker.Meta?, any, number) -> boolean
|
|
340
|
+
local function specMatches(expected: any, value: any, depth: number): boolean
|
|
341
|
+
if type(expected) == "string" then
|
|
342
|
+
local optional = string.sub(expected, -1) == "?"
|
|
343
|
+
local base = if optional then string.sub(expected, 1, -2) else expected
|
|
344
|
+
if value == nil then
|
|
345
|
+
return optional
|
|
346
|
+
end
|
|
347
|
+
-- No number Scribe can store is non-finite: every write refuses NaN and
|
|
348
|
+
-- infinity, and markerMatches already refuses them for Int and Number. A bare
|
|
349
|
+
-- "number" would otherwise hand one to the handler, where typeof says number
|
|
350
|
+
-- and every comparison against NaN is false, so both arms of a guard are
|
|
351
|
+
-- skipped. Refused whatever the spec says, "any" included.
|
|
352
|
+
if type(value) == "number" and (value ~= value or value == math.huge or value == -math.huge) then
|
|
353
|
+
return false
|
|
354
|
+
end
|
|
355
|
+
if base == "any" then
|
|
356
|
+
return true
|
|
357
|
+
end
|
|
358
|
+
return typeof(value) == base
|
|
359
|
+
end
|
|
360
|
+
if type(expected) ~= "table" then
|
|
361
|
+
return false -- unreachable: Register rejects any other spec form
|
|
362
|
+
end
|
|
363
|
+
local kind, default, meta = Marker.inspect(expected)
|
|
364
|
+
if kind ~= nil then
|
|
365
|
+
return markerMatches(kind, default, meta, value, depth)
|
|
366
|
+
end
|
|
367
|
+
-- A shape is always required: a command that wants an optional table declares
|
|
368
|
+
-- "table?" and validates the contents itself.
|
|
369
|
+
if type(value) ~= "table" or depth > MAX_SHAPE_DEPTH then
|
|
370
|
+
return false
|
|
371
|
+
end
|
|
372
|
+
local elementSpec = expected[1]
|
|
373
|
+
if elementSpec ~= nil then
|
|
374
|
+
-- Array form: every element matches and no extra keys hide alongside them.
|
|
375
|
+
for key, item in value do
|
|
376
|
+
if type(key) ~= "number" or not specMatches(elementSpec, item, depth + 1) then
|
|
377
|
+
return false
|
|
378
|
+
end
|
|
379
|
+
end
|
|
380
|
+
return true
|
|
381
|
+
end
|
|
382
|
+
for key, fieldSpec in expected do
|
|
383
|
+
if not specMatches(fieldSpec, value[key], depth + 1) then
|
|
384
|
+
return false
|
|
385
|
+
end
|
|
386
|
+
end
|
|
387
|
+
-- Reject unknown keys: an undeclared field is how an unvalidated value reaches
|
|
388
|
+
-- game logic.
|
|
389
|
+
for key in value do
|
|
390
|
+
if expected[key] == nil then
|
|
391
|
+
return false
|
|
392
|
+
end
|
|
393
|
+
end
|
|
394
|
+
return true
|
|
395
|
+
end
|
|
396
|
+
|
|
397
|
+
-- Declarator constraints, checked against a value that arrived over the wire.
|
|
398
|
+
-- A rejection, never a clamp: a command argument is the client's claim about what
|
|
399
|
+
-- it wants, and clamping it to something legal turns "buy 999999" into "buy 99".
|
|
400
|
+
function markerMatches(kind: string, default: any, given: Marker.Meta?, value: any, depth: number): boolean
|
|
401
|
+
local meta: Marker.Meta = given or {}
|
|
402
|
+
if kind == "Optional" then
|
|
403
|
+
-- Scribe.Optional wraps its inner shape in the marker's Default, not Meta.
|
|
404
|
+
return value == nil or specMatches(default, value, depth)
|
|
405
|
+
end
|
|
406
|
+
if kind == "Int" or kind == "Number" then
|
|
407
|
+
if type(value) ~= "number" or value ~= value or value == math.huge or value == -math.huge then
|
|
408
|
+
return false
|
|
409
|
+
end
|
|
410
|
+
if kind == "Int" and value % 1 ~= 0 then
|
|
411
|
+
return false
|
|
412
|
+
end
|
|
413
|
+
if meta.Min ~= nil and value < meta.Min then
|
|
414
|
+
return false
|
|
415
|
+
end
|
|
416
|
+
if meta.Max ~= nil and value > meta.Max then
|
|
417
|
+
return false
|
|
418
|
+
end
|
|
419
|
+
return true
|
|
420
|
+
end
|
|
421
|
+
if kind == "String" then
|
|
422
|
+
if type(value) ~= "string" or not utf8.len(value) then
|
|
423
|
+
return false -- invalid UTF-8 cannot be persisted, so refuse it at the door
|
|
424
|
+
end
|
|
425
|
+
return meta.MaxLength == nil or #value <= meta.MaxLength
|
|
426
|
+
end
|
|
427
|
+
if kind == "Enum" then
|
|
428
|
+
return type(value) == "string" and table.find(meta.Members or {}, value) ~= nil
|
|
429
|
+
end
|
|
430
|
+
if kind == "Flags" then
|
|
431
|
+
if type(value) ~= "table" then
|
|
432
|
+
return false
|
|
433
|
+
end
|
|
434
|
+
local count = 0
|
|
435
|
+
for key, member in value do
|
|
436
|
+
if type(key) ~= "number" or table.find(meta.Members or {}, member) == nil then
|
|
437
|
+
return false
|
|
438
|
+
end
|
|
439
|
+
count += 1
|
|
440
|
+
end
|
|
441
|
+
return count == #value
|
|
442
|
+
end
|
|
443
|
+
if kind == "ArrayOf" or kind == "SetOf" then
|
|
444
|
+
if type(value) ~= "table" then
|
|
445
|
+
return false
|
|
446
|
+
end
|
|
447
|
+
local count = 0
|
|
448
|
+
for key, item in value do
|
|
449
|
+
if type(key) ~= "number" or not specMatches(meta.Element, item, depth + 1) then
|
|
450
|
+
return false
|
|
451
|
+
end
|
|
452
|
+
count += 1
|
|
453
|
+
end
|
|
454
|
+
if count ~= #value then
|
|
455
|
+
return false -- holes or string keys hiding in an array
|
|
456
|
+
end
|
|
457
|
+
return meta.MaxItems == nil or count <= meta.MaxItems
|
|
458
|
+
end
|
|
459
|
+
if kind == "DictOf" or kind == "MapOf" then
|
|
460
|
+
if type(value) ~= "table" then
|
|
461
|
+
return false
|
|
462
|
+
end
|
|
463
|
+
local wantInteger = meta.KeyType == "integer"
|
|
464
|
+
local count = 0
|
|
465
|
+
for key, item in value do
|
|
466
|
+
if wantInteger then
|
|
467
|
+
if type(key) ~= "number" or key % 1 ~= 0 then
|
|
468
|
+
return false
|
|
469
|
+
end
|
|
470
|
+
else
|
|
471
|
+
if type(key) ~= "string" then
|
|
472
|
+
return false
|
|
473
|
+
end
|
|
474
|
+
if meta.MaxKeyLength ~= nil and #key > meta.MaxKeyLength then
|
|
475
|
+
return false
|
|
476
|
+
end
|
|
477
|
+
end
|
|
478
|
+
if not specMatches(meta.Element, item, depth + 1) then
|
|
479
|
+
return false
|
|
480
|
+
end
|
|
481
|
+
count += 1
|
|
482
|
+
end
|
|
483
|
+
return meta.MaxKeys == nil or count <= meta.MaxKeys
|
|
484
|
+
end
|
|
485
|
+
return false -- unreachable: Register rejects every other kind
|
|
486
|
+
end
|
|
487
|
+
|
|
488
|
+
local function typeMatches(expected: any, value: any): boolean
|
|
489
|
+
return specMatches(expected, value, 0)
|
|
490
|
+
end
|
|
491
|
+
|
|
492
|
+
-- Decode and dispatch a Command frame (called from Replication's inbound
|
|
493
|
+
-- dispatcher; decode errors propagate to its pcall).
|
|
494
|
+
function self.HandleFrame(entry: any, reader: Wire.Reader)
|
|
495
|
+
local correlation = Wire.RU32(reader)
|
|
496
|
+
-- Bounded from the length prefix, so an over-long name costs the varint rather than
|
|
497
|
+
-- the allocation; it could not have matched a registered command anyway.
|
|
498
|
+
local name = Wire.RStrBounded(reader, maxNameBytes)
|
|
499
|
+
local argc = Wire.RU8(reader)
|
|
500
|
+
if argc > MAX_ARGS then
|
|
501
|
+
error("too many command arguments")
|
|
502
|
+
end
|
|
503
|
+
|
|
504
|
+
Metrics.Add("CommandsReceived")
|
|
505
|
+
|
|
506
|
+
-- The token check stays above the argument decode: arguments are attacker-sized and
|
|
507
|
+
-- the decode is where the CPU goes, and these frames are valid, so the
|
|
508
|
+
-- malformed-frame budget never catches them. The header alone answers the rejection.
|
|
509
|
+
if not takeToken(entry) then
|
|
510
|
+
Metrics.Add("CommandsRateLimited")
|
|
511
|
+
local now = Clock.Monotonic()
|
|
512
|
+
-- Decay first, so a rare legitimate burst never creeps toward the cutoff.
|
|
513
|
+
if now - (entry.LastRateLimitAt or -math.huge) > RATE_RESET_WINDOW then
|
|
514
|
+
entry.RateLimitedCount = 0
|
|
515
|
+
end
|
|
516
|
+
entry.LastRateLimitAt = now
|
|
517
|
+
entry.RateLimitedCount = (entry.RateLimitedCount or 0) + 1
|
|
518
|
+
-- Throttle the log: this is the one command path an exploiter drives unbounded.
|
|
519
|
+
if now - (entry.LastRateLimitLog or -math.huge) >= RATE_LOG_INTERVAL then
|
|
520
|
+
entry.LastRateLimitLog = now
|
|
521
|
+
Log.Warn("Commands", "COMMAND_RATE_LIMITED", `player exceeded {rateLimit}/s`, {
|
|
522
|
+
Player = entry.Player,
|
|
523
|
+
Count = entry.RateLimitedCount,
|
|
524
|
+
})
|
|
525
|
+
end
|
|
526
|
+
-- Keep replying up to the cutoff so a client that briefly overruns is not
|
|
527
|
+
-- stranded until its request timeout; past it each reply is only cost.
|
|
528
|
+
if entry.RateLimitedCount < RATE_LIMIT_MAX then
|
|
529
|
+
reply(entry, correlation, false, { "rate-limited" })
|
|
530
|
+
end
|
|
531
|
+
return
|
|
532
|
+
end
|
|
533
|
+
|
|
534
|
+
-- Above the registry lookup, so a not-Ready session answers "not-ready" for every
|
|
535
|
+
-- name. Below it, an unauthenticated client could enumerate the whole command
|
|
536
|
+
-- surface by diffing "unknown-command" against "not-ready". Nothing real is lost:
|
|
537
|
+
-- Client.Request waits for Init, so a genuine client cannot send in this window.
|
|
538
|
+
if entry.State ~= "Ready" then
|
|
539
|
+
reply(entry, correlation, false, { "not-ready" })
|
|
540
|
+
return
|
|
541
|
+
end
|
|
542
|
+
|
|
543
|
+
local registered = registry[name]
|
|
544
|
+
if not registered then
|
|
545
|
+
Metrics.Add("CommandsRejected")
|
|
546
|
+
throttledWarn(entry, "COMMAND_UNKNOWN", `unknown command "{name}"`, { Player = entry.Player })
|
|
547
|
+
reply(entry, correlation, false, { "unknown-command" })
|
|
548
|
+
return
|
|
549
|
+
end
|
|
550
|
+
|
|
551
|
+
-- The arity check needs only the header, so it runs before the decode and
|
|
552
|
+
-- rejects an over-long call without paying for it.
|
|
553
|
+
if registered.Args and argc > #registered.Args then
|
|
554
|
+
Metrics.Add("CommandsRejected")
|
|
555
|
+
reply(entry, correlation, false, { "bad-args" })
|
|
556
|
+
return
|
|
557
|
+
end
|
|
558
|
+
|
|
559
|
+
-- The idempotency key sits between the header and the arguments so an unusable
|
|
560
|
+
-- one is settled before anything attacker-sized is decoded. Empty means the
|
|
561
|
+
-- caller sent none, so Request and RequestOnce share one frame layout.
|
|
562
|
+
local idemKey = Wire.RStr(reader)
|
|
563
|
+
local hasKey = idemKey ~= ""
|
|
564
|
+
-- Refused rather than downgraded in both directions: a key sent to a command that
|
|
565
|
+
-- does not honour it promises protection that does not exist, and a keyless call to
|
|
566
|
+
-- one that does is the same mistake reversed. The length is checked here rather
|
|
567
|
+
-- than at the read: this cap is about what may become a retained table key.
|
|
568
|
+
if
|
|
569
|
+
hasKey ~= registered.Idempotent
|
|
570
|
+
or (hasKey and (#idemKey > MAX_IDEMPOTENCY_KEY_BYTES or utf8.len(idemKey) == nil))
|
|
571
|
+
then
|
|
572
|
+
Metrics.Add("CommandsRejected")
|
|
573
|
+
throttledWarn(
|
|
574
|
+
entry,
|
|
575
|
+
"COMMAND_BAD_IDEMPOTENCY_KEY",
|
|
576
|
+
if registered.Idempotent
|
|
577
|
+
then `"{name}" requires an idempotency key (call it with Client.RequestOnce)`
|
|
578
|
+
else `"{name}" is not registered Idempotent, so it does not accept an idempotency key`,
|
|
579
|
+
{ Player = entry.Player }
|
|
580
|
+
)
|
|
581
|
+
reply(entry, correlation, false, { "bad-idempotency-key" })
|
|
582
|
+
return
|
|
583
|
+
end
|
|
584
|
+
|
|
585
|
+
-- Decode last: every rejection above is answered from the fixed-cost header
|
|
586
|
+
-- alone, so only a frame that cleared all of them costs a decode.
|
|
587
|
+
local args = table.create(argc)
|
|
588
|
+
for i = 1, argc do
|
|
589
|
+
args[i] = Wire.DecodeGeneric(reader)
|
|
590
|
+
end
|
|
591
|
+
|
|
592
|
+
-- Shape rejection before the handler runs; semantic validation is the handler's job.
|
|
593
|
+
if registered.Args then
|
|
594
|
+
for i, expected in registered.Args do
|
|
595
|
+
if not typeMatches(expected, args[i]) then
|
|
596
|
+
Metrics.Add("CommandsRejected")
|
|
597
|
+
throttledWarn(entry, "COMMAND_BAD_ARGS", `argument {i} of "{name}" is not {expected}`, {
|
|
598
|
+
Player = entry.Player,
|
|
599
|
+
})
|
|
600
|
+
reply(entry, correlation, false, { "bad-args" })
|
|
601
|
+
return
|
|
602
|
+
end
|
|
603
|
+
end
|
|
604
|
+
end
|
|
605
|
+
|
|
606
|
+
-- Claimed before the handler runs, not after. A handler may yield, so two identical
|
|
607
|
+
-- requests can be in flight at once, and a check after the call would let concurrent
|
|
608
|
+
-- duplicates both execute. Parking one on the record covers both shapes.
|
|
609
|
+
local record: IdemRecord? = nil
|
|
610
|
+
if registered.Idempotent then
|
|
611
|
+
local store = idemStore(entry)
|
|
612
|
+
local now = Clock.Monotonic()
|
|
613
|
+
-- Namespaced by command: two commands sharing a key are two operations, so
|
|
614
|
+
-- replaying one's reply for the other would be a wrong answer. \0 is the
|
|
615
|
+
-- cheapest unambiguous separator and cannot occur in a registered name.
|
|
616
|
+
local cacheKey = `{name}\0{idemKey}`
|
|
617
|
+
local existing = store[cacheKey]
|
|
618
|
+
if existing ~= nil and existing.Done and now - existing.At > idempotencyTTL then
|
|
619
|
+
store[cacheKey] = nil
|
|
620
|
+
existing = nil
|
|
621
|
+
end
|
|
622
|
+
if existing ~= nil then
|
|
623
|
+
if existing.Done then
|
|
624
|
+
Metrics.Add("CommandsDeduped")
|
|
625
|
+
replay(entry, correlation, existing.Reply :: buffer)
|
|
626
|
+
elseif #existing.Waiters < MAX_IDEMPOTENT_WAITERS then
|
|
627
|
+
-- Still running, so park this correlation on it; settleIdempotent
|
|
628
|
+
-- answers every duplicate when the handler returns.
|
|
629
|
+
Metrics.Add("CommandsDeduped")
|
|
630
|
+
table.insert(existing.Waiters, correlation)
|
|
631
|
+
else
|
|
632
|
+
Metrics.Add("CommandsRejected")
|
|
633
|
+
reply(entry, correlation, false, { "rate-limited" })
|
|
634
|
+
end
|
|
635
|
+
return
|
|
636
|
+
end
|
|
637
|
+
|
|
638
|
+
-- Sweep the settled-and-expired and measure what is left, in one pass.
|
|
639
|
+
-- In-flight records are never swept or evicted: dropping one would strand
|
|
640
|
+
-- the duplicates parked on it with no reply at all.
|
|
641
|
+
local live = 0
|
|
642
|
+
local oldestKey: string? = nil
|
|
643
|
+
local oldestAt = math.huge
|
|
644
|
+
for key, held in store do
|
|
645
|
+
if held.Done and now - held.At > idempotencyTTL then
|
|
646
|
+
store[key] = nil
|
|
647
|
+
else
|
|
648
|
+
live += 1
|
|
649
|
+
if held.Done and held.At < oldestAt then
|
|
650
|
+
oldestAt, oldestKey = held.At, key
|
|
651
|
+
end
|
|
652
|
+
end
|
|
653
|
+
end
|
|
654
|
+
if live >= MAX_IDEMPOTENT_RECORDS then
|
|
655
|
+
if oldestKey == nil then
|
|
656
|
+
-- Every record is in flight, so nothing is safe to drop. It takes a
|
|
657
|
+
-- client deliberately holding that many handlers open.
|
|
658
|
+
Metrics.Add("CommandsRejected")
|
|
659
|
+
throttledWarn(
|
|
660
|
+
entry,
|
|
661
|
+
"COMMAND_IDEM_SATURATED",
|
|
662
|
+
`{MAX_IDEMPOTENT_RECORDS} idempotent commands are in flight for this player; refusing more`,
|
|
663
|
+
{ Player = entry.Player }
|
|
664
|
+
)
|
|
665
|
+
reply(entry, correlation, false, { "rate-limited" })
|
|
666
|
+
return
|
|
667
|
+
end
|
|
668
|
+
-- Evicting an unexpired record is the one thing this cache exists to
|
|
669
|
+
-- prevent, so it is said out loud.
|
|
670
|
+
store[oldestKey] = nil
|
|
671
|
+
Metrics.Add("CommandIdemEvicted")
|
|
672
|
+
throttledWarn(
|
|
673
|
+
entry,
|
|
674
|
+
"COMMAND_IDEM_EVICTED",
|
|
675
|
+
`dropped an unexpired idempotency record to stay under {MAX_IDEMPOTENT_RECORDS} per player; `
|
|
676
|
+
.. "a retry under that key would run the handler again",
|
|
677
|
+
{ Player = entry.Player }
|
|
678
|
+
)
|
|
679
|
+
end
|
|
680
|
+
|
|
681
|
+
record =
|
|
682
|
+
{ CacheKey = cacheKey, At = now, Done = false, Ok = false, Reply = nil, Waiters = {} } :: IdemRecord
|
|
683
|
+
store[cacheKey] = record
|
|
684
|
+
end
|
|
685
|
+
|
|
686
|
+
local results: { any } = {}
|
|
687
|
+
local active = (activeByName[name] or 0) + 1
|
|
688
|
+
activeByName[name] = active
|
|
689
|
+
Metrics.Set(registered.ActiveMetric, active)
|
|
690
|
+
local startedAt = Clock.Monotonic()
|
|
691
|
+
local ok, err = xpcall(function()
|
|
692
|
+
results = table.pack(registered.Handler(entry.Player, table.unpack(args, 1, argc))) :: any
|
|
693
|
+
end, function(e)
|
|
694
|
+
return debug.traceback(tostring(e), 2)
|
|
695
|
+
end)
|
|
696
|
+
-- Elapsed, awaits included.
|
|
697
|
+
Metrics.Observe(registered.DurationMetric, Clock.Monotonic() - startedAt)
|
|
698
|
+
active = activeByName[name] - 1
|
|
699
|
+
activeByName[name] = active
|
|
700
|
+
Metrics.Set(registered.ActiveMetric, active)
|
|
701
|
+
if not ok then
|
|
702
|
+
Metrics.Add("CommandErrors")
|
|
703
|
+
Metrics.Add(registered.ErrorMetric)
|
|
704
|
+
-- Throttled: a handler that throws on a given input is a bug the player can
|
|
705
|
+
-- replay at their full command rate, and each entry costs a JSONEncode, a
|
|
706
|
+
-- console write and a Sched.Spawn per sink. The metric above is unthrottled.
|
|
707
|
+
local nowMono = Clock.Monotonic()
|
|
708
|
+
commandErrorsSinceLog += 1
|
|
709
|
+
if lastCommandErrorLog == nil or nowMono - lastCommandErrorLog >= COMMAND_ERROR_LOG_INTERVAL then
|
|
710
|
+
local suppressed = commandErrorsSinceLog - 1
|
|
711
|
+
lastCommandErrorLog = nowMono
|
|
712
|
+
commandErrorsSinceLog = 0
|
|
713
|
+
Log.Error("Commands", "COMMAND_ERROR", `command "{name}" handler threw: {err}`, {
|
|
714
|
+
Player = entry.Player,
|
|
715
|
+
Suppressed = if suppressed > 0 then suppressed else nil,
|
|
716
|
+
})
|
|
717
|
+
end
|
|
718
|
+
settleIdempotent(entry, record, false, reply(entry, correlation, false, { "error" }))
|
|
719
|
+
return
|
|
720
|
+
end
|
|
721
|
+
Metrics.Add("CommandsHandled")
|
|
722
|
+
settleIdempotent(entry, record, true, reply(entry, correlation, true, results))
|
|
723
|
+
end
|
|
724
|
+
|
|
725
|
+
return self
|
|
726
|
+
end
|
|
727
|
+
|
|
728
|
+
return Commands
|