@rbxts/scribe 2.6.0 → 2.7.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.
@@ -18,6 +18,7 @@ local Profile = require(Internal.Profile)
18
18
  local Replication = {}
19
19
 
20
20
  local HANDSHAKE_TIMEOUT = 10
21
+ local HANDSHAKE_TIMEOUT_LIVE = 60
21
22
  local MAX_OPS_PER_FRAME = 60000
22
23
  local REINIT_COOLDOWN = 5 -- seconds between snapshots to one client
23
24
  -- Per-client cap; excess replies send immediately.
@@ -121,8 +122,38 @@ function Replication.new(ctx: any)
121
122
  end
122
123
  end
123
124
 
125
+ -- Return true when a scalar Set replaces an earlier Set on the same path.
126
+ local function enqueue(queue: { Wire.Op }, index: { [string]: number }, op: Wire.Op, pathKey: string): boolean
127
+ if op.Kind == "Set" and op.Value ~= nil and type(op.Value) ~= "table" then
128
+ local existing = index[pathKey]
129
+ if
130
+ existing
131
+ and queue[existing]
132
+ and queue[existing].Kind == "Set"
133
+ and (queue[existing] :: any)._pk == pathKey
134
+ then
135
+ queue[existing] = op
136
+ return true
137
+ end
138
+ table.insert(queue, op)
139
+ index[pathKey] = #queue
140
+ return false
141
+ end
142
+ -- Later writes to this path or its children must stay after this op.
143
+ table.insert(queue, op)
144
+ index[pathKey] = nil
145
+ local descendantPrefix = pathKey .. "\31"
146
+ local prefixLen = #descendantPrefix
147
+ for k in index do
148
+ if string.sub(k, 1, prefixLen) == descendantPrefix then
149
+ index[k] = nil
150
+ end
151
+ end
152
+ return false
153
+ end
154
+
124
155
  function self.PushOp(entry: any, op: Wire.Op, schema: Template.SchemaNode?)
125
- local visibility = if schema then schema.Visibility else Template.VisibilityOf(compiled, op.Path)
156
+ local visibility = Template.OpVisibility(compiled, op, schema)
126
157
  if visibility == "ServerOnly" then
127
158
  return
128
159
  end
@@ -136,43 +167,15 @@ function Replication.new(ctx: any)
136
167
  (op :: any)._pk = pathKey
137
168
  if entry.QueueOpen then
138
169
  markDirty(entry)
139
- local queue: { Wire.Op } = entry.Queue
140
- if op.Kind == "Set" and op.Value ~= nil and type(op.Value) ~= "table" then
141
- -- Scalar leaf Set: coalesce consecutive writes to the same path in place.
142
- -- Supersession by whole-container writes is resolved at flush (compactOps).
143
- local existing = entry.QueueIndex[pathKey]
144
- if
145
- existing
146
- and queue[existing]
147
- and queue[existing].Kind == "Set"
148
- and (queue[existing] :: any)._pk == pathKey
149
- then
150
- queue[existing] = op
151
- Metrics.Add("OpsCoalesced")
152
- else
153
- table.insert(queue, op)
154
- entry.QueueIndex[pathKey] = #queue
155
- end
156
- else
157
- -- Whole-container writes (table Set, nil Set, Clear) and array ops append,
158
- -- and break scalar coalescing here and below: a later child Set would
159
- -- otherwise collapse into a preceding slot and be dropped as superseded.
160
- table.insert(queue, op)
161
- entry.QueueIndex[pathKey] = nil
162
- local descendantPrefix = pathKey .. "\31"
163
- local prefixLen = #descendantPrefix
164
- for k in entry.QueueIndex do
165
- if string.sub(k, 1, prefixLen) == descendantPrefix then
166
- entry.QueueIndex[k] = nil
167
- end
168
- end
170
+ if enqueue(entry.Queue, entry.QueueIndex, op, pathKey) then
171
+ Metrics.Add("OpsCoalesced")
169
172
  end
170
173
  end
171
174
  -- Before the snapshot is taken there is nothing to diff against: the snapshot
172
175
  -- about to be cloned carries this value, so queueing it would send it twice.
173
176
 
174
177
  if visibility == "Shared" then
175
- table.insert(entry.SharedQueue, op)
178
+ enqueue(entry.SharedQueue, entry.SharedIndex, op, pathKey)
176
179
  markDirty(entry)
177
180
  end
178
181
  end
@@ -634,6 +637,7 @@ function Replication.new(ctx: any)
634
637
  local function detachSharedQueue(entry: any): { Wire.Op }
635
638
  local shared: { Wire.Op } = entry.SharedQueue
636
639
  entry.SharedQueue = {}
640
+ entry.SharedIndex = {}
637
641
  return shared
638
642
  end
639
643
 
@@ -720,6 +724,7 @@ function Replication.new(ctx: any)
720
724
  --- frame cost can be timed around it.
721
725
  -- One queue for the whole server: a single writer, one frame to every ready client.
722
726
  local storeQueue: { Wire.Op } = {}
727
+ local storeIndex: { [string]: number } = {}
723
728
  -- Lets flushFrame skip the drain entirely. Read from the compiled, not from
724
729
  -- ctx.ServerStore, which is assigned after this constructor returns.
725
730
  local hasStore = compiled.Views.Store ~= nil
@@ -728,7 +733,7 @@ function Replication.new(ctx: any)
728
733
  local storeOpsQueued = 0
729
734
 
730
735
  function self.PushStoreOp(op: Wire.Op, schema: Template.SchemaNode?)
731
- local visibility = if schema then schema.Visibility else Template.VisibilityOf(compiled, op.Path)
736
+ local visibility = Template.OpVisibility(compiled, op, schema)
732
737
  if visibility == "ServerOnly" then
733
738
  return
734
739
  end
@@ -739,7 +744,9 @@ function Replication.new(ctx: any)
739
744
  -- with `(` after a call is ambiguous to Luau.
740
745
  local pathKey = Util.pathKey(op.Path);
741
746
  (op :: any)._pk = pathKey
742
- storeQueue[#storeQueue + 1] = op
747
+ if enqueue(storeQueue, storeIndex, op, pathKey) then
748
+ Metrics.Add("OpsCoalesced")
749
+ end
743
750
  end
744
751
 
745
752
  --- Encode whatever the store queued and broadcast it to every ready client.
@@ -781,6 +788,7 @@ function Replication.new(ctx: any)
781
788
  end
782
789
  local queue = compactOps(storeQueue)
783
790
  storeQueue = {}
791
+ storeIndex = {}
784
792
  return sendStoreOps(queue, except)
785
793
  end
786
794
 
@@ -969,6 +977,7 @@ function Replication.new(ctx: any)
969
977
  if hasStore and #storeQueue > 0 then
970
978
  local pending = compactOps(storeQueue)
971
979
  storeQueue = {}
980
+ storeIndex = {}
972
981
  sendStoreOps(pending, entry)
973
982
  end
974
983
  -- Per-root byte spans, filled by the encode, so the oversize warning can name
@@ -1051,6 +1060,10 @@ function Replication.new(ctx: any)
1051
1060
  -- handed a diff it has no mirror to apply to. broadcastBuffer skips unready
1052
1061
  -- entries, which is also what kept the Shared drain above safe.
1053
1062
  entry.HandshakeReady = true
1063
+ if not repair then
1064
+ -- An initial snapshot sent before OnEntryReady has zero wait.
1065
+ Metrics.Observe("HandshakeDuration", if entry.ReadyAt then Clock.Monotonic() - entry.ReadyAt else 0)
1066
+ end
1054
1067
  entry.InitDelivered = true
1055
1068
  -- Any pending repair request is met by this snapshot.
1056
1069
  entry.ResyncPending = false
@@ -1109,6 +1122,9 @@ function Replication.new(ctx: any)
1109
1122
 
1110
1123
  -- Handshake ---------------------------------------------------------------
1111
1124
 
1125
+ -- Any accepted Hello lowers later timeout reports to Debug.
1126
+ local helloSeen = false
1127
+
1112
1128
  local function onHello(entry: any, reader: Wire.Reader)
1113
1129
  local schemaHash = Wire.RU32(reader)
1114
1130
  -- The client sends its wire PROTOCOL_VERSION after the hash. A mismatch means
@@ -1116,11 +1132,14 @@ function Replication.new(ctx: any)
1116
1132
  -- closed, unlike the hash check below which the value-mode prefix keeps safe.
1117
1133
  local protocolVersion = Wire.RU8(reader)
1118
1134
  if protocolVersion ~= Wire.PROTOCOL_VERSION then
1119
- -- Metered as well as logged, so every refusal is countable.
1135
+ -- Count each refusal and log the first mismatch per session.
1120
1136
  Metrics.Add("ProtocolMismatch")
1121
- Log.Warn("Replication", "PROTOCOL_MISMATCH", "client wire protocol version differs from the server", {
1122
- Player = entry.Player,
1123
- })
1137
+ if not entry.HelloRefused then
1138
+ entry.HelloRefused = true
1139
+ Log.Warn("Replication", "PROTOCOL_MISMATCH", "client wire protocol version differs from the server", {
1140
+ Player = entry.Player,
1141
+ })
1142
+ end
1124
1143
  return
1125
1144
  end
1126
1145
  if schemaHash ~= compiled.Hash % 4294967296 then
@@ -1129,15 +1148,19 @@ function Replication.new(ctx: any)
1129
1148
  -- a server op lands on the wrong client key. The value-mode prefix keeps value
1130
1149
  -- decoding safe, not path remapping.
1131
1150
  Metrics.Add("SchemaMismatch")
1132
- Log.Warn(
1133
- "Replication",
1134
- "SCHEMA_MISMATCH",
1135
- "client derived a different schema than the server; refusing to replicate (template drift)",
1136
- { Player = entry.Player }
1137
- )
1151
+ if not entry.HelloRefused then
1152
+ entry.HelloRefused = true
1153
+ Log.Warn(
1154
+ "Replication",
1155
+ "SCHEMA_MISMATCH",
1156
+ "client derived a different schema than the server; refusing to replicate (template drift)",
1157
+ { Player = entry.Player }
1158
+ )
1159
+ end
1138
1160
  return
1139
1161
  end
1140
1162
  entry.HelloReceived = true
1163
+ helloSeen = true
1141
1164
  if entry.State == "Ready" then
1142
1165
  -- A repeated Hello re-Inits (client-driven resync), but a full snapshot
1143
1166
  -- encode is expensive, so throttle floods.
@@ -1161,7 +1184,47 @@ function Replication.new(ctx: any)
1161
1184
  end
1162
1185
  end
1163
1186
 
1187
+ local function checkHandshake(entry: any, final: boolean)
1188
+ if stopped or entry.TornDown or entry.HandshakeReady then
1189
+ return
1190
+ end
1191
+ if entry.HelloReceived then
1192
+ Log.Warn(
1193
+ "Replication",
1194
+ "INIT_UNDELIVERED",
1195
+ "the client sent Hello but its snapshot never reached the transport; check MaxOutboundBytes against what this transport will carry",
1196
+ {
1197
+ Player = entry.Player,
1198
+ }
1199
+ )
1200
+ elseif entry.HelloRefused then
1201
+ return -- mismatch already logged
1202
+ elseif not final then
1203
+ local remaining = entry.ReadyAt + HANDSHAKE_TIMEOUT_LIVE - Clock.Monotonic()
1204
+ Clock.Delay(math.max(remaining, 0), checkHandshake, entry, true)
1205
+ else
1206
+ Metrics.Add("HandshakeTimeouts")
1207
+ local context = { Player = entry.Player, Waited = Clock.Monotonic() - entry.ReadyAt }
1208
+ if helloSeen then
1209
+ Log.Debug(
1210
+ "Replication",
1211
+ "CLIENT_HANDSHAKE_TIMEOUT",
1212
+ "client has not sent Hello, though other clients of this server have; it is still loading or has stalled, and is answered when it asks",
1213
+ context
1214
+ )
1215
+ else
1216
+ Log.Warn(
1217
+ "Replication",
1218
+ "CLIENT_HANDSHAKE_TIMEOUT",
1219
+ "no client has sent Hello to this server, so replication never started; require the Scribe bundle on the client (a LocalScript), or check a custom client transport adapter",
1220
+ context
1221
+ )
1222
+ end
1223
+ end
1224
+ end
1225
+
1164
1226
  function self.OnEntryReady(entry: any)
1227
+ entry.ReadyAt = Clock.Monotonic()
1165
1228
  -- QueueOpen, not HandshakeReady: the question is whether a snapshot has already
1166
1229
  -- been started, which is the same question the re-Init throttle asks. The two
1167
1230
  -- reading different flags is how the gap opened.
@@ -1179,6 +1242,7 @@ function Replication.new(ctx: any)
1179
1242
  -- was queued is in the snapshot, and a write made during the send is the next flush's.
1180
1243
  local sharedOps = sharedSnapshotOps(entry)
1181
1244
  entry.SharedQueue = {}
1245
+ entry.SharedIndex = {}
1182
1246
  if #sharedOps > 0 then
1183
1247
  local ok, bytes = pcall(Wire.EncodeOpsFrame, Wire.Frames.SharedInit, compiled, sharedOps, function(w)
1184
1248
  Wire.F64(w, entry.UserId)
@@ -1192,32 +1256,8 @@ function Replication.new(ctx: any)
1192
1256
  end
1193
1257
  end
1194
1258
  end
1195
- Clock.Delay(HANDSHAKE_TIMEOUT, function()
1196
- if not entry.TornDown and not entry.HandshakeReady then
1197
- if entry.HelloReceived then
1198
- -- A different failure with the same symptom: the client did ask and the
1199
- -- answer could not be delivered. MaxOutboundBytes is named because a
1200
- -- transport refusing a payload this size is the one innocent cause.
1201
- Log.Warn(
1202
- "Replication",
1203
- "INIT_UNDELIVERED",
1204
- "the client sent Hello but its snapshot never reached the transport; check MaxOutboundBytes against what this transport will carry",
1205
- {
1206
- Player = entry.Player,
1207
- }
1208
- )
1209
- else
1210
- Log.Warn(
1211
- "Replication",
1212
- "CLIENT_HANDSHAKE_TIMEOUT",
1213
- "client never sent Hello, so replication never started; require the Scribe bundle on the client (a LocalScript), or check a custom client transport adapter",
1214
- {
1215
- Player = entry.Player,
1216
- }
1217
- )
1218
- end
1219
- end
1220
- end)
1259
+ -- Live clients get a second check for a missing Hello.
1260
+ Clock.Delay(HANDSHAKE_TIMEOUT, checkHandshake, entry, ctx.DevMode == true)
1221
1261
  end
1222
1262
 
1223
1263
  function self.OnEntryRemoved(entry: any)
@@ -474,8 +474,14 @@ function Timed.new(ctx: any)
474
474
 
475
475
  function self.OnLoad(entry: any)
476
476
  restoreDeadlines(entry)
477
- sweepEntry(entry)
478
477
  local store = timedStore(entry)
478
+ -- Session values reset on join, so discard their saved deadlines.
479
+ for pathKey in store or {} do
480
+ if not Template.PersistOf(compiled, string.split(pathKey, "\31")) then
481
+ setTimed(entry, pathKey, nil)
482
+ end
483
+ end
484
+ sweepEntry(entry)
479
485
  if next(visibleFields) ~= nil then
480
486
  local visible: { [string]: number } = {}
481
487
  for pathKey, expiry in store or {} do
package/src/Types.luau CHANGED
@@ -21,13 +21,30 @@ export type ScribeTransport = {
21
21
  -- framing changes the arithmetic, such as base64 inflating by 4/3.
22
22
  MaxFrameBytes: number?,
23
23
  -- Server
24
+ --[[
25
+ Sends a frame to one client.
26
+ ]]
24
27
  SendToClient: (self: any, player: Player, bytes: buffer) -> (),
28
+ --[[
29
+ Sends a frame to every client, when supported.
30
+ ]]
25
31
  SendToAllClients: ((self: any, bytes: buffer) -> ())?,
32
+ --[[
33
+ Registers the server callback for incoming client frames.
34
+ ]]
26
35
  ListenServer: (self: any, callback: (player: Player, bytes: buffer) -> ()) -> (),
27
36
  -- Client
37
+ --[[
38
+ Sends a frame to the server.
39
+ ]]
28
40
  SendToServer: (self: any, bytes: buffer) -> (),
41
+ --[[
42
+ Registers the client callback for incoming server frames.
43
+ ]]
29
44
  ListenClient: (self: any, callback: (bytes: buffer) -> ()) -> (),
30
- -- Optional. Client.Stop calls it to disconnect what ListenClient connected.
45
+ --[[
46
+ Disconnects the client listener when Client.Stop runs.
47
+ ]]
31
48
  Release: ((self: any) -> ())?,
32
49
  }
33
50
 
@@ -230,6 +247,7 @@ export type LogCode =
230
247
  | "LISTENER_ERROR"
231
248
  | "ON_PLAYER_INIT_ERROR"
232
249
  | "ON_PLAYER_INIT_LEDGER"
250
+ | "ON_PLAYER_INIT_SESSION"
233
251
  | "PLAYER_LEAVING_HOOK_SLOW"
234
252
  | "SANDBOXED"
235
253
  | "SERVER_STARTED"
@@ -304,6 +322,7 @@ export type PurchaseReason =
304
322
  | "insufficient funds"
305
323
  | "paid random items are not available for this account"
306
324
  | "cannot check account settings right now; try again in a moment"
325
+ | "invalid IdempotencyKey"
307
326
 
308
327
  -- The fixed refusals of Data.PromptGift. Two more are interpolated (`unknown
309
328
  -- product "<name>"` and `purchase prompt failed: <err>`) and cannot be members.
@@ -344,8 +363,17 @@ export type Visibility = "Replicated" | "ServerOnly" | "Shared"
344
363
  export type BigScore = {
345
364
  M: number,
346
365
  E: number,
366
+ --[[
367
+ Formats the value with a compact suffix.
368
+ ]]
347
369
  Short: (self: any, decimals: number?) -> string,
370
+ --[[
371
+ Converts to a Luau number; large values may overflow.
372
+ ]]
348
373
  ToNumber: (self: any) -> number,
374
+ --[[
375
+ Returns the base-10 logarithm of a positive value.
376
+ ]]
349
377
  Log10: (self: any) -> number,
350
378
  }
351
379
 
@@ -386,7 +414,7 @@ export type LeaderboardConfig = {
386
414
  export type ProductConfig = {
387
415
  Id: number,
388
416
  Category: string?,
389
- Grant: ((data: any) -> ())?,
417
+ Grant: ((data: any, player: Player) -> ())?,
390
418
  Grants: string?,
391
419
  PaidRandom: boolean?,
392
420
  }
@@ -401,7 +429,7 @@ export type PurchaseSpec = {
401
429
  Cost: { Path: string, Amount: number | string | { M: number, E: number } },
402
430
  Category: string?,
403
431
  ItemId: string,
404
- Grant: ((data: any) -> ())?,
432
+ Grant: ((data: any, player: Player) -> ())?,
405
433
  Meta: { [string]: any }?,
406
434
  -- Optional. Two calls carrying the same key apply once: the repeat returns the
407
435
  -- original outcome without debiting or granting again. A FAILED purchase claims