Document the definition-time rejection of uncoercible collection types

[ericproulx]

Summary

#2817 has an unrecorded breaking side effect. Declaring type: Array[Foo] / type: Set[Foo] where Grape cannot coerce Foo now raises while the API class is being loaded:

ArgumentError: type Foo should support coercion via `[]`

An application that boots today can fail to boot on 4.0, without any request being made. This adds the UPGRADING entry and pins the behavior with specs.

Found while investigating grape-swagger's suite failing against grape master — 12 of its failures are this, from fixtures declaring type: Array[Entities::ApiError] on an OpenStruct subclass used purely for documentation.

What actually changed

Nothing about which types are supported — only when the element coercer is built. #2817 made ArrayCoercer build it eagerly in the constructor instead of memoizing it on first use, so that coercers (shared across requests, and cached in CoercerCache) create no state at request time. Building it eagerly means an unsupported element type is discovered at definition.

Before, it was built on the first request that supplied the parameter. So a declaration never exercised by a request never raised at all; one that was exercised got the same ArgumentError swallowed by the coercion validator into a generic 400 {"error":"foo is invalid"}.

This is a correct tightening

declaration	3.3.4	master
type: Foo	ArgumentError when defined	unchanged
type: Array[Foo]	accepted; 400 "is invalid" per request	ArgumentError when defined

The non-collection form has always raised at definition time. The collection form's leniency was an accident of the lazy build, not a supported behavior — and it wasn't a working feature but a landmine, since the parameter could never actually be coerced. The two are now consistent. I'm documenting it rather than reverting it.

Verified across 3.2.0 and 3.3.4 (both accept) and bisected on master to e209dbe7 (#2817) as the first commit that rejects.

The UPGRADING entry

Covers what raises, why, the before/after table, and the three fixes that actually work — each verified end-to-end, not just at load:

• a one-argument self.parse (routes to CustomTypeCollectionCoercer, 200)
• coerce_with: supplying the whole collection (no element coercer is built, 200)
• dropping type: for documentation: { type: Foo } when the class only describes the parameter — the case behind this break

It also warns that defining self.[] silences the load-time error without fixing anything: that's the escape hatch for dry-types objects, and a plain class taking it still fails 400 "is invalid" on every request. I nearly listed coerce_with as a non-fix for the same reason before testing it properly — the distinction is easy to get wrong, hence the explicit note.

Specs

Nothing asserted this anywhere — should support coercion via appeared in no spec — so a future refactor could revert it as silently as #2829 reverted #2824. Five examples added under ::build_coercer: Array/Set/params-block rejection, plus the parse and coerce_with acceptances.

The three "raises" examples fail against the pre-#2817 lazy build and pass against the eager one — verified in both directions.

Notes

• Also extends Remove request-time mutable state from Array and custom-type coercers #2817's CHANGELOG entry, which described only the thread-safety cleanup.
• Full bundle exec rubocop and bundle exec rspec (2521 examples) pass.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run