@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,377 @@
1
+ --!strict
2
+ -- DataStore request budgets: what the engine says is left, whether a deferrable
3
+ -- background request should wait, and a FIFO queue for callers willing to wait.
4
+
5
+ local Clock = require(script.Parent.Clock)
6
+ local Sched = require(script.Parent.Sched)
7
+ local Metrics = require(script.Parent.Metrics)
8
+ local Defaults = require(script.Parent.Defaults)
9
+
10
+ local Budget = {}
11
+
12
+ -- The request types Scribe's own traffic spends. Saves ride UpdateAsync;
13
+ -- leaderboards ride the two Sorted pools and OrderedRemove, which are separate
14
+ -- allowances, so gating a leaderboard write can never starve a save.
15
+ local REQUEST_TYPES = {
16
+ "GetAsync",
17
+ "SetIncrementAsync",
18
+ "UpdateAsync",
19
+ "GetSortedAsync",
20
+ "SetIncrementSortedAsync",
21
+ "OrderedRemove",
22
+ }
23
+
24
+ export type Snapshot = {
25
+ Available: boolean, -- false when the engine could not be asked at all
26
+ Reason: string?, -- why not, when Available is false
27
+ Budgets: { [string]: number }, -- remaining requests, by DataStoreRequestType name
28
+ At: number,
29
+ }
30
+
31
+ -- Resolved per call, never stored. A cached handle latches whatever one unlucky
32
+ -- pcall caught, a module-load `game:GetService` cannot be retried, and a simulated
33
+ -- server without a disk has no DataStoreService at all, so a stored handle would
34
+ -- take the whole bundle down at require time.
35
+ local function service(): (any?, string?)
36
+ local ok, resolved = pcall(function()
37
+ return game:GetService("DataStoreService")
38
+ end)
39
+ if not ok or resolved == nil then
40
+ return nil, "DataStoreService is unavailable"
41
+ end
42
+ return resolved, nil
43
+ end
44
+
45
+ -- Test seam: a spec drives the pump against a budget it controls. nil restores the
46
+ -- engine, and Reset clears it.
47
+ local probe: ((requestType: string) -> number?)? = nil
48
+ local playerCountProbe: (() -> number)? = nil
49
+
50
+ function Budget.SetProbe(fn: ((requestType: string) -> number?)?, countPlayers: (() -> number)?)
51
+ probe = fn
52
+ playerCountProbe = countPlayers
53
+ end
54
+
55
+ --- Requests left for one type, or nil when the engine cannot answer. nil and 0 are
56
+ --- different: 0 means the allowance is spent, nil means the question could not be
57
+ --- asked, and a gate that reads nil as 0 stalls forever in a headless or
58
+ --- API-disabled environment.
59
+ function Budget.Remaining(requestType: string): number?
60
+ if probe ~= nil then
61
+ return probe(requestType)
62
+ end
63
+ local handle = service()
64
+ if handle == nil then
65
+ return nil
66
+ end
67
+ local ok, value = pcall(function()
68
+ return handle:GetRequestBudgetForRequestType((Enum :: any).DataStoreRequestType[requestType])
69
+ end)
70
+ if not ok or type(value) ~= "number" or value ~= value then
71
+ return nil
72
+ end
73
+ return value
74
+ end
75
+
76
+ --- Everything Budget.Remaining can answer, in one record.
77
+ function Budget.Snapshot(): Snapshot
78
+ local handle, reason = service()
79
+ if handle == nil then
80
+ return { Available = false, Reason = reason, Budgets = {}, At = Clock.Now() }
81
+ end
82
+ local budgets: { [string]: number } = {}
83
+ local answered = 0
84
+ for _, requestType in REQUEST_TYPES do
85
+ local value = Budget.Remaining(requestType)
86
+ if value ~= nil then
87
+ budgets[requestType] = value
88
+ answered += 1
89
+ end
90
+ end
91
+ if answered == 0 then
92
+ -- The service exists but answers nothing (Studio with API access off, or a
93
+ -- stub): a table of zeroes would read as a real exhausted allowance.
94
+ return {
95
+ Available = false,
96
+ Reason = "DataStoreService did not answer any request type",
97
+ Budgets = {},
98
+ At = Clock.Now(),
99
+ }
100
+ end
101
+ return { Available = true, Reason = nil, Budgets = budgets, At = Clock.Now() }
102
+ end
103
+
104
+ -- Pacing ----------------------------------------------------------------------
105
+ --
106
+ -- For a caller that may spend many requests for one player (ImportLegacyData). Without
107
+ -- a queue, N joiners poll independently and all fire the moment the allowance frees.
108
+ -- Only the head is ever considered, so FIFO is structural. One queue PER REQUEST TYPE:
109
+ -- the pools are separate allowances, so an exhausted one must not block another.
110
+
111
+ local POLL_INTERVAL = 1
112
+ -- Backstop for callers that never release. Over-counting delays, under-counting brings
113
+ -- the herd back, so it errs high; the exact value stops mattering once callers release.
114
+ local GRANT_TTL = 4
115
+
116
+ -- Stands in when nothing was granted, so a caller can release unconditionally.
117
+ local function noRelease() end
118
+
119
+ type Waiter = {
120
+ Thread: thread,
121
+ Count: number,
122
+ Deadline: number,
123
+ EnqueuedAt: number,
124
+ -- A predicate, not a flag: the caller is suspended inside Await with nowhere to set
125
+ -- one from.
126
+ ShouldCancel: (() -> boolean)?,
127
+ OnState: ((waiting: boolean) -> ())?,
128
+ -- Read by Await when the pump settled it on the calling stack, before it yielded.
129
+ Result: boolean?,
130
+ -- Set by the pump when it granted, so Await can hand the release to its caller.
131
+ Release: (() -> ())?,
132
+ }
133
+
134
+ local queues: { [string]: { Waiter } } = {}
135
+ local pumping: { [string]: boolean } = {}
136
+ -- Granted but presumed unspent. Budget.Remaining reads the ENGINE, which has not moved
137
+ -- between a grant and that caller issuing its request, so granting the next one off the
138
+ -- same reading over-grants.
139
+ local outstanding: { [string]: { { Count: number, At: number, InFlight: boolean } } } = {}
140
+ -- Held back from pacing callers, sized by the server.
141
+ local reserves: { [string]: number } = {}
142
+
143
+ --- Sum of unreleased requests and foreground grants still inside GRANT_TTL.
144
+ local function outstandingFor(requestType: string): number
145
+ local held = outstanding[requestType]
146
+ if held == nil then
147
+ return 0
148
+ end
149
+ local now = Clock.Monotonic()
150
+ local total, keep = 0, 1
151
+ for i = 1, #held do
152
+ local entry = held[i]
153
+ if entry.InFlight or now - entry.At < GRANT_TTL then
154
+ held[keep] = entry
155
+ keep += 1
156
+ total += entry.Count
157
+ end
158
+ end
159
+ for i = #held, keep, -1 do
160
+ held[i] = nil
161
+ end
162
+ return total
163
+ end
164
+
165
+ --- Records a grant and returns its release. By identity: outstandingFor compacts the
166
+ --- list in place, so a position taken now means nothing later.
167
+ local function debit(requestType: string, count: number, inFlight: boolean?): () -> ()
168
+ local held = outstanding[requestType]
169
+ if held == nil then
170
+ held = {}
171
+ outstanding[requestType] = held
172
+ end
173
+ local entry = { Count = count, At = Clock.Monotonic(), InFlight = inFlight == true }
174
+ table.insert(held, entry)
175
+ local released = false
176
+ return function()
177
+ -- Repeat calls are no-ops.
178
+ if released then
179
+ return
180
+ end
181
+ released = true
182
+ local current = outstanding[requestType]
183
+ local index = if current ~= nil then table.find(current, entry) else nil
184
+ if current ~= nil and index ~= nil then
185
+ table.remove(current, index)
186
+ end
187
+ end
188
+ end
189
+
190
+ --- What a pacing caller may take now, or nil when the engine cannot be asked. nil and
191
+ --- 0 differ: reading nil as 0 parks the caller forever in a headless server.
192
+ local function spare(requestType: string): number?
193
+ local remaining = Budget.Remaining(requestType)
194
+ if remaining == nil then
195
+ return nil
196
+ end
197
+ return remaining - outstandingFor(requestType) - (reserves[requestType] or 0)
198
+ end
199
+
200
+ -- Shared per-server limit; other scripts and experience-wide limits are separate.
201
+ -- The token bucket also bounds requests when the engine budget is unavailable.
202
+ local BACKGROUND_FRACTION = 0.8
203
+ type BackgroundRate = { Base: number, PerPlayer: number, Burst: number, MinReserve: number }
204
+ local BACKGROUND_RATES: { [string]: BackgroundRate } = {
205
+ GetSortedAsync = { Base = 5, PerPlayer = 2, Burst = 2, MinReserve = 2 },
206
+ SetIncrementSortedAsync = { Base = 30, PerPlayer = 5, Burst = 8, MinReserve = 5 },
207
+ }
208
+
209
+ type BackgroundBucket = { Tokens: number, At: number, Rate: number }
210
+ local background: { [string]: BackgroundBucket } = {}
211
+
212
+ local function playerCount(): number
213
+ if playerCountProbe then
214
+ return math.max(0, playerCountProbe())
215
+ end
216
+ local ok, players = pcall(function()
217
+ return game:GetService("Players"):GetPlayers()
218
+ end)
219
+ return if ok then #players else 0
220
+ end
221
+
222
+ --- Claims one background request. Always release after the request, including failures.
223
+ --- Release clears the reservation; it does not refund the rate token.
224
+ function Budget.TryBackground(requestType: string): (boolean, () -> ())
225
+ local config = BACKGROUND_RATES[requestType]
226
+ assert(config ~= nil, `unsupported background budget {requestType}`)
227
+ local limit = config.Base + config.PerPlayer * playerCount()
228
+ local rate = limit * BACKGROUND_FRACTION / 60
229
+ local now = Clock.Monotonic()
230
+ local bucket = background[requestType]
231
+ if bucket == nil then
232
+ bucket = { Tokens = config.Burst, At = now, Rate = rate }
233
+ background[requestType] = bucket
234
+ else
235
+ -- Refill at the old rate so joins don't add retroactive credit.
236
+ bucket.Tokens = math.min(config.Burst, bucket.Tokens + math.max(0, now - bucket.At) * bucket.Rate)
237
+ bucket.At = now
238
+ bucket.Rate = rate
239
+ end
240
+ if bucket.Tokens < 1 then
241
+ return false, noRelease
242
+ end
243
+ -- Let queued foreground requests go first.
244
+ local queue = queues[requestType]
245
+ if queue ~= nil and #queue > 0 then
246
+ return false, noRelease
247
+ end
248
+ local remaining = Budget.Remaining(requestType)
249
+ local reserve = math.max(config.MinReserve, math.ceil(limit / 5), reserves[requestType] or 0)
250
+ if remaining ~= nil and remaining == remaining and remaining - outstandingFor(requestType) - reserve < 1 then
251
+ return false, noRelease
252
+ end
253
+ bucket.Tokens -= 1
254
+ return true, debit(requestType, 1, true)
255
+ end
256
+
257
+ --- Remove the head, record the outcome, then resume it.
258
+ local function waiting(): number
259
+ local total = 0
260
+ for _, queue in queues do
261
+ total += #queue
262
+ end
263
+ return total
264
+ end
265
+
266
+ local function settle(queue: { Waiter }, head: Waiter, result: boolean)
267
+ table.remove(queue, 1)
268
+ Metrics.Set("BudgetWaiters", waiting())
269
+ Metrics.Observe("BudgetWaitSeconds", Clock.Monotonic() - head.EnqueuedAt)
270
+ Metrics.Add(if result then "BudgetGranted" else "BudgetTimedOut")
271
+ head.Result = result
272
+ if head.OnState then
273
+ head.OnState(false)
274
+ end
275
+ -- Spawn is immediate, so the pump can run on the waiter's own stack before it has
276
+ -- yielded. That waiter reads Result; resuming it here raises.
277
+ if coroutine.status(head.Thread) == "suspended" then
278
+ Sched.Resume(head.Thread, result)
279
+ end
280
+ end
281
+
282
+ --- One pump per queue, never a thread per waiter. Only the head is examined, so a
283
+ --- caller cannot be overtaken however small the request behind it.
284
+ local function pump(requestType: string)
285
+ local queue = queues[requestType]
286
+ while queue ~= nil and #queue > 0 do
287
+ local head = queue[1]
288
+ local cancelled = head.ShouldCancel ~= nil and head.ShouldCancel()
289
+ if cancelled or Clock.Monotonic() >= head.Deadline then
290
+ -- False, and WITHOUT a debit: a caller going away must unwind rather than park
291
+ -- inside a hook still holding its session, and its allowance goes to the next.
292
+ settle(queue, head, false)
293
+ else
294
+ local available = spare(requestType)
295
+ -- nil grants: the engine will never answer, so parking is forever.
296
+ if available == nil or available >= head.Count then
297
+ head.Release = debit(requestType, head.Count)
298
+ settle(queue, head, true)
299
+ else
300
+ Clock.Wait(POLL_INTERVAL)
301
+ end
302
+ end
303
+ end
304
+ pumping[requestType] = false
305
+ end
306
+
307
+ --- Hold `count` requests of this type back from pacing callers.
308
+ function Budget.SetReserve(requestType: string, count: number)
309
+ reserves[requestType] = math.max(0, count)
310
+ end
311
+
312
+ --- Yield until `count` requests are spare, or `timeout` passes. `onState(waiting)`
313
+ --- reports entering and leaving the queue, which is what surfaces a throttled caller.
314
+ function Budget.Await(
315
+ requestType: string,
316
+ count: number?,
317
+ timeout: number?,
318
+ onState: ((waiting: boolean) -> ())?,
319
+ shouldCancel: (() -> boolean)?
320
+ ): (boolean, () -> ())
321
+ local want = math.max(1, count or 1)
322
+ local queue = queues[requestType]
323
+ -- Only with nobody queued: behind a queue it would let a late caller jump everyone.
324
+ if queue == nil or #queue == 0 then
325
+ local available = spare(requestType)
326
+ if available == nil or available >= want then
327
+ Metrics.Add("BudgetGranted")
328
+ return true, debit(requestType, want)
329
+ end
330
+ end
331
+
332
+ if queue == nil then
333
+ queue = {}
334
+ queues[requestType] = queue
335
+ end
336
+ local waiter: Waiter = {
337
+ Thread = coroutine.running(),
338
+ Count = want,
339
+ Deadline = Clock.Monotonic() + (timeout or Defaults.AwaitBudget),
340
+ EnqueuedAt = Clock.Monotonic(),
341
+ ShouldCancel = shouldCancel,
342
+ OnState = onState,
343
+ Result = nil,
344
+ }
345
+ table.insert(queue, waiter)
346
+ Metrics.Add("BudgetQueued")
347
+ Metrics.Set("BudgetWaiters", waiting())
348
+ if onState then
349
+ onState(true)
350
+ end
351
+ if not pumping[requestType] then
352
+ pumping[requestType] = true
353
+ Sched.Spawn(pump, requestType)
354
+ end
355
+ -- A pump that settled this waiter on its first pass ran on this stack, so yielding
356
+ -- now would never return. Read the outcome: a zero timeout settles false there.
357
+ if waiter.Result ~= nil then
358
+ return waiter.Result, waiter.Release or noRelease
359
+ end
360
+ local granted = coroutine.yield()
361
+ return granted, waiter.Release or noRelease
362
+ end
363
+
364
+ --- Module-global, because the allowance is per process rather than per bundle, so a
365
+ --- test that paces has to reset.
366
+ function Budget.Reset()
367
+ queues = {}
368
+ pumping = {}
369
+ outstanding = {}
370
+ reserves = {}
371
+ background = {}
372
+ Budget.SetProbe(nil)
373
+ end
374
+
375
+ Budget.REQUEST_TYPES = REQUEST_TYPES
376
+
377
+ return Budget
@@ -0,0 +1,75 @@
1
+ --!strict
2
+ -- The clock seam: every time reading and timed wait goes through here, so a test can
3
+ -- replace them and fast-forward. Keep their purposes separate:
4
+ -- Now() wall time (os.time). For anything persisted or compared across servers;
5
+ -- it can jump when corrected, so never measure an interval with it.
6
+ -- Monotonic() a steady process timer (os.clock). For intervals in one session; never
7
+ -- persist it.
8
+ -- ServerNow() synchronized server time for client countdown displays.
9
+ -- ProfileStore reaches the clock only through globals, so loading it under a per-server
10
+ -- environment (test/Sim/Env.luau) virtualises it without a fork.
11
+
12
+ local Clock = {}
13
+
14
+ export type Impl = {
15
+ Now: (() -> number)?,
16
+ ServerNow: (() -> number)?,
17
+ Monotonic: (() -> number)?,
18
+ Wait: ((seconds: number?) -> number)?,
19
+ Delay: ((seconds: number, fn: (...any) -> (), ...any) -> thread)?,
20
+ }
21
+
22
+ -- Held separately so Reset can restore them. os.time is wrapped because its Roblox
23
+ -- signature is `(DateTypeArg?) -> number`, which does not satisfy `() -> number`;
24
+ -- widening Impl to match would force every virtual clock to declare that parameter.
25
+ local DEFAULT_NOW: () -> number = function()
26
+ return os.time()
27
+ end
28
+ local DEFAULT_SERVER_NOW: () -> number = function()
29
+ return game:GetService("Workspace"):GetServerTimeNow()
30
+ end
31
+ local DEFAULT_MONOTONIC: () -> number = os.clock
32
+ local DEFAULT_WAIT: (seconds: number?) -> number = task.wait
33
+ local DEFAULT_DELAY: (seconds: number, fn: (...any) -> (), ...any) -> thread = task.delay
34
+
35
+ Clock.Now = DEFAULT_NOW
36
+ Clock.ServerNow = DEFAULT_SERVER_NOW
37
+ Clock.Monotonic = DEFAULT_MONOTONIC
38
+ Clock.Wait = DEFAULT_WAIT
39
+ Clock.Delay = DEFAULT_DELAY
40
+
41
+ --- Replace clock functions. A virtual Now also supplies ServerNow unless overridden.
42
+ ---
43
+ --- A replacement `Wait` must still yield. Scribe's background loops are shaped
44
+ --- `while ... do Clock.Wait(n) ... end`, so a Wait that returns without yielding
45
+ --- hangs the process with nothing to point at. Yield without sleeping instead.
46
+ function Clock.Install(impl: Impl)
47
+ if impl.Now ~= nil then
48
+ Clock.Now = impl.Now
49
+ Clock.ServerNow = impl.Now
50
+ end
51
+ if impl.ServerNow ~= nil then
52
+ Clock.ServerNow = impl.ServerNow
53
+ end
54
+ if impl.Monotonic ~= nil then
55
+ Clock.Monotonic = impl.Monotonic
56
+ end
57
+ if impl.Wait ~= nil then
58
+ Clock.Wait = impl.Wait
59
+ end
60
+ if impl.Delay ~= nil then
61
+ Clock.Delay = impl.Delay
62
+ end
63
+ end
64
+
65
+ --- Restore defaults. A test that installs must reset, or it leaks a virtual clock
66
+ --- into every spec that runs after it.
67
+ function Clock.Reset()
68
+ Clock.Now = DEFAULT_NOW
69
+ Clock.ServerNow = DEFAULT_SERVER_NOW
70
+ Clock.Monotonic = DEFAULT_MONOTONIC
71
+ Clock.Wait = DEFAULT_WAIT
72
+ Clock.Delay = DEFAULT_DELAY
73
+ end
74
+
75
+ return Clock
@@ -0,0 +1,17 @@
1
+ --!strict
2
+ -- Process-scoped configuration. ProfileStore's AUTO_SAVE_PERIOD is a module-wide
3
+ -- constant, not a per-store one, so the autosave cadence belongs to the process
4
+ -- rather than to any one bundle. Keeping the resolved value here lets Scribe notice
5
+ -- two bundles asking for different cadences instead of silently taking the last.
6
+
7
+ local Config = {}
8
+
9
+ -- The interval actually pushed to ProfileStore, and where it came from.
10
+ Config.AutoSaveInterval = nil :: number?
11
+ Config.AutoSaveSource = nil :: string?
12
+
13
+ -- Set once a bundle has been constructed. Scribe.Configure refuses to run after
14
+ -- this point, since the value may already have been applied.
15
+ Config.BundleConstructed = false
16
+
17
+ return Config