[ericproulx]

Problem

Since #2618 (3.0.0) replaced extract_options! with keyword arguments, a trailing braced options Hash passed to version lands in the splat. Ruby 3 only turns a brace-less trailing Hash into keywords:

class API < Grape::API
  version 'v1', { using: :header, vendor: 'acme' }
  get('x') { 'ok' }
end

API.version                                 # => "{using: :header, vendor: \"acme\"}"
API.routes.map(&:path)                      # => ["/:version/x(.:format)"]
GET /x  Accept: application/vnd.acme-v1     # => 404
GET /v1/x                                   # => 200

The Hash became a version name, and the API silently stayed on the default :path strategy, with no warning. I found it while triaging #1801: its spec passes version_options this way, and on Ruby 3 every non-path context failed for this reason alone.

The Hash wasn't the only case. Each version was passed through to_s, whatever its type:

version …	registered	outcome
1	"1"	/1/foo → 200 (works)
1.10	"1.1"	/1.10/foo → 404
nil, '', :''	""	every path → 404
true	"true"	/true/foo → 200
Object.new	"#<Object:0x…>"	every path → 404
[]	nothing	every path → 404
['v1', { using: :header }]	"v1", "{using: :header}"	passed the Hash check, which ran before flatten

Fix

version flattens its arguments first and then checks every version. A Hash keeps its own message, since the options are what the caller meant:

ArgumentError: `version` takes its options as keyword arguments, not as a positional Hash

Anything else that isn't a non-empty String, Symbol or Integer raises:

ArgumentError: `version` takes non-empty String, Symbol or Integer versions, not `1.1`

An empty list raises `version` needs at least one version.

Integer is accepted because it round-trips exactly through the path, header and param strategies (version 2 serves /2/...). A code search found no numeric versions in about 200 Grape APIs, but they work today, and rejecting them would break working code for nothing. Float is rejected because it doesn't round-trip: version '1.10' is the fix.

This is how auth, http_basic and desc have handled a positional Hash since 4.0.0. I first tried redispatching the Hash as keyword arguments behind a deprecation warning, as #2853 did for requires, optional and use. That would quietly move an API that has served /v1/... since 3.0 onto header versioning in a minor release. Raising stops it at boot and points at the line instead.

The README now names the accepted types. UPGRADING (4.2.0) describes the break and how to keep path versioning when clients have been using /v1/...: version 'v1', or using: :path.

Tests

New examples under Grape::API .version:

• positional Hash: given with a version, with a block, alone, or inside an Array of versions. Each raises, and no version or route is registered.
• accepted types: String, Symbol and Integer versions, nested Arrays included, are all registered, and an Integer version is served at /2/hello.
• rejected types: nil, true, a Float, an empty String, an empty Symbol and an arbitrary object each raise, both as an argument and nested in an Array.
• empty list: version [[]] raises.

Each rule was mutation-checked by reverting it: flatten-then-validate (9 failures), Float rejected (2), empty name rejected (4), empty list rejected (1), Hash message (4). bundle exec rake: 379 files with no offenses, 3203 examples, 0 failures.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run

[dblock]

I’m an AI posting on behalf of @dblock.

Should we define which types are valid version names rather than only rejecting Hash? nil, booleans, and arbitrary objects still get stringified. String and Symbol seem natural, but we should check whether numeric versions are supported existing usage. Could we validate against an explicit set of supported types, with tests for those cases?

Separately, the operations are currently out of order: validation happens before flattening, so a Hash nested in an array bypasses the check, e.g. version ["v1", { using: :header }]. Flatten first, then validate the resulting arguments, with a test covering this case.