@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,400 @@
1
+ --!strict
2
+ -- Checks a stored profile against the compiled template. Read-only and free of policy:
3
+ -- it reports violations, and Persistence decides what one costs. Data-driven, not
4
+ -- schema-driven: walking the schema would flag every field a profile predates, which
5
+ -- Reconcile backfills moments later.
6
+ -- Stored form is not read form for three types, and checking the read form would reject
7
+ -- every healthy profile: datatype (a packed buffer), big ({mantissa, exponent}), flags
8
+ -- (a sorted array of member names).
9
+
10
+ local Big = require(script.Parent.Big)
11
+ local Template = require(script.Parent.Template)
12
+ local Util = require(script.Parent.Util)
13
+
14
+ local Conform = {}
15
+
16
+ -- Matches Util.findUnpersistable's cap. Stored data arrives from a datastore, not
17
+ -- from the accessor tree, so it can be cyclic or absurdly deep.
18
+ local MAX_DEPTH = 64
19
+
20
+ -- A corrupt profile can have a million bad leaves, so the walk stops at the cap
21
+ -- rather than traversing on and merely declining to record.
22
+ local DEFAULT_LIMIT = 32
23
+
24
+ export type Kind =
25
+ "WrongType" -- the value is not the type the schema declares
26
+ | "OutOfBounds" -- numeric, outside Min/Max
27
+ | "OverMaxLength" -- past a declared size cap: MaxLength, MaxItems, MaxKeys, MaxKeyLength
28
+ | "NotAMember" -- enum/flags value is not in Members
29
+ | "BadEncoding" -- a string that is not valid UTF-8; would fail the save
30
+ | "UnknownKey" -- a key a closed record does not declare
31
+
32
+ --- Advisory: report it, but never end a session over it, even under SchemaPolicy =
33
+ --- "Reject". Set on the six container findings only. A flag rather than a `Kind`,
34
+ --- because `Kind` says what is wrong and this says what policy applies. The mixed
35
+ --- array/hash table is the one container finding that is not advisory: it fails the
36
+ --- whole profile's save, so ending the session preserves data that would be lost.
37
+ export type Violation = {
38
+ Path: { string | number },
39
+ Kind: Kind,
40
+ Detail: string,
41
+ Advisory: boolean?,
42
+ }
43
+
44
+ type Walk = {
45
+ Violations: { Violation },
46
+ Limit: number,
47
+ Full: boolean,
48
+ }
49
+
50
+ local function record(walk: Walk, path: { string | number }, kind: Kind, detail: string, advisory: boolean?)
51
+ if #walk.Violations >= walk.Limit then
52
+ walk.Full = true
53
+ return
54
+ end
55
+ table.insert(walk.Violations, { Path = table.clone(path), Kind = kind, Detail = detail, Advisory = advisory })
56
+ end
57
+
58
+ --- Check one leaf against its schema, in the form it is stored in.
59
+ local function checkLeaf(walk: Walk, node: Template.SchemaNode, value: any, path: { string | number })
60
+ local expected = node.ValueType
61
+
62
+ if expected == "datatype" then
63
+ -- Packed at write time; a stored CFrame table means someone wrote raw.
64
+ if typeof(value) ~= "buffer" then
65
+ record(
66
+ walk,
67
+ path,
68
+ "WrongType",
69
+ `expected a packed buffer for {tostring(node.Datatype)}, got {typeof(value)}`
70
+ )
71
+ end
72
+ return
73
+ end
74
+
75
+ if expected == "big" then
76
+ if type(value) ~= "table" or type((value :: any)[1]) ~= "number" or type((value :: any)[2]) ~= "number" then
77
+ record(walk, path, "WrongType", `expected a {"{"}mantissa, exponent{"}"} pair, got {typeof(value)}`)
78
+ return
79
+ end
80
+ -- Ordered through Big.compare, not `<`: a bound past 1.8e308 has to be
81
+ -- declared as a numeric string, and comparing that against a number throws
82
+ -- while comparing two strings orders them lexically.
83
+ local stored = Big.from(value)
84
+ if stored == nil then
85
+ -- Both halves are numbers and at least one is not finite, so nothing can
86
+ -- be ordered against it.
87
+ record(walk, path, "WrongType", "mantissa/exponent pair is not finite")
88
+ return
89
+ end
90
+ -- Guarded on the parse rather than assumed: this walk runs on the load path
91
+ -- over untrusted stored data, so it must never throw.
92
+ if node.Min ~= nil then
93
+ local floor = Big.from(node.Min)
94
+ if floor ~= nil and Big.compare(stored, floor) < 0 then
95
+ record(walk, path, "OutOfBounds", `{Big.toString(stored)} is below Min {Big.toString(floor)}`)
96
+ return
97
+ end
98
+ end
99
+ if node.Max ~= nil then
100
+ local ceiling = Big.from(node.Max)
101
+ if ceiling ~= nil and Big.compare(stored, ceiling) > 0 then
102
+ record(walk, path, "OutOfBounds", `{Big.toString(stored)} is above Max {Big.toString(ceiling)}`)
103
+ end
104
+ end
105
+ return
106
+ end
107
+
108
+ if expected == "flags" then
109
+ if type(value) ~= "table" then
110
+ record(walk, path, "WrongType", `expected an array of flag names, got {typeof(value)}`)
111
+ return
112
+ end
113
+ local index = node.MemberIndex
114
+ if index ~= nil then
115
+ for _, name in value :: { any } do
116
+ if type(name) ~= "string" or index[name] == nil then
117
+ record(walk, path, "NotAMember", `{tostring(name)} is not a declared flag`)
118
+ return
119
+ end
120
+ end
121
+ end
122
+ return
123
+ end
124
+
125
+ if expected == "boolean" then
126
+ if type(value) ~= "boolean" then
127
+ record(walk, path, "WrongType", `expected boolean, got {typeof(value)}`)
128
+ end
129
+ return
130
+ end
131
+
132
+ if expected == "number" or expected == "int" then
133
+ if type(value) ~= "number" then
134
+ record(walk, path, "WrongType", `expected {expected}, got {typeof(value)}`)
135
+ return
136
+ end
137
+ if value ~= value then
138
+ -- NaN survives a JSON round trip in some encoders and poisons every
139
+ -- comparison downstream, so it is called out separately.
140
+ record(walk, path, "WrongType", "value is NaN")
141
+ return
142
+ end
143
+ if expected == "int" and value % 1 ~= 0 then
144
+ record(walk, path, "WrongType", `expected an integer, got {value}`)
145
+ return
146
+ end
147
+ if node.Min ~= nil and value < node.Min then
148
+ record(walk, path, "OutOfBounds", `{value} is below Min {node.Min}`)
149
+ elseif node.Max ~= nil and value > node.Max then
150
+ record(walk, path, "OutOfBounds", `{value} is above Max {node.Max}`)
151
+ end
152
+ return
153
+ end
154
+
155
+ if expected == "enum" then
156
+ if type(value) ~= "string" then
157
+ record(walk, path, "WrongType", `expected an enum member name, got {typeof(value)}`)
158
+ return
159
+ end
160
+ if node.MemberIndex ~= nil and node.MemberIndex[value] == nil then
161
+ record(walk, path, "NotAMember", `"{value}" is not a declared member`)
162
+ end
163
+ return
164
+ end
165
+
166
+ if expected == "string" then
167
+ if type(value) ~= "string" then
168
+ record(walk, path, "WrongType", `expected string, got {typeof(value)}`)
169
+ return
170
+ end
171
+ if not Util.isUtf8(value) then
172
+ -- An invalid-UTF-8 string fails the whole profile save with a DataStore
173
+ -- 104, so one bad byte stops every future write.
174
+ record(walk, path, "BadEncoding", "string is not valid UTF-8; this will fail the save")
175
+ return
176
+ end
177
+ if node.MaxLength ~= nil and #value > node.MaxLength then
178
+ record(walk, path, "OverMaxLength", `{#value} bytes exceeds MaxLength {node.MaxLength}`)
179
+ end
180
+ return
181
+ end
182
+
183
+ if expected == "buffer" then
184
+ if typeof(value) ~= "buffer" then
185
+ record(walk, path, "WrongType", `expected buffer, got {typeof(value)}`)
186
+ end
187
+ return
188
+ end
189
+
190
+ -- "any" and "table" accept whatever is there; a table recurses below.
191
+ end
192
+
193
+ --- Does this table mix array indices with string keys?
194
+ ---
195
+ --- Runs on every table the walk reaches, not just declared containers: JSON cannot
196
+ --- encode the shape, so one mixed table fails the save of the whole profile, opaquely
197
+ --- and far from whatever wrote it. The write path refuses it, but datastore data,
198
+ --- migrations, UpdateOffline drafts and OnPlayerInit hooks never passed through there.
199
+ local function mixesKeyTypes(value: { [any]: any }): boolean
200
+ local hasNum, hasStr = false, false
201
+ for key in value do
202
+ local kt = type(key)
203
+ hasNum = hasNum or kt == "number"
204
+ hasStr = hasStr or kt == "string"
205
+ if hasNum and hasStr then
206
+ return true
207
+ end
208
+ end
209
+ return false
210
+ end
211
+
212
+ --- Container shape and caps, for a node that declares one.
213
+ ---
214
+ --- The write path tolerates a container already over cap in storage and refuses only
215
+ --- growth past the stored size, since a rolling deploy can put a newer server's larger
216
+ --- container in front of an older server's lower cap. This check has no stored size to
217
+ --- compare against: it is the stored size. It therefore reports an over-cap container
218
+ --- that a write would be allowed to make, so every finding here is advisory.
219
+ ---
220
+ --- `Container` is nil on untyped bags: an undeclared `{}` has no key shape and no caps,
221
+ --- and measuring it would report every bag that happens to hold an array.
222
+ local function checkContainer(walk: Walk, node: Template.SchemaNode, value: any, path: { string | number })
223
+ local container = node.Container
224
+ if container == nil then
225
+ return
226
+ end
227
+
228
+ local count = 0
229
+ local maxIndex = 0
230
+ local badIndex = false
231
+ -- A Scribe.MapOf("integer") is numerically keyed and its keys are back in numeric
232
+ -- form by now (Template.CoerceMapKeys runs first), so MaxKeyLength, a byte cap on
233
+ -- a string key, does not apply. Same test the write path makes.
234
+ local maxKeyLength = if node.KeyType ~= "integer" then node.MaxKeyLength else nil
235
+
236
+ for key in value :: { [any]: any } do
237
+ count += 1
238
+ if container == "Array" then
239
+ if type(key) ~= "number" then
240
+ -- What a hole looks like after a datastore round trip: JSON cannot
241
+ -- express a sparse array, so the encoder writes an object and the decode
242
+ -- hands back "1"/"3" instead of 1/3.
243
+ record(
244
+ walk,
245
+ path,
246
+ "WrongType",
247
+ `Scribe.ArrayOf takes array entries, but "{tostring(key)}" is a string key`,
248
+ true
249
+ )
250
+ badIndex = true
251
+ elseif key % 1 ~= 0 or key < 1 then
252
+ record(walk, path, "WrongType", `array index {key} is not a positive integer`, true)
253
+ badIndex = true
254
+ elseif key > maxIndex then
255
+ maxIndex = key
256
+ end
257
+ elseif maxKeyLength ~= nil and type(key) == "string" and #key > maxKeyLength then
258
+ -- Each offending key is its own finding.
259
+ table.insert(path, key)
260
+ record(walk, path, "OverMaxLength", `key "{key}" is {#key} bytes, over MaxKeyLength {maxKeyLength}`, true)
261
+ table.remove(path)
262
+ end
263
+ end
264
+
265
+ if container == "Array" then
266
+ -- `#value` stops at the first hole, so compare the entry count against the
267
+ -- highest index instead: a ragged array always has maxIndex > count. Skipped
268
+ -- once a bad index has been reported, since maxIndex is then meaningless.
269
+ if not badIndex and count ~= maxIndex then
270
+ record(
271
+ walk,
272
+ path,
273
+ "WrongType",
274
+ `array entries must run contiguously from 1 (no holes): {count} entries, highest index {maxIndex}`,
275
+ true
276
+ )
277
+ end
278
+ local maxItems = node.MaxItems
279
+ if maxItems ~= nil then
280
+ -- A set is stored deduplicated, so its cap is on membership. Counting raw
281
+ -- entries would report a stored set whose membership fits.
282
+ local effective = count
283
+ if node.Unique then
284
+ local seen: { [any]: boolean } = {}
285
+ effective = 0
286
+ for _, item in value :: { any } do
287
+ if not seen[item] then
288
+ seen[item] = true
289
+ effective += 1
290
+ end
291
+ end
292
+ end
293
+ if effective > maxItems then
294
+ record(walk, path, "OverMaxLength", `holds {effective} entries, over MaxItems {maxItems}`, true)
295
+ end
296
+ end
297
+ else
298
+ local maxKeys = node.MaxKeys
299
+ if maxKeys ~= nil and count > maxKeys then
300
+ record(walk, path, "OverMaxLength", `holds {count} keys, over MaxKeys {maxKeys}`, true)
301
+ end
302
+ end
303
+ end
304
+
305
+ local function walkNode(walk: Walk, node: Template.SchemaNode, value: any, path: { string | number }, depth: number)
306
+ if walk.Full then
307
+ return
308
+ end
309
+ if depth > MAX_DEPTH then
310
+ record(walk, path, "WrongType", `nesting exceeds {MAX_DEPTH} levels`)
311
+ return
312
+ end
313
+
314
+ -- A nil is a field the profile does not carry yet. Reconcile backfills those, so
315
+ -- absence is never a violation.
316
+ if value == nil then
317
+ return
318
+ end
319
+
320
+ -- Dispatch on what the field is, not on what its default happened to be. `Kind`
321
+ -- records only whether the declared default was a table, and it disagrees with
322
+ -- `ValueType` in two places that reported healthy profiles as corrupt:
323
+ -- flags defaults to `{}`, so Kind is "table", but the stored form is an array
324
+ -- of member names.
325
+ -- any the child ChildSchema synthesises for an undeclared key carries no schema.
326
+ if node.Kind == "leaf" or node.ValueType == "flags" or node.ValueType == "any" then
327
+ checkLeaf(walk, node, value, path)
328
+ return
329
+ end
330
+
331
+ if type(value) ~= "table" then
332
+ record(walk, path, "WrongType", `expected a table, got {typeof(value)}`)
333
+ return
334
+ end
335
+
336
+ -- Reported and then abandoned, not descended into: nothing under a table the
337
+ -- datastore cannot encode can be acted on until the table itself is repaired,
338
+ -- and a finding per leaf would crowd out the rest of the report at the cap.
339
+ if mixesKeyTypes(value) then
340
+ record(walk, path, "WrongType", "table mixes array indices and string keys; this will fail the DataStore save")
341
+ return
342
+ end
343
+ checkContainer(walk, node, value, path)
344
+
345
+ for key, child in value :: { [any]: any } do
346
+ if walk.Full then
347
+ return
348
+ end
349
+ if type(key) ~= "string" and type(key) ~= "number" then
350
+ record(walk, path, "UnknownKey", `key of type {typeof(key)} cannot be stored`)
351
+ continue
352
+ end
353
+
354
+ local childSchema = Template.ChildSchema(node, key)
355
+ table.insert(path, key)
356
+ if childSchema == nil then
357
+ -- Only reachable on a Closed record: everywhere else ChildSchema synthesises
358
+ -- an `any` child, so an unknown key is undetectable outside a closed shape.
359
+ record(walk, path, "UnknownKey", `"{tostring(key)}" is not declared on this record`)
360
+ else
361
+ walkNode(walk, childSchema, child, path, depth + 1)
362
+ end
363
+ table.remove(path)
364
+ end
365
+ end
366
+
367
+ --- Every way `data` fails to match `compiled`, up to `limit` findings.
368
+ ---
369
+ --- An empty result means the stored shape is consistent with the template, not
370
+ --- that the data is correct.
371
+ function Conform.Check(compiled: Template.Compiled, data: { [string]: any }, opts: { Limit: number? }?): { Violation }
372
+ local walk: Walk = {
373
+ Violations = {},
374
+ Limit = if opts and opts.Limit then opts.Limit else DEFAULT_LIMIT,
375
+ Full = false,
376
+ }
377
+ if type(data) ~= "table" then
378
+ return { { Path = {}, Kind = "WrongType" :: Kind, Detail = `profile is {typeof(data)}, not a table` } }
379
+ end
380
+
381
+ local root = compiled.Root
382
+ if root.Children == nil then
383
+ return walk.Violations
384
+ end
385
+
386
+ for name, child in root.Children do
387
+ -- Session subtrees are never stored, so a stored copy of one is stale rather
388
+ -- than corrupt.
389
+ if child.Persist then
390
+ local path: { string | number } = { name }
391
+ walkNode(walk, child, data[name], path, 1)
392
+ end
393
+ end
394
+ return walk.Violations
395
+ end
396
+
397
+ Conform.MAX_DEPTH = MAX_DEPTH
398
+ Conform.DEFAULT_LIMIT = DEFAULT_LIMIT
399
+
400
+ return Conform