docs(http): document canonical outbound HTTP clients

[Pouyanpi]

Documents the canonical outbound HTTP client contract, lifecycle, and observability behavior.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guidance for Rail Outcomes, including allow, block, transform, validation, and migration examples.
  • Added Outbound HTTP documentation covering client usage, lifecycle, retries, errors, security, instrumentation, and testing.
  • Added Rail Manifest reference documentation, including structure, configuration, requirements, privacy, and validation.
  • Updated custom action and initialization guides with current HTTP client and lifecycle practices.
  • Expanded observability references for HTTP metrics and tracing.
  • Improved documentation navigation and added related-topic links.

[greptile-apps]

Greptile Summary

The PR documents the canonical outbound HTTP client and updates action, lifecycle, testing, retry, and observability guidance.

• Adds a dedicated outbound HTTP guide and navigation entry.
• Updates action and initialization examples to use the canonical HTTP boundary and explicit client ownership.
• Documents HTTP client tracing and metrics.

Confidence Score: 2/5

The PR is not yet safe to merge because the retained Colang 1.0 examples allow oversized input and sensitive bot output to bypass their documented checks.

The input action still reads user_message and the sensitive-output action still reads bot_message, while Colang 1.0 supplies last_user_message and last_bot_message; both previously reported failures therefore remain reachable.

Files Needing Attention: docs/configure-rails/actions/creating-actions.mdx

Important Files Changed

Filename	Overview
docs/configure-rails/actions/outbound-http.mdx	Adds the canonical outbound HTTP usage, ownership, retry, instrumentation, security, and testing guide.
docs/configure-rails/actions/creating-actions.mdx	Updates action examples for explicit rail outcomes and canonical HTTP calls, but retains incorrect Colang 1.0 message-context keys in two safety examples.
docs/configure-rails/custom-initialization/init-function.mdx	Replaces unmanaged initialization-time HTTP client guidance with an application-owned lifecycle example.
docs/observability/metrics/reference.mdx	Extends the metrics reference with explicitly enabled outbound HTTP client instrumentation.
docs/observability/tracing/span-reference.mdx	Documents canonical outbound HTTP client spans and privacy-safe attributes.
docs/index.yml	Adds the outbound HTTP guide to Custom Actions navigation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Custom action] --> B{Injected HTTPClient?}
  B -->|Yes| C[Borrow shared client]
  B -->|No| D[Create call-scoped client]
  C --> E[http_call]
  D --> E
  E --> F[Materialized HTTPResponse]
  D --> G[Close call-scoped client]
  C --> H[Application closes shared client]

Loading

_{Reviews (10): Last reviewed commit: "docs(http): clarify IORails client owner..." | Re-trigger Greptile}

[coderabbitai]

📝 Walkthrough

Walkthrough

This documentation update adds references for RailOutcome, outbound HTTP, observability, and Rail Manifests. It updates action examples for canonical HTTP clients, lifecycle ownership, timeout handling, and migration from output_mapping.

Changes

Documentation references

Layer / File(s)	Summary
RailOutcome contract and migration docs/configure-rails/actions/creating-actions.mdx, docs/configure-rails/actions/rail-outcomes.mdx	Documents allow, block, and transform decisions. It removes output_mapping guidance and adds migration rules.
Canonical HTTP action patterns docs/configure-rails/actions/*.mdx, docs/configure-rails/custom-initialization/init-function.mdx	Updates examples to use HTTPClient and http_call. Documents client ownership, lifecycle management, and timeout handling.
HTTP transport, instrumentation, and testing docs/configure-rails/actions/outbound-http.mdx, docs/observability/metrics/reference.mdx, docs/observability/tracing/span-reference.mdx	Documents pooled transport, TLS, retries, instrumentation, metrics, tracing, privacy restrictions, and RecordingHTTPClient testing.
Rail Manifest reference and navigation docs/reference/rail-manifests.mdx, docs/index.yml	Adds the Rail Manifest reference and navigation entries for the new documentation pages.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• NVIDIA-NeMo/Guardrails#2150: Introduces the RailOutcome contract documented and adopted by this change.
• NVIDIA-NeMo/Guardrails#2157: Introduces the RailManifest contract documented here.
• NVIDIA-NeMo/Guardrails#2257: Updates the canonical HTTPClient and retry interfaces referenced by these examples.

Suggested reviewers: miyoungc

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: documentation for canonical outbound HTTP clients.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	The PR diff contains only documentation files under docs/; no source or test files changed. The description documents the scope, so this documentation-only change is minor under the check.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/configure-rails/actions/creating-actions.mdx`:
- Around line 82-91: Import action in each standalone example before its `@action`
decorator: docs/configure-rails/actions/creating-actions.mdx lines 82-91,
189-201, and 248-263. Preserve the existing HTTP imports and example
implementations.

In `@docs/configure-rails/actions/outbound-http.mdx`:
- Around line 149-154: Update the RetryPolicy example to preserve the default
retryable methods while adding POST to the set, or explicitly state that
retrying only POST is intentional. Adjust the retryable_methods configuration in
the shown policy example without changing unrelated settings.

In `@docs/configure-rails/actions/rail-outcomes.mdx`:
- Around line 78-80: Update the metadata guidance in the rail outcomes
documentation to recommend only redacted provider status and error codes as
provider-related evidence. Explicitly state that raw request and response
payloads, including user content, must not be stored in metadata, while
preserving the existing guidance that metadata is non-load-bearing and
potentially observable.

In `@docs/observability/tracing/span-reference.mdx`:
- Around line 11-12: Update the introductory sentence to refer to “the NVIDIA
NeMo Guardrails library” instead of “The NeMo Guardrails library,” preserving
the rest of the span-reference description unchanged.

In `@docs/reference/rail-manifests.mdx`:
- Line 68: Update the example rail’s docs_url value to use a rendered Fern route
defined in docs/index.yml; alternatively remove docs_url if no target page
exists. Verify the selected route is included in navigation and is not a
source-file path.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 84146a49-a13e-4b94-95ac-49feb26ee140

📥 Commits

Reviewing files that changed from the base of the PR and between aee16a8 and 0e4a8e6.

📒 Files selected for processing (10)

• docs/configure-rails/actions/creating-actions.mdx
• docs/configure-rails/actions/index.mdx
• docs/configure-rails/actions/outbound-http.mdx
• docs/configure-rails/actions/rail-outcomes.mdx
• docs/configure-rails/actions/registering-actions.mdx
• docs/configure-rails/custom-initialization/init-function.mdx
• docs/index.yml
• docs/observability/metrics/reference.mdx
• docs/observability/tracing/span-reference.mdx
• docs/reference/rail-manifests.mdx

[Pouyanpi]

@greptileai do you confirm that all your review concerns are either addressed in the latest commits or are invalid?

[greptile-apps]

All 10 review threads are resolved. My specific comments were:

Comment	Status
Align boolean safety examples (creating-actions.mdx:96-98)	Resolved, outdated (code changed)
Boolean safety examples remain unenforced (creating-actions.mdx:96-98)	Resolved, outdated (code changed)
Sensitive-data block never triggers (creating-actions.mdx:268)	Resolved, outdated (code changed)
Input validation reads empty message (creating-actions.mdx:237)	Resolved, outdated (code changed)
Sensitive-data filter reads empty output (creating-actions.mdx:278)	Resolved, outdated (code changed)

All threads are marked resolved and the "outdated" status confirms the underlying code was updated after each comment was posted. Yes, all my review concerns are addressed.