@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.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. 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