1 package com.guinetik.rr.http;
2
3 /**
4 * Centralized constants for HTTP operations used throughout RocketRest.
5 *
6 * <p>This utility class contains all HTTP-related constants including methods, status codes,
7 * timeouts, headers, and circuit breaker configuration. Using these constants ensures
8 * consistency and maintainability across the codebase.
9 *
10 * <h2>HTTP Methods</h2>
11 * <pre class="language-java"><code>
12 * // Use HTTP method constants
13 * String method = HttpConstants.Methods.GET;
14 * String postMethod = HttpConstants.Methods.POST;
15 *
16 * // In request building
17 * RequestSpec request = new RequestBuilder()
18 * .method(HttpConstants.Methods.POST)
19 * .endpoint("/users")
20 * .build();
21 * </code></pre>
22 *
23 * <h2>Status Code Handling</h2>
24 * <pre class="language-java"><code>
25 * // Check response status
26 * if (statusCode == HttpConstants.StatusCodes.OK) {
27 * // Handle success
28 * } else if (statusCode == HttpConstants.StatusCodes.UNAUTHORIZED) {
29 * // Handle auth failure
30 * }
31 *
32 * // Check ranges
33 * if (statusCode >= HttpConstants.StatusCodes.SUCCESS_MIN &&
34 * statusCode <= HttpConstants.StatusCodes.SUCCESS_MAX) {
35 * // 2xx response
36 * }
37 * </code></pre>
38 *
39 * <h2>Circuit Breaker Configuration</h2>
40 * <pre class="language-java"><code>
41 * RocketRestOptions options = new RocketRestOptions();
42 * options.set(HttpConstants.CircuitBreaker.CIRCUIT_BREAKER_ENABLED, true);
43 * options.set(HttpConstants.CircuitBreaker.CIRCUIT_BREAKER_FAILURE_THRESHOLD, 5);
44 * options.set(HttpConstants.CircuitBreaker.CIRCUIT_BREAKER_RESET_TIMEOUT_MS, 30000);
45 * </code></pre>
46 *
47 * @author guinetik <guinetik@gmail.com>
48 * @since 1.0.0
49 */
50 public final class HttpConstants {
51
52 /**
53 * HTTP methods
54 */
55 public static final class Methods {
56 /** HTTP GET method */
57 public static final String GET = "GET";
58 /** HTTP POST method */
59 public static final String POST = "POST";
60 /** HTTP PUT method */
61 public static final String PUT = "PUT";
62 /** HTTP PATCH method */
63 public static final String PATCH = "PATCH";
64 /** HTTP DELETE method */
65 public static final String DELETE = "DELETE";
66 /** HTTP HEAD method */
67 public static final String HEAD = "HEAD";
68 /** HTTP OPTIONS method */
69 public static final String OPTIONS = "OPTIONS";
70 }
71
72 /**
73 * HTTP status codes
74 */
75 public static final class StatusCodes {
76 // 2xx Success
77 /** Status code (200): Request has succeeded */
78 public static final int OK = 200;
79 /** Status code (201): Request has succeeded and new resource has been created */
80 public static final int CREATED = 201;
81 /** Status code (202): Request has been accepted for processing */
82 public static final int ACCEPTED = 202;
83 /** Status code (204): Server fulfilled request but does not need to return content */
84 public static final int NO_CONTENT = 204;
85
86 // 3xx Redirection
87 /** Status code (301): Requested resource has been permanently moved */
88 public static final int MOVED_PERMANENTLY = 301;
89 /** Status code (302): Requested resource has been temporarily moved */
90 public static final int FOUND = 302;
91 /** Status code (303): Response to request can be found under different URI */
92 public static final int SEE_OTHER = 303;
93 /** Status code (304): Resource has not been modified since last request */
94 public static final int NOT_MODIFIED = 304;
95
96 // 4xx Client Errors
97 /** Status code (400): Server cannot process request due to client error */
98 public static final int BAD_REQUEST = 400;
99 /** Status code (401): Authentication is required and has failed or not been provided */
100 public static final int UNAUTHORIZED = 401;
101 /** Status code (403): Server understood request but refuses to authorize it */
102 public static final int FORBIDDEN = 403;
103 /** Status code (404): Server cannot find requested resource */
104 public static final int NOT_FOUND = 404;
105 /** Status code (405): Request method is not supported for the requested resource */
106 public static final int METHOD_NOT_ALLOWED = 405;
107 /** Status code (409): Request conflicts with current state of the server */
108 public static final int CONFLICT = 409;
109 /** Status code (410): Requested resource is no longer available */
110 public static final int GONE = 410;
111
112 // 5xx Server Errors
113 /** Status code (500): Server encountered an unexpected condition */
114 public static final int INTERNAL_SERVER_ERROR = 500;
115 /** Status code (501): Server does not support the functionality required */
116 public static final int NOT_IMPLEMENTED = 501;
117 /** Status code (502): Server received an invalid response from an upstream server */
118 public static final int BAD_GATEWAY = 502;
119 /** Status code (503): Server is currently unavailable */
120 public static final int SERVICE_UNAVAILABLE = 503;
121
122 // Status code ranges
123 /** Minimum status code for success responses (200-299) */
124 public static final int SUCCESS_MIN = 200;
125 /** Maximum status code for success responses (200-299) */
126 public static final int SUCCESS_MAX = 299;
127 /** Minimum status code for redirection responses (300-399) */
128 public static final int REDIRECT_MIN = 300;
129 /** Maximum status code for redirection responses (300-399) */
130 public static final int REDIRECT_MAX = 399;
131 /** Minimum status code for client error responses (400-499) */
132 public static final int CLIENT_ERROR_MIN = 400;
133 /** Maximum status code for client error responses (400-499) */
134 public static final int CLIENT_ERROR_MAX = 499;
135 /** Minimum status code for server error responses (500-599) */
136 public static final int SERVER_ERROR_MIN = 500;
137 /** Maximum status code for server error responses (500-599) */
138 public static final int SERVER_ERROR_MAX = 599;
139 }
140
141 /**
142 * Connection timeouts in milliseconds
143 */
144 public static final class Timeouts {
145 /** Default connection timeout in milliseconds (10 seconds) */
146 public static final int DEFAULT_CONNECT_TIMEOUT = 10000; // 10 seconds
147 /** Default read timeout in milliseconds (30 seconds) */
148 public static final int DEFAULT_READ_TIMEOUT = 30000; // 30 seconds
149 /** Quick timeout in milliseconds for time-sensitive operations (5 seconds) */
150 public static final int QUICK_TIMEOUT = 5000; // 5 seconds
151 /** Extended timeout in milliseconds for operations that might take longer (60 seconds) */
152 public static final int EXTENDED_TIMEOUT = 60000; // 60 seconds
153 }
154
155 /**
156 * URL and encoding constants
157 */
158 public static final class Url {
159 /** Path separator character for URLs */
160 public static final String PATH_SEPARATOR = "/";
161 /** Query string prefix for URLs */
162 public static final String QUERY_PREFIX = "?";
163 /** Query parameter separator for URLs */
164 public static final String QUERY_SEPARATOR = "&";
165 /** Parameter name-value separator for URLs */
166 public static final String PARAM_EQUALS = "=";
167 /** Fragment identifier prefix for URLs */
168 public static final String FRAGMENT_PREFIX = "#";
169 }
170
171 /**
172 * Encoding constants
173 */
174 public static final class Encoding {
175 /** UTF-8 character encoding */
176 public static final String UTF8 = "UTF-8";
177 /** ISO-8859-1 character encoding */
178 public static final String ISO_8859_1 = "ISO-8859-1";
179 }
180
181 /**
182 * Common error messages
183 */
184 public static final class Errors {
185 /** Error message for expired or invalid token */
186 public static final String TOKEN_EXPIRED = "Token expired or invalid";
187 /** Prefix for HTTP request failure message */
188 public static final String REQUEST_FAILED = "HTTP request failed with status ";
189 /** Error message for request execution failure */
190 public static final String EXECUTE_REQUEST = "Failed to execute request";
191 /** Error message template for parameter encoding failure */
192 public static final String ENCODE_PARAM = "Failed to encode parameter: {}";
193 /** Error message for SSL configuration issues */
194 public static final String SSL_ERROR = "SSL configuration error";
195 /** Error message for request timeout */
196 public static final String TIMEOUT = "Request timed out";
197 }
198
199 /**
200 * CircuitBreaker-related constants
201 */
202 public static final class CircuitBreaker {
203 // Default values
204 /** Default number of failures before opening the circuit */
205 public static final int DEFAULT_FAILURE_THRESHOLD = 5;
206 /** Default timeout in milliseconds before attempting to half-open the circuit (30 seconds) */
207 public static final long DEFAULT_RESET_TIMEOUT_MS = 30000; // 30 seconds
208 /** Default time in milliseconds before failure count begins to decay (1 minute) */
209 public static final long DEFAULT_FAILURE_DECAY_TIME_MS = 60000; // 1 minute
210
211 // Error messages
212 /** Error message when the circuit is open */
213 public static final String CIRCUIT_OPEN = "Circuit breaker is open";
214
215 // Log messages
216 /** Log message when circuit moves to half-open state */
217 public static final String LOG_CIRCUIT_HALF_OPEN = "Circuit moving to HALF_OPEN state";
218 /** Log message when circuit is closed */
219 public static final String LOG_CIRCUIT_CLOSED = "Circuit closed - service appears healthy";
220 /** Log message when test request fails */
221 public static final String LOG_TEST_FAILED = "Test request failed, circuit remaining open";
222 /** Log message template when circuit is opened */
223 public static final String LOG_CIRCUIT_OPENED = "Circuit breaker opened after {} failures";
224 /** Log message when failure count is reset due to decay timeout */
225 public static final String LOG_DECAY_RESET = "Reset failure count due to decay timeout";
226 /** Log message when a request is rejected during HALF_OPEN because another test is in progress */
227 public static final String LOG_HALF_OPEN_TEST_IN_PROGRESS = "Rejecting request - another test request is in progress";
228
229 // Health status
230 /** Circuit breaker status: open (not allowing requests) */
231 public static final String STATUS_OPEN = "OPEN";
232 /** Circuit breaker status: closed (allowing requests) */
233 public static final String STATUS_CLOSED = "CLOSED";
234 /** Circuit breaker status: half-open (allowing test requests) */
235 public static final String STATUS_HALF_OPEN = "HALF_OPEN";
236
237 // Options
238 /** Configuration option key for enabling/disabling circuit breaker */
239 public static final String CIRCUIT_BREAKER_ENABLED = "circuit_breaker.enabled";
240 /** Configuration option key for setting failure threshold */
241 public static final String CIRCUIT_BREAKER_FAILURE_THRESHOLD = "circuit_breaker.failure_threshold";
242 /** Configuration option key for setting reset timeout */
243 public static final String CIRCUIT_BREAKER_RESET_TIMEOUT_MS = "circuit_breaker.reset_timeout_ms";
244 /** Configuration option key for setting failure policy */
245 public static final String CIRCUIT_BREAKER_FAILURE_POLICY = "circuit_breaker.failure_policy";
246 /** Configuration option value for server-errors-only failure policy */
247 public static final String CIRCUIT_BREAKER_POLICY_SERVER_ONLY = "SERVER_ERRORS_ONLY";
248 }
249
250 // Prevent instantiation
251 private HttpConstants() {
252 throw new AssertionError("Utility class - do not instantiate");
253 }
254 }