@rbxts/scribe-telemetry 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/Config.luau +446 -0
- package/Diagnostics.luau +104 -0
- package/Format.luau +152 -0
- package/LICENSE +21 -0
- package/LeaderboardMonitor.luau +146 -0
- package/NOTICE +21 -0
- package/Preview.luau +396 -0
- package/README.md +5 -0
- package/Router.luau +152 -0
- package/Sanitize.luau +265 -0
- package/Scribe-source-map.json +1 -0
- package/Transport.luau +498 -0
- package/index.d.ts +150 -0
- package/init.luau +1120 -0
- package/package.json +20 -0
package/Transport.luau
ADDED
|
@@ -0,0 +1,498 @@
|
|
|
1
|
+
--!strict
|
|
2
|
+
-- Bounded asynchronous delivery: one lane per webhook URL and one worker per lane, so
|
|
3
|
+
-- a throttled or dead webhook never holds up another.
|
|
4
|
+
|
|
5
|
+
local Sanitize = require(script.Parent.Sanitize)
|
|
6
|
+
|
|
7
|
+
local Transport = {}
|
|
8
|
+
Transport.__index = Transport
|
|
9
|
+
|
|
10
|
+
export type Response = {
|
|
11
|
+
Ok: boolean,
|
|
12
|
+
Status: number?,
|
|
13
|
+
Headers: { [string]: string }?,
|
|
14
|
+
Body: string?,
|
|
15
|
+
Error: string?,
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export type Http = { Post: (url: string, body: string) -> Response }
|
|
19
|
+
export type Clock = { Now: () -> number, Monotonic: () -> number }
|
|
20
|
+
export type Scheduler = { Spawn: (fn: () -> ()) -> (), Wait: (seconds: number) -> () }
|
|
21
|
+
export type Json = { Encode: (value: any) -> string, Decode: (text: string) -> any }
|
|
22
|
+
|
|
23
|
+
export type Deps = {
|
|
24
|
+
Http: Http,
|
|
25
|
+
Clock: Clock,
|
|
26
|
+
Scheduler: Scheduler,
|
|
27
|
+
Json: Json,
|
|
28
|
+
Jitter: () -> number, -- in [0, 1)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export type Dropped = {
|
|
32
|
+
Overflow: number,
|
|
33
|
+
Expired: number,
|
|
34
|
+
Malformed: number,
|
|
35
|
+
DeadDestination: number,
|
|
36
|
+
Exhausted: number,
|
|
37
|
+
Stopped: number,
|
|
38
|
+
Coalesced: number,
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function Transport.EmptyDropped(): Dropped
|
|
42
|
+
return {
|
|
43
|
+
Overflow = 0,
|
|
44
|
+
Expired = 0,
|
|
45
|
+
Malformed = 0,
|
|
46
|
+
DeadDestination = 0,
|
|
47
|
+
Exhausted = 0,
|
|
48
|
+
Stopped = 0,
|
|
49
|
+
Coalesced = 0,
|
|
50
|
+
}
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
export type Stats = {
|
|
54
|
+
Queued: number,
|
|
55
|
+
QueuedBytes: number,
|
|
56
|
+
Delivered: number,
|
|
57
|
+
Retries: number,
|
|
58
|
+
Uncertain: number,
|
|
59
|
+
Dropped: Dropped,
|
|
60
|
+
LastDeliveredAt: number?,
|
|
61
|
+
Destinations: { [string]: DestinationStats },
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export type Limits = {
|
|
65
|
+
MaxQueued: number,
|
|
66
|
+
MaxQueuedBytes: number,
|
|
67
|
+
PerDestinationQueued: number,
|
|
68
|
+
MaxAge: number,
|
|
69
|
+
MaxAttempts: number,
|
|
70
|
+
MaxRetryDelay: number,
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
type Item = {
|
|
74
|
+
Id: string,
|
|
75
|
+
Destination: string,
|
|
76
|
+
Category: string,
|
|
77
|
+
GroupKey: string?,
|
|
78
|
+
Priority: number,
|
|
79
|
+
Payload: string,
|
|
80
|
+
Bytes: number,
|
|
81
|
+
CreatedAt: number,
|
|
82
|
+
ExpiresAt: number,
|
|
83
|
+
NotBefore: number,
|
|
84
|
+
Attempts: number,
|
|
85
|
+
InFlight: boolean,
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
type Lane = {
|
|
89
|
+
Url: string,
|
|
90
|
+
Queue: { Item },
|
|
91
|
+
Bytes: number,
|
|
92
|
+
NotBefore: number, -- rate-limit pacing, monotonic
|
|
93
|
+
Dead: boolean,
|
|
94
|
+
Working: boolean,
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export type DestinationStats = {
|
|
98
|
+
State: string, -- Ready, Dead, Stopped
|
|
99
|
+
Queued: number,
|
|
100
|
+
Delivered: number,
|
|
101
|
+
Failures: number,
|
|
102
|
+
LastDeliveredAt: number?,
|
|
103
|
+
LastError: string?,
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
local DEAD_STATUSES = { [401] = true, [403] = true, [404] = true, [410] = true }
|
|
107
|
+
local MALFORMED_STATUSES = { [400] = true, [413] = true, [422] = true }
|
|
108
|
+
|
|
109
|
+
local function header(headers: { [string]: string }?, name: string): string?
|
|
110
|
+
if headers == nil then
|
|
111
|
+
return nil
|
|
112
|
+
end
|
|
113
|
+
local lower = string.lower(name)
|
|
114
|
+
for key, value in headers do
|
|
115
|
+
if string.lower(key) == lower then
|
|
116
|
+
return value
|
|
117
|
+
end
|
|
118
|
+
end
|
|
119
|
+
return nil
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
function Transport.new(limits: Limits, deps: Deps)
|
|
123
|
+
local self = setmetatable({}, Transport)
|
|
124
|
+
self.limits = limits
|
|
125
|
+
self.deps = deps
|
|
126
|
+
self.running = true
|
|
127
|
+
self.lanes = {} :: { [string]: Lane }
|
|
128
|
+
self.destinationLane = {} :: { [string]: string }
|
|
129
|
+
self.destinations = {} :: { [string]: DestinationStats }
|
|
130
|
+
self.queued = 0
|
|
131
|
+
self.queuedBytes = 0
|
|
132
|
+
self.stats = {
|
|
133
|
+
Delivered = 0,
|
|
134
|
+
Retries = 0,
|
|
135
|
+
Uncertain = 0,
|
|
136
|
+
Dropped = Transport.EmptyDropped(),
|
|
137
|
+
LastDeliveredAt = nil :: number?,
|
|
138
|
+
}
|
|
139
|
+
return self
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
--- Declares a destination. Two names on one URL share a lane.
|
|
143
|
+
function Transport.AddDestination(self: any, name: string, url: string)
|
|
144
|
+
self.destinationLane[name] = url
|
|
145
|
+
if self.lanes[url] == nil then
|
|
146
|
+
self.lanes[url] = { Url = url, Queue = {}, Bytes = 0, NotBefore = 0, Dead = false, Working = false }
|
|
147
|
+
end
|
|
148
|
+
self.destinations[name] =
|
|
149
|
+
{ State = "Ready", Queued = 0, Delivered = 0, Failures = 0, LastDeliveredAt = nil, LastError = nil }
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
local function take(self: any, lane: Lane, index: number): Item
|
|
153
|
+
local item = table.remove(lane.Queue, index) :: Item
|
|
154
|
+
lane.Bytes -= item.Bytes
|
|
155
|
+
self.queued -= 1
|
|
156
|
+
self.queuedBytes -= item.Bytes
|
|
157
|
+
self.destinations[item.Destination].Queued -= 1
|
|
158
|
+
return item
|
|
159
|
+
end
|
|
160
|
+
|
|
161
|
+
local function dropItem(self: any, lane: Lane, index: number, reason: string)
|
|
162
|
+
take(self, lane, index)
|
|
163
|
+
self.stats.Dropped[reason] += 1
|
|
164
|
+
end
|
|
165
|
+
|
|
166
|
+
-- Short, and carrying no URL, so an echoed body or error is safe in LastError.
|
|
167
|
+
local function shortBody(body: string?): string
|
|
168
|
+
local text = if body then string.gsub(body, "%c", " ") else ""
|
|
169
|
+
text = string.gsub(text, "https?://%S+", "[url]")
|
|
170
|
+
return Sanitize.Truncate(text, 160)
|
|
171
|
+
end
|
|
172
|
+
|
|
173
|
+
-- Expired first, then the lowest priority no higher than `floor`, oldest among equals;
|
|
174
|
+
-- never the item in flight. Asked at most once per Enqueue, so it needs no plan.
|
|
175
|
+
local function victim(lane: Lane, now: number, floor: number): Item?
|
|
176
|
+
local best: Item? = nil
|
|
177
|
+
for _, item in lane.Queue do
|
|
178
|
+
if item.InFlight then
|
|
179
|
+
continue
|
|
180
|
+
end
|
|
181
|
+
if item.ExpiresAt <= now then
|
|
182
|
+
return item
|
|
183
|
+
end
|
|
184
|
+
if item.Priority <= floor and (best == nil or item.Priority < best.Priority) then
|
|
185
|
+
best = item
|
|
186
|
+
end
|
|
187
|
+
end
|
|
188
|
+
return best
|
|
189
|
+
end
|
|
190
|
+
|
|
191
|
+
-- Across every lane, oldest among equals: for a limit every lane shares.
|
|
192
|
+
local function globalVictim(self: any, now: number, floor: number, planned: { [Item]: boolean }): (Lane?, Item?)
|
|
193
|
+
local bestLane: Lane? = nil
|
|
194
|
+
local best: Item? = nil
|
|
195
|
+
for _, lane in self.lanes do
|
|
196
|
+
for _, item in lane.Queue do
|
|
197
|
+
if item.InFlight or planned[item] then
|
|
198
|
+
continue
|
|
199
|
+
end
|
|
200
|
+
if item.ExpiresAt <= now then
|
|
201
|
+
return lane, item
|
|
202
|
+
end
|
|
203
|
+
if item.Priority > floor then
|
|
204
|
+
continue
|
|
205
|
+
end
|
|
206
|
+
if
|
|
207
|
+
best == nil
|
|
208
|
+
or item.Priority < best.Priority
|
|
209
|
+
or (item.Priority == best.Priority and item.CreatedAt < best.CreatedAt)
|
|
210
|
+
then
|
|
211
|
+
bestLane, best = lane, item
|
|
212
|
+
end
|
|
213
|
+
end
|
|
214
|
+
end
|
|
215
|
+
return bestLane, best
|
|
216
|
+
end
|
|
217
|
+
|
|
218
|
+
--- Queues `payload` for `destination`. Returns false with a reason when it was refused.
|
|
219
|
+
function Transport.Enqueue(
|
|
220
|
+
self: any,
|
|
221
|
+
destination: string,
|
|
222
|
+
id: string,
|
|
223
|
+
category: string,
|
|
224
|
+
groupKey: string?,
|
|
225
|
+
priority: number,
|
|
226
|
+
payload: string
|
|
227
|
+
): (boolean, string?)
|
|
228
|
+
if not self.running then
|
|
229
|
+
return false, "stopped"
|
|
230
|
+
end
|
|
231
|
+
local url = self.destinationLane[destination]
|
|
232
|
+
local lane: Lane? = if url then self.lanes[url] else nil
|
|
233
|
+
if lane == nil then
|
|
234
|
+
return false, "unknown-destination"
|
|
235
|
+
end
|
|
236
|
+
if lane.Dead then
|
|
237
|
+
self.stats.Dropped.DeadDestination += 1
|
|
238
|
+
return false, "dead-destination"
|
|
239
|
+
end
|
|
240
|
+
local now = self.deps.Clock.Monotonic()
|
|
241
|
+
local bytes = #payload
|
|
242
|
+
-- A repetition summary supersedes the one still waiting for the same group.
|
|
243
|
+
if groupKey ~= nil then
|
|
244
|
+
for _, queued in lane.Queue do
|
|
245
|
+
if queued.GroupKey == groupKey and not queued.InFlight then
|
|
246
|
+
if self.queuedBytes + bytes - queued.Bytes > self.limits.MaxQueuedBytes then
|
|
247
|
+
self.stats.Dropped.Overflow += 1
|
|
248
|
+
return false, "overflow"
|
|
249
|
+
end
|
|
250
|
+
lane.Bytes += bytes - queued.Bytes
|
|
251
|
+
self.queuedBytes += bytes - queued.Bytes
|
|
252
|
+
queued.Payload = payload
|
|
253
|
+
queued.Bytes = bytes
|
|
254
|
+
queued.Id = id
|
|
255
|
+
queued.CreatedAt = now
|
|
256
|
+
queued.ExpiresAt = now + self.limits.MaxAge
|
|
257
|
+
self.stats.Dropped.Coalesced += 1
|
|
258
|
+
return true, nil
|
|
259
|
+
end
|
|
260
|
+
end
|
|
261
|
+
end
|
|
262
|
+
-- Planned first, so a report no eviction could admit leaves the queue untouched. A full
|
|
263
|
+
-- lane gives up one of its own; a shared limit takes the lowest priority anywhere.
|
|
264
|
+
local planned: { [Item]: boolean } = {}
|
|
265
|
+
local plan: { { Lane: Lane, Item: Item } } = {}
|
|
266
|
+
local laneCount, count, queuedBytes = #lane.Queue, self.queued, self.queuedBytes
|
|
267
|
+
while
|
|
268
|
+
laneCount >= self.limits.PerDestinationQueued
|
|
269
|
+
or count >= self.limits.MaxQueued
|
|
270
|
+
or queuedBytes + bytes > self.limits.MaxQueuedBytes
|
|
271
|
+
do
|
|
272
|
+
local target: Lane? = lane
|
|
273
|
+
local item: Item? = nil
|
|
274
|
+
if laneCount >= self.limits.PerDestinationQueued then
|
|
275
|
+
item = victim(lane, now, priority)
|
|
276
|
+
else
|
|
277
|
+
target, item = globalVictim(self, now, priority, planned)
|
|
278
|
+
end
|
|
279
|
+
if target == nil or item == nil then
|
|
280
|
+
self.stats.Dropped.Overflow += 1
|
|
281
|
+
return false, "overflow"
|
|
282
|
+
end
|
|
283
|
+
local chosenLane, chosen = target :: Lane, item :: Item
|
|
284
|
+
planned[chosen] = true
|
|
285
|
+
table.insert(plan, { Lane = chosenLane, Item = chosen })
|
|
286
|
+
count -= 1
|
|
287
|
+
queuedBytes -= chosen.Bytes
|
|
288
|
+
if chosenLane == lane then
|
|
289
|
+
laneCount -= 1
|
|
290
|
+
end
|
|
291
|
+
end
|
|
292
|
+
for _, entry in plan do
|
|
293
|
+
local index = table.find(entry.Lane.Queue, entry.Item)
|
|
294
|
+
if index ~= nil then
|
|
295
|
+
dropItem(self, entry.Lane, index, "Overflow")
|
|
296
|
+
end
|
|
297
|
+
end
|
|
298
|
+
table.insert(lane.Queue, {
|
|
299
|
+
Id = id,
|
|
300
|
+
Destination = destination,
|
|
301
|
+
Category = category,
|
|
302
|
+
GroupKey = groupKey,
|
|
303
|
+
Priority = priority,
|
|
304
|
+
Payload = payload,
|
|
305
|
+
Bytes = bytes,
|
|
306
|
+
CreatedAt = now,
|
|
307
|
+
ExpiresAt = now + self.limits.MaxAge,
|
|
308
|
+
NotBefore = 0,
|
|
309
|
+
Attempts = 0,
|
|
310
|
+
InFlight = false,
|
|
311
|
+
})
|
|
312
|
+
lane.Bytes += bytes
|
|
313
|
+
self.queued += 1
|
|
314
|
+
self.queuedBytes += bytes
|
|
315
|
+
self.destinations[destination].Queued += 1
|
|
316
|
+
self:startWorker(lane)
|
|
317
|
+
return true, nil
|
|
318
|
+
end
|
|
319
|
+
|
|
320
|
+
-- A zero would post again without yielding.
|
|
321
|
+
local RETRY_AFTER_MIN = 1
|
|
322
|
+
|
|
323
|
+
local function retryAfterSeconds(self: any, response: Response): number
|
|
324
|
+
local body = response.Body
|
|
325
|
+
local delay: number? = nil
|
|
326
|
+
if body ~= nil and body ~= "" then
|
|
327
|
+
local ok, decoded = pcall(self.deps.Json.Decode, body)
|
|
328
|
+
if ok and type(decoded) == "table" and type(decoded.retry_after) == "number" then
|
|
329
|
+
delay = decoded.retry_after
|
|
330
|
+
end
|
|
331
|
+
end
|
|
332
|
+
if delay == nil then
|
|
333
|
+
delay = tonumber(header(response.Headers, "Retry-After") or header(response.Headers, "X-RateLimit-Reset-After"))
|
|
334
|
+
end
|
|
335
|
+
return math.max(RETRY_AFTER_MIN, delay or 5)
|
|
336
|
+
end
|
|
337
|
+
|
|
338
|
+
local function markDead(self: any, lane: Lane, err: string)
|
|
339
|
+
lane.Dead = true
|
|
340
|
+
for name, url in self.destinationLane do
|
|
341
|
+
if url == lane.Url then
|
|
342
|
+
local stats = self.destinations[name]
|
|
343
|
+
stats.State = "Dead"
|
|
344
|
+
stats.LastError = err
|
|
345
|
+
end
|
|
346
|
+
end
|
|
347
|
+
while #lane.Queue > 0 do
|
|
348
|
+
dropItem(self, lane, 1, "DeadDestination")
|
|
349
|
+
end
|
|
350
|
+
end
|
|
351
|
+
|
|
352
|
+
function Transport.startWorker(self: any, lane: Lane)
|
|
353
|
+
if lane.Working then
|
|
354
|
+
return
|
|
355
|
+
end
|
|
356
|
+
lane.Working = true
|
|
357
|
+
self.deps.Scheduler.Spawn(function()
|
|
358
|
+
self:work(lane)
|
|
359
|
+
lane.Working = false
|
|
360
|
+
end)
|
|
361
|
+
end
|
|
362
|
+
|
|
363
|
+
function Transport.work(self: any, lane: Lane)
|
|
364
|
+
local limits: Limits = self.limits
|
|
365
|
+
while self.running and not lane.Dead do
|
|
366
|
+
local item: Item? = lane.Queue[1]
|
|
367
|
+
if item == nil then
|
|
368
|
+
return
|
|
369
|
+
end
|
|
370
|
+
local now = self.deps.Clock.Monotonic()
|
|
371
|
+
if item.ExpiresAt <= now then
|
|
372
|
+
dropItem(self, lane, 1, "Expired")
|
|
373
|
+
continue
|
|
374
|
+
end
|
|
375
|
+
local notBefore = math.max(lane.NotBefore, item.NotBefore)
|
|
376
|
+
if notBefore > now then
|
|
377
|
+
if notBefore >= item.ExpiresAt then
|
|
378
|
+
dropItem(self, lane, 1, "Expired")
|
|
379
|
+
continue
|
|
380
|
+
end
|
|
381
|
+
self.deps.Scheduler.Wait(notBefore - now)
|
|
382
|
+
continue
|
|
383
|
+
end
|
|
384
|
+
|
|
385
|
+
local stats: DestinationStats = self.destinations[item.Destination]
|
|
386
|
+
item.InFlight = true
|
|
387
|
+
local ok, response = pcall(self.deps.Http.Post, lane.Url, item.Payload)
|
|
388
|
+
item.InFlight = false
|
|
389
|
+
if not self.running then
|
|
390
|
+
return
|
|
391
|
+
end
|
|
392
|
+
local res: Response = if ok then response else { Ok = false, Error = tostring(response) }
|
|
393
|
+
now = self.deps.Clock.Monotonic()
|
|
394
|
+
-- Still the head: evictions skip it and enqueues append.
|
|
395
|
+
local index = 1
|
|
396
|
+
|
|
397
|
+
if res.Ok and res.Status ~= nil and res.Status >= 200 and res.Status < 300 then
|
|
398
|
+
take(self, lane, index)
|
|
399
|
+
self.stats.Delivered += 1
|
|
400
|
+
self.stats.LastDeliveredAt = self.deps.Clock.Now()
|
|
401
|
+
stats.Delivered += 1
|
|
402
|
+
stats.Failures = 0
|
|
403
|
+
stats.LastDeliveredAt = self.stats.LastDeliveredAt
|
|
404
|
+
stats.State = "Ready"
|
|
405
|
+
if header(res.Headers, "X-RateLimit-Remaining") == "0" then
|
|
406
|
+
lane.NotBefore = now + (tonumber(header(res.Headers, "X-RateLimit-Reset-After")) or 1)
|
|
407
|
+
end
|
|
408
|
+
continue
|
|
409
|
+
end
|
|
410
|
+
|
|
411
|
+
local status = res.Status
|
|
412
|
+
if status == 429 then
|
|
413
|
+
local delay = retryAfterSeconds(self, res)
|
|
414
|
+
lane.NotBefore = now + delay
|
|
415
|
+
self.stats.Retries += 1
|
|
416
|
+
continue
|
|
417
|
+
end
|
|
418
|
+
if status ~= nil and DEAD_STATUSES[status] then
|
|
419
|
+
local reason = `webhook refused with HTTP {status}`
|
|
420
|
+
if status == 403 and string.match(lane.Url, "^https://[%w%.%-]*discord%.com/") then
|
|
421
|
+
reason ..= "; Discord refuses requests from Roblox servers, so route the webhook through a proxy"
|
|
422
|
+
end
|
|
423
|
+
markDead(self, lane, reason)
|
|
424
|
+
return
|
|
425
|
+
end
|
|
426
|
+
if status ~= nil and MALFORMED_STATUSES[status] then
|
|
427
|
+
stats.LastError = `HTTP {status}: {shortBody(res.Body)}`
|
|
428
|
+
dropItem(self, lane, index, "Malformed")
|
|
429
|
+
continue
|
|
430
|
+
end
|
|
431
|
+
|
|
432
|
+
-- Transient; a timeout may have landed, hence Uncertain.
|
|
433
|
+
if res.Error ~= nil and string.find(string.lower(res.Error), "time", 1, true) then
|
|
434
|
+
self.stats.Uncertain += 1
|
|
435
|
+
end
|
|
436
|
+
stats.Failures += 1
|
|
437
|
+
stats.LastError = if status then `HTTP {status}` else shortBody(tostring(res.Error or "request failed"))
|
|
438
|
+
item.Attempts += 1
|
|
439
|
+
if item.Attempts >= limits.MaxAttempts then
|
|
440
|
+
dropItem(self, lane, index, "Exhausted")
|
|
441
|
+
continue
|
|
442
|
+
end
|
|
443
|
+
local backoff = math.min(limits.MaxRetryDelay, 2 ^ (item.Attempts - 1)) * (0.5 + self.deps.Jitter())
|
|
444
|
+
item.NotBefore = now + backoff
|
|
445
|
+
self.stats.Retries += 1
|
|
446
|
+
if item.NotBefore >= item.ExpiresAt then
|
|
447
|
+
dropItem(self, lane, index, "Expired")
|
|
448
|
+
end
|
|
449
|
+
end
|
|
450
|
+
end
|
|
451
|
+
|
|
452
|
+
--- Waits until every lane is empty, or `timeout` seconds. Returns whether it drained.
|
|
453
|
+
function Transport.Flush(self: any, timeout: number): boolean
|
|
454
|
+
local deadline = self.deps.Clock.Monotonic() + timeout
|
|
455
|
+
while self.running and self.queued > 0 do
|
|
456
|
+
if self.deps.Clock.Monotonic() >= deadline then
|
|
457
|
+
return false
|
|
458
|
+
end
|
|
459
|
+
self.deps.Scheduler.Wait(0.05)
|
|
460
|
+
end
|
|
461
|
+
return self.queued == 0
|
|
462
|
+
end
|
|
463
|
+
|
|
464
|
+
--- Stops delivery. Queued items are released; a request already in flight may complete,
|
|
465
|
+
--- but its result starts nothing.
|
|
466
|
+
function Transport.Stop(self: any)
|
|
467
|
+
if not self.running then
|
|
468
|
+
return
|
|
469
|
+
end
|
|
470
|
+
self.running = false
|
|
471
|
+
for _, lane in self.lanes do
|
|
472
|
+
while #lane.Queue > 0 do
|
|
473
|
+
dropItem(self, lane, 1, "Stopped")
|
|
474
|
+
end
|
|
475
|
+
end
|
|
476
|
+
for _, stats in self.destinations do
|
|
477
|
+
stats.State = "Stopped"
|
|
478
|
+
end
|
|
479
|
+
end
|
|
480
|
+
|
|
481
|
+
function Transport.Stats(self: any): Stats
|
|
482
|
+
local destinations = {}
|
|
483
|
+
for name, stats in self.destinations do
|
|
484
|
+
destinations[name] = table.clone(stats)
|
|
485
|
+
end
|
|
486
|
+
return {
|
|
487
|
+
Queued = self.queued,
|
|
488
|
+
QueuedBytes = self.queuedBytes,
|
|
489
|
+
Delivered = self.stats.Delivered,
|
|
490
|
+
Retries = self.stats.Retries,
|
|
491
|
+
Uncertain = self.stats.Uncertain,
|
|
492
|
+
Dropped = table.clone(self.stats.Dropped),
|
|
493
|
+
LastDeliveredAt = self.stats.LastDeliveredAt,
|
|
494
|
+
Destinations = destinations,
|
|
495
|
+
}
|
|
496
|
+
end
|
|
497
|
+
|
|
498
|
+
return Transport
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import type Scribe from "@rbxts/scribe";
|
|
2
|
+
|
|
3
|
+
/** Optional server-side diagnostics reporter. Importing it does not start reporting. */
|
|
4
|
+
declare namespace ScribeTelemetry {
|
|
5
|
+
const Version: string;
|
|
6
|
+
const LogoUrl: string;
|
|
7
|
+
const DefaultWarningCodes: readonly string[];
|
|
8
|
+
type LogEntry = Scribe.LogEntry;
|
|
9
|
+
|
|
10
|
+
type Category = "Health" | "Issues" | "Warnings" | "Performance" | "Summaries" | "Leaderboards";
|
|
11
|
+
type MentionKind = "Fatal" | "Error" | "Outage" | "Degraded" | "Recovery" | "Performance";
|
|
12
|
+
type Route<Destination extends string = string> = Destination | readonly Destination[] | false;
|
|
13
|
+
type PreviewKind =
|
|
14
|
+
| "All" | "Health" | "Issues" | "Warnings" | "Grouping" | "Performance" | "Leaderboards" | "Summaries" | "Formatting"
|
|
15
|
+
| "HealthyStartup" | "Degraded" | "Outage" | "PartialRecovery" | "Recovery" | "IncidentUnderway"
|
|
16
|
+
| "Warning" | "Error" | "Fatal" | "Repeat" | "UpstreamSuppressed"
|
|
17
|
+
| "SlowLoad" | "SlowLeavingHook" | "ReceiptCapacity" | "ReceiptRoutingRetry"
|
|
18
|
+
| "LeaderboardDegraded" | "LeaderboardRecovery"
|
|
19
|
+
| "SlowSaves" | "SlowSavesCleared" | "SaveFailures" | "SaveFailuresCleared" | "Traffic" | "TrafficCleared"
|
|
20
|
+
| "Summary" | "SummaryNoSamples" | "SummaryNoBudget" | "LongMessage" | "RedactedContext";
|
|
21
|
+
|
|
22
|
+
interface WebhookOptions {
|
|
23
|
+
Url: string;
|
|
24
|
+
Enabled?: boolean;
|
|
25
|
+
Mention?: { RoleId: string; On?: readonly MentionKind[]; Cooldown?: number };
|
|
26
|
+
}
|
|
27
|
+
interface RuleOptions {
|
|
28
|
+
/** Positive threshold; a rule has no default threshold. */
|
|
29
|
+
Threshold: number;
|
|
30
|
+
MinSamples?: number;
|
|
31
|
+
Enabled?: boolean;
|
|
32
|
+
}
|
|
33
|
+
interface RuleSetOptions {
|
|
34
|
+
SlowSaves?: RuleOptions;
|
|
35
|
+
SaveFailures?: RuleOptions;
|
|
36
|
+
Traffic?: RuleOptions;
|
|
37
|
+
}
|
|
38
|
+
interface WarningOptions { Include?: readonly string[]; Categories?: readonly string[] }
|
|
39
|
+
interface IssueOptions { ExcludeCodes?: readonly string[]; ExcludeCategories?: readonly string[] }
|
|
40
|
+
interface GroupingOptions { Interval?: number; Expiry?: number; MaxGroups?: number }
|
|
41
|
+
interface SummaryOptions { Enabled?: boolean; Interval?: number }
|
|
42
|
+
/** Observes cached leaderboard snapshots; never requests a leaderboard refresh. */
|
|
43
|
+
interface LeaderboardOptions { Enabled?: boolean; Interval?: number; MaxBoards?: number }
|
|
44
|
+
interface PerformanceOptions { Interval?: number; Checks?: number; Rules?: RuleSetOptions }
|
|
45
|
+
interface LimitOptions {
|
|
46
|
+
MaxQueued?: number;
|
|
47
|
+
MaxQueuedBytes?: number;
|
|
48
|
+
PerDestination?: number;
|
|
49
|
+
MaxAge?: number;
|
|
50
|
+
MaxAttempts?: number;
|
|
51
|
+
MaxRetryDelay?: number;
|
|
52
|
+
}
|
|
53
|
+
interface HttpResponse {
|
|
54
|
+
Ok: boolean;
|
|
55
|
+
Status?: number;
|
|
56
|
+
Headers?: { [name: string]: string | undefined };
|
|
57
|
+
Body?: string;
|
|
58
|
+
Error?: string;
|
|
59
|
+
}
|
|
60
|
+
interface Http { readonly Post: (this: void, url: string, body: string) => HttpResponse }
|
|
61
|
+
interface Clock { readonly Now: (this: void) => number; readonly Monotonic: (this: void) => number }
|
|
62
|
+
interface Scheduler { readonly Spawn: (this: void, callback: (this: void) => void) => void; readonly Wait: (this: void, seconds: number) => void }
|
|
63
|
+
interface Json { readonly Encode: (this: void, value: unknown) => string; readonly Decode: (this: void, text: string) => unknown }
|
|
64
|
+
|
|
65
|
+
interface Options<Destination extends string = string> {
|
|
66
|
+
Webhooks: { [K in Destination]: WebhookOptions };
|
|
67
|
+
Default?: NoInfer<Destination>;
|
|
68
|
+
Routes?: Partial<Record<Category, Route<NoInfer<Destination>>>>;
|
|
69
|
+
Warnings?: WarningOptions;
|
|
70
|
+
Issues?: IssueOptions;
|
|
71
|
+
Grouping?: GroupingOptions;
|
|
72
|
+
Summaries?: SummaryOptions;
|
|
73
|
+
Leaderboards?: LeaderboardOptions;
|
|
74
|
+
Performance?: PerformanceOptions;
|
|
75
|
+
Limits?: LimitOptions;
|
|
76
|
+
IncludePlayerIds?: boolean;
|
|
77
|
+
Environment?: string;
|
|
78
|
+
AllowStudio?: boolean;
|
|
79
|
+
ReportHealthyStartup?: boolean;
|
|
80
|
+
/** Dependency seams for tests. Omit in normal game code. */
|
|
81
|
+
Http?: Http;
|
|
82
|
+
Clock?: Clock;
|
|
83
|
+
Scheduler?: Scheduler;
|
|
84
|
+
Json?: Json;
|
|
85
|
+
Jitter?: (this: void) => number;
|
|
86
|
+
Studio?: boolean;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
interface Dropped {
|
|
90
|
+
Overflow: number;
|
|
91
|
+
Expired: number;
|
|
92
|
+
Malformed: number;
|
|
93
|
+
DeadDestination: number;
|
|
94
|
+
Exhausted: number;
|
|
95
|
+
Stopped: number;
|
|
96
|
+
Coalesced: number;
|
|
97
|
+
}
|
|
98
|
+
interface DestinationStats {
|
|
99
|
+
State: "Ready" | "Dead" | "Stopped";
|
|
100
|
+
Queued: number;
|
|
101
|
+
Delivered: number;
|
|
102
|
+
Failures: number;
|
|
103
|
+
LastDeliveredAt?: number;
|
|
104
|
+
LastError?: string;
|
|
105
|
+
}
|
|
106
|
+
type LeaderboardMonitorState = "Available" | "Unavailable" | "Disabled" | "DisabledInStudio" | "Stopped";
|
|
107
|
+
interface LeaderboardStats {
|
|
108
|
+
State: LeaderboardMonitorState;
|
|
109
|
+
Monitored: number;
|
|
110
|
+
Omitted: number;
|
|
111
|
+
SnapshotAge?: number;
|
|
112
|
+
LastError?: string;
|
|
113
|
+
}
|
|
114
|
+
interface Stats<Destination extends string = string> {
|
|
115
|
+
State: "Running" | "DisabledInStudio" | "Stopped";
|
|
116
|
+
Queued: number;
|
|
117
|
+
QueuedBytes: number;
|
|
118
|
+
Delivered: number;
|
|
119
|
+
Retries: number;
|
|
120
|
+
Uncertain: number;
|
|
121
|
+
Dropped: Dropped;
|
|
122
|
+
LastDeliveredAt?: number;
|
|
123
|
+
/** Empty when disabled in Studio; entries must be checked before reading. */
|
|
124
|
+
Destinations: Partial<Record<Destination, DestinationStats>>;
|
|
125
|
+
Reports: number;
|
|
126
|
+
Previews: number;
|
|
127
|
+
Skipped: Partial<Record<Category, number>>;
|
|
128
|
+
Filtered: { Issues: number; Warnings: number; Ignored: number };
|
|
129
|
+
Groups: number;
|
|
130
|
+
EncodeFailures: number;
|
|
131
|
+
LastTickError?: string;
|
|
132
|
+
Leaderboards: LeaderboardStats;
|
|
133
|
+
}
|
|
134
|
+
interface Handle<Destination extends string = string> {
|
|
135
|
+
Test(destination: Destination): LuaTuple<[boolean, string | undefined]>;
|
|
136
|
+
Preview(destination: Destination, kind?: PreviewKind): LuaTuple<[boolean, string | undefined]>;
|
|
137
|
+
Flush(timeout?: number): boolean;
|
|
138
|
+
GetStats(): Stats<Destination>;
|
|
139
|
+
Stop(): void;
|
|
140
|
+
}
|
|
141
|
+
type ScribeModule = Pick<typeof Scribe,
|
|
142
|
+
"AddLogSink" | "GetStatus" | "GetMetrics" | "GetPercentiles"
|
|
143
|
+
> & { readonly OnStatusChanged: Pick<typeof Scribe.OnStatusChanged, "Connect"> }
|
|
144
|
+
& Partial<Pick<typeof Scribe, "Version" | "GetBudgetSnapshot" | "GetLeaderboardSnapshot" | "GetProfileKeyPrefix" | "RegisterAddon">>;
|
|
145
|
+
|
|
146
|
+
/** One handle may run per Scribe module. Stop the previous handle before starting another. */
|
|
147
|
+
function Start<Destination extends string>(scribe: ScribeModule, options: Options<Destination>): Handle<Destination>;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
export = ScribeTelemetry;
|