@rbxts/scribe 2.6.1 → 2.8.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,6 +122,36 @@ 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
156
  local visibility = Template.OpVisibility(compiled, op, schema)
126
157
  if visibility == "ServerOnly" then
@@ -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
@@ -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
@@ -59,7 +59,7 @@ function Server.build(options: any, compiled: Template.Compiled): (any, any)
59
59
  OnGiftReceived = Signal.new(), -- (player, { FromUserId, Product, GiftId })
60
60
  OnGiftCredit = Signal.new(), -- (player, productName)
61
61
  OnMessage = Signal.new(), -- (player, message)
62
- OnOwnershipChanged = Signal.new(), -- (player, key, owned)
62
+ OnOwnershipChanged = Signal.new(), -- (player, key, owned, trial)
63
63
  OnCooldownEnded = Signal.new(), -- (player, key)
64
64
  OnLeaderboard = Signal.new(), -- (boardName, entries)
65
65
  }
@@ -320,8 +320,12 @@ function Server.build(options: any, compiled: Template.Compiled): (any, any)
320
320
  function Data.OwnsAsync(player: Player, key: string, timeout: number?)
321
321
  return ctx.Monetization.OwnsAsync(player, key, timeout)
322
322
  end
323
+ -- Returns the cached trial if it alone grants access, otherwise nil.
324
+ function Data.GetTrial(player: Player, key: string)
325
+ return ctx.Monetization.GetTrial(player, key)
326
+ end
323
327
  -- Reports current ownership and later changes; returns a disconnect.
324
- function Data.ObserveOwned(player: Player, key: string, callback: (owned: boolean) -> ())
328
+ function Data.ObserveOwned(player: Player, key: string, callback: (owned: boolean, trial: boolean) -> ())
325
329
  return ctx.Monetization.ObserveOwned(player, key, callback)
326
330
  end
327
331
  -- Grants a perk through Scribe's ownership state.
package/src/Types.luau CHANGED
@@ -170,6 +170,9 @@ export type LogCode =
170
170
  | "RECEIPT_HISTORY_FULL"
171
171
  | "OWNERSHIP_CHECK_FAIL"
172
172
  | "PASS_PURCHASE_UNCONFIRMED"
173
+ | "PASS_TRIAL_STARTED"
174
+ | "PASS_TRIAL_ENDED"
175
+ | "PASS_TRIAL_READ_FAIL"
173
176
  | "PERK_GRANTED"
174
177
  | "PERK_REVOKED"
175
178
  | "PRODUCT_INFO_FAIL"
@@ -247,6 +250,7 @@ export type LogCode =
247
250
  | "LISTENER_ERROR"
248
251
  | "ON_PLAYER_INIT_ERROR"
249
252
  | "ON_PLAYER_INIT_LEDGER"
253
+ | "ON_PLAYER_INIT_SESSION"
250
254
  | "PLAYER_LEAVING_HOOK_SLOW"
251
255
  | "SANDBOXED"
252
256
  | "SERVER_STARTED"
@@ -413,7 +417,7 @@ export type LeaderboardConfig = {
413
417
  export type ProductConfig = {
414
418
  Id: number,
415
419
  Category: string?,
416
- Grant: ((data: any) -> ())?,
420
+ Grant: ((data: any, player: Player) -> ())?,
417
421
  Grants: string?,
418
422
  PaidRandom: boolean?,
419
423
  }
@@ -428,7 +432,7 @@ export type PurchaseSpec = {
428
432
  Cost: { Path: string, Amount: number | string | { M: number, E: number } },
429
433
  Category: string?,
430
434
  ItemId: string,
431
- Grant: ((data: any) -> ())?,
435
+ Grant: ((data: any, player: Player) -> ())?,
432
436
  Meta: { [string]: any }?,
433
437
  -- Optional. Two calls carrying the same key apply once: the repeat returns the
434
438
  -- original outcome without debiting or granting again. A FAILED purchase claims
@@ -446,6 +450,11 @@ export type PurchaseFilter = {
446
450
  Limit: number?,
447
451
  }
448
452
 
453
+ -- Expected trial end in Unix seconds, nil if unknown.
454
+ export type PassTrial = {
455
+ EndsAt: number?,
456
+ }
457
+
449
458
  -- Economy analytics -----------------------------------------------------------
450
459
 
451
460
  -- The tag passed to Increment/Decrement to auto-emit LogEconomyEvent. All