@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.
- package/LICENSE +21 -0
- package/NOTICE +21 -0
- package/README.md +100 -0
- package/Scribe-source-map.json +1 -0
- package/licenses/ProfileStore-Apache-2.0.txt +201 -0
- package/package.json +32 -0
- package/src/Client/DebugHook.luau +457 -0
- package/src/Client/init.luau +1607 -0
- package/src/Internal/Addons.luau +68 -0
- package/src/Internal/Big.luau +582 -0
- package/src/Internal/Budget.luau +377 -0
- package/src/Internal/Clock.luau +75 -0
- package/src/Internal/Config.luau +17 -0
- package/src/Internal/Conform.luau +400 -0
- package/src/Internal/Datatypes.luau +653 -0
- package/src/Internal/Defaults.luau +12 -0
- package/src/Internal/Derived.luau +428 -0
- package/src/Internal/Exchange.luau +556 -0
- package/src/Internal/ExchangeLeg.luau +1368 -0
- package/src/Internal/ExchangeVerdict.luau +179 -0
- package/src/Internal/Failure.luau +148 -0
- package/src/Internal/Health.luau +320 -0
- package/src/Internal/LeaderboardDiagnostics.luau +36 -0
- package/src/Internal/Log.luau +378 -0
- package/src/Internal/Marker.luau +76 -0
- package/src/Internal/Metrics.luau +152 -0
- package/src/Internal/Node.luau +3954 -0
- package/src/Internal/Profile.luau +69 -0
- package/src/Internal/Rng.luau +83 -0
- package/src/Internal/Sched.luau +56 -0
- package/src/Internal/Signal.luau +199 -0
- package/src/Internal/Store/ProfileStore.luau +3019 -0
- package/src/Internal/Store/init.luau +18 -0
- package/src/Internal/StudioCodec.luau +155 -0
- package/src/Internal/Template.luau +1848 -0
- package/src/Internal/Transport.luau +169 -0
- package/src/Internal/Util.luau +517 -0
- package/src/Internal/Version.luau +4 -0
- package/src/Internal/Wire.luau +1283 -0
- package/src/Server/Analytics.luau +223 -0
- package/src/Server/Commands.luau +728 -0
- package/src/Server/DebugHook.luau +1490 -0
- package/src/Server/Exchanges.luau +737 -0
- package/src/Server/Leaderboards.luau +2143 -0
- package/src/Server/Monetization.luau +3212 -0
- package/src/Server/Persistence.luau +3775 -0
- package/src/Server/Replication.luau +1253 -0
- package/src/Server/ServerStore.luau +81 -0
- package/src/Server/Timed.luau +579 -0
- package/src/Server/init.luau +672 -0
- package/src/Types.luau +480 -0
- package/src/init.luau +2231 -0
- package/types/api.d.ts +252 -0
- package/types/common.d.ts +355 -0
- package/types/index.d.ts +226 -0
- package/types/schema.d.ts +276 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Transport. A transport moves opaque buffers; Scribe owns serialization, batching
|
|
3
|
+
-- and RPC correlation. "Default" is two RemoteEvents under a folder in
|
|
4
|
+
-- ReplicatedStorage.
|
|
5
|
+
|
|
6
|
+
local ReplicatedStorage = game:GetService("ReplicatedStorage")
|
|
7
|
+
local RunService = game:GetService("RunService")
|
|
8
|
+
|
|
9
|
+
local Types = require(script.Parent.Parent.Types)
|
|
10
|
+
|
|
11
|
+
--- A replication channel. The send methods MUST NOT YIELD: Scribe calls them from
|
|
12
|
+
--- inside the handshake and from the per-frame flush, and one that parks there
|
|
13
|
+
--- stalls that frame's remaining work for every player. Buffer and return instead.
|
|
14
|
+
---
|
|
15
|
+
--- Re-exported from Types so what a game sees and what Resolve returns cannot drift.
|
|
16
|
+
export type ScribeTransport = Types.ScribeTransport
|
|
17
|
+
|
|
18
|
+
local FOLDER_PREFIX = "ScribeTransport"
|
|
19
|
+
|
|
20
|
+
local Transport = {}
|
|
21
|
+
|
|
22
|
+
-- Two Scribe instances listening on the same RemoteEvents would receive each
|
|
23
|
+
-- other's frames and fail schema decoding; fail loudly at startup instead.
|
|
24
|
+
local boundServerChannels: { [string]: boolean } = {}
|
|
25
|
+
|
|
26
|
+
-- How to hand a claimed channel back, keyed by folder name. The claim above is
|
|
27
|
+
-- module-global and outlives any one bundle: without a release, a stopped bundle
|
|
28
|
+
-- keeps its channel and its OnServerEvent listener for the rest of the process, so
|
|
29
|
+
-- client frames still reach a bundle whose save paths are dead.
|
|
30
|
+
local channelReleases: { [string]: () -> () } = {}
|
|
31
|
+
|
|
32
|
+
local function folderName(channel: string?): string
|
|
33
|
+
if channel and channel ~= "" and channel ~= "Default" then
|
|
34
|
+
return `{FOLDER_PREFIX}_{channel}`
|
|
35
|
+
end
|
|
36
|
+
return FOLDER_PREFIX
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
local function buildDefault(channel: string?): ScribeTransport
|
|
40
|
+
local name = folderName(channel)
|
|
41
|
+
local down: RemoteEvent
|
|
42
|
+
local up: RemoteEvent
|
|
43
|
+
-- The server list backs ReleaseChannel and the claim; the client list backs Release.
|
|
44
|
+
local serverConnections: { RBXScriptConnection }? = nil
|
|
45
|
+
local clientConnections: { RBXScriptConnection } = {}
|
|
46
|
+
|
|
47
|
+
if RunService:IsServer() then
|
|
48
|
+
if boundServerChannels[name] then
|
|
49
|
+
error(
|
|
50
|
+
`Scribe: another Scribe instance is already using the "{channel or "Default"}" transport channel; `
|
|
51
|
+
.. "give each instance a distinct TransportChannel option",
|
|
52
|
+
0
|
|
53
|
+
)
|
|
54
|
+
end
|
|
55
|
+
boundServerChannels[name] = true
|
|
56
|
+
-- Recorded on the channel rather than returned from ListenServer, which would
|
|
57
|
+
-- widen the public ScribeTransport signature custom adapters are written to.
|
|
58
|
+
local connections: { RBXScriptConnection } = {}
|
|
59
|
+
serverConnections = connections
|
|
60
|
+
channelReleases[name] = function()
|
|
61
|
+
for _, connection in connections do
|
|
62
|
+
pcall(function()
|
|
63
|
+
connection:Disconnect()
|
|
64
|
+
end)
|
|
65
|
+
end
|
|
66
|
+
table.clear(connections)
|
|
67
|
+
end
|
|
68
|
+
local folder = ReplicatedStorage:FindFirstChild(name)
|
|
69
|
+
if not folder then
|
|
70
|
+
local newFolder = Instance.new("Folder")
|
|
71
|
+
newFolder.Name = name
|
|
72
|
+
newFolder.Parent = ReplicatedStorage
|
|
73
|
+
folder = newFolder
|
|
74
|
+
end
|
|
75
|
+
local function ensureRemote(remoteName: string): RemoteEvent
|
|
76
|
+
local remote = (folder :: Instance):FindFirstChild(remoteName)
|
|
77
|
+
if not remote then
|
|
78
|
+
local newRemote = Instance.new("RemoteEvent")
|
|
79
|
+
newRemote.Name = remoteName
|
|
80
|
+
newRemote.Parent = folder
|
|
81
|
+
remote = newRemote
|
|
82
|
+
end
|
|
83
|
+
return remote :: RemoteEvent
|
|
84
|
+
end
|
|
85
|
+
down = ensureRemote("Down")
|
|
86
|
+
up = ensureRemote("Up")
|
|
87
|
+
else
|
|
88
|
+
local folder = ReplicatedStorage:WaitForChild(name)
|
|
89
|
+
down = folder:WaitForChild("Down") :: RemoteEvent
|
|
90
|
+
up = folder:WaitForChild("Up") :: RemoteEvent
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
return {
|
|
94
|
+
Name = "Default",
|
|
95
|
+
SendToClient = function(_, player: Player, bytes: buffer)
|
|
96
|
+
down:FireClient(player, bytes)
|
|
97
|
+
end,
|
|
98
|
+
SendToAllClients = function(_, bytes: buffer)
|
|
99
|
+
down:FireAllClients(bytes)
|
|
100
|
+
end,
|
|
101
|
+
ListenServer = function(_, callback: (player: Player, bytes: buffer) -> ())
|
|
102
|
+
local connection = up.OnServerEvent:Connect(function(player: Player, bytes: any)
|
|
103
|
+
-- Validated here so adapters and Scribe's decoder can assume buffers.
|
|
104
|
+
if typeof(bytes) == "buffer" then
|
|
105
|
+
callback(player, bytes)
|
|
106
|
+
end
|
|
107
|
+
end)
|
|
108
|
+
-- Only on the server, where serverConnections exists.
|
|
109
|
+
if serverConnections ~= nil then
|
|
110
|
+
table.insert(serverConnections, connection)
|
|
111
|
+
end
|
|
112
|
+
end,
|
|
113
|
+
SendToServer = function(_, bytes: buffer)
|
|
114
|
+
up:FireServer(bytes)
|
|
115
|
+
end,
|
|
116
|
+
ListenClient = function(_, callback: (bytes: buffer) -> ())
|
|
117
|
+
local connection = down.OnClientEvent:Connect(function(bytes: any)
|
|
118
|
+
if typeof(bytes) == "buffer" then
|
|
119
|
+
callback(bytes)
|
|
120
|
+
end
|
|
121
|
+
end)
|
|
122
|
+
table.insert(clientConnections, connection)
|
|
123
|
+
end,
|
|
124
|
+
Release = function()
|
|
125
|
+
for _, connection in clientConnections do
|
|
126
|
+
pcall(function()
|
|
127
|
+
connection:Disconnect()
|
|
128
|
+
end)
|
|
129
|
+
end
|
|
130
|
+
table.clear(clientConnections)
|
|
131
|
+
end,
|
|
132
|
+
}
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
--- Hand a Default channel back, so a later bundle in this process can claim it.
|
|
136
|
+
--- Disconnects what the channel connected and clears the claim. Idempotent, and a
|
|
137
|
+
--- no-op for a name that was never bound. Call it only from the scope that built the
|
|
138
|
+
--- channel: a bundle on a custom transport releasing Default would take it from
|
|
139
|
+
--- whoever legitimately holds it.
|
|
140
|
+
function Transport.ReleaseChannel(channel: string?)
|
|
141
|
+
local name = folderName(channel)
|
|
142
|
+
local release = channelReleases[name]
|
|
143
|
+
channelReleases[name] = nil
|
|
144
|
+
boundServerChannels[name] = nil
|
|
145
|
+
if release ~= nil then
|
|
146
|
+
release()
|
|
147
|
+
end
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
-- Resolve the Transport option: "Default", an adapter table, or nil.
|
|
151
|
+
function Transport.Resolve(spec: any, channel: string?): ScribeTransport
|
|
152
|
+
if spec == nil or spec == "Default" then
|
|
153
|
+
return buildDefault(channel)
|
|
154
|
+
end
|
|
155
|
+
if type(spec) == "table" then
|
|
156
|
+
local required: { string } = if RunService:IsServer()
|
|
157
|
+
then { "SendToClient", "ListenServer" }
|
|
158
|
+
else { "SendToServer", "ListenClient" }
|
|
159
|
+
for _, key in required do
|
|
160
|
+
if type((spec :: any)[key]) ~= "function" then
|
|
161
|
+
error(`Scribe: custom transport is missing "{key}" (see the ScribeTransport type)`, 0)
|
|
162
|
+
end
|
|
163
|
+
end
|
|
164
|
+
return spec :: ScribeTransport
|
|
165
|
+
end
|
|
166
|
+
error(`Scribe: invalid Transport option ({typeof(spec)})`, 0)
|
|
167
|
+
end
|
|
168
|
+
|
|
169
|
+
return Transport
|
|
@@ -0,0 +1,517 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Small shared utilities.
|
|
3
|
+
|
|
4
|
+
local HttpService = game:GetService("HttpService")
|
|
5
|
+
|
|
6
|
+
-- Datatypes requires nothing, so this cannot cycle back into Util. Used only to
|
|
7
|
+
-- tell a raw-but-packable datatype apart from a genuinely unstorable value.
|
|
8
|
+
local Datatypes = require(script.Parent.Datatypes)
|
|
9
|
+
|
|
10
|
+
local Util = {}
|
|
11
|
+
|
|
12
|
+
-- Deepest nesting a written value may have, counted from the root. Enforced by
|
|
13
|
+
-- Node.validateWrite at write time and against ArrayOf/DictOf element shapes at compile
|
|
14
|
+
-- time, so an unsatisfiable template fails at startup rather than on every write.
|
|
15
|
+
Util.MAX_VALUE_DEPTH = 24
|
|
16
|
+
|
|
17
|
+
function Util.cloneBuffer(value: buffer): buffer
|
|
18
|
+
local out = buffer.create(buffer.len(value))
|
|
19
|
+
buffer.copy(out, 0, value)
|
|
20
|
+
return out
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
-- True when `s` is valid UTF-8, the only strings (and JSON object keys) a DataStore
|
|
24
|
+
-- will persist. Anything else fails the whole profile save with DataStore error 104.
|
|
25
|
+
function Util.isUtf8(s: string): boolean
|
|
26
|
+
return utf8.len(s) ~= nil
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
export type Unpersistable = {
|
|
30
|
+
Path: { string | number }, -- ancestor keys are all valid UTF-8, so safe to log
|
|
31
|
+
Kind: string, -- stable anomaly reason: "InvalidUtf8" or "Unserializable"
|
|
32
|
+
Detail: string, -- human-readable message
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
-- Depth-first scan for the first value or key a DataStore cannot store: invalid UTF-8
|
|
36
|
+
-- (error 104) or an unserializable leaf. Used by the raw-table save boundaries that
|
|
37
|
+
-- bypass Node.validateWrite, where the alternative is the whole save failing opaquely.
|
|
38
|
+
-- A bad key is reported before recursing under it, so the offender's ancestors are all
|
|
39
|
+
-- valid. The path rides a scratch stack: `n` is the live count, passed by value, so a
|
|
40
|
+
-- frame only reads `stack[1..n]` and nothing is popped.
|
|
41
|
+
local function snapshotPath(stack: { string | number }, n: number, extra: (string | number)?): { string | number }
|
|
42
|
+
local out: { string | number } = {}
|
|
43
|
+
table.move(stack, 1, n, 1, out)
|
|
44
|
+
if extra ~= nil then
|
|
45
|
+
out[n + 1] = extra
|
|
46
|
+
end
|
|
47
|
+
return out
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
local function scanUnpersistable(
|
|
51
|
+
value: any,
|
|
52
|
+
stack: { string | number },
|
|
53
|
+
n: number,
|
|
54
|
+
d: number,
|
|
55
|
+
stats: { MaxDepth: number }?
|
|
56
|
+
): Unpersistable?
|
|
57
|
+
if stats and d > stats.MaxDepth then
|
|
58
|
+
stats.MaxDepth = d
|
|
59
|
+
end
|
|
60
|
+
-- Checked first, and on typeof rather than type: a Roblox datatype is storable but not
|
|
61
|
+
-- raw, and it is userdata on Roblox yet a plain table under the headless shim, so
|
|
62
|
+
-- recursing into one reports a confusing key-type error instead of the real problem.
|
|
63
|
+
-- Do not gate it on `type(value)` to skip the typeof call: a miss here is a false
|
|
64
|
+
-- negative, and every future save then fails with no path in the log.
|
|
65
|
+
local typeName = typeof(value)
|
|
66
|
+
if Datatypes.IsSupported(typeName) then
|
|
67
|
+
return {
|
|
68
|
+
Path = snapshotPath(stack, n),
|
|
69
|
+
Kind = "Unserializable",
|
|
70
|
+
Detail = `a raw {typeName}, which only the accessor packs; write `
|
|
71
|
+
.. `Scribe.Datatypes.Pack("{typeName}", value) here, or store a plain number instead`,
|
|
72
|
+
}
|
|
73
|
+
end
|
|
74
|
+
local t = type(value)
|
|
75
|
+
if t == "string" then
|
|
76
|
+
if Util.isUtf8(value :: string) then
|
|
77
|
+
return nil
|
|
78
|
+
end
|
|
79
|
+
return {
|
|
80
|
+
Path = snapshotPath(stack, n),
|
|
81
|
+
Kind = "InvalidUtf8",
|
|
82
|
+
Detail = "string contains invalid UTF-8 bytes",
|
|
83
|
+
}
|
|
84
|
+
elseif t == "boolean" or t == "buffer" then
|
|
85
|
+
return nil
|
|
86
|
+
elseif t == "number" then
|
|
87
|
+
if value ~= value or value == math.huge or value == -math.huge then
|
|
88
|
+
return { Path = snapshotPath(stack, n), Kind = "Unserializable", Detail = "NaN/inf number" }
|
|
89
|
+
end
|
|
90
|
+
return nil
|
|
91
|
+
elseif t == "table" then
|
|
92
|
+
-- A cyclic table would recurse forever, and this scan runs unprotected inside the
|
|
93
|
+
-- load path, so an overflow kills the player's load. Capped well past
|
|
94
|
+
-- MAX_VALUE_DEPTH; nothing this deep is writable or wire-encodable anyway.
|
|
95
|
+
if d > 64 then
|
|
96
|
+
return {
|
|
97
|
+
Path = snapshotPath(stack, n),
|
|
98
|
+
Kind = "Unserializable",
|
|
99
|
+
Detail = "nested deeper than 64 levels (or cyclic)",
|
|
100
|
+
}
|
|
101
|
+
end
|
|
102
|
+
local hasNum, hasStr = false, false
|
|
103
|
+
-- One pass, and the order is load-bearing: splitting this into a key pass and a
|
|
104
|
+
-- value pass would report a different offender for the same data, and would leave
|
|
105
|
+
-- stats.MaxDepth short, since the recursion is what deepens it.
|
|
106
|
+
for k, v in value :: any do
|
|
107
|
+
local kt = type(k)
|
|
108
|
+
if kt ~= "string" and kt ~= "number" then
|
|
109
|
+
return {
|
|
110
|
+
Path = snapshotPath(stack, n, "<key>"),
|
|
111
|
+
Kind = "Unserializable",
|
|
112
|
+
Detail = `unsupported key type "{kt}"`,
|
|
113
|
+
}
|
|
114
|
+
end
|
|
115
|
+
hasNum = hasNum or kt == "number"
|
|
116
|
+
hasStr = hasStr or kt == "string"
|
|
117
|
+
if hasNum and hasStr then
|
|
118
|
+
-- JSON cannot encode a table mixing array indices and object keys;
|
|
119
|
+
-- the whole profile save fails.
|
|
120
|
+
return {
|
|
121
|
+
Path = snapshotPath(stack, n),
|
|
122
|
+
Kind = "Unserializable",
|
|
123
|
+
Detail = "table mixes array indices and string keys",
|
|
124
|
+
}
|
|
125
|
+
end
|
|
126
|
+
if kt == "string" and not Util.isUtf8(k :: string) then
|
|
127
|
+
return {
|
|
128
|
+
Path = snapshotPath(stack, n, "<invalid-key>"),
|
|
129
|
+
Kind = "InvalidUtf8",
|
|
130
|
+
Detail = "object key contains invalid UTF-8 bytes",
|
|
131
|
+
}
|
|
132
|
+
end
|
|
133
|
+
stack[n + 1] = k
|
|
134
|
+
local found = scanUnpersistable(v, stack, n + 1, d + 1, stats)
|
|
135
|
+
if found ~= nil then
|
|
136
|
+
return found
|
|
137
|
+
end
|
|
138
|
+
end
|
|
139
|
+
return nil
|
|
140
|
+
end
|
|
141
|
+
-- userdata (Instance), function, thread, native vector, etc. A packable
|
|
142
|
+
-- datatype never reaches here: it is caught by the typeof check at the top.
|
|
143
|
+
return {
|
|
144
|
+
Path = snapshotPath(stack, n),
|
|
145
|
+
Kind = "Unserializable",
|
|
146
|
+
Detail = `unsupported type "{typeName}"`,
|
|
147
|
+
}
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
function Util.findUnpersistable(
|
|
151
|
+
value: any,
|
|
152
|
+
path: { string | number }?,
|
|
153
|
+
depth: number?,
|
|
154
|
+
stats: { MaxDepth: number }?
|
|
155
|
+
): Unpersistable?
|
|
156
|
+
-- Cloned, not adopted: the caller still owns `path`, and the scratch stack would
|
|
157
|
+
-- otherwise leave its bookkeeping behind in someone else's table.
|
|
158
|
+
local stack: { string | number } = if path then table.clone(path) else {}
|
|
159
|
+
return scanUnpersistable(value, stack, #stack, depth or 0, stats)
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
-- Deep copy of a plain data value. Buffers are mutable, so they are copied
|
|
163
|
+
-- too; other non-table values are returned as-is.
|
|
164
|
+
function Util.deepClone<T>(value: T): T
|
|
165
|
+
local t = type(value)
|
|
166
|
+
if t == "buffer" then
|
|
167
|
+
return Util.cloneBuffer(value :: any) :: any
|
|
168
|
+
elseif t ~= "table" then
|
|
169
|
+
return value
|
|
170
|
+
end
|
|
171
|
+
local out = {}
|
|
172
|
+
for k, v in value :: any do
|
|
173
|
+
local vt = type(v)
|
|
174
|
+
if vt == "table" then
|
|
175
|
+
out[k] = Util.deepClone(v)
|
|
176
|
+
elseif vt == "buffer" then
|
|
177
|
+
out[k] = Util.cloneBuffer(v)
|
|
178
|
+
else
|
|
179
|
+
out[k] = v
|
|
180
|
+
end
|
|
181
|
+
end
|
|
182
|
+
return out :: any
|
|
183
|
+
end
|
|
184
|
+
|
|
185
|
+
-- Recursively freeze a table (template safety).
|
|
186
|
+
function Util.deepFreeze<T>(value: T): T
|
|
187
|
+
if type(value) == "table" then
|
|
188
|
+
for _, v in value :: any do
|
|
189
|
+
if type(v) == "table" and not table.isfrozen(v) then
|
|
190
|
+
Util.deepFreeze(v)
|
|
191
|
+
end
|
|
192
|
+
end
|
|
193
|
+
if not table.isfrozen(value :: any) then
|
|
194
|
+
table.freeze(value :: any)
|
|
195
|
+
end
|
|
196
|
+
end
|
|
197
|
+
return value
|
|
198
|
+
end
|
|
199
|
+
|
|
200
|
+
-- Sorted list of string keys of a table. Deterministic traversal for schema derivation.
|
|
201
|
+
function Util.sortedKeys(t: { [string]: any }): { string }
|
|
202
|
+
local keys = {}
|
|
203
|
+
for k in t do
|
|
204
|
+
if type(k) == "string" then
|
|
205
|
+
table.insert(keys, k)
|
|
206
|
+
end
|
|
207
|
+
end
|
|
208
|
+
table.sort(keys)
|
|
209
|
+
return keys
|
|
210
|
+
end
|
|
211
|
+
|
|
212
|
+
function Util.hasNumericKeys(t: { [any]: any }): boolean
|
|
213
|
+
for k in t do
|
|
214
|
+
if type(k) == "number" then
|
|
215
|
+
return true
|
|
216
|
+
end
|
|
217
|
+
end
|
|
218
|
+
return false
|
|
219
|
+
end
|
|
220
|
+
|
|
221
|
+
function Util.count(t: { [any]: any }): number
|
|
222
|
+
local n = 0
|
|
223
|
+
for _ in t do
|
|
224
|
+
n += 1
|
|
225
|
+
end
|
|
226
|
+
return n
|
|
227
|
+
end
|
|
228
|
+
|
|
229
|
+
-- What each byte costs beyond the raw one it already occupies, indexed by `byte + 1` so
|
|
230
|
+
-- every lookup lands in the array part.
|
|
231
|
+
--
|
|
232
|
+
-- Non-ASCII is free: the encoder emits raw UTF-8, not \uXXXX escapes. \b \t \n \f \r have
|
|
233
|
+
-- two-byte escapes and cost one extra; every other control character below 0x20 is
|
|
234
|
+
-- written as \u00XX, so five extra. A quote and a backslash cost one each.
|
|
235
|
+
local ESCAPE_COST: { number } = table.create(256, 0)
|
|
236
|
+
for b = 0, 31 do
|
|
237
|
+
ESCAPE_COST[b + 1] = 5
|
|
238
|
+
end
|
|
239
|
+
for _, b in { 8, 9, 10, 12, 13 } do
|
|
240
|
+
ESCAPE_COST[b + 1] = 1
|
|
241
|
+
end
|
|
242
|
+
ESCAPE_COST[35] = 1 -- byte 34, a double quote
|
|
243
|
+
ESCAPE_COST[93] = 1 -- byte 92, a backslash
|
|
244
|
+
|
|
245
|
+
-- Bytes JSON spends on a string literal, quotes included. No `string.find` fast path in
|
|
246
|
+
-- front of the byte walk: Luau's pattern matcher tests a character class per byte with no
|
|
247
|
+
-- vectorised path, and measured 2.6x slower than `string.byte` plus an array-part index.
|
|
248
|
+
local function jsonStringBytes(s: string): number
|
|
249
|
+
local n = #s
|
|
250
|
+
local total = n + 2
|
|
251
|
+
for i = 1, n do
|
|
252
|
+
total += ESCAPE_COST[string.byte(s, i) + 1]
|
|
253
|
+
end
|
|
254
|
+
return total
|
|
255
|
+
end
|
|
256
|
+
|
|
257
|
+
-- Digits in a non-negative integral double below 1e21.
|
|
258
|
+
local function decimalDigits(n: number): number
|
|
259
|
+
if n < 10 then
|
|
260
|
+
return 1
|
|
261
|
+
elseif n < 100 then
|
|
262
|
+
return 2
|
|
263
|
+
elseif n < 1000 then
|
|
264
|
+
return 3
|
|
265
|
+
elseif n < 10000 then
|
|
266
|
+
return 4
|
|
267
|
+
elseif n < 100000 then
|
|
268
|
+
return 5
|
|
269
|
+
elseif n < 1000000 then
|
|
270
|
+
return 6
|
|
271
|
+
end
|
|
272
|
+
-- Past a million the comparison ladder stops paying for itself. %.0f prints
|
|
273
|
+
-- the double's exact integer value, so this stays exact rather than fitted.
|
|
274
|
+
return #string.format("%.0f", n)
|
|
275
|
+
end
|
|
276
|
+
|
|
277
|
+
local function jsonNumberBytes(v: number): number
|
|
278
|
+
if v ~= v or v == math.huge or v == -math.huge then
|
|
279
|
+
-- Not encodable at all; findUnpersistable rejects these separately, so
|
|
280
|
+
-- charge `null` and move on rather than inventing a size.
|
|
281
|
+
return 4
|
|
282
|
+
end
|
|
283
|
+
-- The encoder writes integral values in full decimal all the way to 1e20 and only
|
|
284
|
+
-- switches to exponent form at 1e21, so %.17g alone renders 1e20 as "1e+20" and
|
|
285
|
+
-- under-counts it by sixteen bytes.
|
|
286
|
+
if v % 1 == 0 and v > -1e21 and v < 1e21 then
|
|
287
|
+
local digits = decimalDigits(if v < 0 then -v else v)
|
|
288
|
+
return if v < 0 then digits + 1 else digits
|
|
289
|
+
end
|
|
290
|
+
return #string.format("%.17g", v)
|
|
291
|
+
end
|
|
292
|
+
|
|
293
|
+
-- Approximate serialized size in bytes, as an upper bound on what the DataStore would
|
|
294
|
+
-- store, which is the number the ~4 MB per-key ceiling is measured against. Buffer-aware
|
|
295
|
+
-- (DataStores store buffers as base64, 4/3 of their raw length rounded up to a 4-byte
|
|
296
|
+
-- group), so it works where JSONEncode would throw.
|
|
297
|
+
--
|
|
298
|
+
-- Upper bound rather than best guess: PROFILE_SIZE warns before saves start failing at the
|
|
299
|
+
-- ceiling, so an under-count is silent while an over-count only costs an early warning. It
|
|
300
|
+
-- never builds the string, and only array positions inside 1..#t are free: the encoder
|
|
301
|
+
-- writes {[123]="a"} as {"123":"a"} (hence Template.CoerceMapKeys), so a numeric key
|
|
302
|
+
-- outside the array part is charged like a string one.
|
|
303
|
+
function Util.approxSize(value: any, depth: number?): number
|
|
304
|
+
local d = depth or 0
|
|
305
|
+
local t = type(value)
|
|
306
|
+
if t == "string" then
|
|
307
|
+
return jsonStringBytes(value :: string)
|
|
308
|
+
elseif t == "number" then
|
|
309
|
+
return jsonNumberBytes(value :: number)
|
|
310
|
+
elseif t == "boolean" then
|
|
311
|
+
return if value then 4 else 5
|
|
312
|
+
elseif t == "buffer" then
|
|
313
|
+
return 4 * math.ceil(buffer.len(value :: buffer) / 3) + 2
|
|
314
|
+
elseif t == "table" then
|
|
315
|
+
-- This also measures live data from the raw-write boundaries, which can be cyclic,
|
|
316
|
+
-- and it runs unprotected on the save path, so a cycle here would kill the save
|
|
317
|
+
-- rather than fail it. Cap exactly where findUnpersistable does.
|
|
318
|
+
if d > 64 then
|
|
319
|
+
return 2
|
|
320
|
+
end
|
|
321
|
+
local arrayLength = #(value :: any)
|
|
322
|
+
local total, entries = 2, 0 -- {} / []
|
|
323
|
+
for k, v in value :: any do
|
|
324
|
+
entries += 1
|
|
325
|
+
if type(k) == "number" and k >= 1 and k <= arrayLength and k % 1 == 0 then
|
|
326
|
+
total += Util.approxSize(v, d + 1)
|
|
327
|
+
else
|
|
328
|
+
-- The key dispatch tests the key type rather than asserting it. Casting a
|
|
329
|
+
-- key to number here raises on a boolean or table key, and approxSize runs
|
|
330
|
+
-- inside a save-path Signal handler that swallows the raise, so the
|
|
331
|
+
-- PROFILE_SIZE warning silently stops firing. The 6 for an unencodable key
|
|
332
|
+
-- measures nothing (findUnpersistable reports it); what matters is that the
|
|
333
|
+
-- walk continues past it.
|
|
334
|
+
local kt = type(k)
|
|
335
|
+
local keyBytes = if kt == "string"
|
|
336
|
+
then jsonStringBytes(k :: string)
|
|
337
|
+
elseif kt == "number" then jsonNumberBytes(k :: number) + 2 -- quoted, as the encoder writes it
|
|
338
|
+
else 6
|
|
339
|
+
total += keyBytes + 1 + Util.approxSize(v, d + 1) -- + ':'
|
|
340
|
+
end
|
|
341
|
+
end
|
|
342
|
+
if entries > 1 then
|
|
343
|
+
total += entries - 1 -- separating commas, not one per entry
|
|
344
|
+
end
|
|
345
|
+
return total
|
|
346
|
+
end
|
|
347
|
+
return 4
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
local BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
|
|
351
|
+
|
|
352
|
+
-- Base64 for JSON exports of buffer fields.
|
|
353
|
+
function Util.base64FromBuffer(value: buffer): string
|
|
354
|
+
local length = buffer.len(value)
|
|
355
|
+
local out = table.create(math.ceil(length / 3))
|
|
356
|
+
local index = 0
|
|
357
|
+
while index < length do
|
|
358
|
+
local a = buffer.readu8(value, index)
|
|
359
|
+
local b = if index + 1 < length then buffer.readu8(value, index + 1) else 0
|
|
360
|
+
local c = if index + 2 < length then buffer.readu8(value, index + 2) else 0
|
|
361
|
+
local n = a * 65536 + b * 256 + c
|
|
362
|
+
local chunk = {
|
|
363
|
+
string.sub(BASE64, math.floor(n / 262144) % 64 + 1, math.floor(n / 262144) % 64 + 1),
|
|
364
|
+
string.sub(BASE64, math.floor(n / 4096) % 64 + 1, math.floor(n / 4096) % 64 + 1),
|
|
365
|
+
if index + 1 < length
|
|
366
|
+
then string.sub(BASE64, math.floor(n / 64) % 64 + 1, math.floor(n / 64) % 64 + 1)
|
|
367
|
+
else "=",
|
|
368
|
+
if index + 2 < length then string.sub(BASE64, n % 64 + 1, n % 64 + 1) else "=",
|
|
369
|
+
}
|
|
370
|
+
table.insert(out, table.concat(chunk))
|
|
371
|
+
index += 3
|
|
372
|
+
end
|
|
373
|
+
return table.concat(out)
|
|
374
|
+
end
|
|
375
|
+
|
|
376
|
+
function Util.guid(): string
|
|
377
|
+
return HttpService:GenerateGUID(false)
|
|
378
|
+
end
|
|
379
|
+
|
|
380
|
+
-- Byte equality for two buffers, for the array search accessors. Buffers compare by
|
|
381
|
+
-- identity under `==`, so a packed datatype in the store never equals a freshly packed
|
|
382
|
+
-- needle even when they hold the same value.
|
|
383
|
+
function Util.bufferEquals(a: buffer, b: buffer): boolean
|
|
384
|
+
local len = buffer.len(a)
|
|
385
|
+
if len ~= buffer.len(b) then
|
|
386
|
+
return false
|
|
387
|
+
end
|
|
388
|
+
local i = 0
|
|
389
|
+
while i + 4 <= len do
|
|
390
|
+
if buffer.readu32(a, i) ~= buffer.readu32(b, i) then
|
|
391
|
+
return false
|
|
392
|
+
end
|
|
393
|
+
i += 4
|
|
394
|
+
end
|
|
395
|
+
while i < len do
|
|
396
|
+
if buffer.readu8(a, i) ~= buffer.readu8(b, i) then
|
|
397
|
+
return false
|
|
398
|
+
end
|
|
399
|
+
i += 1
|
|
400
|
+
end
|
|
401
|
+
return true
|
|
402
|
+
end
|
|
403
|
+
|
|
404
|
+
-- Shallow equality for "did this leaf change" checks. Tables and buffers always count as
|
|
405
|
+
-- changes: both are mutable, so a re-Set of the same reference may carry in-place edits
|
|
406
|
+
-- that must replicate.
|
|
407
|
+
function Util.leafEquals(a: any, b: any): boolean
|
|
408
|
+
local t = type(a)
|
|
409
|
+
return a == b and t ~= "table" and t ~= "buffer"
|
|
410
|
+
end
|
|
411
|
+
|
|
412
|
+
-- table.concat that tolerates numeric segments.
|
|
413
|
+
function Util.pathKey(path: { string | number }): string
|
|
414
|
+
if #path == 0 then
|
|
415
|
+
return ""
|
|
416
|
+
end
|
|
417
|
+
local parts = table.create(#path)
|
|
418
|
+
for i, seg in path do
|
|
419
|
+
parts[i] = tostring(seg)
|
|
420
|
+
end
|
|
421
|
+
return table.concat(parts, "\31")
|
|
422
|
+
end
|
|
423
|
+
|
|
424
|
+
function Util.pathString(path: { string | number }): string
|
|
425
|
+
local parts = table.create(#path)
|
|
426
|
+
for i, seg in path do
|
|
427
|
+
parts[i] = tostring(seg)
|
|
428
|
+
end
|
|
429
|
+
return table.concat(parts, ".")
|
|
430
|
+
end
|
|
431
|
+
|
|
432
|
+
-- Split a dotted path string ("Attributes.Money") into segments.
|
|
433
|
+
function Util.parsePath(s: string): { string }
|
|
434
|
+
local out = {}
|
|
435
|
+
for seg in string.gmatch(s, "[^%.]+") do
|
|
436
|
+
table.insert(out, seg)
|
|
437
|
+
end
|
|
438
|
+
return out
|
|
439
|
+
end
|
|
440
|
+
|
|
441
|
+
-- Call `fn` through xpcall with a logged traceback; never throws. Returns ok plus
|
|
442
|
+
-- whatever `fn` returned.
|
|
443
|
+
function Util.safeCall(onError: (err: string) -> (), fn: (...any) -> ...any, ...: any): (boolean, ...any)
|
|
444
|
+
local args = table.pack(...)
|
|
445
|
+
local results: any
|
|
446
|
+
local traceback: string?
|
|
447
|
+
local ok = xpcall(function()
|
|
448
|
+
results = table.pack(fn(table.unpack(args, 1, args.n)))
|
|
449
|
+
end, function(e)
|
|
450
|
+
traceback = debug.traceback(tostring(e), 2)
|
|
451
|
+
end)
|
|
452
|
+
if not ok then
|
|
453
|
+
onError(tostring(traceback))
|
|
454
|
+
return false
|
|
455
|
+
end
|
|
456
|
+
return true, table.unpack(results, 1, results.n)
|
|
457
|
+
end
|
|
458
|
+
|
|
459
|
+
-- FNV-1a 32-bit hash over a string; used for the schema handshake checksum.
|
|
460
|
+
function Util.fnv32(s: string, seed: number?): number
|
|
461
|
+
local hash = seed or 2166136261
|
|
462
|
+
for i = 1, #s do
|
|
463
|
+
hash = bit32.bxor(hash, string.byte(s, i))
|
|
464
|
+
hash = bit32.band(hash * 16777619, 0xFFFFFFFF)
|
|
465
|
+
end
|
|
466
|
+
return hash
|
|
467
|
+
end
|
|
468
|
+
|
|
469
|
+
-- Sanitize a context table for logging: Instances become names, Players become
|
|
470
|
+
-- {UserId, Name}, depth-limited, JSON-safe.
|
|
471
|
+
function Util.sanitizeContext(context: any, depth: number?): any
|
|
472
|
+
local d = depth or 0
|
|
473
|
+
if d > 4 then
|
|
474
|
+
return "<deep>"
|
|
475
|
+
end
|
|
476
|
+
local t = typeof(context)
|
|
477
|
+
if t == "Instance" then
|
|
478
|
+
if context:IsA("Player") then
|
|
479
|
+
return { UserId = context.UserId, Name = context.Name }
|
|
480
|
+
end
|
|
481
|
+
return context:GetFullName()
|
|
482
|
+
elseif t == "table" then
|
|
483
|
+
local out = {}
|
|
484
|
+
for k, v in context do
|
|
485
|
+
out[tostring(k)] = Util.sanitizeContext(v, d + 1)
|
|
486
|
+
end
|
|
487
|
+
return out
|
|
488
|
+
elseif t == "string" or t == "number" or t == "boolean" or t == "nil" then
|
|
489
|
+
return context
|
|
490
|
+
end
|
|
491
|
+
return tostring(context)
|
|
492
|
+
end
|
|
493
|
+
|
|
494
|
+
--- The first missing index in what is meant to be a dense array, or nil. `#` cannot
|
|
495
|
+
--- answer this alone: it counts past a constructor hole (`{ "a", nil, "b" }` is 3) and
|
|
496
|
+
--- stops short of an assigned one (t[1], t[3] is 1), and iteration skips either. Named
|
|
497
|
+
--- keys are not gaps.
|
|
498
|
+
function Util.firstGap(list: { any }): number?
|
|
499
|
+
local count, highest = 0, 0
|
|
500
|
+
for key in list do
|
|
501
|
+
count += 1
|
|
502
|
+
if type(key) == "number" and key > highest then
|
|
503
|
+
highest = key
|
|
504
|
+
end
|
|
505
|
+
end
|
|
506
|
+
if count == highest then
|
|
507
|
+
return nil
|
|
508
|
+
end
|
|
509
|
+
for i = 1, highest do
|
|
510
|
+
if list[i] == nil then
|
|
511
|
+
return i
|
|
512
|
+
end
|
|
513
|
+
end
|
|
514
|
+
return nil
|
|
515
|
+
end
|
|
516
|
+
|
|
517
|
+
return Util
|