@rbxts/scribe 2.5.0 → 2.6.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.
@@ -19,7 +19,9 @@ local Replication = {}
19
19
 
20
20
  local HANDSHAKE_TIMEOUT = 10
21
21
  local MAX_OPS_PER_FRAME = 60000
22
- local REINIT_COOLDOWN = 5 -- seconds between full snapshots for repeated Hellos
22
+ local REINIT_COOLDOWN = 5 -- seconds between snapshots to one client
23
+ -- Per-client cap; excess replies send immediately.
24
+ local MAX_HELD_REPLIES = 64
23
25
  local MALFORMED_LOG_INTERVAL = 1 -- seconds; throttle malformed-frame logs/anomalies per player
24
26
  local MALFORMED_MAX = 32 -- after this many malformed frames, ignore all further inbound from the player
25
27
  -- Its own budget rather than counting toward MALFORMED_MAX: a malformed frame
@@ -240,13 +242,23 @@ function Replication.new(ctx: any)
240
242
  -- Defined below, but needed by markResync's driver in the flush loop above it.
241
243
  local sendInit: (entry: any) -> ()
242
244
 
245
+ -- Shared by the repair loop and reply hold checks.
246
+ local function repairPending(entry: any): boolean
247
+ return entry.ResyncPending == true and entry.State == "Ready" and not entry.TornDown
248
+ end
249
+ local function nextResyncAt(entry: any): number
250
+ return (entry.LastResyncAt or -math.huge) + REINIT_COOLDOWN
251
+ end
252
+
243
253
  -- A frame did not reach the transport, so this client's mirror is now a value the
244
254
  -- server never had: Insert, Remove and Clear are not idempotent, so every later
245
255
  -- op lands on the wrong base, and a loaded client never Hellos again. Repair is a
246
256
  -- fresh Init, not a replay: re-broadcasting a SharedDiff would double-apply an
247
257
  -- Insert on the other recipients.
248
258
  local function markResync(entry: any, what: string)
249
- if entry.ResyncPending then
259
+ local already = entry.ResyncPending == true
260
+ -- Already closed: nothing reaches this mirror until the snapshot.
261
+ if already and not entry.HandshakeReady then
250
262
  return
251
263
  end
252
264
  entry.ResyncPending = true
@@ -258,6 +270,10 @@ function Replication.new(ctx: any)
258
270
  entry.QueueOpen = false
259
271
  entry.Queue = {}
260
272
  entry.QueueIndex = {}
273
+ if already then
274
+ -- Reclose after a partial repair, but count and log this episode only once.
275
+ return
276
+ end
261
277
  Metrics.Add("MirrorResyncs")
262
278
  Log.Warn(
263
279
  "Replication",
@@ -336,6 +352,108 @@ function Replication.new(ctx: any)
336
352
  return true
337
353
  end
338
354
 
355
+ -- Held command replies ------------------------------------------------------
356
+ -- Handler writes travel in the repair snapshot; replies wait for its attempt.
357
+
358
+ -- No queue flush: the snapshot carries the writes.
359
+ local function releaseReplies(entry: any)
360
+ local held = entry.HeldReplies
361
+ if held == nil then
362
+ return
363
+ end
364
+ entry.HeldReplies = nil
365
+ entry.HeldDeadline = nil
366
+ -- Failed replies are logged and dropped; they do not trigger mirror repairs.
367
+ for _, bytes in held do
368
+ sendBuffer(entry, bytes)
369
+ end
370
+ end
371
+
372
+ -- Release after the whole handshake, even if it throws. Failed snapshots disable holds.
373
+ local function afterSnapshotAttempt(entry: any)
374
+ entry.ResyncFailed = not entry.HandshakeReady
375
+ releaseReplies(entry)
376
+ end
377
+
378
+ --- Hold a handler's reply if a repair is due by holdUntil. Refusals use SendTo.
379
+ function self.SendReply(entry: any, bytes: buffer, holdUntil: number)
380
+ local held = entry.HeldReplies
381
+ if
382
+ not stopped
383
+ and repairPending(entry)
384
+ and not entry.HandshakeReady
385
+ and not entry.ResyncFailed
386
+ and (held == nil or #held < MAX_HELD_REPLIES)
387
+ and nextResyncAt(entry) <= holdUntil
388
+ then
389
+ local now = Clock.Monotonic()
390
+ if held == nil then
391
+ held = {}
392
+ entry.HeldReplies = held
393
+ end
394
+ table.insert(held, bytes)
395
+ Metrics.Add("CommandRepliesHeld")
396
+ if holdUntil < (entry.HeldDeadline or math.huge) then
397
+ entry.HeldDeadline = holdUntil
398
+ -- Wake at the deadline; the flush loop attempts any due repair before releasing.
399
+ Clock.Delay(math.max(0, holdUntil - now), markDirty, entry)
400
+ end
401
+ return
402
+ end
403
+ sendBuffer(entry, bytes)
404
+ end
405
+
406
+ -- Connected players without a session, and whether they have a snapshot for store Diffs.
407
+ -- Weak keys; leaving or receiving a new snapshot removes them.
408
+ local lingering: { [any]: boolean } = setmetatable({}, { __mode = "k" }) :: any
409
+
410
+ -- A replacement entry (e.g. SimulateLoadFailure) must receive Init before taking over.
411
+ local function stillLingering(player: any): boolean
412
+ local current = ctx.Persistence.Entries[player]
413
+ if player.Parent == nil or (current ~= nil and current.HandshakeReady) then
414
+ lingering[player] = nil
415
+ return false
416
+ end
417
+ return true
418
+ end
419
+
420
+ -- Status needs no snapshot. Skip replacement entries already reached by the main loop.
421
+ local function reachLingering(frames: { buffer }, everyone: boolean)
422
+ for player, hasSnapshot in lingering do
423
+ if not stillLingering(player) then
424
+ continue
425
+ end
426
+ if everyone then
427
+ if ctx.Persistence.Entries[player] ~= nil then
428
+ continue
429
+ end
430
+ elseif not hasSnapshot then
431
+ continue
432
+ end
433
+ -- Excluded from FramesSent, matching broadcast session accounting.
434
+ for _, frame in frames do
435
+ if not pcall(transport.SendToClient, transport, player, frame) then
436
+ break
437
+ end
438
+ end
439
+ end
440
+ end
441
+
442
+ -- Store Diffs need a snapshot; loading clients receive current store data in Init.
443
+ local function everyClientReady(): boolean
444
+ for _, entry in ctx.Persistence.Entries do
445
+ if not entry.HandshakeReady then
446
+ return false
447
+ end
448
+ end
449
+ for player, hasSnapshot in lingering do
450
+ if not hasSnapshot and stillLingering(player) then
451
+ return false
452
+ end
453
+ end
454
+ return true
455
+ end
456
+
339
457
  -- One frame, to every ready client except `exceptEntry`. Returns the entries the
340
458
  -- frame did not reach, or nil when every recipient got it; the only place that
341
459
  -- knows which clients were missed.
@@ -343,7 +461,13 @@ function Replication.new(ctx: any)
343
461
  -- BytesOutPerSend is observed once here, not once per recipient: per-recipient
344
462
  -- sampling cost O(N^2) reservoir writes a frame and skewed the distribution toward
345
463
  -- the fanout. FramesSent still counts every hand-off to the transport.
346
- local function broadcastBuffer(bytes: buffer, exceptEntry: any?, alsoExcept: any?): { any }?
464
+ -- Store frames also reach session-ended clients with snapshots; Status reaches everyone.
465
+ local function broadcastBuffer(
466
+ bytes: buffer,
467
+ exceptEntry: any?,
468
+ alsoExcept: any?,
469
+ kind: ("store" | "status")?
470
+ ): { any }?
347
471
  -- Split once, before the recipient loop and before the fast-path branch: the
348
472
  -- split depends only on the buffer, and the fast path never reaches `deliver`,
349
473
  -- so a fragmenter placed there would let every broadcast out unsplit.
@@ -354,7 +478,12 @@ function Replication.new(ctx: any)
354
478
  return true
355
479
  end) ~= nil
356
480
 
357
- if transport.SendToAllClients and exceptEntry == nil and alsoExcept == nil then
481
+ if
482
+ transport.SendToAllClients
483
+ and exceptEntry == nil
484
+ and alsoExcept == nil
485
+ and (kind ~= "store" or everyClientReady())
486
+ then
358
487
  -- No per-recipient attribution on this path: one raise means the frame
359
488
  -- reached NOBODY, so every ready client is a missed recipient.
360
489
  local function everyReady(): { any }
@@ -400,7 +529,7 @@ function Replication.new(ctx: any)
400
529
  local accepted = 0
401
530
  local missed: { any }? = nil
402
531
  for _, entry in ctx.Persistence.Entries do
403
- if entry.HandshakeReady and entry ~= exceptEntry and entry ~= alsoExcept then
532
+ if (entry.HandshakeReady or kind == "status") and entry ~= exceptEntry and entry ~= alsoExcept then
404
533
  local complete = true
405
534
  if not split then
406
535
  complete = deliver(entry, bytes)
@@ -440,6 +569,9 @@ function Replication.new(ctx: any)
440
569
  if accepted > 0 then
441
570
  countBytesOut(bytes, accepted)
442
571
  end
572
+ if kind ~= nil then
573
+ reachLingering(if split then parts else { bytes }, kind == "status")
574
+ end
443
575
  return missed
444
576
  end
445
577
 
@@ -536,7 +668,8 @@ function Replication.new(ctx: any)
536
668
  sendSharedOps(entry, detachSharedQueue(entry))
537
669
  end
538
670
 
539
- function self.FlushEntry(entry: any)
671
+ --- Flush before a command reply; keep Shared updates batched for other clients.
672
+ function self.FlushOwnerQueue(entry: any)
540
673
  local queue: { Wire.Op } = entry.Queue
541
674
  if #queue > 0 and entry.HandshakeReady then
542
675
  entry.Queue = {}
@@ -570,7 +703,10 @@ function Replication.new(ctx: any)
570
703
  entry.Queue = {}
571
704
  entry.QueueIndex = {}
572
705
  end
706
+ end
573
707
 
708
+ function self.FlushEntry(entry: any)
709
+ self.FlushOwnerQueue(entry)
574
710
  flushSharedQueue(entry)
575
711
  end
576
712
 
@@ -589,6 +725,8 @@ function Replication.new(ctx: any)
589
725
  local hasStore = compiled.Views.Store ~= nil
590
726
 
591
727
  --- Queue a store op. Same visibility rule as a player op: ServerOnly never leaves.
728
+ local storeOpsQueued = 0
729
+
592
730
  function self.PushStoreOp(op: Wire.Op, schema: Template.SchemaNode?)
593
731
  local visibility = if schema then schema.Visibility else Template.VisibilityOf(compiled, op.Path)
594
732
  if visibility == "ServerOnly" then
@@ -596,6 +734,7 @@ function Replication.new(ctx: any)
596
734
  end
597
735
  stripServerOnly(op, schema)
598
736
  Metrics.Add("OpsQueued")
737
+ storeOpsQueued += 1
599
738
  -- compactOps reads _pk unconditionally. The semicolon is load-bearing: a line opening
600
739
  -- with `(` after a call is ambiguous to Luau.
601
740
  local pathKey = Util.pathKey(op.Path);
@@ -613,7 +752,7 @@ function Replication.new(ctx: any)
613
752
  local ok, bytesOrErr = pcall(Wire.EncodeOpsFrame, Wire.Frames.Diff, compiled, chunk)
614
753
  if ok then
615
754
  -- An ordinary Diff against the full compiled: no new frame kind needed.
616
- local missed = broadcastBuffer(bytesOrErr, except)
755
+ local missed = broadcastBuffer(bytesOrErr, except, nil, "store")
617
756
  Metrics.Add("OpsSent", #chunk)
618
757
  sentOps += #chunk
619
758
  if missed ~= nil then
@@ -631,6 +770,11 @@ function Replication.new(ctx: any)
631
770
  return sentOps
632
771
  end
633
772
 
773
+ --- Cumulative count: queue length may shrink while a command handler yields.
774
+ function self.StoreOpsQueued(): number
775
+ return storeOpsQueued
776
+ end
777
+
634
778
  function self.FlushStoreQueue(except: any?): number
635
779
  if #storeQueue == 0 then
636
780
  return 0
@@ -654,9 +798,9 @@ function Replication.new(ctx: any)
654
798
  -- would have flushed this frame is already in it. Throttled on the previous
655
799
  -- attempt, not on LastInitAt, whose clock starts at the join: gating on that
656
800
  -- would leave a client that lost a frame just after its handshake stale.
657
- if entry.ResyncPending and entry.State == "Ready" and not entry.TornDown then
801
+ if repairPending(entry) then
658
802
  local now = Clock.Monotonic()
659
- if now - (entry.LastResyncAt or -math.huge) >= REINIT_COOLDOWN then
803
+ if now >= nextResyncAt(entry) then
660
804
  entry.LastResyncAt = now
661
805
  entry.ResyncPending = false
662
806
  -- pcall for the reason onHello gives: a throw escaping here would take
@@ -669,8 +813,15 @@ function Replication.new(ctx: any)
669
813
  entry.ResyncPending = true
670
814
  markDirty(entry)
671
815
  end
816
+ afterSnapshotAttempt(entry)
672
817
  end
673
818
  end
819
+ -- Bound the wait even if no repair ran; these replies may precede their data.
820
+ local held = entry.HeldReplies
821
+ if held ~= nil and Clock.Monotonic() >= entry.HeldDeadline then
822
+ Metrics.Add("CommandReplyHoldsExpired", #held)
823
+ releaseReplies(entry)
824
+ end
674
825
  -- Counted before the flush, because FlushEntry replaces both queues. Ops
675
826
  -- pending, not ops sent: compaction shrinks it on the way to the wire.
676
827
  local pending = #entry.Queue + #entry.SharedQueue
@@ -792,7 +943,7 @@ function Replication.new(ctx: any)
792
943
  end
793
944
  -- A missed broadcast Status is not mirror state: the next Health transition
794
945
  -- rebroadcasts, and a resync re-sends it as part of the handshake.
795
- broadcastBuffer(bytes)
946
+ broadcastBuffer(bytes, nil, nil, "status")
796
947
  return true
797
948
  end
798
949
 
@@ -800,25 +951,24 @@ function Replication.new(ctx: any)
800
951
  local lastInitBytes: number? = nil
801
952
 
802
953
  function sendInit(entry: any)
803
- -- Sent after the snapshot is taken, so a write made inside Send lands past the boundary.
804
- local pending: { Wire.Op }? = nil
805
- if hasStore and #storeQueue > 0 then
806
- pending = compactOps(storeQueue)
807
- storeQueue = {}
808
- end
809
954
  -- Open the queue in the same breath as taking the snapshot, with no yield
810
955
  -- between them, so every write from here on is either in this clone or in the
811
956
  -- queue behind it. The clear drops what the snapshot supersedes.
812
957
  entry.Queue = {}
813
958
  entry.QueueIndex = {}
814
959
  entry.QueueOpen = true
960
+ -- A failed snapshot must not leave the client ready with dropped ops.
961
+ entry.HandshakeReady = false
815
962
  -- A repair is an Init for a client that already has a snapshot.
816
963
  local repair = entry.InitDelivered == true
817
964
  -- Stamped at the start of the snapshot: measuring from completion would let a
818
965
  -- slow encode widen its own cooldown.
819
966
  entry.LastInitAt = Clock.Monotonic()
820
967
  local ops = ownerSnapshotOps(entry)
821
- if pending ~= nil then
968
+ -- Detach after the snapshot builds successfully. Writes during Send stay queued.
969
+ if hasStore and #storeQueue > 0 then
970
+ local pending = compactOps(storeQueue)
971
+ storeQueue = {}
822
972
  sendStoreOps(pending, entry)
823
973
  end
824
974
  -- Per-root byte spans, filled by the encode, so the oversize warning can name
@@ -891,10 +1041,7 @@ function Replication.new(ctx: any)
891
1041
  entry.Queue = {}
892
1042
  entry.QueueIndex = {}
893
1043
  entry.QueueOpen = false
894
- -- On a re-Init these matter as much as the clear above: HandshakeReady is still
895
- -- true from the first snapshot, and (ready, not open) is the state in which
896
- -- PushOp silently discards every owner op forever. ResyncPending asks again,
897
- -- since a loaded client has no Hello left to send.
1044
+ -- Retry here: a loaded client never sends another Hello.
898
1045
  entry.HandshakeReady = false
899
1046
  entry.ResyncPending = true
900
1047
  markDirty(entry)
@@ -1006,7 +1153,11 @@ function Replication.new(ctx: any)
1006
1153
  if not okInit then
1007
1154
  Log.Error("Replication", "INIT_SEND_FAIL", tostring(initErr), { Player = entry.Player })
1008
1155
  Metrics.Add("InitSendFailed")
1156
+ -- Retry the whole handshake if anything after Init throws.
1157
+ entry.ResyncPending = true
1158
+ markDirty(entry)
1009
1159
  end
1160
+ afterSnapshotAttempt(entry)
1010
1161
  end
1011
1162
  end
1012
1163
 
@@ -1019,6 +1170,9 @@ function Replication.new(ctx: any)
1019
1170
  if not okInit then
1020
1171
  Log.Error("Replication", "INIT_SEND_FAIL", tostring(initErr), { Player = entry.Player })
1021
1172
  Metrics.Add("InitSendFailed")
1173
+ -- Retry the whole handshake, as in onHello.
1174
+ entry.ResyncPending = true
1175
+ markDirty(entry)
1022
1176
  end
1023
1177
  end
1024
1178
  -- Broadcast this player's Shared snapshot. The queue is cleared before the send: what
@@ -1068,6 +1222,21 @@ function Replication.new(ctx: any)
1068
1222
 
1069
1223
  function self.OnEntryRemoved(entry: any)
1070
1224
  dirty[entry] = nil
1225
+ -- No repair can follow teardown; release replies only to connected clients.
1226
+ local held = entry.HeldReplies
1227
+ if held ~= nil then
1228
+ entry.HeldReplies = nil
1229
+ entry.HeldDeadline = nil
1230
+ if entry.Player ~= nil and entry.Player.Parent ~= nil then
1231
+ for _, bytes in held do
1232
+ sendBuffer(entry, bytes)
1233
+ end
1234
+ end
1235
+ end
1236
+ -- Departed players are removed when lingering is next read.
1237
+ if entry.Player ~= nil then
1238
+ lingering[entry.Player] = entry.HandshakeReady == true
1239
+ end
1071
1240
  entry.HandshakeReady = false
1072
1241
  -- Symmetry rather than a fix: a removed entry's tree is already dead, so
1073
1242
  -- nothing can push to it.
@@ -1117,9 +1286,43 @@ function Replication.new(ctx: any)
1117
1286
 
1118
1287
  -- Inbound dispatch -------------------------------------------------
1119
1288
 
1289
+ -- Refuse commands after session end; use a separate limiter since the entry is gone.
1290
+ local commandRate: number = ctx.Options.CommandRateLimit or 20
1291
+ local sessionlessTokens: { [any]: { Tokens: number, At: number } } = setmetatable({}, { __mode = "k" }) :: any
1292
+
1293
+ local function refuseSessionless(player: any, bytes: buffer)
1294
+ if lingering[player] == nil or not stillLingering(player) then
1295
+ return
1296
+ end
1297
+ if buffer.len(bytes) < 5 or buffer.readu8(bytes, 0) ~= Wire.Frames.Command then
1298
+ return
1299
+ end
1300
+ local now = Clock.Monotonic()
1301
+ local bucket = sessionlessTokens[player]
1302
+ if bucket == nil then
1303
+ bucket = { Tokens = commandRate, At = now }
1304
+ sessionlessTokens[player] = bucket
1305
+ end
1306
+ bucket.Tokens = math.min(commandRate, bucket.Tokens + (now - bucket.At) * commandRate)
1307
+ bucket.At = now
1308
+ if bucket.Tokens < 1 then
1309
+ return
1310
+ end
1311
+ bucket.Tokens -= 1
1312
+ local read, correlation = pcall(function()
1313
+ local reader = Wire.NewReader(bytes)
1314
+ Wire.RU8(reader)
1315
+ return Wire.RU32(reader)
1316
+ end)
1317
+ if read then
1318
+ pcall(transport.SendToClient, transport, player, ctx.Commands.EncodeNotReady(correlation))
1319
+ end
1320
+ end
1321
+
1120
1322
  transport:ListenServer(function(player: Player, bytes: buffer)
1121
1323
  local entry = ctx.Persistence.Entries[player]
1122
1324
  if not entry then
1325
+ refuseSessionless(player, bytes)
1123
1326
  return
1124
1327
  end
1125
1328
  if entry.MalformedBlocked or entry.OversizeBlocked then
@@ -1238,6 +1441,12 @@ function Replication.new(ctx: any)
1238
1441
  -- discarded bundle keeps flushing against a dead Persistence forever.
1239
1442
  function self.Stop()
1240
1443
  stopped = true
1444
+ -- No further repairs can release these replies.
1445
+ if ctx.Persistence then
1446
+ for _, entry in ctx.Persistence.Entries do
1447
+ pcall(releaseReplies, entry)
1448
+ end
1449
+ end
1241
1450
  for _, connection in connections do
1242
1451
  pcall(function()
1243
1452
  connection:Disconnect()
@@ -131,7 +131,7 @@ function Timed.new(ctx: any)
131
131
  local fieldId = visibleFields[pathKey]
132
132
  if fieldId and tree then
133
133
  -- Session metadata shares normal replication and transaction rollback.
134
- tree.Accessor.Child(Template.SESSION_ROOT).Child("Timed").Child(fieldId).Set(value, replicate)
134
+ tree.ReservedSession.Child("Timed").Child(fieldId).Set(value, replicate)
135
135
  end
136
136
  end
137
137
 
@@ -484,7 +484,7 @@ function Timed.new(ctx: any)
484
484
  visible[fieldId] = expiry
485
485
  end
486
486
  end
487
- entry.Tree.Accessor.Child(Template.SESSION_ROOT).Child("Timed").Set(visible)
487
+ entry.Tree.ReservedSession.Child("Timed").Set(visible)
488
488
  end
489
489
  if store ~= nil and next(store) ~= nil then
490
490
  watch(entry)
package/src/Types.luau CHANGED
@@ -229,6 +229,7 @@ export type LogCode =
229
229
  | "DYNAMIC_DEFAULT_FAILED"
230
230
  | "LISTENER_ERROR"
231
231
  | "ON_PLAYER_INIT_ERROR"
232
+ | "ON_PLAYER_INIT_LEDGER"
232
233
  | "PLAYER_LEAVING_HOOK_SLOW"
233
234
  | "SANDBOXED"
234
235
  | "SERVER_STARTED"
@@ -396,7 +397,8 @@ export type PassConfig = {
396
397
  }
397
398
 
398
399
  export type PurchaseSpec = {
399
- Cost: { Path: string, Amount: number },
400
+ -- Strings and Big amounts require a Big currency.
401
+ Cost: { Path: string, Amount: number | string | { M: number, E: number } },
400
402
  Category: string?,
401
403
  ItemId: string,
402
404
  Grant: ((data: any) -> ())?,