Pass Grape::Exceptions::ErrorResponse to error_formatter#call

[ericproulx]

Summary

Resolves #2527.

Middleware::Error#error_response already constructs a Grape::Exceptions::ErrorResponse value object — it then unpacks it into five separate positional/keyword arguments to hand to the formatter, which immediately repacks the pieces. Cut out the round-trip: pass the value object through.

New formatter signature

def call(error:, env: nil, include_backtrace: false, include_original_exception: false)

• error: — a frozen Grape::Exceptions::ErrorResponse carrying status, message, headers, backtrace, original_exception. Built once by error_response (with defaults from default_status / default_message / the resolved content-type / fallback backtrace already applied) and threaded through unchanged.
• env: — Rack env, still needed by present(message, env) for entity-presenter resolution.
• include_backtrace: / include_original_exception: — request-time toggles forwarded from the matching rescue_from options. Renamed from the old rescue_options[:backtrace] / [:original_exception] Hash lookups; previously buried inside options[:rescue_options].

Internal plumbing

• Middleware::Error#format_message now takes a single error arg and forwards it directly to the formatter. The unsupported-format throw path reads error.backtrace / error.original_exception off the same value object.
• Middleware::Error#error_response builds the resolved ErrorResponse via raw.with(status: …, message: …, headers: …, backtrace: …) instead of plucking the five fields into separate locals.
• Middleware::Error#error! wraps its positional args into an ErrorResponse before calling format_message.

Side cleanups (carried from earlier on the branch)

• :rescue_options is now a Grape::DSL::RescueOptions value object (built on Data.define(:backtrace, :original_exception) with defaults) instead of a plain Hash. Middleware::Error exposes include_backtrace / include_original_exception via Forwardable.def_delegator :rescue_options, :backtrace, :include_backtrace (same for original_exception).
• DSL::RequestResponse#rescue_from switched from **options to explicit kwargs (with:, rescue_subclasses: true, backtrace: false, original_exception: false); :rescue_subclasses defaults to true so the nil-treated-as-true case-when collapses to a one-liner. The stackable now stores a RescueOptions instance.
• rescue_from YARD now documents original_exception:, which has been a real (but undocumented) option since Bubble up to the error_formatter the original exception and the backtrace #1652.
• Endpoint#build_stack reads the latest stacked RescueOptions directly (namespace_stackable[:rescue_options]&.last) instead of the hash-only namespace_stackable_with_hash.
• Two options[:default_status] / options[:default_message] lookups in Middleware::Error#error_response replaced with the existing default_status / default_message attr_readers.

What this unlocks

JSON:API-style error responses become a one-liner:

error_formatter :json, ->(error:, **) {
  { errors: [{ status: error.status.to_s, detail: error.message }] }.to_json
}

Header-aware formatters work the same way:

error_formatter :txt, ->(error:, **) {
  "[#{error.status}] #{error.message} (#{error.headers['x-marker']})"
}

Breaking change

Custom formatters that override call with the old positional signature will break. UPGRADING.md has a before/after section under ### Upgrading to >= 3.3 with a per-field migration table covering each old positional arg → new accessor (message → error.message, backtrace → error.backtrace, options[:rescue_options][:backtrace] → include_backtrace, etc.).

Built-in formatters (Json, Txt, Xml, SerializableHash) are unaffected — they only override format_structured_message, not call. Existing tests in spec/grape/api_spec.rb, spec/grape/middleware/exception_spec.rb, and spec/grape/dsl/request_response_spec.rb have been migrated.

Test plan

• Full suite: bundle exec rspec — 2308 examples, 0 failures
• RuboCop clean on touched files
• New spec in spec/grape/api_spec.rb (with status and headers exposed (issue 2527)) verifies error.status and error.headers reach a custom formatter
• CI green across Gemfile variants

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run