refactor(agent): forward workflow executor routes generically [PRD-567]

[matthv]

What

The agent proxies the workflow executor with one explicitly declared route per executor route (GET /_internal/workflow-executions/:run_id, POST .../trigger). Each new executor route therefore requires a matching agent route and an agent release — and the agent is customer-deployed, so a new executor capability is unreachable until the parc is upgraded.

This replaces the two hand-written routes with a single catch-all that forwards any sub-path and any verb to the executor's /runs/* namespace. Adding an executor route no longer requires any agent change.

fixes PRD-567

Design (decisions agreed with the ticket author)

• Catch-all ALL /_internal/workflow-executions/*path → /runs/<path>, all verbs.
• Request forwarded verbatim: all client headers (minus hop-by-hop / Host / Content-Length), raw body (no reshaping), query string and method as-is.
• Security boundary: the wildcard can only ever map into /runs — path-traversal (..), encoded dots (%2e), absolute paths and null bytes are rejected, so executor routes outside /runs (e.g. mcp-oauth-credentials) stay unreachable through the proxy.
• ForestController passes the raw request context (method/query_string/body) to the route closure; this is additive — other routes ignore the extra keys.
• Single large timeout (no per-verb), buffered, executor errors pass through verbatim.

Tests

rspec workflow_executor_proxy_spec → 22/22, including 7 path-traversal security cases (the "internal route not exposed" guard). Rubocop clean. The one pre-existing forest_controller_spec failure (exception_handler prod logging) is unrelated (fails on main too).

Scope

Phase 1 of 3 — this is the Ruby v2 agent. The Node @forestadmin/agent and the Ruby v1 liana (forest-rails) carry the identical coupling and will get the same generic proxy in follow-up PRs.

🤖 Generated with Claude Code

Note

Replace explicit workflow executor routes with a generic catch-all proxy in WorkflowExecutorProxy

• Replaces two specific GET/POST routes with a single catch-all route (/_internal/workflow-executions/*path) that forwards any HTTP verb and sub-path to the executor's /runs/* endpoint.
• Forwards raw request bodies (no JSON reshaping), preserves query strings verbatim, and forwards all headers except hop-by-hop/host/body-framing headers; executor response headers are also returned to the client.
• Adds path safety validation in unsafe_path? to reject traversal, encoded-dot, backslash, and null-byte paths with a NotFoundError.
• Updates ForestController to pass method, query_string, and body to route closures, and to merge top-level data[:headers] into the HTTP response.
• Risk: all proxied requests now use a unified 120s timeout (previously verb-dependent), and Faraday transport errors (including SSL) now map to 503 instead of propagating.

^{Macroscope summarized 42f1bc9.}

Known limitation (by design)

This runtime is JSON-only: responses are rendered as JSON (render json: ... via ForestController). A hypothetical non-JSON executor response (e.g. text/plain) would not pass through verbatim. The executor only returns JSON today, so this does not affect the PRD-567 contract in practice; the @forestadmin/agent Node core (agent-nodejs#1666) handles raw passthrough.

[linear-code]

PRD-567

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 7): forwarded_response_headers	1

[qltysh]

Function with high complexity (count = 7): forwarded_response_headers [qlty:function-complexity]

[christophebrun-forest]

LGTM after last commits.