prauga-flexdoc 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 471bae74b8f366cfac9597b1b23ae6eccfcb50920bbe0540592320c7056e4aa5
-  data.tar.gz: 47466979054e4a7ab777388d0b32a3d70c78588fe7c32761615bfba6d25a2863
+  metadata.gz: e0ad5c0a29615b41c949585cb71e6991d212c10c9edabd9cbddf68d9ed5888d8
+  data.tar.gz: 475a99a8da26711567faee0746eda38fbedf36ff5b06f268ad5d075c3cd4bb1f
 SHA512:
-  metadata.gz: 62b0f17dc58050deb5504565005fa58147114f5a8431fbbcacc2ad5c08cf2f61a0ccdb524ca0b1d39c4b7ce9ef8ef0bdb24a79c0204a3b6de84ea66805eda3cb
-  data.tar.gz: 1eb373b2d4cda0a94fdbf883b87629f8f85011f167721327c82b26825142c74cd01a8172b96bc173ca1a3657f414de45baccf1a54e164a62631e6c52267d9c4a
+  metadata.gz: 51f75c062a8b0d0bfc0f475b85845332f8f04f861e21c8573ab188e4ec0ff29119ce2dab990f07ceed9d79c4c1ad004db90e997d7769eeb17b10bd98c5a6a062
+  data.tar.gz: 988e43033ae430ae1388c60fe4d97c7171f4ceb71875df3f2e3fc7168e14284a1037843782c826db61cc2145b64ede757322c9a31fa4ffa03c460de30e63d53e

data/README.md

@@ -1,6 +1,6 @@
 # Prauga FlexDoc for Ruby
 
-`prauga-flexdoc` `0.4.4` provides one framework-neutral Ruby 3.2+ host for the canonical FlexDoc renderer, plus thin Rack and Rails integrations.
+`prauga-flexdoc` `0.4.5` provides one framework-neutral Ruby 3.2+ host for the canonical FlexDoc renderer, plus thin Rack and Rails integrations.
 
 ## Rack
 
@@ -22,6 +22,37 @@ run Prauga::FlexDoc::RackApp.new(host)
 
 The Rack app reconstructs `SCRIPT_NAME + PATH_INFO`, so it also works correctly when mounted beneath another Rack application.
 
+## Native host execution (3.3)
+
+Ruby can execute Try It requests inside the API host using the same FlexDoc execute envelope used by Node, the Runner, and the other native adapters. Execution is opt-in and requires both `try_it_host_execution: true` and a real executor with a non-empty exact-origin allowlist:
+
+```ruby
+executor = Prauga::FlexDoc::HostExecution.new(
+  allowed_origins: ["https://api.internal.example"]
+)
+
+host = Prauga::FlexDoc::Host.new(
+  Prauga::FlexDoc::Config.new(
+    path: "/docs",
+    spec_url: "/openapi.json",
+    try_it_host_execution: true
+  ),
+  host_execution: executor
+)
+
+# Configure application authentication/authorization middleware around the
+# FlexDoc subtree first, then acknowledge that boundary explicitly.
+run Prauga::FlexDoc::RackApp.new(host, host_execution_protected: true)
+```
+
+The Rack transport then owns `POST /docs/__flexdoc/execute`. Without a real executor, FlexDoc advertises `available: false` and the execute path remains a 404.
+
+**Fail-closed rule:** when host execution is available, `RackApp.new` raises `ArgumentError` unless `host_execution_protected: true` is supplied. The flag does not authenticate requests; it is an explicit assertion that the surrounding Rack/Rails stack already protects the documentation and execute surface. The outbound origin allowlist is not user authentication.
+
+This first native slice supports the canonical JSON and multipart envelopes, Basic/Bearer/OAuth2-bearer and header/query API-key request auth, raw/JSON/binary/urlencoded/GraphQL/form-data bodies, same-origin redirect revalidation, unsafe-header stripping, a 32 MiB inbound envelope bound, a 10 MiB response bound, and a full-response deadline. Host-only cookies, client certificates, Digest/Hawk/NTLM/Kerberos, OAuth 1.0, AWS SigV4, host secrets, and runtime-derived environment are not advertised yet.
+
+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.
+
 ## Rails
 
 In `config/routes.rb`:
@@ -37,8 +68,10 @@ host = Prauga::FlexDoc::Host.new(
 Prauga::FlexDoc::Rails.mount(self, host: host, at: "/docs")
 ```
 
-Rails already uses Rack, so the Rails helper intentionally mounts the same `RackApp` rather than introducing a Rails-specific renderer host. If `at:` is supplied, it must resolve to the same normalized path as `host.config.path`; the helper raises immediately on a mismatch so the HTML shell cannot point at renderer asset URLs that the mounted Rack app will reject.
+Rails already uses Rack, so the Rails helper intentionally mounts the same `RackApp` rather than introducing a Rails-specific renderer host. If `at:` is supplied, it must resolve to the same normalized path as `host.config.path`; the helper raises immediately on a mismatch so the HTML shell cannot point at renderer asset URLs that the mounted Rack app will reject. Native execution uses that same mounted Rack app, so Rails does not need a separate executor implementation.
+
+When the host has native execution available, protect the `/docs` mount with the application's authentication/authorization stack and pass `host_execution_protected: true` to `Prauga::FlexDoc::Rails.mount(...)`. The Rails helper forwards that acknowledgement into `RackApp`; omitting it keeps native execution fail closed.
 
 ## Packaging
 
-The gem packages the exact canonical `flexdoc.standalone.js` and `.css`. CI tests the neutral host, Rack mounting, Rails routing, gem contents, and byte-for-byte renderer parity.
+The gem packages the exact canonical `flexdoc.standalone.js` and `.css`. CI tests the neutral host, Rack mounting, Rails routing, native host execution, gem contents, and byte-for-byte renderer parity.