@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/Router.luau ADDED
@@ -0,0 +1,152 @@
1
+ --!strict
2
+ -- Groups repeated reports: the first goes out at once, later ones fold into one
3
+ -- follow-up per interval, and the group set stays bounded.
4
+
5
+ local Router = {}
6
+ Router.__index = Router
7
+
8
+ export type Record = {
9
+ Category: string,
10
+ Kind: string,
11
+ Severity: string,
12
+ Code: string,
13
+ LogCategory: string,
14
+ Subject: string?,
15
+ Message: string,
16
+ Context: { [string]: any }?,
17
+ Repeats: number, -- upstream suppression the entry itself reported
18
+ At: number,
19
+ }
20
+
21
+ export type Group = {
22
+ Key: string,
23
+ Sample: Record,
24
+ FirstAt: number,
25
+ LatestAt: number,
26
+ Count: number, -- occurrences observed by the add-on since the group opened
27
+ WindowCount: number, -- since the last follow-up
28
+ Upstream: number, -- upstream repeats reported since the last follow-up
29
+ SummaryDue: number?,
30
+ LastSeen: number,
31
+ Touched: number, -- offer sequence at the last occurrence; breaks ties in LastSeen
32
+ }
33
+
34
+ export type Callbacks = {
35
+ First: (record: Record) -> (),
36
+ Summary: (group: Group) -> (),
37
+ }
38
+
39
+ function Router.new(interval: number, expiry: number, maxGroups: number, monotonic: () -> number, callbacks: Callbacks)
40
+ local self = setmetatable({}, Router)
41
+ self.interval = interval
42
+ self.expiry = expiry
43
+ self.maxGroups = maxGroups
44
+ self.monotonic = monotonic
45
+ self.callbacks = callbacks
46
+ self.groups = {} :: { [string]: Group }
47
+ self.count = 0
48
+ self.evicted = 0
49
+ self.offers = 0
50
+ return self
51
+ end
52
+
53
+ function Router.Key(record: Record): string
54
+ return `{record.Category}|{record.Code}|{record.LogCategory}|{record.Subject or ""}`
55
+ end
56
+
57
+ local function summarise(self: any, group: Group)
58
+ if group.WindowCount > 0 then
59
+ self.callbacks.Summary(group)
60
+ group.WindowCount = 0
61
+ group.Upstream = 0
62
+ end
63
+ group.SummaryDue = nil
64
+ end
65
+
66
+ local function remove(self: any, key: string)
67
+ if self.groups[key] ~= nil then
68
+ self.groups[key] = nil
69
+ self.count -= 1
70
+ end
71
+ end
72
+
73
+ -- Least recently seen first, ties by offer sequence rather than hash order; its
74
+ -- follow-up goes out before it is dropped.
75
+ local function evictOne(self: any)
76
+ local oldestKey: string? = nil
77
+ local oldest = math.huge
78
+ for key, group in self.groups do
79
+ if group.Touched < oldest then
80
+ oldest, oldestKey = group.Touched, key
81
+ end
82
+ end
83
+ if oldestKey ~= nil then
84
+ summarise(self, self.groups[oldestKey])
85
+ remove(self, oldestKey)
86
+ self.evicted += 1
87
+ end
88
+ end
89
+
90
+ --- Offers a record. The first of its kind is reported now; a repetition waits for the
91
+ --- group's follow-up.
92
+ function Router.Offer(self: any, record: Record)
93
+ local key = Router.Key(record)
94
+ local now = self.monotonic()
95
+ self.offers += 1
96
+ local group: Group? = self.groups[key]
97
+ if group ~= nil and now - group.LastSeen > self.expiry then
98
+ summarise(self, group)
99
+ remove(self, key)
100
+ group = nil
101
+ end
102
+ if group == nil then
103
+ if self.count >= self.maxGroups then
104
+ evictOne(self)
105
+ end
106
+ group = {
107
+ Key = key,
108
+ Sample = record,
109
+ FirstAt = record.At,
110
+ LatestAt = record.At,
111
+ Count = 1,
112
+ WindowCount = 0,
113
+ Upstream = 0,
114
+ SummaryDue = now + self.interval,
115
+ LastSeen = now,
116
+ Touched = self.offers,
117
+ }
118
+ self.groups[key] = group
119
+ self.count += 1
120
+ self.callbacks.First(record)
121
+ return
122
+ end
123
+ group.Count += 1
124
+ group.WindowCount += 1
125
+ group.LatestAt = record.At
126
+ group.Upstream += record.Repeats
127
+ group.LastSeen = now
128
+ group.Touched = self.offers
129
+ if group.SummaryDue == nil then
130
+ group.SummaryDue = now + self.interval
131
+ end
132
+ end
133
+
134
+ --- Sends the follow-ups whose interval has passed and forgets groups gone quiet.
135
+ function Router.Tick(self: any)
136
+ local now = self.monotonic()
137
+ for key, group in self.groups do
138
+ if group.SummaryDue ~= nil and group.SummaryDue <= now then
139
+ summarise(self, group)
140
+ end
141
+ if group.SummaryDue == nil and now - group.LastSeen > self.expiry then
142
+ remove(self, key)
143
+ end
144
+ end
145
+ end
146
+
147
+ function Router.Clear(self: any)
148
+ table.clear(self.groups)
149
+ self.count = 0
150
+ end
151
+
152
+ return Router
package/Sanitize.luau ADDED
@@ -0,0 +1,265 @@
1
+ --!strict
2
+ -- Small plain data safe to serialize: bounded UTF-8 strings, webhook URLs and player
3
+ -- identifiers redacted, no functions, threads or Roblox objects.
4
+
5
+ local Sanitize = {}
6
+
7
+ local ELLIPSIS = "\u{2026}"
8
+ local ELLIPSIS_BYTES = #ELLIPSIS
9
+ local MAX_INPUT_BYTES = 4096
10
+ local OVERSIZED_TEXT = "[oversized text omitted]"
11
+
12
+ export type Options = {
13
+ IncludePlayerIds: boolean?,
14
+ Urls: { string }?, -- configured endpoint URLs, redacted wherever they appear
15
+ KeyPrefix: string?, -- the profile key prefix; it and the digits after it are redacted
16
+ }
17
+
18
+ local function escapePattern(s: string): string
19
+ return (string.gsub(s, "[%^%$%(%)%%%.%[%]%*%+%-%?]", "%%%0"))
20
+ end
21
+
22
+ -- A profile key may carry any prefix or none, so a key field is redacted whatever it holds.
23
+ local function isKeyField(name: string): boolean
24
+ return name == "Key" or string.match(name, "%wKey$") ~= nil
25
+ end
26
+
27
+ -- A stable stand-in, so reports about one key still group without naming it.
28
+ local function digest(s: string): string
29
+ local h = 5381
30
+ for i = 1, #s do
31
+ h = (h * 33 + string.byte(s, i)) % 16777216
32
+ end
33
+ return string.format("%06x", h)
34
+ end
35
+
36
+ --- Cuts `s` to at most `maxBytes` bytes without splitting a UTF-8 sequence, ending in an
37
+ --- ellipsis when it was cut.
38
+ function Sanitize.Truncate(s: string, maxBytes: number): string
39
+ if #s <= maxBytes then
40
+ return s
41
+ end
42
+ if maxBytes <= 0 then
43
+ return ""
44
+ end
45
+ if maxBytes < ELLIPSIS_BYTES then
46
+ return string.sub("...", 1, maxBytes)
47
+ end
48
+ local keep = math.max(0, maxBytes - ELLIPSIS_BYTES)
49
+ -- Back up off any continuation byte so the cut lands on a character boundary.
50
+ while keep > 0 do
51
+ local byte = string.byte(s, keep + 1)
52
+ if byte == nil or byte < 0x80 or byte >= 0xC0 then
53
+ break
54
+ end
55
+ keep -= 1
56
+ end
57
+ return string.sub(s, 1, keep) .. ELLIPSIS
58
+ end
59
+
60
+ -- Any host with Discord's path carries a token, configured or not.
61
+ local WEBHOOK_PATTERNS = {
62
+ "https?://[%w%.%-]+/api/webhooks/%S+",
63
+ }
64
+
65
+ local function redactUrls(s: string, urls: { string }?): string
66
+ if urls == nil then
67
+ return s
68
+ end
69
+ for _, url in urls do
70
+ local start = 1
71
+ while true do
72
+ local i, j = string.find(s, url, start, true)
73
+ if i == nil or j == nil then
74
+ break
75
+ end
76
+ s = string.sub(s, 1, i - 1) .. "[webhook url]" .. string.sub(s, j + 1)
77
+ start = i + #"[webhook url]"
78
+ end
79
+ end
80
+ return s
81
+ end
82
+
83
+ -- Identifiers a report may not carry unless the developer opted in.
84
+ local PLAYER_KEY_PATTERNS =
85
+ { "[Uu]ser[Ii][Dd]$", "[Pp]layer[Ii][Dd]$", "^[Pp]layer$", "^Recipient[Ii][Dd]$", "^Buyer[Ii][Dd]$" }
86
+ local PLAYER_PATTERNS = {
87
+ { "([Uu]ser[Ii][Dd]%s*[=:]%s*)%d+", "%1[player]" },
88
+ { "([Pp]layer%s*[=:]%s*)%d+", "%1[player]" },
89
+ }
90
+
91
+ local function isLetter(byte: number): boolean
92
+ return (byte >= 65 and byte <= 90) or (byte >= 97 and byte <= 122)
93
+ end
94
+
95
+ local function isDigit(byte: number): boolean
96
+ return byte >= 48 and byte <= 57
97
+ end
98
+
99
+ local function isWord(byte: number): boolean
100
+ return isLetter(byte) or isDigit(byte)
101
+ end
102
+
103
+ -- Scan each prefix once; hyphens must not restart a failing suffix search.
104
+ local function redactProfileKeys(s: string): string
105
+ local parts = {}
106
+ local length = #s
107
+ local index, copied = 1, 1
108
+ while index <= length do
109
+ local byte = string.byte(s, index)
110
+ if not isWord(byte) and byte ~= 45 then
111
+ index += 1
112
+ continue
113
+ end
114
+ local eligible = false
115
+ local previous = if index > 1 then string.byte(s, index - 1) else 0
116
+ repeat
117
+ if isLetter(byte) and not isWord(previous) then
118
+ eligible = true
119
+ end
120
+ previous = byte
121
+ index += 1
122
+ byte = if index <= length then string.byte(s, index) else 0
123
+ until not isWord(byte) and byte ~= 45
124
+ if eligible and byte == 95 and index < length and isDigit(string.byte(s, index + 1)) then
125
+ table.insert(parts, string.sub(s, copied, index))
126
+ table.insert(parts, "[player]")
127
+ index += 2
128
+ while index <= length and isDigit(string.byte(s, index)) do
129
+ index += 1
130
+ end
131
+ copied = index
132
+ end
133
+ end
134
+ if #parts == 0 then
135
+ return s
136
+ end
137
+ table.insert(parts, string.sub(s, copied))
138
+ return table.concat(parts)
139
+ end
140
+
141
+ --- A string the report may carry: control characters dropped, webhook URLs and (unless
142
+ --- allowed) player identifiers redacted, bounded to `maxBytes`.
143
+ function Sanitize.Text(value: any, maxBytes: number, options: Options?): string
144
+ local s = if type(value) == "string" then value else tostring(value)
145
+ if #s > MAX_INPUT_BYTES then
146
+ return Sanitize.Truncate(OVERSIZED_TEXT, maxBytes)
147
+ end
148
+ s = string.gsub(s, "[%c]", function(c)
149
+ return if c == "\n" or c == "\t" then c else ""
150
+ end)
151
+ s = redactUrls(s, if options then options.Urls else nil)
152
+ for _, pattern in WEBHOOK_PATTERNS do
153
+ s = string.gsub(s, pattern, "[webhook url]")
154
+ end
155
+ if not (options and options.IncludePlayerIds) then
156
+ for _, rule in PLAYER_PATTERNS do
157
+ s = string.gsub(s, rule[1], rule[2])
158
+ end
159
+ s = redactProfileKeys(s)
160
+ local prefix = if options then options.KeyPrefix else nil
161
+ if prefix ~= nil and prefix ~= "" and prefix ~= "PLAYER_" then
162
+ s = string.gsub(s, escapePattern(prefix) .. "%d+", string.gsub(prefix, "%%", "%%%%") .. "[player]")
163
+ end
164
+ end
165
+ return Sanitize.Truncate(s, maxBytes)
166
+ end
167
+
168
+ local MAX_KEYS = 12
169
+ local MAX_DEPTH = 2
170
+ local MAX_VALUE_BYTES = 200
171
+
172
+ local function isFinite(n: number): boolean
173
+ return n == n and n ~= math.huge and n ~= -math.huge
174
+ end
175
+
176
+ local function snapshot(value: any, depth: number, options: Options?): any
177
+ local t = typeof(value)
178
+ if t == "string" then
179
+ return Sanitize.Text(value, MAX_VALUE_BYTES, options)
180
+ elseif t == "number" then
181
+ return if isFinite(value) then value else tostring(value)
182
+ elseif t == "boolean" then
183
+ return value
184
+ elseif t == "Instance" then
185
+ if value:IsA("Player") then
186
+ return if options and options.IncludePlayerIds then `Player:{value.UserId}` else "[player]"
187
+ end
188
+ return `{value.ClassName}:{Sanitize.Text(value.Name, 64, options)}`
189
+ elseif t == "table" then
190
+ if depth >= MAX_DEPTH then
191
+ return "[table]"
192
+ end
193
+ local out: { [string]: any } = {}
194
+ local visited = 0
195
+ for key, child in value do
196
+ if visited >= MAX_KEYS then
197
+ out["..."] = "more keys omitted"
198
+ break
199
+ end
200
+ visited += 1
201
+ local keyText = if type(key) == "string" then key else tostring(key)
202
+ if #keyText > MAX_INPUT_BYTES then
203
+ out[OVERSIZED_TEXT] = OVERSIZED_TEXT
204
+ continue
205
+ end
206
+ local snap = snapshot(child, depth + 1, options)
207
+ if snap ~= nil and not (options and options.IncludePlayerIds) and type(child) ~= "table" then
208
+ for _, pattern in PLAYER_KEY_PATTERNS do
209
+ if string.match(keyText, pattern) then
210
+ snap = "[player]"
211
+ break
212
+ end
213
+ end
214
+ if isKeyField(keyText) then
215
+ snap = "[key]"
216
+ end
217
+ end
218
+ if snap ~= nil then
219
+ out[Sanitize.Text(keyText, 64, options)] = snap
220
+ end
221
+ end
222
+ return out
223
+ end
224
+ return nil
225
+ end
226
+
227
+ --- A small plain-data copy of a context table: at most 12 keys, two levels, scalars only.
228
+ function Sanitize.Snapshot(context: any, options: Options?): { [string]: any }?
229
+ if type(context) ~= "table" then
230
+ return nil
231
+ end
232
+ local snap = snapshot(context, 0, options)
233
+ return if type(snap) == "table" then snap else nil
234
+ end
235
+
236
+ --- A bounded subject for grouping: the key or user a context names, or nil.
237
+ function Sanitize.Subject(context: any, options: Options?): string?
238
+ if type(context) ~= "table" then
239
+ return nil
240
+ end
241
+ local player = context.Player
242
+ if typeof(player) == "Instance" and player:IsA("Player") then
243
+ return if options and options.IncludePlayerIds then `user:{player.UserId}` else "[player]"
244
+ end
245
+ for _, field in { "UserId", "Key", "Board", "Product", "ProductId", "Subject" } do
246
+ local value = context[field]
247
+ if type(value) == "string" or type(value) == "number" then
248
+ local text = Sanitize.Text(value, 48, options)
249
+ if not (options and options.IncludePlayerIds) then
250
+ if field == "UserId" then
251
+ return "[player]"
252
+ elseif field == "Key" then
253
+ if type(value) == "string" and #value > MAX_INPUT_BYTES then
254
+ return `key:{OVERSIZED_TEXT}`
255
+ end
256
+ return `key:#{digest(tostring(value))}`
257
+ end
258
+ end
259
+ return `{string.lower(field)}:{text}`
260
+ end
261
+ end
262
+ return nil
263
+ end
264
+
265
+ return Sanitize
@@ -0,0 +1 @@
1
+ {"version":"2.5.0","format":1,"description":"Segments are [packedLine, sourceLine]. Use the last segment at or before the packed line, then add its line offset.","files":{"addons/telemetry/ScribeTelemetry/Config.luau":{"sourceSha256":"d5dde0539ce46b19d360f8807e83597af4954e6c2d872b1460e05212d119e446","packedSha256":"d2c9b8060f2c26bcf59436e209f39a65c9ed69c167eb81930859826ab63dc10c","segments":[[1,1]],"packagePath":"Config.luau"},"addons/telemetry/ScribeTelemetry/Diagnostics.luau":{"sourceSha256":"9129893f4669dcb9c2e8732983298bbe038eb60f75588fb48ddbd23b94999804","packedSha256":"81d2b4ddb797654a4643a7161408fd4040a9057d2f267a4f143fad5876e03780","segments":[[1,1]],"packagePath":"Diagnostics.luau"},"addons/telemetry/ScribeTelemetry/Format.luau":{"sourceSha256":"e942761f4c0ed2ca7efd32f1c87090310a8243d0e3f8c7cfd4b5e3015ce8dde9","packedSha256":"d2b7917dd2518e838bab3ac0d819420d6b93bf488e68f9ca3764d7720f57fa2f","segments":[[1,1]],"packagePath":"Format.luau"},"addons/telemetry/ScribeTelemetry/init.luau":{"sourceSha256":"a39a824446a5655f60eb1bc494aa7a310250b430228f9a1621589071bff355e0","packedSha256":"c56865b17804aa6601c91dc7abba3b40f3789e7a25a1ddecf7c3bcb5c64f0837","segments":[[1,1]],"packagePath":"init.luau"},"addons/telemetry/ScribeTelemetry/LeaderboardMonitor.luau":{"sourceSha256":"fffe6f9ade2e2311c4dc016969e6555e8bd6c87563078e05df061537a70074fc","packedSha256":"25dd1f55847e94f3b5d46074008fca3141196eb35e3ed5a083038bd7a83fa1fd","segments":[[1,1]],"packagePath":"LeaderboardMonitor.luau"},"addons/telemetry/ScribeTelemetry/Preview.luau":{"sourceSha256":"fa4227567451f7271d164fb462b881f7393aafc24aa880cb4038289b962a2ff3","packedSha256":"e5e5813ab3b8e24c181ebf8c7ac7d18d1d2183b2d1af95cff248ee754870ae6e","segments":[[1,1]],"packagePath":"Preview.luau"},"addons/telemetry/ScribeTelemetry/Router.luau":{"sourceSha256":"c493f820ef204a7e839c13ba448688a3b24a7b08571dfba23b64a47df204a912","packedSha256":"f45b51bde5e33b2de1ab23338518caec54a1a4a8b642a3eff3e5b11d0669adb9","segments":[[1,1]],"packagePath":"Router.luau"},"addons/telemetry/ScribeTelemetry/Sanitize.luau":{"sourceSha256":"17d18395b8a43ef2e2ef67564e89cc48952ab9c00fd93cb2c06e6e6ebdf206ff","packedSha256":"41846d913c9ee350053778121521e2aca3fbd53e3845d4394e79bfededfefd5c","segments":[[1,1]],"packagePath":"Sanitize.luau"},"addons/telemetry/ScribeTelemetry/Transport.luau":{"sourceSha256":"3750e626a480c5a0185fdbe887743621c99532c2d6f0472f982d7e3c5612f241","packedSha256":"ac306390638dc90cbe097b6d037ac5cf88c8b7882f82efd741628ea4b48c05cf","segments":[[1,1]],"packagePath":"Transport.luau"}}}