qubit_http/client/http_client.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! HTTP client: builds requests, applies defaults and interceptors, executes
11//! them with optional retry, and exposes SSE helpers with reconnect.
12//!
13//! Single-shot execution is [`HttpClient::execute`] / [`HttpClient::execute_once`];
14//! retry policy comes from [`crate::HttpClientOptions::retry`] unless overridden
15//! per request.
16//!
17
18use std::time::{
19 Duration,
20 Instant,
21};
22
23use qubit_retry::{
24 AttemptFailure,
25 AttemptFailureDecision,
26 Retry,
27 RetryContext,
28 RetryError,
29 RetryErrorReason,
30};
31
32use crate::sse::SseReconnectRunner;
33use crate::{
34 response::HttpResponseOptions,
35 sse::{
36 SseEventStream,
37 SseReconnectOptions,
38 },
39 AsyncHttpHeaderInjector,
40 HttpClientOptions,
41 HttpError,
42 HttpHeaderInjector,
43 HttpLogger,
44 HttpRequest,
45 HttpRequestBuilder,
46 HttpRequestInterceptor,
47 HttpRequestInterceptors,
48 HttpResponse,
49 HttpResponseInterceptor,
50 HttpResponseInterceptors,
51 HttpResponseMeta,
52 HttpResult,
53 HttpRetryOptions,
54};
55
56/// High-level HTTP client: default headers, injectors, interceptors, logging,
57/// timeouts, and optional per-request retry.
58///
59/// [`Clone`] is shallow and cheap enough for typical use (including passing into
60/// retry closures); cloning does not duplicate the underlying connection pool
61/// beyond what [`reqwest::Client`] already shares.
62#[derive(Clone)]
63pub struct HttpClient {
64 /// Pluggable low-level HTTP stack used to send requests (currently reqwest).
65 pub(super) backend: reqwest::Client,
66 /// Timeouts, proxy, logging, default headers, and related settings.
67 pub(super) options: HttpClientOptions,
68 /// Header injectors applied to every outgoing request after default
69 /// headers.
70 pub(super) injectors: Vec<HttpHeaderInjector>,
71 /// Async header injectors applied after sync injectors and before request-level headers.
72 pub(super) async_injectors: Vec<AsyncHttpHeaderInjector>,
73 /// Request interceptors applied before request send for each attempt.
74 request_interceptors: HttpRequestInterceptors,
75 /// Response interceptors applied on successful responses before return.
76 response_interceptors: HttpResponseInterceptors,
77}
78
79impl HttpClient {
80 /// Wraps a built [`reqwest::Client`] with the given options and an empty
81 /// injector list.
82 ///
83 /// # Parameters
84 /// - `backend`: Configured low-level HTTP client used for I/O.
85 /// - `options`: Client-wide timeouts, headers, proxy, logging, etc.
86 ///
87 /// # Returns
88 /// A new [`HttpClient`] with no injectors until
89 /// [`HttpClient::add_header_injector`] is called.
90 pub(crate) fn new(backend: reqwest::Client, options: HttpClientOptions) -> Self {
91 Self {
92 backend,
93 options,
94 injectors: Vec::new(),
95 async_injectors: Vec::new(),
96 request_interceptors: HttpRequestInterceptors::new(),
97 response_interceptors: HttpResponseInterceptors::new(),
98 }
99 }
100
101 /// Returns a reference to the client-wide options (timeouts, proxy, logging,
102 /// default headers, retry defaults, etc.).
103 ///
104 /// # Returns
105 /// Immutable borrow of [`HttpClientOptions`]. Never `None`; always the
106 /// options installed on this client.
107 pub fn options(&self) -> &HttpClientOptions {
108 &self.options
109 }
110
111 /// Appends a [`HttpHeaderInjector`] so its mutation function runs on every
112 /// request. Mutates `self` in place.
113 ///
114 /// # Parameters
115 /// - `injector`: Injector to append (order is preserved).
116 pub fn add_header_injector(&mut self, injector: HttpHeaderInjector) {
117 self.injectors.push(injector);
118 }
119
120 /// Appends an async header injector whose mutation runs after sync injectors.
121 /// Mutates `self` in place.
122 ///
123 /// # Parameters
124 /// - `injector`: Async injector to append (order is preserved).
125 pub fn add_async_header_injector(&mut self, injector: AsyncHttpHeaderInjector) {
126 self.async_injectors.push(injector);
127 }
128
129 /// Appends a request interceptor run before each send attempt (including
130 /// each retry attempt). Mutates `self` in place.
131 ///
132 /// # Parameters
133 /// - `interceptor`: Request interceptor to append (order is preserved).
134 pub fn add_request_interceptor(&mut self, interceptor: HttpRequestInterceptor) {
135 self.request_interceptors.push(interceptor);
136 }
137
138 /// Appends a response interceptor run only after a successful HTTP status
139 /// (after the internal `execute_once` step) and before response body logging.
140 /// Mutates `self` in place.
141 ///
142 /// # Parameters
143 /// - `interceptor`: Response interceptor to append (order is preserved).
144 pub fn add_response_interceptor(&mut self, interceptor: HttpResponseInterceptor) {
145 self.response_interceptors.push(interceptor);
146 }
147
148 /// Validates and adds one client-level default header.
149 ///
150 /// The header is applied to every request before header injectors and
151 /// request-level headers.
152 ///
153 /// # Parameters
154 /// - `name`: Header name.
155 /// - `value`: Header value.
156 ///
157 /// # Returns
158 /// `Ok(self)` after the header is stored.
159 ///
160 /// # Errors
161 /// Returns [`HttpError`] when the header name or value is invalid.
162 pub fn add_header(&mut self, name: &str, value: &str) -> HttpResult<&mut Self> {
163 self.options.add_header(name, value)?;
164 Ok(self)
165 }
166
167 /// Validates and adds many client-level default headers atomically.
168 ///
169 /// If any input pair is invalid, no header from this batch is applied.
170 ///
171 /// # Parameters
172 /// - `headers`: Iterator of `(name, value)` pairs.
173 ///
174 /// # Returns
175 /// `Ok(self)` after all headers are stored.
176 ///
177 /// # Errors
178 /// Returns [`HttpError`] when any name/value pair is invalid (nothing from
179 /// this call is applied).
180 pub fn add_headers(&mut self, headers: &[(&str, &str)]) -> HttpResult<&mut Self> {
181 self.options.add_headers(headers)?;
182 Ok(self)
183 }
184
185 /// Clears all synchronous header injectors. Mutates `self` in place.
186 pub fn clear_header_injectors(&mut self) {
187 self.injectors.clear();
188 }
189
190 /// Clears all async header injectors. Mutates `self` in place.
191 pub fn clear_async_header_injectors(&mut self) {
192 self.async_injectors.clear();
193 }
194
195 /// Clears all request interceptors. Mutates `self` in place.
196 pub fn clear_request_interceptors(&mut self) {
197 self.request_interceptors.clear();
198 }
199
200 /// Clears all response interceptors. Mutates `self` in place.
201 pub fn clear_response_interceptors(&mut self) {
202 self.response_interceptors.clear();
203 }
204
205 /// Starts building an [`HttpRequest`] with the given method and path
206 /// (relative or absolute URL string).
207 ///
208 /// # Parameters
209 /// - `method`: HTTP verb (GET, POST, …).
210 /// - `path`: Path relative to [`HttpClientOptions::base_url`] or a full URL
211 /// string.
212 ///
213 /// # Returns
214 /// A new [`HttpRequestBuilder`] borrowing this client for defaults; it is
215 /// not sent until built and passed to [`HttpClient::execute`] (or related
216 /// APIs).
217 pub fn request(&self, method: http::Method, path: &str) -> HttpRequestBuilder {
218 HttpRequestBuilder::new(method, path, self)
219 }
220
221 /// Returns a clone of the client-level default header map.
222 ///
223 /// Used when constructing a built [`HttpRequest`] so the snapshot reflects
224 /// headers at build time.
225 ///
226 /// # Returns
227 /// Owned [`http::HeaderMap`] copy of [`HttpClientOptions`] default headers.
228 pub(crate) fn headers_snapshot(&self) -> http::HeaderMap {
229 self.options.default_headers.clone()
230 }
231
232 /// Returns a clone of the registered synchronous header injectors list.
233 ///
234 /// # Returns
235 /// New [`Vec`] with the same injectors and order as on this client.
236 pub(crate) fn injectors_snapshot(&self) -> Vec<HttpHeaderInjector> {
237 self.injectors.clone()
238 }
239
240 /// Returns a clone of the registered async header injectors list.
241 ///
242 /// # Returns
243 /// New [`Vec`] with the same injectors and order as on this client.
244 pub(crate) fn async_injectors_snapshot(&self) -> Vec<AsyncHttpHeaderInjector> {
245 self.async_injectors.clone()
246 }
247
248 /// Sends the request and returns a unified [`HttpResponse`].
249 ///
250 /// Chooses retry vs single attempt from resolved [`HttpRetryOptions`] for
251 /// this request. Performs network I/O and may await the internal
252 /// `execute_once` path
253 /// multiple times with backoff between attempts when retry is enabled.
254 ///
255 /// # Parameters
256 /// - `request`: Built request (URL resolved against `base_url` if path is
257 /// not absolute).
258 ///
259 /// # Returns
260 /// - `Ok(HttpResponse)` when the HTTP status is success
261 /// ([`http::StatusCode::is_success`]).
262 /// - `Err(HttpError)` when any attempt fails for URL/header validation,
263 /// cancellation, interceptor failure, transport/timeout, non-success
264 /// status, or when the retry executor aborts or exceeds limits.
265 pub async fn execute(&self, request: HttpRequest) -> HttpResult<HttpResponse> {
266 let retry_options = self.options.retry.resolve(&request);
267 if retry_options.should_retry(&request) {
268 self.execute_with_retry(request, retry_options).await
269 } else {
270 self.execute_once(request).await
271 }
272 }
273
274 /// Performs one non-retrying execution: pre-send cancellation check,
275 /// request interceptors, resolve URL, merge headers, log the request, send
276 /// with configured timeouts, map non-success status to an error, then
277 /// response interceptors and response logging. The returned body is read
278 /// lazily according to [`HttpResponse`].
279 ///
280 /// # Parameters
281 /// - `request`: Built request to send (same fields as for
282 /// [`HttpClient::execute`]).
283 ///
284 /// # Returns
285 /// - `Ok(HttpResponse)` on success status and after interceptors/logging
286 /// steps succeed.
287 /// - `Err(HttpError)` from request/response interceptors, cancellation,
288 /// send/transport errors, status mapping, URL resolution for the response
289 /// wrapper, or response logging failures.
290 ///
291 /// # Side effects
292 /// Network I/O, optional logging, and user-provided interceptor callbacks.
293 pub(crate) async fn execute_once(&self, request: HttpRequest) -> HttpResult<HttpResponse> {
294 let mut request = request;
295 if let Some(error) = request.cancelled_error_if_needed("Request cancelled before sending") {
296 return Err(error);
297 }
298 self.request_interceptors.apply(&mut request)?;
299 let response = self
300 .prepare_and_send_once(request, "Request cancelled before sending")
301 .await?;
302 let mut response = response
303 .into_success_or_status_error("HTTP request failed")
304 .await?;
305 self.response_interceptors.apply(&mut response.meta)?;
306 let logger = HttpLogger::new(&self.options);
307 logger.log_response(&mut response).await?;
308 Ok(response)
309 }
310
311 /// Single low-level send: cancellation check, request logging, one backend
312 /// round-trip, then wraps the backend response as [`HttpResponse`].
313 ///
314 /// Does not run response interceptors or success-status enforcement; those
315 /// happen in [`HttpClient::execute_once`] after this returns.
316 ///
317 /// # Parameters
318 /// - `request`: Request to send (may be mutated for logging/send path).
319 /// - `cancellation_message`: Message embedded if the request is already
320 /// cancelled when this runs.
321 ///
322 /// # Returns
323 /// - `Ok(HttpResponse)` with lazy body and metadata.
324 /// - `Err(HttpError)` if cancelled before send, URL resolution fails, or
325 /// send fails.
326 ///
327 /// # Side effects
328 /// Async network I/O and request logging via [`HttpLogger`].
329 async fn prepare_and_send_once(
330 &self,
331 request: HttpRequest,
332 cancellation_message: &str,
333 ) -> HttpResult<HttpResponse> {
334 let mut request = request;
335 if let Some(error) = request.cancelled_error_if_needed(cancellation_message) {
336 return Err(error);
337 }
338 let logger = HttpLogger::new(&self.options);
339 let request_url = request.resolved_url_with_query()?;
340 let backend_response = request.send_impl(&self.backend, &logger).await?;
341 let meta = HttpResponseMeta::new(
342 backend_response.status(),
343 backend_response.headers().clone(),
344 backend_response.url().clone(),
345 request.method().clone(),
346 );
347 let response_options = HttpResponseOptions::new(
348 self.options.error_response_preview_limit,
349 self.options.sse_json_mode,
350 self.options.sse_max_line_bytes,
351 self.options.sse_max_frame_bytes,
352 self.options.sse_done_marker_policy.clone(),
353 );
354 Ok(HttpResponse::from_backend(
355 meta,
356 backend_response,
357 request.read_timeout(),
358 request.cancellation_token().cloned(),
359 request_url,
360 response_options,
361 ))
362 }
363
364 /// Runs [`HttpClient::execute_once`] under the given retry policy.
365 ///
366 /// Between attempts waits according to the resolved retry delay, optionally
367 /// honoring `Retry-After` by extending the next sleep. Each attempt clones
368 /// the request so request bodies can be rebuilt when supported.
369 ///
370 /// # Parameters
371 /// - `request`: Built request passed to each [`HttpClient::execute_once`]
372 /// attempt (cloned per retry closure).
373 /// - `options`: Effective retry options for this request (from resolution
374 /// in [`HttpClient::execute`]).
375 ///
376 /// # Returns
377 /// - `Ok(HttpResponse)` when an attempt completes with success status.
378 /// - `Err(HttpError)` from any [`HttpClient::execute_once`] failure that is
379 /// non-retryable, or from retry exhaustion/max-duration enforcement.
380 ///
381 /// # Side effects
382 /// Multiple async HTTP attempts and optional sleeps.
383 async fn execute_with_retry(
384 &self,
385 request: HttpRequest,
386 options: HttpRetryOptions,
387 ) -> HttpResult<HttpResponse> {
388 let honor_retry_after = request.retry_override().should_honor_retry_after();
389 let retry_options = options.to_executor_options();
390 let started_at = Instant::now();
391
392 let retry_policy_options = options.clone();
393 let retry_delay_options = retry_options.clone();
394 let retry_policy = Retry::<HttpError>::builder()
395 .options(retry_options)
396 .retry_after_from_error(move |error| {
397 honor_retry_after.then_some(error.retry_after).flatten()
398 })
399 .on_failure(
400 move |failure: &AttemptFailure<HttpError>, context: &RetryContext| {
401 Self::retry_failure_decision(
402 failure,
403 context,
404 &retry_policy_options,
405 &retry_delay_options,
406 )
407 },
408 )
409 .build()
410 .expect("validated HTTP retry options should build retry policy");
411
412 let cancellation_token = request.cancellation_token().cloned();
413 let request_method = request.method().clone();
414 let request_url = request.resolved_url_with_query().ok();
415 let retry_request = request.clone();
416 let retry_future = retry_policy.run_async(|| {
417 let attempt_request = retry_request.clone();
418 async move { self.execute_once(attempt_request).await }
419 });
420
421 let retry_result = if let Some(token) = cancellation_token.as_ref() {
422 tokio::select! {
423 _ = token.cancelled() => {
424 return Err(Self::retry_cancelled_error(
425 "HTTP retry cancelled while waiting before next attempt",
426 &request_method,
427 request_url.as_ref(),
428 ));
429 }
430 result = retry_future => result,
431 }
432 } else {
433 retry_future.await
434 };
435
436 match retry_result {
437 Ok(response) => Ok(response),
438 Err(error) => Err(Self::map_retry_error(
439 error,
440 started_at,
441 options.max_duration,
442 options.max_attempts,
443 )),
444 }
445 }
446
447 /// Returns whether `error` is retryable under `options`.
448 ///
449 /// # Parameters
450 /// - `error`: Error produced by a single HTTP attempt.
451 /// - `options`: Effective retry options for the request.
452 ///
453 /// # Returns
454 /// `true` if another attempt may be scheduled.
455 fn is_retryable_error(error: &HttpError, options: &HttpRetryOptions) -> bool {
456 if error.kind == crate::HttpErrorKind::Status {
457 error
458 .status
459 .is_some_and(|status| options.is_retryable_status(status))
460 } else {
461 options.is_retryable_error_kind(error.kind)
462 }
463 }
464
465 /// Computes the sleep before the next retry attempt.
466 ///
467 /// # Parameters
468 /// - `base_delay`: Delay selected from retry policy and jitter.
469 /// - `retry_after_hint`: Retry-After delay extracted by the retry policy.
470 ///
471 /// # Returns
472 /// `base_delay`, or the larger `Retry-After` value when present.
473 fn retry_sleep_delay(base_delay: Duration, retry_after_hint: Option<Duration>) -> Duration {
474 retry_after_hint
475 .map(|retry_after| retry_after.max(base_delay))
476 .unwrap_or(base_delay)
477 }
478
479 /// Decides how HTTP retry should handle one failed attempt.
480 ///
481 /// # Parameters
482 /// - `failure`: Failed attempt reported by `qubit-retry`.
483 /// - `context`: Retry context for the failed attempt.
484 /// - `policy_options`: HTTP retry allowlists and method policy.
485 /// - `delay_options`: Retry executor options used to calculate base delay.
486 ///
487 /// # Returns
488 /// Decision for `qubit-retry`: abort non-retryable HTTP errors, otherwise
489 /// retry after the larger base delay / Retry-After hint. Non-HTTP runtime
490 /// failures fall back to the retry executor default.
491 fn retry_failure_decision(
492 failure: &AttemptFailure<HttpError>,
493 context: &RetryContext,
494 policy_options: &HttpRetryOptions,
495 delay_options: &qubit_retry::RetryOptions,
496 ) -> AttemptFailureDecision {
497 let error = failure
498 .as_error()
499 .expect("HTTP retry attempts do not configure non-HTTP attempt failures");
500 if !Self::is_retryable_error(error, policy_options) {
501 return AttemptFailureDecision::Abort;
502 }
503
504 let base_delay = delay_options.delay_for_attempt(context.attempt());
505 let sleep_delay = Self::retry_sleep_delay(base_delay, context.retry_after_hint());
506 AttemptFailureDecision::RetryAfter(sleep_delay)
507 }
508
509 /// Adds retry-attempt exhaustion context to the last attempt error.
510 ///
511 /// # Parameters
512 /// - `error`: Last retryable attempt error.
513 /// - `attempts`: Number of attempts already made.
514 /// - `max_attempts`: Configured maximum attempts.
515 ///
516 /// # Returns
517 /// The same error with retry exhaustion details appended to its message.
518 fn map_retry_attempts_exhausted(
519 mut error: HttpError,
520 attempts: u32,
521 max_attempts: u32,
522 ) -> HttpError {
523 error.message = format!(
524 "{} (retry attempts exhausted: {attempts}/{max_attempts})",
525 error.message
526 );
527 error
528 }
529
530 /// Builds the error returned when retry policy stops early.
531 ///
532 /// # Parameters
533 /// - `error`: Attempt error that the retry policy chose not to retry.
534 /// - `attempts`: Number of attempts already made.
535 /// - `started_at`: Start instant of the retry flow.
536 ///
537 /// # Returns
538 /// [`HttpError::retry_aborted`] with the original [`HttpError`] chained as
539 /// source for callers that need the underlying status or transport error.
540 fn map_retry_aborted(error: HttpError, attempts: u32, started_at: Instant) -> HttpError {
541 let elapsed = started_at.elapsed();
542 let summary = error.message.clone();
543 HttpError::retry_aborted(format!(
544 "HTTP retry aborted after {attempts} attempt(s) in {elapsed:?}: {summary}"
545 ))
546 .with_source(error)
547 }
548
549 /// Builds the error when retry max-duration is exhausted.
550 ///
551 /// # Parameters
552 /// - `started_at`: Start instant of the retry flow.
553 /// - `max_duration`: Configured max-duration budget.
554 /// - `last_error`: Last captured retryable attempt error, if any.
555 ///
556 /// # Returns
557 /// Augments the last failure when present, otherwise a dedicated
558 /// max-duration error with no underlying attempt error.
559 fn map_retry_max_duration_exceeded(
560 started_at: Instant,
561 max_duration: Duration,
562 last_error: Option<HttpError>,
563 ) -> HttpError {
564 let elapsed = started_at.elapsed();
565 let max_duration_text = format!("{max_duration:?}");
566 match last_error {
567 Some(mut error) => {
568 error.message = format!(
569 "{} (retry max duration exceeded: {elapsed:?}/{max_duration_text})",
570 error.message
571 );
572 error
573 }
574 None => HttpError::retry_max_elapsed_exceeded(format!(
575 "HTTP retry max duration exceeded before a retryable error was captured: {elapsed:?}/{max_duration_text}"
576 )),
577 }
578 }
579
580 /// Maps a [`qubit_retry::RetryError`] into this crate's HTTP error model.
581 ///
582 /// # Parameters
583 /// - `error`: Terminal retry error from `qubit-retry`.
584 /// - `started_at`: Monotonic start instant of the HTTP retry flow.
585 /// - `max_duration`: Optional HTTP total retry budget.
586 /// - `max_attempts`: Configured maximum HTTP attempts.
587 ///
588 /// # Returns
589 /// A rich [`HttpError`] preserving the last attempt error when available.
590 fn map_retry_error(
591 error: RetryError<HttpError>,
592 started_at: Instant,
593 max_duration: Option<Duration>,
594 max_attempts: u32,
595 ) -> HttpError {
596 let attempts = error.attempts();
597 let reason = error.reason();
598 let (_, last_failure, _) = error.into_parts();
599 let last_error = last_failure.and_then(AttemptFailure::into_error);
600
601 match reason {
602 RetryErrorReason::AttemptsExceeded => {
603 let error =
604 last_error.expect("HTTP retry attempts exceeded should preserve last error");
605 Self::map_retry_attempts_exhausted(error, attempts, max_attempts)
606 }
607 RetryErrorReason::MaxOperationElapsedExceeded
608 | RetryErrorReason::MaxTotalElapsedExceeded => {
609 let max_duration =
610 max_duration.expect("HTTP retry elapsed limit requires max_duration");
611 Self::map_retry_max_duration_exceeded(started_at, max_duration, last_error)
612 }
613 RetryErrorReason::Aborted => {
614 let error = last_error.expect("HTTP retry abort should preserve last error");
615 if error.kind == crate::HttpErrorKind::Cancelled {
616 error
617 } else {
618 Self::map_retry_aborted(error, attempts, started_at)
619 }
620 }
621 RetryErrorReason::UnsupportedOperation | RetryErrorReason::WorkerStillRunning => {
622 HttpError::other(format!(
623 "HTTP retry executor failed after {attempts} attempt(s): {reason:?}"
624 ))
625 }
626 }
627 }
628
629 /// Builds a cancellation error for retry wait cancellation.
630 ///
631 /// # Parameters
632 /// - `message`: Human-readable cancellation reason.
633 /// - `method`: Request method to attach.
634 /// - `url`: Optional resolved request URL to attach.
635 ///
636 /// # Returns
637 /// [`HttpErrorKind::Cancelled`](crate::HttpErrorKind::Cancelled) with request
638 /// context.
639 fn retry_cancelled_error(
640 message: &str,
641 method: &http::Method,
642 url: Option<&url::Url>,
643 ) -> HttpError {
644 let mut error = HttpError::cancelled(message).with_method(method);
645 if let Some(url) = url {
646 error = error.with_url(url);
647 }
648 error
649 }
650
651 /// Opens an SSE stream and reconnects automatically on retryable stream
652 /// failures.
653 ///
654 /// Reconnect behavior:
655 /// - retryable transport/read failures trigger reconnects;
656 /// - optional reconnect on clean EOF (`reconnect_on_eof`);
657 /// - `Last-Event-ID` is set from the latest parsed SSE `id:` field;
658 /// - optional use of SSE `retry:` as next reconnect delay.
659 ///
660 /// # Parameters
661 /// - `request`: SSE request template reused on reconnect.
662 /// - `options`: Reconnect limits and delay policy.
663 ///
664 /// # Returns
665 /// SSE event stream yielding events from one or more reconnect sessions.
666 ///
667 /// # Errors
668 /// Stream items are `Result`; `Err` covers per-item failures such as:
669 /// - initial stream-open failures when not reconnectable or retries exhausted;
670 /// - SSE protocol errors (non-reconnectable by default);
671 /// - transport/read errors after reconnect budget is exhausted.
672 ///
673 /// # Side effects
674 /// Performs repeated HTTP requests and reads on reconnect; may sleep between
675 /// attempts according to reconnect options.
676 pub fn execute_sse_with_reconnect(
677 &self,
678 request: HttpRequest,
679 options: SseReconnectOptions,
680 ) -> SseEventStream {
681 SseReconnectRunner::new(self.clone(), request, options).run()
682 }
683}
684
685impl std::fmt::Debug for HttpClient {
686 /// Formats the client for debugging (exposes options and injectors; omits
687 /// the backend client).
688 ///
689 /// # Parameters
690 /// - `f`: Destination formatter.
691 ///
692 /// # Returns
693 /// `fmt::Result` from writing the debug struct.
694 ///
695 /// # Errors
696 /// Returns an error if formatting to `f` fails.
697 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
698 f.debug_struct("HttpClient")
699 .field("options", &self.options)
700 .field("injectors", &self.injectors)
701 .field("async_injectors", &self.async_injectors)
702 .field("request_interceptors", &self.request_interceptors)
703 .field("response_interceptors", &self.response_interceptors)
704 .finish_non_exhaustive()
705 }
706}