foam-otel 1.0.2 → 1.2.0

data/lib/foam/otel/classifier.rb

@@ -14,9 +14,26 @@ module Foam
     # subclasses of the proxies, so instance_of? (not is_a?) is correct. The
     # metrics-/logs-api gems must be required before their slots exist; init()
     # loads the SDK before classifying.
+    #
+    # RULE-42 FENCE (GOTCHAS F7): the Internal::Proxy* constants are
+    # @api-private — this reach BREAKS IF upstream renames/moves them, so it
+    # is (1) isolated to this one file, (2) feature-detected (`defined?`)
+    # degrading to a warned fail-safe no-op (UNCLASSIFIABLE, below), (3+4)
+    # documented in GOTCHAS F7 and pinned by spec/classifier_spec.rb's
+    # degradation examples, and (5) the upstream need — a public "is the
+    # global still the default" predicate — is tracked for filing against
+    # open-telemetry/opentelemetry-ruby (see GOTCHAS F7); delete the reach
+    # when it ships.
     Verdict = Struct.new(:free, :owner) do
       def free? = free
       def claimed? = !free
+
+      # rule 42 fence: when the API's Internal proxy constant is missing
+      # (upstream renamed/removed it), foam cannot PROVE the slot free. The
+      # verdict stays fail-safe (claimed → register nothing) but is marked
+      # UNCLASSIFIABLE so init warns "foam cannot classify this OTel API
+      # version" instead of fabricating a foreign-owner name (GOTCHAS G14).
+      def unclassifiable? = !free && owner.equal?(Classifier::UNCLASSIFIABLE)
     end
 
     module Classifier
@@ -24,16 +41,37 @@ module Foam
 
       SIGNALS = %i[traces metrics logs].freeze
 
+      # Sentinel owner for a slot whose FREE predicate is unavailable (the
+      # Internal proxy constant disappeared — see Verdict#unclassifiable?).
+      UNCLASSIFIABLE = :unclassifiable_otel_api_shape
+
       def classify
-        {
-          traces: verdict(OpenTelemetry.tracer_provider, defined?(OpenTelemetry::Internal::ProxyTracerProvider) && OpenTelemetry::Internal::ProxyTracerProvider),
-          metrics: verdict(OpenTelemetry.meter_provider, defined?(OpenTelemetry::Internal::ProxyMeterProvider) && OpenTelemetry::Internal::ProxyMeterProvider),
-          logs: verdict(OpenTelemetry.logger_provider, defined?(OpenTelemetry::Internal::ProxyLoggerProvider) && OpenTelemetry::Internal::ProxyLoggerProvider),
-        }
+        SIGNALS.to_h { |signal| [signal, classify_signal(signal)] }
+      end
+
+      # One slot, read NOW. init() calls this IMMEDIATELY before each
+      # signal's setter — never as an up-front classify-all pass — so the
+      # unavoidable pre-read→set gap (Ruby has no atomic set-once attempt;
+      # GOTCHAS F8) stays as narrow as the platform allows.
+      def classify_signal(signal)
+        case signal
+        when :traces
+          verdict(OpenTelemetry.tracer_provider, defined?(OpenTelemetry::Internal::ProxyTracerProvider) && OpenTelemetry::Internal::ProxyTracerProvider)
+        when :metrics
+          verdict(OpenTelemetry.meter_provider, defined?(OpenTelemetry::Internal::ProxyMeterProvider) && OpenTelemetry::Internal::ProxyMeterProvider)
+        when :logs
+          verdict(OpenTelemetry.logger_provider, defined?(OpenTelemetry::Internal::ProxyLoggerProvider) && OpenTelemetry::Internal::ProxyLoggerProvider)
+        end
       end
 
       def verdict(provider, proxy_class)
-        free = proxy_class ? provider.instance_of?(proxy_class) : false
+        # No proxy constant to test against: fail safe (never register into a
+        # slot foam cannot prove free) but report the DISTINCT unclassifiable
+        # state — a degraded verdict must never name the renamed proxy class
+        # as a "foreign owner" (rule 42 warned no-op, GOTCHAS G14).
+        return Verdict.new(false, UNCLASSIFIABLE) unless proxy_class
+
+        free = provider.instance_of?(proxy_class)
         Verdict.new(free, free ? nil : owner_name(provider))
       end
 

data/lib/foam/otel/config.rb

@@ -42,8 +42,9 @@ module Foam
           environment: environment,
           version: version,
           enabled: enabled,
-          # Customer lists EXTEND the always-on floor (rule 14) — stored
-          # lowercased for the engine's case-insensitive substring match.
+          # Opt-in redaction (holistic redesign): the ONLY keys ever redacted.
+          # Empty (the default) → zero redaction, raw capture. Stored lowercased
+          # for the engine's case-insensitive substring match.
           redact_keys: downcase_list(redact_keys),
           redact_pii_keys: downcase_list(redact_pii_keys),
           ignored_outbound_hosts: Array(ignored_outbound_hosts).map { |h| h.to_s.downcase }.freeze,
@@ -57,6 +58,25 @@ module Foam
       def downcase_list(list)
         Array(list).map { |k| k.to_s.downcase }.reject(&:empty?).uniq.freeze
       end
+
+      # A second init() refreshes ONLY the redaction lists (and diagnostics)
+      # onto the EXISTING config: enabled/endpoint/identity are process-global
+      # and immutable after the first init (see init.rb — a second init must
+      # never flip enabled and leave foam half-dark). Private: not public API
+      # surface (pinned by export_surface_spec).
+      def refresh_post_init_config(existing, redact_keys:, redact_pii_keys:, diagnostics:)
+        Config.new(
+          name: existing.name,
+          environment: existing.environment,
+          version: existing.version,
+          enabled: existing.enabled,
+          redact_keys: downcase_list(redact_keys),
+          redact_pii_keys: downcase_list(redact_pii_keys),
+          ignored_outbound_hosts: existing.ignored_outbound_hosts,
+          diagnostics: diagnostics ? true : false,
+          endpoint: existing.endpoint
+        ).freeze
+      end
     end
   end
 end

data/lib/foam/otel/constants.rb

@@ -21,95 +21,21 @@ module Foam
     # but is never rewritten).
     KNOWN_ENVIRONMENTS = %w[production staging development test].freeze
 
-    # ---- Secrets floor (BASE_PACKAGE_SPEC rule 14) --------------------------
-    # RESEARCHED, not invented (provenance cited in RESEARCH.md): substring
-    # roots curated from the consensus of OSS scrubbers — raven-ruby,
-    # sentry-python/js, Elastic APM sanitize_field_names, is-secret,
-    # @zapier/secret-scrubber, HyperDX, Instana, Rails filter_parameters.
-    # Matching is SUBSTRING, case-insensitive, over a key NORMALIZED by
-    # lowercasing and folding `-` `_` `.` and space (so `X-Api-Key` ≡
-    # `api_key` ≡ `apiKey`).
-    #
-    # BARE_SECRET_ROOTS are separator-free and matched against the normalized
-    # key. They are distinctive enough to never over-redact.
-    BARE_SECRET_ROOTS = %w[
-      secret
-      token
-      password
-      passwd
-      pwd
-      passphrase
-      apikey
-      secretkey
-      accesskey
-      privatekey
-      credential
-      credentials
-      session
-      phpsessid
-      jsessionid
-      connectsid
-      aspnetsessionid
-      cookie
-      csrf
-      xsrf
-      jwt
-      bearer
-      signature
-      mysqlpwd
-      proxyauthorization
-      crypt
-      creditcard
-      cardnumber
-    ].freeze
-
-    # GUARDED roots are short/ambiguous — matched with word boundaries on the
-    # lowercased key (separators kept) so they never OVER-redact (lost
-    # observability, not extra safety). `key`/`sid`/`id`/`salt` are REJECTED
-    # as roots entirely: bare `key` eats idempotency_key/cache_key/public_key;
-    # bare `sid` eats consider/reside/president. `auth` must miss author;
-    # `card` must miss dashboard/wildcard/postcard.
-    GUARDED_SECRET_ROOTS = %w[ssn otp mfa 2fa sso saml cvv cvc dni].freeze
-
-    # Precompiled once at load: one token-boundary regex matching ANY guarded
-    # root, so the hot path never recompiles an interpolated regex per key.
-    GUARDED_SECRET_RE =
-      /(?<![a-z0-9])(?:#{GUARDED_SECRET_ROOTS.map { |r| Regexp.escape(r) }.join('|')})(?![a-z0-9])/
-
-    # ---- Value patterns (rule 14 second pass) ------------------------------
-    # A pass over string VALUES/bodies so a secret under an UNLISTED key still
-    # masks. \b-bounded (usable both whole-value and embedded), prefix-
-    # anchored, low false-positive vendor key shapes catalogued by OSS secret
-    # scanners (detect-secrets Apache-2.0, secretlint MIT, gitleaks MIT).
-    # Bare high-entropy / plain 32-hex / base64 / credit-card-Luhn are
-    # deliberately OMITTED (opt-in only — they destroy observability without a
-    # nearby keyword). Cited in RESEARCH.md.
-    SECRET_VALUE_PATTERNS = [
-      %r{\b(?:Bearer|Basic)\s+[A-Za-z0-9\-._~+/=]{8,}}i,                     # auth header values
-      /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\b/,      # JWT
-      /\b(?:sk|pk|rk)[-_](?:ant-)?[A-Za-z0-9_-]{16,}\b/,                     # OpenAI/Anthropic/generic
-      /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/,                                 # Stripe live
-      /\bgh[pousr]_[A-Za-z0-9]{16,}\b/,                                      # GitHub tokens
-      /\bgithub_pat_[A-Za-z0-9_]{16,}\b/,                                    # GitHub fine-grained PAT
-      /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,                                    # Slack
-      /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/,                            # AWS access key id
-      /\bAIza[0-9A-Za-z\-_]{20,}\b/,                                         # Google API key
-      /\bglpat-[A-Za-z0-9\-_]{16,}\b/,                                       # GitLab PAT
-      /\bnpm_[A-Za-z0-9]{16,}\b/,                                            # npm
-      /\bpypi-[A-Za-z0-9\-_]{16,}\b/,                                        # PyPI
-      /\bhf_[A-Za-z0-9]{16,}\b/,                                             # HuggingFace
-      /\bshp(?:ss|at|ca|pa|a)_[A-Za-z0-9]{16,}\b/,                          # Shopify
-      /\bdapi[a-f0-9]{32}\b/i,                                               # Databricks
-      /-----BEGIN[A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END[A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----/, # PEM
-    ].freeze
-
-    # One unioned regex (per-pattern flags preserved) so the value-pattern pass
-    # is a SINGLE scan per string instead of one gsub per pattern.
-    SECRET_VALUE_RE = Regexp.union(SECRET_VALUE_PATTERNS)
-
-    # The two mask shapes (rule 14). Secret-key matches keep a debug tail;
-    # PII matches and non-scalar values redact in full. MASK_BODY matches
-    # raven-ruby's STRING_MASK precedent.
+    # ---- Redaction is FULLY OPT-IN (holistic redesign, 2026-07-26) ----------
+    # The package does NO redaction by default: with neither redact_keys nor
+    # redact_pii_keys set (or both empty) every value is captured RAW,
+    # including secrets / PII / PHI. There is NO always-on secret floor and NO
+    # value-pattern auto-masking — the package auto-masks NOTHING. Redaction
+    # happens ONLY for the exact keys the customer enumerates:
+    #   * redact_keys     → tail-mask the value (shape-preserving; see below)
+    #   * redact_pii_keys → erase the value ([REDACTED])
+    # (See docs/decisions/holistic-redesign-decision-log.md — "Redaction is
+    # FULLY OPT-IN".) The customer owns the privacy/legal posture.
+
+    # The two mask shapes. A redact_keys match on a scalar keeps a debug tail;
+    # a redact_pii_keys match (and any non-scalar value under a redact_keys
+    # match) erases in full. MASK_BODY matches raven-ruby's STRING_MASK
+    # precedent.
     REDACTED = "[REDACTED]"
     MASK_BODY = "********" # always exactly eight chars — never length-revealing
     TAIL_MIN_LENGTH = 12   # below this, no tail is safe

data/lib/foam/otel/errors.rb

@@ -35,7 +35,10 @@ module Foam
         span.record_exception(error)
         span.status = OpenTelemetry::Trace::Status.error(error.message.to_s)
         true
-      rescue StandardError
+      rescue StandardError, SystemStackError
+        # SystemStackError is not a StandardError: a customer error whose
+        # #message/#to_s recurses unboundedly must never turn "recording an
+        # exception" into a host-thread crash (rule 9).
         false
       end
     end

data/lib/foam/otel/fork_hooks.rb

@@ -35,6 +35,13 @@ module Foam
           if pid.zero?
             begin
               Foam::Otel.after_fork!
+              # Let a per-worker init (the README on_worker_boot recipe) be a
+              # REAL re-init in the child: without this, the inherited
+              # @initialized guard returns the PARENT's instance and every
+              # worker reports the parent's service.instance.id (section 0
+              # resource table / GOTCHAS R1). Workers that never re-init keep
+              # the inherited pipelines (readers restarted above).
+              Foam::Otel.send(:mark_forked!)
             rescue StandardError
               nil
             end