prauga-flexdoc 0.4.7 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efc2b18bbb41bb01b8f97489c9ef029bccca00456403d0ac2976b1ac3f1c0cd7
-  data.tar.gz: 82fdc6f5d6938c7e2354adeca9d24243f14819ce2be9713fe844f425e4b04f38
+  metadata.gz: 2cfa79303d5ae57884ca1c3fc8157eecf7852a764c04edeece1f72302cb9f881
+  data.tar.gz: e2946cba95ac973864b0f81e8b0e9a46165fa1685b2bff3b1bfa7e3b07e8bda3
 SHA512:
-  metadata.gz: 5e3482cdbc2905f508ac91edf0fddcaf1f9e80827b39f8a66b344c90927b4d278968844725bc91ab838f289a820a67ccad2eb890f4cae075e2611d673b5366d0
-  data.tar.gz: 1d533bffac5d5e3c400f17259b38f12fb903e2b3c37c70936644eeecd5a942d5d1a5a806926b79ac0687ed59ec989cd8e2e58c39fdf9e5300a2c4ddac37026b7
+  metadata.gz: fe41dcf5a51516ac2993bd1ef08e6c698d9f9998c53c856975023c0a2000a017fa0cdbb94417eb415f5035f1b7b86dd16d7eaf279d0a7db81ec504607250db66
+  data.tar.gz: 164d984ad22590f7dafd522888de0ab3d93d46a533f355dbb2ae602383137153fe674767d7f651f760478429666eea833beebf54b5e57b9f281d3dd462642754

data/README.md

@@ -53,6 +53,28 @@ This first native slice supports the canonical JSON and multipart envelopes, Bas
 
 The Ruby executor blocks link-local/cloud-metadata targets and validates DNS results before connecting. It then pins `Net::HTTP` to one of the validated addresses with `ipaddr=` while retaining the original hostname for the HTTP `Host` header and TLS SNI/certificate verification. Environment proxy routing is disabled for native execution, so the validated destination cannot be bypassed through `http_proxy`/`HTTP_PROXY`. Private-network relaxation is not part of this slice.
 
+### Execution evidence
+
+An executor that reports nothing leaves an operator guessing whether a failing Try It is a policy rejection, a slow upstream or traffic that never carried an execute marker. Pass a metric sink to emit the same metric names, labels and reason vocabulary as the Node, Python, Go and Rust hosts, so one collector reads a mixed fleet:
+
+```ruby
+observation = Prauga::FlexDoc::HostExecutionObservation.new
+
+executor = Prauga::FlexDoc::HostExecution.new(
+  allowed_origins: ["https://api.example.internal"],
+  metric_sink: observation.sink
+)
+
+# Whenever an operator asks for evidence:
+report = Prauga::FlexDoc.host_execution_observation_report(observation)
+```
+
+The sink receives `HostExecutionMetric` values carrying a name, kind, value and labels, and nothing else: no URL, header, body or credential reaches it. Bridge it to Prometheus or OpenTelemetry where such a stack exists; where none does, `HostExecutionObservation` folds the same updates into a mutex-guarded aggregate safe to share across threaded or forked-with-threads servers, and `host_execution_observation_report` produces the shared `flexdoc.host-execution.observation/1` document every other runtime also emits. Under a forking server each worker keeps its own window, so treat the export as per-process evidence.
+
+Every non-successful execution carries one of the stable categories in `HostExecutionObservability::HOST_EXECUTION_REASONS`, which is why rejections and upstream failures are separable at all — the human-readable messages interpolate origins and field names, so they are unbounded and unusable as a metric label. Requests arriving without `X-FlexDoc-Execute` are counted by `flexdoc_execute_unmarked_total` and deliberately move no lifecycle metric, since they produced no validated envelope.
+
+The report declares `browser-direct-transport-mix` in its gaps: a browser-direct execution never reaches this process, so the transport mix cannot be derived here. See [host-execution observability](../../docs/host-execution-observability.md) for the full metric contract and the browser half of a review. Metric delivery is best effort: a sink that raises cannot fail an execution.
+
 ## Rails
 
 In `config/routes.rb`:

data/lib/prauga/flexdoc/host_execution.rb

@@ -9,6 +9,8 @@ require "socket"
 require "timeout"
 require "uri"
 
+require_relative "host_execution_observability"
+
 module Prauga
   module FlexDoc
     HostExecutionFile = Data.define(:filename, :content_type, :data)
@@ -33,7 +35,8 @@ module Prauga
 
       attr_reader :allowed_origins
 
-      def initialize(allowed_origins:)
+      def initialize(allowed_origins:, metric_sink: nil)
+        @metric_sink = metric_sink
         normalized = Array(allowed_origins).filter_map do |raw|
           value = raw.to_s.strip
           next if value.empty?
@@ -52,38 +55,90 @@ module Prauga
         @allowed_origins = normalized.uniq.freeze
       end
 
+      attr_reader :metric_sink
+
       def capabilities
         []
       end
 
+      # Validate the marker and map executor failures to canonical JSON errors.
+      #
+      # This is the single choke point every transport reaches, so it is also where
+      # execution evidence is emitted: one started/completed pair per validated
+      # envelope, and an unmarked counter for requests that never became executions.
       def handle(marker:, envelope:, files: {})
-        return HostExecutionResult.new(status: 403, body: { "error" => "Missing X-FlexDoc-Execute header." }) unless marker == "1"
+        unless marker == "1"
+          # Counted outside the lifecycle: an unmarked request never became an
+          # execution, and folding it into rejections would double-count attempts.
+          metric("flexdoc_execute_unmarked_total", "counter", 1, { "reason" => "marker-missing" })
+          return HostExecutionResult.new(status: 403, body: { "error" => "Missing X-FlexDoc-Execute header." })
+        end
 
-        HostExecutionResult.new(status: 200, body: execute(envelope, files))
-      rescue ExecutionError => error
-        HostExecutionResult.new(status: error.status, body: { "error" => error.message })
+        metric("flexdoc_execute_requests_total", "counter", 1)
+        metric("flexdoc_execute_in_flight", "gauge", 1)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          body = execute(envelope, files)
+        rescue ExecutionError => error
+          complete(error.status >= 500 ? "error" : "rejected", started, error.reason, error.status)
+          return HostExecutionResult.new(status: error.status, body: { "error" => error.message })
+        rescue StandardError
+          complete("error", started, "upstream-error", 502)
+          raise
+        end
+        complete("success", started)
+        HostExecutionResult.new(status: 200, body:)
       end
 
       private
 
       class ExecutionError < StandardError
-        attr_reader :status
+        attr_reader :status, :reason
 
-        def initialize(status, message)
+        # Messages interpolate origins, field names and methods, so they are
+        # unbounded and cannot be aggregated. The reason can, and it matches the
+        # Node, Python, Go and Rust vocabulary exactly.
+        def initialize(status, message, reason)
           @status = status
+          @reason = reason
           super(message)
         end
       end
 
-      def bad_request(message) = raise(ExecutionError.new(400, message))
-      def forbidden(message) = raise(ExecutionError.new(403, message))
-      def upstream(message) = raise(ExecutionError.new(502, message))
+      def bad_request(message, reason = "request-invalid") = raise(ExecutionError.new(400, message, reason))
+      def unsupported(message, reason = "auth-unsupported") = raise(ExecutionError.new(400, message, reason))
+      def forbidden(message, reason = "destination-forbidden") = raise(ExecutionError.new(403, message, reason))
+      def upstream(message, reason = "upstream-error") = raise(ExecutionError.new(502, message, reason))
+
+      def complete(outcome, started, reason = nil, status = nil)
+        metric("flexdoc_execute_in_flight", "gauge", -1)
+        metric("flexdoc_execute_completions_total", "counter", 1, { "outcome" => outcome })
+        elapsed = [Process.clock_gettime(Process::CLOCK_MONOTONIC) - started, 0.0].max
+        metric("flexdoc_execute_duration_seconds", "histogram", elapsed, { "outcome" => outcome })
+        return if reason.nil?
+
+        if outcome == "rejected"
+          metric("flexdoc_execute_rejections_total", "counter", 1,
+                 { "source" => "route", "statusCode" => (status || 400).to_s, "reason" => reason })
+        else
+          metric("flexdoc_execute_errors_total", "counter", 1, { "reason" => reason })
+        end
+      end
+
+      def metric(name, kind, value, labels = {})
+        return if @metric_sink.nil?
+
+        @metric_sink.call(HostExecutionMetric.new(name:, kind:, value:, labels:))
+      rescue StandardError
+        # Observability must never decide whether an execution succeeds.
+        nil
+      end
 
       def execute(envelope, files)
-        root = envelope.is_a?(Hash) ? envelope : bad_request("Host execution body must be a JSON object.")
-        bad_request("Session cookie jars are not implemented by the Ruby host executor.") if root["cookieJar"] == "session"
+        root = envelope.is_a?(Hash) ? envelope : bad_request("Host execution body must be a JSON object.", "body-malformed")
+        unsupported("Session cookie jars are not implemented by the Ruby host executor.") if root["cookieJar"] == "session"
         certificate_id = root["certificateId"].to_s
-        bad_request("Client certificates are not implemented by the Ruby host executor.") unless certificate_id.strip.empty?
+        unsupported("Client certificates are not implemented by the Ruby host executor.") unless certificate_id.strip.empty?
 
         draft = root["request"]
         bad_request("Host execution body requires a canonical request draft.") unless draft.is_a?(Hash)
@@ -123,9 +178,9 @@ module Prauga
             status = response[:status]
 
             if status.between?(300, 399) && response[:location]
-              forbidden("Host execution exceeded the redirect safety limit.") if redirect_count == MAX_REDIRECTS
+              forbidden("Host execution exceeded the redirect safety limit.", "redirect-forbidden") if redirect_count == MAX_REDIRECTS
               next_uri = request_uri.merge(response[:location])
-              forbidden("Host execution does not follow cross-origin redirects.") unless origin_of(next_uri) == origin_of(request_uri)
+              forbidden("Host execution does not follow cross-origin redirects.", "redirect-forbidden") unless origin_of(next_uri) == origin_of(request_uri)
               assert_allowed!(next_uri)
               if status == 303
                 method = "GET"
@@ -146,13 +201,13 @@ module Prauga
             }
           end
         end
-        forbidden("Host execution exceeded the redirect safety limit.")
+        forbidden("Host execution exceeded the redirect safety limit.", "redirect-forbidden")
       rescue Timeout::Error
-        upstream("Host execution request timed out after #{timeout_ms} ms.")
+        upstream("Host execution request timed out after #{timeout_ms} ms.", "upstream-timeout")
       rescue ExecutionError
         raise
       rescue StandardError => error
-        upstream("Host execution request failed: #{error.message}")
+        upstream("Host execution request failed: #{error.message}", "upstream-unreachable")
       end
 
       def perform_request(method, uri, headers, body, timeout_ms, validated_ip)
@@ -188,7 +243,7 @@ module Prauga
             end
             response.read_body do |chunk|
               if response_body.bytesize + chunk.bytesize > MAX_EXECUTION_RESPONSE_BYTES
-                upstream("Host execution response exceeded the 10 MiB safety limit.")
+                upstream("Host execution response exceeded the 10 MiB safety limit.", "body-too-large")
               end
               response_body << chunk.b
             end
@@ -212,14 +267,14 @@ module Prauga
         end
 
         addresses = Addrinfo.getaddrinfo(host, uri.port, nil, :STREAM)
-        upstream("Host execution could not resolve target hostname.") if addresses.empty?
+        upstream("Host execution could not resolve target hostname.", "upstream-unreachable") if addresses.empty?
         if addresses.any? { |address| metadata_ip?(address.ip_address) }
           forbidden("Host execution blocks DNS resolutions to link-local and cloud metadata endpoints.")
         end
 
         addresses.first.ip_address
       rescue SocketError
-        upstream("Host execution could not resolve target hostname.")
+        upstream("Host execution could not resolve target hostname.", "upstream-unreachable")
       end
 
       def parse_http_uri(raw)
@@ -301,12 +356,12 @@ module Prauga
           when "query"
             nil
           when "cookie"
-            bad_request("Cookie authentication is not implemented by the Ruby host executor.")
+            unsupported("Cookie authentication is not implemented by the Ruby host executor.")
           else
             bad_request("Unsupported API key location: #{location}")
           end
         else
-          bad_request("Authentication type #{string_value(auth["type"])} is not implemented by the Ruby host executor.")
+          unsupported("Authentication type #{string_value(auth["type"])} is not implemented by the Ruby host executor.")
         end
       end
 
@@ -354,7 +409,7 @@ module Prauga
         when "formdata"
           build_multipart(draft, files)
         else
-          bad_request("Body mode #{mode} is not implemented by the Ruby host executor.")
+          unsupported("Body mode #{mode} is not implemented by the Ruby host executor.")
         end
       rescue ArgumentError
         bad_request("Binary host execution bodyBase64 is invalid.") if mode == "binary"
@@ -376,7 +431,7 @@ module Prauga
             bad_request("Host execution multipart file formData[#{index}] is missing.") unless file
             filename = non_empty(file.filename.to_s) || non_empty(string_value(entry["fileName"])) || "upload.bin"
             content_type = non_empty(file.content_type.to_s) || non_empty(string_value(entry["contentType"])) || "application/octet-stream"
-            bad_request("Host execution multipart Content-Type is invalid.") if content_type.include?("\r") || content_type.include?("\n")
+            bad_request("Host execution multipart Content-Type is invalid.", "unsupported-media-type") if content_type.include?("\r") || content_type.include?("\n")
             output << "--#{boundary}\r\n"
             output << "Content-Disposition: form-data; name=\"#{quote_multipart(key)}\"; filename=\"#{quote_multipart(filename)}\"\r\n"
             output << "Content-Type: #{content_type}\r\n\r\n"

data/lib/prauga/flexdoc/host_execution_observability.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Prauga
+  module FlexDoc
+    # Execution evidence for the Ruby host executor.
+    #
+    # This mirrors the Node, Python, Go and Rust contract deliberately: the same
+    # reason vocabulary, the same metric names and labels, and the same export
+    # schema. An operator running a mixed fleet should read one document shape
+    # regardless of which runtime served the execute route, and a collector
+    # written for one runtime should not need a second parser for another.
+    module HostExecutionObservability
+      # Stable low-cardinality categories for a non-successful execution.
+      #
+      # Rejection messages interpolate request values such as origins, field
+      # names and methods, so they are unbounded and cannot be used as a metric
+      # label. These can.
+      HOST_EXECUTION_REASONS = %w[
+        marker-missing
+        execution-disabled
+        admission-saturated
+        destination-forbidden
+        redirect-forbidden
+        body-malformed
+        body-too-large
+        unsupported-media-type
+        request-invalid
+        auth-unsupported
+        upstream-timeout
+        upstream-unreachable
+        upstream-error
+      ].freeze
+
+      OBSERVATION_SCHEMA = "flexdoc.host-execution.observation/1"
+
+      # Evidence an API host cannot observe by itself, declared rather than omitted.
+      OBSERVATION_GAPS = %w[browser-direct-transport-mix].freeze
+
+      OUTCOMES = %w[success rejected error].freeze
+
+      def self.host_execution_reason?(value)
+        HOST_EXECUTION_REASONS.include?(value)
+      end
+    end
+
+    # One dependency-free metric update that can be bridged to Prometheus or
+    # OpenTelemetry without FlexDoc owning a registry.
+    HostExecutionMetric = Data.define(:name, :kind, :value, :labels) do
+      def initialize(name:, kind:, value:, labels: {})
+        super
+      end
+    end
+
+    # Aggregates host-execution evidence for one window, free of request content.
+    #
+    # Only counters and durations are retained. No URL, header, body, credential
+    # or per-request timestamp reaches this recorder, so the aggregate cannot
+    # carry request content by construction.
+    #
+    # Durations are retained up to +duration_sample_capacity+ and then replaced by
+    # reservoir sampling, so memory stays bounded for a host that runs
+    # indefinitely while percentiles stay representative of the whole window
+    # rather than only its opening. Counts stay exact regardless.
+    class HostExecutionObservation
+      def initialize(duration_sample_capacity: 8192, clock: -> { Time.now }, random: -> { Kernel.rand })
+        @capacity = [duration_sample_capacity.to_i, 1].max
+        @clock = clock
+        @random = random
+        @mutex = Mutex.new
+        reset
+      end
+
+      # Discard all counts and start a new window.
+      def reset
+        @mutex.synchronize { clear_state }
+        nil
+      end
+
+      # Fold one metric update into the aggregate. Safe to pass as a metric sink
+      # from concurrent request handlers.
+      def record(metric)
+        @mutex.synchronize do
+          timestamp = @clock.call
+          @window_start ||= timestamp
+          @window_end = timestamp
+
+          case metric.name
+          when "flexdoc_execute_requests_total"
+            @started += 1
+          when "flexdoc_execute_in_flight"
+            @in_flight = [@in_flight + metric.value.to_i, 0].max
+            @peak_in_flight = [@peak_in_flight, @in_flight].max
+          when "flexdoc_execute_completions_total"
+            @completed += 1
+            outcome = metric.labels["outcome"] || metric.labels[:outcome]
+            @outcomes[outcome] += 1 if @outcomes.key?(outcome)
+          when "flexdoc_execute_rejections_total"
+            tally(@rejections, metric.labels["reason"] || metric.labels[:reason])
+          when "flexdoc_execute_unmarked_total"
+            # Deliberately not folded into rejections: those describe validated
+            # envelopes, and merging the two would double-count attempts.
+            @unmarked += 1
+          when "flexdoc_execute_errors_total"
+            tally(@errors, metric.labels["reason"] || metric.labels[:reason])
+          when "flexdoc_execute_duration_seconds"
+            record_duration(metric.value.to_f)
+          end
+        end
+        nil
+      end
+
+      # A callable sink usable directly as the executor's +metric_sink+.
+      def sink
+        method(:record)
+      end
+
+      # Current aggregate; safe to call at any time.
+      def snapshot
+        @mutex.synchronize do
+          ordered = @durations.sort
+          {
+            "windowStart" => @window_start&.utc&.iso8601(3),
+            "windowEnd" => @window_end&.utc&.iso8601(3),
+            "startedExecutions" => @started,
+            "unmarkedRequests" => @unmarked,
+            "completedExecutions" => @completed,
+            "outcomes" => @outcomes.dup,
+            "inFlight" => @in_flight,
+            "peakInFlight" => @peak_in_flight,
+            "rejectionsByReason" => @rejections.dup,
+            "errorsByReason" => @errors.dup,
+            "durations" => duration_summary(ordered)
+          }
+        end
+      end
+
+      private
+
+      def clear_state
+        @window_start = nil
+        @window_end = nil
+        @started = 0
+        @unmarked = 0
+        @completed = 0
+        @in_flight = 0
+        @peak_in_flight = 0
+        @observed_durations = 0
+        @outcomes = HostExecutionObservability::OUTCOMES.to_h { |outcome| [outcome, 0] }
+        @rejections = {}
+        @errors = {}
+        @durations = []
+      end
+
+      def tally(counts, reason)
+        return unless HostExecutionObservability.host_execution_reason?(reason)
+
+        counts[reason] = counts.fetch(reason, 0) + 1
+      end
+
+      def record_duration(seconds)
+        milliseconds = [seconds * 1000, 0.0].max
+        @observed_durations += 1
+        if @durations.length < @capacity
+          @durations << milliseconds
+          return
+        end
+        candidate = (@random.call * @observed_durations).to_i
+        @durations[candidate] = milliseconds if candidate < @capacity
+      end
+
+      def duration_summary(ordered)
+        return nil if ordered.empty?
+
+        {
+          "sampleCount" => ordered.length,
+          "sampled" => @observed_durations > ordered.length,
+          "minMs" => ordered.first,
+          "p50Ms" => percentile(ordered, 0.5),
+          "p95Ms" => percentile(ordered, 0.95),
+          "p99Ms" => percentile(ordered, 0.99),
+          "maxMs" => ordered.last
+        }
+      end
+
+      def percentile(ordered, fraction)
+        return ordered.first if ordered.length == 1
+
+        rank = (fraction * ordered.length).ceil.clamp(1, ordered.length)
+        ordered[rank - 1]
+      end
+    end
+
+    # Build the operator export document for a host-execution observation.
+    #
+    # The document is aggregate-only and is meant to be written to disk or handed
+    # to an operator; FlexDoc never transmits it. Browser-direct executions never
+    # reach an API host, so the transport mix cannot be derived here, and that gap
+    # is declared so a review cannot mistake this document for complete evidence.
+    def self.host_execution_observation_report(observation, generated_at: nil)
+      {
+        "schema" => HostExecutionObservability::OBSERVATION_SCHEMA,
+        "generatedAt" => generated_at || Time.now.utc.iso8601(3),
+        "runtime" => "ruby",
+        "observation" => observation.snapshot,
+        "gaps" => HostExecutionObservability::OBSERVATION_GAPS.dup
+      }
+    end
+  end
+end

data/lib/prauga/flexdoc/version.rb

@@ -2,6 +2,6 @@
 
 module Prauga
   module FlexDoc
-    VERSION = "0.4.7"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prauga-flexdoc
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.5.0
 platform: ruby
 authors:
 - Prauga
@@ -113,6 +113,7 @@ files:
 - lib/prauga/flexdoc/config.rb
 - lib/prauga/flexdoc/host.rb
 - lib/prauga/flexdoc/host_execution.rb
+- lib/prauga/flexdoc/host_execution_observability.rb
 - lib/prauga/flexdoc/rack_app.rb
 - lib/prauga/flexdoc/rails.rb
 - lib/prauga/flexdoc/response.rb