QoSHandler: Allow customization of rejection status code (429 vs 503) and improve extensibility

[jan-osc]

Jetty version(s)
12.1.X

Enhancement Description
Two changes to make the class QoSHandler more flexible:

1. Allow configuration of the status code - Add a field and setter to configure the status code returned when limits are exceeded. It could also be the constructor parameter.

// Default to 503 for backward compatibility
private int _throttledStatus = HttpStatus.SERVICE_UNAVAILABLE_503;

public void setThrottledStatus(int status) {
    _throttledStatus = status;
}

2. Relax the visibility of internal rejection methods
   Change the visibility of some methods from private to protected. This would allow developers to extend the class and implement custom rejection logic (e.g., by adding specific headers such as Retry-After or custom JSON error bodies).

Specifically, these methods:

• private boolean tooManyRequests(Response response, Callback callback)
• private boolean notAvailable(Response response, Callback callback)

Currently, the only way to achieve this without copying the entire class is a complex workaround involving:

1. A "Marker" handler inside the QoS handler to flag successful passage.
2. A "Wrapper" handler outside the QoS handler that intercepts 503 responses, checks for the absence of the marker, and swaps the code to 429

This adds unnecessary object allocation and runtime overhead for a simple status code change.

[lorban]

I'm not sold on the idea of making those private methods of QoSHandler protected, but I'm not rejecting your idea of being able to respond with status code 429 and adding the Retry-After header.

I'm wondering if that functionality should be baked in QoSHandler, so how would you do that, and how would you choose when to set Retry-After and what to set it to?

[jan-osc]

This behavior should be left to the user configuring the QoSHandler. Since Jetty serves as a fundamental building block for applications, it should remain flexible and avoid being overly opinionated about HTTP semantics (e.g., enforcing 503 over 429).
The ability to specify custom headers (like Retry-After) is a great idea.

This flexibility could be achieved in two ways:

1. Configuration: Exposing setters like setThrottledStatus(int) and potentially a map for setThrottledHeaders(...).
2. Extension: Relaxing visibility by overriding methods like notAvailable or failSuspended.

Given Jetty's role as a flexible toolkit, enabling this customization seems like the right move.