@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,3954 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- The Value tree runtime: a metatable-backed accessor tree that lazily materializes
|
|
3
|
+
-- child nodes, records paths for replication, validates every write, and holds
|
|
4
|
+
-- per-node callback lists. Used for the server tree and the client mirror alike.
|
|
5
|
+
|
|
6
|
+
local Util = require(script.Parent.Util)
|
|
7
|
+
local Big = require(script.Parent.Big)
|
|
8
|
+
local Template = require(script.Parent.Template)
|
|
9
|
+
local Datatypes = require(script.Parent.Datatypes)
|
|
10
|
+
local DerivedModule = require(script.Parent.Derived)
|
|
11
|
+
local Metrics = require(script.Parent.Metrics)
|
|
12
|
+
|
|
13
|
+
type SchemaNode = Template.SchemaNode
|
|
14
|
+
type Compiled = Template.Compiled
|
|
15
|
+
|
|
16
|
+
export type Op = {
|
|
17
|
+
Kind: string,
|
|
18
|
+
Path: { string | number },
|
|
19
|
+
Value: any?,
|
|
20
|
+
Index: number?,
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export type TimedHooks = {
|
|
24
|
+
SetTimed: (accessor: any, value: any, seconds: number, replicate: boolean?) -> (),
|
|
25
|
+
ExtendTimed: (accessor: any, seconds: number, replicate: boolean?) -> (),
|
|
26
|
+
Active: (accessor: any) -> (boolean, number?),
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export type TreeParams = {
|
|
30
|
+
Compiled: Compiled,
|
|
31
|
+
Stores: { Persist: { [string]: any }, Session: { [string]: any } },
|
|
32
|
+
IsServer: boolean,
|
|
33
|
+
Label: string,
|
|
34
|
+
OnOp: ((op: Op, schema: SchemaNode?) -> ())?,
|
|
35
|
+
OnAnomaly: ((path: { string | number }, value: any, reason: string) -> ())?,
|
|
36
|
+
BoundsPolicy: ("Clamp" | "Reject")?,
|
|
37
|
+
DevMode: boolean?,
|
|
38
|
+
TimedHooks: TimedHooks?,
|
|
39
|
+
OnEconomy: ((path: { string | number }, delta: number, newValue: number, tags: { [string]: any }) -> ())?,
|
|
40
|
+
LogError: (message: string) -> (),
|
|
41
|
+
LogWarn: ((message: string) -> ())?,
|
|
42
|
+
OnBatchEnd: (() -> ())?,
|
|
43
|
+
-- Scribe.Derived diagnostics, so each realm logs with its own context and this
|
|
44
|
+
-- module stays free of the logger.
|
|
45
|
+
OnDerivedIssue: ((code: string, field: string, detail: string) -> ())?,
|
|
46
|
+
-- The server store: no player, no key. Read only by the cross-tree refusal.
|
|
47
|
+
IsServerStore: boolean?,
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
-- Cast once: Big.from is optional because parsing can fail, which a literal cannot,
|
|
51
|
+
-- and the economy path below would otherwise compare through `any`.
|
|
52
|
+
local BIG_ZERO = Big.from(0) :: Big.Big
|
|
53
|
+
|
|
54
|
+
local Node = {}
|
|
55
|
+
|
|
56
|
+
-- The message RunTransaction returns when `fn` yielded. Exported so a caller can tell
|
|
57
|
+
-- a yield apart from a throw without string-matching a literal.
|
|
58
|
+
local YIELD_ERROR =
|
|
59
|
+
"Scribe: a transaction function must not yield (no task.wait, DataStore, or MarketplaceService calls inside Data.Transaction; do async work before or after it)"
|
|
60
|
+
Node.YIELD_ERROR = YIELD_ERROR
|
|
61
|
+
|
|
62
|
+
local ACCESSOR_MT: any -- forward declaration
|
|
63
|
+
|
|
64
|
+
-- Tree ------------------------------------------------------------------------
|
|
65
|
+
|
|
66
|
+
local Tree = {}
|
|
67
|
+
Tree.__index = Tree
|
|
68
|
+
|
|
69
|
+
export type Tree = typeof(setmetatable(
|
|
70
|
+
{} :: {
|
|
71
|
+
Params: TreeParams,
|
|
72
|
+
Compiled: Compiled,
|
|
73
|
+
Accessor: any,
|
|
74
|
+
-- The library's handle on the reserved `_Scribe` root: the only accessor
|
|
75
|
+
-- permitted to write there, and never returned by any public API.
|
|
76
|
+
Reserved: any,
|
|
77
|
+
Dead: boolean,
|
|
78
|
+
_listeners: { [string]: { [string]: { [any]: (...any) -> () } } },
|
|
79
|
+
-- Path array per listened pathKey; the pathKey string is lossy and cannot be
|
|
80
|
+
-- reversed to read a node's value.
|
|
81
|
+
_paths: { [string]: { string | number } },
|
|
82
|
+
-- Ancestor pathKey -> listened pathKeys strictly below it, so a container write
|
|
83
|
+
-- finds its descendant listeners by lookup instead of sweeping every path.
|
|
84
|
+
_descendants: { [string]: { [string]: boolean } },
|
|
85
|
+
-- True only while replaying the initial snapshot: suppresses per-op fires so
|
|
86
|
+
-- descendants can be fired once, together, afterwards.
|
|
87
|
+
_replaying: boolean,
|
|
88
|
+
_batchDepth: number,
|
|
89
|
+
-- Ancestor Changed fires deferred to the end of a batch, keyed by pathKey so N
|
|
90
|
+
-- writes under one container collapse to one fire. Insertion-ordered via
|
|
91
|
+
-- _pendingAncestorOrder, which reproduces the unbatched order.
|
|
92
|
+
_pendingAncestors: { [string]: { string | number } }?,
|
|
93
|
+
_pendingAncestorOrder: { string }?,
|
|
94
|
+
-- Set only while a failed transaction rolls back: dispatch is queued here and
|
|
95
|
+
-- drained once the tree is whole again. See `fire` and `rollbackTransaction`.
|
|
96
|
+
_fireQueue: { { any } }?,
|
|
97
|
+
_txn: {
|
|
98
|
+
Snapshots: { [string]: { Path: { string | number }, Value: any } },
|
|
99
|
+
Below: { [string]: { [string]: boolean } },
|
|
100
|
+
Ops: { { Op: Op, Schema: SchemaNode? } },
|
|
101
|
+
Created: { { string | number } },
|
|
102
|
+
Seeded: { { string | number } },
|
|
103
|
+
Economy: { { Path: { string | number }, Delta: number, New: number, Tags: { [string]: any } } },
|
|
104
|
+
RawRestores: { [string]: { Store: { [string]: any }, Value: any } },
|
|
105
|
+
}?,
|
|
106
|
+
-- Scribe.Derived: fields whose inputs changed and have not been recomputed
|
|
107
|
+
-- yet, and the reentrancy guard for the settle pass that drains them.
|
|
108
|
+
_derivedDirty: { [SchemaNode]: true }?,
|
|
109
|
+
_derivedAudit: { { Path: { string | number }, Label: string, Server: any } }?,
|
|
110
|
+
_derivedSettling: boolean,
|
|
111
|
+
-- Fields whose compute function has already reported a throw this session.
|
|
112
|
+
_derivedLogged: { [SchemaNode]: true }?,
|
|
113
|
+
},
|
|
114
|
+
Tree
|
|
115
|
+
))
|
|
116
|
+
|
|
117
|
+
-- Per-accessor state, stored under keys a caller cannot type. Table identities, not
|
|
118
|
+
-- strings: a rawset string key like "_tree" is found before __index runs, so
|
|
119
|
+
-- `Data.Get(p)._tree` would hand game code the live Tree and its raw stores.
|
|
120
|
+
local F_TREE = {} :: any
|
|
121
|
+
local F_PATH = {} :: any
|
|
122
|
+
local F_KEY = {} :: any
|
|
123
|
+
local F_SCHEMA = {} :: any
|
|
124
|
+
local F_CHILDREN = {} :: any
|
|
125
|
+
|
|
126
|
+
-- The accessors permitted to write under Template.RESERVED_ROOT. A module upvalue
|
|
127
|
+
-- rather than a field, so no object a caller can reach can rawset the capability onto
|
|
128
|
+
-- a public accessor. Weak-keyed: a collected child accessor is rebuilt from its
|
|
129
|
+
-- parent, which re-grants it.
|
|
130
|
+
local PRIVILEGED: { [any]: true } = setmetatable({}, { __mode = "k" }) :: any
|
|
131
|
+
|
|
132
|
+
-- The ONE tree whose transaction is open right now, or nil. `Tree._txn` is per-tree,
|
|
133
|
+
-- right for the journal but wrong as the admission test: a transaction can only undo
|
|
134
|
+
-- writes to its own tree, and another player is another tree behind another DataStore
|
|
135
|
+
-- key. A module upvalue is sound because a transaction is synchronous by construction:
|
|
136
|
+
-- `fn` runs on its own coroutine and a yield is refused. Cleared BEFORE the rollback
|
|
137
|
+
-- restores and before the queued fires drain, so a listener writing after a rollback is
|
|
138
|
+
-- an ordinary write.
|
|
139
|
+
local OPEN_TXN_TREE: Tree? = nil
|
|
140
|
+
|
|
141
|
+
-- The shared half of both cross-tree refusals: why, and the durable outbox to use
|
|
142
|
+
-- instead. One player handing value to another is a real need, so the refusal has to
|
|
143
|
+
-- name the route that works.
|
|
144
|
+
local CROSS_TREE_TXN_WHY = "a transaction can only roll back its OWN player, because another player is "
|
|
145
|
+
.. "another tree behind another DataStore key -- the same reason a yield inside a transaction is "
|
|
146
|
+
.. "refused. For one-sided value (a gift, mail, a reward, a bounty payout) use the durable outbox that "
|
|
147
|
+
.. "gift delivery already uses: record the debit on the giver's own key INSIDE this transaction, "
|
|
148
|
+
.. "Data.Flush it, then deliver with Data.SendMessage and apply it idempotently at the far end. See the "
|
|
149
|
+
.. "Transactions guide."
|
|
150
|
+
|
|
151
|
+
-- The cross-tree refusal, in one place: accessorIndex is not the only writer, since
|
|
152
|
+
-- Server/Timed writes the flat `_Scribe.Timed` store raw. `subject` names what was
|
|
153
|
+
-- written, `level` is the caller's own blame depth. Callers gate on OPEN_TXN_TREE
|
|
154
|
+
-- before building `subject`, which is not worth allocating on every write.
|
|
155
|
+
local function assertSameTreeWrite(tree: Tree?, subject: string, level: number)
|
|
156
|
+
if OPEN_TXN_TREE == nil or tree == OPEN_TXN_TREE then
|
|
157
|
+
return
|
|
158
|
+
end
|
|
159
|
+
-- Not another player, so the outbox route is wrong advice: it has no key at all.
|
|
160
|
+
if tree ~= nil and tree.Params.IsServerStore then
|
|
161
|
+
error(
|
|
162
|
+
`Scribe: "{subject}" is on the ServerStore, not on the player whose transaction is `
|
|
163
|
+
.. `open, so it cannot be written from inside that transaction: a rollback restores one `
|
|
164
|
+
.. `player's own tree, and the store is not saved to any key, so a store write would `
|
|
165
|
+
.. `outlive an aborted transaction. Write the store before Data.Transaction, or after it `
|
|
166
|
+
.. `returns true.`,
|
|
167
|
+
level
|
|
168
|
+
)
|
|
169
|
+
end
|
|
170
|
+
error(
|
|
171
|
+
`Scribe: "{subject}" belongs to a different player than the one `
|
|
172
|
+
.. `whose transaction is open, so it cannot be written from inside that transaction: `
|
|
173
|
+
.. CROSS_TREE_TXN_WHY,
|
|
174
|
+
level
|
|
175
|
+
)
|
|
176
|
+
end
|
|
177
|
+
|
|
178
|
+
local function newAccessor(tree: Tree, path: { string | number }, schema: SchemaNode?, privileged: boolean?): any
|
|
179
|
+
local accessor: any = setmetatable({}, ACCESSOR_MT)
|
|
180
|
+
rawset(accessor, F_TREE, tree)
|
|
181
|
+
rawset(accessor, F_PATH, path)
|
|
182
|
+
rawset(accessor, F_KEY, Util.pathKey(path))
|
|
183
|
+
rawset(accessor, F_SCHEMA, schema)
|
|
184
|
+
-- Weak VALUES: child accessors carry no state (listeners live on the tree, keyed by
|
|
185
|
+
-- pathKey), so a collected one is simply rebuilt on the next index. Without this,
|
|
186
|
+
-- indexing a dictionary by transient keys (GUIDs, trade ids) leaks for the session.
|
|
187
|
+
rawset(accessor, F_CHILDREN, setmetatable({}, { __mode = "v" }))
|
|
188
|
+
if privileged then
|
|
189
|
+
PRIVILEGED[accessor] = true
|
|
190
|
+
end
|
|
191
|
+
return accessor
|
|
192
|
+
end
|
|
193
|
+
|
|
194
|
+
function Node.NewTree(params: TreeParams): Tree
|
|
195
|
+
local self = setmetatable({
|
|
196
|
+
Params = params,
|
|
197
|
+
Compiled = params.Compiled,
|
|
198
|
+
Accessor = nil :: any,
|
|
199
|
+
Reserved = nil :: any,
|
|
200
|
+
Dead = false,
|
|
201
|
+
_listeners = {},
|
|
202
|
+
_paths = {},
|
|
203
|
+
_descendants = {},
|
|
204
|
+
_replaying = false,
|
|
205
|
+
_batchDepth = 0,
|
|
206
|
+
_pendingAncestors = nil,
|
|
207
|
+
_pendingAncestorOrder = nil,
|
|
208
|
+
_fireQueue = nil,
|
|
209
|
+
_txn = nil,
|
|
210
|
+
_derivedDirty = nil,
|
|
211
|
+
_derivedSettling = false,
|
|
212
|
+
_derivedLogged = nil,
|
|
213
|
+
}, Tree) :: Tree
|
|
214
|
+
self.Accessor = newAccessor(self, {}, params.Compiled.Root)
|
|
215
|
+
-- The schema is read straight off Root.Children, not through ChildSchema: a template
|
|
216
|
+
-- lacking the reserved root must not get an AnyChild node synthesized and cached onto
|
|
217
|
+
-- the compiled root as a side effect of building a tree.
|
|
218
|
+
local rootChildren = params.Compiled.Root.Children
|
|
219
|
+
self.Reserved = newAccessor(
|
|
220
|
+
self,
|
|
221
|
+
{ Template.RESERVED_ROOT },
|
|
222
|
+
if rootChildren then rootChildren[Template.RESERVED_ROOT] else nil,
|
|
223
|
+
true
|
|
224
|
+
)
|
|
225
|
+
return self
|
|
226
|
+
end
|
|
227
|
+
|
|
228
|
+
local function assertAlive(tree: Tree)
|
|
229
|
+
if tree.Dead then
|
|
230
|
+
error(`Scribe: data for {tree.Params.Label} has been unloaded`, 3)
|
|
231
|
+
end
|
|
232
|
+
end
|
|
233
|
+
|
|
234
|
+
local function storeFor(tree: Tree, rootKey: string | number): { [string]: any }
|
|
235
|
+
local children = tree.Compiled.Root.Children
|
|
236
|
+
if type(rootKey) == "string" and children then
|
|
237
|
+
local rootSchema = children[rootKey]
|
|
238
|
+
if rootSchema and not rootSchema.Persist then
|
|
239
|
+
return tree.Params.Stores.Session
|
|
240
|
+
end
|
|
241
|
+
end
|
|
242
|
+
return tree.Params.Stores.Persist
|
|
243
|
+
end
|
|
244
|
+
|
|
245
|
+
-- The other-typed form of a key that produces the SAME Util.pathKey (7 <-> "7"), or
|
|
246
|
+
-- nil when there is none. Used to reject a numeric key coexisting with its string
|
|
247
|
+
-- form, whose colliding pathKeys would alias listeners, coalescing and rollback.
|
|
248
|
+
local function aliasForm(seg: any): any
|
|
249
|
+
if type(seg) == "number" then
|
|
250
|
+
return tostring(seg)
|
|
251
|
+
elseif type(seg) == "string" then
|
|
252
|
+
local n = tonumber(seg)
|
|
253
|
+
if n ~= nil and n % 1 == 0 and tostring(n) == seg then
|
|
254
|
+
return n
|
|
255
|
+
end
|
|
256
|
+
end
|
|
257
|
+
return nil
|
|
258
|
+
end
|
|
259
|
+
|
|
260
|
+
-- Container memos -------------------------------------------------------------
|
|
261
|
+
--
|
|
262
|
+
-- Key count and "holds a string key", memoised by container identity so building a
|
|
263
|
+
-- capped or integer-keyed dictionary key by key is not O(n^2). Weak-keyed, and safe
|
|
264
|
+
-- because a whole-table Set installs a different table with no entry yet. Maintained
|
|
265
|
+
-- where a container is ASSIGNED INTO, not where a write is validated: NoValidate and
|
|
266
|
+
-- FromRemote writes skip validation entirely.
|
|
267
|
+
local containerCounts: { [any]: number } = setmetatable({}, { __mode = "k" }) :: any
|
|
268
|
+
-- The offending string key of an integer-keyed container, or `false` for
|
|
269
|
+
-- "walked it, there is none".
|
|
270
|
+
local stringKeyed: { [any]: any } = setmetatable({}, { __mode = "k" }) :: any
|
|
271
|
+
|
|
272
|
+
local function countKeysExact(container: any): number
|
|
273
|
+
local n = 0
|
|
274
|
+
for _ in container do
|
|
275
|
+
n += 1
|
|
276
|
+
end
|
|
277
|
+
containerCounts[container] = n
|
|
278
|
+
return n
|
|
279
|
+
end
|
|
280
|
+
|
|
281
|
+
local function countKeys(container: any): number
|
|
282
|
+
local cached = containerCounts[container]
|
|
283
|
+
if cached ~= nil then
|
|
284
|
+
return cached
|
|
285
|
+
end
|
|
286
|
+
return countKeysExact(container)
|
|
287
|
+
end
|
|
288
|
+
|
|
289
|
+
-- One key of `container` went from absent to present or back. A container with no
|
|
290
|
+
-- memo yet is left alone: the next countKeys walks it once and starts from truth.
|
|
291
|
+
local function noteKeyDelta(container: any, key: any, had: boolean, has: boolean)
|
|
292
|
+
if had == has then
|
|
293
|
+
return
|
|
294
|
+
end
|
|
295
|
+
-- A cached "holds no string key" stops being true the moment one is added. Upgraded
|
|
296
|
+
-- here rather than in the guard because NoValidate and FromRemote writes assign
|
|
297
|
+
-- without reaching validation, and this hook still sees them. A string key going AWAY
|
|
298
|
+
-- is deliberately not tracked: that only leaves a stale "yes", which
|
|
299
|
+
-- blockingStringKey re-derives before acting on.
|
|
300
|
+
if has and type(key) == "string" and stringKeyed[container] == false then
|
|
301
|
+
stringKeyed[container] = key
|
|
302
|
+
end
|
|
303
|
+
local cached = containerCounts[container]
|
|
304
|
+
if cached ~= nil then
|
|
305
|
+
containerCounts[container] = if has then cached + 1 else cached - 1
|
|
306
|
+
end
|
|
307
|
+
end
|
|
308
|
+
|
|
309
|
+
-- Drop both memos for a container mutated in a way this module cannot account for
|
|
310
|
+
-- key by key. Cheaper and safer than trying to reconstruct the delta.
|
|
311
|
+
local function forgetContainer(container: any)
|
|
312
|
+
containerCounts[container] = nil
|
|
313
|
+
stringKeyed[container] = nil
|
|
314
|
+
end
|
|
315
|
+
|
|
316
|
+
-- A container emptied in place (table.clear keeps the identity) has no keys at all, so
|
|
317
|
+
-- neither memo needs re-deriving. Not load-bearing; it just keeps them truthful.
|
|
318
|
+
local function noteContainerCleared(container: any)
|
|
319
|
+
containerCounts[container] = 0
|
|
320
|
+
stringKeyed[container] = false
|
|
321
|
+
end
|
|
322
|
+
|
|
323
|
+
local function scanStringKey(container: any): string?
|
|
324
|
+
for existing in container do
|
|
325
|
+
if type(existing) == "string" then
|
|
326
|
+
stringKeyed[container] = existing
|
|
327
|
+
return existing
|
|
328
|
+
end
|
|
329
|
+
end
|
|
330
|
+
stringKeyed[container] = false
|
|
331
|
+
return nil
|
|
332
|
+
end
|
|
333
|
+
|
|
334
|
+
-- Does this container still hold a string key? Only a Scribe.MapOf("integer") asks, and
|
|
335
|
+
-- only when adding a key, so "no" is the case worth memoising. A cached "yes" is NOT
|
|
336
|
+
-- trusted: such a key goes away by a raw fix-up of the stored table (a migration, an
|
|
337
|
+
-- operator edit) this module never sees, so re-deriving lets the repair take effect
|
|
338
|
+
-- instead of locking the container forever.
|
|
339
|
+
local function blockingStringKey(container: any): string?
|
|
340
|
+
local cached = stringKeyed[container]
|
|
341
|
+
if cached == false then
|
|
342
|
+
return nil
|
|
343
|
+
end
|
|
344
|
+
return scanStringKey(container)
|
|
345
|
+
end
|
|
346
|
+
|
|
347
|
+
-- Would creating `key` in this UNDECLARED container leave it holding an array part and
|
|
348
|
+
-- string keys at once? The DataStore drops half of such a table on encode. Returns a
|
|
349
|
+
-- description of the blocker, or nil.
|
|
350
|
+
--
|
|
351
|
+
-- Deliberately asymmetric: a numeric key is refused whenever a string key is present,
|
|
352
|
+
-- but a string key only when index 1 is occupied, since `{ [7] = ... }` is a legitimate
|
|
353
|
+
-- sparse bag that encodes cleanly.
|
|
354
|
+
local function mixedKeyBlocker(container: any, key: any): string?
|
|
355
|
+
if type(key) == "number" then
|
|
356
|
+
if container[1] ~= nil then
|
|
357
|
+
-- Already array-shaped, so a further index adds nothing the string side did
|
|
358
|
+
-- not already have to permit. Short-circuiting here is also what keeps
|
|
359
|
+
-- building an array key-by-key linear rather than quadratic.
|
|
360
|
+
return nil
|
|
361
|
+
end
|
|
362
|
+
local blocking = blockingStringKey(container)
|
|
363
|
+
if blocking ~= nil then
|
|
364
|
+
return `the string key "{blocking}"`
|
|
365
|
+
end
|
|
366
|
+
return nil
|
|
367
|
+
end
|
|
368
|
+
if container[1] ~= nil then
|
|
369
|
+
return "an array starting at index 1"
|
|
370
|
+
end
|
|
371
|
+
return nil
|
|
372
|
+
end
|
|
373
|
+
|
|
374
|
+
local function checkContainerKey(
|
|
375
|
+
containerSchema: SchemaNode?,
|
|
376
|
+
container: any,
|
|
377
|
+
key: any,
|
|
378
|
+
path: { any },
|
|
379
|
+
upto: number,
|
|
380
|
+
removing: boolean?
|
|
381
|
+
)
|
|
382
|
+
-- Rendered only when refusing; this runs on every container write.
|
|
383
|
+
local function where(): string
|
|
384
|
+
return Util.pathString(table.move(path, 1, upto, 1, {}))
|
|
385
|
+
end
|
|
386
|
+
local kind = if containerSchema then containerSchema.Container else nil
|
|
387
|
+
if kind == nil then
|
|
388
|
+
-- No declared key type, but an undeclared container still may not become a mixed
|
|
389
|
+
-- array/hash table. Only key CREATION is judged: a removal, or a write to a key
|
|
390
|
+
-- already there, must stay possible or a profile that loaded already mixed has no
|
|
391
|
+
-- way to repair itself.
|
|
392
|
+
if not removing and container[key] == nil then
|
|
393
|
+
local blocker = mixedKeyBlocker(container, key)
|
|
394
|
+
if blocker ~= nil then
|
|
395
|
+
-- A write on the profile root has an empty path prefix, and `"" already
|
|
396
|
+
-- holds ...` reads like a bug in the message. Name the root instead.
|
|
397
|
+
local label = if where() == "" then "the profile root" else `"{where()}"`
|
|
398
|
+
error(
|
|
399
|
+
`Scribe: {label} already holds {blocker}, so adding the key {tostring(key)} would make it `
|
|
400
|
+
.. "a mixed array/hash table -- the DataStore drops half of one on save, and Set on the "
|
|
401
|
+
.. "parent refuses the same shape. Use one key type for this container",
|
|
402
|
+
0
|
|
403
|
+
)
|
|
404
|
+
end
|
|
405
|
+
end
|
|
406
|
+
return
|
|
407
|
+
end
|
|
408
|
+
local schema = containerSchema :: SchemaNode
|
|
409
|
+
if kind == "Array" then
|
|
410
|
+
if type(key) ~= "number" then
|
|
411
|
+
error(
|
|
412
|
+
`Scribe: "{where()}" is a Scribe.ArrayOf and takes array indices, but the key "{tostring(key)}" `
|
|
413
|
+
.. `is a {type(key)}`,
|
|
414
|
+
0
|
|
415
|
+
)
|
|
416
|
+
end
|
|
417
|
+
local len = #container
|
|
418
|
+
if removing then
|
|
419
|
+
-- Only the tail can go away by a nil write without leaving a hole. Removing
|
|
420
|
+
-- a key that is not there stays a no-op.
|
|
421
|
+
if container[key] ~= nil and key ~= len then
|
|
422
|
+
error(
|
|
423
|
+
`Scribe: "{where()}" is a Scribe.ArrayOf and must stay contiguous; use Remove({key}) `
|
|
424
|
+
.. `instead of setting index {key} to nil`,
|
|
425
|
+
0
|
|
426
|
+
)
|
|
427
|
+
end
|
|
428
|
+
return
|
|
429
|
+
end
|
|
430
|
+
if key % 1 ~= 0 or key < 1 or key > len + 1 then
|
|
431
|
+
error(
|
|
432
|
+
`Scribe: index {key} is out of range for "{where()}" (length {len}); `
|
|
433
|
+
.. "array elements are created with Insert",
|
|
434
|
+
0
|
|
435
|
+
)
|
|
436
|
+
end
|
|
437
|
+
-- Growth only: an entry past the cap that already exists stays writable,
|
|
438
|
+
-- because a newer-template server may have stored it before this server's
|
|
439
|
+
-- lower cap deployed, and stranding it turns a rolling deploy into lost writes.
|
|
440
|
+
if schema.MaxItems and key > schema.MaxItems and container[key] == nil then
|
|
441
|
+
error(`Scribe: "{where()}" is capped at MaxItems {schema.MaxItems}`, 0)
|
|
442
|
+
end
|
|
443
|
+
else
|
|
444
|
+
-- Scribe.MapOf declares its key type; a plain Scribe.DictOf is string-keyed.
|
|
445
|
+
local keyType = schema.KeyType or "string"
|
|
446
|
+
if keyType == "integer" then
|
|
447
|
+
if type(key) ~= "number" then
|
|
448
|
+
error(
|
|
449
|
+
`Scribe: "{where()}" is a Scribe.MapOf("integer") and takes integer keys, but the key `
|
|
450
|
+
.. `{tostring(key)} is a {type(key)}`,
|
|
451
|
+
0
|
|
452
|
+
)
|
|
453
|
+
end
|
|
454
|
+
-- A DataStore serializes object keys to JSON strings, and only a finite
|
|
455
|
+
-- integer survives that round trip unambiguously.
|
|
456
|
+
if key ~= key or key == math.huge or key == -math.huge or key % 1 ~= 0 then
|
|
457
|
+
error(`Scribe: "{where()}" takes finite integer keys, got {tostring(key)}`, 0)
|
|
458
|
+
end
|
|
459
|
+
elseif type(key) ~= "string" then
|
|
460
|
+
local declarator = if schema.KeyType then `Scribe.MapOf("string")` else "Scribe.DictOf"
|
|
461
|
+
error(
|
|
462
|
+
`Scribe: "{where()}" is a {declarator} and takes string keys, but the key {tostring(key)} `
|
|
463
|
+
.. `is a {type(key)}`,
|
|
464
|
+
0
|
|
465
|
+
)
|
|
466
|
+
end
|
|
467
|
+
if removing then
|
|
468
|
+
return
|
|
469
|
+
end
|
|
470
|
+
-- A new integer key in a container that still holds a string one gives a
|
|
471
|
+
-- table with both key types, which fails the WHOLE profile save, not just
|
|
472
|
+
-- this field. Reachable when load-time coercion was blocked by a
|
|
473
|
+
-- non-canonical spelling ("07", "1.5"). Refuse and name the blocker.
|
|
474
|
+
if keyType == "integer" and container[key] == nil then
|
|
475
|
+
local blocking = blockingStringKey(container)
|
|
476
|
+
if blocking ~= nil then
|
|
477
|
+
error(
|
|
478
|
+
`Scribe: "{where()}" is a Scribe.MapOf("integer") but still holds the string key `
|
|
479
|
+
.. `"{blocking}", which load-time coercion could not convert. Writing an integer `
|
|
480
|
+
.. "key now would leave both key types in one table, which fails the whole "
|
|
481
|
+
.. "profile save. Remove or migrate that key first",
|
|
482
|
+
0
|
|
483
|
+
)
|
|
484
|
+
end
|
|
485
|
+
end
|
|
486
|
+
local maxKeyLength = if keyType == "string" then schema.MaxKeyLength else nil
|
|
487
|
+
if maxKeyLength and #(key :: string) > maxKeyLength then
|
|
488
|
+
-- Reject rather than truncate: a truncated key writes to the wrong slot.
|
|
489
|
+
error(`Scribe: key "{key}" at "{where()}" is {#(key :: string)} bytes, over MaxKeyLength {maxKeyLength}`, 0)
|
|
490
|
+
end
|
|
491
|
+
local maxKeys = schema.MaxKeys
|
|
492
|
+
if maxKeys and container[key] == nil then
|
|
493
|
+
local count = countKeys(container)
|
|
494
|
+
if count >= maxKeys then
|
|
495
|
+
-- At the cap according to the memo. Re-derive before refusing, so a
|
|
496
|
+
-- memo drifted by a caller mutating the live table from a container
|
|
497
|
+
-- Get() costs a walk rather than rejecting a legitimate write.
|
|
498
|
+
count = countKeysExact(container)
|
|
499
|
+
end
|
|
500
|
+
if count >= maxKeys then
|
|
501
|
+
error(`Scribe: "{where()}" already holds {count} keys, at its MaxKeys {maxKeys}`, 0)
|
|
502
|
+
end
|
|
503
|
+
end
|
|
504
|
+
end
|
|
505
|
+
end
|
|
506
|
+
|
|
507
|
+
-- Resolves the container holding path's last segment, materializing missing
|
|
508
|
+
-- intermediates when `create`. `schema` is the LAST segment's schema; the
|
|
509
|
+
-- per-segment ones come from walking its Parent chain, which mirrors the path.
|
|
510
|
+
local function resolveContainer(
|
|
511
|
+
tree: Tree,
|
|
512
|
+
path: { string | number },
|
|
513
|
+
create: boolean,
|
|
514
|
+
schema: SchemaNode?,
|
|
515
|
+
validating: boolean?
|
|
516
|
+
): (any, any)
|
|
517
|
+
local n = #path
|
|
518
|
+
if n == 0 then
|
|
519
|
+
return nil, nil
|
|
520
|
+
end
|
|
521
|
+
local chain: { SchemaNode }? = nil
|
|
522
|
+
if create and schema ~= nil and n > 1 then
|
|
523
|
+
local c = table.create(n) :: { SchemaNode }
|
|
524
|
+
local cursor: SchemaNode? = schema
|
|
525
|
+
for i = n, 1, -1 do
|
|
526
|
+
if cursor == nil then
|
|
527
|
+
break
|
|
528
|
+
end
|
|
529
|
+
c[i] = cursor
|
|
530
|
+
cursor = cursor.Parent
|
|
531
|
+
end
|
|
532
|
+
chain = c
|
|
533
|
+
end
|
|
534
|
+
local container: any = storeFor(tree, path[1])
|
|
535
|
+
for i = 1, n - 1 do
|
|
536
|
+
local seg = path[i]
|
|
537
|
+
local nextContainer = container[seg]
|
|
538
|
+
if nextContainer == nil then
|
|
539
|
+
if not create then
|
|
540
|
+
return nil, nil
|
|
541
|
+
end
|
|
542
|
+
-- The container written into is path[1..i-1], so its schema is the chain
|
|
543
|
+
-- entry one level up; i == 1 is the store root, never a declared
|
|
544
|
+
-- container. Validated writes only: a remote apply must never throw here,
|
|
545
|
+
-- because one throw drops the rest of the frame and desyncs the mirror.
|
|
546
|
+
if validating and chain and i > 1 then
|
|
547
|
+
checkContainerKey(chain[i - 1], container, seg, path, i - 1)
|
|
548
|
+
end
|
|
549
|
+
-- Same alias hazard applySet guards for the leaf key: a nested write like
|
|
550
|
+
-- Dict[7].Sub must not create a numeric 7 next to an existing string "7".
|
|
551
|
+
local alias = aliasForm(seg)
|
|
552
|
+
if alias ~= nil and container[alias] ~= nil then
|
|
553
|
+
error(
|
|
554
|
+
`Scribe: key "{tostring(seg)}" at "{Util.pathString(path)}" collides with the existing `
|
|
555
|
+
.. `"{tostring(alias)}" key form (a numeric key and its string form cannot coexist)`,
|
|
556
|
+
0
|
|
557
|
+
)
|
|
558
|
+
end
|
|
559
|
+
-- A declared element materializes from its compiled defaults, so writing
|
|
560
|
+
-- one field of a fresh key does not leave the rest nil against a type
|
|
561
|
+
-- that says they are always present.
|
|
562
|
+
local createdSchema = if chain then chain[i] else nil
|
|
563
|
+
local seed: any = nil
|
|
564
|
+
if createdSchema and createdSchema.IsElement then
|
|
565
|
+
-- The mirror gets the ServerOnly-stripped copy; the full default would
|
|
566
|
+
-- surface a value on the client that no replicated op ever sent.
|
|
567
|
+
seed = if tree.Params.IsServer then createdSchema.Default else createdSchema.ClientDefault
|
|
568
|
+
end
|
|
569
|
+
nextContainer = if type(seed) == "table" then Util.deepClone(seed) else {}
|
|
570
|
+
local segHad = container[seg] ~= nil
|
|
571
|
+
container[seg] = nextContainer
|
|
572
|
+
noteKeyDelta(container, seg, segHad, true)
|
|
573
|
+
-- Recorded so a rollback can prune containers that never existed pre-txn.
|
|
574
|
+
local txn = tree._txn
|
|
575
|
+
if txn then
|
|
576
|
+
txn.Created[#txn.Created + 1] = table.move(path, 1, i, 1, table.create(i) :: { string | number })
|
|
577
|
+
end
|
|
578
|
+
elseif type(nextContainer) ~= "table" then
|
|
579
|
+
if not create then
|
|
580
|
+
-- A READ through a segment that now holds a scalar answers nil, as a
|
|
581
|
+
-- read through an absent segment does. readValue is on the apply path
|
|
582
|
+
-- twice (snapshotDescendants and fireDescendants), so raising here would
|
|
583
|
+
-- kill the frame and desync the mirror for good. Only a WRITE raises.
|
|
584
|
+
return nil, nil
|
|
585
|
+
end
|
|
586
|
+
error(`Scribe: cannot index "{Util.pathString(path)}": "{tostring(seg)}" is not a table`, 0)
|
|
587
|
+
end
|
|
588
|
+
container = nextContainer
|
|
589
|
+
end
|
|
590
|
+
return container, path[n]
|
|
591
|
+
end
|
|
592
|
+
|
|
593
|
+
local function readValue(tree: Tree, path: { string | number }): any
|
|
594
|
+
if #path == 0 then
|
|
595
|
+
return tree.Params.Stores.Persist
|
|
596
|
+
end
|
|
597
|
+
local container, key = resolveContainer(tree, path, false)
|
|
598
|
+
if container == nil then
|
|
599
|
+
return nil
|
|
600
|
+
end
|
|
601
|
+
return container[key]
|
|
602
|
+
end
|
|
603
|
+
|
|
604
|
+
-- Listeners ---------------------------------------------------------------------
|
|
605
|
+
|
|
606
|
+
local function listenersFor(tree: Tree, pathKey: string, event: string, create: boolean): { [any]: (...any) -> () }?
|
|
607
|
+
local byEvent = tree._listeners[pathKey]
|
|
608
|
+
if byEvent == nil then
|
|
609
|
+
if not create then
|
|
610
|
+
return nil
|
|
611
|
+
end
|
|
612
|
+
byEvent = {}
|
|
613
|
+
tree._listeners[pathKey] = byEvent
|
|
614
|
+
end
|
|
615
|
+
local list = byEvent[event]
|
|
616
|
+
if list == nil then
|
|
617
|
+
if not create then
|
|
618
|
+
return nil
|
|
619
|
+
end
|
|
620
|
+
list = {}
|
|
621
|
+
byEvent[event] = list
|
|
622
|
+
end
|
|
623
|
+
return list
|
|
624
|
+
end
|
|
625
|
+
|
|
626
|
+
-- Calls `fn` with every strict ancestor pathKey of `pathKey`, outermost first. A
|
|
627
|
+
-- segment can never contain the \31 separator (control characters are refused at
|
|
628
|
+
-- write time), so a prefix ending at one is exactly an ancestor.
|
|
629
|
+
local function forEachAncestorKey(pathKey: string, fn: (string) -> ())
|
|
630
|
+
local at = string.find(pathKey, "\31", 1, true)
|
|
631
|
+
while at do
|
|
632
|
+
fn(string.sub(pathKey, 1, at - 1))
|
|
633
|
+
at = string.find(pathKey, "\31", at + 1, true)
|
|
634
|
+
end
|
|
635
|
+
end
|
|
636
|
+
|
|
637
|
+
-- Register/unregister `pathKey` under each of its ancestors, so a write at an
|
|
638
|
+
-- ancestor can find everything listening below it without sweeping every path.
|
|
639
|
+
local function indexDescendant(tree: Tree, pathKey: string)
|
|
640
|
+
forEachAncestorKey(pathKey, function(ancestor)
|
|
641
|
+
local set = tree._descendants[ancestor]
|
|
642
|
+
if set == nil then
|
|
643
|
+
set = {}
|
|
644
|
+
tree._descendants[ancestor] = set
|
|
645
|
+
end
|
|
646
|
+
set[pathKey] = true
|
|
647
|
+
end)
|
|
648
|
+
end
|
|
649
|
+
|
|
650
|
+
local function unindexDescendant(tree: Tree, pathKey: string)
|
|
651
|
+
forEachAncestorKey(pathKey, function(ancestor)
|
|
652
|
+
local set = tree._descendants[ancestor]
|
|
653
|
+
if set ~= nil then
|
|
654
|
+
set[pathKey] = nil
|
|
655
|
+
if next(set) == nil then
|
|
656
|
+
tree._descendants[ancestor] = nil
|
|
657
|
+
end
|
|
658
|
+
end
|
|
659
|
+
end)
|
|
660
|
+
end
|
|
661
|
+
|
|
662
|
+
local function connect(tree: Tree, path: { string | number }, event: string, fn: (...any) -> ()): () -> ()
|
|
663
|
+
assertAlive(tree)
|
|
664
|
+
local pathKey = Util.pathKey(path)
|
|
665
|
+
local list = listenersFor(tree, pathKey, event, true) :: { [any]: (...any) -> () }
|
|
666
|
+
if tree._paths[pathKey] == nil then
|
|
667
|
+
indexDescendant(tree, pathKey)
|
|
668
|
+
end
|
|
669
|
+
tree._paths[pathKey] = path
|
|
670
|
+
local token = {}
|
|
671
|
+
list[token] = fn
|
|
672
|
+
return function()
|
|
673
|
+
local byEvent = tree._listeners[pathKey]
|
|
674
|
+
local current = byEvent and byEvent[event]
|
|
675
|
+
if current then
|
|
676
|
+
current[token] = nil
|
|
677
|
+
-- Reclaim now-empty listener tables so they don't accumulate and
|
|
678
|
+
-- permanently defeat the fireAncestors no-listener fast path.
|
|
679
|
+
if next(current) == nil then
|
|
680
|
+
byEvent[event] = nil
|
|
681
|
+
if next(byEvent) == nil then
|
|
682
|
+
tree._listeners[pathKey] = nil
|
|
683
|
+
tree._paths[pathKey] = nil
|
|
684
|
+
unindexDescendant(tree, pathKey)
|
|
685
|
+
end
|
|
686
|
+
end
|
|
687
|
+
end
|
|
688
|
+
end
|
|
689
|
+
end
|
|
690
|
+
|
|
691
|
+
local function fire(tree: Tree, pathKey: string, event: string, ...: any)
|
|
692
|
+
if tree._replaying then
|
|
693
|
+
return -- suppressed during the Init replay; fired together afterwards
|
|
694
|
+
end
|
|
695
|
+
local list = listenersFor(tree, pathKey, event, false)
|
|
696
|
+
if list == nil then
|
|
697
|
+
return
|
|
698
|
+
end
|
|
699
|
+
-- A rollback restores many paths one at a time; dispatching as each lands would
|
|
700
|
+
-- let a listener read and write from a half-restored tree that never existed.
|
|
701
|
+
-- Queue instead, and RunTransaction drains once every restore has landed. Unlike
|
|
702
|
+
-- the `_replaying` suppression above, nothing is dropped: only the dispatch moves.
|
|
703
|
+
local queue = tree._fireQueue
|
|
704
|
+
if queue ~= nil then
|
|
705
|
+
queue[#queue + 1] = { pathKey, event, table.pack(...) }
|
|
706
|
+
return
|
|
707
|
+
end
|
|
708
|
+
local args = table.pack(...)
|
|
709
|
+
-- Snapshot the listeners before dispatch: a callback may connect or disconnect
|
|
710
|
+
-- into this same live table, and mutating during generalized iteration is
|
|
711
|
+
-- undefined in Luau. Semantics match GoodSignal: a listener connected during the
|
|
712
|
+
-- fire does not receive it, and one disconnected mid-fire is not called.
|
|
713
|
+
local tokens = {}
|
|
714
|
+
local fns = {}
|
|
715
|
+
for token, fn in list do
|
|
716
|
+
tokens[#tokens + 1] = token
|
|
717
|
+
fns[#fns + 1] = fn
|
|
718
|
+
end
|
|
719
|
+
for i = 1, #fns do
|
|
720
|
+
if list[tokens[i]] == nil then
|
|
721
|
+
continue -- disconnected by an earlier listener during this fire
|
|
722
|
+
end
|
|
723
|
+
local fn = fns[i]
|
|
724
|
+
local ok, err = xpcall(function()
|
|
725
|
+
fn(table.unpack(args, 1, args.n))
|
|
726
|
+
end, function(e)
|
|
727
|
+
return debug.traceback(tostring(e), 2)
|
|
728
|
+
end)
|
|
729
|
+
if not ok then
|
|
730
|
+
tree.Params.LogError(`listener error at "{pathKey}" ({event}): {err}`)
|
|
731
|
+
end
|
|
732
|
+
end
|
|
733
|
+
end
|
|
734
|
+
|
|
735
|
+
-- Walks up from `path` firing two kinds of event on each ancestor. OnChildChanged is a
|
|
736
|
+
-- TRANSITION, so it fires immediately and is never coalesced, which would destroy what
|
|
737
|
+
-- it reports. Changed is STATE, and its `old` is the same reference as `new`, so a batch
|
|
738
|
+
-- can collapse it losing nothing.
|
|
739
|
+
--
|
|
740
|
+
-- `childOld` is the deepest ancestor's immediate child's prior value, passed only by
|
|
741
|
+
-- applySet. It needs its own `known` flag because nil is a legitimate prior value.
|
|
742
|
+
local function fireAncestors(tree: Tree, path: { string | number }, childOld: any, childOldKnown: boolean?)
|
|
743
|
+
if next(tree._listeners) == nil then
|
|
744
|
+
return
|
|
745
|
+
end
|
|
746
|
+
local deferring = tree._batchDepth > 0
|
|
747
|
+
-- The child of the ancestor at `depth` is the prefix of length depth + 1, i.e.
|
|
748
|
+
-- the previous iteration's already-allocated prefix. Starts as `path` itself.
|
|
749
|
+
local childPrefix: { string | number } = path
|
|
750
|
+
for depth = #path - 1, 0, -1 do
|
|
751
|
+
local prefix = table.move(path, 1, depth, 1, table.create(depth) :: { string | number })
|
|
752
|
+
local pathKey = Util.pathKey(prefix)
|
|
753
|
+
local byEvent = tree._listeners[pathKey]
|
|
754
|
+
if byEvent ~= nil then
|
|
755
|
+
local childList = byEvent.OnChildChanged
|
|
756
|
+
if childList and next(childList) ~= nil then
|
|
757
|
+
-- Read the child on its OWN path, not by indexing the parent's table:
|
|
758
|
+
-- at the root, readValue short-circuits to Stores.Persist, so
|
|
759
|
+
-- `parentValue[key]` would read nil for a Session root's child.
|
|
760
|
+
local childNew = readValue(tree, childPrefix)
|
|
761
|
+
local previous = if depth == #path - 1 and childOldKnown then childOld else childNew
|
|
762
|
+
fire(tree, pathKey, "OnChildChanged", path[depth + 1], childNew, previous)
|
|
763
|
+
end
|
|
764
|
+
local list = byEvent.Changed
|
|
765
|
+
if list and next(list) ~= nil then
|
|
766
|
+
if not deferring then
|
|
767
|
+
local value = readValue(tree, prefix)
|
|
768
|
+
fire(tree, pathKey, "Changed", value, value)
|
|
769
|
+
else
|
|
770
|
+
local pending = tree._pendingAncestors
|
|
771
|
+
if pending == nil then
|
|
772
|
+
pending = {}
|
|
773
|
+
tree._pendingAncestors = pending
|
|
774
|
+
tree._pendingAncestorOrder = {}
|
|
775
|
+
end
|
|
776
|
+
if (pending :: any)[pathKey] == nil then
|
|
777
|
+
(pending :: any)[pathKey] = prefix
|
|
778
|
+
local order = tree._pendingAncestorOrder :: { string }
|
|
779
|
+
order[#order + 1] = pathKey
|
|
780
|
+
end
|
|
781
|
+
end
|
|
782
|
+
end
|
|
783
|
+
end
|
|
784
|
+
childPrefix = prefix
|
|
785
|
+
end
|
|
786
|
+
end
|
|
787
|
+
|
|
788
|
+
-- A container's own STATE fire, routed through the defer queue fireAncestors uses.
|
|
789
|
+
-- Insert/Remove/Clear mutate at the container's own path, so they never reach
|
|
790
|
+
-- fireAncestors for that node and would otherwise fire N times in a batch where every
|
|
791
|
+
-- other container fires once. Safe to collapse: the fire is (value, value), and OnInsert
|
|
792
|
+
-- and OnRemove carry the per-entry transitions separately.
|
|
793
|
+
local function deferSelfState(tree: Tree, pathKey: string, path: { string | number }): boolean
|
|
794
|
+
if tree._replaying then
|
|
795
|
+
-- Same suppression `fire` applies: ReplayFire fires every observed path
|
|
796
|
+
-- itself once the apply is done, so queuing here would double it.
|
|
797
|
+
return true
|
|
798
|
+
end
|
|
799
|
+
if tree._batchDepth == 0 then
|
|
800
|
+
return false
|
|
801
|
+
end
|
|
802
|
+
local list = listenersFor(tree, pathKey, "Changed", false)
|
|
803
|
+
if list == nil or next(list) == nil then
|
|
804
|
+
return true -- nothing listening: skip the fire either way
|
|
805
|
+
end
|
|
806
|
+
local pending = tree._pendingAncestors
|
|
807
|
+
if pending == nil then
|
|
808
|
+
pending = {}
|
|
809
|
+
tree._pendingAncestors = pending
|
|
810
|
+
tree._pendingAncestorOrder = {}
|
|
811
|
+
end
|
|
812
|
+
if (pending :: any)[pathKey] == nil then
|
|
813
|
+
(pending :: any)[pathKey] = table.clone(path)
|
|
814
|
+
local order = tree._pendingAncestorOrder :: { string }
|
|
815
|
+
order[#order + 1] = pathKey
|
|
816
|
+
end
|
|
817
|
+
return true
|
|
818
|
+
end
|
|
819
|
+
|
|
820
|
+
-- Fire the ancestor Changed events a batch deferred, one per container. Values are
|
|
821
|
+
-- read NOW, so every listener sees the batch's end state.
|
|
822
|
+
--
|
|
823
|
+
-- Order is first-touch, which reproduces the unbatched order minus the duplicates. It
|
|
824
|
+
-- is NOT globally deepest-first, and sorting it that way would move fires.
|
|
825
|
+
local function flushPendingAncestors(tree: Tree)
|
|
826
|
+
local pending = tree._pendingAncestors
|
|
827
|
+
if pending == nil then
|
|
828
|
+
return
|
|
829
|
+
end
|
|
830
|
+
local order = tree._pendingAncestorOrder :: { string }
|
|
831
|
+
tree._pendingAncestors = nil
|
|
832
|
+
tree._pendingAncestorOrder = nil
|
|
833
|
+
for _, pathKey in order do
|
|
834
|
+
local list = listenersFor(tree, pathKey, "Changed", false)
|
|
835
|
+
if list and next(list) ~= nil then
|
|
836
|
+
local value = readValue(tree, pending[pathKey])
|
|
837
|
+
fire(tree, pathKey, "Changed", value, value)
|
|
838
|
+
end
|
|
839
|
+
end
|
|
840
|
+
end
|
|
841
|
+
|
|
842
|
+
-- Drop a rolled-back transaction's deferred fires; the restores below fire their own
|
|
843
|
+
-- Changed with the pre-transaction values. Scoped by a mark taken when the transaction
|
|
844
|
+
-- opened, because the queue is tree-wide: a transaction nested in a Data.Batch shares it
|
|
845
|
+
-- with the batch's surviving writes, and clearing it wholesale would swallow those too.
|
|
846
|
+
local function discardPendingAncestors(tree: Tree, mark: number)
|
|
847
|
+
local order = tree._pendingAncestorOrder
|
|
848
|
+
if order == nil then
|
|
849
|
+
return
|
|
850
|
+
end
|
|
851
|
+
local pending = tree._pendingAncestors :: any
|
|
852
|
+
for i = #order, mark + 1, -1 do
|
|
853
|
+
pending[order[i]] = nil
|
|
854
|
+
order[i] = nil
|
|
855
|
+
end
|
|
856
|
+
if mark == 0 then
|
|
857
|
+
tree._pendingAncestors = nil
|
|
858
|
+
tree._pendingAncestorOrder = nil
|
|
859
|
+
end
|
|
860
|
+
end
|
|
861
|
+
|
|
862
|
+
-- Stands in for "this path held nothing" in a descendant snapshot: `olds[key] = nil`
|
|
863
|
+
-- stores no entry, so an absent-to-present descendant would be invisible to the diff.
|
|
864
|
+
-- That is the ordinary case, not an edge one (every appended array element).
|
|
865
|
+
local ABSENT = table.freeze({})
|
|
866
|
+
|
|
867
|
+
-- A whole-table write changes every leaf beneath it, but `fire` touches only that
|
|
868
|
+
-- pathKey and `fireAncestors` walks upward, so a descendant listener would never hear
|
|
869
|
+
-- about it. These two snapshot the observed descendants before the write and fire
|
|
870
|
+
-- whichever changed after it. Scoped to STRICT descendants: the written path is fired
|
|
871
|
+
-- by the caller, and including it would double-fire the container's own observer.
|
|
872
|
+
local function snapshotDescendants(tree: Tree, pathKey: string): { [string]: any }?
|
|
873
|
+
if next(tree._listeners) == nil then
|
|
874
|
+
return nil
|
|
875
|
+
end
|
|
876
|
+
-- Indexed, not swept: _descendants answers this in one lookup, so a write does
|
|
877
|
+
-- not cost a prefix match against every path the game is listening to.
|
|
878
|
+
local below = tree._descendants[pathKey]
|
|
879
|
+
if below == nil then
|
|
880
|
+
return nil
|
|
881
|
+
end
|
|
882
|
+
local olds: { [string]: any }? = nil
|
|
883
|
+
for key in below do
|
|
884
|
+
local byEvent = tree._listeners[key]
|
|
885
|
+
if byEvent and byEvent.Changed then
|
|
886
|
+
local path = tree._paths[key]
|
|
887
|
+
if path then
|
|
888
|
+
olds = olds or {}
|
|
889
|
+
local was = readValue(tree, path)
|
|
890
|
+
local slot = olds :: { [string]: any }
|
|
891
|
+
slot[key] = if was == nil then ABSENT else was
|
|
892
|
+
end
|
|
893
|
+
end
|
|
894
|
+
end
|
|
895
|
+
return olds
|
|
896
|
+
end
|
|
897
|
+
|
|
898
|
+
local function fireDescendants(tree: Tree, olds: { [string]: any }?)
|
|
899
|
+
if not olds then
|
|
900
|
+
return
|
|
901
|
+
end
|
|
902
|
+
-- Collect before firing: a fired listener may add or remove listeners.
|
|
903
|
+
local pending: { { Key: string, New: any, Old: any } } = {}
|
|
904
|
+
for key, parked in olds do
|
|
905
|
+
local path = tree._paths[key]
|
|
906
|
+
if path then
|
|
907
|
+
local old = if parked == ABSENT then nil else parked
|
|
908
|
+
local current = readValue(tree, path)
|
|
909
|
+
-- Identity, not leafEquals, which reports tables as never equal. Both sides
|
|
910
|
+
-- are the same path read before and after one mutation, so a container still
|
|
911
|
+
-- holding its original table held its contents too. Insert at the tail
|
|
912
|
+
-- depends on this, or it wakes every bound row in the array.
|
|
913
|
+
if current ~= old then
|
|
914
|
+
table.insert(pending, { Key = key, New = current, Old = old })
|
|
915
|
+
end
|
|
916
|
+
end
|
|
917
|
+
end
|
|
918
|
+
for _, item in pending do
|
|
919
|
+
fire(tree, item.Key, "Changed", item.New, item.Old)
|
|
920
|
+
end
|
|
921
|
+
end
|
|
922
|
+
|
|
923
|
+
-- Key transitions for the containers a whole-table write REWRITES. applySet reports only
|
|
924
|
+
-- the one key it wrote, so a Set at an ancestor would add or drop keys further down with
|
|
925
|
+
-- nothing saying so. Scoped to STRICT descendants, like `snapshotDescendants`: the
|
|
926
|
+
-- written path's own contents are a bulk state change. The snapshot is a shallow
|
|
927
|
+
-- key -> value map per container bound to OnKeyAdded/OnKeyRemoved.
|
|
928
|
+
type KeyedSnapshot = {
|
|
929
|
+
Key: string,
|
|
930
|
+
Path: { string | number },
|
|
931
|
+
Schema: SchemaNode?,
|
|
932
|
+
Old: { [any]: any },
|
|
933
|
+
}
|
|
934
|
+
|
|
935
|
+
-- Resolve the schema at `path` starting from the node that sits at depth `from - 1`.
|
|
936
|
+
local function schemaBelow(base: SchemaNode?, path: { string | number }, from: number): SchemaNode?
|
|
937
|
+
local node = base
|
|
938
|
+
for i = from, #path do
|
|
939
|
+
if node == nil then
|
|
940
|
+
return nil
|
|
941
|
+
end
|
|
942
|
+
node = Template.ChildSchema(node, path[i])
|
|
943
|
+
end
|
|
944
|
+
return node
|
|
945
|
+
end
|
|
946
|
+
|
|
947
|
+
-- The same dynamic-key test applySet applies to a direct parent: a DECLARED child is
|
|
948
|
+
-- part of a record's fixed shape, so it never appears or disappears as a key.
|
|
949
|
+
local function isDynamicKey(node: SchemaNode?, key: any): boolean
|
|
950
|
+
local declared = if node then node.Children else nil
|
|
951
|
+
return declared == nil or type(key) ~= "string" or declared[key :: string] == nil
|
|
952
|
+
end
|
|
953
|
+
|
|
954
|
+
local function snapshotKeyed(tree: Tree, pathKey: string, depth: number, schema: SchemaNode?): { KeyedSnapshot }?
|
|
955
|
+
local below = tree._descendants[pathKey]
|
|
956
|
+
if below == nil then
|
|
957
|
+
return nil
|
|
958
|
+
end
|
|
959
|
+
local out: { KeyedSnapshot }? = nil
|
|
960
|
+
for key in below do
|
|
961
|
+
local byEvent = tree._listeners[key]
|
|
962
|
+
if byEvent ~= nil and (byEvent.OnKeyAdded ~= nil or byEvent.OnKeyRemoved ~= nil) then
|
|
963
|
+
local p = tree._paths[key]
|
|
964
|
+
if p ~= nil then
|
|
965
|
+
local node = schemaBelow(schema, p, depth + 1)
|
|
966
|
+
-- A Scribe.Big and a Scribe.Flags are leaves that merely store as
|
|
967
|
+
-- tables: their keys are an encoding, not container entries.
|
|
968
|
+
if node == nil or (node.ValueType ~= "big" and node.ValueType ~= "flags") then
|
|
969
|
+
local current = readValue(tree, p)
|
|
970
|
+
local olds: { [any]: any } = {}
|
|
971
|
+
if type(current) == "table" then
|
|
972
|
+
for k, v in current :: { [any]: any } do
|
|
973
|
+
olds[k] = v
|
|
974
|
+
end
|
|
975
|
+
end
|
|
976
|
+
local list = out or {}
|
|
977
|
+
out = list
|
|
978
|
+
list[#list + 1] = { Key = key, Path = p, Schema = node, Old = olds }
|
|
979
|
+
end
|
|
980
|
+
end
|
|
981
|
+
end
|
|
982
|
+
end
|
|
983
|
+
return out
|
|
984
|
+
end
|
|
985
|
+
|
|
986
|
+
local function fireKeyDeltas(tree: Tree, snapshots: { KeyedSnapshot }?)
|
|
987
|
+
if snapshots == nil then
|
|
988
|
+
return
|
|
989
|
+
end
|
|
990
|
+
for _, entry in snapshots do
|
|
991
|
+
local current = readValue(tree, entry.Path)
|
|
992
|
+
local new: { [any]: any } = if type(current) == "table" then current :: any else {}
|
|
993
|
+
local old = entry.Old
|
|
994
|
+
for k, v in new do
|
|
995
|
+
if old[k] == nil and isDynamicKey(entry.Schema, k) then
|
|
996
|
+
fire(tree, entry.Key, "OnKeyAdded", k, v)
|
|
997
|
+
end
|
|
998
|
+
end
|
|
999
|
+
for k, v in old do
|
|
1000
|
+
if new[k] == nil and isDynamicKey(entry.Schema, k) then
|
|
1001
|
+
fire(tree, entry.Key, "OnKeyRemoved", k, v)
|
|
1002
|
+
end
|
|
1003
|
+
end
|
|
1004
|
+
end
|
|
1005
|
+
end
|
|
1006
|
+
|
|
1007
|
+
-- Tier-1 validation ----------------------------------------------------------
|
|
1008
|
+
|
|
1009
|
+
local function anomaly(tree: Tree, path: { string | number }, value: any, reason: string)
|
|
1010
|
+
if tree.Params.OnAnomaly then
|
|
1011
|
+
tree.Params.OnAnomaly(path, value, reason)
|
|
1012
|
+
end
|
|
1013
|
+
end
|
|
1014
|
+
|
|
1015
|
+
local function validationError(path: { string | number }, message: string): never
|
|
1016
|
+
error(`Scribe: invalid write to "{Util.pathString(path)}": {message}`, 0)
|
|
1017
|
+
end
|
|
1018
|
+
|
|
1019
|
+
-- Matches the wire codec's recursion cap (Wire.luau); a value that passes
|
|
1020
|
+
-- validation must always be encodable, so over-deep tables are rejected here.
|
|
1021
|
+
local MAX_VALUE_DEPTH = Util.MAX_VALUE_DEPTH
|
|
1022
|
+
|
|
1023
|
+
-- Truncate `s` to at most `maxBytes` without splitting a multi-byte UTF-8 character; a
|
|
1024
|
+
-- half-encoded trailing character fails the DataStore save. Callers pass an
|
|
1025
|
+
-- already-validated string, so the loop runs at most 3 times.
|
|
1026
|
+
local function truncateUtf8(s: string, maxBytes: number): string
|
|
1027
|
+
if #s <= maxBytes then
|
|
1028
|
+
return s
|
|
1029
|
+
end
|
|
1030
|
+
local cut = maxBytes
|
|
1031
|
+
while cut > 0 do
|
|
1032
|
+
local nextByte = string.byte(s, cut + 1)
|
|
1033
|
+
if nextByte == nil or nextByte < 0x80 or nextByte >= 0xC0 then
|
|
1034
|
+
break -- byte after the cut starts a fresh character (or end of string)
|
|
1035
|
+
end
|
|
1036
|
+
cut -= 1
|
|
1037
|
+
end
|
|
1038
|
+
return string.sub(s, 1, cut)
|
|
1039
|
+
end
|
|
1040
|
+
|
|
1041
|
+
-- Returns the (possibly clamped) value to write. Throws on type violations.
|
|
1042
|
+
local function validateWrite(
|
|
1043
|
+
tree: Tree,
|
|
1044
|
+
schema: SchemaNode?,
|
|
1045
|
+
path: { string | number },
|
|
1046
|
+
value: any,
|
|
1047
|
+
depth: number?
|
|
1048
|
+
): any
|
|
1049
|
+
if value == nil then
|
|
1050
|
+
return nil
|
|
1051
|
+
end
|
|
1052
|
+
-- Depth is budgeted from the ROOT, because Init snapshots re-encode the whole
|
|
1053
|
+
-- root from depth 0: a value that is not encodable from there silently drops
|
|
1054
|
+
-- the entire root from every snapshot.
|
|
1055
|
+
local d = depth or math.max(0, #path - 1)
|
|
1056
|
+
if d > MAX_VALUE_DEPTH then
|
|
1057
|
+
validationError(path, `nested deeper than {MAX_VALUE_DEPTH} levels from the root`)
|
|
1058
|
+
end
|
|
1059
|
+
|
|
1060
|
+
-- Declared datatype fields accept their Roblox datatype (packed here) or an
|
|
1061
|
+
-- already-packed buffer. Checked before the generic type gate, which would
|
|
1062
|
+
-- otherwise reject the userdata.
|
|
1063
|
+
if schema and schema.ValueType == "datatype" then
|
|
1064
|
+
local name = schema.Datatype :: string
|
|
1065
|
+
if typeof(value) == name then
|
|
1066
|
+
-- Precision is nil for a field that did not declare one. The template
|
|
1067
|
+
-- compiler has already refused any value a codec would reject, so this
|
|
1068
|
+
-- cannot fail on the Precision itself.
|
|
1069
|
+
local ok, packed = pcall(Datatypes.Pack, name, value, schema.Precision)
|
|
1070
|
+
if not ok then
|
|
1071
|
+
if type(packed) == "string" and string.find(packed, Datatypes.NONFINITE, 1, true) then
|
|
1072
|
+
anomaly(tree, path, value, "NonFiniteComponent")
|
|
1073
|
+
validationError(path, `{name} has a NaN/inf component`)
|
|
1074
|
+
end
|
|
1075
|
+
validationError(path, `could not pack {name}: {tostring(packed)}`)
|
|
1076
|
+
end
|
|
1077
|
+
return packed
|
|
1078
|
+
end
|
|
1079
|
+
if type(value) == "buffer" then
|
|
1080
|
+
return Util.cloneBuffer(value)
|
|
1081
|
+
end
|
|
1082
|
+
validationError(path, `expected {name}, got {typeof(value)}`)
|
|
1083
|
+
end
|
|
1084
|
+
|
|
1085
|
+
local t = type(value)
|
|
1086
|
+
if t == "function" or t == "thread" or t == "userdata" or typeof(value) ~= t then
|
|
1087
|
+
validationError(path, `unsupported type "{typeof(value)}"`)
|
|
1088
|
+
end
|
|
1089
|
+
if t == "number" and (value ~= value or value == math.huge or value == -math.huge) then
|
|
1090
|
+
validationError(path, "NaN/inf")
|
|
1091
|
+
end
|
|
1092
|
+
-- Invalid UTF-8 cannot be JSON-encoded, so the ENTIRE profile save fails (error
|
|
1093
|
+
-- 104) silently, long after this write. Rejecting every string leaf here names the
|
|
1094
|
+
-- offending path at the write site instead.
|
|
1095
|
+
if t == "string" and not Util.isUtf8(value :: string) then
|
|
1096
|
+
anomaly(tree, path, value, "InvalidUtf8")
|
|
1097
|
+
validationError(path, "string contains invalid UTF-8 bytes")
|
|
1098
|
+
end
|
|
1099
|
+
|
|
1100
|
+
local vt = if schema then schema.ValueType else "any"
|
|
1101
|
+
local policy = tree.Params.BoundsPolicy or "Clamp"
|
|
1102
|
+
|
|
1103
|
+
if vt == "boolean" then
|
|
1104
|
+
if t ~= "boolean" then
|
|
1105
|
+
validationError(path, `expected boolean, got {t}`)
|
|
1106
|
+
end
|
|
1107
|
+
elseif vt == "number" or vt == "int" then
|
|
1108
|
+
if t ~= "number" then
|
|
1109
|
+
validationError(path, `expected number, got {t}`)
|
|
1110
|
+
end
|
|
1111
|
+
local v = value :: number
|
|
1112
|
+
if vt == "int" and v % 1 ~= 0 then
|
|
1113
|
+
if policy == "Reject" then
|
|
1114
|
+
validationError(path, "expected integer")
|
|
1115
|
+
end
|
|
1116
|
+
v = math.floor(v + 0.5)
|
|
1117
|
+
end
|
|
1118
|
+
local min = schema and schema.Min
|
|
1119
|
+
local max = schema and schema.Max
|
|
1120
|
+
if (min and v < min) or (max and v > max) then
|
|
1121
|
+
anomaly(tree, path, value, "OutOfBounds")
|
|
1122
|
+
if policy == "Reject" then
|
|
1123
|
+
validationError(path, `out of bounds [{min or "-inf"}, {max or "inf"}]`)
|
|
1124
|
+
end
|
|
1125
|
+
v = math.clamp(v, min or -math.huge, max or math.huge)
|
|
1126
|
+
end
|
|
1127
|
+
return v
|
|
1128
|
+
elseif vt == "big" then
|
|
1129
|
+
local parsed = Big.from(value)
|
|
1130
|
+
if parsed == nil then
|
|
1131
|
+
validationError(path, `expected a number or a numeric string, got {t}`)
|
|
1132
|
+
end
|
|
1133
|
+
local big = parsed :: any
|
|
1134
|
+
local min = schema and schema.Min
|
|
1135
|
+
local max = schema and schema.Max
|
|
1136
|
+
if min ~= nil then
|
|
1137
|
+
local floor = Big.from(min) :: any
|
|
1138
|
+
if Big.compare(big, floor) < 0 then
|
|
1139
|
+
anomaly(tree, path, Big.toString(big), "OutOfBounds")
|
|
1140
|
+
if policy == "Reject" then
|
|
1141
|
+
validationError(path, `below Min {Big.toString(floor)}`)
|
|
1142
|
+
end
|
|
1143
|
+
big = floor
|
|
1144
|
+
end
|
|
1145
|
+
end
|
|
1146
|
+
if max ~= nil then
|
|
1147
|
+
local ceiling = Big.from(max) :: any
|
|
1148
|
+
if Big.compare(big, ceiling) > 0 then
|
|
1149
|
+
anomaly(tree, path, Big.toString(big), "OutOfBounds")
|
|
1150
|
+
if policy == "Reject" then
|
|
1151
|
+
validationError(path, `above Max {Big.toString(ceiling)}`)
|
|
1152
|
+
end
|
|
1153
|
+
big = ceiling
|
|
1154
|
+
end
|
|
1155
|
+
end
|
|
1156
|
+
return Big.toStored(big)
|
|
1157
|
+
elseif vt == "flags" then
|
|
1158
|
+
if t ~= "table" then
|
|
1159
|
+
validationError(path, `expected a table of member names, got {t}`)
|
|
1160
|
+
end
|
|
1161
|
+
-- Normalize to declaration order with duplicates dropped, so one set of flags
|
|
1162
|
+
-- has one stored form and no diff downstream has to care about write order.
|
|
1163
|
+
local index = (schema and schema.MemberIndex) :: { [string]: number }?
|
|
1164
|
+
local enabled: { [string]: boolean } = {}
|
|
1165
|
+
for _, name in value :: { any } do
|
|
1166
|
+
if type(name) ~= "string" then
|
|
1167
|
+
validationError(path, `flag names must be strings, got {type(name)}`)
|
|
1168
|
+
end
|
|
1169
|
+
if index == nil or index[name] == nil then
|
|
1170
|
+
anomaly(tree, path, name, "NotAMember")
|
|
1171
|
+
validationError(path, `"{tostring(name)}" is not a member of the flags`)
|
|
1172
|
+
end
|
|
1173
|
+
enabled[name] = true
|
|
1174
|
+
end
|
|
1175
|
+
local out = {}
|
|
1176
|
+
for _, name in (schema and schema.Members) :: { string } do
|
|
1177
|
+
if enabled[name] then
|
|
1178
|
+
table.insert(out, name)
|
|
1179
|
+
end
|
|
1180
|
+
end
|
|
1181
|
+
return out
|
|
1182
|
+
elseif vt == "string" or vt == "enum" then
|
|
1183
|
+
if t ~= "string" then
|
|
1184
|
+
validationError(path, `expected string, got {t}`)
|
|
1185
|
+
end
|
|
1186
|
+
if vt == "enum" then
|
|
1187
|
+
local index = schema and schema.MemberIndex
|
|
1188
|
+
if index and index[value] == nil then
|
|
1189
|
+
anomaly(tree, path, value, "NotAMember")
|
|
1190
|
+
validationError(path, `"{value}" is not a member of the enum`)
|
|
1191
|
+
end
|
|
1192
|
+
end
|
|
1193
|
+
local maxLength = schema and schema.MaxLength
|
|
1194
|
+
if maxLength and #(value :: string) > maxLength then
|
|
1195
|
+
anomaly(tree, path, value, "OverMaxLength")
|
|
1196
|
+
if policy == "Reject" then
|
|
1197
|
+
validationError(path, `exceeds MaxLength {maxLength}`)
|
|
1198
|
+
end
|
|
1199
|
+
-- Truncate on a character boundary: MaxLength is a byte budget, and a raw
|
|
1200
|
+
-- string.sub could split a multi-byte character and fail the save.
|
|
1201
|
+
return truncateUtf8(value :: string, maxLength)
|
|
1202
|
+
end
|
|
1203
|
+
elseif vt == "buffer" then
|
|
1204
|
+
if t ~= "buffer" then
|
|
1205
|
+
validationError(path, `expected buffer, got {t}`)
|
|
1206
|
+
end
|
|
1207
|
+
elseif vt == "table" then
|
|
1208
|
+
if t ~= "table" then
|
|
1209
|
+
validationError(path, `expected table, got {t}`)
|
|
1210
|
+
end
|
|
1211
|
+
end
|
|
1212
|
+
|
|
1213
|
+
if t == "buffer" then
|
|
1214
|
+
-- Buffers are mutable: store a private copy so a caller-held reference
|
|
1215
|
+
-- can't bypass replication later.
|
|
1216
|
+
return Util.cloneBuffer(value)
|
|
1217
|
+
end
|
|
1218
|
+
|
|
1219
|
+
if t == "table" then
|
|
1220
|
+
-- Recursive Tier-1 over the written table. A numeric key N and the string key
|
|
1221
|
+
-- tostring(N) produce the SAME pathKey, so they would alias distinct slots in
|
|
1222
|
+
-- listeners, coalescing and rollback. Only scanned when numeric keys exist.
|
|
1223
|
+
if Util.hasNumericKeys(value :: any) then
|
|
1224
|
+
for k in value :: any do
|
|
1225
|
+
-- A mixed table cannot be JSON-encoded, so the whole profile save fails
|
|
1226
|
+
-- later, far from this write. This also subsumes the alias pair above.
|
|
1227
|
+
if type(k) == "string" then
|
|
1228
|
+
validationError(
|
|
1229
|
+
path,
|
|
1230
|
+
"a table cannot mix array indices and string keys (it would fail the DataStore save)"
|
|
1231
|
+
)
|
|
1232
|
+
end
|
|
1233
|
+
end
|
|
1234
|
+
end
|
|
1235
|
+
-- A whole-container write must match the declared key shape, or a pure-dictionary
|
|
1236
|
+
-- payload passes the plain table gate above and lands under a `{ Record }` field.
|
|
1237
|
+
local container = if schema then schema.Container else nil
|
|
1238
|
+
if container ~= nil then
|
|
1239
|
+
local declared = schema :: SchemaNode
|
|
1240
|
+
local count = 0
|
|
1241
|
+
local maxIndex = 0
|
|
1242
|
+
for k in value do
|
|
1243
|
+
count += 1
|
|
1244
|
+
if container == "Array" then
|
|
1245
|
+
if type(k) ~= "number" then
|
|
1246
|
+
validationError(path, `Scribe.ArrayOf takes array entries, but "{tostring(k)}" is a string key`)
|
|
1247
|
+
end
|
|
1248
|
+
if (k :: number) > maxIndex then
|
|
1249
|
+
maxIndex = k :: number
|
|
1250
|
+
end
|
|
1251
|
+
elseif declared.KeyType == "integer" then
|
|
1252
|
+
-- A Scribe.MapOf("integer") declares its key type, so judge against that
|
|
1253
|
+
-- and not DictOf's string assumption, which would refuse the map's own
|
|
1254
|
+
-- keys and accept the ones it cannot store.
|
|
1255
|
+
if type(k) ~= "number" then
|
|
1256
|
+
validationError(
|
|
1257
|
+
path,
|
|
1258
|
+
`Scribe.MapOf("integer") takes integer keys, but "{tostring(k)}" is a string key`
|
|
1259
|
+
)
|
|
1260
|
+
end
|
|
1261
|
+
local n = k :: number
|
|
1262
|
+
if n ~= n or n == math.huge or n == -math.huge or n % 1 ~= 0 then
|
|
1263
|
+
validationError(path, `key {tostring(k)} is not a finite integer`)
|
|
1264
|
+
end
|
|
1265
|
+
else
|
|
1266
|
+
if type(k) ~= "string" then
|
|
1267
|
+
validationError(path, `Scribe.DictOf takes string keys, but {tostring(k)} is a number key`)
|
|
1268
|
+
end
|
|
1269
|
+
local maxKeyLength = declared.MaxKeyLength
|
|
1270
|
+
if maxKeyLength and #(k :: string) > maxKeyLength then
|
|
1271
|
+
validationError(path, `key "{k}" is {#(k :: string)} bytes, over MaxKeyLength {maxKeyLength}`)
|
|
1272
|
+
end
|
|
1273
|
+
end
|
|
1274
|
+
end
|
|
1275
|
+
-- A container already over cap in storage (a newer-template server wrote it
|
|
1276
|
+
-- before this server's lower cap deployed) stays writable; only growth is refused.
|
|
1277
|
+
local function storedCount(): number
|
|
1278
|
+
local stored = readValue(tree, path)
|
|
1279
|
+
return if type(stored) == "table" then Util.count(stored) else 0
|
|
1280
|
+
end
|
|
1281
|
+
if container == "Array" then
|
|
1282
|
+
-- `#value` stops at the first hole, so compare against the HIGHEST key
|
|
1283
|
+
-- instead: a ragged payload always has maxIndex > count.
|
|
1284
|
+
if count ~= maxIndex then
|
|
1285
|
+
validationError(path, "array entries must run contiguously from 1 (no holes)")
|
|
1286
|
+
end
|
|
1287
|
+
local maxItems = declared.MaxItems
|
|
1288
|
+
if maxItems then
|
|
1289
|
+
-- A set is stored deduplicated, so its cap is on MEMBERSHIP: counting the
|
|
1290
|
+
-- caller's raw array would refuse Set({1,1,1}) against MaxItems 2.
|
|
1291
|
+
local effective = count
|
|
1292
|
+
if declared.Unique then
|
|
1293
|
+
local seen: { [any]: boolean } = {}
|
|
1294
|
+
effective = 0
|
|
1295
|
+
for _, item in value do
|
|
1296
|
+
if not seen[item] then
|
|
1297
|
+
seen[item] = true
|
|
1298
|
+
effective += 1
|
|
1299
|
+
end
|
|
1300
|
+
end
|
|
1301
|
+
end
|
|
1302
|
+
if effective > maxItems and effective > storedCount() then
|
|
1303
|
+
validationError(path, `holds {effective} entries, over MaxItems {maxItems}`)
|
|
1304
|
+
end
|
|
1305
|
+
end
|
|
1306
|
+
else
|
|
1307
|
+
local maxKeys = declared.MaxKeys
|
|
1308
|
+
if maxKeys and count > maxKeys and count > storedCount() then
|
|
1309
|
+
validationError(path, `holds {count} keys, over MaxKeys {maxKeys}`)
|
|
1310
|
+
end
|
|
1311
|
+
end
|
|
1312
|
+
end
|
|
1313
|
+
|
|
1314
|
+
local out = {}
|
|
1315
|
+
for k, v in value do
|
|
1316
|
+
local kt = type(k)
|
|
1317
|
+
if kt ~= "string" and kt ~= "number" then
|
|
1318
|
+
validationError(path, `unsupported key type "{kt}"`)
|
|
1319
|
+
end
|
|
1320
|
+
if kt == "number" then
|
|
1321
|
+
-- Non-integer or non-finite numeric keys do not survive the DataStore
|
|
1322
|
+
-- JSON round trip.
|
|
1323
|
+
if k ~= k or k == math.huge or k == -math.huge or k % 1 ~= 0 then
|
|
1324
|
+
validationError(path, "invalid numeric key (must be a finite integer)")
|
|
1325
|
+
end
|
|
1326
|
+
else
|
|
1327
|
+
local ks = k :: string
|
|
1328
|
+
if string.find(ks, "\31", 1, true) then
|
|
1329
|
+
-- char 31 is the pathKey separator; a key containing it would
|
|
1330
|
+
-- alias a distinct path in coalescing/listeners/rollback.
|
|
1331
|
+
validationError(path, "string key may not contain control character \\31")
|
|
1332
|
+
end
|
|
1333
|
+
-- A JSON object key must be valid UTF-8 too; an invalid-byte key
|
|
1334
|
+
-- fails the whole profile save exactly like an invalid string value.
|
|
1335
|
+
if not Util.isUtf8(ks) then
|
|
1336
|
+
validationError(path, "string key contains invalid UTF-8 bytes")
|
|
1337
|
+
end
|
|
1338
|
+
end
|
|
1339
|
+
local childSchema = if schema then Template.ChildSchema(schema, k) else nil
|
|
1340
|
+
-- A declared element record has a fixed field set, so an undeclared key is a
|
|
1341
|
+
-- typo. The exception: a key this profile already stores was written by a newer
|
|
1342
|
+
-- template during a rolling deploy, and rejecting it would turn every
|
|
1343
|
+
-- read-modify-write on an old server into a lost write.
|
|
1344
|
+
if childSchema == nil and schema and schema.Closed then
|
|
1345
|
+
local stored = readValue(tree, path)
|
|
1346
|
+
if not (type(stored) == "table" and stored[k] ~= nil) then
|
|
1347
|
+
validationError(path, `"{tostring(k)}" is not a declared field of this element shape`)
|
|
1348
|
+
end
|
|
1349
|
+
end
|
|
1350
|
+
local childPath = table.clone(path)
|
|
1351
|
+
table.insert(childPath, k)
|
|
1352
|
+
out[k] = validateWrite(tree, childSchema, childPath, v, d + 1)
|
|
1353
|
+
end
|
|
1354
|
+
-- Fill declared element fields the caller omitted: the element type says they are
|
|
1355
|
+
-- always present, so a partial element nil-crashes every consumer typed against
|
|
1356
|
+
-- it. Scribe.Optional fields have no default and stay absent.
|
|
1357
|
+
if schema and schema.Closed and schema.Children then
|
|
1358
|
+
for name, child in schema.Children do
|
|
1359
|
+
if out[name] == nil and child.Default ~= nil then
|
|
1360
|
+
-- A mirror never fills a ServerOnly field: no replicated op would have
|
|
1361
|
+
-- sent it, so an optimistic local write would visibly diverge.
|
|
1362
|
+
if tree.Params.IsServer or child.Visibility ~= "ServerOnly" then
|
|
1363
|
+
out[name] = Util.deepClone(child.Default)
|
|
1364
|
+
end
|
|
1365
|
+
end
|
|
1366
|
+
end
|
|
1367
|
+
end
|
|
1368
|
+
if schema and schema.Unique then
|
|
1369
|
+
-- Deduplicate and sort so a set has one stored form whatever the write
|
|
1370
|
+
-- order. Safe because Template refuses any set element that is not an
|
|
1371
|
+
-- orderable scalar.
|
|
1372
|
+
local seen: { [any]: boolean } = {}
|
|
1373
|
+
local unique = {}
|
|
1374
|
+
for _, item in out do
|
|
1375
|
+
if not seen[item] then
|
|
1376
|
+
seen[item] = true
|
|
1377
|
+
table.insert(unique, item)
|
|
1378
|
+
end
|
|
1379
|
+
end
|
|
1380
|
+
table.sort(unique)
|
|
1381
|
+
return unique
|
|
1382
|
+
end
|
|
1383
|
+
return out
|
|
1384
|
+
end
|
|
1385
|
+
|
|
1386
|
+
return value
|
|
1387
|
+
end
|
|
1388
|
+
|
|
1389
|
+
-- Mutation core ----------------------------------------------------------------
|
|
1390
|
+
|
|
1391
|
+
type WriteOpts = {
|
|
1392
|
+
Replicate: boolean?,
|
|
1393
|
+
FromRemote: boolean?,
|
|
1394
|
+
NoOp: boolean?, -- rollback writes: fire listeners but never emit ops
|
|
1395
|
+
NoValidate: boolean?,
|
|
1396
|
+
}
|
|
1397
|
+
|
|
1398
|
+
local function emitOp(tree: Tree, op: Op, schema: SchemaNode?, opts: WriteOpts)
|
|
1399
|
+
if opts.NoOp or opts.FromRemote or opts.Replicate == false then
|
|
1400
|
+
return
|
|
1401
|
+
end
|
|
1402
|
+
local onOp = tree.Params.OnOp
|
|
1403
|
+
if onOp == nil then
|
|
1404
|
+
return
|
|
1405
|
+
end
|
|
1406
|
+
if tree._txn then
|
|
1407
|
+
table.insert(tree._txn.Ops, { Op = op, Schema = schema })
|
|
1408
|
+
else
|
|
1409
|
+
onOp(op, schema)
|
|
1410
|
+
end
|
|
1411
|
+
end
|
|
1412
|
+
|
|
1413
|
+
-- Derived fields ---------------------------------------------------------------
|
|
1414
|
+
-- A recompute is an ordinary write through applySet, so bounds, coalescing,
|
|
1415
|
+
-- listeners, transactions and replication all keep working. This layer only decides
|
|
1416
|
+
-- WHEN to recompute.
|
|
1417
|
+
|
|
1418
|
+
-- A listener fired by a recompute may write an input, re-dirtying the field that
|
|
1419
|
+
-- fired it. Bounded so a feedback loop is reported rather than hanging the writer.
|
|
1420
|
+
local MAX_SETTLE_PASSES = 4
|
|
1421
|
+
|
|
1422
|
+
-- Assigned below applyClear: settling writes through applySet.
|
|
1423
|
+
local settleDerived: (tree: Tree) -> ()
|
|
1424
|
+
|
|
1425
|
+
local function markDerivedDirty(tree: Tree, pathKey: string)
|
|
1426
|
+
local dependents = tree.Compiled.DerivedByWrite[pathKey]
|
|
1427
|
+
if dependents == nil then
|
|
1428
|
+
return
|
|
1429
|
+
end
|
|
1430
|
+
local dirty = tree._derivedDirty
|
|
1431
|
+
if dirty == nil then
|
|
1432
|
+
dirty = {}
|
|
1433
|
+
tree._derivedDirty = dirty
|
|
1434
|
+
end
|
|
1435
|
+
for _, node in dependents do
|
|
1436
|
+
(dirty :: any)[node] = true
|
|
1437
|
+
end
|
|
1438
|
+
end
|
|
1439
|
+
|
|
1440
|
+
-- A write settles immediately unless something else is already going to settle for
|
|
1441
|
+
-- it: inside a batch the flush does, inside a transaction the commit does, during a
|
|
1442
|
+
-- replay ReplayFire does (once, after the whole snapshot has landed), and inside a
|
|
1443
|
+
-- settle pass the pass itself does.
|
|
1444
|
+
local function settleAfterWrite(tree: Tree)
|
|
1445
|
+
if
|
|
1446
|
+
tree._derivedDirty == nil
|
|
1447
|
+
or tree._derivedSettling
|
|
1448
|
+
or tree._batchDepth > 0
|
|
1449
|
+
or tree._txn ~= nil
|
|
1450
|
+
or tree._replaying
|
|
1451
|
+
then
|
|
1452
|
+
return
|
|
1453
|
+
end
|
|
1454
|
+
settleDerived(tree)
|
|
1455
|
+
end
|
|
1456
|
+
|
|
1457
|
+
-- Per-transaction mirror of the tree's _descendants index: ancestor pathKey -> the
|
|
1458
|
+
-- snapshot keys strictly below it, so a snapshot can absorb the ones underneath it
|
|
1459
|
+
-- without scanning every snapshot in the transaction.
|
|
1460
|
+
local function indexSnapshot(txn: any, pathKey: string)
|
|
1461
|
+
forEachAncestorKey(pathKey, function(ancestor)
|
|
1462
|
+
local set = txn.Below[ancestor]
|
|
1463
|
+
if set == nil then
|
|
1464
|
+
set = {}
|
|
1465
|
+
txn.Below[ancestor] = set
|
|
1466
|
+
end
|
|
1467
|
+
set[pathKey] = true
|
|
1468
|
+
end)
|
|
1469
|
+
end
|
|
1470
|
+
|
|
1471
|
+
local function unindexSnapshot(txn: any, pathKey: string)
|
|
1472
|
+
forEachAncestorKey(pathKey, function(ancestor)
|
|
1473
|
+
local set = txn.Below[ancestor]
|
|
1474
|
+
if set ~= nil then
|
|
1475
|
+
set[pathKey] = nil
|
|
1476
|
+
if next(set) == nil then
|
|
1477
|
+
txn.Below[ancestor] = nil
|
|
1478
|
+
end
|
|
1479
|
+
end
|
|
1480
|
+
end)
|
|
1481
|
+
end
|
|
1482
|
+
|
|
1483
|
+
-- Whether `a` is a strict ancestor path of `b` (a shorter, matching prefix).
|
|
1484
|
+
local function pathIsStrictAncestor(a: { string | number }, b: { string | number }): boolean
|
|
1485
|
+
if #a >= #b then
|
|
1486
|
+
return false
|
|
1487
|
+
end
|
|
1488
|
+
for i = 1, #a do
|
|
1489
|
+
if a[i] ~= b[i] then
|
|
1490
|
+
return false
|
|
1491
|
+
end
|
|
1492
|
+
end
|
|
1493
|
+
return true
|
|
1494
|
+
end
|
|
1495
|
+
|
|
1496
|
+
-- Restore `value` at a relative path inside `root`, creating tables as needed.
|
|
1497
|
+
local function setNested(root: { [any]: any }, relPath: { string | number }, value: any)
|
|
1498
|
+
local container = root
|
|
1499
|
+
for i = 1, #relPath - 1 do
|
|
1500
|
+
local seg = relPath[i]
|
|
1501
|
+
local nextContainer = container[seg]
|
|
1502
|
+
if type(nextContainer) ~= "table" then
|
|
1503
|
+
nextContainer = {}
|
|
1504
|
+
forgetContainer(container)
|
|
1505
|
+
container[seg] = nextContainer
|
|
1506
|
+
end
|
|
1507
|
+
container = nextContainer
|
|
1508
|
+
end
|
|
1509
|
+
forgetContainer(container)
|
|
1510
|
+
container[relPath[#relPath]] = value
|
|
1511
|
+
end
|
|
1512
|
+
|
|
1513
|
+
-- Remove `relPath` from `root` WITHOUT creating any intermediate tables (unlike
|
|
1514
|
+
-- setNested). Used to strip txn-materialized descendant containers out of a rollback
|
|
1515
|
+
-- reconstruction so no phantom empty sub-table survives.
|
|
1516
|
+
local function removeNested(root: { [any]: any }, relPath: { string | number })
|
|
1517
|
+
local container = root
|
|
1518
|
+
for i = 1, #relPath - 1 do
|
|
1519
|
+
local nextContainer = container[relPath[i]]
|
|
1520
|
+
if type(nextContainer) ~= "table" then
|
|
1521
|
+
return
|
|
1522
|
+
end
|
|
1523
|
+
container = nextContainer
|
|
1524
|
+
end
|
|
1525
|
+
container[relPath[#relPath]] = nil
|
|
1526
|
+
end
|
|
1527
|
+
|
|
1528
|
+
-- Records the pre-transaction value of `path`, keeping snapshots DISJOINT so rollback
|
|
1529
|
+
-- order is irrelevant. An ancestor snapshot already covers this subtree; earlier
|
|
1530
|
+
-- descendant snapshots are overlaid onto the current value and then dropped.
|
|
1531
|
+
local function snapshotForTxn(tree: Tree, path: { string | number }, pathKey: string, oldValue: any)
|
|
1532
|
+
local txn = tree._txn
|
|
1533
|
+
if not txn or txn.Snapshots[pathKey] ~= nil then
|
|
1534
|
+
return
|
|
1535
|
+
end
|
|
1536
|
+
-- Already covered by an ancestor snapshot? Walk THIS path's ancestor keys rather than
|
|
1537
|
+
-- every snapshot taken so far, which made a transaction quadratic in the number of
|
|
1538
|
+
-- distinct paths it touched. The real path comparison still runs on a hit: it is
|
|
1539
|
+
-- O(depth) and it decides whether a rollback restores the correct subtree.
|
|
1540
|
+
local at = string.find(pathKey, "\31", 1, true)
|
|
1541
|
+
while at do
|
|
1542
|
+
local ancestorSnap = txn.Snapshots[string.sub(pathKey, 1, at - 1)]
|
|
1543
|
+
if ancestorSnap ~= nil and pathIsStrictAncestor(ancestorSnap.Path, path) then
|
|
1544
|
+
return
|
|
1545
|
+
end
|
|
1546
|
+
at = string.find(pathKey, "\31", at + 1, true)
|
|
1547
|
+
end
|
|
1548
|
+
local value = Util.deepClone(oldValue)
|
|
1549
|
+
-- Track which descendant snapshots get overlaid: each is the authoritative
|
|
1550
|
+
-- pre-txn state at its path, which the Created-strip below must not undo.
|
|
1551
|
+
local overlaid: { { string | number } }? = nil
|
|
1552
|
+
-- Snapshots strictly BELOW this path, by lookup. Collected first because
|
|
1553
|
+
-- absorbing one removes it from the same index being iterated.
|
|
1554
|
+
local belowSet = txn.Below[pathKey]
|
|
1555
|
+
if belowSet ~= nil then
|
|
1556
|
+
local descKeys: { string } = {}
|
|
1557
|
+
for descKey in belowSet do
|
|
1558
|
+
descKeys[#descKeys + 1] = descKey
|
|
1559
|
+
end
|
|
1560
|
+
for _, descKey in descKeys do
|
|
1561
|
+
local snap = txn.Snapshots[descKey]
|
|
1562
|
+
if snap ~= nil and pathIsStrictAncestor(path, snap.Path) then
|
|
1563
|
+
if type(value) ~= "table" then
|
|
1564
|
+
value = {}
|
|
1565
|
+
end
|
|
1566
|
+
local relPath = table.move(
|
|
1567
|
+
snap.Path,
|
|
1568
|
+
#path + 1,
|
|
1569
|
+
#snap.Path,
|
|
1570
|
+
1,
|
|
1571
|
+
table.create(#snap.Path - #path) :: { string | number }
|
|
1572
|
+
)
|
|
1573
|
+
setNested(value, relPath, snap.Value)
|
|
1574
|
+
overlaid = overlaid or {}
|
|
1575
|
+
table.insert(overlaid :: { { string | number } }, snap.Path)
|
|
1576
|
+
txn.Snapshots[descKey] = nil
|
|
1577
|
+
unindexSnapshot(txn, descKey)
|
|
1578
|
+
end
|
|
1579
|
+
end
|
|
1580
|
+
end
|
|
1581
|
+
-- Reconcile against containers materialized during this txn, so a rollback cannot
|
|
1582
|
+
-- resurrect them as phantom empty tables: either the snapshotted container itself was
|
|
1583
|
+
-- created (pre-txn value is nil), or a strict descendant was (strip it out). Only
|
|
1584
|
+
-- strip a created path when NO overlaid snapshot sits at or above it: Created also
|
|
1585
|
+
-- records a pre-existing container deleted and recreated inside this txn, whose
|
|
1586
|
+
-- overlay re-established genuine pre-txn state that stripping would destroy.
|
|
1587
|
+
local function establishedByOverlay(createdPath: { string | number }): boolean
|
|
1588
|
+
if not overlaid then
|
|
1589
|
+
return false
|
|
1590
|
+
end
|
|
1591
|
+
for _, snapPath in overlaid :: { { string | number } } do
|
|
1592
|
+
if #snapPath <= #createdPath then
|
|
1593
|
+
local isPrefix = true
|
|
1594
|
+
for i = 1, #snapPath do
|
|
1595
|
+
if snapPath[i] ~= createdPath[i] then
|
|
1596
|
+
isPrefix = false
|
|
1597
|
+
break
|
|
1598
|
+
end
|
|
1599
|
+
end
|
|
1600
|
+
if isPrefix then
|
|
1601
|
+
return true
|
|
1602
|
+
end
|
|
1603
|
+
end
|
|
1604
|
+
end
|
|
1605
|
+
return false
|
|
1606
|
+
end
|
|
1607
|
+
if value ~= nil then
|
|
1608
|
+
local pathCreated = false
|
|
1609
|
+
for _, createdPath in txn.Created do
|
|
1610
|
+
if #createdPath == #path then
|
|
1611
|
+
local same = true
|
|
1612
|
+
for i = 1, #path do
|
|
1613
|
+
if createdPath[i] ~= path[i] then
|
|
1614
|
+
same = false
|
|
1615
|
+
break
|
|
1616
|
+
end
|
|
1617
|
+
end
|
|
1618
|
+
if same then
|
|
1619
|
+
pathCreated = true
|
|
1620
|
+
break
|
|
1621
|
+
end
|
|
1622
|
+
end
|
|
1623
|
+
end
|
|
1624
|
+
if pathCreated then
|
|
1625
|
+
value = nil
|
|
1626
|
+
elseif type(value) == "table" then
|
|
1627
|
+
for _, createdPath in txn.Created do
|
|
1628
|
+
if pathIsStrictAncestor(path, createdPath) and not establishedByOverlay(createdPath) then
|
|
1629
|
+
local relPath: { string | number } = {}
|
|
1630
|
+
for i = #path + 1, #createdPath do
|
|
1631
|
+
relPath[#relPath + 1] = createdPath[i]
|
|
1632
|
+
end
|
|
1633
|
+
removeNested(value, relPath)
|
|
1634
|
+
end
|
|
1635
|
+
end
|
|
1636
|
+
end
|
|
1637
|
+
end
|
|
1638
|
+
txn.Snapshots[pathKey] = { Path = table.clone(path), Value = value }
|
|
1639
|
+
indexSnapshot(txn, pathKey)
|
|
1640
|
+
end
|
|
1641
|
+
|
|
1642
|
+
local applySet: (Tree, { string | number }, SchemaNode?, any, WriteOpts) -> any
|
|
1643
|
+
|
|
1644
|
+
-- Materializes every missing DECLARED-ELEMENT intermediate along `path` as a real
|
|
1645
|
+
-- applySet write of the element's defaults, before the caller's own write resolves the
|
|
1646
|
+
-- chain. That makes materialization visible everywhere a write is: the element Set
|
|
1647
|
+
-- replicates (so a schema-less Shared mirror rebuilds the full element, not a bare {}),
|
|
1648
|
+
-- OnKeyAdded fires, a transaction can roll the creation back, and a later leaf write
|
|
1649
|
+
-- equal to the default no-ops safely. Untyped intermediates keep their silent plain-{}
|
|
1650
|
+
-- materialization in resolveContainer.
|
|
1651
|
+
local function seedMissingElements(tree: Tree, path: { string | number }, schema: SchemaNode?, opts: WriteOpts)
|
|
1652
|
+
local n = #path
|
|
1653
|
+
if n < 2 or schema == nil then
|
|
1654
|
+
return
|
|
1655
|
+
end
|
|
1656
|
+
local chain = table.create(n) :: { SchemaNode }
|
|
1657
|
+
local cursor: SchemaNode? = schema
|
|
1658
|
+
for i = n, 1, -1 do
|
|
1659
|
+
if cursor == nil then
|
|
1660
|
+
break
|
|
1661
|
+
end
|
|
1662
|
+
chain[i] = cursor
|
|
1663
|
+
cursor = cursor.Parent
|
|
1664
|
+
end
|
|
1665
|
+
local validating = not opts.NoValidate and not opts.FromRemote
|
|
1666
|
+
local container: any = storeFor(tree, path[1])
|
|
1667
|
+
for i = 1, n - 1 do
|
|
1668
|
+
if type(container) ~= "table" then
|
|
1669
|
+
return -- the caller's own resolve reports the real error
|
|
1670
|
+
end
|
|
1671
|
+
local seg = path[i]
|
|
1672
|
+
local nextContainer = container[seg]
|
|
1673
|
+
if nextContainer == nil then
|
|
1674
|
+
local createdSchema = chain[i]
|
|
1675
|
+
if createdSchema and createdSchema.IsElement then
|
|
1676
|
+
local seed = if tree.Params.IsServer then createdSchema.Default else createdSchema.ClientDefault
|
|
1677
|
+
if type(seed) == "table" then
|
|
1678
|
+
-- The element's own key must satisfy its container's rules before the
|
|
1679
|
+
-- seed write lands, which runs NoValidate on an already-stored form.
|
|
1680
|
+
if validating and i > 1 then
|
|
1681
|
+
checkContainerKey(chain[i - 1], container, seg, path, i - 1)
|
|
1682
|
+
-- The same alias guard resolveContainer applies. Seeding reaches the
|
|
1683
|
+
-- container first, so resolveContainer's own check would see a key
|
|
1684
|
+
-- that already exists and never run. Unreachable today only because
|
|
1685
|
+
-- checkContainerKey above rejects the mismatched form, which is a
|
|
1686
|
+
-- guard in another function, so this stays.
|
|
1687
|
+
local alias = aliasForm(seg)
|
|
1688
|
+
if alias ~= nil and container[alias] ~= nil then
|
|
1689
|
+
error(
|
|
1690
|
+
`Scribe: key "{tostring(seg)}" at "{Util.pathString(path)}" collides with the `
|
|
1691
|
+
.. `existing "{tostring(alias)}" key form (a numeric key and its string form `
|
|
1692
|
+
.. "cannot coexist)",
|
|
1693
|
+
0
|
|
1694
|
+
)
|
|
1695
|
+
end
|
|
1696
|
+
end
|
|
1697
|
+
local prefix = table.move(path, 1, i, 1, table.create(i) :: { string | number })
|
|
1698
|
+
-- This element exists because a write descended THROUGH its key, not
|
|
1699
|
+
-- because anything asked for it. Recorded inside transactions only, for
|
|
1700
|
+
-- the receipt path. Deliberately NOT txn.Created, which rollback
|
|
1701
|
+
-- consumes: this list is observational.
|
|
1702
|
+
local seedTxn = tree._txn
|
|
1703
|
+
if seedTxn then
|
|
1704
|
+
seedTxn.Seeded[#seedTxn.Seeded + 1] = prefix
|
|
1705
|
+
end
|
|
1706
|
+
applySet(tree, prefix, createdSchema, Util.deepClone(seed), {
|
|
1707
|
+
NoValidate = true,
|
|
1708
|
+
FromRemote = opts.FromRemote,
|
|
1709
|
+
Replicate = opts.Replicate,
|
|
1710
|
+
})
|
|
1711
|
+
nextContainer = container[seg]
|
|
1712
|
+
end
|
|
1713
|
+
end
|
|
1714
|
+
if nextContainer == nil then
|
|
1715
|
+
return -- untyped intermediate: created silently by resolveContainer
|
|
1716
|
+
end
|
|
1717
|
+
end
|
|
1718
|
+
container = nextContainer
|
|
1719
|
+
end
|
|
1720
|
+
end
|
|
1721
|
+
|
|
1722
|
+
-- Value equality for the three leaves whose canonical stored form is a table or a
|
|
1723
|
+
-- buffer, which `Util.leafEquals` always reports as changed; without it a no-op Set on
|
|
1724
|
+
-- one fires Changed and replicates. Safe because validateWrite has just rebuilt the
|
|
1725
|
+
-- value into Scribe's own normal form, of bounded size and never handed out by
|
|
1726
|
+
-- reference. Deliberately NOT extended to user tables, Scribe.SetOf or containers: a
|
|
1727
|
+
-- deep compare there is unbounded, and a whole-table Set is how a caller replaces a
|
|
1728
|
+
-- table.
|
|
1729
|
+
local function canonicalStoredEquals(schema: SchemaNode?, old: any, new: any): boolean
|
|
1730
|
+
if schema == nil then
|
|
1731
|
+
return false
|
|
1732
|
+
end
|
|
1733
|
+
local vt = schema.ValueType
|
|
1734
|
+
if vt == "big" then
|
|
1735
|
+
-- Big.toStored is exactly two numbers, and normalize() snaps the mantissa
|
|
1736
|
+
-- through "%.15g" precisely so that one value has ONE stored pair.
|
|
1737
|
+
return type(old) == "table"
|
|
1738
|
+
and type(new) == "table"
|
|
1739
|
+
and #(old :: { any }) == 2
|
|
1740
|
+
and #(new :: { any }) == 2
|
|
1741
|
+
and (old :: { any })[1] == (new :: { any })[1]
|
|
1742
|
+
and (old :: { any })[2] == (new :: { any })[2]
|
|
1743
|
+
elseif vt == "datatype" then
|
|
1744
|
+
-- Byte-for-byte on the PACKED form. Packing is deterministic, so an equal
|
|
1745
|
+
-- value re-packs to equal bytes; a lossy round trip just fails this test and
|
|
1746
|
+
-- writes, which is the safe direction to be wrong in.
|
|
1747
|
+
return type(old) == "buffer" and type(new) == "buffer" and Util.bufferEquals(old :: buffer, new :: buffer)
|
|
1748
|
+
elseif vt == "flags" then
|
|
1749
|
+
if type(old) ~= "table" or type(new) ~= "table" then
|
|
1750
|
+
return false
|
|
1751
|
+
end
|
|
1752
|
+
local a, b = old :: { any }, new :: { any }
|
|
1753
|
+
if #a ~= #b then
|
|
1754
|
+
return false
|
|
1755
|
+
end
|
|
1756
|
+
for i = 1, #a do
|
|
1757
|
+
if a[i] ~= b[i] then
|
|
1758
|
+
return false
|
|
1759
|
+
end
|
|
1760
|
+
end
|
|
1761
|
+
-- Both sides are member names in declaration order, so element-by-element
|
|
1762
|
+
-- equality IS set equality. An out-of-order stored value fails and writes,
|
|
1763
|
+
-- which canonicalizes it.
|
|
1764
|
+
return true
|
|
1765
|
+
end
|
|
1766
|
+
return false
|
|
1767
|
+
end
|
|
1768
|
+
|
|
1769
|
+
function applySet(tree: Tree, path: { string | number }, schema: SchemaNode?, value: any, opts: WriteOpts): any
|
|
1770
|
+
-- validateWrite rebuilds tables entry-by-entry (no aliasing); unvalidated
|
|
1771
|
+
-- table writes are cloned explicitly instead.
|
|
1772
|
+
local newValue = if opts.NoValidate then value else validateWrite(tree, schema, path, value)
|
|
1773
|
+
if type(newValue) == "table" and opts.NoValidate then
|
|
1774
|
+
newValue = Util.deepClone(newValue)
|
|
1775
|
+
end
|
|
1776
|
+
|
|
1777
|
+
-- A REMOTE nil-Set materializes missing parents: the server only emits a removal
|
|
1778
|
+
-- when the parent chain existed, so a mirror missing them lost the creating op to
|
|
1779
|
+
-- coalescing and the server still holds them. Creating them here keeps existence
|
|
1780
|
+
-- and Count() parity; local writes keep the no-op semantics. Seeding runs AFTER
|
|
1781
|
+
-- validateWrite so a rejected value leaves no phantom element behind.
|
|
1782
|
+
if newValue ~= nil or opts.FromRemote == true then
|
|
1783
|
+
seedMissingElements(tree, path, schema, opts)
|
|
1784
|
+
end
|
|
1785
|
+
local container, key = resolveContainer(
|
|
1786
|
+
tree,
|
|
1787
|
+
path,
|
|
1788
|
+
newValue ~= nil or opts.FromRemote == true,
|
|
1789
|
+
schema,
|
|
1790
|
+
not opts.NoValidate and not opts.FromRemote
|
|
1791
|
+
)
|
|
1792
|
+
if container == nil then
|
|
1793
|
+
if newValue == nil then
|
|
1794
|
+
return nil -- removing under a missing parent is a no-op
|
|
1795
|
+
end
|
|
1796
|
+
error(`Scribe: cannot write to "{Util.pathString(path)}"`, 0)
|
|
1797
|
+
end
|
|
1798
|
+
|
|
1799
|
+
-- Reject a keyed write whose other-typed form already occupies the container
|
|
1800
|
+
-- (number 7 vs string "7"), because their pathKeys alias. Local validated writes
|
|
1801
|
+
-- only; remote and restore writes are trusted.
|
|
1802
|
+
if not opts.NoValidate and not opts.FromRemote then
|
|
1803
|
+
-- The last segment is a key of its parent, so the container's key rules apply
|
|
1804
|
+
-- to it too; resolveContainer only saw the intermediate ones. Removals are
|
|
1805
|
+
-- checked because a nil write to a middle array index punches a hole.
|
|
1806
|
+
if schema and schema.Parent then
|
|
1807
|
+
checkContainerKey(schema.Parent, container, key, path, #path - 1, newValue == nil)
|
|
1808
|
+
end
|
|
1809
|
+
-- Deleting a declared, non-Optional field of a closed element record stores the
|
|
1810
|
+
-- partial element that shape exists to prevent. Removing the WHOLE element stays
|
|
1811
|
+
-- legal: its parent is the container, not a record.
|
|
1812
|
+
if
|
|
1813
|
+
newValue == nil
|
|
1814
|
+
and schema
|
|
1815
|
+
and schema.Nullable ~= true
|
|
1816
|
+
and schema.Default ~= nil
|
|
1817
|
+
and schema.Parent
|
|
1818
|
+
and schema.Parent.Closed
|
|
1819
|
+
and container[key] ~= nil
|
|
1820
|
+
then
|
|
1821
|
+
error(
|
|
1822
|
+
`Scribe: "{Util.pathString(path)}" is a declared element field; Set a value instead of removing it `
|
|
1823
|
+
.. "(wrap the field in Scribe.Optional if absence is legitimate)",
|
|
1824
|
+
0
|
|
1825
|
+
)
|
|
1826
|
+
end
|
|
1827
|
+
if newValue ~= nil then
|
|
1828
|
+
local aliasKey = aliasForm(key)
|
|
1829
|
+
if aliasKey ~= nil and container[aliasKey] ~= nil then
|
|
1830
|
+
error(
|
|
1831
|
+
`Scribe: key at "{Util.pathString(path)}" collides with the existing "{tostring(aliasKey)}" key `
|
|
1832
|
+
.. "form (a numeric key and its string form cannot coexist)",
|
|
1833
|
+
0
|
|
1834
|
+
)
|
|
1835
|
+
end
|
|
1836
|
+
end
|
|
1837
|
+
end
|
|
1838
|
+
|
|
1839
|
+
local old = container[key]
|
|
1840
|
+
-- `not opts.NoValidate` is what makes the second test sound: only then did
|
|
1841
|
+
-- validateWrite build `newValue`, and only then is it in canonical stored form.
|
|
1842
|
+
if Util.leafEquals(old, newValue) or (not opts.NoValidate and canonicalStoredEquals(schema, old, newValue)) then
|
|
1843
|
+
return old
|
|
1844
|
+
end
|
|
1845
|
+
|
|
1846
|
+
local pathKey = Util.pathKey(path)
|
|
1847
|
+
-- After the no-op early-out, so an unchanged write never triggers a recompute,
|
|
1848
|
+
-- and before the fires, so a listener reading a derived field sees it settled.
|
|
1849
|
+
markDerivedDirty(tree, pathKey)
|
|
1850
|
+
snapshotForTxn(tree, path, pathKey, old)
|
|
1851
|
+
-- Snapshot observed descendants BEFORE the write; a whole-table Set changes
|
|
1852
|
+
-- every leaf beneath this path and only this pass can report it.
|
|
1853
|
+
local descendantOlds = if type(newValue) == "table" or type(old) == "table"
|
|
1854
|
+
then snapshotDescendants(tree, pathKey)
|
|
1855
|
+
else nil
|
|
1856
|
+
-- Only a table on one side or the other can add or drop keys BELOW this path.
|
|
1857
|
+
local keyedOlds = if type(newValue) == "table" or type(old) == "table"
|
|
1858
|
+
then snapshotKeyed(tree, pathKey, #path, schema)
|
|
1859
|
+
else nil
|
|
1860
|
+
local keyHad = old ~= nil
|
|
1861
|
+
container[key] = newValue
|
|
1862
|
+
noteKeyDelta(container, key, keyHad, newValue ~= nil)
|
|
1863
|
+
|
|
1864
|
+
emitOp(tree, { Kind = "Set", Path = table.clone(path), Value = newValue }, schema, opts)
|
|
1865
|
+
|
|
1866
|
+
fire(tree, pathKey, "Changed", newValue, old)
|
|
1867
|
+
-- Key transitions on a descendant container come BEFORE that container's own
|
|
1868
|
+
-- Changed, matching a single-key write and keeping the guarantee that a
|
|
1869
|
+
-- container's transitions arrive before the state fire summarizing them.
|
|
1870
|
+
fireKeyDeltas(tree, keyedOlds)
|
|
1871
|
+
fireDescendants(tree, descendantOlds)
|
|
1872
|
+
-- Dictionary key events on the parent (dynamic keys only).
|
|
1873
|
+
if #path >= 1 then
|
|
1874
|
+
local parentPath = table.move(path, 1, #path - 1, 1, table.create(#path - 1) :: { string | number })
|
|
1875
|
+
local parentSchema = if schema then schema.Parent else nil
|
|
1876
|
+
local isDynamic = parentSchema == nil
|
|
1877
|
+
or parentSchema.Children == nil
|
|
1878
|
+
or type(key) ~= "string"
|
|
1879
|
+
or parentSchema.Children[key :: string] == nil
|
|
1880
|
+
if isDynamic then
|
|
1881
|
+
local parentKey = Util.pathKey(parentPath)
|
|
1882
|
+
if old == nil and newValue ~= nil then
|
|
1883
|
+
fire(tree, parentKey, "OnKeyAdded", key, newValue)
|
|
1884
|
+
elseif old ~= nil and newValue == nil then
|
|
1885
|
+
fire(tree, parentKey, "OnKeyRemoved", key, old)
|
|
1886
|
+
end
|
|
1887
|
+
end
|
|
1888
|
+
end
|
|
1889
|
+
fireAncestors(tree, path, old, true)
|
|
1890
|
+
settleAfterWrite(tree)
|
|
1891
|
+
return newValue
|
|
1892
|
+
end
|
|
1893
|
+
|
|
1894
|
+
local function ensureContainerValue(tree: Tree, path: { string | number }, schema: SchemaNode?): { [any]: any }
|
|
1895
|
+
local container, key = resolveContainer(tree, path, true, schema)
|
|
1896
|
+
if container == nil then
|
|
1897
|
+
error(`Scribe: cannot access "{Util.pathString(path)}"`, 0)
|
|
1898
|
+
end
|
|
1899
|
+
local value = container[key]
|
|
1900
|
+
if value == nil then
|
|
1901
|
+
value = {}
|
|
1902
|
+
container[key] = value
|
|
1903
|
+
noteKeyDelta(container, key, false, true)
|
|
1904
|
+
elseif type(value) ~= "table" then
|
|
1905
|
+
error(`Scribe: "{Util.pathString(path)}" is not a container`, 0)
|
|
1906
|
+
end
|
|
1907
|
+
return value
|
|
1908
|
+
end
|
|
1909
|
+
|
|
1910
|
+
-- Forward declaration: applyInsert evicts through the real remove path so the client
|
|
1911
|
+
-- mirror receives a Remove op rather than the table quietly shrinking.
|
|
1912
|
+
local applyArrayRemove: (Tree, { string | number }, SchemaNode?, number?, WriteOpts) -> any
|
|
1913
|
+
|
|
1914
|
+
-- Scribe.Big and Scribe.Flags are leaves whose stored form happens to be a table, and
|
|
1915
|
+
-- every container mutation gates on the stored value being one: without this, Insert on
|
|
1916
|
+
-- a big rewrites its mantissa pair and Clear leaves a non-Optional field nil. A
|
|
1917
|
+
-- Scribe.SetOf is a real container, but Insert and positional writes bypass the dedupe
|
|
1918
|
+
-- and ordering its stored form depends on, so it is refused too.
|
|
1919
|
+
local function refuseStructuralWrite(schema: SchemaNode?, path: { string | number }, method: string)
|
|
1920
|
+
if schema == nil then
|
|
1921
|
+
return
|
|
1922
|
+
end
|
|
1923
|
+
local vt = schema.ValueType
|
|
1924
|
+
if vt == "big" then
|
|
1925
|
+
error(
|
|
1926
|
+
`Scribe: "{Util.pathString(path)}" is a Scribe.Big, not a container; {method} would rewrite its `
|
|
1927
|
+
.. "stored mantissa/exponent pair. Use Set, Increment, Decrement, Multiply or Divide",
|
|
1928
|
+
0
|
|
1929
|
+
)
|
|
1930
|
+
elseif vt == "flags" then
|
|
1931
|
+
error(
|
|
1932
|
+
`Scribe: "{Util.pathString(path)}" is a Scribe.Flags, not a container; {method} would corrupt its `
|
|
1933
|
+
.. "member list. Use Enable, Disable, Toggle or Clear",
|
|
1934
|
+
0
|
|
1935
|
+
)
|
|
1936
|
+
elseif schema.Unique then
|
|
1937
|
+
error(
|
|
1938
|
+
`Scribe: "{Util.pathString(path)}" is a Scribe.SetOf; {method} bypasses the dedupe and ordering `
|
|
1939
|
+
.. "its stored form depends on. Use Add or Remove",
|
|
1940
|
+
0
|
|
1941
|
+
)
|
|
1942
|
+
end
|
|
1943
|
+
end
|
|
1944
|
+
|
|
1945
|
+
local function applyInsert(
|
|
1946
|
+
tree: Tree,
|
|
1947
|
+
path: { string | number },
|
|
1948
|
+
schema: SchemaNode?,
|
|
1949
|
+
item: any,
|
|
1950
|
+
pos: number?,
|
|
1951
|
+
opts: WriteOpts
|
|
1952
|
+
)
|
|
1953
|
+
-- Validation only: Tree.ApplyOp replays replicated Inserts with FromRemote and
|
|
1954
|
+
-- NoValidate, and a mirror momentarily ahead of the server must not throw
|
|
1955
|
+
-- mid-frame, which drops the frame and desyncs permanently.
|
|
1956
|
+
local validating = not opts.NoValidate and not opts.FromRemote
|
|
1957
|
+
if validating then
|
|
1958
|
+
refuseStructuralWrite(schema, path, "Insert")
|
|
1959
|
+
if schema and schema.Container == "Dict" then
|
|
1960
|
+
error(`Scribe: "{Util.pathString(path)}" is a Scribe.DictOf; write a key instead of calling Insert`, 0)
|
|
1961
|
+
end
|
|
1962
|
+
-- Ahead of the other refusals because the `math.clamp` below raises its own error
|
|
1963
|
+
-- on a non-number position, and a NaN or fractional position would silently write
|
|
1964
|
+
-- a hash-part index. The cost: `Insert(nil, "x")` names the position, not the nil.
|
|
1965
|
+
if pos ~= nil and (type(pos) ~= "number" or pos ~= pos or pos % 1 ~= 0) then
|
|
1966
|
+
error(`Scribe: Insert position must be an integer, got {tostring(pos)}`, 0)
|
|
1967
|
+
end
|
|
1968
|
+
end
|
|
1969
|
+
|
|
1970
|
+
local pathKey = Util.pathKey(path)
|
|
1971
|
+
-- Read the existing array first (create = false, so nothing is materialized). The
|
|
1972
|
+
-- prospective index is needed up front so validation errors name the real element
|
|
1973
|
+
-- path, and the pre-creation value is what a rollback must restore, rather than an
|
|
1974
|
+
-- empty table. The MaxItems cap is applied further down, because with Evict it writes.
|
|
1975
|
+
local existingContainer, existingKey = resolveContainer(tree, path, false)
|
|
1976
|
+
local preValue = if existingContainer then existingContainer[existingKey] else nil
|
|
1977
|
+
local existingLength = if type(preValue) == "table" then #(preValue :: any) else 0
|
|
1978
|
+
local index = math.clamp(pos or existingLength + 1, 1, existingLength + 1)
|
|
1979
|
+
|
|
1980
|
+
-- One decision read in two places, computed once so the two cannot drift. They sit
|
|
1981
|
+
-- on opposite sides of the other checks: the refusal (no Evict declared) belongs
|
|
1982
|
+
-- with the other refusals, the eviction belongs past all of them because it WRITES.
|
|
1983
|
+
local capped: SchemaNode? = if validating
|
|
1984
|
+
and schema ~= nil
|
|
1985
|
+
and schema.MaxItems ~= nil
|
|
1986
|
+
and existingLength >= schema.MaxItems
|
|
1987
|
+
then schema
|
|
1988
|
+
else nil
|
|
1989
|
+
|
|
1990
|
+
if validating then
|
|
1991
|
+
if capped ~= nil and capped.Evict ~= "Front" and capped.Evict ~= "Back" then
|
|
1992
|
+
error(
|
|
1993
|
+
`Scribe: "{Util.pathString(path)}" already holds {existingLength} entries, `
|
|
1994
|
+
.. `at its MaxItems {capped.MaxItems}`,
|
|
1995
|
+
0
|
|
1996
|
+
)
|
|
1997
|
+
end
|
|
1998
|
+
if item == nil then
|
|
1999
|
+
error(`Scribe: cannot Insert nil into "{Util.pathString(path)}"`, 0)
|
|
2000
|
+
end
|
|
2001
|
+
-- Insert creates an array index, so it can mix an undeclared container just as a
|
|
2002
|
+
-- keyed write can, and it is the one path checkContainerKey never sees. Checked
|
|
2003
|
+
-- before validateWrite, seedMissingElements and ensureContainerValue, so a refusal
|
|
2004
|
+
-- leaves nothing materialized.
|
|
2005
|
+
if (schema == nil or schema.Container == nil) and type(preValue) == "table" then
|
|
2006
|
+
local blocker = mixedKeyBlocker(preValue, index)
|
|
2007
|
+
if blocker ~= nil then
|
|
2008
|
+
error(
|
|
2009
|
+
`Scribe: "{Util.pathString(path)}" already holds {blocker}, so Insert would make it a mixed `
|
|
2010
|
+
.. "array/hash table -- the DataStore drops half of one on save, and Set on the parent "
|
|
2011
|
+
.. "refuses the same shape. Use one key type for this container",
|
|
2012
|
+
0
|
|
2013
|
+
)
|
|
2014
|
+
end
|
|
2015
|
+
end
|
|
2016
|
+
end
|
|
2017
|
+
|
|
2018
|
+
-- Validate the item BEFORE creating any container, so a rejected item can
|
|
2019
|
+
-- never leave a phantom container behind.
|
|
2020
|
+
local elementSchema = if schema then Template.ChildSchema(schema, index) else nil
|
|
2021
|
+
local elementPath = table.clone(path)
|
|
2022
|
+
table.insert(elementPath, index)
|
|
2023
|
+
-- Pass depth = #path: an inserted element sits one level below the array's own
|
|
2024
|
+
-- path, and the default under-budgets it by one, admitting an element the Init
|
|
2025
|
+
-- snapshot cannot re-encode and so dropping that client's whole root.
|
|
2026
|
+
local value = if opts.NoValidate
|
|
2027
|
+
then Util.deepClone(item)
|
|
2028
|
+
else validateWrite(tree, elementSchema, elementPath, item, #path)
|
|
2029
|
+
|
|
2030
|
+
-- Only now, with the insert guaranteed to land, make room at the named end. Run any
|
|
2031
|
+
-- earlier and a REFUSED Insert on a full array would still drop the oldest entry,
|
|
2032
|
+
-- fire OnRemove and replicate a Remove, with no rollback outside a transaction.
|
|
2033
|
+
-- Nothing above here has written, so a refusal still materializes nothing.
|
|
2034
|
+
if capped ~= nil then
|
|
2035
|
+
-- Through the real remove path on purpose: a bare table.remove would shrink
|
|
2036
|
+
-- the server's array without emitting a Remove op, leaving every mirror one
|
|
2037
|
+
-- entry longer forever. The loop handles an array already over cap (a lowered
|
|
2038
|
+
-- MaxItems, or data predating it) rather than trimming one entry per Insert.
|
|
2039
|
+
local dropFront = capped.Evict == "Front"
|
|
2040
|
+
for _ = 1, existingLength - (capped.MaxItems :: number) + 1 do
|
|
2041
|
+
-- Recompute the tail index each pass: the array shrinks under us.
|
|
2042
|
+
local current = if type(preValue) == "table" then #(preValue :: any) else 0
|
|
2043
|
+
applyArrayRemove(tree, path, schema, if dropFront then 1 else current, opts)
|
|
2044
|
+
end
|
|
2045
|
+
-- Everything shifted down, so re-read rather than trusting the stale index.
|
|
2046
|
+
-- Rollback stays correct: applyArrayRemove snapshotted the pre-eviction array
|
|
2047
|
+
-- and snapshotForTxn keeps the first value per pathKey.
|
|
2048
|
+
existingContainer, existingKey = resolveContainer(tree, path, false)
|
|
2049
|
+
preValue = if existingContainer then existingContainer[existingKey] else nil
|
|
2050
|
+
existingLength = if type(preValue) == "table" then #(preValue :: any) else 0
|
|
2051
|
+
index = math.clamp(pos or existingLength + 1, 1, existingLength + 1)
|
|
2052
|
+
end
|
|
2053
|
+
|
|
2054
|
+
-- Seed AFTER validation (a rejected item must not leave a phantom element),
|
|
2055
|
+
-- BEFORE the snapshot so intermediate declared elements replicate as real ops.
|
|
2056
|
+
seedMissingElements(tree, path, schema, opts)
|
|
2057
|
+
markDerivedDirty(tree, pathKey)
|
|
2058
|
+
snapshotForTxn(tree, path, pathKey, preValue)
|
|
2059
|
+
|
|
2060
|
+
local arr = ensureContainerValue(tree, path, schema)
|
|
2061
|
+
-- Every element from `index` up shifts, so a listener bound to an element path is
|
|
2062
|
+
-- now looking at a different element. Snapshot before the shift and diff after.
|
|
2063
|
+
local descendantOlds = snapshotDescendants(tree, pathKey)
|
|
2064
|
+
table.insert(arr, index, value)
|
|
2065
|
+
|
|
2066
|
+
emitOp(tree, { Kind = "Insert", Path = table.clone(path), Value = value, Index = index }, schema, opts)
|
|
2067
|
+
fire(tree, pathKey, "OnInsert", value, index)
|
|
2068
|
+
fireDescendants(tree, descendantOlds)
|
|
2069
|
+
if not deferSelfState(tree, pathKey, path) then
|
|
2070
|
+
fire(tree, pathKey, "Changed", arr, arr)
|
|
2071
|
+
end
|
|
2072
|
+
fireAncestors(tree, path)
|
|
2073
|
+
settleAfterWrite(tree)
|
|
2074
|
+
end
|
|
2075
|
+
|
|
2076
|
+
function applyArrayRemove(
|
|
2077
|
+
tree: Tree,
|
|
2078
|
+
path: { string | number },
|
|
2079
|
+
schema: SchemaNode?,
|
|
2080
|
+
pos: number?,
|
|
2081
|
+
opts: WriteOpts
|
|
2082
|
+
): any
|
|
2083
|
+
if not opts.NoValidate and not opts.FromRemote then
|
|
2084
|
+
refuseStructuralWrite(schema, path, "Remove by index")
|
|
2085
|
+
end
|
|
2086
|
+
local container, key = resolveContainer(tree, path, false)
|
|
2087
|
+
local arr = if container then container[key] else nil
|
|
2088
|
+
if type(arr) ~= "table" or #arr == 0 then
|
|
2089
|
+
return nil
|
|
2090
|
+
end
|
|
2091
|
+
-- No argument means "the last element". An explicit index outside the array is a
|
|
2092
|
+
-- no-op, not a clamp: clamping turns an off-by-one or a stale index into a silent
|
|
2093
|
+
-- deletion of the wrong element.
|
|
2094
|
+
local index: number
|
|
2095
|
+
if pos == nil then
|
|
2096
|
+
index = #arr
|
|
2097
|
+
else
|
|
2098
|
+
if pos ~= math.floor(pos) or pos < 1 or pos > #arr then
|
|
2099
|
+
return nil
|
|
2100
|
+
end
|
|
2101
|
+
index = pos
|
|
2102
|
+
end
|
|
2103
|
+
|
|
2104
|
+
local pathKey = Util.pathKey(path)
|
|
2105
|
+
markDerivedDirty(tree, pathKey)
|
|
2106
|
+
snapshotForTxn(tree, path, pathKey, arr)
|
|
2107
|
+
-- The same shift as Insert, in the other direction.
|
|
2108
|
+
local descendantOlds = snapshotDescendants(tree, pathKey)
|
|
2109
|
+
local item = table.remove(arr, index)
|
|
2110
|
+
|
|
2111
|
+
emitOp(tree, { Kind = "Remove", Path = table.clone(path), Index = index }, schema, opts)
|
|
2112
|
+
fire(tree, pathKey, "OnRemove", item, index)
|
|
2113
|
+
fireDescendants(tree, descendantOlds)
|
|
2114
|
+
if not deferSelfState(tree, pathKey, path) then
|
|
2115
|
+
fire(tree, pathKey, "Changed", arr, arr)
|
|
2116
|
+
end
|
|
2117
|
+
fireAncestors(tree, path)
|
|
2118
|
+
settleAfterWrite(tree)
|
|
2119
|
+
return item
|
|
2120
|
+
end
|
|
2121
|
+
|
|
2122
|
+
local function applyClear(tree: Tree, path: { string | number }, schema: SchemaNode?, opts: WriteOpts)
|
|
2123
|
+
-- A Scribe.Flags and a Scribe.SetOf both clear legitimately to {}, so only the
|
|
2124
|
+
-- big is refused here.
|
|
2125
|
+
if not opts.NoValidate and not opts.FromRemote and schema and schema.ValueType == "big" then
|
|
2126
|
+
refuseStructuralWrite(schema, path, "Clear")
|
|
2127
|
+
end
|
|
2128
|
+
local container, key = resolveContainer(tree, path, opts.FromRemote == true, schema)
|
|
2129
|
+
local value = if container then container[key] else nil
|
|
2130
|
+
if type(value) ~= "table" then
|
|
2131
|
+
if not (opts.FromRemote and container) then
|
|
2132
|
+
return
|
|
2133
|
+
end
|
|
2134
|
+
-- A remote Clear implies the container existed server-side at emission, so if
|
|
2135
|
+
-- the op that created it was coalesced away, materialize it as {} to keep
|
|
2136
|
+
-- existence and Count() parity.
|
|
2137
|
+
value = {}
|
|
2138
|
+
container[key] = value
|
|
2139
|
+
noteKeyDelta(container, key, false, true)
|
|
2140
|
+
end
|
|
2141
|
+
local pathKey = Util.pathKey(path)
|
|
2142
|
+
-- Clear accepts any table node, a static record included, so this is the one
|
|
2143
|
+
-- non-Set path that can blank a derived input.
|
|
2144
|
+
markDerivedDirty(tree, pathKey)
|
|
2145
|
+
snapshotForTxn(tree, path, pathKey, value)
|
|
2146
|
+
local descendantOlds = snapshotDescendants(tree, pathKey)
|
|
2147
|
+
table.clear(value)
|
|
2148
|
+
noteContainerCleared(value)
|
|
2149
|
+
|
|
2150
|
+
emitOp(tree, { Kind = "Clear", Path = table.clone(path) }, schema, opts)
|
|
2151
|
+
-- Bulk semantics: the parent Changed fires once and per-entry key events do not. A
|
|
2152
|
+
-- descendant leaf listener is not a per-entry event: its value really did change.
|
|
2153
|
+
-- Descendants come BEFORE the container's own state, the only order both paths can
|
|
2154
|
+
-- share: inside a batch the self fire is deferred to the flush and lands last anyway,
|
|
2155
|
+
-- so firing it first when unbatched gave one Clear two orders.
|
|
2156
|
+
fireDescendants(tree, descendantOlds)
|
|
2157
|
+
if not deferSelfState(tree, pathKey, path) then
|
|
2158
|
+
fire(tree, pathKey, "Changed", value, value)
|
|
2159
|
+
end
|
|
2160
|
+
fireAncestors(tree, path)
|
|
2161
|
+
settleAfterWrite(tree)
|
|
2162
|
+
end
|
|
2163
|
+
|
|
2164
|
+
-- Recomputes every dirty derived field in the compiler's topological order, so a
|
|
2165
|
+
-- field reading another derived field sees the settled value in the same sweep. Each
|
|
2166
|
+
-- recompute writes through applySet, so an unchanged result costs nothing.
|
|
2167
|
+
local function runSettle(tree: Tree)
|
|
2168
|
+
local ordered = tree.Compiled.DerivedNodes
|
|
2169
|
+
local devMode = tree.Params.DevMode == true
|
|
2170
|
+
local onIssue = tree.Params.OnDerivedIssue
|
|
2171
|
+
|
|
2172
|
+
for _ = 1, MAX_SETTLE_PASSES do
|
|
2173
|
+
local dirty = tree._derivedDirty
|
|
2174
|
+
if dirty == nil then
|
|
2175
|
+
break
|
|
2176
|
+
end
|
|
2177
|
+
-- Sweeping `ordered` rather than the dirty set is what settles chains of any
|
|
2178
|
+
-- depth in ONE pass: a dependent sits after its inputs, so a mark laid down
|
|
2179
|
+
-- by the recompute above is still ahead of the cursor.
|
|
2180
|
+
for _, node in ordered do
|
|
2181
|
+
if dirty[node] then
|
|
2182
|
+
dirty[node] = nil
|
|
2183
|
+
local spec = node.Derived :: any
|
|
2184
|
+
local inputs = spec.Inputs
|
|
2185
|
+
local count = #inputs
|
|
2186
|
+
local values = table.create(count)
|
|
2187
|
+
for i, input in inputs do
|
|
2188
|
+
values[i] = DerivedModule.ReadForm(input, readValue(tree, input.Path :: any))
|
|
2189
|
+
end
|
|
2190
|
+
local ok, value = DerivedModule.Compute(node, values, count)
|
|
2191
|
+
Metrics.Add("DerivedRecomputes")
|
|
2192
|
+
if ok then
|
|
2193
|
+
if not spec.Transmit then
|
|
2194
|
+
-- The transmit rule, counted: a recompute that cost no bytes.
|
|
2195
|
+
Metrics.Add("DerivedOpsSuppressed")
|
|
2196
|
+
end
|
|
2197
|
+
applySet(tree, node.Path :: any, node, value, {
|
|
2198
|
+
-- Dev mode sends locally computed values too, so the client can
|
|
2199
|
+
-- compare and report an impure function. Production sends nothing.
|
|
2200
|
+
Replicate = spec.Transmit or devMode,
|
|
2201
|
+
})
|
|
2202
|
+
else
|
|
2203
|
+
Metrics.Add("DerivedErrors")
|
|
2204
|
+
-- Never rethrow: a Set on an input must not fail because a compute
|
|
2205
|
+
-- function has a typo. Logged once per field per tree, or the throw
|
|
2206
|
+
-- on every write evicts the ring holding the evidence.
|
|
2207
|
+
local logged = tree._derivedLogged
|
|
2208
|
+
if logged == nil then
|
|
2209
|
+
logged = {}
|
|
2210
|
+
tree._derivedLogged = logged
|
|
2211
|
+
end
|
|
2212
|
+
if onIssue and not (logged :: any)[node] then
|
|
2213
|
+
(logged :: any)[node] = true
|
|
2214
|
+
onIssue("DERIVED_ERROR", spec.Label, tostring(value))
|
|
2215
|
+
end
|
|
2216
|
+
end
|
|
2217
|
+
end
|
|
2218
|
+
end
|
|
2219
|
+
if next(dirty) == nil then
|
|
2220
|
+
tree._derivedDirty = nil
|
|
2221
|
+
break
|
|
2222
|
+
end
|
|
2223
|
+
end
|
|
2224
|
+
|
|
2225
|
+
local leftover = tree._derivedDirty
|
|
2226
|
+
if leftover ~= nil then
|
|
2227
|
+
if onIssue then
|
|
2228
|
+
local names = {}
|
|
2229
|
+
for node in leftover do
|
|
2230
|
+
table.insert(names, (node.Derived :: any).Label)
|
|
2231
|
+
end
|
|
2232
|
+
table.sort(names)
|
|
2233
|
+
onIssue(
|
|
2234
|
+
"DERIVED_FEEDBACK",
|
|
2235
|
+
table.concat(names, ", "),
|
|
2236
|
+
`still dirty after {MAX_SETTLE_PASSES} passes: a listener keeps writing an input from inside the `
|
|
2237
|
+
.. "recompute it triggered"
|
|
2238
|
+
)
|
|
2239
|
+
end
|
|
2240
|
+
tree._derivedDirty = nil
|
|
2241
|
+
end
|
|
2242
|
+
end
|
|
2243
|
+
|
|
2244
|
+
settleDerived = function(tree: Tree)
|
|
2245
|
+
if tree._derivedDirty == nil or tree._derivedSettling then
|
|
2246
|
+
return
|
|
2247
|
+
end
|
|
2248
|
+
-- The guard is cleared even when a recompute's write throws. Leaving it set would
|
|
2249
|
+
-- silently retire every derived field on this tree for the rest of the session.
|
|
2250
|
+
tree._derivedSettling = true
|
|
2251
|
+
local ok, err = pcall(runSettle, tree)
|
|
2252
|
+
tree._derivedSettling = false
|
|
2253
|
+
if not ok then
|
|
2254
|
+
error(err, 0)
|
|
2255
|
+
end
|
|
2256
|
+
end
|
|
2257
|
+
|
|
2258
|
+
--- Compares each derived value the server sent this frame against the one this realm
|
|
2259
|
+
--- computed, once the local recompute has run. A disagreement is an impure compute
|
|
2260
|
+
--- function, which nothing else can detect.
|
|
2261
|
+
local function runDerivedAudit(tree: Tree)
|
|
2262
|
+
local audit = tree._derivedAudit
|
|
2263
|
+
if audit == nil then
|
|
2264
|
+
return
|
|
2265
|
+
end
|
|
2266
|
+
tree._derivedAudit = nil
|
|
2267
|
+
local onIssue = tree.Params.OnDerivedIssue
|
|
2268
|
+
if onIssue == nil then
|
|
2269
|
+
return
|
|
2270
|
+
end
|
|
2271
|
+
for _, pending in audit do
|
|
2272
|
+
local mine = readValue(tree, pending.Path)
|
|
2273
|
+
if not Util.leafEquals(mine, pending.Server) then
|
|
2274
|
+
onIssue(
|
|
2275
|
+
"DERIVED_MISMATCH",
|
|
2276
|
+
pending.Label,
|
|
2277
|
+
`server computed {tostring(pending.Server)}, this realm computed {tostring(mine)}: the `
|
|
2278
|
+
.. "compute function is not pure (os.time / math.random / a realm-specific upvalue?)"
|
|
2279
|
+
)
|
|
2280
|
+
end
|
|
2281
|
+
end
|
|
2282
|
+
end
|
|
2283
|
+
|
|
2284
|
+
-- Applies a whole frame's ops as ONE batch, so N ops under the same container give one
|
|
2285
|
+
-- container Changed. The receiving half of Server.Batch: the server already coalesced
|
|
2286
|
+
-- the batch into one frame. Leaf fires are untouched.
|
|
2287
|
+
function Tree.ApplyOps(self: Tree, ops: { Op })
|
|
2288
|
+
if self.Dead then
|
|
2289
|
+
return
|
|
2290
|
+
end
|
|
2291
|
+
self._batchDepth += 1
|
|
2292
|
+
local ok, err = pcall(function()
|
|
2293
|
+
for _, op in ops do
|
|
2294
|
+
self:ApplyOp(op)
|
|
2295
|
+
end
|
|
2296
|
+
end)
|
|
2297
|
+
self._batchDepth -= 1
|
|
2298
|
+
if self._batchDepth == 0 then
|
|
2299
|
+
-- One recompute per FRAME, not per op: the server already coalesced these
|
|
2300
|
+
-- ops into a single flush.
|
|
2301
|
+
settleDerived(self)
|
|
2302
|
+
runDerivedAudit(self)
|
|
2303
|
+
-- Flush even when an op threw: the ops before it landed, and a listener
|
|
2304
|
+
-- that never hears about them is worse than one that hears late.
|
|
2305
|
+
flushPendingAncestors(self)
|
|
2306
|
+
end
|
|
2307
|
+
if not ok then
|
|
2308
|
+
error(err, 0)
|
|
2309
|
+
end
|
|
2310
|
+
end
|
|
2311
|
+
|
|
2312
|
+
--[=[
|
|
2313
|
+
Recomputes every derived field from current state, whatever the dirty set says.
|
|
2314
|
+
|
|
2315
|
+
Used once per profile load, where the tree has just been pointed at real data
|
|
2316
|
+
that no write ever passed through: the session store still holds the compile-time
|
|
2317
|
+
defaults, which were computed from the template's defaults rather than from this
|
|
2318
|
+
player's values.
|
|
2319
|
+
]=]
|
|
2320
|
+
function Tree.SeedDerived(self: Tree)
|
|
2321
|
+
local ordered = self.Compiled.DerivedNodes
|
|
2322
|
+
if #ordered == 0 then
|
|
2323
|
+
return
|
|
2324
|
+
end
|
|
2325
|
+
local dirty = self._derivedDirty
|
|
2326
|
+
if dirty == nil then
|
|
2327
|
+
dirty = {}
|
|
2328
|
+
self._derivedDirty = dirty
|
|
2329
|
+
end
|
|
2330
|
+
for _, node in ordered do
|
|
2331
|
+
(dirty :: any)[node] = true
|
|
2332
|
+
end
|
|
2333
|
+
settleDerived(self)
|
|
2334
|
+
end
|
|
2335
|
+
|
|
2336
|
+
-- Applies an op received over the wire (client mirror / gift delivery replays).
|
|
2337
|
+
function Tree.ApplyOp(self: Tree, op: Op)
|
|
2338
|
+
if self.Dead then
|
|
2339
|
+
return
|
|
2340
|
+
end
|
|
2341
|
+
-- Resolve the exact schema node (dynamic tail resolves to any-nodes).
|
|
2342
|
+
local baseSchema, dynStart = Template.Resolve(self.Compiled, op.Path)
|
|
2343
|
+
local exactSchema: SchemaNode? = baseSchema
|
|
2344
|
+
for i = dynStart, #op.Path do
|
|
2345
|
+
exactSchema = if exactSchema then Template.ChildSchema(exactSchema, op.Path[i]) else nil
|
|
2346
|
+
end
|
|
2347
|
+
|
|
2348
|
+
-- Purity audit. A locally computed derived field is not sent in production, so
|
|
2349
|
+
-- receiving one means the server is in dev mode and wants the two compared.
|
|
2350
|
+
--
|
|
2351
|
+
-- The comparison cannot happen HERE: this realm recomputes at the end of the frame,
|
|
2352
|
+
-- not per op, so reading the path now returns the pre-frame value, which differs on
|
|
2353
|
+
-- every derived op (one is emitted only when the value changed). Record the server's
|
|
2354
|
+
-- value and let runDerivedAudit compare once both realms have seen the same inputs.
|
|
2355
|
+
if exactSchema ~= nil and exactSchema.Derived ~= nil and not exactSchema.Derived.Transmit then
|
|
2356
|
+
if self.Params.OnDerivedIssue then
|
|
2357
|
+
local audit = self._derivedAudit
|
|
2358
|
+
if audit == nil then
|
|
2359
|
+
audit = {}
|
|
2360
|
+
self._derivedAudit = audit
|
|
2361
|
+
end
|
|
2362
|
+
(audit :: any)[#audit + 1] = {
|
|
2363
|
+
Path = table.clone(op.Path),
|
|
2364
|
+
Label = exactSchema.Derived.Label,
|
|
2365
|
+
Server = op.Value,
|
|
2366
|
+
}
|
|
2367
|
+
end
|
|
2368
|
+
end
|
|
2369
|
+
local opts: WriteOpts = { FromRemote = true, NoValidate = true }
|
|
2370
|
+
if op.Kind == "Set" or op.Kind == "Init" then
|
|
2371
|
+
applySet(self, op.Path, exactSchema, op.Value, opts)
|
|
2372
|
+
elseif op.Kind == "Insert" then
|
|
2373
|
+
applyInsert(self, op.Path, exactSchema, op.Value, op.Index, opts)
|
|
2374
|
+
elseif op.Kind == "Remove" then
|
|
2375
|
+
applyArrayRemove(self, op.Path, exactSchema, op.Index, opts)
|
|
2376
|
+
elseif op.Kind == "Clear" then
|
|
2377
|
+
applyClear(self, op.Path, exactSchema, opts)
|
|
2378
|
+
end
|
|
2379
|
+
-- Outside a frame the apply above settled derived itself, so the audit can run
|
|
2380
|
+
-- now. Inside one, ApplyOps runs it after the frame's single recompute.
|
|
2381
|
+
if self._batchDepth == 0 then
|
|
2382
|
+
runDerivedAudit(self)
|
|
2383
|
+
end
|
|
2384
|
+
end
|
|
2385
|
+
|
|
2386
|
+
-- Runs `apply` with per-op fires suppressed, then fires Changed once per observed
|
|
2387
|
+
-- path the mutation actually changed. A whole-container Set never fires descendants,
|
|
2388
|
+
-- so a nested Observe registered before the mutation would miss its value. Used by
|
|
2389
|
+
-- ReplayInit and edit-mode Mock. Cost is O(listeners), not O(data).
|
|
2390
|
+
function Tree.ReplayFire(self: Tree, apply: () -> ())
|
|
2391
|
+
if self.Dead then
|
|
2392
|
+
apply()
|
|
2393
|
+
return
|
|
2394
|
+
end
|
|
2395
|
+
-- Snapshot the pre-apply value of every observed path.
|
|
2396
|
+
local olds: { [string]: any } = {}
|
|
2397
|
+
for pathKey, path in self._paths do
|
|
2398
|
+
local byEvent = self._listeners[pathKey]
|
|
2399
|
+
if byEvent and byEvent.Changed then
|
|
2400
|
+
olds[pathKey] = readValue(self, path)
|
|
2401
|
+
end
|
|
2402
|
+
end
|
|
2403
|
+
self._replaying = true
|
|
2404
|
+
local ok, err = pcall(apply)
|
|
2405
|
+
-- Derived fields settle INSIDE the replay, with fires still suppressed, so their
|
|
2406
|
+
-- new values reach the single diff pass below instead of arriving as a second
|
|
2407
|
+
-- round of events. Only on success: a half-applied snapshot is not worth deriving.
|
|
2408
|
+
if ok then
|
|
2409
|
+
pcall(settleDerived, self)
|
|
2410
|
+
pcall(runDerivedAudit, self)
|
|
2411
|
+
end
|
|
2412
|
+
self._replaying = false -- always cleared, even if `apply` threw
|
|
2413
|
+
if not ok then
|
|
2414
|
+
error(err, 0)
|
|
2415
|
+
end
|
|
2416
|
+
-- Collect first (a fired listener may add or remove listeners), then fire.
|
|
2417
|
+
-- leafEquals is false for tables and buffers, so container observers always fire,
|
|
2418
|
+
-- matching a live whole-container Set; scalar leaves fire only on a real change.
|
|
2419
|
+
local pending: { { Key: string, New: any, Old: any } } = {}
|
|
2420
|
+
for pathKey, path in self._paths do
|
|
2421
|
+
local byEvent = self._listeners[pathKey]
|
|
2422
|
+
if byEvent and byEvent.Changed then
|
|
2423
|
+
local current = readValue(self, path)
|
|
2424
|
+
if not Util.leafEquals(current, olds[pathKey]) then
|
|
2425
|
+
table.insert(pending, { Key = pathKey, New = current, Old = olds[pathKey] })
|
|
2426
|
+
end
|
|
2427
|
+
end
|
|
2428
|
+
end
|
|
2429
|
+
for _, entry in pending do
|
|
2430
|
+
fire(self, entry.Key, "Changed", entry.New, entry.Old)
|
|
2431
|
+
end
|
|
2432
|
+
end
|
|
2433
|
+
|
|
2434
|
+
-- Applies the initial snapshot, firing nested observers registered before Init. The
|
|
2435
|
+
-- caller has already reset the mirror to defaults.
|
|
2436
|
+
function Tree.ReplayInit(self: Tree, ops: { Op })
|
|
2437
|
+
self:ReplayFire(function()
|
|
2438
|
+
for _, op in ops do
|
|
2439
|
+
self:ApplyOp(op)
|
|
2440
|
+
end
|
|
2441
|
+
end)
|
|
2442
|
+
end
|
|
2443
|
+
|
|
2444
|
+
-- Batch / Transaction ------------------------------------------------
|
|
2445
|
+
|
|
2446
|
+
function Tree.RunBatch(self: Tree, fn: () -> ())
|
|
2447
|
+
assertAlive(self)
|
|
2448
|
+
self._batchDepth += 1
|
|
2449
|
+
local ok, err = pcall(fn :: any)
|
|
2450
|
+
self._batchDepth -= 1
|
|
2451
|
+
if self._batchDepth == 0 then
|
|
2452
|
+
-- Before the flush and before OnBatchEnd: one recompute for the whole batch,
|
|
2453
|
+
-- whose ops join the same replication frame as the writes that caused it.
|
|
2454
|
+
settleDerived(self)
|
|
2455
|
+
-- Listeners before replication, matching the unbatched ordering.
|
|
2456
|
+
flushPendingAncestors(self)
|
|
2457
|
+
local onBatchEnd: (() -> ())? = self.Params.OnBatchEnd
|
|
2458
|
+
if onBatchEnd then
|
|
2459
|
+
onBatchEnd()
|
|
2460
|
+
end
|
|
2461
|
+
end
|
|
2462
|
+
if not ok then
|
|
2463
|
+
error(err, 0)
|
|
2464
|
+
end
|
|
2465
|
+
end
|
|
2466
|
+
|
|
2467
|
+
-- Register a pre-transaction value for a RAW store mutation, i.e. a write that does
|
|
2468
|
+
-- not go through applySet (the _Scribe.Timed store, whose keys are full pathKeys
|
|
2469
|
+
-- containing \31 that the accessor tree rejects). The first write to a key records
|
|
2470
|
+
-- its pre-txn value for rollback; commits keep the write. No-op outside a transaction.
|
|
2471
|
+
function Tree.RecordRawWrite(self: Tree, store: { [string]: any }, key: string)
|
|
2472
|
+
local txn = self._txn
|
|
2473
|
+
if not txn or txn.RawRestores[key] ~= nil then
|
|
2474
|
+
return
|
|
2475
|
+
end
|
|
2476
|
+
txn.RawRestores[key] = { Store = store, Value = store[key] }
|
|
2477
|
+
end
|
|
2478
|
+
|
|
2479
|
+
-- The rollback half of RunTransaction. Its own function so the caller can pcall it
|
|
2480
|
+
-- and still drain the queued fires when a restore or a recompute throws: a tree left
|
|
2481
|
+
-- with `_fireQueue` set would go permanently silent.
|
|
2482
|
+
local function rollbackTransaction(self: Tree, txn: any)
|
|
2483
|
+
-- Roll back every touched field to its pre-transaction value; listeners are told
|
|
2484
|
+
-- afterwards, in one drain.
|
|
2485
|
+
--
|
|
2486
|
+
-- Restores EMIT replication ops. A listener woken by the drain can write a field this
|
|
2487
|
+
-- txn also touched, and that write replicates, so only an emitted restore keeps the
|
|
2488
|
+
-- client's baseline equal to the server's. ORDERED, because those listener writes are
|
|
2489
|
+
-- neither snapshotted nor rolled back. Sorting does not stop the write; it makes the
|
|
2490
|
+
-- outcome the same every run, which Universe.Digest depends on outright.
|
|
2491
|
+
local ordered: { { Path: { string | number }, Value: any } } = {}
|
|
2492
|
+
local orderKeys: { [any]: string } = {}
|
|
2493
|
+
for pathKey, snapshot in txn.Snapshots :: { [string]: { Path: { string | number }, Value: any } } do
|
|
2494
|
+
ordered[#ordered + 1] = snapshot
|
|
2495
|
+
orderKeys[snapshot] = pathKey
|
|
2496
|
+
end
|
|
2497
|
+
-- Shallowest first, then by path key: if a snapshot pair is ever not disjoint, the
|
|
2498
|
+
-- ancestor must land before the descendant it contains, not be overwritten by it.
|
|
2499
|
+
table.sort(
|
|
2500
|
+
ordered,
|
|
2501
|
+
function(a: { Path: { string | number }, Value: any }, b: { Path: { string | number }, Value: any })
|
|
2502
|
+
if #a.Path ~= #b.Path then
|
|
2503
|
+
return #a.Path < #b.Path
|
|
2504
|
+
end
|
|
2505
|
+
return orderKeys[a] < orderKeys[b]
|
|
2506
|
+
end
|
|
2507
|
+
)
|
|
2508
|
+
for _, snapshot in ordered do
|
|
2509
|
+
local baseSchema, dynStart = Template.Resolve(self.Compiled, snapshot.Path)
|
|
2510
|
+
local exactSchema: SchemaNode? = baseSchema
|
|
2511
|
+
for i = dynStart, #snapshot.Path do
|
|
2512
|
+
exactSchema = if exactSchema then Template.ChildSchema(exactSchema, snapshot.Path[i]) else nil
|
|
2513
|
+
end
|
|
2514
|
+
applySet(self, snapshot.Path, exactSchema, snapshot.Value, {
|
|
2515
|
+
NoValidate = true,
|
|
2516
|
+
})
|
|
2517
|
+
end
|
|
2518
|
+
-- Restore raw store writes that bypassed applySet; a nil pre-txn value restores
|
|
2519
|
+
-- by removing the key.
|
|
2520
|
+
for key, restore in txn.RawRestores :: { [string]: { Store: { [string]: any }, Value: any } } do
|
|
2521
|
+
restore.Store[key] = restore.Value
|
|
2522
|
+
end
|
|
2523
|
+
-- Prune containers materialized during the transaction, deepest first, so no
|
|
2524
|
+
-- phantom empty tables survive. A created path covered by a snapshot is
|
|
2525
|
+
-- authoritative pre-txn state the restore just recreated: never prune those.
|
|
2526
|
+
local created = txn.Created :: { { string | number } }
|
|
2527
|
+
local snapshots = txn.Snapshots :: { [string]: { Path: { string | number }, Value: any } }
|
|
2528
|
+
local function coveredBySnapshot(createdPath: { string | number }): boolean
|
|
2529
|
+
for _, snap in snapshots do
|
|
2530
|
+
if #snap.Path == #createdPath then
|
|
2531
|
+
local same = true
|
|
2532
|
+
for i = 1, #snap.Path do
|
|
2533
|
+
if snap.Path[i] ~= createdPath[i] then
|
|
2534
|
+
same = false
|
|
2535
|
+
break
|
|
2536
|
+
end
|
|
2537
|
+
end
|
|
2538
|
+
if same then
|
|
2539
|
+
return true
|
|
2540
|
+
end
|
|
2541
|
+
elseif pathIsStrictAncestor(snap.Path, createdPath) then
|
|
2542
|
+
return true
|
|
2543
|
+
end
|
|
2544
|
+
end
|
|
2545
|
+
return false
|
|
2546
|
+
end
|
|
2547
|
+
for i = #created, 1, -1 do
|
|
2548
|
+
if not coveredBySnapshot(created[i]) then
|
|
2549
|
+
local container, key = resolveContainer(self, created[i], false)
|
|
2550
|
+
-- No emptiness requirement: a path in Created did not exist before the
|
|
2551
|
+
-- transaction. Necessary too, since a declared element materializes from its
|
|
2552
|
+
-- defaults and so is never empty.
|
|
2553
|
+
if container ~= nil and type(container[key]) == "table" then
|
|
2554
|
+
-- Prune through applySet so the removal EMITS: a restore op beneath this
|
|
2555
|
+
-- created container has just materialized it on the client, and a silent
|
|
2556
|
+
-- raw removal would strand that phantom {} forever.
|
|
2557
|
+
local baseSchema, dynStart = Template.Resolve(self.Compiled, created[i])
|
|
2558
|
+
local exactSchema: SchemaNode? = baseSchema
|
|
2559
|
+
for j = dynStart, #created[i] do
|
|
2560
|
+
exactSchema = if exactSchema then Template.ChildSchema(exactSchema, created[i][j]) else nil
|
|
2561
|
+
end
|
|
2562
|
+
applySet(self, created[i], exactSchema, nil, { NoValidate = true })
|
|
2563
|
+
end
|
|
2564
|
+
end
|
|
2565
|
+
end
|
|
2566
|
+
-- The restores above settle as they go, since the transaction is closed by now.
|
|
2567
|
+
-- This is the backstop for a body that dirtied a field where every restore was a
|
|
2568
|
+
-- no-op, leaving marks unclaimed until the next unrelated write.
|
|
2569
|
+
settleDerived(self)
|
|
2570
|
+
end
|
|
2571
|
+
|
|
2572
|
+
-- `onSeeded`, when given, is called on the COMMIT path with the path of every
|
|
2573
|
+
-- declared container element this transaction materialized IMPLICITLY: a write
|
|
2574
|
+
-- descended through a key that named no element. A deliberate whole-element Set is
|
|
2575
|
+
-- not one of these. The receipt path uses it; see GRANT_SEEDED_ELEMENT.
|
|
2576
|
+
function Tree.RunTransaction(
|
|
2577
|
+
self: Tree,
|
|
2578
|
+
fn: () -> (),
|
|
2579
|
+
onSeeded: ((seeded: { { string | number } }) -> ())?
|
|
2580
|
+
): (boolean, string?)
|
|
2581
|
+
assertAlive(self)
|
|
2582
|
+
if self._txn then
|
|
2583
|
+
error("Scribe: transactions do not nest", 2)
|
|
2584
|
+
end
|
|
2585
|
+
-- Nor does a transaction on a DIFFERENT player nest inside this one, which is the
|
|
2586
|
+
-- shape a trade is written in. The guard above only sees one player's tree, and
|
|
2587
|
+
-- neither half of such a pair is atomic with the other: an outer throw after the
|
|
2588
|
+
-- inner commit mints value, an inner rollback under a committing outer destroys it.
|
|
2589
|
+
if OPEN_TXN_TREE ~= nil then
|
|
2590
|
+
error(
|
|
2591
|
+
`Scribe: a transaction is already open on another player, and transactions do not span players: `
|
|
2592
|
+
.. CROSS_TREE_TXN_WHY,
|
|
2593
|
+
2
|
|
2594
|
+
)
|
|
2595
|
+
end
|
|
2596
|
+
self._txn = { Snapshots = {}, Below = {}, Ops = {}, Created = {}, Seeded = {}, RawRestores = {}, Economy = {} }
|
|
2597
|
+
OPEN_TXN_TREE = self
|
|
2598
|
+
-- Everything already queued belongs to an enclosing batch, not to this
|
|
2599
|
+
-- transaction, so a rollback must leave it alone.
|
|
2600
|
+
local outerOrder = self._pendingAncestorOrder
|
|
2601
|
+
local pendingMark = if outerOrder then #outerOrder else 0
|
|
2602
|
+
-- RESTORED, not decremented, at the end. A Data.Batch opened inside `fn` raises the
|
|
2603
|
+
-- depth on `fn`'s coroutine, and closing that coroutine on the yield path does not
|
|
2604
|
+
-- unwind pending frames in Luau, so RunBatch's decrement dies with the stack.
|
|
2605
|
+
-- Decrementing only our own would strand the tree above zero, where
|
|
2606
|
+
-- flushPendingAncestors never runs and every container listener goes silent.
|
|
2607
|
+
local depthBefore = self._batchDepth
|
|
2608
|
+
self._batchDepth += 1
|
|
2609
|
+
-- Run fn in its OWN coroutine so a yield can be detected. Every write path absorbs
|
|
2610
|
+
-- into `self._txn` while it is set, so a concurrent write landing during a yield
|
|
2611
|
+
-- would be pulled into this transaction and rolled back with it, reverting a receipt
|
|
2612
|
+
-- grant and losing paid currency. Refuse the yield and roll back fn's writes so far.
|
|
2613
|
+
-- The inner xpcall preserves the original traceback for the non-yield case.
|
|
2614
|
+
local co = coroutine.create(function()
|
|
2615
|
+
return xpcall(fn :: any, function(e)
|
|
2616
|
+
return debug.traceback(tostring(e), 2)
|
|
2617
|
+
end)
|
|
2618
|
+
end)
|
|
2619
|
+
local resumed, innerOk, innerErr = coroutine.resume(co)
|
|
2620
|
+
local ok, err
|
|
2621
|
+
if coroutine.status(co) ~= "dead" then
|
|
2622
|
+
coroutine.close(co) -- cancel it so the scheduler never resumes it after rollback
|
|
2623
|
+
ok, err = false, YIELD_ERROR
|
|
2624
|
+
elseif not resumed then
|
|
2625
|
+
ok, err = false, tostring(innerOk) -- coroutine itself errored (should not happen)
|
|
2626
|
+
else
|
|
2627
|
+
ok, err = innerOk, innerErr
|
|
2628
|
+
end
|
|
2629
|
+
-- Settle while the transaction is still open, so a recompute is journaled with the
|
|
2630
|
+
-- writes that caused it and commits or rolls back atomically with them.
|
|
2631
|
+
if ok then
|
|
2632
|
+
local settleOk, settleErr = pcall(settleDerived, self)
|
|
2633
|
+
if not settleOk then
|
|
2634
|
+
ok, err = false, tostring(settleErr)
|
|
2635
|
+
end
|
|
2636
|
+
end
|
|
2637
|
+
|
|
2638
|
+
local txn = self._txn :: any
|
|
2639
|
+
self._txn = nil
|
|
2640
|
+
-- Cleared in lockstep with `_txn`, so the restores, the queued drain and the
|
|
2641
|
+
-- OnOp / OnEconomy / onSeeded callbacks all run outside the transaction.
|
|
2642
|
+
OPEN_TXN_TREE = nil
|
|
2643
|
+
self._batchDepth = depthBefore
|
|
2644
|
+
if not ok then
|
|
2645
|
+
discardPendingAncestors(self, pendingMark)
|
|
2646
|
+
end
|
|
2647
|
+
|
|
2648
|
+
if ok then
|
|
2649
|
+
local onOp: ((op: Op, schema: SchemaNode?) -> ())? = self.Params.OnOp
|
|
2650
|
+
if onOp then
|
|
2651
|
+
for _, entry in txn.Ops :: { { Op: Op, Schema: SchemaNode? } } do
|
|
2652
|
+
onOp(entry.Op, entry.Schema)
|
|
2653
|
+
end
|
|
2654
|
+
end
|
|
2655
|
+
local onEconomy: ((path: { string | number }, delta: number, newValue: number, tags: { [string]: any }) -> ())? =
|
|
2656
|
+
self.Params.OnEconomy
|
|
2657
|
+
if onEconomy then
|
|
2658
|
+
for _, event in txn.Economy :: { { Path: { string | number }, Delta: number, New: number, Tags: any } } do
|
|
2659
|
+
onEconomy(event.Path, event.Delta, event.New, event.Tags)
|
|
2660
|
+
end
|
|
2661
|
+
end
|
|
2662
|
+
-- After the ops, so anything reported here describes journaled writes, and only on
|
|
2663
|
+
-- the committed path. pcall, unlike the two callbacks above, because this one is a
|
|
2664
|
+
-- DIAGNOSTIC and the transaction has already committed: a throw would skip
|
|
2665
|
+
-- flushPendingAncestors and surface as a failed grant, which Roblox retries into a
|
|
2666
|
+
-- double grant. OnOp and OnEconomy are load-bearing and stay unguarded.
|
|
2667
|
+
if onSeeded and #txn.Seeded > 0 then
|
|
2668
|
+
local reported = pcall(onSeeded, txn.Seeded :: { { string | number } })
|
|
2669
|
+
if not reported then
|
|
2670
|
+
warn("[Scribe] seeded-element reporter errored")
|
|
2671
|
+
end
|
|
2672
|
+
end
|
|
2673
|
+
if self._batchDepth == 0 then
|
|
2674
|
+
flushPendingAncestors(self)
|
|
2675
|
+
local onBatchEnd: (() -> ())? = self.Params.OnBatchEnd
|
|
2676
|
+
if onBatchEnd then
|
|
2677
|
+
onBatchEnd()
|
|
2678
|
+
end
|
|
2679
|
+
end
|
|
2680
|
+
return true, nil
|
|
2681
|
+
end
|
|
2682
|
+
|
|
2683
|
+
-- Restores run with listener dispatch QUEUED rather than immediate (see `fire`), so
|
|
2684
|
+
-- the tree is whole before any listener sees it. A listener write made during the
|
|
2685
|
+
-- drain is an ordinary post-rollback write: it lands, emits, and is not rolled back.
|
|
2686
|
+
-- Rolling it back too would need an unbounded fixpoint, since undoing it re-fires
|
|
2687
|
+
-- the listener that wrote it.
|
|
2688
|
+
local queue: { { any } } = {}
|
|
2689
|
+
self._fireQueue = queue
|
|
2690
|
+
local rolledBack, rollbackErr = pcall(rollbackTransaction, self, txn)
|
|
2691
|
+
self._fireQueue = nil
|
|
2692
|
+
for _, entry in queue do
|
|
2693
|
+
local args = entry[3]
|
|
2694
|
+
fire(self, entry[1], entry[2], table.unpack(args, 1, args.n))
|
|
2695
|
+
end
|
|
2696
|
+
if not rolledBack then
|
|
2697
|
+
error(rollbackErr, 0)
|
|
2698
|
+
end
|
|
2699
|
+
return false, tostring(err)
|
|
2700
|
+
end
|
|
2701
|
+
|
|
2702
|
+
function Tree.Destroy(self: Tree)
|
|
2703
|
+
self.Dead = true
|
|
2704
|
+
table.clear(self._listeners)
|
|
2705
|
+
-- _paths holds one entry per listened path, so leaving it behind would keep every
|
|
2706
|
+
-- path array alive on a tree destroyed with listeners still connected. Accessors
|
|
2707
|
+
-- need no equivalent sweep: the per-parent _children caches are weak-valued.
|
|
2708
|
+
table.clear(self._paths)
|
|
2709
|
+
table.clear(self._descendants)
|
|
2710
|
+
end
|
|
2711
|
+
|
|
2712
|
+
-- Accessor methods -----------------------------------------------------------------
|
|
2713
|
+
|
|
2714
|
+
type Accessor = any
|
|
2715
|
+
|
|
2716
|
+
local function accessorSchema(accessor: Accessor): SchemaNode?
|
|
2717
|
+
return rawget(accessor, F_SCHEMA) :: any
|
|
2718
|
+
end
|
|
2719
|
+
|
|
2720
|
+
local function accessorTree(accessor: Accessor): Tree
|
|
2721
|
+
return rawget(accessor, F_TREE) :: any
|
|
2722
|
+
end
|
|
2723
|
+
|
|
2724
|
+
local function accessorPath(accessor: Accessor): { string | number }
|
|
2725
|
+
return rawget(accessor, F_PATH) :: any
|
|
2726
|
+
end
|
|
2727
|
+
|
|
2728
|
+
local function accessorKey(accessor: Accessor): string
|
|
2729
|
+
return rawget(accessor, F_KEY) :: any
|
|
2730
|
+
end
|
|
2731
|
+
|
|
2732
|
+
local function parseIncrementArgs(tagsOrReplicate: any): ({ [string]: any }?, boolean?)
|
|
2733
|
+
if type(tagsOrReplicate) == "boolean" then
|
|
2734
|
+
return nil, tagsOrReplicate
|
|
2735
|
+
elseif type(tagsOrReplicate) == "table" then
|
|
2736
|
+
return tagsOrReplicate, nil
|
|
2737
|
+
end
|
|
2738
|
+
return nil, nil
|
|
2739
|
+
end
|
|
2740
|
+
|
|
2741
|
+
-- Declared datatype fields store a packed buffer; the accessor converts at
|
|
2742
|
+
-- the boundary so callers only ever see the real datatype.
|
|
2743
|
+
local function unpackIfDatatype(schema: SchemaNode?, value: any): any
|
|
2744
|
+
if schema and schema.ValueType == "datatype" and type(value) == "buffer" then
|
|
2745
|
+
return Datatypes.Unpack(schema.Datatype :: string, value)
|
|
2746
|
+
end
|
|
2747
|
+
return value
|
|
2748
|
+
end
|
|
2749
|
+
|
|
2750
|
+
-- Read-boundary unpack that also handles containers: one with packed descendants
|
|
2751
|
+
-- comes back as a fresh table with every buffer and mantissa pair converted, so a
|
|
2752
|
+
-- container read never leaks a stored shape. Unpacked subtrees are shared by
|
|
2753
|
+
-- reference, and a container with nothing packed below returns unchanged.
|
|
2754
|
+
local function unpackRead(schema: SchemaNode?, value: any): any
|
|
2755
|
+
-- A big is stored as { mantissa, exponent } and read as the object with
|
|
2756
|
+
-- arithmetic on it, the same split datatype fields use.
|
|
2757
|
+
if schema and schema.ValueType == "big" then
|
|
2758
|
+
return if value == nil then nil else Big.from(value)
|
|
2759
|
+
end
|
|
2760
|
+
if type(value) == "table" then
|
|
2761
|
+
if schema ~= nil and Template.IsPacked(schema) then
|
|
2762
|
+
local out: { [any]: any } = {}
|
|
2763
|
+
for k, v in value do
|
|
2764
|
+
out[k] = unpackRead(Template.ChildSchema(schema, k), v)
|
|
2765
|
+
end
|
|
2766
|
+
return out
|
|
2767
|
+
end
|
|
2768
|
+
return value
|
|
2769
|
+
end
|
|
2770
|
+
return unpackIfDatatype(schema, value)
|
|
2771
|
+
end
|
|
2772
|
+
|
|
2773
|
+
-- Schema of a container's entries: the compiled element for a Scribe.ArrayOf /
|
|
2774
|
+
-- Scribe.DictOf, otherwise the generic dynamic pseudo-node (or nil for a leaf).
|
|
2775
|
+
local function elementSchemaOf(schema: SchemaNode?): SchemaNode?
|
|
2776
|
+
return if schema then Template.ChildSchema(schema, 1) else nil
|
|
2777
|
+
end
|
|
2778
|
+
|
|
2779
|
+
-- Whether `schema` sits anywhere inside an ArrayOf/DictOf element subtree. Fields
|
|
2780
|
+
-- there may legitimately not exist yet, unlike static fields, which Reconcile
|
|
2781
|
+
-- guarantees present.
|
|
2782
|
+
local function inElementSubtree(schema: SchemaNode?): boolean
|
|
2783
|
+
local cursor = schema
|
|
2784
|
+
while cursor do
|
|
2785
|
+
if cursor.IsElement then
|
|
2786
|
+
return true
|
|
2787
|
+
end
|
|
2788
|
+
cursor = cursor.Parent
|
|
2789
|
+
end
|
|
2790
|
+
return false
|
|
2791
|
+
end
|
|
2792
|
+
|
|
2793
|
+
-- Canonical packed form of a datatype, for comparison only. Packing is not
|
|
2794
|
+
-- byte-canonical for every codec, so a value Get() handed out would not re-pack to the
|
|
2795
|
+
-- bytes it came from; routing both sides through the same unpack+repack lands them on
|
|
2796
|
+
-- one representative, which makes `Has(Get()[i])` work. `precision` must be the same on
|
|
2797
|
+
-- both sides, hence threaded rather than defaulted.
|
|
2798
|
+
local function canonicalDatatype(name: string, value: any, precision: (string | number)?): buffer?
|
|
2799
|
+
local packed: buffer
|
|
2800
|
+
if type(value) == "buffer" then
|
|
2801
|
+
packed = value
|
|
2802
|
+
elseif typeof(value) == name then
|
|
2803
|
+
local ok, result = pcall(Datatypes.Pack, name, value, precision)
|
|
2804
|
+
if not ok then
|
|
2805
|
+
return nil
|
|
2806
|
+
end
|
|
2807
|
+
packed = result
|
|
2808
|
+
else
|
|
2809
|
+
return nil
|
|
2810
|
+
end
|
|
2811
|
+
local unpackOk, unpacked = pcall(Datatypes.Unpack, name, packed)
|
|
2812
|
+
if not unpackOk then
|
|
2813
|
+
return packed
|
|
2814
|
+
end
|
|
2815
|
+
local repackOk, repacked = pcall(Datatypes.Pack, name, unpacked, precision)
|
|
2816
|
+
return if repackOk then repacked else packed
|
|
2817
|
+
end
|
|
2818
|
+
|
|
2819
|
+
-- Structural equality between a STORED entry and a caller-supplied needle, resolved
|
|
2820
|
+
-- through the element schema so packed datatype and big leaves compare by value.
|
|
2821
|
+
local function entryEquals(schema: SchemaNode?, stored: any, needle: any): boolean
|
|
2822
|
+
if schema and schema.ValueType == "big" then
|
|
2823
|
+
-- The stored side is a { mantissa, exponent } pair and the needle is whatever a
|
|
2824
|
+
-- read handed back, so both go through Big.from; otherwise the pair-vs-object
|
|
2825
|
+
-- walk never matches and Has/Find/RemoveValue silently no-op.
|
|
2826
|
+
local a, b = Big.from(stored), Big.from(needle)
|
|
2827
|
+
return a ~= nil and b ~= nil and Big.compare(a, b) == 0
|
|
2828
|
+
end
|
|
2829
|
+
if schema and schema.ValueType == "datatype" then
|
|
2830
|
+
local name = schema.Datatype :: string
|
|
2831
|
+
local a = canonicalDatatype(name, stored, schema.Precision)
|
|
2832
|
+
local b = canonicalDatatype(name, needle, schema.Precision)
|
|
2833
|
+
return a ~= nil and b ~= nil and Util.bufferEquals(a, b)
|
|
2834
|
+
end
|
|
2835
|
+
if type(stored) == "buffer" or type(needle) == "buffer" then
|
|
2836
|
+
return type(stored) == "buffer" and type(needle) == "buffer" and Util.bufferEquals(stored, needle)
|
|
2837
|
+
end
|
|
2838
|
+
if type(stored) ~= "table" or type(needle) ~= "table" then
|
|
2839
|
+
return stored == needle
|
|
2840
|
+
end
|
|
2841
|
+
local seen = 0
|
|
2842
|
+
for k, v in stored do
|
|
2843
|
+
if not entryEquals(if schema then Template.ChildSchema(schema, k) else nil, v, (needle :: any)[k]) then
|
|
2844
|
+
return false
|
|
2845
|
+
end
|
|
2846
|
+
seen += 1
|
|
2847
|
+
end
|
|
2848
|
+
for _ in needle do
|
|
2849
|
+
seen -= 1
|
|
2850
|
+
end
|
|
2851
|
+
return seen == 0
|
|
2852
|
+
end
|
|
2853
|
+
|
|
2854
|
+
-- Element-aware `table.find`. A declared element is compared structurally, because
|
|
2855
|
+
-- entries reach callers unpacked and copied, so identity never holds. Untyped
|
|
2856
|
+
-- containers keep identity semantics, which existing code relies on.
|
|
2857
|
+
local function findElement(schema: SchemaNode?, arr: { any }, item: any): number?
|
|
2858
|
+
if schema and schema.Container == "Dict" then
|
|
2859
|
+
error(
|
|
2860
|
+
"Scribe: Find/Has/RemoveValue search array entries; a Scribe.DictOf is keyed, "
|
|
2861
|
+
.. "so read the key directly (or Remove(key))",
|
|
2862
|
+
0
|
|
2863
|
+
)
|
|
2864
|
+
end
|
|
2865
|
+
local element = elementSchemaOf(schema)
|
|
2866
|
+
if element == nil or not (element.IsElement or element.ValueType == "datatype") then
|
|
2867
|
+
return table.find(arr, item)
|
|
2868
|
+
end
|
|
2869
|
+
for i, v in arr do
|
|
2870
|
+
if entryEquals(element, v, item) then
|
|
2871
|
+
return i
|
|
2872
|
+
end
|
|
2873
|
+
end
|
|
2874
|
+
return nil
|
|
2875
|
+
end
|
|
2876
|
+
|
|
2877
|
+
-- Clone counterpart: a full deep copy with packed descendants unpacked, so Clone()
|
|
2878
|
+
-- of a datatype- or big-bearing container yields an independent value in its read
|
|
2879
|
+
-- shape rather than the stored one.
|
|
2880
|
+
local function cloneUnpack(schema: SchemaNode?, value: any): any
|
|
2881
|
+
if schema and schema.ValueType == "big" then
|
|
2882
|
+
-- A Big object is immutable and built fresh here, so it needs no extra copy.
|
|
2883
|
+
return if value == nil then nil else Big.from(value)
|
|
2884
|
+
end
|
|
2885
|
+
if type(value) ~= "table" then
|
|
2886
|
+
local unpacked = unpackIfDatatype(schema, value)
|
|
2887
|
+
-- A raw buffer leaf must be copied, not aliased: buffers are mutable and Clone
|
|
2888
|
+
-- promises an independent value. A datatype leaf already became an immutable
|
|
2889
|
+
-- Roblox datatype above.
|
|
2890
|
+
if type(unpacked) == "buffer" then
|
|
2891
|
+
return Util.cloneBuffer(unpacked)
|
|
2892
|
+
end
|
|
2893
|
+
return unpacked
|
|
2894
|
+
end
|
|
2895
|
+
local out: { [any]: any } = {}
|
|
2896
|
+
for k, v in value do
|
|
2897
|
+
out[k] = cloneUnpack(if schema then Template.ChildSchema(schema, k) else nil, v)
|
|
2898
|
+
end
|
|
2899
|
+
return out
|
|
2900
|
+
end
|
|
2901
|
+
|
|
2902
|
+
-- Is this accessor GAME CODE's handle on Scribe's own ledger? Shared by both
|
|
2903
|
+
-- reserved-root guards: the write refusal in accessorIndex and the copy-on-read below.
|
|
2904
|
+
-- Neither term can change for a given accessor, so callers evaluate this once when a
|
|
2905
|
+
-- method is built.
|
|
2906
|
+
local function isPublicReserved(accessor: Accessor): boolean
|
|
2907
|
+
return accessorPath(accessor)[1] == Template.RESERVED_ROOT and not PRIVILEGED[accessor]
|
|
2908
|
+
end
|
|
2909
|
+
|
|
2910
|
+
-- The independent copy Clone() hands back: unpack-and-deep-clone when anything below
|
|
2911
|
+
-- is packed, an ordinary deep clone otherwise. Shared with the reserved-root read
|
|
2912
|
+
-- guard, which needs the identical value.
|
|
2913
|
+
local function detachedCopy(schema: SchemaNode?, value: any): any
|
|
2914
|
+
if Template.IsPacked(schema) then
|
|
2915
|
+
return cloneUnpack(schema, value)
|
|
2916
|
+
end
|
|
2917
|
+
return Util.deepClone(value)
|
|
2918
|
+
end
|
|
2919
|
+
|
|
2920
|
+
-- The read boundary. An ordinary read unpacks and hands back the live stored table by
|
|
2921
|
+
-- reference, which is deliberate; a read of the reserved root BY GAME CODE hands back a
|
|
2922
|
+
-- detached deep copy, or the write guard in accessorIndex is decorative and clearing the
|
|
2923
|
+
-- ledger through a reader lets the next retried receipt grant twice. Deep, because the
|
|
2924
|
+
-- ledger nests. Not table.freeze, which is permanent in Luau and would break the
|
|
2925
|
+
-- library's own writes through Tree.Reserved.
|
|
2926
|
+
local function readOut(guarded: boolean, schema: SchemaNode?, value: any): any
|
|
2927
|
+
if guarded and type(value) == "table" then
|
|
2928
|
+
return detachedCopy(schema, value)
|
|
2929
|
+
end
|
|
2930
|
+
return unpackRead(schema, value)
|
|
2931
|
+
end
|
|
2932
|
+
|
|
2933
|
+
-- The whole-data value the ROOT accessor reads. Reading the store directly is wrong in
|
|
2934
|
+
-- both directions: it carries Scribe's library-owned roots, which the declared type
|
|
2935
|
+
-- never had, and it is only one of the two stores, so Session roots go missing. Building
|
|
2936
|
+
-- from the DECLARED roots gives exactly the keys the template promises. Scribe's
|
|
2937
|
+
-- internals stay reachable by indexing the accessor (`data._Scribe.Perks`).
|
|
2938
|
+
local function rootShell(tree: Tree, clone: boolean): { [string]: any }
|
|
2939
|
+
local out: { [string]: any } = {}
|
|
2940
|
+
local children = tree.Compiled.Root.Children
|
|
2941
|
+
if children == nil then
|
|
2942
|
+
return out
|
|
2943
|
+
end
|
|
2944
|
+
for key, childSchema in children do
|
|
2945
|
+
if key == Template.RESERVED_ROOT or key == Template.SESSION_ROOT then
|
|
2946
|
+
continue
|
|
2947
|
+
end
|
|
2948
|
+
local value = storeFor(tree, key)[key]
|
|
2949
|
+
if value == nil then
|
|
2950
|
+
continue
|
|
2951
|
+
end
|
|
2952
|
+
if not clone then
|
|
2953
|
+
out[key] = unpackRead(childSchema, value)
|
|
2954
|
+
elseif Template.IsPacked(childSchema) then
|
|
2955
|
+
out[key] = cloneUnpack(childSchema, value)
|
|
2956
|
+
else
|
|
2957
|
+
out[key] = Util.deepClone(value)
|
|
2958
|
+
end
|
|
2959
|
+
end
|
|
2960
|
+
return out
|
|
2961
|
+
end
|
|
2962
|
+
|
|
2963
|
+
-- Every root read hands back the same frozen shell, so Get, Observe and Changed
|
|
2964
|
+
-- cannot disagree about what "all of the data" means.
|
|
2965
|
+
local function frozenRootShell(tree: Tree): { [string]: any }
|
|
2966
|
+
return table.freeze(rootShell(tree, false))
|
|
2967
|
+
end
|
|
2968
|
+
|
|
2969
|
+
-- A root Observe/Changed re-reads every root on every write, and a root holding a
|
|
2970
|
+
-- datatype or a Scribe.Big must be rebuilt key by key to be read at all, so over a few
|
|
2971
|
+
-- thousand packed elements one unrelated write costs milliseconds. The library cannot
|
|
2972
|
+
-- make that cheap safely: skipping the rebuild means sharing one view, and that view
|
|
2973
|
+
-- aliases live store tables. The fix belongs in the game, which should listen to the
|
|
2974
|
+
-- container it cares about. Said once, in DevMode.
|
|
2975
|
+
local ROOT_OBSERVE_WARN_NODES = 512
|
|
2976
|
+
local warnedRootObserve: { [any]: boolean } = setmetatable({}, { __mode = "k" }) :: any
|
|
2977
|
+
|
|
2978
|
+
local function countNodes(value: any, budget: number): number
|
|
2979
|
+
if type(value) ~= "table" or budget <= 0 then
|
|
2980
|
+
return 1
|
|
2981
|
+
end
|
|
2982
|
+
local n = 1
|
|
2983
|
+
for _, child in value do
|
|
2984
|
+
n += countNodes(child, budget - n)
|
|
2985
|
+
if n >= budget then
|
|
2986
|
+
break
|
|
2987
|
+
end
|
|
2988
|
+
end
|
|
2989
|
+
return n
|
|
2990
|
+
end
|
|
2991
|
+
|
|
2992
|
+
local function warnIfRootObserveIsExpensive(tree: Tree, what: string)
|
|
2993
|
+
if not tree.Params.DevMode or warnedRootObserve[tree] then
|
|
2994
|
+
return
|
|
2995
|
+
end
|
|
2996
|
+
local warnFn = tree.Params.LogWarn
|
|
2997
|
+
if warnFn == nil then
|
|
2998
|
+
return
|
|
2999
|
+
end
|
|
3000
|
+
local children = tree.Compiled.Root.Children
|
|
3001
|
+
if children == nil then
|
|
3002
|
+
return
|
|
3003
|
+
end
|
|
3004
|
+
for key, childSchema in children do
|
|
3005
|
+
if key ~= Template.RESERVED_ROOT and key ~= Template.SESSION_ROOT and Template.IsPacked(childSchema) then
|
|
3006
|
+
local nodes = countNodes(storeFor(tree, key)[key], ROOT_OBSERVE_WARN_NODES)
|
|
3007
|
+
if nodes >= ROOT_OBSERVE_WARN_NODES then
|
|
3008
|
+
warnedRootObserve[tree] = true
|
|
3009
|
+
warnFn(
|
|
3010
|
+
`a root {what} re-reads every root on every write, and "{key}" holds a datatype or `
|
|
3011
|
+
.. `Scribe.Big across {nodes}+ values, which must be unpacked each time. Listen to the `
|
|
3012
|
+
.. `container you care about instead (data.{key}.{what}) -- a container only fires for `
|
|
3013
|
+
.. "writes at or under it, so unrelated writes cost nothing. DevMode-only warning."
|
|
3014
|
+
)
|
|
3015
|
+
return
|
|
3016
|
+
end
|
|
3017
|
+
end
|
|
3018
|
+
end
|
|
3019
|
+
end
|
|
3020
|
+
-- Whether this node holds children, and so receives coalesced ancestor fires rather
|
|
3021
|
+
-- than leaf transitions. The root always does; a dynamic node is judged by what is
|
|
3022
|
+
-- stored there now, the best answer available at connect time.
|
|
3023
|
+
local function isContainerNode(tree: Tree, schema: SchemaNode?, path: { string | number }): boolean
|
|
3024
|
+
if #path == 0 then
|
|
3025
|
+
return true
|
|
3026
|
+
end
|
|
3027
|
+
-- Kind == "any" is the pseudo-node Template synthesizes for an undeclared key
|
|
3028
|
+
-- under an untyped `{}` subtree. It is never nil, so testing `schema ~= nil`
|
|
3029
|
+
-- alone would classify every such node as a leaf and skip the check below.
|
|
3030
|
+
if schema ~= nil and schema.Kind ~= "any" then
|
|
3031
|
+
return schema.Kind == "table" or schema.Children ~= nil
|
|
3032
|
+
end
|
|
3033
|
+
return type(readValue(tree, path)) == "table"
|
|
3034
|
+
end
|
|
3035
|
+
|
|
3036
|
+
local METHOD_FACTORIES: { [string]: (Accessor) -> any } = {}
|
|
3037
|
+
|
|
3038
|
+
-- Reads settle first, so a derived field never hands back a value its inputs have
|
|
3039
|
+
-- moved past, inside a batch or mid-transaction alike. One nil compare when nothing
|
|
3040
|
+
-- is dirty, which is the common case.
|
|
3041
|
+
local function settleForRead(tree: Tree)
|
|
3042
|
+
if tree._derivedDirty ~= nil then
|
|
3043
|
+
settleDerived(tree)
|
|
3044
|
+
end
|
|
3045
|
+
end
|
|
3046
|
+
|
|
3047
|
+
METHOD_FACTORIES.Get = function(accessor)
|
|
3048
|
+
local guarded = isPublicReserved(accessor)
|
|
3049
|
+
return function()
|
|
3050
|
+
local tree = accessorTree(accessor)
|
|
3051
|
+
assertAlive(tree)
|
|
3052
|
+
settleForRead(tree)
|
|
3053
|
+
local path = accessorPath(accessor)
|
|
3054
|
+
if #path == 0 then
|
|
3055
|
+
-- Frozen so `Get().Coins = 1` raises at the offending line. Unfrozen, it
|
|
3056
|
+
-- either edits authoritative state unvalidated or is silently discarded,
|
|
3057
|
+
-- depending only on whether the template declares a datatype anywhere.
|
|
3058
|
+
return frozenRootShell(tree)
|
|
3059
|
+
end
|
|
3060
|
+
return readOut(guarded, accessorSchema(accessor), readValue(tree, path))
|
|
3061
|
+
end
|
|
3062
|
+
end
|
|
3063
|
+
|
|
3064
|
+
METHOD_FACTORIES.Set = function(accessor)
|
|
3065
|
+
return function(value: any, replicate: boolean?)
|
|
3066
|
+
local tree = accessorTree(accessor)
|
|
3067
|
+
assertAlive(tree)
|
|
3068
|
+
local schema = accessorSchema(accessor)
|
|
3069
|
+
local stored = applySet(tree, accessorPath(accessor), schema, value, { Replicate = replicate })
|
|
3070
|
+
return unpackRead(schema, stored)
|
|
3071
|
+
end
|
|
3072
|
+
end
|
|
3073
|
+
|
|
3074
|
+
METHOD_FACTORIES.Update = function(accessor)
|
|
3075
|
+
return function(fn: (any) -> any, replicate: boolean?)
|
|
3076
|
+
local tree = accessorTree(accessor)
|
|
3077
|
+
assertAlive(tree)
|
|
3078
|
+
local schema = accessorSchema(accessor)
|
|
3079
|
+
local current = unpackRead(schema, readValue(tree, accessorPath(accessor)))
|
|
3080
|
+
local stored = applySet(tree, accessorPath(accessor), schema, fn(current), { Replicate = replicate })
|
|
3081
|
+
return unpackRead(schema, stored)
|
|
3082
|
+
end
|
|
3083
|
+
end
|
|
3084
|
+
|
|
3085
|
+
METHOD_FACTORIES.Clone = function(accessor)
|
|
3086
|
+
return function()
|
|
3087
|
+
local tree = accessorTree(accessor)
|
|
3088
|
+
assertAlive(tree)
|
|
3089
|
+
settleForRead(tree)
|
|
3090
|
+
local path = accessorPath(accessor)
|
|
3091
|
+
if #path == 0 then
|
|
3092
|
+
-- Deliberately NOT frozen: an editable copy is the point of Clone, and
|
|
3093
|
+
-- it is already detached from the store.
|
|
3094
|
+
return rootShell(tree, true)
|
|
3095
|
+
end
|
|
3096
|
+
-- detachedCopy deep-clones and unpacks together when anything below is packed,
|
|
3097
|
+
-- so the copy is independent and in its read shape.
|
|
3098
|
+
return detachedCopy(accessorSchema(accessor), readValue(tree, path))
|
|
3099
|
+
end
|
|
3100
|
+
end
|
|
3101
|
+
|
|
3102
|
+
-- Flags helpers. Each reads the current set, edits it and writes the whole field
|
|
3103
|
+
-- back, so a flag change is one validated, replicated write firing one Changed.
|
|
3104
|
+
local function flagsSchema(accessor: Accessor, method: string): SchemaNode
|
|
3105
|
+
local schema = accessorSchema(accessor)
|
|
3106
|
+
if not schema or schema.ValueType ~= "flags" then
|
|
3107
|
+
error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Flags field ({method})`, 3)
|
|
3108
|
+
end
|
|
3109
|
+
return schema
|
|
3110
|
+
end
|
|
3111
|
+
|
|
3112
|
+
local function flagsSet(
|
|
3113
|
+
tree: Tree,
|
|
3114
|
+
accessor: Accessor,
|
|
3115
|
+
schema: SchemaNode,
|
|
3116
|
+
name: string,
|
|
3117
|
+
on: boolean,
|
|
3118
|
+
replicate: boolean?
|
|
3119
|
+
)
|
|
3120
|
+
local index = schema.MemberIndex :: { [string]: number }
|
|
3121
|
+
if index[name] == nil then
|
|
3122
|
+
error(`Scribe: "{tostring(name)}" is not a member of "{Util.pathString(accessorPath(accessor))}"`, 3)
|
|
3123
|
+
end
|
|
3124
|
+
local current = readValue(tree, accessorPath(accessor))
|
|
3125
|
+
local enabled: { [string]: boolean } = {}
|
|
3126
|
+
if type(current) == "table" then
|
|
3127
|
+
for _, member in current :: { string } do
|
|
3128
|
+
enabled[member] = true
|
|
3129
|
+
end
|
|
3130
|
+
end
|
|
3131
|
+
-- `or false` matters: an unset flag reads nil, and nil == false is false, so a
|
|
3132
|
+
-- Disable on an already-off flag would otherwise write and fire Changed.
|
|
3133
|
+
if (enabled[name] or false) == on then
|
|
3134
|
+
return -- no transition, so no write, no Changed, no replication op
|
|
3135
|
+
end
|
|
3136
|
+
enabled[name] = on or nil
|
|
3137
|
+
local out = {}
|
|
3138
|
+
for _, member in schema.Members :: { string } do
|
|
3139
|
+
if enabled[member] then
|
|
3140
|
+
table.insert(out, member)
|
|
3141
|
+
end
|
|
3142
|
+
end
|
|
3143
|
+
applySet(tree, accessorPath(accessor), schema, out, { Replicate = replicate })
|
|
3144
|
+
end
|
|
3145
|
+
|
|
3146
|
+
METHOD_FACTORIES.Enable = function(accessor)
|
|
3147
|
+
return function(name: string, replicate: boolean?)
|
|
3148
|
+
local tree = accessorTree(accessor)
|
|
3149
|
+
assertAlive(tree)
|
|
3150
|
+
flagsSet(tree, accessor, flagsSchema(accessor, "Enable"), name, true, replicate)
|
|
3151
|
+
end
|
|
3152
|
+
end
|
|
3153
|
+
|
|
3154
|
+
METHOD_FACTORIES.Disable = function(accessor)
|
|
3155
|
+
return function(name: string, replicate: boolean?)
|
|
3156
|
+
local tree = accessorTree(accessor)
|
|
3157
|
+
assertAlive(tree)
|
|
3158
|
+
flagsSet(tree, accessor, flagsSchema(accessor, "Disable"), name, false, replicate)
|
|
3159
|
+
end
|
|
3160
|
+
end
|
|
3161
|
+
|
|
3162
|
+
-- Scribe.SetOf membership. Both go through the whole-value write path, so
|
|
3163
|
+
-- validateWrite's dedupe-and-sort maintains the invariant; these only decide
|
|
3164
|
+
-- whether a write is needed at all.
|
|
3165
|
+
local function setSchema(accessor: Accessor, method: string): SchemaNode
|
|
3166
|
+
local schema = accessorSchema(accessor)
|
|
3167
|
+
if not schema or not schema.Unique then
|
|
3168
|
+
error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.SetOf field ({method})`, 3)
|
|
3169
|
+
end
|
|
3170
|
+
return schema
|
|
3171
|
+
end
|
|
3172
|
+
|
|
3173
|
+
METHOD_FACTORIES.Add = function(accessor)
|
|
3174
|
+
return function(item: any, replicate: boolean?)
|
|
3175
|
+
local tree = accessorTree(accessor)
|
|
3176
|
+
assertAlive(tree)
|
|
3177
|
+
local schema = setSchema(accessor, "Add")
|
|
3178
|
+
local path = accessorPath(accessor)
|
|
3179
|
+
if item == nil then
|
|
3180
|
+
error(`Scribe: cannot Add nil to "{Util.pathString(path)}"`, 3)
|
|
3181
|
+
end
|
|
3182
|
+
local current = readValue(tree, path)
|
|
3183
|
+
local arr = if type(current) == "table" then current :: { any } else {}
|
|
3184
|
+
if findElement(schema, arr, item) ~= nil then
|
|
3185
|
+
return false -- already a member: no write, no op, no Changed
|
|
3186
|
+
end
|
|
3187
|
+
local next_ = table.clone(arr)
|
|
3188
|
+
table.insert(next_, item)
|
|
3189
|
+
applySet(tree, path, schema, next_, { Replicate = replicate })
|
|
3190
|
+
return true
|
|
3191
|
+
end
|
|
3192
|
+
end
|
|
3193
|
+
|
|
3194
|
+
-- Scribe.Big arithmetic. Each reads, applies the operation and writes the whole
|
|
3195
|
+
-- field, so bounds, replication and the economy event run on the normal write path.
|
|
3196
|
+
local function bigSchema(accessor: Accessor, method: string): SchemaNode
|
|
3197
|
+
local schema = accessorSchema(accessor)
|
|
3198
|
+
if not schema or schema.ValueType ~= "big" then
|
|
3199
|
+
error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Big field ({method})`, 3)
|
|
3200
|
+
end
|
|
3201
|
+
return schema
|
|
3202
|
+
end
|
|
3203
|
+
|
|
3204
|
+
local function bigOperand(accessor: Accessor, method: string, value: any): any
|
|
3205
|
+
local parsed = Big.from(value)
|
|
3206
|
+
if parsed == nil then
|
|
3207
|
+
error(`Scribe: {method} on "{Util.pathString(accessorPath(accessor))}" needs a number or numeric string`, 3)
|
|
3208
|
+
end
|
|
3209
|
+
return parsed
|
|
3210
|
+
end
|
|
3211
|
+
|
|
3212
|
+
local function bigApply(accessor: Accessor, method: string, value: any, replicate: boolean?, op: (any, any) -> any): any
|
|
3213
|
+
local tree = accessorTree(accessor)
|
|
3214
|
+
assertAlive(tree)
|
|
3215
|
+
local schema = bigSchema(accessor, method)
|
|
3216
|
+
local path = accessorPath(accessor)
|
|
3217
|
+
local operand = bigOperand(accessor, method, value)
|
|
3218
|
+
-- A Nullable leaf has no default and is legitimately absent, so there is nothing to
|
|
3219
|
+
-- arithmetic against. Starting from 0 would contradict every other Scribe.Optional
|
|
3220
|
+
-- leaf, where Increment on an absent value errors.
|
|
3221
|
+
local current = Big.from(readValue(tree, path)) or Big.from(schema.Default)
|
|
3222
|
+
if current == nil then
|
|
3223
|
+
if schema.Nullable then
|
|
3224
|
+
validationError(path, `{method} on an absent Scribe.Optional value`)
|
|
3225
|
+
end
|
|
3226
|
+
current = Big.from(0)
|
|
3227
|
+
end
|
|
3228
|
+
local result = op(current, operand)
|
|
3229
|
+
if result == nil then
|
|
3230
|
+
error(`Scribe: {method} on "{Util.pathString(path)}" divided by zero`, 3)
|
|
3231
|
+
end
|
|
3232
|
+
return unpackRead(schema, applySet(tree, path, schema, result, { Replicate = replicate }))
|
|
3233
|
+
end
|
|
3234
|
+
|
|
3235
|
+
METHOD_FACTORIES.Multiply = function(accessor)
|
|
3236
|
+
return function(factor: any, replicate: boolean?)
|
|
3237
|
+
return bigApply(accessor, "Multiply", factor, replicate, Big.mul)
|
|
3238
|
+
end
|
|
3239
|
+
end
|
|
3240
|
+
|
|
3241
|
+
METHOD_FACTORIES.Divide = function(accessor)
|
|
3242
|
+
return function(factor: any, replicate: boolean?)
|
|
3243
|
+
return bigApply(accessor, "Divide", factor, replicate, Big.div)
|
|
3244
|
+
end
|
|
3245
|
+
end
|
|
3246
|
+
|
|
3247
|
+
local function incrementImpl(accessor: Accessor, delta: any, tagsOrReplicate: any, defaultFlow: string): any
|
|
3248
|
+
local tree = accessorTree(accessor)
|
|
3249
|
+
assertAlive(tree)
|
|
3250
|
+
local path = accessorPath(accessor)
|
|
3251
|
+
local bigNode = accessorSchema(accessor)
|
|
3252
|
+
if not (bigNode and bigNode.ValueType == "big") and defaultFlow == "Sink" and type(delta) == "number" then
|
|
3253
|
+
delta = -delta
|
|
3254
|
+
end
|
|
3255
|
+
if bigNode and bigNode.ValueType == "big" then
|
|
3256
|
+
-- Same economy plumbing as a plain number, with arithmetic that does not
|
|
3257
|
+
-- lose the value at 2^53.
|
|
3258
|
+
local method = if defaultFlow == "Source" then "Increment" else "Decrement"
|
|
3259
|
+
local signed = bigOperand(accessor, method, delta)
|
|
3260
|
+
if defaultFlow == "Sink" then
|
|
3261
|
+
signed = Big.negate(signed)
|
|
3262
|
+
end
|
|
3263
|
+
local tags, replicate = parseIncrementArgs(tagsOrReplicate)
|
|
3264
|
+
local stored = Big.from(readValue(tree, path)) or Big.from(bigNode.Default)
|
|
3265
|
+
if stored == nil and bigNode.Nullable then
|
|
3266
|
+
validationError(path, `{method} on an absent Scribe.Optional value`)
|
|
3267
|
+
end
|
|
3268
|
+
local before: Big.Big = stored or BIG_ZERO
|
|
3269
|
+
local result = bigApply(accessor, method, signed, replicate, Big.add)
|
|
3270
|
+
if tags and tree.Params.OnEconomy then
|
|
3271
|
+
local after: Big.Big = Big.from(result) or BIG_ZERO
|
|
3272
|
+
-- Report the EFFECTIVE change so a Min/Max clamp does not over-report.
|
|
3273
|
+
-- LogEconomyEvent takes a double, so the conversion happens here;
|
|
3274
|
+
-- Big.toNumber saturates past the double range, which is lossy but
|
|
3275
|
+
-- reaches the log, unlike a table that Analytics' pcall would swallow.
|
|
3276
|
+
local effective = Big.sub(after, before)
|
|
3277
|
+
if Big.compare(effective, BIG_ZERO) ~= 0 then
|
|
3278
|
+
local applied = table.clone(tags)
|
|
3279
|
+
if applied.Flow == nil then
|
|
3280
|
+
applied.Flow = defaultFlow
|
|
3281
|
+
end
|
|
3282
|
+
local effectiveDelta = Big.toNumber(effective)
|
|
3283
|
+
local newValue = Big.toNumber(after)
|
|
3284
|
+
local txn = tree._txn
|
|
3285
|
+
if txn then
|
|
3286
|
+
table.insert(txn.Economy, { Path = path, Delta = effectiveDelta, New = newValue, Tags = applied })
|
|
3287
|
+
else
|
|
3288
|
+
tree.Params.OnEconomy(path, effectiveDelta, newValue, applied)
|
|
3289
|
+
end
|
|
3290
|
+
end
|
|
3291
|
+
end
|
|
3292
|
+
return result
|
|
3293
|
+
end
|
|
3294
|
+
if type(delta) ~= "number" or delta ~= delta then
|
|
3295
|
+
validationError(path, "Increment delta must be a number")
|
|
3296
|
+
end
|
|
3297
|
+
local schema = accessorSchema(accessor)
|
|
3298
|
+
local current = readValue(tree, path)
|
|
3299
|
+
if current == nil then
|
|
3300
|
+
-- A declared element leaf not yet written starts from its compiled default
|
|
3301
|
+
-- rather than erroring, so `Resources.Wood.Increment(5)` on a fresh key
|
|
3302
|
+
-- yields 5. Scribe.Optional leaves have no default and keep erroring.
|
|
3303
|
+
if schema and type(schema.Default) == "number" and inElementSubtree(schema) then
|
|
3304
|
+
current = schema.Default
|
|
3305
|
+
end
|
|
3306
|
+
end
|
|
3307
|
+
if type(current) ~= "number" then
|
|
3308
|
+
validationError(path, `Increment on non-number value ({typeof(current)})`)
|
|
3309
|
+
end
|
|
3310
|
+
local tags, replicate = parseIncrementArgs(tagsOrReplicate)
|
|
3311
|
+
local newValue = applySet(tree, path, schema, current + delta, { Replicate = replicate }) :: number
|
|
3312
|
+
-- Report the EFFECTIVE change, not the requested delta: a bounded field may clamp
|
|
3313
|
+
-- or reject, so logging the raw delta over-reports and firing on a no-op logs a
|
|
3314
|
+
-- transaction the balance never made.
|
|
3315
|
+
local effectiveDelta = newValue - current
|
|
3316
|
+
if tags and tree.Params.OnEconomy and effectiveDelta ~= 0 then
|
|
3317
|
+
local applied = table.clone(tags)
|
|
3318
|
+
if applied.Flow == nil then
|
|
3319
|
+
applied.Flow = defaultFlow
|
|
3320
|
+
end
|
|
3321
|
+
local txn = tree._txn
|
|
3322
|
+
if txn then
|
|
3323
|
+
-- Deferred like replication ops: fired on commit, dropped on rollback,
|
|
3324
|
+
-- so a rolled-back Increment never logs a transaction.
|
|
3325
|
+
table.insert(txn.Economy, { Path = path, Delta = effectiveDelta, New = newValue, Tags = applied })
|
|
3326
|
+
else
|
|
3327
|
+
tree.Params.OnEconomy(path, effectiveDelta, newValue, applied)
|
|
3328
|
+
end
|
|
3329
|
+
end
|
|
3330
|
+
return newValue
|
|
3331
|
+
end
|
|
3332
|
+
|
|
3333
|
+
METHOD_FACTORIES.Increment = function(accessor)
|
|
3334
|
+
return function(delta: number, tagsOrReplicate: any?)
|
|
3335
|
+
return incrementImpl(accessor, delta, tagsOrReplicate, "Source")
|
|
3336
|
+
end
|
|
3337
|
+
end
|
|
3338
|
+
|
|
3339
|
+
METHOD_FACTORIES.Decrement = function(accessor)
|
|
3340
|
+
return function(delta: number, tagsOrReplicate: any?)
|
|
3341
|
+
local tree = accessorTree(accessor)
|
|
3342
|
+
if tree.Params.DevMode and type(delta) == "number" and delta < 0 then
|
|
3343
|
+
local warnFn = tree.Params.LogWarn
|
|
3344
|
+
if warnFn then
|
|
3345
|
+
warnFn(
|
|
3346
|
+
`Decrement called with a negative delta at "{Util.pathString(accessorPath(accessor))}", likely a sign error`
|
|
3347
|
+
)
|
|
3348
|
+
end
|
|
3349
|
+
end
|
|
3350
|
+
return incrementImpl(accessor, delta, tagsOrReplicate, "Sink")
|
|
3351
|
+
end
|
|
3352
|
+
end
|
|
3353
|
+
|
|
3354
|
+
-- Min/Max read the declarator's bounds off the static schema, so they work on both
|
|
3355
|
+
-- realms and before data has loaded.
|
|
3356
|
+
METHOD_FACTORIES.Min = function(accessor)
|
|
3357
|
+
return function(): number?
|
|
3358
|
+
local schema = accessorSchema(accessor)
|
|
3359
|
+
return if schema then schema.Min else nil
|
|
3360
|
+
end
|
|
3361
|
+
end
|
|
3362
|
+
|
|
3363
|
+
METHOD_FACTORIES.Max = function(accessor)
|
|
3364
|
+
return function(): number?
|
|
3365
|
+
local schema = accessorSchema(accessor)
|
|
3366
|
+
return if schema then schema.Max else nil
|
|
3367
|
+
end
|
|
3368
|
+
end
|
|
3369
|
+
|
|
3370
|
+
-- The declarator's default, straight off the static schema: a fresh datatype, a Big,
|
|
3371
|
+
-- a deep copy for tables and buffers, or the scalar itself.
|
|
3372
|
+
METHOD_FACTORIES.Default = function(accessor)
|
|
3373
|
+
return function(): any
|
|
3374
|
+
local schema = accessorSchema(accessor)
|
|
3375
|
+
if schema == nil then
|
|
3376
|
+
return nil
|
|
3377
|
+
end
|
|
3378
|
+
if Template.IsPacked(schema) then
|
|
3379
|
+
-- The stored Default holds the PACKED form, so deep-clone and unpack
|
|
3380
|
+
-- together, matching Clone(); a plain deepClone would hand back the
|
|
3381
|
+
-- stored shape.
|
|
3382
|
+
return cloneUnpack(schema, schema.Default)
|
|
3383
|
+
end
|
|
3384
|
+
return Util.deepClone(schema.Default)
|
|
3385
|
+
end
|
|
3386
|
+
end
|
|
3387
|
+
|
|
3388
|
+
METHOD_FACTORIES.Toggle = function(accessor)
|
|
3389
|
+
return function(nameOrReplicate: any, replicate: boolean?)
|
|
3390
|
+
local tree = accessorTree(accessor)
|
|
3391
|
+
assertAlive(tree)
|
|
3392
|
+
local path = accessorPath(accessor)
|
|
3393
|
+
local schema = accessorSchema(accessor)
|
|
3394
|
+
if schema and schema.ValueType == "flags" then
|
|
3395
|
+
-- On a Scribe.Flags field Toggle names the flag to flip, since the field
|
|
3396
|
+
-- holds a set rather than one boolean.
|
|
3397
|
+
if type(nameOrReplicate) ~= "string" then
|
|
3398
|
+
error(`Scribe: Toggle on a Scribe.Flags field takes a member name`, 3)
|
|
3399
|
+
end
|
|
3400
|
+
local index = schema.MemberIndex :: { [string]: number }
|
|
3401
|
+
if index[nameOrReplicate] == nil then
|
|
3402
|
+
error(`Scribe: "{nameOrReplicate}" is not a member of "{Util.pathString(path)}"`, 3)
|
|
3403
|
+
end
|
|
3404
|
+
local current = readValue(tree, path)
|
|
3405
|
+
local on = false
|
|
3406
|
+
if type(current) == "table" then
|
|
3407
|
+
for _, member in current :: { string } do
|
|
3408
|
+
if member == nameOrReplicate then
|
|
3409
|
+
on = true
|
|
3410
|
+
break
|
|
3411
|
+
end
|
|
3412
|
+
end
|
|
3413
|
+
end
|
|
3414
|
+
flagsSet(tree, accessor, schema, nameOrReplicate, not on, replicate)
|
|
3415
|
+
return not on
|
|
3416
|
+
end
|
|
3417
|
+
local replicateFlag = nameOrReplicate :: boolean?
|
|
3418
|
+
local current = readValue(tree, path)
|
|
3419
|
+
if current == nil and schema and type(schema.Default) == "boolean" and inElementSubtree(schema) then
|
|
3420
|
+
-- Same fresh-element fallback as Increment: the entry materializes on
|
|
3421
|
+
-- first write, so Toggle starts from the declared default.
|
|
3422
|
+
current = schema.Default
|
|
3423
|
+
end
|
|
3424
|
+
if type(current) ~= "boolean" then
|
|
3425
|
+
validationError(path, `Toggle on non-boolean value ({typeof(current)})`)
|
|
3426
|
+
end
|
|
3427
|
+
return applySet(tree, path, schema, not current, { Replicate = replicateFlag })
|
|
3428
|
+
end
|
|
3429
|
+
end
|
|
3430
|
+
|
|
3431
|
+
METHOD_FACTORIES.Changed = function(accessor)
|
|
3432
|
+
local guarded = isPublicReserved(accessor)
|
|
3433
|
+
return function(fn: (any, any) -> ())
|
|
3434
|
+
local tree = accessorTree(accessor)
|
|
3435
|
+
local schema = accessorSchema(accessor)
|
|
3436
|
+
local path = accessorPath(accessor)
|
|
3437
|
+
|
|
3438
|
+
-- A container Changed takes no third `key` argument: one fire covers every
|
|
3439
|
+
-- child a batch or a frame touched, so no single key describes it. Refused at
|
|
3440
|
+
-- connect time rather than passing nil forever, which would make
|
|
3441
|
+
-- `if key == "Coins"` quietly stop matching. Arity is read once per connect.
|
|
3442
|
+
if isContainerNode(tree, schema, path) then
|
|
3443
|
+
local params, isVararg = debug.info(fn, "a")
|
|
3444
|
+
if not isVararg and params > 2 then
|
|
3445
|
+
error(
|
|
3446
|
+
`Scribe: a container Changed listener takes (new, old). "{Util.pathString(path)}" declares `
|
|
3447
|
+
.. `{params} parameters. The third key argument was removed because one fire can now cover `
|
|
3448
|
+
.. `several children. Use OnChildChanged(key, value) to learn which child moved.`,
|
|
3449
|
+
3
|
|
3450
|
+
)
|
|
3451
|
+
end
|
|
3452
|
+
end
|
|
3453
|
+
|
|
3454
|
+
if #path == 0 then
|
|
3455
|
+
warnIfRootObserveIsExpensive(tree, "Changed")
|
|
3456
|
+
-- Match what Get hands back. The root's only fires are ancestor fires, where
|
|
3457
|
+
-- old and new are one reference, so a single shell serves both and a
|
|
3458
|
+
-- listener's `if new == old then return` holds.
|
|
3459
|
+
local inner = fn
|
|
3460
|
+
fn = function()
|
|
3461
|
+
local shell = frozenRootShell(tree)
|
|
3462
|
+
inner(shell, shell)
|
|
3463
|
+
end
|
|
3464
|
+
return connect(tree, path, "Changed", fn)
|
|
3465
|
+
end
|
|
3466
|
+
-- `guarded` joins IsPacked here because a listener is a reader: handed the live
|
|
3467
|
+
-- reserved table it could write through it, the same hole readOut closes on Get.
|
|
3468
|
+
if guarded or Template.IsPacked(schema) then
|
|
3469
|
+
local inner = fn
|
|
3470
|
+
fn = function(newValue, oldValue)
|
|
3471
|
+
local newUnpacked = readOut(guarded, schema, newValue)
|
|
3472
|
+
-- An ancestor container fire passes the SAME reference for new and old, so
|
|
3473
|
+
-- reuse the unpacked value: it skips a walk and keeps reference equality
|
|
3474
|
+
-- for a listener's `if new == old then return` guard.
|
|
3475
|
+
local oldUnpacked = if oldValue == newValue then newUnpacked else readOut(guarded, schema, oldValue)
|
|
3476
|
+
inner(newUnpacked, oldUnpacked)
|
|
3477
|
+
end
|
|
3478
|
+
end
|
|
3479
|
+
return connect(tree, path, "Changed", fn)
|
|
3480
|
+
end
|
|
3481
|
+
end
|
|
3482
|
+
|
|
3483
|
+
METHOD_FACTORIES.Observe = function(accessor)
|
|
3484
|
+
local guarded = isPublicReserved(accessor)
|
|
3485
|
+
return function(fn: (any) -> ())
|
|
3486
|
+
local tree = accessorTree(accessor)
|
|
3487
|
+
assertAlive(tree)
|
|
3488
|
+
local schema = accessorSchema(accessor)
|
|
3489
|
+
local path = accessorPath(accessor)
|
|
3490
|
+
local isRoot = #path == 0
|
|
3491
|
+
if isRoot then
|
|
3492
|
+
warnIfRootObserveIsExpensive(tree, "Observe")
|
|
3493
|
+
end
|
|
3494
|
+
local disconnect = connect(tree, path, "Changed", function(newValue)
|
|
3495
|
+
fn(if isRoot then frozenRootShell(tree) else readOut(guarded, schema, newValue))
|
|
3496
|
+
end)
|
|
3497
|
+
local ok, err = xpcall(function()
|
|
3498
|
+
fn(if isRoot then frozenRootShell(tree) else readOut(guarded, schema, readValue(tree, path)))
|
|
3499
|
+
end, function(e)
|
|
3500
|
+
return debug.traceback(tostring(e), 2)
|
|
3501
|
+
end)
|
|
3502
|
+
if not ok then
|
|
3503
|
+
tree.Params.LogError(`listener error at "{accessorKey(accessor)}" (Observe): {err}`)
|
|
3504
|
+
end
|
|
3505
|
+
return disconnect
|
|
3506
|
+
end
|
|
3507
|
+
end
|
|
3508
|
+
|
|
3509
|
+
METHOD_FACTORIES.Insert = function(accessor)
|
|
3510
|
+
return function(item: any, pos: number?, replicate: boolean?)
|
|
3511
|
+
local tree = accessorTree(accessor)
|
|
3512
|
+
assertAlive(tree)
|
|
3513
|
+
applyInsert(tree, accessorPath(accessor), accessorSchema(accessor), item, pos, { Replicate = replicate })
|
|
3514
|
+
end
|
|
3515
|
+
end
|
|
3516
|
+
|
|
3517
|
+
METHOD_FACTORIES.Remove = function(accessor)
|
|
3518
|
+
return function(posOrKey: any, replicate: boolean?)
|
|
3519
|
+
local tree = accessorTree(accessor)
|
|
3520
|
+
assertAlive(tree)
|
|
3521
|
+
local setNode = accessorSchema(accessor)
|
|
3522
|
+
if setNode and setNode.Unique then
|
|
3523
|
+
-- A set has no indices, so Remove names the member to drop.
|
|
3524
|
+
local path = accessorPath(accessor)
|
|
3525
|
+
local current = readValue(tree, path)
|
|
3526
|
+
local arr = if type(current) == "table" then current :: { any } else {}
|
|
3527
|
+
local at = findElement(setNode, arr, posOrKey)
|
|
3528
|
+
if at == nil then
|
|
3529
|
+
return false -- not a member: nothing to do
|
|
3530
|
+
end
|
|
3531
|
+
local next_ = table.clone(arr)
|
|
3532
|
+
table.remove(next_, at)
|
|
3533
|
+
applySet(tree, path, setNode, next_, { Replicate = replicate })
|
|
3534
|
+
return true
|
|
3535
|
+
end
|
|
3536
|
+
-- Branch on the SCHEMA, not the Lua type of the argument: a
|
|
3537
|
+
-- Scribe.MapOf("integer") takes number keys, and reading those as array indices
|
|
3538
|
+
-- would remove the wrong entry. The type fallback covers untyped nodes.
|
|
3539
|
+
if (setNode and setNode.Container == "Dict") or type(posOrKey) == "string" then
|
|
3540
|
+
-- Dictionary removal: sugar for Set(nil) with a useful return.
|
|
3541
|
+
local path = table.clone(accessorPath(accessor))
|
|
3542
|
+
table.insert(path, posOrKey)
|
|
3543
|
+
local schema = accessorSchema(accessor)
|
|
3544
|
+
local childSchema = if schema then Template.ChildSchema(schema, posOrKey) else nil
|
|
3545
|
+
local container, key = resolveContainer(tree, path, false)
|
|
3546
|
+
local old = if container then container[key] else nil
|
|
3547
|
+
if old ~= nil then
|
|
3548
|
+
applySet(tree, path, childSchema, nil, { Replicate = replicate })
|
|
3549
|
+
end
|
|
3550
|
+
-- Convert at the datatype boundary: a removed static datatype leaf is
|
|
3551
|
+
-- stored packed, so return the real value.
|
|
3552
|
+
return unpackRead(childSchema, old)
|
|
3553
|
+
end
|
|
3554
|
+
-- Same datatype boundary as the dictionary branch: an element of a
|
|
3555
|
+
-- Scribe.ArrayOf(Scribe.CFrame(...)) is stored packed, so returning it raw
|
|
3556
|
+
-- would hand the caller a buffer.
|
|
3557
|
+
local schema = accessorSchema(accessor)
|
|
3558
|
+
local removed =
|
|
3559
|
+
applyArrayRemove(tree, accessorPath(accessor), schema, posOrKey :: number?, { Replicate = replicate })
|
|
3560
|
+
return unpackRead(elementSchemaOf(schema), removed)
|
|
3561
|
+
end
|
|
3562
|
+
end
|
|
3563
|
+
|
|
3564
|
+
METHOD_FACTORIES.RemoveValue = function(accessor)
|
|
3565
|
+
return function(item: any, replicate: boolean?): (any, number?)
|
|
3566
|
+
local tree = accessorTree(accessor)
|
|
3567
|
+
assertAlive(tree)
|
|
3568
|
+
local schema = accessorSchema(accessor)
|
|
3569
|
+
local arr = readValue(tree, accessorPath(accessor))
|
|
3570
|
+
if type(arr) ~= "table" then
|
|
3571
|
+
return nil, nil
|
|
3572
|
+
end
|
|
3573
|
+
local index = findElement(schema, arr, item)
|
|
3574
|
+
if index == nil then
|
|
3575
|
+
return nil, nil
|
|
3576
|
+
end
|
|
3577
|
+
local removed = applyArrayRemove(tree, accessorPath(accessor), schema, index, { Replicate = replicate })
|
|
3578
|
+
return unpackRead(elementSchemaOf(schema), removed), index
|
|
3579
|
+
end
|
|
3580
|
+
end
|
|
3581
|
+
|
|
3582
|
+
METHOD_FACTORIES.Find = function(accessor)
|
|
3583
|
+
return function(item: any): number?
|
|
3584
|
+
local tree = accessorTree(accessor)
|
|
3585
|
+
assertAlive(tree)
|
|
3586
|
+
local arr = readValue(tree, accessorPath(accessor))
|
|
3587
|
+
if type(arr) ~= "table" then
|
|
3588
|
+
return nil
|
|
3589
|
+
end
|
|
3590
|
+
return findElement(accessorSchema(accessor), arr, item)
|
|
3591
|
+
end
|
|
3592
|
+
end
|
|
3593
|
+
|
|
3594
|
+
METHOD_FACTORIES.Has = function(accessor)
|
|
3595
|
+
return function(item: any)
|
|
3596
|
+
local tree = accessorTree(accessor)
|
|
3597
|
+
assertAlive(tree)
|
|
3598
|
+
local arr = readValue(tree, accessorPath(accessor))
|
|
3599
|
+
return type(arr) == "table" and findElement(accessorSchema(accessor), arr, item) ~= nil
|
|
3600
|
+
end
|
|
3601
|
+
end
|
|
3602
|
+
|
|
3603
|
+
METHOD_FACTORIES.Clear = function(accessor)
|
|
3604
|
+
return function(replicate: boolean?)
|
|
3605
|
+
local tree = accessorTree(accessor)
|
|
3606
|
+
assertAlive(tree)
|
|
3607
|
+
applyClear(tree, accessorPath(accessor), accessorSchema(accessor), { Replicate = replicate })
|
|
3608
|
+
end
|
|
3609
|
+
end
|
|
3610
|
+
|
|
3611
|
+
METHOD_FACTORIES.Count = function(accessor)
|
|
3612
|
+
return function()
|
|
3613
|
+
local tree = accessorTree(accessor)
|
|
3614
|
+
assertAlive(tree)
|
|
3615
|
+
local value = readValue(tree, accessorPath(accessor))
|
|
3616
|
+
if type(value) ~= "table" then
|
|
3617
|
+
return 0
|
|
3618
|
+
end
|
|
3619
|
+
return Util.count(value)
|
|
3620
|
+
end
|
|
3621
|
+
end
|
|
3622
|
+
|
|
3623
|
+
-- Value handed to an entry-level listener. Packed values are converted back and a
|
|
3624
|
+
-- table is copied: the fired value IS the stored one, so a listener mutating it
|
|
3625
|
+
-- would edit authoritative state with no validation and no replication.
|
|
3626
|
+
local function entryValueForListener(guarded: boolean, schema: SchemaNode?, value: any): any
|
|
3627
|
+
-- Reserved root read by game code gets the same detached copy readOut hands back:
|
|
3628
|
+
-- the live `{ Id, At }` record would let a listener blank an Id and un-dedupe
|
|
3629
|
+
-- that purchase.
|
|
3630
|
+
if guarded and type(value) == "table" then
|
|
3631
|
+
return detachedCopy(schema, value)
|
|
3632
|
+
end
|
|
3633
|
+
if Template.IsPacked(schema) then
|
|
3634
|
+
return cloneUnpack(schema, value)
|
|
3635
|
+
end
|
|
3636
|
+
-- Only a DECLARED element is copied. An untyped container must keep handing out the
|
|
3637
|
+
-- stored reference, because Has/Find/RemoveValue fall back to table.find and a copy
|
|
3638
|
+
-- would make a listener's own entry unfindable.
|
|
3639
|
+
if schema and schema.IsElement and type(value) == "table" then
|
|
3640
|
+
return Util.deepClone(value)
|
|
3641
|
+
end
|
|
3642
|
+
return value
|
|
3643
|
+
end
|
|
3644
|
+
|
|
3645
|
+
-- The listener kinds that receive a container ENTRY rather than the container itself,
|
|
3646
|
+
-- and so need the same datatype conversion Changed and Observe do.
|
|
3647
|
+
for _, event in { "OnInsert", "OnRemove", "OnKeyAdded", "OnKeyRemoved", "OnChildChanged" } do
|
|
3648
|
+
METHOD_FACTORIES[event] = function(accessor)
|
|
3649
|
+
local guarded = isPublicReserved(accessor)
|
|
3650
|
+
-- The root accessor's own path is empty, so isPublicReserved answers false for it,
|
|
3651
|
+
-- but these events carry a CHILD and one of the root's children IS the reserved
|
|
3652
|
+
-- root: without this, binding data.OnChildChanged hands game code the live ledger
|
|
3653
|
+
-- by reference. The PRIVILEGED term is unreachable today and stays, so a
|
|
3654
|
+
-- privileged root added later does not silently start receiving copies.
|
|
3655
|
+
local rootGuard = #accessorPath(accessor) == 0 and not PRIVILEGED[accessor]
|
|
3656
|
+
return function(fn: (...any) -> ())
|
|
3657
|
+
local tree = accessorTree(accessor)
|
|
3658
|
+
local schema = accessorSchema(accessor)
|
|
3659
|
+
local inner = fn
|
|
3660
|
+
local wrapped: (...any) -> ()
|
|
3661
|
+
if event == "OnInsert" or event == "OnRemove" then
|
|
3662
|
+
local element = elementSchemaOf(schema)
|
|
3663
|
+
wrapped = function(value: any, index: any)
|
|
3664
|
+
inner(entryValueForListener(guarded, element, value), index)
|
|
3665
|
+
end
|
|
3666
|
+
elseif event == "OnChildChanged" then
|
|
3667
|
+
-- Carries a transition, so both sides need unpacking. OnKeyAdded and
|
|
3668
|
+
-- OnKeyRemoved take a single value: an appearance has no prior and a
|
|
3669
|
+
-- disappearance has no successor.
|
|
3670
|
+
wrapped = function(key: any, newValue: any, oldValue: any)
|
|
3671
|
+
local childSchema = if schema then Template.ChildSchema(schema, key) else nil
|
|
3672
|
+
local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
|
|
3673
|
+
inner(
|
|
3674
|
+
key,
|
|
3675
|
+
entryValueForListener(g, childSchema, newValue),
|
|
3676
|
+
entryValueForListener(g, childSchema, oldValue)
|
|
3677
|
+
)
|
|
3678
|
+
end
|
|
3679
|
+
else
|
|
3680
|
+
wrapped = function(key: any, value: any)
|
|
3681
|
+
local childSchema = if schema then Template.ChildSchema(schema, key) else nil
|
|
3682
|
+
-- Same key-derived guard. Unreachable today, since the reserved root is
|
|
3683
|
+
-- created with the tree and never appears or disappears
|
|
3684
|
+
-- (RootChildLedgerGuard.spec pins that), but kept so the sibling wrappers
|
|
3685
|
+
-- do not differ for no reason.
|
|
3686
|
+
local g = guarded or (rootGuard and key == Template.RESERVED_ROOT)
|
|
3687
|
+
inner(key, entryValueForListener(g, childSchema, value))
|
|
3688
|
+
end
|
|
3689
|
+
end
|
|
3690
|
+
return connect(tree, accessorPath(accessor), event, wrapped)
|
|
3691
|
+
end
|
|
3692
|
+
end
|
|
3693
|
+
end
|
|
3694
|
+
|
|
3695
|
+
local function timedHooks(accessor: Accessor): TimedHooks
|
|
3696
|
+
local tree = accessorTree(accessor)
|
|
3697
|
+
local schema = accessorSchema(accessor)
|
|
3698
|
+
if not schema or not schema.Timed then
|
|
3699
|
+
error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is not a Scribe.Timed field`, 3)
|
|
3700
|
+
end
|
|
3701
|
+
local hooks = tree.Params.TimedHooks
|
|
3702
|
+
if not hooks then
|
|
3703
|
+
error("Scribe: timed fields are managed on the server", 3)
|
|
3704
|
+
end
|
|
3705
|
+
return hooks
|
|
3706
|
+
end
|
|
3707
|
+
|
|
3708
|
+
METHOD_FACTORIES.SetTimed = function(accessor)
|
|
3709
|
+
return function(value: any, seconds: number, replicate: boolean?)
|
|
3710
|
+
local tree = accessorTree(accessor)
|
|
3711
|
+
assertAlive(tree)
|
|
3712
|
+
timedHooks(accessor).SetTimed(accessor, value, seconds, replicate)
|
|
3713
|
+
end
|
|
3714
|
+
end
|
|
3715
|
+
|
|
3716
|
+
METHOD_FACTORIES.ExtendTimed = function(accessor)
|
|
3717
|
+
return function(seconds: number, replicate: boolean?)
|
|
3718
|
+
local tree = accessorTree(accessor)
|
|
3719
|
+
assertAlive(tree)
|
|
3720
|
+
timedHooks(accessor).ExtendTimed(accessor, seconds, replicate)
|
|
3721
|
+
end
|
|
3722
|
+
end
|
|
3723
|
+
|
|
3724
|
+
METHOD_FACTORIES.Active = function(accessor)
|
|
3725
|
+
return function()
|
|
3726
|
+
local tree = accessorTree(accessor)
|
|
3727
|
+
assertAlive(tree)
|
|
3728
|
+
return timedHooks(accessor).Active(accessor)
|
|
3729
|
+
end
|
|
3730
|
+
end
|
|
3731
|
+
|
|
3732
|
+
-- Accessor metatable -----------------------------------------------------------------
|
|
3733
|
+
|
|
3734
|
+
-- Every method that mutates; all of them are refused on a derived field. Listed by
|
|
3735
|
+
-- name rather than inferred, so a method added later has to make a deliberate choice
|
|
3736
|
+
-- rather than silently becoming writable.
|
|
3737
|
+
local MUTATOR_METHODS: { [string]: boolean } = {
|
|
3738
|
+
Set = true,
|
|
3739
|
+
Update = true,
|
|
3740
|
+
Increment = true,
|
|
3741
|
+
Decrement = true,
|
|
3742
|
+
Multiply = true,
|
|
3743
|
+
Divide = true,
|
|
3744
|
+
Toggle = true,
|
|
3745
|
+
Enable = true,
|
|
3746
|
+
Disable = true,
|
|
3747
|
+
Add = true,
|
|
3748
|
+
Insert = true,
|
|
3749
|
+
Remove = true,
|
|
3750
|
+
RemoveValue = true,
|
|
3751
|
+
Clear = true,
|
|
3752
|
+
SetTimed = true,
|
|
3753
|
+
ExtendTimed = true,
|
|
3754
|
+
}
|
|
3755
|
+
|
|
3756
|
+
-- One module-private identity per mutator name, used as the rawset key its built
|
|
3757
|
+
-- method is cached under. Private so nothing outside this file can name or plant a
|
|
3758
|
+
-- cached mutator. See accessorIndex for why they are not cached under their own name.
|
|
3759
|
+
local MUTATOR_CACHE_KEY: { [string]: any } = {}
|
|
3760
|
+
for name in MUTATOR_METHODS do
|
|
3761
|
+
MUTATOR_CACHE_KEY[name] = {}
|
|
3762
|
+
end
|
|
3763
|
+
|
|
3764
|
+
local function accessorIndex(accessor: Accessor, key: any, childOnly: boolean?): any
|
|
3765
|
+
local factory = if childOnly then nil else METHOD_FACTORIES[key]
|
|
3766
|
+
if factory then
|
|
3767
|
+
if MUTATOR_METHODS[key] then
|
|
3768
|
+
-- A write to a DIFFERENT player's tree is refused while a transaction is open: it
|
|
3769
|
+
-- cannot be rolled back with the transaction, so one half of a trade could commit
|
|
3770
|
+
-- while the other is undone. Reads never enter this branch. The residual: a handle
|
|
3771
|
+
-- taken BEFORE the transaction opened (`local inc = other.Coins.Increment`) is not
|
|
3772
|
+
-- refused, since no index happens at the call. Gated on OPEN_TXN_TREE because
|
|
3773
|
+
-- pathString allocates; level 3 blames the game code that indexed the mutator.
|
|
3774
|
+
if OPEN_TXN_TREE ~= nil then
|
|
3775
|
+
assertSameTreeWrite(accessorTree(accessor), Util.pathString(accessorPath(accessor)), 3)
|
|
3776
|
+
end
|
|
3777
|
+
-- The reserved root is Scribe's own ledger, and ServerOnly only keeps it off the
|
|
3778
|
+
-- wire. Clearing ProcessedPurchaseIds makes the next retried receipt grant a
|
|
3779
|
+
-- second time; dropping Version re-runs every migration against migrated data.
|
|
3780
|
+
-- Refused by CALLER, not by object: the library writes these paths through
|
|
3781
|
+
-- Tree.Reserved, which holds the capability.
|
|
3782
|
+
local path = accessorPath(accessor)
|
|
3783
|
+
if path[1] == Template.RESERVED_ROOT and not PRIVILEGED[accessor] then
|
|
3784
|
+
error(
|
|
3785
|
+
`Scribe: "{Util.pathString(path)}" is inside the reserved "{Template.RESERVED_ROOT}" root `
|
|
3786
|
+
.. `and cannot be written; it is Scribe's own ledger -- processed receipt ids, perks, `
|
|
3787
|
+
.. `gift credits, pending gifts, purchase logs, timers and the schema version. Read it `
|
|
3788
|
+
.. `with the typed readers (Owns, GetGiftCredits, GetPurchases) and change it through `
|
|
3789
|
+
.. `the APIs that own it (GrantPerk, RevokePerk, Purchase, PromptGift)`,
|
|
3790
|
+
2
|
|
3791
|
+
)
|
|
3792
|
+
end
|
|
3793
|
+
local schema = accessorSchema(accessor)
|
|
3794
|
+
local derived = if schema then schema.Derived else nil
|
|
3795
|
+
if derived then
|
|
3796
|
+
local inputs = table.create(#derived.InputPaths)
|
|
3797
|
+
for i, segments in derived.InputPaths do
|
|
3798
|
+
inputs[i] = table.concat(segments, ".")
|
|
3799
|
+
end
|
|
3800
|
+
error(
|
|
3801
|
+
`Scribe: "{Util.pathString(accessorPath(accessor))}" is a derived field and cannot be written; `
|
|
3802
|
+
.. `it is computed from {table.concat(inputs, ", ")}`,
|
|
3803
|
+
2
|
|
3804
|
+
)
|
|
3805
|
+
end
|
|
3806
|
+
-- Cached under a module-private identity rather than under `key`, so every
|
|
3807
|
+
-- `x.Set` keeps going through __index and past the guards. A plain rawset under
|
|
3808
|
+
-- `key`, as the non-mutator branch below does, would be satisfied off the
|
|
3809
|
+
-- accessor table on the second read: harmless for the fixed refusals, wrong for
|
|
3810
|
+
-- the transaction one, which changes with the caller. Cache the method, not the
|
|
3811
|
+
-- decision.
|
|
3812
|
+
local cached = rawget(accessor, MUTATOR_CACHE_KEY[key])
|
|
3813
|
+
if cached ~= nil then
|
|
3814
|
+
return cached
|
|
3815
|
+
end
|
|
3816
|
+
local built = factory(accessor)
|
|
3817
|
+
rawset(accessor, MUTATOR_CACHE_KEY[key], built)
|
|
3818
|
+
return built
|
|
3819
|
+
end
|
|
3820
|
+
local method = factory(accessor)
|
|
3821
|
+
rawset(accessor, key, method)
|
|
3822
|
+
return method
|
|
3823
|
+
end
|
|
3824
|
+
|
|
3825
|
+
local tree = accessorTree(accessor)
|
|
3826
|
+
assertAlive(tree)
|
|
3827
|
+
if type(key) ~= "string" and type(key) ~= "number" then
|
|
3828
|
+
error(`Scribe: invalid child key of type {typeof(key)}`, 2)
|
|
3829
|
+
end
|
|
3830
|
+
-- The pathKey separator (char 31) would let a crafted dynamic key alias a
|
|
3831
|
+
-- distinct path, corrupting coalescing, listeners and txn rollback.
|
|
3832
|
+
if type(key) == "string" and string.find(key, "\31", 1, true) then
|
|
3833
|
+
error("Scribe: dictionary keys may not contain control character \\31", 2)
|
|
3834
|
+
end
|
|
3835
|
+
-- Invalid UTF-8 in a dynamic key fails the DataStore save for the entire profile.
|
|
3836
|
+
-- Rejected here so the error points at the offending index, not a later save.
|
|
3837
|
+
if type(key) == "string" and not Util.isUtf8(key) then
|
|
3838
|
+
error("Scribe: dictionary keys must be valid UTF-8", 2)
|
|
3839
|
+
end
|
|
3840
|
+
-- Fractional or non-finite numeric keys do not survive the DataStore JSON round
|
|
3841
|
+
-- trip, which would diverge the stored key from its pathKey and listeners.
|
|
3842
|
+
if type(key) == "number" and (key ~= key or key == math.huge or key == -math.huge or key % 1 ~= 0) then
|
|
3843
|
+
error(`Scribe: numeric dictionary keys must be finite integers, got {tostring(key)}`, 2)
|
|
3844
|
+
end
|
|
3845
|
+
|
|
3846
|
+
local children = rawget(accessor, F_CHILDREN) :: { [any]: any }
|
|
3847
|
+
local child = children[key]
|
|
3848
|
+
if child == nil then
|
|
3849
|
+
local schema = accessorSchema(accessor)
|
|
3850
|
+
-- Kind alone is not enough: Scribe.Big and Scribe.Flags compile as Kind
|
|
3851
|
+
-- "table" because their stored form is one, so indexing them would let
|
|
3852
|
+
-- `Tutorial[1].Set(...)` overwrite an enabled flag in place.
|
|
3853
|
+
if schema and (schema.Kind == "leaf" or schema.ValueType == "big" or schema.ValueType == "flags") then
|
|
3854
|
+
error(`Scribe: "{Util.pathString(accessorPath(accessor))}" is a leaf value and has no children`, 2)
|
|
3855
|
+
end
|
|
3856
|
+
local path = table.clone(accessorPath(accessor))
|
|
3857
|
+
table.insert(path, key)
|
|
3858
|
+
local childSchema = if schema then Template.ChildSchema(schema, key) else nil
|
|
3859
|
+
-- A declared element record has a fixed field set, so an undeclared key is a
|
|
3860
|
+
-- typo. Refusing it HERE is load-bearing: a nil child schema reads as untyped
|
|
3861
|
+
-- everywhere downstream, so a write under a misspelled field would bypass
|
|
3862
|
+
-- MaxKeys, MaxItems, MaxKeyLength and the array contiguity rule entirely.
|
|
3863
|
+
if childSchema == nil and schema and schema.Closed then
|
|
3864
|
+
error(
|
|
3865
|
+
`Scribe: "{tostring(key)}" is not a declared field of the element shape at `
|
|
3866
|
+
.. `"{Util.pathString(accessorPath(accessor))}"`,
|
|
3867
|
+
2
|
|
3868
|
+
)
|
|
3869
|
+
end
|
|
3870
|
+
-- The capability follows the HANDLE down, so Tree.Reserved.Perks.VIP may
|
|
3871
|
+
-- write and Accessor[RESERVED_ROOT].Perks.VIP may not.
|
|
3872
|
+
child = newAccessor(tree, path, childSchema, PRIVILEGED[accessor])
|
|
3873
|
+
children[key] = child
|
|
3874
|
+
end
|
|
3875
|
+
return child
|
|
3876
|
+
end
|
|
3877
|
+
|
|
3878
|
+
-- An explicit child lookup shares every indexing guard, schema lookup and cache,
|
|
3879
|
+
-- but bypasses method lookup. In particular, dictionaries may store keys such as
|
|
3880
|
+
-- "Get", "Remove" or "Child" without hiding either the method or the entry.
|
|
3881
|
+
METHOD_FACTORIES.Child = function(accessor)
|
|
3882
|
+
return function(key: string | number)
|
|
3883
|
+
return accessorIndex(accessor, key, true)
|
|
3884
|
+
end
|
|
3885
|
+
end
|
|
3886
|
+
|
|
3887
|
+
-- Callable shorthand: node() gets, node(value) sets, node(fn) updates.
|
|
3888
|
+
local function accessorCall(accessor: Accessor, ...: any): any
|
|
3889
|
+
local n = select("#", ...)
|
|
3890
|
+
if n == 0 then
|
|
3891
|
+
return accessor.Get()
|
|
3892
|
+
end
|
|
3893
|
+
local first = ...
|
|
3894
|
+
if type(first) == "function" then
|
|
3895
|
+
return accessor.Update(first, select(2, ...))
|
|
3896
|
+
end
|
|
3897
|
+
-- `node(nil, nil)` is what a generalized `for` used to produce before __iter
|
|
3898
|
+
-- existed, and it reaches Set(nil) which deletes the node. A deliberate clear is
|
|
3899
|
+
-- `node.Set(nil)` with one argument; two nils is never intentional.
|
|
3900
|
+
if n == 2 and first == nil and select(2, ...) == nil then
|
|
3901
|
+
error("Scribe: accessor(nil, nil) would delete this node; use Set(nil) if that is what you mean", 2)
|
|
3902
|
+
end
|
|
3903
|
+
return accessor.Set(...)
|
|
3904
|
+
end
|
|
3905
|
+
|
|
3906
|
+
-- Without __iter, a generalized `for` falls back to __call and invokes it as the
|
|
3907
|
+
-- iterator with two nil arguments, which reaches `accessor.Set(nil, nil)` and DELETES
|
|
3908
|
+
-- the node. The loop body never runs, so `for k, v in data.Inventory do` reads as a
|
|
3909
|
+
-- no-op and silently destroys the container, then replicates and persists the deletion.
|
|
3910
|
+
local function accessorIter(): ()
|
|
3911
|
+
error(
|
|
3912
|
+
"Scribe: an accessor is not iterable. Iterate the value instead: "
|
|
3913
|
+
.. "`for key, entry in data.Inventory.Get() do` (read-only) or `.Clone()` for a table you may edit",
|
|
3914
|
+
2
|
|
3915
|
+
)
|
|
3916
|
+
end
|
|
3917
|
+
|
|
3918
|
+
ACCESSOR_MT = {
|
|
3919
|
+
__index = accessorIndex,
|
|
3920
|
+
__call = accessorCall,
|
|
3921
|
+
__iter = accessorIter,
|
|
3922
|
+
}
|
|
3923
|
+
|
|
3924
|
+
Node.METHOD_NAMES = {} :: { [string]: boolean }
|
|
3925
|
+
for name in METHOD_FACTORIES do
|
|
3926
|
+
Node.METHOD_NAMES[name] = true
|
|
3927
|
+
end
|
|
3928
|
+
|
|
3929
|
+
-- The canonical write set, exported so a guard's spec can iterate it rather than
|
|
3930
|
+
-- hand-list it, and a mutator added later is covered without editing the spec.
|
|
3931
|
+
Node.MUTATOR_METHODS = table.freeze(MUTATOR_METHODS)
|
|
3932
|
+
|
|
3933
|
+
--- The cross-tree transaction refusal, for a writer that bypasses the accessor tree.
|
|
3934
|
+
--- Server/Timed writes the flat `_Scribe.Timed` store directly, so this export is the
|
|
3935
|
+
--- only way it can enforce the same rule with the same sentence.
|
|
3936
|
+
Node.AssertSameTreeWrite = assertSameTreeWrite
|
|
3937
|
+
|
|
3938
|
+
--- The pathKey of an accessor. Exported because the accessor's fields are keyed by
|
|
3939
|
+
--- module-private identities no other module can name.
|
|
3940
|
+
function Node.PathKeyOf(accessor: any): string
|
|
3941
|
+
return rawget(accessor, F_KEY) :: any
|
|
3942
|
+
end
|
|
3943
|
+
|
|
3944
|
+
--- The declared schema behind an accessor.
|
|
3945
|
+
function Node.SchemaOf(accessor: any): SchemaNode?
|
|
3946
|
+
return rawget(accessor, F_SCHEMA) :: any
|
|
3947
|
+
end
|
|
3948
|
+
|
|
3949
|
+
-- Deep-clone a value while unpacking every declared datatype descendant. Exposed for
|
|
3950
|
+
-- the client's Shared mirror, which stores the packed wire form but has no accessor
|
|
3951
|
+
-- tree to convert it on read.
|
|
3952
|
+
Node.CloneUnpack = cloneUnpack
|
|
3953
|
+
|
|
3954
|
+
return Node
|