Provide documentation and context information for NIOTooManyBytesError

[cmcgee1024]

Motivation:

The NIOTooManyBytesError doesn't have any documentation for someone that encounters this error. Also, they have no idea the magnitude of the limit that was set to decide if the payload is an unreasonable size.

Modifications:

Provide documentation that explains the situation when the error occurs, which is the upTo limit of an AsyncSequence is exceeded. Describe one potential action, which is to increase this limit.

Provide the maxBytes in the error so that the user can gauge whether the upTo limit is already reasonable and the payload size is excessive, or the limit needs to be increased to suit more situations.

Result:

There will be documentation for the NIOTooManyBytesError so that if someone looks it up they will have a better understanding of the situation, and possible actions. The limit will be included in the error to give them an idea of the scale of the payload limit that is in place, or potentially the configuration value that they can change.

[cmcgee1024]

@weissi would it preferable to provide a backward compatible init function and make maxBytes optional?

[weissi]

@weissi would it preferable to provide a backward compatible init function and make maxBytes optional?

Yes, we should not break SemVer major just for this. I'll let @Lukasa & @FranzBusch et al comment more on what API would be good

[dnadoba]

We likely want to make two of these errors equal regardless of their value of the maxBytes property.

[dnadoba]

This should be a var. no need to restrict it to a let as there are no invariants or similar that need to be verified.

[Lukasa]

Also this should be public.

[cmcgee1024]

If it's var and public, then what's a good way to prevent it from being mutated after the initial throw?

[Lukasa]

There's no reason to prevent it being mutated. And indeed, given the init, you can't:

extension NIOTooManyBytesError {
   mutating func getOutOfMyWayFoolsIMutateWhatIWant(maxBytes: Int?) {
       self = .init(maxBytes: maxBytes)
   }
}

[cmcgee1024]

Ok, I've updated it to be public mutable.

[dnadoba]

The docs for a property should be above the property.

[Lukasa]

This generally looks good, but I'd like to see the tests updated to validate that this is working properly.

[Lukasa]

Also this should be public.

[Lukasa]

This should fail the test if the cast doesn't pass.

[Lukasa]

This should fail the test if the cast doesn't pass.

[dnadoba]

Can you add a custom Equatable and Hashable implementation that ignores maxBytes? == can just return true and hash(into:) can just hash a constant e.g. 0. Users are usually not interested in the specific maxBytes value but rather just that it is a NIOTooManyBytesError error.

[dnadoba]

Thanks! LGTM

[cmcgee1024]

After looking through the various failures I see that there's a formatter failure. How best to run the formatter for this project to reformat the code? Homebrew installing the swift-format package yields an error about an unrecognized rule.