Update HTTP status codes and associated symbols

[wtn]

These commits bring Rack in sync with the 2022-06-08 version of the IANA HTTP Status Code Registry.

This change is notably impactful in that the symbol for HTTP status code 422 changes from :unprocessable_entity to :unprocessable_content. To mitigate the impact, I added legacy symbol lookup to Rack::Utils.status_code.

It seems that some Rubyists are in the habit of retrieving status codes from Rack::Utils::SYMBOL_TO_STATUS_CODE directly (examples: here, here, here) rather than using the public method. Admittedly, I've done this myself. Well, it can't be helped, but perhaps this pattern can be discouraged in the future.

[ioquatix]

This looks reasonable to me. @jeremyevans are you happy that backwards compatibility is sufficient?

[jeremyevans]

I'm good with the general idea.

[wtn]

I removed the duplicated constant and added deprecation warnings.

The use of Hash#invert here is not ideal, but I didn't want to add yet more constants.

[ioquatix]

Looking good, just a few minor suggestions.

[wtn]

Thank you for feedback. I've made the following changes:

1. use Hash#fetch in fallback symbol lookup
2. rename OBSOLETE_HTTP_REASON_PHRASES to OBSOLETE_SYMBOLS_TO_STATUS_CODES and make it private
3. add private constant OBSOLETE_SYMBOL_MAPPINGS to precompute preferred symbol for deprecation message
4. use ternary statement for deprecation warning for succinctness and readability

[jeremyevans]

This looks almost ready. I just have a couple of minor change requests.

[ioquatix]

LGTM, let's see if @jeremyevans is okay to merge.

[rafaelfranca]

Can we introduce the new names but keep the old names not deprecated?

For a libraries on top of rack the only way to support Rack 2 and Rails 3 at the same time after this change is by introducing a bunch of conditionals on the version of rack.

[ioquatix]

@rafaelfranca feel free to create a PR, not completely sure what issue you are having but sounds reasonable.

[rafaelfranca]

Will do.

The problem is that in Rails we have a few controllers with head :unprocessable_entity. To work without deprecation on Rack 3 we need to change it to head :unprocessable_content, but that doesn't work on Rack 2. So to work on both version we need to change the code to be:

head RACK_VERSION >= "3" ? :unprocessable_content : :unprocessable_entity

or some variation of that.

I'm also considering dropping support to Rack 2, in that case the problem will be solved for Rails 8, but not for 7.1, but I can probably work around the issue itself in Rails since that code will not live for much loger.

[ioquatix]

I believe you can use the status_code helper? Maybe it resolves the issue for you.

[rafaelfranca]

That shows the deprecation. We don't want Rails to show people deprecation message for code the framework has.

[wtn]

In my view, it's best to keep the deprecation message in Rack.

Frameworks like Rails can manage the transition by adding status code symbols:

if Gem::Version.new(Rack.release) >= Gem::Version.new('3.y.z')
  Rack::Utils::SYMBOL_TO_STATUS_CODE[:payload_too_large] = 413
  Rack::Utils::SYMBOL_TO_STATUS_CODE[:unprocessable_entity] = 422
end

SYMBOL_TO_STATUS_CODE is not frozen, consider it part of the public API.

[rafaelfranca]

This is exactly my point. I don't think rack should be pushing frameworks to do version checks. Rack is supposed to be a stable API. If a framework that depends on rack needs to check a version of the library we can't consider Rack stable anymore.

I'm all for adding features to Rack, but all their changes need to be backward compatible in a way that users don't have a hard time supporting 2 versions of Rack.

So my suggestion is: while Rack 2 is still supported, we don't show any deprecation, when only Rack 3 is supported we can add the deprecation in some Rack 3.x and in Rack 4 we remove it.

If this plan was hard to implement, I'd totally understand pushing version checks to users, but I'm sure we can keep an old status code name longer to make users' life easier.

[rafaelfranca]

Just to be clear, not criticizing the breaking changes/deprecations we had to do to evolve the spec, fix issues, etc, just saying there are a few like this one we can avoid if we decide to.

[tenderlove]

SYMBOL_TO_STATUS_CODE is not frozen, consider it part of the public API.

I don't think we should consider mutating another library's constants to be "part of the public API". It's true that the constant is not frozen, but I also consider it bad manners to mutate someone else's constants. Also, in general, I think it's acceptable to freeze a constant but not do a major version release. IOW constant mutation is not public API, please do not consider it as such. If we want an API to mutate this constant, then we should add methods people call to register keys and values.

So my suggestion is: while Rack 2 is still supported, we don't show any deprecation, when only Rack 3 is supported we can add the deprecation in some Rack 3.x and in Rack 4 we remove it.

If this plan was hard to implement, I'd totally understand pushing version checks to users, but I'm sure we can keep an old status code name longer to make users' life easier.

I think this is reasonable.