devfortress-sdk 0.1.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.
Files changed (39) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +4 -0
  3. data/Gemfile +7 -0
  4. data/LICENSE +63 -0
  5. data/README.md +121 -0
  6. data/Rakefile +11 -0
  7. data/lib/devfortress/agent_adapter.rb +185 -0
  8. data/lib/devfortress/agent_loop_detector.rb +167 -0
  9. data/lib/devfortress/agent_output_exfiltration_detector.rb +115 -0
  10. data/lib/devfortress/agent_security.rb +431 -0
  11. data/lib/devfortress/alias_verify.rb +87 -0
  12. data/lib/devfortress/api_key_aliasing.rb +240 -0
  13. data/lib/devfortress/bounded_map.rb +80 -0
  14. data/lib/devfortress/circuit_breaker.rb +149 -0
  15. data/lib/devfortress/classifier.rb +133 -0
  16. data/lib/devfortress/client.rb +380 -0
  17. data/lib/devfortress/client_ip.rb +28 -0
  18. data/lib/devfortress/clock_drift_detector.rb +71 -0
  19. data/lib/devfortress/credential_isolation.rb +340 -0
  20. data/lib/devfortress/credential_vault.rb +93 -0
  21. data/lib/devfortress/delivery_result.rb +9 -0
  22. data/lib/devfortress/graduated_rate_limiter.rb +270 -0
  23. data/lib/devfortress/internal_closed_loop_engine.rb +658 -0
  24. data/lib/devfortress/license_manager.rb +297 -0
  25. data/lib/devfortress/observer.rb +62 -0
  26. data/lib/devfortress/prompt_injection_filter.rb +73 -0
  27. data/lib/devfortress/response_webhook_client.rb +165 -0
  28. data/lib/devfortress/shadow_agent_registry.rb +123 -0
  29. data/lib/devfortress/signer.rb +134 -0
  30. data/lib/devfortress/telemetry.rb +407 -0
  31. data/lib/devfortress/tier_gate.rb +294 -0
  32. data/lib/devfortress/tool_call_sequence_validator.rb +126 -0
  33. data/lib/devfortress/transport.rb +31 -0
  34. data/lib/devfortress/unified_audit_trail.rb +213 -0
  35. data/lib/devfortress/version.rb +5 -0
  36. data/lib/devfortress/webhook_verification.rb +9 -0
  37. data/lib/devfortress/webhook_verifier.rb +93 -0
  38. data/lib/devfortress.rb +96 -0
  39. metadata +110 -0
@@ -0,0 +1,123 @@
1
+ # frozen_string_literal: true
2
+
3
+ module DevFortress
4
+ # Shadow Agent Registry (B10).
5
+ #
6
+ # Detects and tracks unauthorized ("shadow") AI agents that operate
7
+ # without proper registration. Maintains a registry of known agents and
8
+ # flags unregistered agent-like behavior. Mirrors
9
+ # packages/devfortress-sdk/src/shadow-agent-registry.ts.
10
+ class ShadowAgentRegistry
11
+ DEFAULT_AGENT_PATTERNS = [
12
+ "automated request pattern (>100 req/min)",
13
+ "consistent timing between requests (<50ms variance)",
14
+ "sequential resource enumeration",
15
+ "user-agent indicates bot/automation",
16
+ "no mouse/keyboard entropy in session",
17
+ "API-only access (no page loads)",
18
+ ].freeze
19
+
20
+ def initialize(heartbeat_timeout_seconds: 300, agent_patterns: nil, auto_block: false)
21
+ @heartbeat_timeout_seconds = heartbeat_timeout_seconds
22
+ @agent_patterns = agent_patterns || DEFAULT_AGENT_PATTERNS
23
+ @auto_block = auto_block
24
+ @registry = {}
25
+ @shadow_detections = {}
26
+ @stats = { registered_count: 0, active_count: 0, shadow_detections: 0, blocked_shadows: 0 }
27
+ end
28
+
29
+ # Registers a known agent. agent: a Hash with :agent_id, :name, :owner,
30
+ # :permissions (symbol keys) — :registered_at/:last_heartbeat/:active
31
+ # are set here, not supplied by the caller.
32
+ def register(agent)
33
+ if ENV["FEATURE_PLATFORM_INTEL"] == "false"
34
+ return agent.merge(registered_at: 0, last_heartbeat: 0, active: false)
35
+ end
36
+
37
+ registered = agent.merge(registered_at: now_ms, last_heartbeat: now_ms, active: true)
38
+ @registry[agent[:agent_id]] = registered
39
+ @stats[:registered_count] += 1
40
+ @stats[:active_count] += 1
41
+ registered
42
+ end
43
+
44
+ # Records a heartbeat from a registered agent.
45
+ def heartbeat(agent_id)
46
+ agent = @registry[agent_id]
47
+ return false unless agent
48
+
49
+ agent[:last_heartbeat] = now_ms
50
+ agent[:active] = true
51
+ true
52
+ end
53
+
54
+ # Checks whether a request source is a registered agent or a shadow.
55
+ def detect(fingerprint, indicators)
56
+ if ENV["FEATURE_PLATFORM_INTEL"] == "false"
57
+ return { detected: false, agent_fingerprint: fingerprint, indicators: [], confidence: 0,
58
+ recommendation: "monitor", matched_patterns: [] }
59
+ end
60
+
61
+ # Check if any registered agent matches this fingerprint
62
+ @registry.each_value do |agent|
63
+ if agent[:agent_id] == fingerprint && agent[:active]
64
+ return { detected: false, agent_fingerprint: fingerprint, indicators: [], confidence: 0,
65
+ recommendation: "monitor", matched_patterns: [] }
66
+ end
67
+ end
68
+
69
+ # Check indicators against known agent patterns
70
+ matched_patterns = @agent_patterns.select do |pattern|
71
+ pattern_key = pattern.split("(").first.strip.downcase
72
+ indicators.any? { |i| i.downcase.include?(pattern_key) }
73
+ end
74
+
75
+ confidence = [1, matched_patterns.length / 3.0].min
76
+ detected = confidence > 0.3
77
+
78
+ if detected
79
+ @stats[:shadow_detections] += 1
80
+ @stats[:blocked_shadows] += 1 if @auto_block && confidence > 0.7
81
+ end
82
+
83
+ result = {
84
+ detected: detected,
85
+ agent_fingerprint: fingerprint,
86
+ indicators: indicators,
87
+ confidence: confidence,
88
+ recommendation: confidence > 0.7 ? (@auto_block ? "block" : "register") : "monitor",
89
+ matched_patterns: matched_patterns,
90
+ }
91
+ @shadow_detections[fingerprint] = result if detected
92
+ result
93
+ end
94
+
95
+ # Prunes inactive agents (no heartbeat within the configured timeout).
96
+ def prune_inactive
97
+ cutoff = now_ms - (@heartbeat_timeout_seconds * 1000)
98
+ pruned = []
99
+ @registry.each do |id, agent|
100
+ if agent[:last_heartbeat] < cutoff
101
+ agent[:active] = false
102
+ @stats[:active_count] -= 1
103
+ pruned << id
104
+ end
105
+ end
106
+ pruned
107
+ end
108
+
109
+ def stats
110
+ @stats.dup
111
+ end
112
+
113
+ def registered
114
+ @registry.values
115
+ end
116
+
117
+ private
118
+
119
+ def now_ms
120
+ (Time.now.to_f * 1000).to_i
121
+ end
122
+ end
123
+ end
@@ -0,0 +1,134 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+ require "openssl"
5
+ require "securerandom"
6
+
7
+ module DevFortress
8
+ # Request integrity headers for every SDK-to-platform call (contract v2).
9
+ #
10
+ # Canonical string: "{METHOD}.{requestTarget}.{timestamp}.{nonce}.{payloadHash}"
11
+ # where METHOD is the uppercase HTTP method, requestTarget is the URL path plus
12
+ # "?query" exactly as sent (no host, no re-encoding), and payloadHash is the
13
+ # lowercase hex SHA-256 of the exact body bytes (the empty string for a request
14
+ # with no body). The signature is the lowercase hex HMAC-SHA256 of that string,
15
+ # keyed with the project API key (UTF-8). The timestamp is Unix epoch
16
+ # milliseconds; the nonce is a dashed UUID v4, fresh for every request attempt.
17
+ # Tolerance is 300 seconds.
18
+ #
19
+ # The API key never travels on a signed request. X-DevFortress-Key-Id is a
20
+ # non-secret identifier derived from the key (first 32 hex characters of its
21
+ # SHA-256); the platform verifies the HMAC with the key it has stored.
22
+ class Signer
23
+ SIGNATURE_VERSION = "2"
24
+ TOLERANCE_SECONDS = 300
25
+
26
+ KEY_ID_HEADER = "X-DevFortress-Key-Id"
27
+ VERSION_HEADER = "X-DevFortress-Signature-Version"
28
+ NONCE_HEADER = "X-DevFortress-Nonce"
29
+ TIMESTAMP_HEADER = "X-DevFortress-Timestamp"
30
+ PAYLOAD_HASH_HEADER = "X-DevFortress-Payload-Hash"
31
+ SIGNATURE_HEADER = "X-DevFortress-Signature"
32
+
33
+ class Error < StandardError; end
34
+
35
+ def initialize(api_key)
36
+ raise Error, "DevFortress: an API key is required" if api_key.nil? || api_key.empty?
37
+
38
+ @api_key = api_key
39
+ end
40
+
41
+ # Non-secret key ID: first 32 hex characters of SHA-256 over the UTF-8 key.
42
+ def self.derive_key_id(api_key)
43
+ Digest::SHA256.hexdigest(api_key)[0, 32]
44
+ end
45
+
46
+ def key_id
47
+ self.class.derive_key_id(@api_key)
48
+ end
49
+
50
+ # Returns the six signing headers (key ID, version, nonce, timestamp, hash, signature).
51
+ def sign(method, request_target, body, timestamp: nil, nonce: nil)
52
+ ts = timestamp || self.class.now_ms
53
+ n = nonce || self.class.uuid_v4
54
+ digest = self.class.digest(@api_key, method, request_target, ts, n, body)
55
+
56
+ {
57
+ KEY_ID_HEADER => key_id,
58
+ VERSION_HEADER => SIGNATURE_VERSION,
59
+ NONCE_HEADER => n,
60
+ TIMESTAMP_HEADER => ts,
61
+ PAYLOAD_HASH_HEADER => digest[:payload_hash],
62
+ SIGNATURE_HEADER => digest[:signature],
63
+ }
64
+ end
65
+
66
+ # Returns "valid", "invalid", "expired", "missing" or "unsupported_version".
67
+ #
68
+ # +headers+ uses the wire header names. Mirrors the platform's check.
69
+ def self.verify(api_key, method, request_target, body, headers, now_ms: nil)
70
+ nonce = headers[NONCE_HEADER]
71
+ ts = headers[TIMESTAMP_HEADER]
72
+ payload_hash = headers[PAYLOAD_HASH_HEADER]
73
+ signature = headers[SIGNATURE_HEADER]
74
+ if blank?(nonce) || blank?(ts) || blank?(payload_hash) || blank?(signature)
75
+ return "missing"
76
+ end
77
+ return "unsupported_version" unless headers[VERSION_HEADER] == SIGNATURE_VERSION
78
+
79
+ expected = digest(api_key, method, request_target, ts, nonce, body)
80
+ hash_ok = secure_compare(expected[:payload_hash], payload_hash.downcase)
81
+ sig_ok = secure_compare(expected[:signature], signature.downcase)
82
+ return "invalid" unless hash_ok && sig_ok
83
+ return "invalid" unless ts.match?(/\A-?[0-9]+\z/)
84
+
85
+ now = now_ms || self.now_ms
86
+ age = (now.to_i - ts.to_i).abs
87
+ age > TOLERANCE_SECONDS * 1000 ? "expired" : "valid"
88
+ end
89
+
90
+ # The request target for a URL: path plus "?query" as written, no scheme,
91
+ # host or fragment, and nothing re-encoded or normalised. An empty path is "/".
92
+ def self.request_target_from_url(url)
93
+ url = url.split("#", 2).first || url
94
+ rest = url.sub(%r{\A[A-Za-z][A-Za-z0-9+.\-]*://[^/?]*}, "")
95
+ return "/#{rest}" if rest.empty? || rest.start_with?("?")
96
+
97
+ rest
98
+ end
99
+
100
+ # A dashed UUID v4 from SecureRandom.
101
+ def self.uuid_v4
102
+ SecureRandom.uuid
103
+ end
104
+
105
+ # Unix epoch milliseconds as a decimal string.
106
+ def self.now_ms
107
+ (Time.now.to_r * 1000).to_i.to_s
108
+ end
109
+
110
+ # Not private: #sign (an instance method) calls this via the explicit
111
+ # `self.class.digest` receiver, which Ruby's `private_class_method`
112
+ # would reject even though both live on this class.
113
+ def self.digest(api_key, method, request_target, timestamp, nonce, body)
114
+ payload_hash = Digest::SHA256.hexdigest(body)
115
+ canonical = "#{method.to_s.upcase}.#{request_target}.#{timestamp}.#{nonce}.#{payload_hash}"
116
+ {
117
+ payload_hash: payload_hash,
118
+ signature: OpenSSL::HMAC.hexdigest("SHA256", api_key, canonical),
119
+ }
120
+ end
121
+
122
+ def self.secure_compare(a, b)
123
+ return false unless a.bytesize == b.bytesize
124
+
125
+ OpenSSL.fixed_length_secure_compare(a, b)
126
+ end
127
+ private_class_method :secure_compare
128
+
129
+ def self.blank?(value)
130
+ value.nil? || value.empty?
131
+ end
132
+ private_class_method :blank?
133
+ end
134
+ end
@@ -0,0 +1,407 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "thread"
5
+
6
+ require_relative "signer"
7
+ require_relative "transport"
8
+ require_relative "version"
9
+
10
+ module DevFortress
11
+ # Telemetry Heartbeat — CV-M2.
12
+ #
13
+ # Sends anonymised usage telemetry to the platform periodically (default
14
+ # every 5 minutes). No PII is transmitted — only aggregate counts and
15
+ # operational metadata.
16
+ #
17
+ # If the heartbeat stops, the platform dashboard shows: "SDK offline —
18
+ # upgrade to Hybrid for guaranteed visibility." Mirrors
19
+ # packages/devfortress-sdk/src/telemetry.ts.
20
+ #
21
+ # A background periodic-heartbeat thread is only started if
22
+ # heartbeat_interval_seconds is given and positive (mirrors Client's own
23
+ # opt-in flush_interval convention) — #send_heartbeat is always callable
24
+ # directly, which is what the test suite uses.
25
+ class TelemetryManager
26
+ DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 5 * 60 # 5 minutes
27
+ DEFAULT_TIMEOUT_SECONDS = 5
28
+ MAX_LATENCY_SAMPLES = 100
29
+ INITIAL_HEARTBEAT_DELAY_SECONDS = 5
30
+
31
+ def initialize(
32
+ api_key:,
33
+ endpoint:,
34
+ heartbeat_interval_seconds: nil,
35
+ debug: false,
36
+ timeout: DEFAULT_TIMEOUT_SECONDS,
37
+ transport: nil
38
+ )
39
+ @api_key = api_key
40
+ @endpoint = endpoint
41
+ @signer = Signer.new(api_key)
42
+ @heartbeat_interval_seconds = heartbeat_interval_seconds
43
+ @debug = debug
44
+ @timeout = timeout
45
+ @transport = transport || Transport.new
46
+
47
+ @event_count = 0
48
+ @block_count = 0
49
+ @rate_limit_count = 0
50
+ @latencies = []
51
+
52
+ @started_at = now_ms
53
+ @snapshot_provider = nil
54
+
55
+ @mutex = Mutex.new
56
+ @heartbeat_thread = nil
57
+ @stop = false
58
+ @stop_cv = ConditionVariable.new
59
+ end
60
+
61
+ # Starts sending periodic heartbeats if heartbeat_interval_seconds was
62
+ # configured and positive. snapshot_provider, if given, is a callable
63
+ # (#call) returning a Hash with symbol keys (:cl_mode, :tier,
64
+ # :sdk_version, :model_expired, :license_degraded, :integrity_hash)
65
+ # used to enrich each heartbeat with live SDK state.
66
+ def start(snapshot_provider: nil)
67
+ return if @heartbeat_thread
68
+
69
+ @snapshot_provider = snapshot_provider
70
+ @started_at = now_ms
71
+ return unless @heartbeat_interval_seconds && @heartbeat_interval_seconds.positive?
72
+
73
+ @heartbeat_thread = Thread.new { periodic_heartbeat }
74
+ log(:info, "Telemetry heartbeat started (interval: #{@heartbeat_interval_seconds}s)")
75
+ end
76
+
77
+ def record_event
78
+ @mutex.synchronize { @event_count += 1 }
79
+ end
80
+
81
+ def record_block
82
+ @mutex.synchronize { @block_count += 1 }
83
+ end
84
+
85
+ def record_rate_limit
86
+ @mutex.synchronize { @rate_limit_count += 1 }
87
+ end
88
+
89
+ # Records observe latency for p99 calculation (bounded reservoir
90
+ # sampling, matching the Node source).
91
+ def record_latency(latency_ms)
92
+ @mutex.synchronize do
93
+ if @latencies.length >= MAX_LATENCY_SAMPLES
94
+ idx = rand(@latencies.length)
95
+ @latencies[idx] = latency_ms
96
+ else
97
+ @latencies << latency_ms
98
+ end
99
+ end
100
+ end
101
+
102
+ # Sends a heartbeat to the platform. Fire-and-forget — failures are
103
+ # logged, never raised. Public (rather than private, as on the Node
104
+ # source) so it can be called directly in tests without waiting on the
105
+ # background thread's timing.
106
+ def send_heartbeat
107
+ enriched = @snapshot_provider ? (@snapshot_provider.call || {}) : {}
108
+
109
+ snapshot = {
110
+ "eventCount" => @event_count,
111
+ "blockCount" => @block_count,
112
+ "rateLimitCount" => @rate_limit_count,
113
+ "clMode" => enriched[:cl_mode] || "external",
114
+ "tier" => enriched[:tier] || "starter",
115
+ "sdkVersion" => enriched[:sdk_version] || VERSION,
116
+ "modelExpired" => enriched.fetch(:model_expired, false),
117
+ "licenseDegraded" => enriched.fetch(:license_degraded, false),
118
+ "integrityHash" => enriched[:integrity_hash] || "",
119
+ "uptimeSeconds" => ((now_ms - @started_at) / 1000),
120
+ "p99LatencyMs" => compute_p99,
121
+ }
122
+
123
+ url = "#{@endpoint}/api/sdk/heartbeat"
124
+ body = JSON.generate(snapshot.merge("timestamp" => now_ms))
125
+ headers = @signer.sign("POST", Signer.request_target_from_url(url), body)
126
+ headers["Content-Type"] = "application/json"
127
+
128
+ begin
129
+ @transport.send_request("POST", url, headers, body, @timeout)
130
+ log(:debug,
131
+ "Heartbeat sent: events=#{snapshot['eventCount']}, blocks=#{snapshot['blockCount']}, " \
132
+ "uptime=#{snapshot['uptimeSeconds']}s")
133
+ @mutex.synchronize do
134
+ @event_count = 0
135
+ @block_count = 0
136
+ @rate_limit_count = 0
137
+ @latencies = []
138
+ end
139
+ rescue StandardError => e
140
+ log(:debug, "Heartbeat failed: #{e.message}")
141
+ end
142
+ end
143
+
144
+ # Current telemetry state (for diagnostics).
145
+ def state
146
+ @mutex.synchronize do
147
+ {
148
+ event_count: @event_count,
149
+ block_count: @block_count,
150
+ rate_limit_count: @rate_limit_count,
151
+ uptime_seconds: ((now_ms - @started_at) / 1000),
152
+ }
153
+ end
154
+ end
155
+
156
+ # Stops sending heartbeats and clean up. Safe to call more than once.
157
+ def destroy
158
+ @mutex.synchronize do
159
+ @stop = true
160
+ @stop_cv.broadcast
161
+ end
162
+ @heartbeat_thread&.join
163
+ @heartbeat_thread = nil
164
+ end
165
+
166
+ private
167
+
168
+ def periodic_heartbeat
169
+ # Send the first heartbeat after a short delay so #start doesn't
170
+ # block init, then on the configured interval thereafter.
171
+ stop = @mutex.synchronize do
172
+ @stop_cv.wait(@mutex, INITIAL_HEARTBEAT_DELAY_SECONDS)
173
+ @stop
174
+ end
175
+ return if stop
176
+
177
+ send_heartbeat
178
+
179
+ loop do
180
+ stop = @mutex.synchronize do
181
+ @stop_cv.wait(@mutex, @heartbeat_interval_seconds)
182
+ @stop
183
+ end
184
+ break if stop
185
+
186
+ send_heartbeat
187
+ end
188
+ end
189
+
190
+ def compute_p99
191
+ return 0 if @latencies.empty?
192
+
193
+ sorted = @latencies.sort
194
+ idx = (sorted.length * 0.99).floor
195
+ sorted[[idx, sorted.length - 1].min]
196
+ end
197
+
198
+ def now_ms
199
+ (Time.now.to_f * 1000).to_i
200
+ end
201
+
202
+ def log(level, message)
203
+ return if level == :debug && !@debug
204
+
205
+ prefix = "[DevFortress:Telemetry]"
206
+ case level
207
+ when :warn
208
+ warn("#{prefix} #{message}")
209
+ else
210
+ puts("#{prefix} #{message}")
211
+ end
212
+ end
213
+ end
214
+
215
+ # Anomaly-Gated Metering: Aggregate Telemetry Rollup Buffer.
216
+ #
217
+ # Option B (2026-08-27): CLEAN/unflagged traffic no longer gets a full,
218
+ # billed LiveThreatEvent row per request. Instead, this buffer
219
+ # accumulates lightweight per-alias/IP-per-hour counters in memory
220
+ # (request count, unique endpoints seen, error count, latency sum) and
221
+ # flushes them as a small number of upsert-increment rows to
222
+ # /api/events/telemetry-rollup on a short interval — not per request.
223
+ # This is what feeds B1/B10's population-level baseline needs without
224
+ # counting toward the customer's billed event quota (see
225
+ # AliasTelemetryRollup in prisma/schema.prisma and
226
+ # DF-Session-task-report-27-08-26.md, Section 1/4). Mirrors
227
+ # packages/devfortress-sdk/src/telemetry-rollup-buffer.ts.
228
+ #
229
+ # The Node source keys its in-memory buckets on a NUL-byte string
230
+ # concatenation (`"#{aliasOrIpKey}\x00#{periodKey}"`) as a
231
+ # collision-free composite map key. This port uses BucketKey, a frozen
232
+ # Struct of (alias_or_ip_key, period_key), as the Hash key instead — the
233
+ # same collision-free bucketing semantics, without embedding a control
234
+ # character in a string.
235
+ class TelemetryRollupBuffer
236
+ # Bounded per-bucket endpoint tracking — uniqueEndpoints is an
237
+ # approximation (this is non-billing, best-effort aggregate
238
+ # telemetry, not an exact count).
239
+ MAX_ENDPOINTS_TRACKED_PER_BUCKET = 50
240
+ # Matches TelemetryManager's DEFAULT_HEARTBEAT_INTERVAL_SECONDS — this
241
+ # is aggregate, non-billing telemetry, not real-time-critical, so a
242
+ # wider batching window means fewer platform requests.
243
+ DEFAULT_FLUSH_INTERVAL_SECONDS = 5 * 60
244
+ DEFAULT_MAX_BUFFERED_KEYS = 500
245
+ DEFAULT_TIMEOUT_SECONDS = 10
246
+
247
+ BucketKey = Struct.new(:alias_or_ip_key, :period_key)
248
+
249
+ # Hour-bucket period key, e.g. "2026-08-27T14" (UTC) — matches
250
+ # AliasTelemetryRollup.periodKey.
251
+ def self.hourly_period_key(time = Time.now)
252
+ time.utc.strftime("%Y-%m-%dT%H")
253
+ end
254
+
255
+ def initialize(
256
+ api_key:,
257
+ endpoint:,
258
+ flush_interval_seconds: nil,
259
+ max_buffered_keys: DEFAULT_MAX_BUFFERED_KEYS,
260
+ debug: false,
261
+ timeout: DEFAULT_TIMEOUT_SECONDS,
262
+ transport: nil
263
+ )
264
+ @api_key = api_key
265
+ @endpoint = endpoint
266
+ @signer = Signer.new(api_key)
267
+ @flush_interval_seconds = flush_interval_seconds
268
+ @max_buffered_keys = max_buffered_keys || DEFAULT_MAX_BUFFERED_KEYS
269
+ @debug = debug
270
+ @timeout = timeout
271
+ @transport = transport || Transport.new
272
+
273
+ @buckets = {}
274
+ @mutex = Mutex.new
275
+ @flush_thread = nil
276
+ @stop = false
277
+ @stop_cv = ConditionVariable.new
278
+ end
279
+
280
+ # Starts the periodic flush thread, if flush_interval_seconds was
281
+ # configured and positive. Safe to call multiple times (no-op if
282
+ # already started).
283
+ def start
284
+ return if @flush_thread
285
+ return unless @flush_interval_seconds && @flush_interval_seconds.positive?
286
+
287
+ @flush_thread = Thread.new { periodic_flush }
288
+ end
289
+
290
+ # Buffers one clean (non-flagged) request's contribution. Synchronous,
291
+ # no network call — actual delivery happens on the next #flush.
292
+ def add(alias_or_ip_key:, endpoint:, is_error:, latency_ms:)
293
+ period_key = self.class.hourly_period_key
294
+ key = BucketKey.new(alias_or_ip_key, period_key)
295
+ now = now_ms
296
+ force_flush = false
297
+
298
+ @mutex.synchronize do
299
+ bucket = @buckets[key]
300
+ unless bucket
301
+ # Bound total buffered keys so a burst of unique IPs can't grow
302
+ # memory unbounded — force an early flush and drop this one
303
+ # contribution. Acceptable: this is approximate, non-billing
304
+ # aggregate telemetry.
305
+ if @buckets.size >= @max_buffered_keys
306
+ force_flush = true
307
+ else
308
+ bucket = {
309
+ alias_or_ip_key: alias_or_ip_key,
310
+ period_key: period_key,
311
+ request_count: 0,
312
+ endpoints: {},
313
+ error_count: 0,
314
+ latency_sum_ms: 0,
315
+ window_start: now,
316
+ window_end: now,
317
+ }
318
+ @buckets[key] = bucket
319
+ end
320
+ end
321
+
322
+ if bucket
323
+ bucket[:request_count] += 1
324
+ bucket[:endpoints][endpoint] = true if bucket[:endpoints].size < MAX_ENDPOINTS_TRACKED_PER_BUCKET
325
+ bucket[:error_count] += 1 if is_error
326
+ bucket[:latency_sum_ms] += latency_ms
327
+ bucket[:window_end] = now
328
+ end
329
+ end
330
+
331
+ flush if force_flush
332
+ end
333
+
334
+ # Flushes all buffered buckets to the platform in one batch request.
335
+ def flush
336
+ contributions = @mutex.synchronize do
337
+ break nil if @buckets.empty?
338
+
339
+ list = @buckets.values.map do |b|
340
+ {
341
+ "aliasOrIpKey" => b[:alias_or_ip_key],
342
+ "periodKey" => b[:period_key],
343
+ "requestCount" => b[:request_count],
344
+ "uniqueEndpointsInBatch" => b[:endpoints].size,
345
+ "errorCount" => b[:error_count],
346
+ "latencySumMs" => b[:latency_sum_ms],
347
+ "windowStart" => b[:window_start],
348
+ "windowEnd" => b[:window_end],
349
+ }
350
+ end
351
+ @buckets.clear
352
+ list
353
+ end
354
+ return if contributions.nil?
355
+
356
+ post(contributions)
357
+ end
358
+
359
+ # Cleans up the flush thread and drops any unflushed buckets.
360
+ def destroy
361
+ @mutex.synchronize do
362
+ @stop = true
363
+ @stop_cv.broadcast
364
+ @buckets.clear
365
+ end
366
+ @flush_thread&.join
367
+ @flush_thread = nil
368
+ end
369
+
370
+ private
371
+
372
+ def periodic_flush
373
+ loop do
374
+ stop = @mutex.synchronize do
375
+ @stop_cv.wait(@mutex, @flush_interval_seconds)
376
+ @stop
377
+ end
378
+ break if stop
379
+
380
+ flush
381
+ end
382
+ end
383
+
384
+ def post(contributions)
385
+ url = "#{@endpoint}/api/events/telemetry-rollup"
386
+ body = JSON.generate({ "contributions" => contributions })
387
+ headers = @signer.sign("POST", Signer.request_target_from_url(url), body)
388
+ headers["Content-Type"] = "application/json"
389
+ @transport.send_request("POST", url, headers, body, @timeout)
390
+ rescue StandardError => e
391
+ # Best-effort — aggregate telemetry is not billing-relevant, so
392
+ # dropping a batch on transient failure is acceptable (unlike the
393
+ # full event relay path, which retries).
394
+ log(:debug, "telemetry rollup flush failed: #{e.message}")
395
+ end
396
+
397
+ def now_ms
398
+ (Time.now.to_f * 1000).to_i
399
+ end
400
+
401
+ def log(level, message)
402
+ return if level == :debug && !@debug
403
+
404
+ puts("[DevFortress:TelemetryRollup] #{message}")
405
+ end
406
+ end
407
+ end