@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,2143 @@
1
+ --!strict
2
+ -- Global all-time leaderboards on OrderedDataStore: paced deduplicated write
3
+ -- queue, cached top-N reads, and per-player rank replication. Clients are
4
+ -- served from the server cache only.
5
+
6
+ local DataStoreService = game:GetService("DataStoreService")
7
+ local Players = game:GetService("Players")
8
+
9
+ local Internal = script.Parent.Parent.Internal
10
+ local Types = require(script.Parent.Parent.Types)
11
+ local Util = require(Internal.Util)
12
+ local Wire = require(Internal.Wire)
13
+ local Template = require(Internal.Template)
14
+ local Big = require(Internal.Big)
15
+ local Log = require(Internal.Log)
16
+ local Metrics = require(Internal.Metrics)
17
+ local Clock = require(Internal.Clock)
18
+ local Profile = require(Internal.Profile)
19
+ local Sched = require(Internal.Sched)
20
+ local Budget = require(Internal.Budget)
21
+ local Rng = require(Internal.Rng)
22
+ local Failure = require(Internal.Failure)
23
+ local Diagnostics = require(Internal.LeaderboardDiagnostics)
24
+
25
+ local Leaderboards = {}
26
+
27
+ local WRITE_INTERVAL = 1.5
28
+ local SCORE_WRITE_INTERVAL = 30
29
+ local RETRY_BASE = 30
30
+ local RETRY_MAX = 300
31
+ -- Ceiling on what one tick may drain once the queue has backed up. Every write
32
+ -- yields, so an unbounded drain turns the pacer into the unpaced flush it prevents.
33
+ local MAX_WRITES_PER_TICK = 8
34
+ local REFRESH_INTERVAL = 60
35
+ -- Floor on a per-board RefreshInterval. GetSortedAsync's request budget scales with
36
+ -- player count, so a near-empty server is the worst case. A sub-minute board is
37
+ -- almost always an in-server scoreboard, which belongs in Scribe.Shared at no
38
+ -- DataStore cost.
39
+ local MIN_REFRESH_INTERVAL = 60
40
+ -- A server board sorts the players here, with no store behind it.
41
+ local SERVER_REFRESH_INTERVAL = 5
42
+ local MIN_SERVER_REFRESH_INTERVAL = 1
43
+ -- Read twice after a rollover, so a late leave flush is not missed.
44
+ local PREVIOUS_READS = 2
45
+ local WEEK_DAYS = { Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6 }
46
+ local ERASE_BUDGET_TIMEOUT = 30
47
+ local ERASE_PROGRESS_EVERY = 25
48
+ -- Lease renewal interval when nothing else checkpoints; well inside Persistence's lease.
49
+ local ERASE_HEARTBEAT = 30
50
+ -- Boot guard on the aggregate rate, which is what actually burns budget: ten boards
51
+ -- at 60s cost more than one at 15s, and the flat floor above permits exactly that.
52
+ local MAX_REFRESH_PER_MINUTE = 12
53
+ local QUEUE_CAP = 1000
54
+ -- Seconds between LB_BUDGET_DEFERRED warns. Deferral is normal and self-correcting,
55
+ -- so only a sustained one should be visible.
56
+ local BUDGET_LOG_INTERVAL = 30
57
+ -- Seconds between LB_QUEUE_OVERFLOW warns; drops in between are counted and
58
+ -- reported on the next one.
59
+ local OVERFLOW_LOG_INTERVAL = 30
60
+ -- Seconds between store-failure warns of the same code. Failures arrive once per
61
+ -- queued write and once per refresh, so an outage otherwise logs a line per attempt.
62
+ local FAILURE_LOG_INTERVAL = 30
63
+ local NAME_TTL = 900
64
+ local NAME_NEGATIVE_TTL = 120
65
+ local NAME_CACHE_CAP = 4096 -- bound the resolved-name cache; entries are re-resolvable
66
+
67
+ -- Scribe.Big leaderboards ----------------------------------------------------------
68
+ --
69
+ -- An OrderedDataStore key is an integer, so a big is packed exponent-major:
70
+ --
71
+ -- key = e * stride + floor(m * mantissaScale)
72
+ --
73
+ -- with stride = 10^SigFigs and mantissaScale = 10^(SigFigs - 1). The mantissa lands
74
+ -- in [mantissaScale, stride) and can never spill into the next exponent's slot, so
75
+ -- the ordering is exact. SigFigs is per board because the key must stay under 2^53
76
+ -- and every extra significant figure costs a factor of ten of exponent range.
77
+ local BIG_DEFAULT_SIG_FIGS = 12
78
+ local BIG_MIN_SIG_FIGS = 1
79
+ -- Past 15 the mantissa slot itself passes 2^53, so floor() would no longer be exact
80
+ -- and a big carries no more than ~15 significant digits anyway.
81
+ local BIG_MAX_SIG_FIGS = 15
82
+ local MAX_EXACT_INT = 2 ^ 53
83
+
84
+ -- The largest exponent whose key still lands under 2^53. The mantissa slot holds up
85
+ -- to stride - 1, so that headroom comes off the top.
86
+ local function bigMaxExponent(stride: number): number
87
+ return math.floor((MAX_EXACT_INT - stride + 1) / stride)
88
+ end
89
+
90
+ type Board = {
91
+ Name: string,
92
+ StatPath: { string },
93
+ Limit: number,
94
+ Scale: number,
95
+ IsBig: boolean,
96
+ -- Big packing, derived once at boot from the board's SigFigs.
97
+ BigSigFigs: number,
98
+ BigStride: number,
99
+ BigMantissaScale: number,
100
+ BigMaxExponent: number,
101
+ RefreshInterval: number,
102
+ WriteInterval: number,
103
+ Replicate: boolean, -- default false: server-only, no client mirror
104
+ -- The prefix; a periodic board appends the period index at write time.
105
+ StoreName: string,
106
+ Period: string?, -- "Daily" | "Weekly"; nil is lifetime
107
+ Mode: string, -- "Gain" | "Peak"
108
+ Scope: string, -- "Global" | "Server"
109
+ CachePeriod: number?,
110
+ PreviousCache: { Entries: { any }, Period: number }?,
111
+ PreviousReads: number,
112
+ Refreshing: boolean,
113
+ RefreshPending: boolean,
114
+ RefreshWaiters: { thread },
115
+ Cache: { Entries: { any }, At: number },
116
+ Signature: string, -- fingerprint of Cache.Entries; broadcasts only on change
117
+ MyRanks: { [number]: number? },
118
+ -- `any`, not `number`: a big board's score is the Big itself, not the packed key.
119
+ MyScores: { [number]: any },
120
+ SentState: { [number]: { Sig: string, Rank: number?, Score: any } },
121
+ LastReadAt: number?,
122
+ LastReadMono: number?,
123
+ LastWriteAt: number?,
124
+ LastReadError: string?,
125
+ LastWriteError: string?,
126
+ }
127
+
128
+ -- In-memory OrderedDataStore shim for UseMock/DontSave testing.
129
+ local function newMockOrderedStore()
130
+ local values: { [string]: number } = {}
131
+ return {
132
+ SetAsync = function(_, key: string, value: number)
133
+ values[key] = value
134
+ end,
135
+ RemoveAsync = function(_, key: string)
136
+ values[key] = nil
137
+ end,
138
+ GetSortedAsync = function(_, ascending: boolean, pageSize: number)
139
+ local sorted = {}
140
+ for key, value in values do
141
+ table.insert(sorted, { key = key, value = value })
142
+ end
143
+ table.sort(sorted, function(a: { key: string, value: number }, b: { key: string, value: number })
144
+ if ascending then
145
+ return a.value < b.value
146
+ end
147
+ return a.value > b.value
148
+ end)
149
+ local page = table.move(sorted, 1, math.min(pageSize, #sorted), 1, {})
150
+ return {
151
+ GetCurrentPage = function()
152
+ return page
153
+ end,
154
+ }
155
+ end,
156
+ }
157
+ end
158
+
159
+ function Leaderboards.new(ctx: any)
160
+ local self = {} :: any
161
+ local options = ctx.Options
162
+ -- Read the resolved mode, not options.UseMock: Persistence resolves Mode into its
163
+ -- own fields and never writes it back, so a Mode = "Mock" bundle would otherwise
164
+ -- hit real OrderedDataStores. NoSave mocks too, since a board write is a write.
165
+ local mode: string = ctx.Persistence.Mode
166
+ local useMock: boolean = mode == "Mock" or mode == "NoSave"
167
+
168
+ local boards: { [string]: Board } = {}
169
+ local storeCache: { [string]: any } = {}
170
+ local mockStores: { [string]: any } = {}
171
+
172
+ local stopped = false
173
+ local started = false
174
+ local unregisterDiagnostics: (() -> ())? = nil
175
+ local pacerThread: thread? = nil
176
+ local refreshThread: thread? = nil
177
+ type WriteState = {
178
+ Board: Board,
179
+ UserId: number,
180
+ StoreName: string,
181
+ LastScore: number?,
182
+ LastAttempt: number?,
183
+ InFlight: boolean,
184
+ Failures: number?,
185
+ RetryAt: number?,
186
+ RejectedScore: number?,
187
+ }
188
+ type QueueItem = {
189
+ Board: Board,
190
+ UserId: number,
191
+ Score: number,
192
+ StoreName: string,
193
+ State: WriteState,
194
+ Urgent: boolean,
195
+ }
196
+ local writeQueue: { QueueItem } = {}
197
+ local writeQueueMap: { [string]: QueueItem } = {}
198
+ local writeStates: { [number]: { [string]: WriteState } } = {}
199
+ local activeUsers: { [number]: number } = {}
200
+ local activeWrites = 0
201
+ local budgetReleases: { [() -> ()]: boolean } = {}
202
+ local pacerParked = false
203
+ local function wakePacer()
204
+ if pacerParked and pacerThread ~= nil and not stopped then
205
+ pacerParked = false
206
+ Sched.Resume(pacerThread)
207
+ end
208
+ end
209
+ -- Overflow-log throttle: over cap the warn rate tracks the stat-change rate of every
210
+ -- out-of-queue player, enough to roll the log ring. The counter still counts drops.
211
+ local lastOverflowLog: number? = nil
212
+ local overflowSinceLog = 0
213
+ -- Defer enables burst draining and paced erasure; background admission is always gated.
214
+ local budgetPolicy: boolean = options.BudgetPolicy == "Defer" and not useMock
215
+ local lastBudgetLog: number? = nil
216
+
217
+ -- Periods -------------------------------------------------------------------
218
+
219
+ local periodReset = options.PeriodReset or {}
220
+ if type(periodReset) ~= "table" then
221
+ error("Scribe: PeriodReset must be a table", 0)
222
+ end
223
+ local utcOffset = periodReset.UtcOffset or 0
224
+ if type(utcOffset) ~= "number" or utcOffset ~= utcOffset or utcOffset < -12 or utcOffset > 14 then
225
+ error("Scribe: PeriodReset.UtcOffset must be a number of hours from -12 to 14", 0)
226
+ end
227
+ local weekStart = periodReset.WeekStart or "Monday"
228
+ if WEEK_DAYS[weekStart] == nil then
229
+ error(`Scribe: PeriodReset.WeekStart must be a day name, not "{tostring(weekStart)}"`, 0)
230
+ end
231
+ local offsetSeconds = utcOffset * 3600
232
+ -- Day 0 of the epoch was a Thursday; this shift puts the chosen day at a multiple of 7.
233
+ local weekShift = (11 - WEEK_DAYS[weekStart]) % 7
234
+
235
+ local function currentPeriod(period: string): number
236
+ local day = math.floor((Clock.Now() + offsetSeconds) / 86400)
237
+ if period == "Daily" then
238
+ return day
239
+ end
240
+ return math.floor((day + weekShift) / 7)
241
+ end
242
+
243
+ -- Never zero: at the rollover instant the next period has begun.
244
+ local function periodEndsIn(period: string): number
245
+ local localNow = Clock.Now() + offsetSeconds
246
+ local day = math.floor(localNow / 86400)
247
+ local endDay: number
248
+ if period == "Daily" then
249
+ endDay = day + 1
250
+ else
251
+ endDay = (math.floor((day + weekShift) / 7) + 1) * 7 - weekShift
252
+ end
253
+ return endDay * 86400 - localNow
254
+ end
255
+
256
+ local function storeNameForKind(board: Board, kind: string, period: number): string
257
+ return `{board.StoreName}_{if kind == "Daily" then "d" else "w"}{period}`
258
+ end
259
+
260
+ local function storeNameFor(board: Board, period: number?): string
261
+ if board.Period == nil or period == nil then
262
+ return board.StoreName
263
+ end
264
+ return storeNameForKind(board, board.Period, period)
265
+ end
266
+
267
+ local function reservedRaw(data: { [string]: any }): { [string]: any }
268
+ local reserved = data[Template.RESERVED_ROOT]
269
+ if type(reserved) ~= "table" then
270
+ reserved = {}
271
+ data[Template.RESERVED_ROOT] = reserved
272
+ end
273
+ if type(reserved.Boards) ~= "table" then
274
+ reserved.Boards = {}
275
+ end
276
+ return reserved
277
+ end
278
+
279
+ local function toStored(board: Board, value: any): any
280
+ return if board.IsBig then Big.toStored(value) else value
281
+ end
282
+
283
+ local function fromStored(board: Board, stored: any): any
284
+ return if board.IsBig then Big.from(stored) else stored
285
+ end
286
+
287
+ -- The gain since the period began, or the peak seen in it. The baseline lives in the
288
+ -- profile; a stale period resets it to `old` so the first write after a rollover
289
+ -- counts. The refresh thread passes commit = false and never writes it.
290
+ local function periodScore(board: Board, entry: any, value: any, old: any, commit: boolean): any
291
+ if board.Period == nil then
292
+ return value
293
+ end
294
+ if entry.LiveData == nil then
295
+ return nil
296
+ end
297
+ local period = currentPeriod(board.Period)
298
+ local records = reservedRaw(entry.LiveData).Boards
299
+ local record = records[board.Name]
300
+ local write: any = nil
301
+ if type(record) ~= "table" or record.P ~= period then
302
+ local base = if old ~= nil then old else value
303
+ if not commit then
304
+ -- Not committing, and nothing gained yet.
305
+ return if board.Mode == "Peak" then value elseif board.IsBig then Big.from(0) else 0
306
+ end
307
+ local first = if type(record) == "table" then record.First else period
308
+ local prior = if type(record) == "table" then record.Prior else nil
309
+ if type(record) == "table" and record.K ~= nil and record.K ~= board.Period then
310
+ -- A period change closes the old range for the erase.
311
+ prior = table.clone(prior or {})
312
+ table.insert(prior, { K = record.K, First = record.First, Last = record.P })
313
+ first = period
314
+ end
315
+ write = { P = period, V = toStored(board, base), First = first, K = board.Period, Prior = prior }
316
+ record = write
317
+ end
318
+ local base = fromStored(board, record.V)
319
+ local score: any
320
+ if board.Mode == "Peak" then
321
+ local higher = if board.IsBig then Big.compare(value, base) > 0 else value > base
322
+ if higher then
323
+ score = value
324
+ if commit then
325
+ write = {
326
+ P = period,
327
+ V = toStored(board, value),
328
+ First = record.First,
329
+ K = record.K,
330
+ Prior = record.Prior,
331
+ }
332
+ end
333
+ else
334
+ score = base
335
+ end
336
+ else
337
+ if board.IsBig then
338
+ score = Big.sub(value, base)
339
+ if Big.compare(score, Big.from(0)) < 0 then
340
+ score = Big.from(0)
341
+ end
342
+ else
343
+ score = math.max(0, value - base)
344
+ end
345
+ end
346
+ if write ~= nil and commit then
347
+ local tree = entry.Tree
348
+ if tree ~= nil and not tree.Dead then
349
+ tree.Reserved.Boards[board.Name].Set(write)
350
+ else
351
+ records[board.Name] = write
352
+ end
353
+ end
354
+ return score
355
+ end
356
+
357
+ -- Store-failure reporting -------------------------------------------------------
358
+
359
+ local failureLog: { [string]: { Last: number?, Since: number } } = {}
360
+ -- Studio with API access off refuses every store call for the whole session. It is
361
+ -- a setting rather than an outage, so it is reported once and then silenced.
362
+ local apiAccessReported = false
363
+
364
+ --- Is Studio refusing the call because API access is off, rather than a store problem?
365
+ --- Matched on the two phrasings Roblox uses. A miss costs nothing: the caller throttles.
366
+ local function isStudioApiDisabled(text: string): boolean
367
+ local lower = string.lower(text)
368
+ return string.find(lower, "studio access to apis", 1, true) ~= nil
369
+ or string.find(lower, "api access is not enabled", 1, true) ~= nil
370
+ end
371
+
372
+ --- One line per failure code per interval, with the suppressed count carried onto the
373
+ --- next. Callers count their own metric, which stays accurate while this is quiet.
374
+ local function reportStoreFailure(code: string, err: any, context: { [string]: any })
375
+ -- Once the Studio setting has been named, every later failure has the same cause.
376
+ if apiAccessReported then
377
+ return
378
+ end
379
+ local text = tostring(err)
380
+ if isStudioApiDisabled(text) then
381
+ apiAccessReported = true
382
+ Log.Warn(
383
+ "Leaderboards",
384
+ code :: any,
385
+ "leaderboard store calls are being refused because Studio API access is off, so boards "
386
+ .. "will neither read nor write for this session. Turn on File > Game Settings > "
387
+ .. "Security > Enable Studio Access to API Services (the place must be published). "
388
+ .. "Reported once; further failures are counted in LbReadFailures and LbWriteFailures",
389
+ context
390
+ )
391
+ return
392
+ end
393
+ local state = failureLog[code]
394
+ if state == nil then
395
+ state = { Last = nil, Since = 0 } :: { Last: number?, Since: number }
396
+ failureLog[code] = state
397
+ end
398
+ state.Since += 1
399
+ local now = Clock.Monotonic()
400
+ if state.Last == nil or now - state.Last >= FAILURE_LOG_INTERVAL then
401
+ state.Last = now
402
+ local suppressed = state.Since - 1
403
+ state.Since = 0
404
+ Log.Warn(
405
+ "Leaderboards",
406
+ code :: any,
407
+ if suppressed > 0 then `{text} ({suppressed} more since the last of these)` else text,
408
+ context
409
+ )
410
+ end
411
+ end
412
+ -- GDPR tombstones: an erased userId is suppressed in the pacer until this
413
+ -- clock time, long enough to outlive any in-flight write plus its retries.
414
+ local erasedUsers: { [number]: number } = {}
415
+ local function isErased(userId: number): boolean
416
+ local until_ = erasedUsers[userId]
417
+ if until_ == nil then
418
+ return false
419
+ end
420
+ if Clock.Monotonic() >= until_ then
421
+ erasedUsers[userId] = nil -- expired; a returning player may re-enter
422
+ return false
423
+ end
424
+ return true
425
+ end
426
+ local nameCache: { [number]: { Name: string?, At: number } } = {}
427
+ local statDisconnects: { [any]: { () -> () } } = {}
428
+
429
+ for name, config in (options.Leaderboards or {}) :: { [string]: any } do
430
+ if type(config.Stat) ~= "string" then
431
+ error(`Scribe: leaderboard "{name}" must declare a Stat path`, 0)
432
+ end
433
+ -- Fail fast on a Stat path that descends through a leaf field: at runtime it
434
+ -- throws on every player load, after Ready, skipping the rest of that load's
435
+ -- wiring. Paths into dynamic ("any") subtables are legitimate and pass.
436
+ local statPath = Util.parsePath(config.Stat)
437
+ local walkNode: any = ctx.Compiled.Root
438
+ for i, segment in statPath do
439
+ if walkNode == nil then
440
+ -- ChildSchema returns nil only for an undeclared field of a closed
441
+ -- element shape, so this Stat can never resolve.
442
+ error(
443
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}": `
444
+ .. `"{tostring(statPath[i - 1])}" has no declared field "{tostring(segment)}"`,
445
+ 0
446
+ )
447
+ end
448
+ if walkNode.Kind == "leaf" then
449
+ error(
450
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" descends through leaf field "{tostring(segment)}"`,
451
+ 0
452
+ )
453
+ end
454
+ walkNode = Template.ChildSchema(walkNode, segment)
455
+ end
456
+ if walkNode == nil then
457
+ -- Final-segment miss: the leaf itself is an undeclared field of a closed
458
+ -- element shape.
459
+ error(
460
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}": `
461
+ .. `no declared field "{tostring(statPath[#statPath])}"`,
462
+ 0
463
+ )
464
+ end
465
+ -- A board outlives the session but a Scribe.Session field is rebuilt from its
466
+ -- default every session, so the board would rank a default forever. A Derived
467
+ -- field does not persist either, but is rankable when it is a pure function of
468
+ -- fields that do, which is what OfflineComputable means.
469
+ local derived = walkNode.Derived
470
+ if derived ~= nil then
471
+ if not derived.OfflineComputable then
472
+ error(
473
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is a derived field that reads `
474
+ .. "session-only state, so its value is not reproducible across sessions and a board "
475
+ .. "cannot rank it. Derive the stat from persisted fields instead",
476
+ 0
477
+ )
478
+ end
479
+ elseif walkNode.Persist == false then
480
+ error(
481
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is a Scribe.Session field, which never `
482
+ .. "persists and resets every session, so there is nothing for a board to rank",
483
+ 0
484
+ )
485
+ end
486
+ -- The score becomes the OrderedDataStore key, so a non-numeric stat has nothing
487
+ -- to rank and the refresh cycle would silently drop it. "any" is a dynamic
488
+ -- subtree whose type is unknowable at boot, so it stays allowed.
489
+ local statType = walkNode.ValueType
490
+ if statType ~= "number" and statType ~= "int" and statType ~= "big" and statType ~= "any" then
491
+ error(
492
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is a {tostring(statType)} field; a Stat must `
493
+ .. "resolve to a number, a Scribe.Int, or a Scribe.Big",
494
+ 0
495
+ )
496
+ end
497
+ if config.Replicate == true and walkNode ~= nil and walkNode.ValueType == "big" then
498
+ -- The board frame writes each Score as an f64 and a big Score is a table.
499
+ -- Sending one throws inside broadcastBoard, under the inbound frame pcall
500
+ -- during a client Hello, breaking that player's handshake. Refuse at boot.
501
+ error(
502
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is a Scribe.Big, which cannot be `
503
+ .. "replicated yet; read it on the server with GetLeaderboard or OnLeaderboard",
504
+ 0
505
+ )
506
+ end
507
+ if config.Scale ~= nil and walkNode ~= nil and walkNode.ValueType == "big" then
508
+ error(
509
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is a Scribe.Big; Scale does not apply, `
510
+ .. "because the exponent packing already maps it into the key space",
511
+ 0
512
+ )
513
+ end
514
+ -- Scale multiplies into the stored integer and divides back out on read, so a zero
515
+ -- serves NaN, a negative inverts the ordering against the descending query, and a
516
+ -- non-finite makes every write a guaranteed rejection.
517
+ if config.Scale ~= nil then
518
+ local scale = config.Scale
519
+ if type(scale) ~= "number" or scale ~= scale or scale <= 0 or scale == math.huge then
520
+ error(`Scribe: leaderboard "{name}" Scale must be a finite number greater than 0`, 0)
521
+ end
522
+ end
523
+ local isBig = walkNode ~= nil and walkNode.ValueType == "big"
524
+ local sigFigs = BIG_DEFAULT_SIG_FIGS
525
+ if config.SigFigs ~= nil then
526
+ -- SigFigs is the big packing's dial; on a plain numeric stat the key is the
527
+ -- value and Scale is the dial, so accepting SigFigs there would do nothing.
528
+ if not isBig then
529
+ error(
530
+ `Scribe: leaderboard "{name}" Stat "{config.Stat}" is not a Scribe.Big; SigFigs only applies `
531
+ .. "to the big exponent packing. Use Scale to control a plain numeric stat's resolution",
532
+ 0
533
+ )
534
+ end
535
+ local requested = config.SigFigs
536
+ if
537
+ type(requested) ~= "number"
538
+ or requested % 1 ~= 0
539
+ or requested < BIG_MIN_SIG_FIGS
540
+ or requested > BIG_MAX_SIG_FIGS
541
+ then
542
+ error(
543
+ `Scribe: leaderboard "{name}" SigFigs must be a whole number from {BIG_MIN_SIG_FIGS} to `
544
+ .. `{BIG_MAX_SIG_FIGS}, got {tostring(requested)}`,
545
+ 0
546
+ )
547
+ end
548
+ sigFigs = requested
549
+ end
550
+ local bigStride = 10 ^ sigFigs
551
+ -- No boot warning for a narrowed exponent range: LB_SCORE_OUT_OF_RANGE names the
552
+ -- cap and its SigFigs when a score is actually dropped, which is when it matters.
553
+ local maxExponent = bigMaxExponent(bigStride)
554
+ -- Clamped up rather than rejected so an existing config keeps working, but the
555
+ -- clamp is reported: silently running slower than asked is its own bug.
556
+ local scope = config.Scope or "Global"
557
+ if scope ~= "Global" and scope ~= "Server" then
558
+ error(`Scribe: leaderboard "{name}" Scope must be "Global" or "Server"`, 0)
559
+ end
560
+ local period = config.Period
561
+ if period == "AllTime" then
562
+ period = nil
563
+ end
564
+ if period ~= nil and period ~= "Daily" and period ~= "Weekly" then
565
+ error(`Scribe: leaderboard "{name}" Period must be "Daily" or "Weekly"`, 0)
566
+ end
567
+ local boardMode = config.Mode or "Gain"
568
+ if boardMode ~= "Gain" and boardMode ~= "Peak" then
569
+ error(`Scribe: leaderboard "{name}" Mode must be "Gain" or "Peak"`, 0)
570
+ end
571
+ if config.Mode ~= nil and period == nil then
572
+ error(`Scribe: leaderboard "{name}" Mode needs a Period; a lifetime board has nothing to gain over`, 0)
573
+ end
574
+ local isServer = scope == "Server"
575
+ local storeName = if config.StoreName ~= nil
576
+ then config.StoreName
577
+ elseif isBig then `LB_{name}_big{sigFigs}`
578
+ else `LB_{name}`
579
+ if not isServer then
580
+ if type(storeName) ~= "string" or #storeName == 0 then
581
+ error(`Scribe: leaderboard "{name}" StoreName must be a non-empty string`, 0)
582
+ end
583
+ local longest = storeName
584
+ if period then
585
+ for offset = -1, 1 do
586
+ local candidate =
587
+ `{storeName}_{if period == "Daily" then "d" else "w"}{currentPeriod(period) + offset}`
588
+ if #candidate > #longest then
589
+ longest = candidate
590
+ end
591
+ end
592
+ end
593
+ if #longest > 50 then
594
+ error(`Scribe: leaderboard "{name}" generated store name exceeds 50 bytes; shorten StoreName`, 0)
595
+ end
596
+ end
597
+ local refreshInterval = if isServer then SERVER_REFRESH_INTERVAL else REFRESH_INTERVAL
598
+ local writeInterval = if config.WriteInterval == nil then SCORE_WRITE_INTERVAL else config.WriteInterval
599
+ if
600
+ type(writeInterval) ~= "number"
601
+ or writeInterval ~= writeInterval
602
+ or writeInterval <= 0
603
+ or writeInterval == math.huge
604
+ then
605
+ error(`Scribe: leaderboard "{name}" WriteInterval must be a finite positive number of seconds`, 0)
606
+ end
607
+ if writeInterval < 1 then
608
+ Log.Warn(
609
+ "Leaderboards",
610
+ "LB_INTERVAL_CLAMPED",
611
+ `leaderboard "{name}" WriteInterval was clamped to 1s`,
612
+ { Board = name, Requested = writeInterval, Applied = 1 }
613
+ )
614
+ writeInterval = 1
615
+ end
616
+ local minInterval = if isServer then MIN_SERVER_REFRESH_INTERVAL else MIN_REFRESH_INTERVAL
617
+ if config.RefreshInterval ~= nil then
618
+ local requested = config.RefreshInterval
619
+ if type(requested) ~= "number" or requested ~= requested or requested <= 0 then
620
+ error(`Scribe: leaderboard "{name}" RefreshInterval must be a positive number of seconds`, 0)
621
+ end
622
+ refreshInterval = math.max(requested, minInterval)
623
+ if refreshInterval ~= requested then
624
+ Log.Warn(
625
+ "Leaderboards",
626
+ "LB_INTERVAL_CLAMPED",
627
+ `leaderboard "{name}" RefreshInterval {requested}s is below the {minInterval}s floor and was clamped. `
628
+ .. 'A sub-minute board is usually an in-server scoreboard, which is Scope = "Server" (no DataStore cost).',
629
+ { Board = name, Requested = requested, Applied = refreshInterval }
630
+ )
631
+ end
632
+ end
633
+ boards[name] = {
634
+ Name = name,
635
+ RefreshInterval = refreshInterval,
636
+ WriteInterval = writeInterval,
637
+ StatPath = Util.parsePath(config.Stat),
638
+ Limit = math.clamp(config.Limit or 100, 1, 100),
639
+ Scale = config.Scale or 1,
640
+ -- Resolved at boot from the stat's schema, so the write path never re-walks it.
641
+ IsBig = isBig,
642
+ BigSigFigs = sigFigs,
643
+ BigStride = bigStride,
644
+ BigMantissaScale = bigStride / 10,
645
+ BigMaxExponent = maxExponent,
646
+ Replicate = config.Replicate == true,
647
+ Period = period,
648
+ Mode = boardMode,
649
+ Scope = scope,
650
+ CachePeriod = nil,
651
+ PreviousCache = nil,
652
+ PreviousReads = 0,
653
+ Refreshing = false,
654
+ RefreshPending = false,
655
+ RefreshWaiters = {},
656
+ -- SigFigs is in the store name: big and plain keys are different layouts, so
657
+ -- sharing `LB_<name>` would silently reinterpret every key already written
658
+ -- when a stat is retyped or its SigFigs change, with no repair pass able to
659
+ -- separate the two formats afterwards. An explicit StoreName still wins.
660
+ StoreName = storeName,
661
+ Cache = { Entries = {}, At = 0 },
662
+ Signature = "",
663
+ MyRanks = {},
664
+ MyScores = {},
665
+ SentState = {},
666
+ }
667
+ end
668
+
669
+ -- Aggregate budget guard: fail at boot rather than as mystery throttling in production.
670
+ do
671
+ local perMinute = 0
672
+ for _, board in boards do
673
+ if board.Scope ~= "Server" then
674
+ perMinute += 60 / board.RefreshInterval
675
+ end
676
+ end
677
+ if perMinute > MAX_REFRESH_PER_MINUTE then
678
+ error(
679
+ `Scribe: leaderboards would issue {string.format("%.1f", perMinute)} GetSortedAsync reads per minute `
680
+ .. `across {Util.count(boards)} board(s), over the {MAX_REFRESH_PER_MINUTE}/min guard. `
681
+ .. "Raise RefreshInterval on some boards, or declare fewer of them.",
682
+ 0
683
+ )
684
+ end
685
+ end
686
+
687
+ -- Sizes the GetSortedAsync reserve in Persistence; a server board never reads a store.
688
+ self.BoardCount = 0
689
+ for _, board in boards do
690
+ if board.Scope ~= "Server" then
691
+ self.BoardCount += 1
692
+ end
693
+ end
694
+
695
+ local function orderedStore(name: string): any
696
+ if #name == 0 or #name > 50 then
697
+ error("101: leaderboard store name must be between 1 and 50 bytes", 0)
698
+ end
699
+ if useMock then
700
+ local mock = mockStores[name]
701
+ if not mock then
702
+ mock = newMockOrderedStore()
703
+ mockStores[name] = mock
704
+ end
705
+ return mock
706
+ end
707
+ local store = storeCache[name]
708
+ if not store then
709
+ store = DataStoreService:GetOrderedDataStore(name)
710
+ storeCache[name] = store
711
+ end
712
+ return store
713
+ end
714
+
715
+ local function packBig(board: Board, value: any): number?
716
+ local big = Big.from(value)
717
+ if big == nil then
718
+ return nil
719
+ end
720
+ if big.M == 0 then
721
+ -- Below every representable key, not 0: a value in (0, 1) has a negative
722
+ -- exponent and so a negative key, which a zero mapped to 0 would outrank.
723
+ return -board.BigMaxExponent * board.BigStride
724
+ end
725
+ -- The packing has no room for a sign, and mis-ranking negatives is worse than
726
+ -- refusing them.
727
+ if big.M < 0 or math.abs(big.E) > board.BigMaxExponent then
728
+ return nil
729
+ end
730
+ return big.E * board.BigStride + math.floor(big.M * board.BigMantissaScale)
731
+ end
732
+
733
+ -- Copy a handed-out entry, since the caller may keep or mutate it. table.clone is
734
+ -- shallow, so a big Score would still alias the cache; rebuild the big instead.
735
+ local function copyEntry(board: Board, item: any): any
736
+ local copy = table.clone(item)
737
+ if board.IsBig and copy.Score ~= nil then
738
+ copy.Score = Big.from(copy.Score)
739
+ end
740
+ return copy
741
+ end
742
+
743
+ -- A player's current value for a board's Stat. Reads through the accessor tree,
744
+ -- the only view that sees Session and Derived fields; LiveData is the persisted
745
+ -- store alone, and is the fallback when teardown races the leave flush.
746
+ local function readStat(entry: any, board: Board): any
747
+ local tree = entry.Tree
748
+ if tree ~= nil and not tree.Dead then
749
+ local ok, value = pcall(function()
750
+ local accessor = tree.Accessor
751
+ for _, segment in board.StatPath do
752
+ accessor = accessor[segment]
753
+ end
754
+ return accessor.Get()
755
+ end)
756
+ if ok then
757
+ return value
758
+ end
759
+ end
760
+ local value: any = entry.LiveData
761
+ for _, segment in board.StatPath do
762
+ value = if type(value) == "table" then value[segment] else nil
763
+ end
764
+ return value
765
+ end
766
+
767
+ local function unpackBig(board: Board, key: number): any
768
+ local stride = board.BigStride
769
+ -- The zero sentinel, plus the legacy 0 that boards written before it used.
770
+ if key == 0 or key <= -board.BigMaxExponent * stride then
771
+ return Big.from(0)
772
+ end
773
+ -- The division cannot round up into the next exponent, which would decode the
774
+ -- score at the wrong magnitude: that needs e * stride >= 2^53, and
775
+ -- bigMaxExponent caps e strictly below it. Widening that cap breaks this.
776
+ local exponent = math.floor(key / stride)
777
+ return Big.normalize((key - exponent * stride) / board.BigMantissaScale, exponent)
778
+ end
779
+
780
+ -- Write queue ------------------------------------------------------------------
781
+
782
+ local function writeKey(board: Board, userId: number, storeName: string): string
783
+ return `{board.Name}|{userId}|{storeName}`
784
+ end
785
+
786
+ local function releaseWriteState(state: WriteState)
787
+ local key = writeKey(state.Board, state.UserId, state.StoreName)
788
+ if state.InFlight or writeQueueMap[key] ~= nil then
789
+ return
790
+ end
791
+ local currentStore =
792
+ storeNameFor(state.Board, if state.Board.Period then currentPeriod(state.Board.Period) else nil)
793
+ if not stopped and (activeUsers[state.UserId] or 0) > 0 and state.StoreName == currentStore then
794
+ return
795
+ end
796
+ local states = writeStates[state.UserId]
797
+ if states and states[key] == state then
798
+ states[key] = nil
799
+ if next(states) == nil then
800
+ writeStates[state.UserId] = nil
801
+ end
802
+ end
803
+ end
804
+
805
+ local function queueWrite(item: QueueItem)
806
+ while #writeQueue >= QUEUE_CAP do
807
+ local dropped = table.remove(writeQueue, 1)
808
+ if dropped then
809
+ writeQueueMap[writeKey(dropped.Board, dropped.UserId, dropped.StoreName)] = nil
810
+ releaseWriteState(dropped.State)
811
+ end
812
+ Metrics.Add("LbQueueOverflow")
813
+ overflowSinceLog += 1
814
+ end
815
+ if overflowSinceLog > 0 then
816
+ local now = Clock.Monotonic()
817
+ if lastOverflowLog == nil or now - lastOverflowLog >= OVERFLOW_LOG_INTERVAL then
818
+ lastOverflowLog = now
819
+ Log.Warn(
820
+ "Leaderboards",
821
+ "LB_QUEUE_OVERFLOW",
822
+ `write queue overflow; dropped the oldest entry ({overflowSinceLog} drop(s) since the last of these). `
823
+ .. "Scores are being produced faster than the write pacer drains them",
824
+ { Dropped = overflowSinceLog, Depth = #writeQueue }
825
+ )
826
+ overflowSinceLog = 0
827
+ end
828
+ end
829
+ table.insert(writeQueue, item)
830
+ writeQueueMap[writeKey(item.Board, item.UserId, item.StoreName)] = item
831
+ Metrics.Set("LbQueueDepth", #writeQueue)
832
+ wakePacer()
833
+ end
834
+
835
+ function self.Enqueue(board: Board, entry: any, value: any, old: any?, urgent: boolean?)
836
+ local userId: number = entry.UserId
837
+ if isErased(userId) then
838
+ return -- within the GDPR tombstone window; do not re-add
839
+ end
840
+ local score = periodScore(board, entry, value, old, true)
841
+ if score == nil or board.Scope == "Server" then
842
+ return -- a server board is rebuilt from live entries on refresh
843
+ end
844
+ local scaled: number
845
+ if board.IsBig then
846
+ -- Scale does not apply: the packing is the mapping into the key space.
847
+ local packed = packBig(board, score)
848
+ if packed == nil then
849
+ Metrics.Add("LbScoreOutOfRange")
850
+ Log.Warn(
851
+ "Leaderboards",
852
+ "LB_SCORE_OUT_OF_RANGE",
853
+ `big score cannot be ranked (negative, or exponent past {board.BigMaxExponent} at SigFigs `
854
+ .. `{board.BigSigFigs}); not written`,
855
+ { Board = board.Name, UserId = userId }
856
+ )
857
+ return
858
+ end
859
+ scaled = packed
860
+ else
861
+ if type(score) ~= "number" or score ~= score then
862
+ return
863
+ end
864
+ scaled = math.floor(score * board.Scale + 0.5)
865
+ end
866
+ -- A scaled value outside the exact integer range is rejected by SetAsync every
867
+ -- time and re-enqueued on every Changed, so it becomes a permanent failure stream.
868
+ if scaled ~= scaled or math.abs(scaled) > 9007199254740992 then
869
+ Metrics.Add("LbScoreOutOfRange")
870
+ Log.Warn(
871
+ "Leaderboards",
872
+ "LB_SCORE_OUT_OF_RANGE",
873
+ `score {tostring(score)} x Scale {board.Scale} is outside the exact integer range (2^53); not written`,
874
+ { Board = board.Name, UserId = userId }
875
+ )
876
+ return
877
+ end
878
+ -- Resolved now and in the dedup key: a score drains to the period it was computed
879
+ -- for, and a new period's score never overwrites an old one.
880
+ local storeName = storeNameFor(board, if board.Period then currentPeriod(board.Period) else nil)
881
+ local key = writeKey(board, userId, storeName)
882
+ local states = writeStates[userId]
883
+ if board.Period ~= nil and states ~= nil and states[key] == nil then
884
+ -- Drop finished history from older periods.
885
+ for _, state in states do
886
+ if state.Board == board then
887
+ releaseWriteState(state)
888
+ end
889
+ end
890
+ end
891
+ states = writeStates[userId]
892
+ if states == nil then
893
+ states = {}
894
+ writeStates[userId] = states
895
+ end
896
+ local state: WriteState = states[key]
897
+ or { Board = board, UserId = userId, StoreName = storeName, InFlight = false }
898
+ states[key] = state
899
+ if state.RejectedScore ~= nil then
900
+ if state.RejectedScore == scaled then
901
+ return
902
+ end
903
+ state.RejectedScore, state.Failures, state.RetryAt = nil, nil, nil
904
+ end
905
+ local existing = writeQueueMap[key]
906
+ if existing then
907
+ -- Dedup by (board, userId), keeping only the latest value.
908
+ existing.Score = scaled
909
+ existing.Urgent = existing.Urgent or urgent == true
910
+ return
911
+ end
912
+ -- Keep changes queued until the in-flight write settles.
913
+ if not state.InFlight and state.LastScore == scaled then
914
+ Metrics.Add("LbWritesSkipped")
915
+ releaseWriteState(state)
916
+ return
917
+ end
918
+ local item: QueueItem = {
919
+ Board = board,
920
+ UserId = userId,
921
+ Score = scaled,
922
+ StoreName = storeName,
923
+ State = state,
924
+ Urgent = urgent == true,
925
+ }
926
+ queueWrite(item)
927
+ end
928
+
929
+ local function performWrite(item: QueueItem): (boolean, boolean)
930
+ local board = item.Board
931
+ local ok, err = pcall(function()
932
+ orderedStore(item.StoreName):SetAsync(tostring(item.UserId), item.Score)
933
+ end)
934
+ if ok then
935
+ Metrics.Add("LbWrites")
936
+ board.LastWriteAt = Clock.Now()
937
+ board.LastWriteError = nil
938
+ else
939
+ -- Deliberately not Health.ReportFailure: board writes are routinely throttled
940
+ -- under load, and the shared health budget would flip global status to Outage
941
+ -- and block Robux receipts. LbWriteFailures and LB_WRITE_FAIL signal instead.
942
+ Metrics.Add("LbWriteFailures")
943
+ board.LastWriteError = tostring(err)
944
+ reportStoreFailure("LB_WRITE_FAIL", err, {
945
+ Board = board.Name,
946
+ UserId = item.UserId,
947
+ Score = item.Score,
948
+ })
949
+ end
950
+ return ok, not ok and (Failure.Classify(err) == "Rejected" or isStudioApiDisabled(tostring(err)))
951
+ end
952
+
953
+ local function claimBackground(requestType: string): (boolean, () -> ())
954
+ if useMock then
955
+ return true, function() end
956
+ end
957
+ local granted, free = Budget.TryBackground(requestType)
958
+ if granted then
959
+ local release: () -> ()
960
+ release = function()
961
+ if budgetReleases[release] then
962
+ budgetReleases[release] = nil
963
+ free()
964
+ end
965
+ end
966
+ budgetReleases[release] = true
967
+ return true, release
968
+ end
969
+ Metrics.Add("LbBudgetDeferred")
970
+ local now = Clock.Monotonic()
971
+ if lastBudgetLog == nil or now - lastBudgetLog >= BUDGET_LOG_INTERVAL then
972
+ lastBudgetLog = now
973
+ Log.Warn(
974
+ "Leaderboards",
975
+ "LB_BUDGET_DEFERRED",
976
+ `leaderboard work is waiting for its share of the {requestType} request budget; boards update more slowly while this lasts`,
977
+ { RequestType = requestType }
978
+ )
979
+ end
980
+ return false, free
981
+ end
982
+
983
+ -- Skip cooling or in-flight keys so other scores can progress.
984
+ local function nextWrite(ignoreInterval: boolean, attempted: { [WriteState]: boolean }?): (number?, QueueItem?)
985
+ local now = Clock.Monotonic()
986
+ for index, item in writeQueue do
987
+ local state = item.State
988
+ if
989
+ not state.InFlight
990
+ and not (attempted and attempted[state])
991
+ and (ignoreInterval or state.RetryAt == nil or now >= state.RetryAt)
992
+ and (
993
+ ignoreInterval
994
+ or item.Urgent
995
+ or state.LastScore == item.Score
996
+ or state.LastAttempt == nil
997
+ or now - state.LastAttempt >= item.Board.WriteInterval
998
+ )
999
+ then
1000
+ return index, item
1001
+ end
1002
+ end
1003
+ return nil, nil
1004
+ end
1005
+
1006
+ local function dequeue(index: number, item: QueueItem)
1007
+ table.remove(writeQueue, index)
1008
+ writeQueueMap[writeKey(item.Board, item.UserId, item.StoreName)] = nil
1009
+ Metrics.Set("LbQueueDepth", #writeQueue)
1010
+ end
1011
+
1012
+ local function writeItem(item: QueueItem)
1013
+ local state = item.State
1014
+ state.InFlight = true
1015
+ state.LastAttempt = Clock.Monotonic()
1016
+ activeWrites += 1
1017
+ local wrote, rejected = performWrite(item)
1018
+ if wrote then
1019
+ state.Failures, state.RetryAt, state.RejectedScore = nil, nil, nil
1020
+ else
1021
+ state.Failures = math.min((state.Failures or 0) + 1, 32)
1022
+ if rejected then
1023
+ state.RejectedScore = item.Score
1024
+ elseif state.Failures >= 3 then
1025
+ local delay = math.min(RETRY_MAX, RETRY_BASE * 2 ^ math.min(state.Failures - 3, 4))
1026
+ state.RetryAt = Clock.Monotonic() + math.min(RETRY_MAX, Rng.Jitter(delay))
1027
+ end
1028
+ end
1029
+ -- Failed responses may follow committed writes; invalidate the cached score.
1030
+ state.LastScore = if wrote then item.Score else nil
1031
+ -- SetAsync yields. An erase during it must not resurrect the score.
1032
+ if wrote and isErased(item.UserId) then
1033
+ state.LastScore = nil
1034
+ pcall(function()
1035
+ orderedStore(item.StoreName):RemoveAsync(tostring(item.UserId))
1036
+ end)
1037
+ end
1038
+ state.InFlight = false
1039
+ activeWrites -= 1
1040
+ local key = writeKey(item.Board, item.UserId, item.StoreName)
1041
+ if not wrote and not stopped and not isErased(item.UserId) then
1042
+ local newer = writeQueueMap[key]
1043
+ if rejected and (newer == nil or newer.Score == item.Score) then
1044
+ if newer then
1045
+ local index = table.find(writeQueue, newer)
1046
+ if index then
1047
+ dequeue(index, newer)
1048
+ end
1049
+ end
1050
+ reportStoreFailure("LB_WRITE_DROPPED", "leaderboard score rejected; waiting for a changed score", {
1051
+ Board = item.Board.Name,
1052
+ UserId = item.UserId,
1053
+ Score = item.Score,
1054
+ })
1055
+ elseif newer == nil then
1056
+ queueWrite(item)
1057
+ elseif rejected then
1058
+ state.RejectedScore, state.Failures, state.RetryAt = nil, nil, nil
1059
+ end
1060
+ end
1061
+ Metrics.Set("LbQueueDepth", #writeQueue)
1062
+ releaseWriteState(state)
1063
+ end
1064
+
1065
+ local function writePacerLoop()
1066
+ Profile.MemoryCategory("Scribe")
1067
+ while not stopped do
1068
+ if #writeQueue == 0 then
1069
+ pacerParked = true
1070
+ coroutine.yield()
1071
+ pacerParked = false
1072
+ if stopped then
1073
+ break
1074
+ end
1075
+ end
1076
+ Clock.Wait(Rng.Jitter(WRITE_INTERVAL))
1077
+ local attempted: { [WriteState]: boolean } = {}
1078
+ -- Claim shared budget before dequeuing, including Defer batches.
1079
+ for _ = 1, math.min(if budgetPolicy then MAX_WRITES_PER_TICK else 1, #writeQueue) do
1080
+ if stopped then
1081
+ break
1082
+ end
1083
+ local index, item = nextWrite(false, attempted)
1084
+ if index == nil or item == nil then
1085
+ break
1086
+ end
1087
+ if isErased(item.UserId) or item.State.LastScore == item.Score then
1088
+ dequeue(index, item)
1089
+ if not isErased(item.UserId) then
1090
+ Metrics.Add("LbWritesSkipped")
1091
+ end
1092
+ releaseWriteState(item.State)
1093
+ continue
1094
+ end
1095
+ local granted, release = claimBackground("SetIncrementSortedAsync")
1096
+ if not granted then
1097
+ break
1098
+ end
1099
+ dequeue(index, item)
1100
+ attempted[item.State] = true
1101
+ writeItem(item)
1102
+ release()
1103
+ end
1104
+ end
1105
+ end
1106
+
1107
+ -- Reads + refresh cycle -----------------------------------------------------------
1108
+
1109
+ -- Cache a resolved name, dropping TTL-lapsed entries once the map fills. Unbounded it
1110
+ -- grows one entry per distinct userId ever seen in a top-N, for the server's lifetime.
1111
+ local nameCacheCount = 0
1112
+ local function cacheName(userId: number, entry: { Name: string?, At: number })
1113
+ if nameCache[userId] == nil then
1114
+ nameCacheCount += 1
1115
+ end
1116
+ nameCache[userId] = entry
1117
+ if nameCacheCount >= NAME_CACHE_CAP then
1118
+ local now = Clock.Monotonic()
1119
+ local kept = 0
1120
+ for id, c in nameCache do
1121
+ local ttl = if c.Name then NAME_TTL else NAME_NEGATIVE_TTL
1122
+ if now - c.At >= ttl then
1123
+ nameCache[id] = nil
1124
+ else
1125
+ kept += 1
1126
+ end
1127
+ end
1128
+ nameCacheCount = kept
1129
+ -- TTL eviction alone does not bound the map when every entry is still fresh, so
1130
+ -- drop the oldest down to half the cap, amortizing this sort over cap/2 inserts.
1131
+ if nameCacheCount >= NAME_CACHE_CAP then
1132
+ local ordered: { { Id: number, At: number } } = {}
1133
+ for id, c in nameCache do
1134
+ table.insert(ordered, { Id = id, At = c.At })
1135
+ end
1136
+ table.sort(ordered, function(a: { Id: number, At: number }, b: { Id: number, At: number })
1137
+ return a.At < b.At
1138
+ end)
1139
+ local target = NAME_CACHE_CAP // 2
1140
+ for i = 1, #ordered - target do
1141
+ nameCache[ordered[i].Id] = nil
1142
+ end
1143
+ nameCacheCount = target
1144
+ end
1145
+ end
1146
+ end
1147
+
1148
+ local function resolveName(userId: number): string
1149
+ local cached = nameCache[userId]
1150
+ local now = Clock.Monotonic()
1151
+ if cached then
1152
+ local ttl = if cached.Name then NAME_TTL else NAME_NEGATIVE_TTL
1153
+ if now - cached.At < ttl then
1154
+ return cached.Name or "Unknown"
1155
+ end
1156
+ end
1157
+ local player = Players:GetPlayerByUserId(userId)
1158
+ if player then
1159
+ cacheName(userId, { Name = player.Name, At = now })
1160
+ return player.Name
1161
+ end
1162
+ local ok, name = pcall(function()
1163
+ return Players:GetNameFromUserIdAsync(userId)
1164
+ end)
1165
+ -- Negative caching: failed lookups are cached briefly.
1166
+ cacheName(userId, { Name = if ok then name else nil, At = now })
1167
+ return if ok then name else "Unknown"
1168
+ end
1169
+
1170
+ local function sendBoardTo(board: Board, entry: any)
1171
+ local w = Wire.NewWriter(64 + #board.Cache.Entries * 32)
1172
+ Wire.U8(w, Wire.Frames.Leaderboard)
1173
+ Wire.Str(w, board.Name)
1174
+ Wire.U8(w, #board.Cache.Entries)
1175
+ for _, item in board.Cache.Entries do
1176
+ Wire.F64(w, item.UserId)
1177
+ Wire.Str(w, item.Name)
1178
+ Wire.F64(w, item.Score)
1179
+ end
1180
+ local myRank = board.MyRanks[entry.UserId]
1181
+ local myScore = board.MyScores[entry.UserId]
1182
+ if myRank and myScore then
1183
+ Wire.U8(w, 1)
1184
+ Wire.Varint(w, myRank)
1185
+ Wire.F64(w, myScore)
1186
+ else
1187
+ Wire.U8(w, 0)
1188
+ end
1189
+ -- Only stamp what actually left: SentState is broadcastBoard's dedup key, so a
1190
+ -- refused board recorded as delivered is not resent until its content changes.
1191
+ if ctx.Replication.SendTo(entry, Wire.Finish(w)) then
1192
+ board.SentState[entry.UserId] = { Sig = board.Signature, Rank = myRank, Score = myScore }
1193
+ end
1194
+ end
1195
+
1196
+ -- Change-driven: a client only receives the board when its content or their
1197
+ -- own rank/score differs from what they were last sent.
1198
+ local function broadcastBoard(board: Board)
1199
+ if not board.Replicate then
1200
+ return
1201
+ end
1202
+ for _, entry in ctx.Persistence.Entries do
1203
+ if not entry.HandshakeReady then
1204
+ continue
1205
+ end
1206
+ local sent = board.SentState[entry.UserId]
1207
+ if
1208
+ sent == nil
1209
+ or sent.Sig ~= board.Signature
1210
+ or sent.Rank ~= board.MyRanks[entry.UserId]
1211
+ or sent.Score ~= board.MyScores[entry.UserId]
1212
+ then
1213
+ sendBoardTo(board, entry)
1214
+ end
1215
+ end
1216
+ end
1217
+
1218
+ -- Ranks the players on this server by the board's score, with no store behind it.
1219
+ local function refreshServerBoard(board: Board)
1220
+ local scored: { { UserId: number, Score: any } } = {}
1221
+ for _, entry in ctx.Persistence.Entries do
1222
+ if entry.State == "Ready" and entry.LiveData then
1223
+ local value: any = readStat(entry, board)
1224
+ if board.IsBig or type(value) == "number" then
1225
+ local score = periodScore(board, entry, value, nil, false)
1226
+ if score ~= nil then
1227
+ table.insert(scored, { UserId = entry.UserId, Score = score })
1228
+ end
1229
+ end
1230
+ end
1231
+ end
1232
+ table.sort(scored, function(a, b)
1233
+ if board.IsBig then
1234
+ return Big.compare(a.Score, b.Score) > 0
1235
+ end
1236
+ return a.Score > b.Score
1237
+ end)
1238
+ local entries = {}
1239
+ local signatureParts = {}
1240
+ table.clear(board.MyRanks)
1241
+ for rank, item in scored do
1242
+ board.MyRanks[item.UserId] = rank
1243
+ board.MyScores[item.UserId] = item.Score
1244
+ if rank <= board.Limit then
1245
+ table.insert(
1246
+ entries,
1247
+ { Rank = rank, UserId = item.UserId, Name = resolveName(item.UserId), Score = item.Score }
1248
+ )
1249
+ table.insert(signatureParts, `{item.UserId}:{item.Score}`)
1250
+ end
1251
+ end
1252
+ board.Cache = { Entries = entries, At = Clock.Monotonic() }
1253
+ board.LastReadAt, board.LastReadMono, board.LastReadError = Clock.Now(), Clock.Monotonic(), nil
1254
+ local previousSignature = board.Signature
1255
+ board.Signature = table.concat(signatureParts, "|")
1256
+ if board.Signature ~= previousSignature then
1257
+ local snapshot = table.create(#entries)
1258
+ for _, item in entries do
1259
+ table.insert(snapshot, copyEntry(board, item))
1260
+ end
1261
+ ctx.Signals.OnLeaderboard:Fire(board.Name, snapshot)
1262
+ end
1263
+ broadcastBoard(board)
1264
+ end
1265
+
1266
+ -- Ranked entries. resolveName yields, so the erase check repeats after the last name is in.
1267
+ local function pageEntries(board: Board, page: any): { any }
1268
+ local named = {}
1269
+ for _, item in page:GetCurrentPage() do
1270
+ -- Per row: a name lookup can yield past a Stop.
1271
+ if stopped then
1272
+ return {}
1273
+ end
1274
+ local userId = tonumber(item.key) or 0
1275
+ if isErased(userId) then
1276
+ continue
1277
+ end
1278
+ local score: any = if board.IsBig then unpackBig(board, item.value) else item.value / board.Scale
1279
+ table.insert(named, { Rank = 0, UserId = userId, Name = resolveName(userId), Score = score })
1280
+ end
1281
+ local entries = {}
1282
+ for _, item in named do
1283
+ if not isErased(item.UserId) then
1284
+ item.Rank = #entries + 1
1285
+ table.insert(entries, item)
1286
+ end
1287
+ end
1288
+ return entries
1289
+ end
1290
+
1291
+ -- Reads one period's store into an entry list, or nil on failure.
1292
+ local function readStore(board: Board, storeName: string, background: boolean?): { any }?
1293
+ local release: (() -> ())? = nil
1294
+ if background then
1295
+ local granted, free = claimBackground("GetSortedAsync")
1296
+ if not granted then
1297
+ return nil
1298
+ end
1299
+ release = free
1300
+ end
1301
+ local ok, page = pcall(function()
1302
+ return orderedStore(storeName):GetSortedAsync(false, board.Limit)
1303
+ end)
1304
+ if release then
1305
+ release()
1306
+ end
1307
+ if not ok then
1308
+ Metrics.Add("LbReadFailures")
1309
+ reportStoreFailure("LB_READ_FAIL", page, { Board = board.Name })
1310
+ return nil
1311
+ end
1312
+ return pageEntries(board, page)
1313
+ end
1314
+
1315
+ local function refreshPeriodicBoard(board: Board, background: boolean?, reserved: (() -> ())?): boolean
1316
+ -- Reserve the live-board read before spending budget on history.
1317
+ local release = reserved
1318
+ if background and release == nil then
1319
+ local granted, free = claimBackground("GetSortedAsync")
1320
+ if not granted then
1321
+ return false
1322
+ end
1323
+ release = free
1324
+ end
1325
+ local period: number? = if board.Period then currentPeriod(board.Period) else nil
1326
+ if period ~= nil and period ~= board.CachePeriod then
1327
+ board.CachePeriod = period
1328
+ board.PreviousReads = 0
1329
+ end
1330
+ if period ~= nil and board.PreviousReads < PREVIOUS_READS then
1331
+ local previous = readStore(board, storeNameFor(board, period - 1), background)
1332
+ if stopped then
1333
+ if release then
1334
+ release()
1335
+ end
1336
+ return true
1337
+ end
1338
+ if previous ~= nil then
1339
+ board.PreviousReads += 1
1340
+ board.PreviousCache = { Entries = previous, Period = period - 1 }
1341
+ end
1342
+ end
1343
+ local ok, page = pcall(function()
1344
+ return orderedStore(storeNameFor(board, period)):GetSortedAsync(false, board.Limit)
1345
+ end)
1346
+ if release then
1347
+ release()
1348
+ end
1349
+ if not ok then
1350
+ -- As in performWrite: a throttled read must not drive the global health gate.
1351
+ Metrics.Add("LbReadFailures")
1352
+ board.LastReadError = tostring(page)
1353
+ reportStoreFailure("LB_READ_FAIL", page, { Board = board.Name })
1354
+ return true
1355
+ end
1356
+
1357
+ local entries = pageEntries(board, page)
1358
+ if stopped then
1359
+ return true
1360
+ end
1361
+ local rankByUserId: { [number]: number } = {}
1362
+ local signatureParts = {}
1363
+ for _, item in entries do
1364
+ rankByUserId[item.UserId] = item.Rank
1365
+ table.insert(signatureParts, `{item.UserId}:{item.Score}`)
1366
+ end
1367
+ board.Cache = { Entries = entries, At = Clock.Monotonic() }
1368
+ board.LastReadAt, board.LastReadMono, board.LastReadError = Clock.Now(), Clock.Monotonic(), nil
1369
+ local previousSignature = board.Signature
1370
+ board.Signature = table.concat(signatureParts, "|")
1371
+
1372
+ -- Fire before broadcastBoard, which returns immediately for a non-replicated
1373
+ -- board: server-only is the default and those would have no other way to observe
1374
+ -- a refresh. Cloned so a listener cannot mutate what every later read serves.
1375
+ if board.Signature ~= previousSignature then
1376
+ local snapshot = table.create(#board.Cache.Entries)
1377
+ for _, item in board.Cache.Entries do
1378
+ table.insert(snapshot, copyEntry(board, item))
1379
+ end
1380
+ ctx.Signals.OnLeaderboard:Fire(board.Name, snapshot)
1381
+ end
1382
+
1383
+ -- Each online player's own rank/score, computed on the refresh cycle.
1384
+ for _, entry in ctx.Persistence.Entries do
1385
+ if entry.State == "Ready" and entry.LiveData then
1386
+ local value: any = readStat(entry, board)
1387
+ board.MyScores[entry.UserId] = if board.IsBig or type(value) == "number" then value else nil
1388
+ board.MyRanks[entry.UserId] = rankByUserId[entry.UserId]
1389
+ end
1390
+ end
1391
+
1392
+ broadcastBoard(board)
1393
+ return true
1394
+ end
1395
+
1396
+ local function wakeRefreshWaiters(board: Board)
1397
+ local waiters = board.RefreshWaiters
1398
+ board.RefreshWaiters = {}
1399
+ for _, thread in waiters do
1400
+ Sched.Resume(thread)
1401
+ end
1402
+ end
1403
+
1404
+ --- Parks until the refresh in flight finishes or the bundle stops.
1405
+ local function awaitRefresh(board: Board)
1406
+ table.insert(board.RefreshWaiters, coroutine.running())
1407
+ coroutine.yield()
1408
+ end
1409
+
1410
+ local function refreshBoard(board: Board, background: boolean?, reserved: (() -> ())?): boolean
1411
+ if board.Scope == "Server" then
1412
+ refreshServerBoard(board)
1413
+ return true
1414
+ end
1415
+ -- One refresh per board at a time and at most one waiting: later callers ride on
1416
+ -- the pending one, and nothing waiting starts after Stop.
1417
+ if board.Refreshing then
1418
+ if board.RefreshPending then
1419
+ repeat
1420
+ awaitRefresh(board)
1421
+ until stopped or not (board.Refreshing or board.RefreshPending)
1422
+ if reserved then
1423
+ reserved()
1424
+ end
1425
+ return true
1426
+ end
1427
+ board.RefreshPending = true
1428
+ repeat
1429
+ awaitRefresh(board)
1430
+ until stopped or not board.Refreshing
1431
+ board.RefreshPending = false
1432
+ end
1433
+ if stopped then
1434
+ if reserved then
1435
+ reserved()
1436
+ end
1437
+ return true
1438
+ end
1439
+ board.Refreshing = true
1440
+ local ok, result = pcall(refreshPeriodicBoard, board, background, reserved)
1441
+ if reserved then
1442
+ reserved()
1443
+ end
1444
+ board.Refreshing = false
1445
+ wakeRefreshWaiters(board)
1446
+ if not ok then
1447
+ error(result, 0)
1448
+ end
1449
+ return result
1450
+ end
1451
+
1452
+ -- Due-time scheduler: each board on its own cadence, with the initial due times
1453
+ -- staggered across the first cycle so boot does not fire every board at once.
1454
+ -- When each board next reads, monotonic; empty until the first cycle is scheduled.
1455
+ local dueAt: { [string]: number } = {}
1456
+
1457
+ local function refreshTick()
1458
+ local now = Clock.Monotonic()
1459
+ local dueBoards: { Board } = {}
1460
+ for boardName, board in boards do
1461
+ local due = dueAt[boardName]
1462
+ if due == nil or now >= due then
1463
+ table.insert(dueBoards, board)
1464
+ end
1465
+ end
1466
+ -- Claim budget for the oldest due board before spawning; keep denied boards overdue.
1467
+ table.sort(dueBoards, function(a, b)
1468
+ local left, right = dueAt[a.Name] or 0, dueAt[b.Name] or 0
1469
+ return if left == right then a.Name < b.Name else left < right
1470
+ end)
1471
+ for _, board in dueBoards do
1472
+ if board.Refreshing or board.RefreshPending then
1473
+ continue
1474
+ end
1475
+ local release: (() -> ())? = nil
1476
+ if board.Scope ~= "Server" then
1477
+ local granted, free = claimBackground("GetSortedAsync")
1478
+ if not granted then
1479
+ continue
1480
+ end
1481
+ release = free
1482
+ end
1483
+ dueAt[board.Name] = now + board.RefreshInterval
1484
+ Sched.Spawn(refreshBoard, board, true, release)
1485
+ end
1486
+ end
1487
+
1488
+ --- Test seam: one pass of the scheduler.
1489
+ function self.RefreshTick()
1490
+ refreshTick()
1491
+ end
1492
+
1493
+ local function refreshLoop()
1494
+ -- Attributes this loop's allocations to Scribe, as in writePacerLoop.
1495
+ Profile.MemoryCategory("Scribe")
1496
+ -- The jittered warm-up spreads the first refresh across a fleet booted by one
1497
+ -- deploy; the stagger below spreads boards within one server. Both are needed,
1498
+ -- and replacing the stagger with jitter would re-collide a server's own boards.
1499
+ Clock.Wait(Rng.Jitter(5))
1500
+ local index = 0
1501
+ local count = math.max(Util.count(boards), 1)
1502
+ for boardName, board in boards do
1503
+ dueAt[boardName] = Clock.Monotonic() + (board.RefreshInterval * index) / count
1504
+ index += 1
1505
+ end
1506
+ while not stopped do
1507
+ refreshTick()
1508
+ -- One draw per tick, not per re-arm. Drawing inside the board loop above would
1509
+ -- make the sequence depend on `boards` hash order, and jittering the tick
1510
+ -- decorrelates the re-arm anyway: `dueAt` inherits the drift in `now`.
1511
+ Clock.Wait(Rng.Jitter(1))
1512
+ end
1513
+ end
1514
+
1515
+ type Counts = { Pending: number, Retrying: number, Rejected: number }
1516
+ local function writeCounts(onlyBoard: Board?): { [Board]: Counts }
1517
+ local counts: { [Board]: Counts } = {}
1518
+ for _, states in writeStates do
1519
+ for key, state in states do
1520
+ local board = state.Board
1521
+ if onlyBoard ~= nil and board ~= onlyBoard then
1522
+ continue
1523
+ end
1524
+ local count = counts[board]
1525
+ if count == nil then
1526
+ count = { Pending = 0, Retrying = 0, Rejected = 0 }
1527
+ counts[board] = count
1528
+ end
1529
+ local waiting = state.InFlight or writeQueueMap[key] ~= nil
1530
+ if waiting or state.RejectedScore ~= nil then
1531
+ count.Pending += 1
1532
+ end
1533
+ if state.RejectedScore ~= nil then
1534
+ count.Rejected += 1
1535
+ elseif waiting and (state.Failures or 0) > 0 then
1536
+ count.Retrying += 1
1537
+ end
1538
+ end
1539
+ end
1540
+ return counts
1541
+ end
1542
+
1543
+ local function boardStatus(board: Board, count: Counts?, now: number): Types.LeaderboardStatusInfo
1544
+ local pending = if count then count.Pending else 0
1545
+ local retrying = if count then count.Retrying else 0
1546
+ local rejected = if count then count.Rejected else 0
1547
+ local age = if board.LastReadMono ~= nil then math.max(0, now - board.LastReadMono) else nil
1548
+ local stale = age ~= nil and age > 2 * board.RefreshInterval
1549
+ local status: Types.LeaderboardStatus = if retrying > 0
1550
+ or rejected > 0
1551
+ or board.LastReadError ~= nil
1552
+ or board.LastWriteError ~= nil
1553
+ or stale
1554
+ then "Degraded"
1555
+ elseif age == nil then "Starting"
1556
+ else "Healthy"
1557
+ return {
1558
+ Status = status,
1559
+ PendingWrites = pending,
1560
+ RetryingWrites = retrying,
1561
+ RejectedWrites = rejected,
1562
+ LastReadAt = board.LastReadAt,
1563
+ ReadAge = age,
1564
+ LastWriteAt = board.LastWriteAt,
1565
+ LastReadError = board.LastReadError,
1566
+ LastWriteError = board.LastWriteError,
1567
+ }
1568
+ end
1569
+
1570
+ local function diagnosticSnapshot(): { [string]: Types.LeaderboardStatusInfo }
1571
+ local counts, now = writeCounts(nil), Clock.Monotonic()
1572
+ local snapshot: { [string]: Types.LeaderboardStatusInfo } = {}
1573
+ for name, board in boards do
1574
+ snapshot[name] = boardStatus(board, counts[board], now)
1575
+ end
1576
+ return snapshot
1577
+ end
1578
+
1579
+ -- Called by Server.build once the full ctx is assembled, so neither loop ever runs
1580
+ -- against a half-constructed context.
1581
+ function self.Start()
1582
+ if started or stopped then
1583
+ return
1584
+ end
1585
+ started = true
1586
+ local any, global = false, false
1587
+ for _, board in boards do
1588
+ any = true
1589
+ if board.Scope ~= "Server" then
1590
+ global = true
1591
+ end
1592
+ end
1593
+ if global then
1594
+ pacerThread = Sched.Spawn(writePacerLoop)
1595
+ end
1596
+ if any then
1597
+ unregisterDiagnostics = Diagnostics.Register(diagnosticSnapshot)
1598
+ refreshThread = Sched.Spawn(refreshLoop)
1599
+ end
1600
+ end
1601
+
1602
+ --- Which workers run, and whether the pacer is parked.
1603
+ function self.Workers(): { Pacer: boolean, Refresh: boolean, PacerParked: boolean }
1604
+ return { Pacer = pacerThread ~= nil, Refresh = refreshThread ~= nil, PacerParked = pacerParked }
1605
+ end
1606
+
1607
+ -- Test seam: count retained score states.
1608
+ function self.WriteStateCount(): number
1609
+ local count = 0
1610
+ for _, states in writeStates do
1611
+ for _ in states do
1612
+ count += 1
1613
+ end
1614
+ end
1615
+ return count
1616
+ end
1617
+
1618
+ -- Release both loops. Cancelled as well as flagged, because a parked loop would
1619
+ -- otherwise keep a thread alive per bundle until its next wake.
1620
+ function self.Stop()
1621
+ if stopped then
1622
+ return
1623
+ end
1624
+ stopped = true
1625
+ if unregisterDiagnostics then
1626
+ unregisterDiagnostics()
1627
+ unregisterDiagnostics = nil
1628
+ end
1629
+ for _, thread in { pacerThread, refreshThread } do
1630
+ pcall(task.cancel, thread)
1631
+ end
1632
+ pacerThread, refreshThread = nil, nil
1633
+ for release in budgetReleases do
1634
+ release()
1635
+ end
1636
+ table.clear(writeStates)
1637
+ table.clear(activeUsers)
1638
+ for _, board in boards do
1639
+ wakeRefreshWaiters(board)
1640
+ end
1641
+ end
1642
+
1643
+ -- The OrderedDataStore a board reads and writes. Exposed so a test can pin the
1644
+ -- SigFigs namespacing, which is what keeps two key formats out of one store.
1645
+ function self.BoardStoreName(name: string, offset: number?): string?
1646
+ local board = boards[name]
1647
+ if not board then
1648
+ return nil
1649
+ end
1650
+ return storeNameFor(board, if board.Period then currentPeriod(board.Period) + (offset or 0) else nil)
1651
+ end
1652
+
1653
+ function self.CurrentPeriod(name: string): number?
1654
+ local board = boards[name]
1655
+ return if board and board.Period then currentPeriod(board.Period) else nil
1656
+ end
1657
+
1658
+ -- Whether boards resolved to the in-memory mock store. Exposed so a test can assert
1659
+ -- Leaderboards read the resolved Mode; board contents cannot, since a real store only
1660
+ -- happens to fail under the headless runner and in Studio the write lands.
1661
+ self.UsesMockStore = useMock
1662
+
1663
+ --- The mock ordered store behind a board, so a test can make its calls fail. Mock
1664
+ --- mode only: nil on a real store, which no test may reach.
1665
+ -- Every range a period change closed, then the live one. A record with no kind is taken
1666
+ -- to be in the board's current kind.
1667
+ local function eraseRanges(board: Board, record: any): { { K: string, First: number, Last: number } }
1668
+ local last = currentPeriod(board.Period :: string)
1669
+ local sweeps = {}
1670
+ if type(record) ~= "table" then
1671
+ return { { K = board.Period :: string, First = last, Last = last } }
1672
+ end
1673
+ for _, prior in (if type(record.Prior) == "table" then record.Prior else {}) :: { any } do
1674
+ if
1675
+ type(prior) == "table"
1676
+ and (prior.K == "Daily" or prior.K == "Weekly")
1677
+ and type(prior.First) == "number"
1678
+ and type(prior.Last) == "number"
1679
+ then
1680
+ table.insert(sweeps, { K = prior.K, First = prior.First, Last = prior.Last })
1681
+ end
1682
+ end
1683
+ local kind = if record.K == "Daily" or record.K == "Weekly" then record.K else board.Period :: string
1684
+ local first = if type(record.First) == "number" then record.First else last
1685
+ if kind == board.Period then
1686
+ table.insert(sweeps, { K = kind, First = first, Last = last })
1687
+ else
1688
+ table.insert(
1689
+ sweeps,
1690
+ { K = kind, First = first, Last = if type(record.P) == "number" then record.P else first }
1691
+ )
1692
+ table.insert(sweeps, { K = board.Period :: string, First = last, Last = last })
1693
+ end
1694
+ return sweeps
1695
+ end
1696
+
1697
+ --- A mock store by full name, for a period the board no longer uses.
1698
+ function self.MockStoreNamed(storeName: string): any?
1699
+ return if useMock then orderedStore(storeName) else nil
1700
+ end
1701
+
1702
+ function self.MockStoreFor(name: string, offset: number?): any?
1703
+ if not useMock then
1704
+ return nil
1705
+ end
1706
+ local storeName = self.BoardStoreName(name, offset)
1707
+ return if storeName then orderedStore(storeName) else nil
1708
+ end
1709
+
1710
+ function self.RefreshNow(name: string?)
1711
+ if name then
1712
+ local board = boards[name]
1713
+ if board then
1714
+ refreshBoard(board)
1715
+ end
1716
+ return
1717
+ end
1718
+ for _, board in boards do
1719
+ refreshBoard(board)
1720
+ end
1721
+ end
1722
+
1723
+ -- Called by Replication when a client completes the handshake: hand them
1724
+ -- the current cached replicated boards once, then only changes are broadcast.
1725
+ function self.OnClientReady(entry: any)
1726
+ for _, board in boards do
1727
+ if board.Replicate and board.Cache.At > 0 then
1728
+ sendBoardTo(board, entry)
1729
+ end
1730
+ end
1731
+ end
1732
+
1733
+ -- Player lifecycle ------------------------------------------------------------------
1734
+
1735
+ function self.OnLoad(entry: any)
1736
+ activeUsers[entry.UserId] = (activeUsers[entry.UserId] or 0) + 1
1737
+ local disconnects = {}
1738
+ for _, board in boards do
1739
+ -- Per-board isolation: one board's path failing at runtime must not kill
1740
+ -- the wiring of every remaining board for the whole session.
1741
+ local ok, err = pcall(function()
1742
+ local accessor = entry.Tree.Accessor
1743
+ for _, segment in board.StatPath do
1744
+ accessor = accessor[segment]
1745
+ end
1746
+ local value = accessor.Get()
1747
+ if board.IsBig or type(value) == "number" then
1748
+ self.Enqueue(board, entry, value)
1749
+ end
1750
+ table.insert(
1751
+ disconnects,
1752
+ -- Parenthesised to truncate the call to one value: `Changed` returns
1753
+ -- exactly one, the disconnect closure, but the accessor is `any`, so
1754
+ -- the solver sees a variadic tail and cannot pick a table.insert
1755
+ -- overload.
1756
+ (
1757
+ accessor.Changed(function(newValue: any, oldValue: any)
1758
+ if board.IsBig or type(newValue) == "number" then
1759
+ self.Enqueue(board, entry, newValue, oldValue)
1760
+ end
1761
+ end)
1762
+ )
1763
+ )
1764
+ end)
1765
+ if not ok then
1766
+ Log.Warn(
1767
+ "Leaderboards",
1768
+ "LB_STAT_RESOLVE_FAIL",
1769
+ `board "{board.Name}" stat did not resolve for this player: {tostring(err)}`,
1770
+ { Board = board.Name, UserId = entry.UserId }
1771
+ )
1772
+ end
1773
+ end
1774
+ statDisconnects[entry] = disconnects
1775
+ end
1776
+
1777
+ function self.OnUnload(entry: any)
1778
+ local disconnects = statDisconnects[entry]
1779
+ if disconnects then
1780
+ statDisconnects[entry] = nil
1781
+ for _, disconnect in disconnects do
1782
+ disconnect()
1783
+ end
1784
+ end
1785
+ -- Only if this is still the live entry for that user id. TargetUserId points every
1786
+ -- session at one profile, so two entries can share an id and either leaving would
1787
+ -- blank the other's. EntriesByUserId still points here when teardown calls in.
1788
+ if ctx.Persistence.EntriesByUserId[entry.UserId] == entry then
1789
+ for _, board in boards do
1790
+ board.MyRanks[entry.UserId] = nil
1791
+ board.MyScores[entry.UserId] = nil
1792
+ board.SentState[entry.UserId] = nil
1793
+ end
1794
+ end
1795
+ -- Flush the player's latest scores on leave.
1796
+ if entry.LiveData then
1797
+ for _, board in boards do
1798
+ local value: any = readStat(entry, board)
1799
+ if board.IsBig or type(value) == "number" then
1800
+ self.Enqueue(board, entry, value, nil, true)
1801
+ end
1802
+ end
1803
+ end
1804
+ if disconnects then
1805
+ local remaining = (activeUsers[entry.UserId] or 1) - 1
1806
+ activeUsers[entry.UserId] = if remaining > 0 then remaining else nil
1807
+ end
1808
+ local states = writeStates[entry.UserId]
1809
+ if states then
1810
+ for key, state in states do
1811
+ local queued = writeQueueMap[key]
1812
+ if queued then
1813
+ queued.Urgent = true
1814
+ end
1815
+ releaseWriteState(state)
1816
+ end
1817
+ end
1818
+ end
1819
+
1820
+ -- Public API --------------------------------------------------------------------------
1821
+
1822
+ -- Names are case-sensitive and an unknown one returns empty with no other signal, so a
1823
+ -- typo looks like a board that has not refreshed. Warn once per name in Studio.
1824
+ local warnedBoardNames: { [string]: boolean } = {}
1825
+ local function checkBoardName(name: string, caller: string)
1826
+ if ctx.DevMode and not boards[name] and not warnedBoardNames[name] then
1827
+ warnedBoardNames[name] = true
1828
+ Log.Warn(
1829
+ "Leaderboards",
1830
+ "LB_UNKNOWN_BOARD",
1831
+ `{caller}("{name}"): no board named "{name}" is declared in the Leaderboards option (names are case-sensitive); this always returns nothing`,
1832
+ { Board = name }
1833
+ )
1834
+ end
1835
+ end
1836
+
1837
+ function self.GetLeaderboard(name: string, limit: number?, offset: number?): { any }
1838
+ local board = boards[name]
1839
+ if not board then
1840
+ checkBoardName(name, "GetLeaderboard")
1841
+ return {}
1842
+ end
1843
+ local entries = board.Cache.Entries
1844
+ if offset ~= nil and offset ~= 0 then
1845
+ if offset ~= -1 then
1846
+ error(`Scribe.GetLeaderboard: offset must be 0 or -1, not {tostring(offset)}`, 2)
1847
+ end
1848
+ -- A server or lifetime board has no previous period.
1849
+ local previous = board.PreviousCache
1850
+ if board.Period == nil or previous == nil or previous.Period ~= currentPeriod(board.Period) - 1 then
1851
+ return {}
1852
+ end
1853
+ entries = previous.Entries
1854
+ end
1855
+ local out = {}
1856
+ for i = 1, math.min(limit or board.Limit, #entries) do
1857
+ table.insert(out, copyEntry(board, entries[i]))
1858
+ end
1859
+ return out
1860
+ end
1861
+
1862
+ function self.GetStatus(name: string): Types.LeaderboardStatusInfo?
1863
+ local board = boards[name]
1864
+ if not board then
1865
+ checkBoardName(name, "GetLeaderboardStatus")
1866
+ return nil
1867
+ end
1868
+ return boardStatus(board, writeCounts(board)[board], Clock.Monotonic())
1869
+ end
1870
+
1871
+ function self.GetRefreshIn(name: string): number?
1872
+ if not boards[name] then
1873
+ checkBoardName(name, "GetLeaderboardRefreshIn")
1874
+ return nil
1875
+ end
1876
+ local due = dueAt[name]
1877
+ if due == nil then
1878
+ return nil
1879
+ end
1880
+ return math.max(0, due - Clock.Monotonic())
1881
+ end
1882
+
1883
+ function self.GetResetIn(name: string): number?
1884
+ local board = boards[name]
1885
+ if not board then
1886
+ checkBoardName(name, "GetLeaderboardResetIn")
1887
+ return nil
1888
+ end
1889
+ return if board.Period then periodEndsIn(board.Period) else nil
1890
+ end
1891
+
1892
+ function self.GetMyRank(player: Player, name: string): number?
1893
+ local board = boards[name]
1894
+ local entry = ctx.Persistence.Entries[player]
1895
+ if not board then
1896
+ checkBoardName(name, "GetMyRank")
1897
+ end
1898
+ if not board or not entry then
1899
+ return nil
1900
+ end
1901
+ return board.MyRanks[entry.UserId]
1902
+ end
1903
+
1904
+ -- Drain the whole queue synchronously within a deadline.
1905
+ function self.FlushAllBlocking(budget: number)
1906
+ local deadline = Clock.Monotonic() + budget
1907
+ local flushed = 0
1908
+ local attempts: { [WriteState]: number } = {}
1909
+ local exhausted: { [WriteState]: boolean } = {}
1910
+ while Clock.Monotonic() < deadline do
1911
+ local index, item = nextWrite(true, exhausted)
1912
+ if index == nil or item == nil then
1913
+ if activeWrites > 0 then
1914
+ Clock.Wait(math.min(0.05, math.max(0, deadline - Clock.Monotonic())))
1915
+ continue
1916
+ end
1917
+ break
1918
+ end
1919
+ dequeue(index, item)
1920
+ if isErased(item.UserId) or item.State.LastScore == item.Score then
1921
+ if not isErased(item.UserId) then
1922
+ Metrics.Add("LbWritesSkipped")
1923
+ end
1924
+ releaseWriteState(item.State)
1925
+ continue
1926
+ end
1927
+ flushed += 1
1928
+ local count = (attempts[item.State] or 0) + 1
1929
+ attempts[item.State] = count
1930
+ exhausted[item.State] = count >= 3
1931
+ writeItem(item)
1932
+ end
1933
+ Log.Info("Leaderboards", "LB_SHUTDOWN_FLUSH", "leaderboard queue drained on shutdown", {
1934
+ Flushed = flushed,
1935
+ Remaining = #writeQueue,
1936
+ })
1937
+ end
1938
+
1939
+ -- GDPR: remove the user from every board. Returns (ok, err); a false ok
1940
+ -- means at least one board's RemoveAsync failed and the caller must retry.
1941
+ -- `ranges` is the profile's Boards record; a periodic board is swept from First to now.
1942
+ --- Removes `userId` from an entry list and renumbers the rest; true if it was there.
1943
+ local function pruneEntries(entries: { any }, userId: number): boolean
1944
+ local pruned = false
1945
+ for i = #entries, 1, -1 do
1946
+ if entries[i].UserId == userId then
1947
+ table.remove(entries, i)
1948
+ pruned = true
1949
+ end
1950
+ end
1951
+ if pruned then
1952
+ for i, item in entries do
1953
+ item.Rank = i
1954
+ end
1955
+ end
1956
+ return pruned
1957
+ end
1958
+
1959
+ --- The third return is true when the budget never freed up.
1960
+ local function removeOne(storeName: string, key: string): (boolean, string?, boolean)
1961
+ local release: (() -> ())? = nil
1962
+ if budgetPolicy then
1963
+ local granted, free = Budget.Await("OrderedRemove", 1, ERASE_BUDGET_TIMEOUT)
1964
+ if not granted then
1965
+ return false, "the OrderedRemove budget did not free up in time", true
1966
+ end
1967
+ release = free
1968
+ end
1969
+ Metrics.Add("LbEraseRemoves")
1970
+ local ok, err = pcall(function()
1971
+ orderedStore(storeName):RemoveAsync(key)
1972
+ end)
1973
+ if release ~= nil then
1974
+ release()
1975
+ end
1976
+ return ok, if ok then nil else tostring(err), false
1977
+ end
1978
+
1979
+ --- `progress`, when given, is `{ Done, Cursors, Save }`; `Save` persists the other two and
1980
+ --- answers false when the sweep must stop. It runs every 25 removals, every
1981
+ --- ERASE_HEARTBEAT seconds, and on any failure or completion.
1982
+ function self.EraseUser(userId: number, ranges: { [string]: any }?, progress: any?): (boolean, string?)
1983
+ -- Tombstone first, so an already-dequeued pacer write cannot resurrect the score
1984
+ -- after RemoveAsync. Held long enough to outlive that write plus its retries.
1985
+ erasedUsers[userId] = Clock.Monotonic() + 300
1986
+ writeStates[userId] = nil
1987
+
1988
+ -- Drop any still-queued writes for this user, or the pacer would
1989
+ -- SetAsync their score back into a board we just RemoveAsync'd.
1990
+ for i = #writeQueue, 1, -1 do
1991
+ local queued = writeQueue[i]
1992
+ if queued.UserId == userId then
1993
+ writeQueueMap[`{queued.Board.Name}|{userId}|{queued.StoreName}`] = nil
1994
+ table.remove(writeQueue, i)
1995
+ end
1996
+ end
1997
+ Metrics.Set("LbQueueDepth", #writeQueue)
1998
+
1999
+ local key = tostring(userId)
2000
+ local failed: string? = nil
2001
+ -- Reported once below rather than per board: the log folds by subject, so N
2002
+ -- per-board lines collapse into the first, losing which boards still hold the data.
2003
+ local failedBoards: { string }? = nil
2004
+ local halted = false
2005
+ local lost = false
2006
+ local lastSave = Clock.Monotonic()
2007
+ local function checkpoint(): boolean
2008
+ lastSave = Clock.Monotonic()
2009
+ if progress == nil or progress.Save() then
2010
+ return true
2011
+ end
2012
+ lost = true
2013
+ return false
2014
+ end
2015
+ local function heartbeatDue(): boolean
2016
+ return progress ~= nil and Clock.Monotonic() - lastSave >= ERASE_HEARTBEAT
2017
+ end
2018
+ for _, board in boards do
2019
+ -- A server board stores nothing; the cache prune below is its whole erase.
2020
+ local ok, err = true, nil
2021
+ local done = progress ~= nil and progress.Done[board.Name] == true
2022
+ if board.Scope == "Server" or done or halted or lost then
2023
+ ok = true
2024
+ elseif board.Period == nil then
2025
+ local budgetOut
2026
+ ok, err, budgetOut = removeOne(board.StoreName, key)
2027
+ if progress then
2028
+ if ok then
2029
+ progress.Done[board.Name] = true
2030
+ if heartbeatDue() then
2031
+ checkpoint()
2032
+ end
2033
+ else
2034
+ checkpoint()
2035
+ end
2036
+ end
2037
+ halted = budgetOut
2038
+ else
2039
+ local cursor = if progress then progress.Cursors[board.Name] else nil
2040
+ local removed = 0
2041
+ for index, sweep in eraseRanges(board, if ranges then ranges[board.Name] else nil) do
2042
+ if not ok or lost then
2043
+ break
2044
+ end
2045
+ local from = sweep.First
2046
+ if type(cursor) == "table" and type(cursor.Range) == "number" then
2047
+ if index < cursor.Range then
2048
+ continue
2049
+ elseif index == cursor.Range and type(cursor.Next) == "number" then
2050
+ from = math.max(from, cursor.Next)
2051
+ end
2052
+ end
2053
+ for period = from, sweep.Last do
2054
+ local okOne, errOne, budgetOut = removeOne(storeNameForKind(board, sweep.K, period), key)
2055
+ if not okOne then
2056
+ ok, err = false, errOne
2057
+ halted = budgetOut
2058
+ if progress then
2059
+ progress.Cursors[board.Name] = { Range = index, Next = period }
2060
+ checkpoint()
2061
+ end
2062
+ break
2063
+ end
2064
+ removed += 1
2065
+ if
2066
+ progress
2067
+ and period < sweep.Last
2068
+ and (removed % ERASE_PROGRESS_EVERY == 0 or heartbeatDue())
2069
+ then
2070
+ progress.Cursors[board.Name] = { Range = index, Next = period + 1 }
2071
+ if not checkpoint() then
2072
+ break
2073
+ end
2074
+ end
2075
+ end
2076
+ end
2077
+ if ok and not lost and progress then
2078
+ progress.Cursors[board.Name] = nil
2079
+ progress.Done[board.Name] = true
2080
+ checkpoint()
2081
+ end
2082
+ end
2083
+ if not ok then
2084
+ -- Attempt every board, but remember the failure so erase can't
2085
+ -- report success while personal data is retained.
2086
+ failed = tostring(err)
2087
+ failedBoards = failedBoards or {}
2088
+ table.insert(failedBoards :: { string }, board.Name)
2089
+ end
2090
+ board.MyRanks[userId] = nil
2091
+ board.MyScores[userId] = nil
2092
+ board.SentState[userId] = nil
2093
+ -- The caches too, or the user is served until the next refresh.
2094
+ local entries = board.Cache.Entries
2095
+ if pruneEntries(entries, userId) then
2096
+ -- A new signature, so stale SentState cannot suppress the broadcast.
2097
+ local signatureParts = {}
2098
+ for _, item in entries do
2099
+ table.insert(signatureParts, `{item.UserId}:{item.Score}`)
2100
+ end
2101
+ board.Signature = table.concat(signatureParts, "|")
2102
+ broadcastBoard(board)
2103
+ end
2104
+ if board.PreviousCache ~= nil then
2105
+ pruneEntries(board.PreviousCache.Entries, userId)
2106
+ end
2107
+ end
2108
+ if failedBoards ~= nil then
2109
+ -- Board names as a string, not an array: Log trims an oversized context down
2110
+ -- to its scalar fields, so an array is the first thing dropped.
2111
+ Failure.Report({
2112
+ Subsystem = "Leaderboards",
2113
+ Key = tostring(userId),
2114
+ Error = failed,
2115
+ Level = "Error",
2116
+ Category = "Leaderboards",
2117
+ Code = "LB_ERASE_FAIL",
2118
+ Message = tostring(failed),
2119
+ Context = {
2120
+ UserId = userId,
2121
+ Boards = table.concat(failedBoards :: { string }, ", "),
2122
+ BoardCount = #(failedBoards :: { string }),
2123
+ },
2124
+ })
2125
+ end
2126
+ -- Evict the resolved name so it is neither re-served nor re-broadcast.
2127
+ if nameCache[userId] ~= nil then
2128
+ nameCache[userId] = nil
2129
+ nameCacheCount -= 1
2130
+ end
2131
+ if lost then
2132
+ return false, "the erase was finished or replaced elsewhere"
2133
+ end
2134
+ if failed then
2135
+ return false, `a leaderboard erase failed: {failed}`
2136
+ end
2137
+ return true, nil
2138
+ end
2139
+
2140
+ return self
2141
+ end
2142
+
2143
+ return Leaderboards