traffic-resilience-http: Add documentation for capacity limiters #3082
Conversation
Motivation: It could use some documentation. Modifications: Add it.
docs/generation/site-remote.yml
Outdated
| @@ -68,6 +68,10 @@ content: | |||
| branches: main | |||
| tags: [0.25.0, 0.26.0, 0.27.0, 0.28.0, 0.29.0, 0.30.0, 0.31.0, 0.32.0, 0.33.0, 0.34.0, 0.35.0, 0.36.0, 0.37.0, 0.38.0, 0.39.0, 0.40.0, 0.41.14, 0.42.50] | |||
| start_path: servicetalk-client-api/docs | |||
| - url: ../../ | |||
| branches: main | |||
| tags: [] | |||
There was a problem hiding this comment.
does it need tags to show up in the built docs?
There was a problem hiding this comment.
I think this is right, but I don't actually know for sure so another opinion is welcome.
...esilience/src/main/java/io/servicetalk/examples/http/traffic/resilience/GradientExample.java
Outdated
Show resolved
Hide resolved
...e/src/main/java/io/servicetalk/examples/http/traffic/resilience/LifecycleObserverServer.java
Show resolved
Hide resolved
.../io/servicetalk/examples/http/traffic/resilience/TrafficResilienceClientBreakersExample.java
Outdated
Show resolved
Hide resolved
servicetalk-traffic-resilience-http/docs/modules/ROOT/pages/index.adoc
Outdated
Show resolved
Hide resolved
servicetalk-traffic-resilience-http/docs/modules/ROOT/pages/index.adoc
Outdated
Show resolved
Hide resolved
servicetalk-traffic-resilience-http/docs/modules/ROOT/pages/index.adoc
Outdated
Show resolved
Hide resolved
servicetalk-traffic-resilience-http/docs/modules/ROOT/pages/index.adoc
Outdated
Show resolved
Hide resolved
And he did a much better job than I. 😄 |
Follow-up for apple#3082 to address some comments.
| [#TrafficResiliency] | ||
| = Traffic Resiliency | ||
|
|
||
| Some examples that use the traffic resiliency features. |
There was a problem hiding this comment.
We typically clarify what those examples demonstrate and link to them. In this case, there are no clarifications on docs page nor javadoc in each example class.
|
|
||
| HttpServers.forPort(0) | ||
| .appendNonOffloadingServiceFilter(resilienceFilter) | ||
| .listenAndAwait((ctx, request, responseFactory) -> Single.succeeded(responseFactory.ok())); |
There was a problem hiding this comment.
We should use awaitShutdown() at the end, like in all other examples. Otherwise, it exists main block and users don't see the actual server running.
We assume that any example can be used as an example for starting a server, so it's good to show how they can present JVM app from exiting.
| .classifier(() -> (meta) -> "/health".equals(meta.requestTarget()) ? () -> 20 : () -> 100) | ||
| .build(); | ||
|
|
||
| HttpServers.forPort(0) |
There was a problem hiding this comment.
Using a standard port 8080 helps to make sure that when users start a server-side of an example, they can also run a client-side of an example to see it in action.
|
|
||
| HttpClients.forSingleAddress("localhost", 8080) | ||
| .appendClientFilter(resilienceFilter) | ||
| .build(); |
There was a problem hiding this comment.
Assuming all examples can be used as learning material, it's better to always show that client should be closed after they are not required anymore. Using try-with-resources block consistently across all examples helps to preserve that.
| try (HttpClient client = HttpClients.forSingleAddress("localhost", 8080) | ||
| .appendClientFilter(resilienceFilter) | ||
| .build()) { | ||
| // use client |
There was a problem hiding this comment.
Examples are great when they can be run, even if they demonstrate something that is not visible via request logs.
| // Initializing a Gradient limiter with configuration profile that favors lower latency. | ||
| // See the `.dynamicGradientOptimizeForThroughput()` variant to optimize for higher throughput. | ||
| @SuppressWarnings("unused") | ||
| final CapacityLimiter limiter = CapacityLimiters.dynamicGradientOptimizeForLatency() |
There was a problem hiding this comment.
How useful is this example if we already demonstrate how to build a limiter in other classes?
Follow-up for #3082 to address some comments.
Motivation:
It could use some documentation.
Modifications:
Add it.