prauga-flexdoc 0.4.6 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 798627606d78584437759e1205cdc1b8caa77ac1cc9535bf84fc07d38ff5cbf0
-  data.tar.gz: 7c8ade813f5e428aa9b403cd52d9a2fd5a57397d9c7aae8b15e06c661d072f15
+  metadata.gz: 2cfa79303d5ae57884ca1c3fc8157eecf7852a764c04edeece1f72302cb9f881
+  data.tar.gz: e2946cba95ac973864b0f81e8b0e9a46165fa1685b2bff3b1bfa7e3b07e8bda3
 SHA512:
-  metadata.gz: fc5826d44e100d68f1cd98918013d2645e0522fcddd530871bc7360d1aeda3bd3b552b066c246ceda60d3544391b0090dd03595e081c6e694361ef44b7a50864
-  data.tar.gz: b50a006a186fc7e1477dadb40bf949ce06b8d6095b2ab7e038595ef6c59ca6c3ce92533b194074827c7426857eac2863e54a699102456e23de4db2f9dc61aa72
+  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`: