1 package com.guinetik.rr.interceptor;
2
3 import com.guinetik.rr.http.RocketRestException;
4 import com.guinetik.rr.request.RequestSpec;
5
6 /**
7 * Represents the interceptor chain during request execution.
8 *
9 * <p>This interface is passed to {@link RequestInterceptor#onError} to allow
10 * interceptors to retry failed requests or query chain state.
11 *
12 * <h2>Retry Example</h2>
13 * <pre class="language-java"><code>
14 * public <Req, Res> Res onError(RocketRestException e, RequestSpec<Req, Res> request,
15 * InterceptorChain chain) throws RocketRestException {
16 * if (isRetryable(e) && chain.getRetryCount() < 3) {
17 * return chain.retry(request);
18 * }
19 * throw e;
20 * }
21 * </code></pre>
22 *
23 * @author guinetik <guinetik@gmail.com>
24 * @see RequestInterceptor
25 * @since 1.1.0
26 */
27 public interface InterceptorChain {
28
29 /**
30 * Retries the request from the beginning of the chain.
31 *
32 * <p>This increments the retry count and re-executes the full interceptor
33 * chain, including all beforeRequest/afterResponse hooks.
34 *
35 * @param request The request to retry (can be modified from original)
36 * @param <Req> The request body type
37 * @param <Res> The response type
38 * @return The response from the retried request
39 * @throws RocketRestException If the retry also fails
40 */
41 <Req, Res> Res retry(RequestSpec<Req, Res> request) throws RocketRestException;
42
43 /**
44 * Gets the current retry count for this execution.
45 *
46 * <p>Starts at 0 for the initial request, increments with each retry.
47 * Use this to implement retry limits.
48 *
49 * @return The number of retries attempted so far
50 */
51 int getRetryCount();
52
53 /**
54 * Gets the maximum retry count configured for this chain.
55 *
56 * <p>Returns 0 if no retry limit is configured.
57 *
58 * @return The maximum retry count, or 0 if unlimited
59 */
60 int getMaxRetries();
61 }