@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,1283 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Buffer wire format. Transports carry opaque buffers; both sides derive an
|
|
3
|
+
-- identical schema from the shared template, so paths intern to field IDs and
|
|
4
|
+
-- values pack by declared type. A 1-byte header per value lets anything the
|
|
5
|
+
-- schema cannot describe fall back to the generic codec.
|
|
6
|
+
|
|
7
|
+
local Template = require(script.Parent.Template)
|
|
8
|
+
|
|
9
|
+
type SchemaNode = Template.SchemaNode
|
|
10
|
+
type Compiled = Template.Compiled
|
|
11
|
+
|
|
12
|
+
local Wire = {}
|
|
13
|
+
|
|
14
|
+
-- Bump on any frame layout change, even a purely additive one. The server's Hello
|
|
15
|
+
-- version check is all that stands between a mixed deploy and mis-decoded frames.
|
|
16
|
+
Wire.PROTOCOL_VERSION = 6
|
|
17
|
+
|
|
18
|
+
-- Max arguments a command frame carries. Shared so the client's encode cap and the
|
|
19
|
+
-- server's decode guard cannot drift.
|
|
20
|
+
Wire.MAX_COMMAND_ARGS = 16
|
|
21
|
+
|
|
22
|
+
-- Built-in purchase prompt request; it uses the existing Command/CommandReply layout.
|
|
23
|
+
-- A game cannot register over it and replace the server's purchase checks.
|
|
24
|
+
Wire.PURCHASE_PROMPT_COMMAND = "__scribe_prompt_purchase"
|
|
25
|
+
|
|
26
|
+
-- Max bytes in an idempotency key, enforced on both sides. It governs a Command
|
|
27
|
+
-- frame's key and the persisted Data.Purchase key, so raising it raises what a
|
|
28
|
+
-- profile can carry. The number is repeated in prose nothing binds to this line:
|
|
29
|
+
-- Client/init, Server/init and Types.luau doc-comments, plus
|
|
30
|
+
-- docgen/guides/monetization.md and docgen/guides/log-codes.md.
|
|
31
|
+
Wire.MAX_IDEMPOTENCY_KEY_BYTES = 64
|
|
32
|
+
|
|
33
|
+
Wire.Frames = {
|
|
34
|
+
Hello = 1,
|
|
35
|
+
Init = 2,
|
|
36
|
+
Diff = 3,
|
|
37
|
+
Command = 4,
|
|
38
|
+
CommandReply = 5,
|
|
39
|
+
Status = 6,
|
|
40
|
+
SharedInit = 7,
|
|
41
|
+
SharedDiff = 8,
|
|
42
|
+
SharedGone = 9,
|
|
43
|
+
Leaderboard = 10,
|
|
44
|
+
Fragment = 11,
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
local KIND_TO_ID: { [string]: number } = { Set = 1, Insert = 2, Remove = 3, Clear = 4 }
|
|
48
|
+
local ID_TO_KIND: { [number]: string } = { "Set", "Insert", "Remove", "Clear" }
|
|
49
|
+
|
|
50
|
+
local FLAG_VALUE = 0x10
|
|
51
|
+
local FLAG_INDEX = 0x20
|
|
52
|
+
|
|
53
|
+
-- Writer ----------------------------------------------------------------------
|
|
54
|
+
|
|
55
|
+
export type Writer = {
|
|
56
|
+
buf: buffer,
|
|
57
|
+
len: number,
|
|
58
|
+
cap: number,
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function Wire.NewWriter(capacity: number?): Writer
|
|
62
|
+
local cap = capacity or 128
|
|
63
|
+
return { buf = buffer.create(cap), len = 0, cap = cap }
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
local function ensure(w: Writer, n: number)
|
|
67
|
+
if w.len + n <= w.cap then
|
|
68
|
+
return
|
|
69
|
+
end
|
|
70
|
+
local newCap = math.max(w.cap * 2, w.len + n)
|
|
71
|
+
local newBuf = buffer.create(newCap)
|
|
72
|
+
buffer.copy(newBuf, 0, w.buf, 0, w.len)
|
|
73
|
+
w.buf = newBuf
|
|
74
|
+
w.cap = newCap
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
local function wu8(w: Writer, v: number)
|
|
78
|
+
ensure(w, 1)
|
|
79
|
+
buffer.writeu8(w.buf, w.len, v)
|
|
80
|
+
w.len += 1
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
local function wu16(w: Writer, v: number)
|
|
84
|
+
ensure(w, 2)
|
|
85
|
+
buffer.writeu16(w.buf, w.len, v)
|
|
86
|
+
w.len += 2
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
local function wu32(w: Writer, v: number)
|
|
90
|
+
ensure(w, 4)
|
|
91
|
+
buffer.writeu32(w.buf, w.len, v)
|
|
92
|
+
w.len += 4
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
local function wf64(w: Writer, v: number)
|
|
96
|
+
ensure(w, 8)
|
|
97
|
+
buffer.writef64(w.buf, w.len, v)
|
|
98
|
+
w.len += 8
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
-- Only reached for a value canSchemaEncode has already proved binary32 can hold
|
|
102
|
+
-- within the declared error bound.
|
|
103
|
+
local function wf32(w: Writer, v: number)
|
|
104
|
+
ensure(w, 4)
|
|
105
|
+
buffer.writef32(w.buf, w.len, v)
|
|
106
|
+
w.len += 4
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
-- Largest value the writer will encode. A Luau number is only an exact integer to
|
|
110
|
+
-- 2^53; past it the arithmetic below loses digits the reader cannot recover.
|
|
111
|
+
local MAX_VARINT = 2 ^ 53
|
|
112
|
+
|
|
113
|
+
-- Unsigned LEB128; arithmetic (not bit32) so values up to 2^53 round-trip.
|
|
114
|
+
local function wvarint(w: Writer, v: number)
|
|
115
|
+
-- Refuse rather than loop: math.floor(inf) is inf, so a non-finite input grows
|
|
116
|
+
-- the buffer until the process dies, and a negative wraps writeu8 into garbage.
|
|
117
|
+
if v ~= v or v == math.huge or v == -math.huge or v < 0 or v > MAX_VARINT then
|
|
118
|
+
error(`Scribe: cannot encode {tostring(v)} as a varint (expected an integer from 0 to 2^53)`, 0)
|
|
119
|
+
end
|
|
120
|
+
v = math.floor(v)
|
|
121
|
+
while v >= 128 do
|
|
122
|
+
wu8(w, v % 128 + 128)
|
|
123
|
+
v = math.floor(v / 128)
|
|
124
|
+
end
|
|
125
|
+
wu8(w, v)
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
local function wzigzag(w: Writer, v: number)
|
|
129
|
+
wvarint(w, if v >= 0 then v * 2 else -v * 2 - 1)
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
local function wstr(w: Writer, s: string)
|
|
133
|
+
wvarint(w, #s)
|
|
134
|
+
ensure(w, #s)
|
|
135
|
+
buffer.writestring(w.buf, w.len, s)
|
|
136
|
+
w.len += #s
|
|
137
|
+
end
|
|
138
|
+
|
|
139
|
+
local function wbuf(w: Writer, value: buffer)
|
|
140
|
+
local length = buffer.len(value)
|
|
141
|
+
wvarint(w, length)
|
|
142
|
+
ensure(w, length)
|
|
143
|
+
buffer.copy(w.buf, w.len, value)
|
|
144
|
+
w.len += length
|
|
145
|
+
end
|
|
146
|
+
|
|
147
|
+
function Wire.Finish(w: Writer): buffer
|
|
148
|
+
local out = buffer.create(w.len)
|
|
149
|
+
buffer.copy(out, 0, w.buf, 0, w.len)
|
|
150
|
+
return out
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
Wire.U8 = wu8
|
|
154
|
+
Wire.U16 = wu16
|
|
155
|
+
Wire.U32 = wu32
|
|
156
|
+
Wire.F64 = wf64
|
|
157
|
+
Wire.Varint = wvarint
|
|
158
|
+
Wire.Str = wstr
|
|
159
|
+
|
|
160
|
+
-- Reader ----------------------------------------------------------------------
|
|
161
|
+
|
|
162
|
+
export type Reader = {
|
|
163
|
+
buf: buffer,
|
|
164
|
+
pos: number,
|
|
165
|
+
size: number,
|
|
166
|
+
-- Remaining allocations this frame may still produce, nil for unlimited.
|
|
167
|
+
budget: number?,
|
|
168
|
+
-- Set when the budget ran out, so the caller can tell "too expensive" from
|
|
169
|
+
-- "malformed" without matching on error text a crafted frame controls.
|
|
170
|
+
overBudget: boolean?,
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
--- A reader over `buf`. `retainBudget` caps how many bytes the decoder may retain
|
|
174
|
+
--- from this frame, modelled per object; nil means unlimited.
|
|
175
|
+
---
|
|
176
|
+
--- Caller-supplied on purpose: the same decoder runs on the client over Init
|
|
177
|
+
--- frames the size of a whole profile, so a module-level budget would refuse a
|
|
178
|
+
--- legitimate snapshot. Only the server's untrusted inbound path passes one.
|
|
179
|
+
function Wire.NewReader(buf: buffer, retainBudget: number?): Reader
|
|
180
|
+
return { buf = buf, pos = 0, size = buffer.len(buf), budget = retainBudget }
|
|
181
|
+
end
|
|
182
|
+
|
|
183
|
+
local function ru8(r: Reader): number
|
|
184
|
+
local v = buffer.readu8(r.buf, r.pos)
|
|
185
|
+
r.pos += 1
|
|
186
|
+
return v
|
|
187
|
+
end
|
|
188
|
+
|
|
189
|
+
local function ru16(r: Reader): number
|
|
190
|
+
local v = buffer.readu16(r.buf, r.pos)
|
|
191
|
+
r.pos += 2
|
|
192
|
+
return v
|
|
193
|
+
end
|
|
194
|
+
|
|
195
|
+
local function ru32(r: Reader): number
|
|
196
|
+
local v = buffer.readu32(r.buf, r.pos)
|
|
197
|
+
r.pos += 4
|
|
198
|
+
return v
|
|
199
|
+
end
|
|
200
|
+
|
|
201
|
+
local function rf64(r: Reader): number
|
|
202
|
+
local v = buffer.readf64(r.buf, r.pos)
|
|
203
|
+
r.pos += 8
|
|
204
|
+
return v
|
|
205
|
+
end
|
|
206
|
+
|
|
207
|
+
local function rf32(r: Reader): number
|
|
208
|
+
local v = buffer.readf32(r.buf, r.pos)
|
|
209
|
+
r.pos += 4
|
|
210
|
+
return v
|
|
211
|
+
end
|
|
212
|
+
|
|
213
|
+
local function rvarint(r: Reader): number
|
|
214
|
+
local result = 0
|
|
215
|
+
local multiplier = 1
|
|
216
|
+
-- 10 groups = 70 bits. A valid varint never exceeds ~8 groups; the extra
|
|
217
|
+
-- headroom just bounds a malicious one.
|
|
218
|
+
for _ = 1, 10 do
|
|
219
|
+
local byte = ru8(r)
|
|
220
|
+
result += (byte % 128) * multiplier
|
|
221
|
+
if byte < 128 then
|
|
222
|
+
return result
|
|
223
|
+
end
|
|
224
|
+
multiplier *= 128
|
|
225
|
+
end
|
|
226
|
+
error("Scribe: varint too long")
|
|
227
|
+
end
|
|
228
|
+
|
|
229
|
+
local function rzigzag(r: Reader): number
|
|
230
|
+
local v = rvarint(r)
|
|
231
|
+
if v % 2 == 0 then
|
|
232
|
+
return v / 2
|
|
233
|
+
end
|
|
234
|
+
return -(v + 1) / 2
|
|
235
|
+
end
|
|
236
|
+
|
|
237
|
+
-- What one decoded object retains, in bytes. Denominated in bytes rather than
|
|
238
|
+
-- object counts because an array slot costs the same whether it holds `true` or a
|
|
239
|
+
-- string pointer, while the two differ 2.5x in input bytes. Rounded up, and the two
|
|
240
|
+
-- Luau grows by doubling are counted at twice their unit size.
|
|
241
|
+
local SLOT_BYTES = 32 -- a 16-byte TValue, doubled for power-of-two array growth
|
|
242
|
+
local TABLE_BYTES = 64 -- the Table struct, ~56, rounded
|
|
243
|
+
local HASH_BYTES = 64 -- a 32-byte LuaNode, doubled for power-of-two node growth
|
|
244
|
+
local STRING_BYTES = 24 -- TString header, excluding the payload
|
|
245
|
+
local BUFFER_BYTES = 24 -- Buffer header, excluding the payload
|
|
246
|
+
|
|
247
|
+
-- The default budget of MaxInboundBytes * 16 (Replication.luau) is a ceiling, not
|
|
248
|
+
-- a per-byte figure: a nested empty table costs the sender two bytes and retains a
|
|
249
|
+
-- whole Table struct on top of the slot holding it, so table-valued elements
|
|
250
|
+
-- amplify well past 16:1 (WireBitmask.spec pins each path's worst case). Nothing
|
|
251
|
+
-- untrusted reaches the schema-typed decoder today; re-derive the multiplier from
|
|
252
|
+
-- those figures before one does.
|
|
253
|
+
|
|
254
|
+
-- Charge what one decoded object will retain, refusing the frame when the budget
|
|
255
|
+
-- runs out. Depth alone does not bound this: a flat table of four thousand empty
|
|
256
|
+
-- buffers is depth 1 and two bytes each. Raises rather than returning early, since
|
|
257
|
+
-- everything downstream assumes a failed decode discards the whole frame.
|
|
258
|
+
local function charge(r: Reader, bytes: number)
|
|
259
|
+
local left = r.budget
|
|
260
|
+
if left == nil then
|
|
261
|
+
return
|
|
262
|
+
end
|
|
263
|
+
if left < bytes then
|
|
264
|
+
r.overBudget = true
|
|
265
|
+
error("Scribe: inbound frame exceeded its retention budget")
|
|
266
|
+
end
|
|
267
|
+
r.budget = left - bytes
|
|
268
|
+
end
|
|
269
|
+
|
|
270
|
+
--- Read a string, refusing it from its length prefix instead of after the fact: a
|
|
271
|
+
--- cap applied to the result has already paid for the allocation.
|
|
272
|
+
local function rstrBounded(r: Reader, maxBytes: number): string
|
|
273
|
+
local len = rvarint(r)
|
|
274
|
+
if len > maxBytes then
|
|
275
|
+
error(`Scribe: string field of {len} bytes exceeds its {maxBytes}-byte limit`)
|
|
276
|
+
end
|
|
277
|
+
if r.pos + len > r.size then
|
|
278
|
+
error("Scribe: string overruns buffer")
|
|
279
|
+
end
|
|
280
|
+
local s = buffer.readstring(r.buf, r.pos, len)
|
|
281
|
+
r.pos += len
|
|
282
|
+
return s
|
|
283
|
+
end
|
|
284
|
+
|
|
285
|
+
--- `headerBytes` is the fixed per-object overhead charged against the frame's
|
|
286
|
+
--- retention budget, plus the payload length taken from the length prefix. Omitted
|
|
287
|
+
--- by callers not decoding untrusted generic data.
|
|
288
|
+
local function rstr(r: Reader, headerBytes: number?): string
|
|
289
|
+
local len = rvarint(r)
|
|
290
|
+
if headerBytes ~= nil then
|
|
291
|
+
charge(r, headerBytes + len)
|
|
292
|
+
end
|
|
293
|
+
if r.pos + len > r.size then
|
|
294
|
+
error("Scribe: string overruns buffer")
|
|
295
|
+
end
|
|
296
|
+
local s = buffer.readstring(r.buf, r.pos, len)
|
|
297
|
+
r.pos += len
|
|
298
|
+
return s
|
|
299
|
+
end
|
|
300
|
+
|
|
301
|
+
local function rbuf(r: Reader, headerBytes: number?): buffer
|
|
302
|
+
local length = rvarint(r)
|
|
303
|
+
if headerBytes ~= nil then
|
|
304
|
+
charge(r, headerBytes + length)
|
|
305
|
+
end
|
|
306
|
+
if r.pos + length > r.size then
|
|
307
|
+
error("Scribe: buffer overruns frame")
|
|
308
|
+
end
|
|
309
|
+
local out = buffer.create(length)
|
|
310
|
+
buffer.copy(out, 0, r.buf, r.pos, length)
|
|
311
|
+
r.pos += length
|
|
312
|
+
return out
|
|
313
|
+
end
|
|
314
|
+
|
|
315
|
+
Wire.RU8 = ru8
|
|
316
|
+
Wire.RU16 = ru16
|
|
317
|
+
Wire.RU32 = ru32
|
|
318
|
+
Wire.RF64 = rf64
|
|
319
|
+
Wire.RVarint = rvarint
|
|
320
|
+
Wire.RStr = rstr
|
|
321
|
+
Wire.RStrBounded = rstrBounded
|
|
322
|
+
|
|
323
|
+
function Wire.Remaining(r: Reader): number
|
|
324
|
+
return r.size - r.pos
|
|
325
|
+
end
|
|
326
|
+
|
|
327
|
+
-- Generic tagged value codec ---------------------------------------------------
|
|
328
|
+
|
|
329
|
+
local TAG_NIL, TAG_FALSE, TAG_TRUE, TAG_NUMBER, TAG_STRING, TAG_TABLE, TAG_BUFFER = 0, 1, 2, 3, 4, 5, 6
|
|
330
|
+
|
|
331
|
+
local function encodeGeneric(w: Writer, value: any, depth: number)
|
|
332
|
+
if depth > 24 then
|
|
333
|
+
error("Scribe: value too deep to serialize")
|
|
334
|
+
end
|
|
335
|
+
local t = type(value)
|
|
336
|
+
if value == nil then
|
|
337
|
+
wu8(w, TAG_NIL)
|
|
338
|
+
elseif t == "boolean" then
|
|
339
|
+
wu8(w, if value then TAG_TRUE else TAG_FALSE)
|
|
340
|
+
elseif t == "number" then
|
|
341
|
+
wu8(w, TAG_NUMBER)
|
|
342
|
+
wf64(w, value)
|
|
343
|
+
elseif t == "string" then
|
|
344
|
+
wu8(w, TAG_STRING)
|
|
345
|
+
wstr(w, value)
|
|
346
|
+
elseif t == "buffer" then
|
|
347
|
+
wu8(w, TAG_BUFFER)
|
|
348
|
+
wbuf(w, value)
|
|
349
|
+
elseif t == "table" then
|
|
350
|
+
wu8(w, TAG_TABLE)
|
|
351
|
+
-- Contiguous array part, then hash part.
|
|
352
|
+
local arrayLen = 0
|
|
353
|
+
while (value :: any)[arrayLen + 1] ~= nil do
|
|
354
|
+
arrayLen += 1
|
|
355
|
+
end
|
|
356
|
+
wvarint(w, arrayLen)
|
|
357
|
+
for i = 1, arrayLen do
|
|
358
|
+
encodeGeneric(w, value[i], depth + 1)
|
|
359
|
+
end
|
|
360
|
+
local hashCount = 0
|
|
361
|
+
for k in value do
|
|
362
|
+
if not (type(k) == "number" and k % 1 == 0 and k >= 1 and k <= arrayLen) then
|
|
363
|
+
hashCount += 1
|
|
364
|
+
end
|
|
365
|
+
end
|
|
366
|
+
wvarint(w, hashCount)
|
|
367
|
+
for k, v in value do
|
|
368
|
+
if not (type(k) == "number" and k % 1 == 0 and k >= 1 and k <= arrayLen) then
|
|
369
|
+
encodeGeneric(w, k, depth + 1)
|
|
370
|
+
encodeGeneric(w, v, depth + 1)
|
|
371
|
+
end
|
|
372
|
+
end
|
|
373
|
+
else
|
|
374
|
+
error(`Scribe: cannot serialize value of type "{t}"`)
|
|
375
|
+
end
|
|
376
|
+
end
|
|
377
|
+
|
|
378
|
+
local function decodeGeneric(r: Reader, depth: number): any
|
|
379
|
+
if depth > 24 then
|
|
380
|
+
error("Scribe: value too deep to deserialize")
|
|
381
|
+
end
|
|
382
|
+
local tag = ru8(r)
|
|
383
|
+
if tag == TAG_NIL then
|
|
384
|
+
return nil
|
|
385
|
+
elseif tag == TAG_FALSE then
|
|
386
|
+
return false
|
|
387
|
+
elseif tag == TAG_TRUE then
|
|
388
|
+
return true
|
|
389
|
+
elseif tag == TAG_NUMBER then
|
|
390
|
+
return rf64(r)
|
|
391
|
+
elseif tag == TAG_STRING then
|
|
392
|
+
return rstr(r, STRING_BYTES)
|
|
393
|
+
elseif tag == TAG_BUFFER then
|
|
394
|
+
return rbuf(r, BUFFER_BYTES)
|
|
395
|
+
elseif tag == TAG_TABLE then
|
|
396
|
+
charge(r, TABLE_BYTES)
|
|
397
|
+
local out = {}
|
|
398
|
+
local arrayLen = rvarint(r)
|
|
399
|
+
for i = 1, arrayLen do
|
|
400
|
+
-- Charged per slot, not just per table: a table of N booleans would
|
|
401
|
+
-- otherwise cost one charge while allocating N slots, at one byte each.
|
|
402
|
+
-- Charged before the recursive decode so the refusal precedes it.
|
|
403
|
+
charge(r, SLOT_BYTES)
|
|
404
|
+
out[i] = decodeGeneric(r, depth + 1)
|
|
405
|
+
end
|
|
406
|
+
local hashCount = rvarint(r)
|
|
407
|
+
for _ = 1, hashCount do
|
|
408
|
+
-- Same reasoning; a hash pair costs at least as much as an array slot.
|
|
409
|
+
charge(r, HASH_BYTES)
|
|
410
|
+
local k = decodeGeneric(r, depth + 1)
|
|
411
|
+
local v = decodeGeneric(r, depth + 1)
|
|
412
|
+
if k ~= nil and k == k then
|
|
413
|
+
out[k] = v
|
|
414
|
+
end
|
|
415
|
+
end
|
|
416
|
+
return out
|
|
417
|
+
end
|
|
418
|
+
error(`Scribe: unknown generic tag {tag}`)
|
|
419
|
+
end
|
|
420
|
+
|
|
421
|
+
function Wire.EncodeGeneric(w: Writer, value: any)
|
|
422
|
+
encodeGeneric(w, value, 0)
|
|
423
|
+
end
|
|
424
|
+
|
|
425
|
+
function Wire.DecodeGeneric(r: Reader): any
|
|
426
|
+
return decodeGeneric(r, 0)
|
|
427
|
+
end
|
|
428
|
+
|
|
429
|
+
-- Schema-typed value codec -------------------------------------------------------
|
|
430
|
+
|
|
431
|
+
-- The value header byte, in front of every encoded value.
|
|
432
|
+
-- bits 0-1 mode: GENERIC (the schema cannot describe it; self-describing codec),
|
|
433
|
+
-- DENSE (keys exactly 1..n; values positional, no key), STATIC (all declared
|
|
434
|
+
-- children; a presence bitmask over ChildOrder, then values in order), or
|
|
435
|
+
-- TAGGED (the fallback, and the only mode that can carry an unknown key).
|
|
436
|
+
-- bits 2-3 key tag, present only for an entry of a tagged table.
|
|
437
|
+
-- bits 4-7 reserved and refused: a set bit is a drifted encoder or a crafted frame.
|
|
438
|
+
-- A standalone header is 0..3 and a table entry's 0..15. DENSE and STATIC are refused on
|
|
439
|
+
-- a non-table node, which the scalar readers would otherwise accept in silence.
|
|
440
|
+
local VH_TAGGED = 0x00
|
|
441
|
+
local VH_GENERIC = 0x01
|
|
442
|
+
local VH_DENSE = 0x02
|
|
443
|
+
local VH_STATIC = 0x03
|
|
444
|
+
-- The key tag lives in bits 2-3, so it is scaled by 4 rather than shifted, which
|
|
445
|
+
-- makes VH_KEY_SCALE double as the modulus that extracts the mode. Bit work here
|
|
446
|
+
-- is arithmetic so that nothing depends on 32-bit truncation.
|
|
447
|
+
local VH_KEY_SCALE = 4
|
|
448
|
+
local VH_ENTRY_MAX = 16 -- one past the largest legal table-entry header
|
|
449
|
+
local VH_VALUE_MAX = 4 -- one past the largest legal standalone value header
|
|
450
|
+
|
|
451
|
+
local function intWidth(node: SchemaNode): number?
|
|
452
|
+
if node.Min ~= nil and node.Max ~= nil then
|
|
453
|
+
local range = node.Max - node.Min
|
|
454
|
+
if range < 256 then
|
|
455
|
+
return 1
|
|
456
|
+
elseif range < 65536 then
|
|
457
|
+
return 2
|
|
458
|
+
elseif range < 4294967296 then
|
|
459
|
+
return 4
|
|
460
|
+
end
|
|
461
|
+
end
|
|
462
|
+
return nil
|
|
463
|
+
end
|
|
464
|
+
|
|
465
|
+
-- Narrowed floats. The plan, the constants and the step count come from Template,
|
|
466
|
+
-- so the compiler, the encoder and the decoder share one derivation.
|
|
467
|
+
local FLOAT_F64 = Template.FLOAT_F64
|
|
468
|
+
local FLOAT_F32 = Template.FLOAT_F32
|
|
469
|
+
local FLOAT_Q8 = Template.FLOAT_Q8
|
|
470
|
+
local FLOAT_Q16 = Template.FLOAT_Q16
|
|
471
|
+
-- FLOAT_Q32 is deliberately absent: it is the fall-through plan in both the
|
|
472
|
+
-- encoder and the decoder below.
|
|
473
|
+
local F32_MAX = Template.F32_MAX
|
|
474
|
+
local F32_MIN_NORMAL = Template.F32_MIN_NORMAL
|
|
475
|
+
local floatPlan = Template.FloatPlan
|
|
476
|
+
|
|
477
|
+
--- The grid index of `v` on this node's fixed-point grid, rounded to nearest.
|
|
478
|
+
--- Truncating instead would double the worst-case error and bias it, so a quantized
|
|
479
|
+
--- field would drift downward over repeated round trips.
|
|
480
|
+
---
|
|
481
|
+
--- The clamp is unreachable while canSchemaEncode holds, and stays: without it a
|
|
482
|
+
--- value just past Max reaches buffer.writeu8 as 256, wraps, and comes back as Min.
|
|
483
|
+
local function quantIndex(node: SchemaNode, v: number, steps: number): number
|
|
484
|
+
local q = math.floor((v - (node.Min :: number)) / (node.Precision :: number) + 0.5)
|
|
485
|
+
if q < 0 then
|
|
486
|
+
return 0
|
|
487
|
+
elseif q > steps then
|
|
488
|
+
return steps
|
|
489
|
+
end
|
|
490
|
+
return q
|
|
491
|
+
end
|
|
492
|
+
|
|
493
|
+
--- The grid point `q` names, clamped to Max.
|
|
494
|
+
---
|
|
495
|
+
--- Not about crafted frames: `steps` is ceil((Max - Min)/Precision), so when
|
|
496
|
+
--- Precision does not divide the range the top index sits one grid point past Max
|
|
497
|
+
--- and quantIndex rounds Max itself onto it. Min=0, Max=100, Precision=0.6 gives
|
|
498
|
+
--- 167 steps and 167*0.6 = 100.2 for a legal, in-range 100. The int path has no
|
|
499
|
+
--- legitimate overshoot to correct. Max is never nil here: a numeric Precision
|
|
500
|
+
--- requires both bounds.
|
|
501
|
+
local function quantValue(node: SchemaNode, q: number): number
|
|
502
|
+
local v = (node.Min :: number) + q * (node.Precision :: number)
|
|
503
|
+
local max = node.Max :: number
|
|
504
|
+
if v > max then
|
|
505
|
+
return max
|
|
506
|
+
end
|
|
507
|
+
return v
|
|
508
|
+
end
|
|
509
|
+
|
|
510
|
+
local function canSchemaEncode(node: SchemaNode, value: any): boolean
|
|
511
|
+
local vt = node.ValueType
|
|
512
|
+
if vt == "boolean" then
|
|
513
|
+
return type(value) == "boolean"
|
|
514
|
+
elseif vt == "int" then
|
|
515
|
+
if type(value) ~= "number" or value % 1 ~= 0 then
|
|
516
|
+
return false
|
|
517
|
+
end
|
|
518
|
+
-- Beyond 2^52 the varint/zigzag arithmetic loses precision; fall back
|
|
519
|
+
-- to the generic f64 path, which round-trips any finite double.
|
|
520
|
+
if value > 0x10000000000000 or value < -0x10000000000000 then
|
|
521
|
+
return false
|
|
522
|
+
end
|
|
523
|
+
if node.Min ~= nil and node.Max ~= nil then
|
|
524
|
+
return value >= node.Min and value <= node.Max
|
|
525
|
+
end
|
|
526
|
+
if node.Min ~= nil and node.Min >= 0 then
|
|
527
|
+
return value >= 0
|
|
528
|
+
end
|
|
529
|
+
return true
|
|
530
|
+
elseif vt == "number" then
|
|
531
|
+
if type(value) ~= "number" then
|
|
532
|
+
return false
|
|
533
|
+
end
|
|
534
|
+
local plan = floatPlan(node)
|
|
535
|
+
if plan == FLOAT_F64 then
|
|
536
|
+
-- The default, and the only arm an undeclared Scribe.Number reaches: any
|
|
537
|
+
-- double at all, NaN and both infinities included.
|
|
538
|
+
return true
|
|
539
|
+
end
|
|
540
|
+
-- Narrowed, so the tests below are the precision guarantee: anything outside
|
|
541
|
+
-- the stated error bound is refused here and takes the generic path, where it
|
|
542
|
+
-- round-trips as an exact f64. NaN and the infinities fall out of the same
|
|
543
|
+
-- comparisons.
|
|
544
|
+
if plan == FLOAT_F32 then
|
|
545
|
+
local magnitude = math.abs(value)
|
|
546
|
+
-- Zero is exact in binary32. Above F32_MAX the nearest binary32 is
|
|
547
|
+
-- infinity; below F32_MIN_NORMAL the relative error blows past the 2^-24
|
|
548
|
+
-- the width promises.
|
|
549
|
+
return magnitude == 0 or (magnitude >= F32_MIN_NORMAL and magnitude <= F32_MAX)
|
|
550
|
+
end
|
|
551
|
+
-- Fixed-point. The grid only exists between the declared bounds, and both are
|
|
552
|
+
-- finite, so this also rejects the infinities and NaN.
|
|
553
|
+
return value >= (node.Min :: number) and value <= (node.Max :: number)
|
|
554
|
+
elseif vt == "enum" then
|
|
555
|
+
return type(value) == "string" and node.MemberIndex ~= nil and node.MemberIndex[value] ~= nil
|
|
556
|
+
elseif vt == "big" then
|
|
557
|
+
return type(value) == "table" and type(value[1]) == "number" and type(value[2]) == "number"
|
|
558
|
+
elseif vt == "flags" then
|
|
559
|
+
if type(value) ~= "table" or node.MemberIndex == nil then
|
|
560
|
+
return false
|
|
561
|
+
end
|
|
562
|
+
for _, name in value :: { any } do
|
|
563
|
+
if type(name) ~= "string" or node.MemberIndex[name] == nil then
|
|
564
|
+
return false
|
|
565
|
+
end
|
|
566
|
+
end
|
|
567
|
+
return true
|
|
568
|
+
elseif vt == "string" then
|
|
569
|
+
return type(value) == "string"
|
|
570
|
+
elseif vt == "buffer" or vt == "datatype" then
|
|
571
|
+
-- Datatype fields store (and travel as) their packed buffer form.
|
|
572
|
+
return type(value) == "buffer"
|
|
573
|
+
elseif vt == "table" then
|
|
574
|
+
return type(value) == "table"
|
|
575
|
+
end
|
|
576
|
+
return false
|
|
577
|
+
end
|
|
578
|
+
|
|
579
|
+
local TAG_KEY_STATIC, TAG_KEY_STRING, TAG_KEY_UINT, TAG_KEY_F64 = 0, 1, 2, 3
|
|
580
|
+
|
|
581
|
+
--- Whether `value`'s keys are exactly 1..count, so its body can be written
|
|
582
|
+
--- positionally. The only thing that may set the dense bit.
|
|
583
|
+
---
|
|
584
|
+
--- `#value == count` is not equivalent: `#` on a holey table may return either
|
|
585
|
+
--- boundary, so `{[1]=1,[3]=3}` can answer 3 and would be written as three
|
|
586
|
+
--- positional values and read back as a different table. Probing every index costs
|
|
587
|
+
--- O(count) against an iteration that is already O(count).
|
|
588
|
+
local function isDenseArray(value: any, count: number): boolean
|
|
589
|
+
if count == 0 then
|
|
590
|
+
-- An empty table is trivially dense, but the flag saves nothing and costs
|
|
591
|
+
-- the decoder a shape it need not model.
|
|
592
|
+
return false
|
|
593
|
+
end
|
|
594
|
+
for i = 1, count do
|
|
595
|
+
if value[i] == nil then
|
|
596
|
+
return false
|
|
597
|
+
end
|
|
598
|
+
end
|
|
599
|
+
return true
|
|
600
|
+
end
|
|
601
|
+
|
|
602
|
+
--- The number of bytes wvarint spends on `v`, for comparing two candidate
|
|
603
|
+
--- encodings before either is written.
|
|
604
|
+
local function varintLen(v: number): number
|
|
605
|
+
local n = 1
|
|
606
|
+
while v >= 128 do
|
|
607
|
+
v = math.floor(v / 128)
|
|
608
|
+
n += 1
|
|
609
|
+
end
|
|
610
|
+
return n
|
|
611
|
+
end
|
|
612
|
+
|
|
613
|
+
--- Whether every key of `value` is a static child `node` declares, and whether a
|
|
614
|
+
--- presence bitmask costs fewer bytes than tagging each key. The only thing that
|
|
615
|
+
--- may set the static mode.
|
|
616
|
+
---
|
|
617
|
+
--- The test is over the table's keys, not the schema's: walking ChildOrder instead
|
|
618
|
+
--- and finding every declared child present would pass a table that also carried
|
|
619
|
+
--- undeclared keys, and those would vanish from the frame in silence. No
|
|
620
|
+
--- empty-table guard is needed, unlike isDenseArray: no mask fits in fewer than
|
|
621
|
+
--- two bytes, so the cost comparison below already refuses one.
|
|
622
|
+
local function isStaticStruct(node: SchemaNode, value: any, count: number): boolean
|
|
623
|
+
local children = node.Children
|
|
624
|
+
local order = node.ChildOrder
|
|
625
|
+
if children == nil or order == nil then
|
|
626
|
+
return false
|
|
627
|
+
end
|
|
628
|
+
-- Unreachable for a compiled node that has Children, but it is the precondition
|
|
629
|
+
-- the encoder's `math.ceil(declared / 8) - 1` loop bound depends on.
|
|
630
|
+
local declared = #order
|
|
631
|
+
if declared == 0 then
|
|
632
|
+
return false
|
|
633
|
+
end
|
|
634
|
+
for k in value do
|
|
635
|
+
if type(k) ~= "string" or children[k] == nil then
|
|
636
|
+
return false
|
|
637
|
+
end
|
|
638
|
+
end
|
|
639
|
+
-- Static spends a width varint plus the mask; tagged spends a count varint plus
|
|
640
|
+
-- one ordinal varint per entry. Header and payload per field cancel. A tie goes
|
|
641
|
+
-- to tagged.
|
|
642
|
+
local staticBytes = varintLen(declared) + math.ceil(declared / 8)
|
|
643
|
+
local taggedBytes = varintLen(count) + count
|
|
644
|
+
return staticBytes < taggedBytes
|
|
645
|
+
end
|
|
646
|
+
|
|
647
|
+
--- The header bits for `value` under `node`, the node its payload is written
|
|
648
|
+
--- against (nil means the generic codec), and a table's entry count, so the payload
|
|
649
|
+
--- writer need not walk it again.
|
|
650
|
+
---
|
|
651
|
+
--- Split out because a table entry writes its key between the header and the
|
|
652
|
+
--- payload: returning the bits lets the caller fold in the key tag and emit one byte.
|
|
653
|
+
local function valueHeaderBits(node: SchemaNode?, value: any): (number, SchemaNode?, number)
|
|
654
|
+
if node == nil or not canSchemaEncode(node, value) then
|
|
655
|
+
return VH_GENERIC, nil, 0
|
|
656
|
+
end
|
|
657
|
+
if node.ValueType == "table" then
|
|
658
|
+
local count = 0
|
|
659
|
+
for _ in value do
|
|
660
|
+
count += 1
|
|
661
|
+
end
|
|
662
|
+
if isDenseArray(value, count) then
|
|
663
|
+
return VH_DENSE, node, count
|
|
664
|
+
end
|
|
665
|
+
if isStaticStruct(node, value, count) then
|
|
666
|
+
return VH_STATIC, node, count
|
|
667
|
+
end
|
|
668
|
+
return VH_TAGGED, node, count
|
|
669
|
+
end
|
|
670
|
+
return VH_TAGGED, node, 0
|
|
671
|
+
end
|
|
672
|
+
|
|
673
|
+
local encodeValuePayload: (Writer, SchemaNode?, any, number, number, number) -> ()
|
|
674
|
+
|
|
675
|
+
--- Writes the value header (with no key tag; see the entry loop for the folded
|
|
676
|
+
--- form) and then the payload.
|
|
677
|
+
local function encodeValue(w: Writer, node: SchemaNode?, value: any, depth: number)
|
|
678
|
+
local bits, target, count = valueHeaderBits(node, value)
|
|
679
|
+
wu8(w, bits)
|
|
680
|
+
encodeValuePayload(w, target, value, depth, bits, count)
|
|
681
|
+
end
|
|
682
|
+
|
|
683
|
+
--- `bits` and `count` come from valueHeaderBits rather than being recomputed: the
|
|
684
|
+
--- header is already written, so the mode here has to be the one it announced.
|
|
685
|
+
function encodeValuePayload(w: Writer, node: SchemaNode?, value: any, depth: number, bits: number, count: number)
|
|
686
|
+
if node == nil then
|
|
687
|
+
encodeGeneric(w, value, depth)
|
|
688
|
+
return
|
|
689
|
+
end
|
|
690
|
+
local vt = node.ValueType
|
|
691
|
+
if vt == "boolean" then
|
|
692
|
+
wu8(w, if value then 1 else 0)
|
|
693
|
+
elseif vt == "int" then
|
|
694
|
+
local width = intWidth(node)
|
|
695
|
+
if width == 1 then
|
|
696
|
+
wu8(w, value - (node.Min :: number))
|
|
697
|
+
elseif width == 2 then
|
|
698
|
+
wu16(w, value - (node.Min :: number))
|
|
699
|
+
elseif width == 4 then
|
|
700
|
+
wu32(w, value - (node.Min :: number))
|
|
701
|
+
elseif node.Min ~= nil and node.Min >= 0 then
|
|
702
|
+
wvarint(w, value)
|
|
703
|
+
else
|
|
704
|
+
wzigzag(w, value)
|
|
705
|
+
end
|
|
706
|
+
elseif vt == "number" then
|
|
707
|
+
local plan = floatPlan(node)
|
|
708
|
+
if plan == FLOAT_F64 then
|
|
709
|
+
wf64(w, value)
|
|
710
|
+
elseif plan == FLOAT_F32 then
|
|
711
|
+
wf32(w, value)
|
|
712
|
+
else
|
|
713
|
+
local steps = Template.QuantSteps(node.Min :: number, node.Max :: number, node.Precision :: number)
|
|
714
|
+
local q = quantIndex(node, value, steps)
|
|
715
|
+
if plan == FLOAT_Q8 then
|
|
716
|
+
wu8(w, q)
|
|
717
|
+
elseif plan == FLOAT_Q16 then
|
|
718
|
+
wu16(w, q)
|
|
719
|
+
else
|
|
720
|
+
wu32(w, q) -- FLOAT_Q32
|
|
721
|
+
end
|
|
722
|
+
end
|
|
723
|
+
elseif vt == "enum" then
|
|
724
|
+
wu8(w, (node.MemberIndex :: { [string]: number })[value])
|
|
725
|
+
elseif vt == "big" then
|
|
726
|
+
-- The mantissa needs full double precision; the exponent is a small signed
|
|
727
|
+
-- integer, so a zigzag varint is one or two bytes for any realistic value.
|
|
728
|
+
wf64(w, value[1])
|
|
729
|
+
wzigzag(w, value[2])
|
|
730
|
+
elseif vt == "flags" then
|
|
731
|
+
-- One bit per declared member, LSB = first member. Positional only within a
|
|
732
|
+
-- frame; the stored form is the member names.
|
|
733
|
+
local index = node.MemberIndex :: { [string]: number }
|
|
734
|
+
local mask = 0
|
|
735
|
+
for _, name in value :: { string } do
|
|
736
|
+
-- MemberIndex is 0-based, so the first member owns bit 0.
|
|
737
|
+
mask += 2 ^ index[name]
|
|
738
|
+
end
|
|
739
|
+
local memberCount = #(node.Members :: { string })
|
|
740
|
+
if memberCount <= 8 then
|
|
741
|
+
wu8(w, mask)
|
|
742
|
+
elseif memberCount <= 16 then
|
|
743
|
+
wu16(w, mask)
|
|
744
|
+
else
|
|
745
|
+
wu32(w, mask)
|
|
746
|
+
end
|
|
747
|
+
elseif vt == "string" then
|
|
748
|
+
wstr(w, value)
|
|
749
|
+
elseif vt == "buffer" or vt == "datatype" then
|
|
750
|
+
wbuf(w, value)
|
|
751
|
+
elseif vt == "table" then
|
|
752
|
+
if depth > 24 then
|
|
753
|
+
error("Scribe: value too deep to serialize")
|
|
754
|
+
end
|
|
755
|
+
local mode = bits % VH_KEY_SCALE
|
|
756
|
+
if mode == VH_STATIC then
|
|
757
|
+
-- One bit per declared child replaces the keys, then the present values in
|
|
758
|
+
-- ordinal order. No entry count: it would restate the mask's popcount. Each
|
|
759
|
+
-- child still carries its own header, so a value the schema cannot describe
|
|
760
|
+
-- degrades to generic in place; only an undeclared key forces the tagged path.
|
|
761
|
+
local order = node.ChildOrder :: { string }
|
|
762
|
+
local children = node.Children :: { [string]: SchemaNode }
|
|
763
|
+
local declared = #order
|
|
764
|
+
wvarint(w, declared)
|
|
765
|
+
-- LSB of the first byte is ordinal 1. Padding bits past `declared` are
|
|
766
|
+
-- written zero and refused on the way back in.
|
|
767
|
+
for byteIndex = 0, math.ceil(declared / 8) - 1 do
|
|
768
|
+
local mask = 0
|
|
769
|
+
for bit = 0, 7 do
|
|
770
|
+
local ordinal = byteIndex * 8 + bit + 1
|
|
771
|
+
if ordinal <= declared and value[order[ordinal]] ~= nil then
|
|
772
|
+
mask += 2 ^ bit
|
|
773
|
+
end
|
|
774
|
+
end
|
|
775
|
+
wu8(w, mask)
|
|
776
|
+
end
|
|
777
|
+
for i = 1, declared do
|
|
778
|
+
local name = order[i]
|
|
779
|
+
local v = value[name]
|
|
780
|
+
if v ~= nil then
|
|
781
|
+
local ebits, etarget, ecount = valueHeaderBits(children[name], v)
|
|
782
|
+
wu8(w, ebits)
|
|
783
|
+
encodeValuePayload(w, etarget, v, depth + 1, ebits, ecount)
|
|
784
|
+
end
|
|
785
|
+
end
|
|
786
|
+
elseif mode == VH_DENSE then
|
|
787
|
+
wvarint(w, count)
|
|
788
|
+
-- Keys are 1..count and inferable from position, so nothing is written for
|
|
789
|
+
-- them. Each element still carries a header and can degrade to generic.
|
|
790
|
+
for i = 1, count do
|
|
791
|
+
local child = Template.ChildSchema(node, i)
|
|
792
|
+
local element = value[i]
|
|
793
|
+
local ebits, etarget, ecount = valueHeaderBits(child, element)
|
|
794
|
+
wu8(w, ebits)
|
|
795
|
+
encodeValuePayload(w, etarget, element, depth + 1, ebits, ecount)
|
|
796
|
+
end
|
|
797
|
+
else
|
|
798
|
+
wvarint(w, count)
|
|
799
|
+
for k, v in value do
|
|
800
|
+
local child: SchemaNode? = nil
|
|
801
|
+
local keyTag: number
|
|
802
|
+
if type(k) == "string" and node.Children and node.Children[k] then
|
|
803
|
+
child = node.Children[k]
|
|
804
|
+
keyTag = TAG_KEY_STATIC
|
|
805
|
+
elseif type(k) == "string" then
|
|
806
|
+
child = Template.ChildSchema(node, k)
|
|
807
|
+
keyTag = TAG_KEY_STRING
|
|
808
|
+
elseif type(k) == "number" and k % 1 == 0 and k >= 0 then
|
|
809
|
+
child = Template.ChildSchema(node, k)
|
|
810
|
+
keyTag = TAG_KEY_UINT
|
|
811
|
+
else
|
|
812
|
+
child = Template.ChildSchema(node, k)
|
|
813
|
+
keyTag = TAG_KEY_F64
|
|
814
|
+
end
|
|
815
|
+
local ebits, etarget, ecount = valueHeaderBits(child, v)
|
|
816
|
+
-- The fold: key tag and value mode share one byte.
|
|
817
|
+
wu8(w, ebits + keyTag * VH_KEY_SCALE)
|
|
818
|
+
if keyTag == TAG_KEY_STATIC then
|
|
819
|
+
wvarint(w, (node.ChildOrdinal :: { [string]: number })[k])
|
|
820
|
+
elseif keyTag == TAG_KEY_STRING then
|
|
821
|
+
wstr(w, k :: string)
|
|
822
|
+
elseif keyTag == TAG_KEY_UINT then
|
|
823
|
+
wvarint(w, k :: number)
|
|
824
|
+
else
|
|
825
|
+
wf64(w, k :: number)
|
|
826
|
+
end
|
|
827
|
+
encodeValuePayload(w, etarget, v, depth + 1, ebits, ecount)
|
|
828
|
+
end
|
|
829
|
+
end
|
|
830
|
+
end
|
|
831
|
+
end
|
|
832
|
+
|
|
833
|
+
local decodeValuePayload: (Reader, SchemaNode?, number, number) -> any
|
|
834
|
+
|
|
835
|
+
--- Reads a standalone value header (no key tag) and its payload.
|
|
836
|
+
local function decodeValue(r: Reader, node: SchemaNode?, depth: number): any
|
|
837
|
+
local header = ru8(r)
|
|
838
|
+
-- A standalone header owns bits 0-1 only. Key-tag bits here mean the writer and
|
|
839
|
+
-- the reader disagree about whether this value sits in a table.
|
|
840
|
+
if header >= VH_VALUE_MAX then
|
|
841
|
+
error("Scribe: malformed value header")
|
|
842
|
+
end
|
|
843
|
+
return decodeValuePayload(r, node, depth, header)
|
|
844
|
+
end
|
|
845
|
+
|
|
846
|
+
--- `header` carries the mode and dense bits (bits 0-1); the caller has already
|
|
847
|
+
--- stripped any key tag and validated the reserved range.
|
|
848
|
+
function decodeValuePayload(r: Reader, node: SchemaNode?, depth: number, header: number): any
|
|
849
|
+
-- An enumeration, not a set of flags: VH_STATIC is 3, so a `header % 2` test
|
|
850
|
+
-- for genericness would decode a presence bitmask as a generic type tag.
|
|
851
|
+
local mode = header % VH_KEY_SCALE
|
|
852
|
+
if mode == VH_GENERIC then
|
|
853
|
+
return decodeGeneric(r, depth)
|
|
854
|
+
end
|
|
855
|
+
if node == nil then
|
|
856
|
+
error("Scribe: malformed value mode")
|
|
857
|
+
end
|
|
858
|
+
local vt = node.ValueType
|
|
859
|
+
-- DENSE and STATIC describe a table's body, so either over a scalar node is a
|
|
860
|
+
-- drifted encoder or a crafted header. Refused rather than ignored: none of the
|
|
861
|
+
-- scalar readers below looks at the mode.
|
|
862
|
+
if mode >= VH_DENSE and vt ~= "table" then
|
|
863
|
+
error(`Scribe: table value mode on a "{vt}" node`)
|
|
864
|
+
end
|
|
865
|
+
if vt == "boolean" then
|
|
866
|
+
return ru8(r) ~= 0
|
|
867
|
+
elseif vt == "int" then
|
|
868
|
+
local width = intWidth(node)
|
|
869
|
+
if width == 1 then
|
|
870
|
+
return ru8(r) + (node.Min :: number)
|
|
871
|
+
elseif width == 2 then
|
|
872
|
+
return ru16(r) + (node.Min :: number)
|
|
873
|
+
elseif width == 4 then
|
|
874
|
+
return ru32(r) + (node.Min :: number)
|
|
875
|
+
elseif node.Min ~= nil and node.Min >= 0 then
|
|
876
|
+
return rvarint(r)
|
|
877
|
+
else
|
|
878
|
+
return rzigzag(r)
|
|
879
|
+
end
|
|
880
|
+
elseif vt == "number" then
|
|
881
|
+
local plan = floatPlan(node)
|
|
882
|
+
if plan == FLOAT_F64 then
|
|
883
|
+
return rf64(r)
|
|
884
|
+
elseif plan == FLOAT_F32 then
|
|
885
|
+
return rf32(r)
|
|
886
|
+
elseif plan == FLOAT_Q8 then
|
|
887
|
+
return quantValue(node, ru8(r))
|
|
888
|
+
elseif plan == FLOAT_Q16 then
|
|
889
|
+
return quantValue(node, ru16(r))
|
|
890
|
+
end
|
|
891
|
+
-- FLOAT_Q32, as the tail rather than a branch of its own. These arms must
|
|
892
|
+
-- mirror the encoder's, or a field is written and read at different widths.
|
|
893
|
+
return quantValue(node, ru32(r))
|
|
894
|
+
elseif vt == "big" then
|
|
895
|
+
return { rf64(r), rzigzag(r) }
|
|
896
|
+
elseif vt == "flags" then
|
|
897
|
+
local members = node.Members :: { string }
|
|
898
|
+
local count = #members
|
|
899
|
+
local mask = if count <= 8 then ru8(r) elseif count <= 16 then ru16(r) else ru32(r)
|
|
900
|
+
charge(r, TABLE_BYTES)
|
|
901
|
+
local out = {}
|
|
902
|
+
for i, name in members do
|
|
903
|
+
if mask % (2 ^ i) >= 2 ^ (i - 1) then
|
|
904
|
+
-- The name is interned in the compiled template, so only the slot is
|
|
905
|
+
-- new; charged for symmetry with decodeGeneric.
|
|
906
|
+
charge(r, SLOT_BYTES)
|
|
907
|
+
table.insert(out, name)
|
|
908
|
+
end
|
|
909
|
+
end
|
|
910
|
+
return out
|
|
911
|
+
elseif vt == "enum" then
|
|
912
|
+
local idx = ru8(r)
|
|
913
|
+
local member = (node.Members :: { string })[idx + 1]
|
|
914
|
+
if member == nil then
|
|
915
|
+
error("Scribe: enum index out of range")
|
|
916
|
+
end
|
|
917
|
+
return member
|
|
918
|
+
elseif vt == "string" then
|
|
919
|
+
return rstr(r, STRING_BYTES)
|
|
920
|
+
elseif vt == "buffer" or vt == "datatype" then
|
|
921
|
+
return rbuf(r, BUFFER_BYTES)
|
|
922
|
+
elseif vt == "table" then
|
|
923
|
+
if depth > 24 then
|
|
924
|
+
error("Scribe: value too deep to deserialize")
|
|
925
|
+
end
|
|
926
|
+
charge(r, TABLE_BYTES)
|
|
927
|
+
-- Written with a string key in the static branch and a number key in the
|
|
928
|
+
-- array branch, so the first write alone must not pin the index type.
|
|
929
|
+
local out: { [string | number]: any } = {}
|
|
930
|
+
if mode == VH_STATIC then
|
|
931
|
+
local order = node.ChildOrder
|
|
932
|
+
local children = node.Children
|
|
933
|
+
if order == nil or children == nil then
|
|
934
|
+
-- An open any-node or a leaf element declares no children, so there is
|
|
935
|
+
-- no ChildOrder for a bitmask to index.
|
|
936
|
+
error("Scribe: static table under a node with no declared children")
|
|
937
|
+
end
|
|
938
|
+
local declared = rvarint(r)
|
|
939
|
+
-- The mask's width comes from the frame and is checked against the schema,
|
|
940
|
+
-- so a disagreeing frame fails here, at the table that is wrong, rather than
|
|
941
|
+
-- mis-parsing everything after it. It also bounds the read below by the
|
|
942
|
+
-- schema rather than by an attacker-chosen varint.
|
|
943
|
+
if declared ~= #order then
|
|
944
|
+
error("Scribe: static bitmask width disagrees with the schema")
|
|
945
|
+
end
|
|
946
|
+
local maskBytes = math.ceil(declared / 8)
|
|
947
|
+
local maskStart = r.pos
|
|
948
|
+
if maskStart + maskBytes > r.size then
|
|
949
|
+
error("Scribe: static bitmask overruns buffer")
|
|
950
|
+
end
|
|
951
|
+
r.pos += maskBytes
|
|
952
|
+
-- Charged up front from the popcount, so a wide struct is refused before the
|
|
953
|
+
-- first recursive decode. The mask already states the whole entry list.
|
|
954
|
+
local present = 0
|
|
955
|
+
for b = 0, maskBytes - 1 do
|
|
956
|
+
local byte = buffer.readu8(r.buf, maskStart + b)
|
|
957
|
+
if b == maskBytes - 1 then
|
|
958
|
+
-- Padding bits past `declared` are written zero; a frame that sets
|
|
959
|
+
-- one is refused rather than masked off.
|
|
960
|
+
local used = declared - b * 8
|
|
961
|
+
if used < 8 and byte >= 2 ^ used then
|
|
962
|
+
error("Scribe: static bitmask has bits set past its declared width")
|
|
963
|
+
end
|
|
964
|
+
end
|
|
965
|
+
while byte > 0 do
|
|
966
|
+
present += byte % 2
|
|
967
|
+
byte = math.floor(byte / 2)
|
|
968
|
+
end
|
|
969
|
+
end
|
|
970
|
+
charge(r, HASH_BYTES * present)
|
|
971
|
+
for i = 1, declared do
|
|
972
|
+
local byte = buffer.readu8(r.buf, maskStart + math.floor((i - 1) / 8))
|
|
973
|
+
local bit = (i - 1) % 8
|
|
974
|
+
if byte % (2 ^ (bit + 1)) >= 2 ^ bit then
|
|
975
|
+
local name = order[i]
|
|
976
|
+
out[name] = decodeValue(r, children[name], depth + 1)
|
|
977
|
+
end
|
|
978
|
+
end
|
|
979
|
+
return out
|
|
980
|
+
end
|
|
981
|
+
local count = rvarint(r)
|
|
982
|
+
if mode == VH_DENSE then
|
|
983
|
+
for i = 1, count do
|
|
984
|
+
-- SLOT_BYTES rather than the tagged path's HASH_BYTES because these
|
|
985
|
+
-- really are array slots, and two bytes against 32 is the same ratio as
|
|
986
|
+
-- the tagged path's four against 64. Charged before the decode.
|
|
987
|
+
charge(r, SLOT_BYTES)
|
|
988
|
+
out[i] = decodeValue(r, Template.ChildSchema(node, i), depth + 1)
|
|
989
|
+
end
|
|
990
|
+
return out
|
|
991
|
+
end
|
|
992
|
+
for _ = 1, count do
|
|
993
|
+
-- Charged per declared entry, from the count above, before the key or the
|
|
994
|
+
-- value is read. A no-op against the client's nil budget today; it is here
|
|
995
|
+
-- so it is not a hole to rediscover.
|
|
996
|
+
charge(r, HASH_BYTES)
|
|
997
|
+
local entryHeader = ru8(r)
|
|
998
|
+
if entryHeader >= VH_ENTRY_MAX then
|
|
999
|
+
error("Scribe: malformed value header")
|
|
1000
|
+
end
|
|
1001
|
+
local tag = (entryHeader - entryHeader % VH_KEY_SCALE) / VH_KEY_SCALE
|
|
1002
|
+
local key: any
|
|
1003
|
+
local child: SchemaNode? = nil
|
|
1004
|
+
if tag == TAG_KEY_STATIC then
|
|
1005
|
+
local ordinal = rvarint(r)
|
|
1006
|
+
-- ChildOrder is nil on a node that declares no static children, so a
|
|
1007
|
+
-- frame claiming a static key under one is malformed. Without this it
|
|
1008
|
+
-- surfaces as "attempt to index nil with number", reading as a bug.
|
|
1009
|
+
local order = node.ChildOrder
|
|
1010
|
+
local name = if order ~= nil then order[ordinal] else nil
|
|
1011
|
+
if name == nil then
|
|
1012
|
+
error("Scribe: bad child ordinal")
|
|
1013
|
+
end
|
|
1014
|
+
key = name
|
|
1015
|
+
child = (node.Children :: { [string]: SchemaNode })[name]
|
|
1016
|
+
elseif tag == TAG_KEY_STRING then
|
|
1017
|
+
key = rstr(r, STRING_BYTES)
|
|
1018
|
+
child = Template.ChildSchema(node, key)
|
|
1019
|
+
elseif tag == TAG_KEY_UINT then
|
|
1020
|
+
key = rvarint(r)
|
|
1021
|
+
child = Template.ChildSchema(node, key)
|
|
1022
|
+
else
|
|
1023
|
+
key = rf64(r)
|
|
1024
|
+
child = Template.ChildSchema(node, key)
|
|
1025
|
+
end
|
|
1026
|
+
local value = decodeValuePayload(r, child, depth + 1, entryHeader % VH_KEY_SCALE)
|
|
1027
|
+
-- Skip a NaN key (only a crafted TAG_KEY_F64 decodes to one): t[NaN] throws.
|
|
1028
|
+
-- Decode the value first to keep the reader in sync.
|
|
1029
|
+
if key == key then
|
|
1030
|
+
out[key] = value
|
|
1031
|
+
end
|
|
1032
|
+
end
|
|
1033
|
+
return out
|
|
1034
|
+
end
|
|
1035
|
+
error(`Scribe: cannot decode schema value type "{vt}"`)
|
|
1036
|
+
end
|
|
1037
|
+
|
|
1038
|
+
function Wire.EncodeValue(w: Writer, node: SchemaNode?, value: any)
|
|
1039
|
+
encodeValue(w, node, value, 0)
|
|
1040
|
+
end
|
|
1041
|
+
|
|
1042
|
+
function Wire.DecodeValue(r: Reader, node: SchemaNode?): any
|
|
1043
|
+
return decodeValue(r, node, 0)
|
|
1044
|
+
end
|
|
1045
|
+
|
|
1046
|
+
-- Path codec --------------------------------------------------------------------
|
|
1047
|
+
|
|
1048
|
+
-- Encodes a path as (deepest static field ID, dynamic tail). Returns the schema
|
|
1049
|
+
-- node the full path resolves to (dynamic segments resolve to any-nodes).
|
|
1050
|
+
function Wire.EncodePath(w: Writer, compiled: Compiled, path: { string | number }): SchemaNode?
|
|
1051
|
+
local node, dynStart = Template.Resolve(compiled, path)
|
|
1052
|
+
wvarint(w, node.Id :: number)
|
|
1053
|
+
local dynCount = #path - dynStart + 1
|
|
1054
|
+
-- The count travels as a u8, so a deeper path would wrap and desync the frame.
|
|
1055
|
+
-- Writes are already capped at MAX_PATH_DYN_SEGMENTS (Node.validateWrite).
|
|
1056
|
+
if dynCount > 255 then
|
|
1057
|
+
error(`Scribe: path has too many dynamic segments ({dynCount})`)
|
|
1058
|
+
end
|
|
1059
|
+
wu8(w, dynCount)
|
|
1060
|
+
local target: SchemaNode? = node
|
|
1061
|
+
for i = dynStart, #path do
|
|
1062
|
+
local seg = path[i]
|
|
1063
|
+
if type(seg) == "string" then
|
|
1064
|
+
wu8(w, TAG_KEY_STRING)
|
|
1065
|
+
wstr(w, seg)
|
|
1066
|
+
elseif seg % 1 == 0 and seg >= 0 then
|
|
1067
|
+
wu8(w, TAG_KEY_UINT)
|
|
1068
|
+
wvarint(w, seg)
|
|
1069
|
+
else
|
|
1070
|
+
wu8(w, TAG_KEY_F64)
|
|
1071
|
+
wf64(w, seg)
|
|
1072
|
+
end
|
|
1073
|
+
target = if target then Template.ChildSchema(target, seg) else nil
|
|
1074
|
+
end
|
|
1075
|
+
return target
|
|
1076
|
+
end
|
|
1077
|
+
|
|
1078
|
+
function Wire.DecodePath(r: Reader, compiled: Compiled): ({ string | number }, SchemaNode?)
|
|
1079
|
+
local id = rvarint(r)
|
|
1080
|
+
local node = compiled.ById[id]
|
|
1081
|
+
if node == nil then
|
|
1082
|
+
error(`Scribe: unknown field id {id}`)
|
|
1083
|
+
end
|
|
1084
|
+
local path: { string | number } = table.clone(node.Path) :: any
|
|
1085
|
+
local dynCount = ru8(r)
|
|
1086
|
+
local target: SchemaNode? = node
|
|
1087
|
+
for _ = 1, dynCount do
|
|
1088
|
+
local tag = ru8(r)
|
|
1089
|
+
local seg: string | number
|
|
1090
|
+
if tag == TAG_KEY_STRING then
|
|
1091
|
+
seg = rstr(r)
|
|
1092
|
+
elseif tag == TAG_KEY_UINT then
|
|
1093
|
+
seg = rvarint(r)
|
|
1094
|
+
elseif tag == TAG_KEY_F64 then
|
|
1095
|
+
seg = rf64(r)
|
|
1096
|
+
else
|
|
1097
|
+
error("Scribe: bad path segment tag")
|
|
1098
|
+
end
|
|
1099
|
+
table.insert(path, seg)
|
|
1100
|
+
target = if target then Template.ChildSchema(target, seg) else nil
|
|
1101
|
+
end
|
|
1102
|
+
return path, target
|
|
1103
|
+
end
|
|
1104
|
+
|
|
1105
|
+
-- Op codec ------------------------------------------------------------------------
|
|
1106
|
+
|
|
1107
|
+
export type Op = {
|
|
1108
|
+
Kind: string, -- "Set" | "Insert" | "Remove" | "Clear"
|
|
1109
|
+
Path: { string | number },
|
|
1110
|
+
Value: any?,
|
|
1111
|
+
Index: number?,
|
|
1112
|
+
}
|
|
1113
|
+
|
|
1114
|
+
function Wire.EncodeOp(w: Writer, compiled: Compiled, op: Op)
|
|
1115
|
+
local kindId = KIND_TO_ID[op.Kind]
|
|
1116
|
+
if kindId == nil then
|
|
1117
|
+
error(`Scribe: unknown op kind "{op.Kind}"`)
|
|
1118
|
+
end
|
|
1119
|
+
local head = kindId
|
|
1120
|
+
local hasValue = op.Value ~= nil
|
|
1121
|
+
if hasValue then
|
|
1122
|
+
head += FLAG_VALUE
|
|
1123
|
+
end
|
|
1124
|
+
if op.Index ~= nil then
|
|
1125
|
+
head += FLAG_INDEX
|
|
1126
|
+
end
|
|
1127
|
+
wu8(w, head)
|
|
1128
|
+
local target = Wire.EncodePath(w, compiled, op.Path)
|
|
1129
|
+
if op.Index ~= nil then
|
|
1130
|
+
wvarint(w, op.Index)
|
|
1131
|
+
end
|
|
1132
|
+
if hasValue then
|
|
1133
|
+
local valueNode = target
|
|
1134
|
+
if op.Kind == "Insert" and target then
|
|
1135
|
+
-- Array elements are children of the container node.
|
|
1136
|
+
valueNode = Template.ChildSchema(target, 1)
|
|
1137
|
+
end
|
|
1138
|
+
Wire.EncodeValue(w, valueNode, op.Value)
|
|
1139
|
+
end
|
|
1140
|
+
end
|
|
1141
|
+
|
|
1142
|
+
function Wire.DecodeOp(r: Reader, compiled: Compiled): Op
|
|
1143
|
+
local head = ru8(r)
|
|
1144
|
+
local kindId = head % 16
|
|
1145
|
+
local kind = ID_TO_KIND[kindId]
|
|
1146
|
+
if kind == nil then
|
|
1147
|
+
error(`Scribe: unknown op kind id {kindId}`)
|
|
1148
|
+
end
|
|
1149
|
+
local hasValue = head % 32 >= 16
|
|
1150
|
+
local hasIndex = head % 64 >= 32
|
|
1151
|
+
local path, target = Wire.DecodePath(r, compiled)
|
|
1152
|
+
local index: number? = nil
|
|
1153
|
+
if hasIndex then
|
|
1154
|
+
index = rvarint(r)
|
|
1155
|
+
end
|
|
1156
|
+
local value: any = nil
|
|
1157
|
+
if hasValue then
|
|
1158
|
+
local valueNode = target
|
|
1159
|
+
if kind == "Insert" and target then
|
|
1160
|
+
valueNode = Template.ChildSchema(target, 1)
|
|
1161
|
+
end
|
|
1162
|
+
value = Wire.DecodeValue(r, valueNode)
|
|
1163
|
+
end
|
|
1164
|
+
return { Kind = kind, Path = path, Value = value, Index = index }
|
|
1165
|
+
end
|
|
1166
|
+
|
|
1167
|
+
--- The initial writer capacity EncodeOpsFrame will choose for `opCount` ops and an
|
|
1168
|
+
--- optional `sizeHint`. Exported so a spec can pin it: seeding changes allocation
|
|
1169
|
+
--- counts and not one output byte, so nothing else could tell it from an
|
|
1170
|
+
--- implementation that quietly stopped seeding. InitWriterSeed.spec watches it.
|
|
1171
|
+
function Wire.OpsFrameCapacity(opCount: number, sizeHint: number?): number
|
|
1172
|
+
-- A hint smaller than the op count implies, from a tiny previous Init before a
|
|
1173
|
+
-- large one, must not shrink the writer below what the ops alone justify.
|
|
1174
|
+
local capacity = 64 + opCount * 16
|
|
1175
|
+
if sizeHint ~= nil and sizeHint > capacity then
|
|
1176
|
+
return sizeHint
|
|
1177
|
+
end
|
|
1178
|
+
return capacity
|
|
1179
|
+
end
|
|
1180
|
+
|
|
1181
|
+
--- Encodes a frame: a frame-type byte, an optional prelude written by `prelude(w)`,
|
|
1182
|
+
--- and a u16-counted op list. When `spans` is given it is filled with each op's
|
|
1183
|
+
--- encoded byte length, in order, measured from the writer's own offset rather than
|
|
1184
|
+
--- by re-encoding, which would cost a second pass and over-count one header per op.
|
|
1185
|
+
---
|
|
1186
|
+
--- `sizeHint` is a floor for the writer's initial capacity, in bytes, and only the
|
|
1187
|
+
--- Init path passes one. `#ops` models a Diff but not an Init: ownerSnapshotOps
|
|
1188
|
+
--- emits one op per root, so a forty-thousand-field profile produces the same
|
|
1189
|
+
--- handful of ops as a tiny one and the writer doubles its way up from a couple of
|
|
1190
|
+
--- hundred bytes. The last Init's size estimates the next.
|
|
1191
|
+
function Wire.EncodeOpsFrame(
|
|
1192
|
+
frameType: number,
|
|
1193
|
+
compiled: Compiled,
|
|
1194
|
+
ops: { Op },
|
|
1195
|
+
prelude: ((Writer) -> ())?,
|
|
1196
|
+
spans: { number }?,
|
|
1197
|
+
sizeHint: number?
|
|
1198
|
+
): buffer
|
|
1199
|
+
-- Callers pre-chunk to MAX_OPS_PER_FRAME; a frame over the u16 count limit
|
|
1200
|
+
-- would silently drop its tail, so fail loudly instead.
|
|
1201
|
+
if #ops > 65535 then
|
|
1202
|
+
error(`Scribe: op frame too large ({#ops} ops); chunk before encoding`)
|
|
1203
|
+
end
|
|
1204
|
+
local w = Wire.NewWriter(Wire.OpsFrameCapacity(#ops, sizeHint))
|
|
1205
|
+
wu8(w, frameType)
|
|
1206
|
+
if prelude then
|
|
1207
|
+
prelude(w)
|
|
1208
|
+
end
|
|
1209
|
+
wu16(w, #ops)
|
|
1210
|
+
if spans == nil then
|
|
1211
|
+
for i = 1, #ops do
|
|
1212
|
+
Wire.EncodeOp(w, compiled, ops[i])
|
|
1213
|
+
end
|
|
1214
|
+
else
|
|
1215
|
+
local prev = w.len
|
|
1216
|
+
for i = 1, #ops do
|
|
1217
|
+
Wire.EncodeOp(w, compiled, ops[i])
|
|
1218
|
+
spans[i] = w.len - prev
|
|
1219
|
+
prev = w.len
|
|
1220
|
+
end
|
|
1221
|
+
end
|
|
1222
|
+
return Wire.Finish(w)
|
|
1223
|
+
end
|
|
1224
|
+
|
|
1225
|
+
-- Frame fragmentation ------------------------------------------------------------
|
|
1226
|
+
--
|
|
1227
|
+
-- Framing, not replication: an Init snapshot is one op per root, so the encoded buffer
|
|
1228
|
+
-- is split rather than the ops.
|
|
1229
|
+
-- u8 Frames.Fragment | u16 seq | u32 total | u16 index | <payload slice>
|
|
1230
|
+
-- `total` repeats in every fragment so the receiver can size from the first. `index`
|
|
1231
|
+
-- makes a lost middle fragment detectable. `seq` stops two interleaved frames splicing
|
|
1232
|
+
-- into one that decodes cleanly to values from neither; Scribe never interleaves today.
|
|
1233
|
+
Wire.FRAGMENT_HEADER = 9
|
|
1234
|
+
|
|
1235
|
+
--- Splits `bytes` into fragments no larger than `maxBytes`, handing each to `emit`
|
|
1236
|
+
--- in order. Returns nil when the frame already fits and `emit` was never called;
|
|
1237
|
+
--- otherwise whether every fragment was emitted (`emit` may return false to stop).
|
|
1238
|
+
---
|
|
1239
|
+
--- Streaming rather than list-returning: a materialised list is a second full copy
|
|
1240
|
+
--- of the frame, and the unicast Init has one recipient and needs none.
|
|
1241
|
+
function Wire.Fragment(bytes: buffer, maxBytes: number, seq: number, emit: (buffer) -> boolean): boolean?
|
|
1242
|
+
local total = buffer.len(bytes)
|
|
1243
|
+
if total <= maxBytes then
|
|
1244
|
+
return nil
|
|
1245
|
+
end
|
|
1246
|
+
local capacity = maxBytes - Wire.FRAGMENT_HEADER
|
|
1247
|
+
if capacity < 1 then
|
|
1248
|
+
error(`Scribe: fragment budget of {maxBytes} bytes cannot carry a payload`, 0)
|
|
1249
|
+
end
|
|
1250
|
+
-- buffer.writeu16 truncates silently, so a wrapped index would reset the
|
|
1251
|
+
-- receiver mid-frame and a wrapped count would end it early.
|
|
1252
|
+
local count = math.ceil(total / capacity)
|
|
1253
|
+
if count > 65535 then
|
|
1254
|
+
error(`Scribe: frame of {total} bytes needs {count} fragments (max 65535); raise MaxOutboundBytes`, 0)
|
|
1255
|
+
end
|
|
1256
|
+
local offset, index = 0, 0
|
|
1257
|
+
while offset < total do
|
|
1258
|
+
local take = math.min(capacity, total - offset)
|
|
1259
|
+
local frame = buffer.create(Wire.FRAGMENT_HEADER + take)
|
|
1260
|
+
buffer.writeu8(frame, 0, Wire.Frames.Fragment)
|
|
1261
|
+
buffer.writeu16(frame, 1, seq)
|
|
1262
|
+
buffer.writeu32(frame, 3, total)
|
|
1263
|
+
buffer.writeu16(frame, 7, index)
|
|
1264
|
+
buffer.copy(frame, Wire.FRAGMENT_HEADER, bytes, offset, take)
|
|
1265
|
+
if not emit(frame) then
|
|
1266
|
+
return false
|
|
1267
|
+
end
|
|
1268
|
+
offset += take
|
|
1269
|
+
index += 1
|
|
1270
|
+
end
|
|
1271
|
+
return true
|
|
1272
|
+
end
|
|
1273
|
+
|
|
1274
|
+
function Wire.DecodeOps(r: Reader, compiled: Compiled): { Op }
|
|
1275
|
+
local count = ru16(r)
|
|
1276
|
+
local ops = table.create(count) :: { Op }
|
|
1277
|
+
for _ = 1, count do
|
|
1278
|
+
table.insert(ops, Wire.DecodeOp(r, compiled))
|
|
1279
|
+
end
|
|
1280
|
+
return ops
|
|
1281
|
+
end
|
|
1282
|
+
|
|
1283
|
+
return Wire
|