Replace #status_code with #status

[dwightwatson]

This is a follow-up to #7231 but broken out into another PR because the direction changed a bit from the discussion over there - thought it might be wise in case that direction is reversed. This basically introduces a number of breaking changes:

• #status_code on the response object is replaced with #status which is an instance of HTTP::Status. It encapsulates everything needed to do with HTTP status codes.
• HTTP.default_status_message_for was replaced by the HTTP::Status object's description and it will now return nil instead of an empty string when it doesn't have an answer.
• You can still set status_code= if you like, and it will be mapped under the hood to an instance of HTTP::Status.
  *HTTP::Status has #code so can call status.code to get the integer value instead of needing to know to call status.value.

Open to more guidance and feedback here. Hope it's going in the direction you'd like to see - there were a lot of comments on the last PR and I've tried to take it all into consideration.

[straight-shoota]

When starting with a fresh PR, could you please squash the commits into logical pieces (probably similar to your bullet points)? That makes it much easier to review and follow the individual changes. Thanks 👍

[straight-shoota]

This looks good!

There is however still an issue with creating a new HTTP::Status instance from an arbitrary status code number. .new on enums is implicitly defined and technically not part of the public API. As far as I can tell, it can neither be overriden nor documented.
Thus, we'd probably need to use a method with a different name that can be documented as part of the public API and validate the assigned value.
Probably something like this:

# Create a new `HTTP::Status` instance from *status_code* number.
# The values are not limited to defined enum members, but also allow to use custom status codes. Any number in the range 100..999 is allowed.
def HTTP::Status.from_code(status_code : Int32)
  raise "Invalid status code" unless 100 <= status_code <= 999
  new(status_code)
end

HTTP::Status.from_code should be used everywhere instead of .new.

[asterite]

Maybe we could move this method to a body_mandatory? in the HTTP::Status enum (it could be done in a separate PR).

[dwightwatson]

Happy to tackle that one separately.

[straight-shoota]

In light of #7266 suggest to rename Status.code to Status.new because it was only a workaround in the first place and is no longer needed.
The compiler change is non-breaking and goes into 0.27.1, so this feature can safely be merged to 0.28.0 (where this PR needs to go anyway, because it's breaking the API).

NOTE: Implementing this needs a very recent compiler build from master.

[dwightwatson]

@straight-shoota Do you mean replace .from_code with .new?

And is this the sort of implementation you'd expect - defining self.new instead of initialize and then calling private_def inside of that?

def self.new(status_code : Int32)
  raise ArgumentError.new("Invalid HTTP status code: #{status_code}") unless 100 <= status_code <= 999
  previous_def(status_code)
end

[dwightwatson]

Seems like the tests fail now (but work fine locally). Do the tests not run with a fresh build of Crystal?

[straight-shoota]

Specs must pass with latest compiler release and a fresh build from current master. This is to ensure every compiler release can be build with the previous one.
Thus CI is expected to fail, but that's fine. We'll revisit once 0.27.1 is released.

[bcardiff]

@dwightwatson I notice you are already merging from master. Once you make the CI happy we need a 👍 from @asterite / @RX14 before saquash merging this PR. Thanks!

[Sija]

Needs a rebase to make CI (with Crystal 0.27.1) green.

[dwightwatson]

Back to green now, please let me know if there is anything more I can do to get this merged in.

[Sija]

Btw, is this GTG already?

[bcardiff]

I think we are ready to (squash) merge this PR.
With the current status I don't think there is a breaking-change, am I wrong?

[asterite]

@bcardiff HTTP::Response#status_code is renamed to HTTP::Response#status. This is a breaking change.

[asterite]

@bcardiff It also changes it from a number to an enum (once you rename status_code to status you'll need to do some more changes)

[bcardiff]

@asterite but #status_code is preserved as a getter and the initializer with and Int is available also.

[z64]

@bcardiff It currently removes the public HTTP.default_status_message_for(int) method, replaced by HTTP::Status.new(int).description

[asterite]

@bcardiff You are right, sorry for the confusion

[straight-shoota]

Thank you @dwightwatson ❤️