@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,69 @@
1
+ --!strict
2
+ -- MicroProfiler spans and memory attribution. `debug.profilebegin` exists only in the
3
+ -- Roblox VM, so the functions are resolved once here and the headless path costs one
4
+ -- nil check. There is no exposed Begin/End pair on purpose: an unclosed span skews every
5
+ -- label after it for the rest of the frame, so the only entry point wraps the call and
6
+ -- closes through the error unwind too.
7
+ local Profile = {}
8
+
9
+ local profileBegin: ((label: string) -> ())? = (debug :: any).profilebegin
10
+ local profileEnd: (() -> ())? = (debug :: any).profileend
11
+ local setMemoryCategory: ((tag: string) -> ())? = (debug :: any).setmemorycategory
12
+
13
+ -- Kept so Install can put them back.
14
+ local nativeBegin, nativeEnd, nativeCategory = profileBegin, profileEnd, setMemoryCategory
15
+
16
+ --- Can this VM profile at all? False headless.
17
+ function Profile.Available(): boolean
18
+ return profileBegin ~= nil and profileEnd ~= nil
19
+ end
20
+
21
+ --- Substitute the profiler, the way Clock and Sched are substituted. Without the seam
22
+ --- the profiling path is unreachable from a test, and two mutations to it survived the
23
+ --- whole suite.
24
+ function Profile.Install(impl: { Begin: (string) -> (), End: () -> (), Category: ((string) -> ())? })
25
+ profileBegin = impl.Begin
26
+ profileEnd = impl.End
27
+ setMemoryCategory = impl.Category
28
+ end
29
+
30
+ --- Put the real ones back, or the absence of them.
31
+ function Profile.Reset()
32
+ profileBegin, profileEnd, setMemoryCategory = nativeBegin, nativeEnd, nativeCategory
33
+ end
34
+
35
+ --- Run `fn` inside a named span and return whatever it returns. The span closes when
36
+ --- `fn` raises, and the error is re-raised at level 0 to keep its original message and
37
+ --- origin.
38
+ ---
39
+ --- `fn` MUST NOT YIELD. An annotation belongs to the thread's current synchronous slice,
40
+ --- so a yield loses it and the close then logs "No active profile annotation" on every
41
+ --- call. Measure anything that waits with a Metrics.Observe instead.
42
+ function Profile.SyncSpan(label: string, fn: (...any) -> ...any, ...: any): ...any
43
+ -- Read as a pair up front: Install can replace the seam while `fn` runs, and closing
44
+ -- with a different profiler than opened is worse than not profiling.
45
+ local begin, finish = profileBegin, profileEnd
46
+ if begin == nil or finish == nil then
47
+ return fn(...)
48
+ end
49
+ begin(label)
50
+ local results = table.pack(pcall(fn, ...))
51
+ if not results[1] then
52
+ finish()
53
+ error(results[2], 0)
54
+ end
55
+ finish()
56
+ return table.unpack(results, 2, results.n)
57
+ end
58
+
59
+ --- Attribute this THREAD's allocations to a category in the developer console.
60
+ --- Per thread, so only Scribe's own long-lived loops call it: a write made from game
61
+ --- code runs on the caller's thread and stays under their category. Never call it from
62
+ --- a handler the engine recycles, or the tag outlives the call.
63
+ function Profile.MemoryCategory(tag: string): ()
64
+ if setMemoryCategory ~= nil then
65
+ setMemoryCategory(tag)
66
+ end
67
+ end
68
+
69
+ return Profile
@@ -0,0 +1,83 @@
1
+ --!strict
2
+ -- The randomness seam: every draw goes through here, so a simulation can replay a run.
3
+ -- Next() returns a float in [0, 1). Not math.random, whose state the game shares, and
4
+ -- not Random.new, which does not exist outside Roblox.
5
+ -- Seeded from JobId mixed with Clock.Now(), because a fleet booted by one deploy reads
6
+ -- nearly the same clock and a synchronised herd is what jitter exists to prevent.
7
+ -- Seeded lazily, so a module drawing at load does not beat Clock.Install.
8
+
9
+ local Clock = require(script.Parent.Clock)
10
+
11
+ local Rng = {}
12
+
13
+ export type Impl = {
14
+ Next: (() -> number)?,
15
+ }
16
+
17
+ -- xorshift32 has zero as a fixed point: seeded there it returns zero forever.
18
+ local ZERO_SEED_SUBSTITUTE = 0x9E3779B9
19
+
20
+ local state: number? = nil
21
+
22
+ --- FNV-1a over this server's job id, mixed with wall time. Inlined rather than
23
+ --- taken from Util to keep this seam's dependencies small.
24
+ local function makeSeed(): number
25
+ local hash = 2166136261
26
+ local jobId = tostring((game :: any).JobId)
27
+ for i = 1, #jobId do
28
+ hash = bit32.band(bit32.bxor(hash, string.byte(jobId, i)) * 16777619, 0xFFFFFFFF)
29
+ end
30
+ hash = bit32.bxor(hash, bit32.band(math.floor(Clock.Now()), 0xFFFFFFFF))
31
+ if hash == 0 then
32
+ return ZERO_SEED_SUBSTITUTE
33
+ end
34
+ return hash
35
+ end
36
+
37
+ local DEFAULT_NEXT: () -> number = function(): number
38
+ local s = state or makeSeed()
39
+ s = bit32.bxor(s, bit32.lshift(s, 13))
40
+ s = bit32.bxor(s, bit32.rshift(s, 17))
41
+ s = bit32.bxor(s, bit32.lshift(s, 5))
42
+ state = s
43
+ return s / 4294967296
44
+ end
45
+
46
+ Rng.Next = DEFAULT_NEXT
47
+
48
+ --- Replace the draw. Omitting it keeps the current value, matching Clock and Sched.
49
+ --- A replacement must stay inside [0, 1): jitter multiplies a delay by it, so a
50
+ --- larger value overruns the bound its caller reasoned about and a negative one
51
+ --- turns a wait into an immediate retry.
52
+ function Rng.Install(impl: Impl)
53
+ if impl.Next ~= nil then
54
+ Rng.Next = impl.Next
55
+ end
56
+ end
57
+
58
+ -- How far a jittered delay may stray from nominal, in either direction.
59
+ local JITTER_FRACTION = 0.25
60
+
61
+ -- Floor for a jittered delay, guarding an installed Next that breaks its [0, 1)
62
+ -- contract. Must be strictly positive: the simulation scheduler re-queues a wait of
63
+ -- <= 0 without advancing virtual time, so the run stalls at its step limit and
64
+ -- reads as a deadlocked workload.
65
+ local MIN_DELAY = 1 / 60
66
+
67
+ --- `seconds`, moved up or down by up to a quarter. Two-sided and bounded at both
68
+ --- ends, so it is safe inside loops that already assert timing.
69
+ ---
70
+ --- For delays, not for timeouts: a timeout is a promise about when a caller will be
71
+ --- answered, so moving it changes a contract.
72
+ function Rng.Jitter(seconds: number): number
73
+ return math.max(seconds * (1 + (Rng.Next() - 0.5) * 2 * JITTER_FRACTION), MIN_DELAY)
74
+ end
75
+
76
+ --- Restore the default. A test that installs must reset, or it hands its generator
77
+ --- to every spec that runs afterwards. The default's own state is not rewound, so
78
+ --- nothing can depend on the sequence a reset produces.
79
+ function Rng.Reset()
80
+ Rng.Next = DEFAULT_NEXT
81
+ end
82
+
83
+ return Rng
@@ -0,0 +1,56 @@
1
+ --!strict
2
+ -- The scheduling seam: starting a thread goes through here, so a simulation can decide
3
+ -- the interleaving. A replacement must keep the engine's semantics, or it finds bugs
4
+ -- that cannot happen and hides ones that can:
5
+ -- Spawn(fn, ...) runs `fn` immediately on the caller's stack, like task.spawn. Code
6
+ -- relies on a spawned load that never yields being done on return.
7
+ -- Defer(fn, ...) queues `fn` after the current resumption point.
8
+ -- Resume(thr, ...) resumes an existing suspended coroutine: the moments a request
9
+ -- completes, which an interleaving search most wants to move.
10
+ -- Signal dispatch and the DebugHook pair are not routed: the signal runner is never
11
+ -- blocked, so simulating it buys no orderings, and the hooks are Studio tooling.
12
+
13
+ local Sched = {}
14
+
15
+ export type Impl = {
16
+ Spawn: ((fn: (...any) -> (), ...any) -> thread)?,
17
+ Defer: ((fn: (...any) -> (), ...any) -> thread)?,
18
+ Resume: ((thread: thread, ...any) -> ())?,
19
+ }
20
+
21
+ local DEFAULT_SPAWN: (fn: (...any) -> (), ...any) -> thread = task.spawn
22
+ local DEFAULT_DEFER: (fn: (...any) -> (), ...any) -> thread = task.defer
23
+ -- Wrapped rather than assigned directly: task.spawn returns the thread, and Resume
24
+ -- returns nothing so nobody mistakes a resumption for a spawn.
25
+ local DEFAULT_RESUME: (thread: thread, ...any) -> () = function(thread: thread, ...: any)
26
+ task.spawn(thread, ...)
27
+ end
28
+
29
+ Sched.Spawn = DEFAULT_SPAWN
30
+ Sched.Defer = DEFAULT_DEFER
31
+ Sched.Resume = DEFAULT_RESUME
32
+
33
+ --- Replace any of the three. Anything omitted keeps its current value. A
34
+ --- replacement Spawn must still run its function immediately; one that queues
35
+ --- appears to work while quietly reordering everything that assumed otherwise.
36
+ function Sched.Install(impl: Impl)
37
+ if impl.Spawn ~= nil then
38
+ Sched.Spawn = impl.Spawn
39
+ end
40
+ if impl.Defer ~= nil then
41
+ Sched.Defer = impl.Defer
42
+ end
43
+ if impl.Resume ~= nil then
44
+ Sched.Resume = impl.Resume
45
+ end
46
+ end
47
+
48
+ --- Restore all three. A test that installs must reset, or it hands its scheduler
49
+ --- to every spec that runs afterwards.
50
+ function Sched.Reset()
51
+ Sched.Spawn = DEFAULT_SPAWN
52
+ Sched.Defer = DEFAULT_DEFER
53
+ Sched.Resume = DEFAULT_RESUME
54
+ end
55
+
56
+ return Sched
@@ -0,0 +1,199 @@
1
+ --!strict
2
+ -- Signal: the batched, yield-safe Roblox signal (GoodSignal), vendored so Scribe carries
3
+ -- no external Signal dependency. Handlers run on a cached runner thread (cheap yielding),
4
+ -- connections form a linked list so a listener can disconnect another mid-fire, and a
5
+ -- throwing handler is surfaced by the scheduler rather than swallowed.
6
+ --
7
+ -- Adapted from GoodSignal by stravant (2021) and sleitnick's typed copy; both
8
+ -- MIT-licensed. Trimmed to new / Connect / Once / Fire / Wait / DisconnectAll / Destroy.
9
+
10
+ export type Connection = {
11
+ Disconnect: (self: Connection) -> (),
12
+ Connected: boolean,
13
+ }
14
+
15
+ export type Signal<T...> = {
16
+ Connect: (self: Signal<T...>, fn: (T...) -> ()) -> Connection,
17
+ Once: (self: Signal<T...>, fn: (T...) -> ()) -> Connection,
18
+ Fire: (self: Signal<T...>, T...) -> (),
19
+ Wait: (self: Signal<T...>) -> T...,
20
+ Destroy: (self: Signal<T...>) -> (),
21
+ }
22
+
23
+ -- The currently idle runner thread, reused across handlers. A handler that yields
24
+ -- takes it over, and Fire makes a new one for the next handler.
25
+ local freeRunnerThread: thread? = nil
26
+
27
+ local function acquireRunnerThreadAndCallEventHandler(fn: (...any) -> (), ...)
28
+ local acquired = freeRunnerThread
29
+ freeRunnerThread = nil
30
+ fn(...)
31
+ freeRunnerThread = acquired
32
+ end
33
+
34
+ -- Primed to its first yield: a runner started with the handler's arguments keeps
35
+ -- them on its stack for life.
36
+ local function runEventHandlerInFreeThread()
37
+ while true do
38
+ acquireRunnerThreadAndCallEventHandler(coroutine.yield())
39
+ end
40
+ end
41
+
42
+ -- Connection ------------------------------------------------------------------
43
+
44
+ local Connection = {}
45
+ Connection.__index = Connection
46
+
47
+ -- Detaches this handler; repeated calls do nothing.
48
+ function Connection.Disconnect(self: any)
49
+ if not self.Connected then
50
+ return
51
+ end
52
+ self.Connected = false
53
+ -- Unhook the node without clearing it, so a Fire currently iterating on it
54
+ -- can still move forward; the node is GCed once no Fire references it.
55
+ local signal = self._signal
56
+ if signal._head == self then
57
+ signal._head = self._next
58
+ else
59
+ local prev = signal._head
60
+ while prev and prev._next ~= self do
61
+ prev = prev._next
62
+ end
63
+ if prev then
64
+ prev._next = self._next
65
+ end
66
+ end
67
+ end
68
+
69
+ -- Signal ----------------------------------------------------------------------
70
+
71
+ local Signal = {}
72
+ Signal.__index = Signal
73
+
74
+ function Signal.new(): any
75
+ return setmetatable({ _head = false }, Signal)
76
+ end
77
+
78
+ -- Registers a handler and returns its disconnectable connection.
79
+ function Signal.Connect(self: any, fn: (...any) -> ()): any
80
+ local connection = setmetatable({
81
+ Connected = true,
82
+ _signal = self,
83
+ _fn = fn,
84
+ _next = self._head,
85
+ }, Connection)
86
+ self._head = connection
87
+ return connection
88
+ end
89
+
90
+ -- `_head` is false when empty and a connection otherwise; Disconnect unlinks, so
91
+ -- the chain only ever holds live connections.
92
+ function Signal.HasListeners(self: any): boolean
93
+ return not not self._head
94
+ end
95
+
96
+ -- Disconnects before the handler's first call.
97
+ function Signal.Once(self: any, fn: (...any) -> ()): any
98
+ local connection
99
+ connection = Signal.Connect(self, function(...)
100
+ if connection.Connected then
101
+ connection:Disconnect()
102
+ end
103
+ fn(...)
104
+ end)
105
+ return connection
106
+ end
107
+
108
+ function Signal.Fire(self: any, ...: any)
109
+ local item = self._head
110
+ while item do
111
+ if item.Connected then
112
+ if not freeRunnerThread then
113
+ freeRunnerThread = coroutine.create(runEventHandlerInFreeThread)
114
+ coroutine.resume(freeRunnerThread :: thread)
115
+ end
116
+ task.spawn(freeRunnerThread :: thread, item._fn, ...)
117
+ end
118
+ item = item._next
119
+ end
120
+ end
121
+
122
+ -- Fires like Fire does, one isolated thread per handler, then hands
123
+ -- `onSettled(ran, ok, err)` the outcome once the last handler has returned or raised.
124
+ -- Fire alone cannot say whether a handler ran, finished or blew up, and the cross-server
125
+ -- message drain has to know: retiring a message whose handler never observed it destroys
126
+ -- it. Not on the exported Signal type, like HasListeners.
127
+ --
128
+ -- `ran` is how many connections were live at the call, `ok` is false if any raised,
129
+ -- `err` is the first error. onSettled runs synchronously when no handler yielded,
130
+ -- otherwise on the last handler's thread. A handler that yields and never returns never
131
+ -- settles, so the caller is never told to acknowledge.
132
+ function Signal.FireTracked(self: any, onSettled: (number, boolean, any) -> (), ...: any)
133
+ local ran, settled = 0, 0
134
+ local failed, firstError = false, nil
135
+ -- False while the list is still being walked, so a handler that completes
136
+ -- synchronously cannot settle the fire before its siblings are spawned.
137
+ local dispatched = false
138
+ local function finish(ok: boolean, err: any)
139
+ settled += 1
140
+ if not ok and not failed then
141
+ failed = true
142
+ firstError = err
143
+ end
144
+ if dispatched and settled == ran then
145
+ onSettled(ran, not failed, firstError)
146
+ end
147
+ end
148
+ local item = self._head
149
+ while item do
150
+ if item.Connected then
151
+ ran += 1
152
+ local fn = item._fn
153
+ -- A fresh thread per handler rather than Fire's cached runner, which cannot
154
+ -- report when a handler ended. Message delivery is not a hot path.
155
+ task.spawn(function(...)
156
+ finish(pcall(fn, ...))
157
+ end, ...)
158
+ end
159
+ item = item._next
160
+ end
161
+ dispatched = true
162
+ if settled == ran then
163
+ onSettled(ran, not failed, firstError)
164
+ end
165
+ end
166
+
167
+ -- Yields until the next fire and returns its arguments.
168
+ function Signal.Wait(self: any): ...any
169
+ local waiting = coroutine.running()
170
+ local connection
171
+ connection = Signal.Connect(self, function(...)
172
+ connection:Disconnect()
173
+ task.spawn(waiting, ...)
174
+ end)
175
+ return coroutine.yield()
176
+ end
177
+
178
+ -- Detaches every handler and marks its connection disconnected.
179
+ function Signal.DisconnectAll(self: any)
180
+ local item = self._head
181
+ while item do
182
+ item.Connected = false
183
+ item = item._next
184
+ end
185
+ self._head = false
186
+ end
187
+
188
+ -- Disconnects handlers; the signal can still be reused.
189
+ Signal.Destroy = Signal.DisconnectAll
190
+
191
+ --------------------------------------------------------------------------------
192
+
193
+ local SignalModule = {}
194
+
195
+ function SignalModule.new(): any
196
+ return Signal.new()
197
+ end
198
+
199
+ return SignalModule