fix: surface HTTP errors instead of silently skipping schema sync

[matthv]

Context

PRD-878. A client (core-banking-system, staging) was installing a new Forest Admin environment and its schema never reached Forest, with no visible error in their application logs — the Rails app booted normally. Root cause on the client side: FOREST_ENV_SECRET was copied with the variable name included in the value.

Root cause (gem side)

ForestAdminApiRequester builds its Faraday connection without the raise_error middleware, so a non-2xx HTTP response (e.g. a 404 "unknown secret key") never raises an exception. AgentFactory#do_server_want_schema just parsed the JSON body, found no sendSchema key, and treated it as "nothing to send" → logged Info: Schema was not updated since last run. The invalid secret was never detected, in any environment.

The HTTP-status-to-business-error mapping (handle_response_error, 404 → "invalid envSecret", etc.) already existed but was never reached on this path.

Fix

1. ForestAdminApiRequester#raise_for_response!(response): checks response.success? and raises the same typed errors handle_response_error already maps, without depending on the missing Faraday middleware. Called from both do_server_want_schema and send_schema_to_server.
2. ForestAdminErrorSubscriber (found while digging further): it dropped every log in production (return if is_production before any log) for ForestExceptions caught by Rails.error.handle at boot — invisible even on a real error. Logging is now unconditional, mapping the real Rails error severity: to the matching Forest logger level. severity: :error is now explicit on the Rails.error.handle call in engine.rb.
3. Addressed a review comment: the fallback InternalServerError was dropping the original error message from details — restored it (via cause&.message / response.reason_phrase).
4. AgentFactory#send_schema now validates env_secret (64-char lowercase hex) and auth_secret (must be a string) before syncing — mirroring the Node agent's OptionsValidator. This catches the exact client mistake (a secret copied with the variable name still glued to the value) instantly, without needing network access.
5. Both that format check and the actual server sync (post_schema) are handled the same way: raise in production, warn and move on everywhere else. A local secret typo, or a well-formed secret the server rejects (wrong project, revoked, network down), no longer blocks dev boot — logs two clear [ForestAdmin] Warn lines and skips the schema sync instead. The rescue is scoped to that HTTP sync call only (not the whole method), so a real local bug — a broken customization, an unwritable schema_path, a malformed append_schema file — still surfaces immediately in every environment instead of being logged as a generic warning (addressed after review feedback).
6. The validation only fires for a secret that was actually configured (non-nil), not merely present as a settings key, and it's checked from send_schema rather than setup so schema_only_mode (offline generation, e.g. rake forest_admin:schema:generate) never fails on a secret it doesn't need — both addressed after review feedback (Macroscope high-severity finding on the second one).

Resulting behavior (confirmed intentional, see PRD-878)

• In production, any problem syncing the schema — malformed secret, well-formed secret rejected by the server, network down — crashes the Rails server boot with a clear message, consistent with how every other Forest setup error is already handled.
• Outside production, the same problems log two clear Warn lines and let the app boot normally, skipping only the schema sync until it's fixed. A genuine local bug (customization, file I/O) is never swallowed — it always raises, in every environment.
• An agent that was never configured at all (secret left nil) stays completely silent, in every environment — matching the pre-PR behavior.
• schema_only_mode (offline generation) never validates secrets at all, since it never talks to the server.

Tests

• 785/785 forest_admin_agent tests green
• New spec forest_admin_error_subscriber_spec.rb
• No regression on forest_admin_rails / forest_admin_datasource_customizer (5 pre-existing forest_admin_rails failures confirmed identical on main, unrelated — missing gems locally)
• Rebased on latest main
• Reproduced and validated live on real Rails boots, in every combination: invalid-format secret in prod → crash; well-formed-but-wrong secret in prod → crash; either case outside production → warns and boots normally (app still serves traffic); unconfigured forest_admin_rpc_agent bundled in _examples/demo → no spurious warnings; valid secret → clean boot, no regression

Closes PRD-878

🤖 Generated with Claude Code

Note

Surface HTTP errors during schema sync instead of silently skipping

• Adds raise_for_response! to ForestAdminApiRequester that maps non-2xx HTTP responses to typed exceptions (NotFoundError, BadGatewayError, ServiceUnavailableError, InternalServerError); do_server_want_schema and send_schema_to_server now call this instead of ignoring failures.
• Validates env_secret format (64-char lowercase hex) and auth_secret type before attempting schema sync; in production, invalid config raises ValidationError, while non-production logs a warning and skips sync.
• Fixes @has_env_secret to be false when env_secret is nil (previously a nil secret was treated as present).
• Updates ForestAdminErrorSubscriber to log in all environments (including production) with severity mapping; previously errors were silently dropped in production.
• Behavioral Change: schema sync errors that were previously swallowed in production are now re-raised, which may surface startup failures that were previously hidden.

^{Macroscope summarized 9225c8e.}

[linear-code]

PRD-878

[arnaud-moncel]

🔥

[forest-bot]

🎉 This PR is included in version 1.37.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀