feat(file-resolve): route file_id callouts through a filtered outbound chain

[leseb]

Summary

Route openai_file_resolve's configured Files API (file_id) metadata and content callouts through a filtered outbound chain executed via the FilteredSubrequestExecutor, replacing the direct subrequest path. The chain's filters observe and can mutate each callout before it is dialed. Client-controlled file_url downloads stay on the credential-free hardened resolver and never traverse the chain.

Closes #960.

What changed

• New outbound_chain config key on openai_file_resolve — an inline filter chain applied to configured file_id metadata + content callouts.
• allow_private_files_api_url removed. SSRF protection for files_api_url now derives from the pipeline's allow_private_upstreams, enforced both when the callout target is pinned (prepare_url_target) and again at connect time.
• New internal filter openai_callout_seed_upstream projects the validated, pinned upstream onto the callout context (the executor dials ctx.upstream, which only a chain filter can set).
• Example configs updated (drop the removed flag, add the outbound chain + allow_private_upstreams); generated filter docs regenerated.

Design: head + tail upstream seed

The seed is installed at both ends of the inline chain:

• the head projects the pinned upstream so an operator's own filters observe the real destination;
• the tail reasserts the pinned upstream after those filters run, so an operator filter (e.g. an endpoint_selector) cannot silently retarget a callout that still carries Files API credentials.

The seed clones rather than consumes the staged upstream so both instances see it. Named outbound chains are rejected at build time — the seed cannot be injected into a chain resolved by name inside the binding context, so the field is inline-only.

⚠️ Draft: dependency status

This PR consumes praxis-core APIs that landed in praxis PR #1166 (URL-aware target preparation for subrequests + the chain-binding callout executor), which is not yet in a crates.io release. Locally it builds against a [patch.crates-io] git-rev pin of praxis main; that dev-only patch (and its Cargo.lock churn) is intentionally excluded from the commit, so CI will be red until praxis publishes a release containing #1166 and we bump the [workspace.dependencies] version. No functional code change is needed at that point — just the version bump.

Known praxis-executor limitations (fail-closed, documented in-code)

Two behaviors from the previous direct-subrequest path cannot be fully preserved against the merged callout executor and are documented as honest, fail-closed limitations:

1. Multi-address DNS fallback. praxis Upstream carries a single address and the executor dials only it — there is no connect-fallback list like the old subrequest::execute_with_addresses. Dual-stack / multi-A hosts fail closed if the first validated address is unreachable. Minimal praxis fix: let Upstream/the executor carry and try multiple validated addresses.
2. Typed oversized-response result. TransportFailure::ResponseTooLarge is pub(crate) and collapsed into an opaque 502 inside executor.run(), so the typed 413/ResponseTooLarge classification is lost. The common case is mitigated by the existing metadata pre-check (metadata.bytes vs max_content_bytes, which rejects before download); the residual case fails closed as 502. Minimal praxis fix: surface the typed overflow result from run().

Tests

• Unit: openai_callout_seed_upstream head/tail reassert (incl. a mid-chain operator-override defeat test); registration installs seed at head+tail and rejects named chains.
• Integration: file_id runs through the outbound chain while file_url does not (observable via a marker header).
• SDK: new OpenAI-client integration test (test_file_id_resolved_via_outbound_chain_not_file_url) proving file_id → chain-resolved base64 content and file_url → data-URI (chain not run).

Preserved: caching, ref limits, rewritten-body/resolved budgets, deadlines, on_missing, DNS-rebind/SSRF validation, TLS/SNI/Host, static creds, forward_headers.

[praxis-bot]

Re-review (praxis-bot) -- 1 finding.

[Medium] tests/utils/src/proxy.rs: duplicate set_allow_private_upstreams call. The new line (added before add_pipeline_extension) and the existing line (after it) both call pipeline.set_allow_private_upstreams(config.insecure_options.allow_private_upstreams). The second call is redundant since set_allow_private_upstreams does not interact with extensions. Remove one of the two calls to match the server's configure_pipeline, which has a single call.