Class: Restless::CaptureEngine

Inherits:
Object
  • Object
show all
Defined in:
lib/restless/capture.rb

Overview

The capture engine: redaction choke point (section 4), the two caches (section 11), fingerprinting (section 5) and the hand-off to the uploader (sections 8 and 9).

Every adapter goes through here. No adapter may bypass record, which is the single point where redaction runs.

Constant Summary collapse

MAX_BODY_BYTES =

REDACT-030.

Redact::MAX_BODY_BYTES

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url:, request_id_prefix: nil, redact: nil, transport: nil) ⇒ CaptureEngine

Returns a new instance of CaptureEngine.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/restless/capture.rb', line 23

def initialize(api_key:, base_url:, request_id_prefix: nil, redact: nil,
               transport: nil)
  @redact = redact || {}
  @enrich_cache = EnrichCache.new
  @recovery_cache = RecoveryCache.new
  @portal_url = nil
  @docs_mutex = Mutex.new
  @callback = nil
  @uploader = Uploader.new(
    api_key: api_key,
    base_url: base_url,
    request_id_prefix: request_id_prefix,
    transport: transport,
    on_response: method(:handle_server_response)
  )
end

Instance Attribute Details

#enrich_cache ⇒ Object (readonly)

Returns the value of attribute enrich_cache.



21
22
23
 
# File 'lib/restless/capture.rb', line 21

def enrich_cache
  @enrich_cache
end

#recovery_cache ⇒ Object (readonly)

Returns the value of attribute recovery_cache.



21
22
23
 
# File 'lib/restless/capture.rb', line 21

def recovery_cache
  @recovery_cache
end

#uploader ⇒ Object (readonly)

Returns the value of attribute uploader.



21
22
23
 
# File 'lib/restless/capture.rb', line 21

def uploader
  @uploader
end

Class Method Details

.resolve_block(block) ⇒ Object

SETUP-004.



201
202
203
204
205
206
207
208
209
 
# File 'lib/restless/capture.rb', line 201

def self.resolve_block(block)
  return nil if block.nil? || block == false
  return { status: 403, message: "Forbidden" } if block == true
  return nil unless block.is_a?(Hash)

  status = block[:status] || block["status"] || 403
  message = block[:message] || block["message"] || "Forbidden"
  { status: status.to_i, message: message.to_s }
end

.wire_fingerprint(fingerprint) ⇒ Object

WIRE-017. The serialized form of a fingerprint.

Fingerprint::Result is a Struct with symbol members, and the wire wants string keys, so the mapping has to be written somewhere. It is written once: the Rack middleware computes the fingerprint early (INJECT-009) and must serialize it identically to record below.



130
131
132
133
134
135
136
 
# File 'lib/restless/capture.rb', line 130

def self.wire_fingerprint(fingerprint)
  {
    "strategy" => fingerprint.strategy,
    "key" => fingerprint.key,
    "reason" => fingerprint.reason
  }
end

Instance Method Details

#callback=(callback) ⇒ Object 



40
41
42
 
# File 'lib/restless/capture.rb', line 40

def callback=(callback)
  @callback = callback
end

#compute_fingerprint(captured, stack_frame = nil) ⇒ Object

FP-002. Errors only; the ingest treats an absent fingerprint as success.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/restless/capture.rb', line 96

def compute_fingerprint(captured, stack_frame = nil)
  response = captured["response"] || {}
  status = response["status"].to_i
  return nil if status < 400

  body = response["body"]
  if body.is_a?(String)
    begin
      body = JSON.parse(body, max_nesting: false)
    rescue StandardError
      # Leave it as a string; `extract_message` handles both shapes.
    end
  end

  request = captured["request"] || {}
  Fingerprint.compute(
    status: status,
    method: request["method"],
    route: captured["routePattern"],
    response_headers: response["headers"],
    response_body: body,
    stack_frame: stack_frame
  )
rescue StandardError => e
  Env.debug_log("fingerprint failed: #{e.class}: #{e.message}")
  nil
end

#flush ⇒ Object 



53
54
55
 
# File 'lib/restless/capture.rb', line 53

def flush
  @uploader.flush
end

#handle_server_response(body, batch_fingerprints) ⇒ Object

WIRE-020..023, CACHE-006, CACHE-011..013.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/restless/capture.rb', line 58

def handle_server_response(body, batch_fingerprints)
  needs = body["needsEnrichment"]
  if needs.is_a?(Array)
    needs.each { |key| @enrich_cache.invalidate(key) if key.is_a?(String) }
  end

  docs = body["docsUrl"]
  if docs.is_a?(String) && !docs.empty?
    # Origin only; strip trailing slashes so the server can be lax.
    # The wire key stays `docsUrl`: every already-deployed SDK reads it,
    # so renaming would strand them all with no portal origin (WIRE-023).
    @docs_mutex.synchronize { @portal_url = docs.sub(%r{/+\z}, "") }
  end

  messages = body["recoveryMessages"].is_a?(Hash) ? body["recoveryMessages"] : {}
  batch_fingerprints.each do |key|
    value = messages[key]
    if value.is_a?(String)
      @recovery_cache.set(key, value) # CACHE-011
    elsif messages.key?(key)
      @recovery_cache.set(key, nil)
    else
      # CACHE-012 + CACHE-013: negative-cache anything the server did not
      # answer for, without clobbering an existing positive entry. This is
      # what guarantees the SECOND occurrence of any error is a cache hit.
      @recovery_cache.set_negative_unless_present(key)
    end
  end
rescue StandardError => e
  Env.debug_log("server response handling failed: #{e.class}: #{e.message}")
end

#lookup_recovery(fingerprint_key) ⇒ Object

CACHE-010. Synchronous, in-process, no I/O, never blocks the response.



91
92
93
 
# File 'lib/restless/capture.rb', line 91

def lookup_recovery(fingerprint_key)
  @recovery_cache.lookup(fingerprint_key)
end

#portal_url ⇒ Object

INJECT-006. The latest server-resolved docs origin, or nil when no batch has round-tripped yet. INJECT-006. The server-published portal origin every injected URL is built on. Nil before the first upload round-trip, and then nothing is emitted rather than a guess.



49
50
51
 
# File 'lib/restless/capture.rb', line 49

def portal_url
  @docs_mutex.synchronize { @portal_url }
end

#record(captured, stack_frame: nil) ⇒ Object

The single redaction choke point. Redact, truncate, fingerprint, enqueue.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/restless/capture.rb', line 212

def record(captured, stack_frame: nil)
  request = captured["request"] || {}
  response = captured["response"] || {}
  request_headers = request["headers"] || {}
  response_headers = response["headers"] || {}

  sanitized = captured.dup
  sanitized["request"] = request.merge(
    "url" => Redact.redact_url(request["url"].to_s, @redact[:query_params] || []),
    "headers" => Redact.redact_headers(request_headers, @redact[:headers] || []),
    # REDACT-033: truncation runs AFTER redaction, so a secret cannot
    # survive by sitting past the byte limit.
    "body" => Redact.truncate_body(
      Redact.redact_body(request["body"], request_headers["content-type"],
                         @redact[:body_keys] || []),
      MAX_BODY_BYTES
    )
  )
  sanitized["response"] = response.merge(
    "headers" => Redact.redact_headers(response_headers, @redact[:headers] || []),
    "body" => Redact.truncate_body(
      Redact.redact_body(response["body"], response_headers["content-type"],
                         @redact[:body_keys] || []),
      MAX_BODY_BYTES
    )
  )

  if sanitized["errorFingerprint"].nil? && response["status"].to_i >= 400
    fingerprint = compute_fingerprint(sanitized, stack_frame)
    sanitized["errorFingerprint"] = self.class.wire_fingerprint(fingerprint) if fingerprint
  end

  @uploader.push(sanitized)
  nil
rescue StandardError => e
  # SAFETY-001. Nothing in here may reach customer handler code.
  Env.debug_log("record failed: #{e.class}: #{e.message}")
  nil
end

#resolve(request) ⇒ Object

Run the user's setup callback and resolve owner metadata.

SAFETY-002: a callback that raises is caught and the request proceeds with no user context attached.



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/restless/capture.rb', line 142

def resolve(request)
  return {} if @callback.nil?

  begin
    raw = @callback.call(request)
  rescue StandardError => e
    Env.debug_log("setup callback raised: #{e.class}: #{e.message}")
    return {}
  end
  return {} unless raw.is_a?(Hash)

  result = normalize_setup(raw)
  owner = result[:owner]
  return { "apiKey" => result[:api_key], "block" => result[:block],
           "extra" => result[:extra] }.compact if owner.nil?

  owner_id = owner[:id]
  enrich = owner[:enrich]
  # CACHE-002: key on owner id when present, else the masked end-user key,
  # so multiple end-users in one workspace share a slot.
  cache_key = (owner_id if owner_id && !owner_id.empty?) || result[:api_key]

  resolved_owner = { "id" => owner_id }.compact

  if enrich.respond_to?(:call) && owner_id && !owner_id.empty? && cache_key
    cached = @enrich_cache.get(cache_key)
    if cached
      # CACHE-003: the VALUE is cached, not merely a freshness flag, so
      # every upload carries owner metadata even when the callback was
      # skipped. The ingest cannot backfill.
      resolved_owner = resolved_owner.merge(cached)
    else
      enriched = begin
        enrich.call(owner_id)
      rescue StandardError => e
        # CACHE-005 / SAFETY-003: swallowed, and NOT cached, so the next
        # request retries.
        Env.debug_log("enrich raised: #{e.class}: #{e.message}")
        nil
      end
      if enriched.is_a?(Hash)
        stringified = stringify_keys(enriched)
        @enrich_cache.set(cache_key, stringified)
        resolved_owner = resolved_owner.merge(stringified)
      end
    end
  end

  # CACHE-007: when enrichment did not run or produced nothing, the upload
  # still carries the bare owner id so the dashboard can group by it.
  {
    "apiKey" => result[:api_key],
    "owner" => resolved_owner,
    "block" => result[:block],
    "extra" => result[:extra]
  }.compact
end