diff --git a/Cargo.lock b/Cargo.lock index bad5a7a4a..7c027819e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5221,6 +5221,7 @@ dependencies = [ "reqwest", "serde", "thiserror 2.0.18", + "torrust-tracker-rest-api-protocol", "url", "uuid", ] diff --git a/docs/issues/open/1944-1938-si-6-align-rest-api-client.md b/docs/issues/open/1944-1938-si-6-align-rest-api-client.md index 3d4de21ce..6373d395f 100644 --- a/docs/issues/open/1944-1938-si-6-align-rest-api-client.md +++ b/docs/issues/open/1944-1938-si-6-align-rest-api-client.md @@ -24,6 +24,16 @@ semantic-links: ## Subissue of REST API Contract-First Migration EPIC +## Clarifying Decisions (from AI agent Q&A with user) + +- **`AddKeyForm`**: Use the protocol package's `AddKeyForm` (with field `opt_seconds_valid`) and remove the local `AddKeyForm` from client. +- **`ClientError` enum variants**: + - `TransportError(reqwest::Error)` — network/connection failures + - `ApiError { status: StatusCode, body: String }` — non-2xx responses with the error body + - `DeserializationError(reqwest::Error)` — JSON parsing failures +- **Public `get()` function**: Keep as a public free function (used by health_check tests directly). +- **Re-export strategy**: Re-export both `ApiClient` and `ApiHttpClient` from the crate root for ergonomics. + ## Problem The REST API client package (`torrust-tracker-rest-api-client`) currently exposes only a **low-level** `Client` struct where all 10 methods return raw `reqwest::Response` values. Callers must manually deserialize responses and handle errors. Some internal methods use `.unwrap()`, panicking on transport errors. @@ -175,23 +185,23 @@ impl ApiClient { | ID | Status | Task | Notes | | --- | ------ | ------------------------------------------------------------ | ------------------------------------------------ | -| T1 | TODO | Rename `Client` → `ApiHttpClient` in `client.rs` | Compiler catches all references | -| T2 | TODO | Add `rest-api-protocol` to `rest-api-client/Cargo.toml` | | -| T3 | TODO | Define `ClientError` enum | Wraps reqwest error, deserialization, API errors | -| T4 | TODO | Add `ApiClient` struct before `ApiHttpClient` in `client.rs` | New high-level typed client | -| T5 | TODO | Implement typed methods on `ApiClient` for all endpoints | Returns `Result` | -| T6 | TODO | Verify pre-commit and pre-push checks pass | | +| T1 | DONE | Rename `Client` → `ApiHttpClient` in `client.rs` | Compiler catches all references | +| T2 | DONE | Add `rest-api-protocol` to `rest-api-client/Cargo.toml` | | +| T3 | DONE | Define `ClientError` enum | Wraps reqwest error, deserialization, API errors | +| T4 | DONE | Add `ApiClient` struct before `ApiHttpClient` in `client.rs` | New high-level typed client | +| T5 | DONE | Implement typed methods on `ApiClient` for all endpoints | Returns `Result` | +| T6 | DONE | Verify pre-commit and pre-push checks pass | | ## Verification / Progress -- [ ] `Client` renamed to `ApiHttpClient` across the codebase -- [ ] `rest-api-protocol` added as dependency -- [ ] `ClientError` enum defined -- [ ] `ApiClient` struct with typed methods for all endpoints added -- [ ] `ApiClient` appears before `ApiHttpClient` in `client.rs` -- [ ] All existing tests pass unchanged -- [ ] Pre-commit checks pass -- [ ] Pre-push checks pass +- [x] `Client` renamed to `ApiHttpClient` across the codebase +- [x] `rest-api-protocol` added as dependency +- [x] `ClientError` enum defined +- [x] `ApiClient` struct with typed methods for all endpoints added +- [x] `ApiClient` appears before `ApiHttpClient` in `client.rs` +- [x] All existing tests pass unchanged +- [x] Pre-commit checks pass +- [x] Pre-push checks pass ### Progress Log diff --git a/docs/issues/open/1969-1938-si-8-eliminate-unwraps-from-rest-api-client.md b/docs/issues/open/1969-1938-si-8-eliminate-unwraps-from-rest-api-client.md new file mode 100644 index 000000000..a63b868af --- /dev/null +++ b/docs/issues/open/1969-1938-si-8-eliminate-unwraps-from-rest-api-client.md @@ -0,0 +1,101 @@ +--- +doc-type: spec +issue-type: task +status: planned +priority: p2 +epic: 1938 +github-issue: 1969 +spec-path: docs/issues/open/1969-1938-si-8-eliminate-unwraps-from-rest-api-client.md +last-updated-utc: 2026-06-30 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md + - packages/rest-api-client/ + - packages/rest-api-client/src/v1/client.rs +--- + + + +# SI-8: Eliminate all unwraps from the REST API client package + +## Subissue of REST API Contract-First Migration EPIC + +## Goal + +Eliminate all `.unwrap()` calls from the `torrust-tracker-rest-api-client` package. Every operation that can fail must return a `Result`. For operations that are provably infallible, replace bare `.unwrap()` with an explicit `.expect("infallible: ...")` that documents why the operation cannot fail. + +## Background + +The `ApiClient` was made fully panic-free in SI-6 (PR #1968). However, the low-level `ApiHttpClient` and several free functions/helpers in `client.rs` still contain `.unwrap()` and `.expect()` calls that can panic at runtime. + +The calls fall into two categories: + +### Transport unwraps (must return `Result`) + +These are real failure points — network errors, URL parsing failures, etc. They must return `Result`: + +1. **11 public `ApiHttpClient` methods** — thin wrappers that delegate to fallible `*_result()` counterparts but `.unwrap()` the result. +2. **`post_empty()`, `post_form()`** (private) — same wrapper-with-unwrap pattern. +3. **`get()` (pub method on `ApiHttpClient`)** — same pattern. +4. **`get()` (pub free function)** — thin wrapper around `get_result()`. +5. **`get_request()` (pub on `ApiHttpClient`)** — calls `base_url()` which already returns `Result`. + +### Infallible conversions (replace `unwrap` with `expect`) + +These are provably infallible operations where a descriptive `expect` message is the right pattern: + +1. **`headers_with_request_id()`** — `Uuid::to_string()` always produces a valid ASCII string, and `HeaderValue::from_str()` for ASCII strings never fails. +2. **`headers_with_auth_token()`** — same pattern, pre-formatted token string. +3. **`get_request_with_query_result()` auth token inserts** — 2 token-to-HeaderValue conversions, same provably-infallible pattern. + +## Scope + +### In Scope + +- Change all panicking public `ApiHttpClient` methods to return `Result` instead of `Response`. +- Update all caller sites across the repository (contract tests, E2E tests, integration tests) to handle the new `Result` return types. +- Change helper functions (`post_empty`, `post_form`, `get`, `get_request`, `get()`) to return `Result`. +- Replace bare `.unwrap()` with `.expect("infallible: ...")` in `headers_with_request_id()`, `headers_with_auth_token()`, and `get_request_with_query_result()` auth token inserts. +- Update issue spec and documentation. + +### Out of Scope + +- Changing the `ApiHttpClient`'s HTTP transport or connection model. +- Adding retry/timeout policy (tracked separately). +- Removing the `ApiClient`/`ApiHttpClient` two-tier architecture. + +## Implementation Plan + +| ID | Status | Task | Notes | +| --- | ------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| T1 | TODO | Move `ApiHttpClient` public methods to return `Result` | 10 methods + `get()` method — return `ClientError` | +| T2 | TODO | Update all callers in contract tests (`packages/axum-rest-api-server/tests/`) | ~65 `ApiHttpClient::new(...)` call sites | +| T3 | TODO | Update callers in `src/console/ci/qbittorrent_e2e/tracker/client.rs` | E2E test runner wrapper | +| T4 | TODO | Update callers in `tests/servers/api/contract/stats/mod.rs` | Integration test | +| T5 | TODO | Replace bare `.unwrap()` with `.expect("infallible: ...")` for provably infallible conversions | `headers_with_request_id`, `headers_with_auth_token`, auth token inserts | +| T6 | TODO | Verify pre-commit and pre-push checks pass | | + +## Verification / Progress + +- [ ] All `ApiHttpClient` public methods return `Result` +- [ ] No bare `.unwrap()` calls remain (only `.expect("infallible: ...")` for provably infallible operations) +- [ ] All contract tests pass unchanged (except for updated `.unwrap()` calls on test side) +- [ ] E2E tests compile +- [ ] Pre-commit checks pass +- [ ] Pre-push checks pass + +## Acceptance Criteria + +- `ApiHttpClient` never panics on transport/URL failures; all errors are returned as `ClientError` +- Provably infallible conversions use `.expect("infallible: ...")` with a clear rationale +- No regressions in existing tests +- `linter all` passes + +### Progress Log + +| Date | Event | +| ---------- | ------------------ | +| 2026-06-30 | Spec drafted | +| 2026-06-30 | Spec moved to open | diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/authentication.rs b/packages/axum-rest-api-server/tests/server/v1/contract/authentication.rs index 24cc4193e..e9fc8d396 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/authentication.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/authentication.rs @@ -4,7 +4,7 @@ mod given_that_the_token_is_only_provided_in_the_authentication_header { use torrust_tracker_rest_api_client::common::http::Query; use torrust_tracker_rest_api_client::connection_info::ConnectionInfo; use torrust_tracker_rest_api_client::v1::client::{ - AUTH_BEARER_TOKEN_HEADER_PREFIX, Client, headers_with_auth_token, headers_with_request_id, + AUTH_BEARER_TOKEN_HEADER_PREFIX, ApiHttpClient, headers_with_auth_token, headers_with_request_id, }; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; @@ -20,7 +20,7 @@ mod given_that_the_token_is_only_provided_in_the_authentication_header { let token = env.get_connection_info().api_token.unwrap(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_request_with_query("stats", Query::default(), Some(headers_with_auth_token(&token))) .await; @@ -48,7 +48,7 @@ mod given_that_the_token_is_only_provided_in_the_authentication_header { .expect("the auth token is not a valid header value"), ); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_request_with_query("stats", Query::default(), Some(headers)) .await; @@ -83,7 +83,7 @@ mod given_that_the_token_is_only_provided_in_the_authentication_header { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request_with_query("stats", Query::default(), Some(headers)) .await; @@ -103,7 +103,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_rest_api_client::common::http::{Query, QueryParam}; use torrust_tracker_rest_api_client::connection_info::ConnectionInfo; - use torrust_tracker_rest_api_client::v1::client::{Client, TOKEN_PARAM_NAME, headers_with_request_id}; + use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, TOKEN_PARAM_NAME, headers_with_request_id}; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; use uuid::Uuid; @@ -120,7 +120,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request_with_query( "stats", @@ -144,7 +144,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request_with_query( "stats", @@ -173,7 +173,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request_with_query( "stats", @@ -203,7 +203,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); // At the beginning of the query component - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request(&format!("torrents?token={token}&limit=1")) .await; @@ -211,7 +211,7 @@ mod given_that_the_token_is_only_provided_in_the_query_param { assert_eq!(response.status(), 200); // At the end of the query component - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_request(&format!("torrents?limit=1&token={token}")) .await; @@ -227,7 +227,7 @@ mod given_that_not_token_is_provided { use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_rest_api_client::common::http::Query; use torrust_tracker_rest_api_client::connection_info::ConnectionInfo; - use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; + use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, headers_with_request_id}; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; use uuid::Uuid; @@ -244,7 +244,7 @@ mod given_that_not_token_is_provided { let connection_info = ConnectionInfo::anonymous(env.get_connection_info().origin); - let response = Client::new(connection_info) + let response = ApiHttpClient::new(connection_info) .unwrap() .get_request_with_query("stats", Query::default(), Some(headers_with_request_id(request_id))) .await; @@ -263,7 +263,7 @@ mod given_that_not_token_is_provided { mod given_that_token_is_provided_via_get_param_and_authentication_header { use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_rest_api_client::common::http::{Query, QueryParam}; - use torrust_tracker_rest_api_client::v1::client::{Client, TOKEN_PARAM_NAME, headers_with_auth_token}; + use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, TOKEN_PARAM_NAME, headers_with_auth_token}; use torrust_tracker_test_helpers::{configuration, logging}; #[tokio::test] @@ -276,7 +276,7 @@ mod given_that_token_is_provided_via_get_param_and_authentication_header { let non_authorized_token = "NonAuthorizedToken"; - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_request_with_query( "stats", diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/auth_key.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/auth_key.rs index c9dba6bfb..36c1d7074 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/auth_key.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/auth_key.rs @@ -3,7 +3,7 @@ use std::time::Duration; use serde::Serialize; use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_core::authentication::Key; -use torrust_tracker_rest_api_client::v1::client::{AddKeyForm, Client, headers_with_request_id}; +use torrust_tracker_rest_api_client::v1::client::{AddKeyForm, ApiHttpClient, headers_with_request_id}; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; use uuid::Uuid; @@ -24,12 +24,12 @@ async fn should_allow_generating_a_new_random_auth_key() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .add_auth_key( AddKeyForm { opt_key: None, - seconds_valid: Some(60), + opt_seconds_valid: Some(60), }, Some(headers_with_request_id(request_id)), ) @@ -57,12 +57,12 @@ async fn should_allow_uploading_a_preexisting_auth_key() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .add_auth_key( AddKeyForm { opt_key: Some("Xc1L4PbQJSFGlrgSRZl8wxSFAuMa21z5".to_string()), - seconds_valid: Some(60), + opt_seconds_valid: Some(60), }, Some(headers_with_request_id(request_id)), ) @@ -90,12 +90,12 @@ async fn should_not_allow_generating_a_new_auth_key_for_unauthenticated_users() let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .add_auth_key( AddKeyForm { opt_key: None, - seconds_valid: Some(60), + opt_seconds_valid: Some(60), }, Some(headers_with_request_id(request_id)), ) @@ -110,12 +110,12 @@ async fn should_not_allow_generating_a_new_auth_key_for_unauthenticated_users() let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .add_auth_key( AddKeyForm { opt_key: None, - seconds_valid: Some(60), + opt_seconds_valid: Some(60), }, Some(headers_with_request_id(request_id)), ) @@ -141,12 +141,12 @@ async fn should_fail_when_the_auth_key_cannot_be_generated() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .add_auth_key( AddKeyForm { opt_key: None, - seconds_valid: Some(60), + opt_seconds_valid: Some(60), }, Some(headers_with_request_id(request_id)), ) @@ -179,7 +179,7 @@ async fn should_allow_deleting_an_auth_key() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .delete_auth_key(&auth_key.key.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -214,7 +214,7 @@ async fn should_fail_generating_a_new_auth_key_when_the_provided_key_is_invalid( for invalid_key in invalid_keys { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .post_form( "keys", @@ -254,7 +254,7 @@ async fn should_fail_generating_a_new_auth_key_when_the_key_duration_is_invalid( for invalid_key_duration in invalid_key_durations { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .post_form( "keys", @@ -291,7 +291,7 @@ async fn should_fail_deleting_an_auth_key_when_the_key_id_is_invalid() { for invalid_auth_key in &invalid_auth_keys { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .delete_auth_key(invalid_auth_key, Some(headers_with_request_id(request_id))) .await; @@ -321,7 +321,7 @@ async fn should_fail_when_the_auth_key_cannot_be_deleted() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .delete_auth_key(&auth_key.key.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -355,7 +355,7 @@ async fn should_not_allow_deleting_an_auth_key_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .delete_auth_key(&auth_key.key.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -378,7 +378,7 @@ async fn should_not_allow_deleting_an_auth_key_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .delete_auth_key(&auth_key.key.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -409,7 +409,7 @@ async fn should_allow_reloading_keys() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .reload_keys(Some(headers_with_request_id(request_id))) .await; @@ -437,7 +437,7 @@ async fn should_fail_when_keys_cannot_be_reloaded() { force_database_error(&env.container.tracker_core_container.database_stores.schema_migrator).await; - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .reload_keys(Some(headers_with_request_id(request_id))) .await; @@ -468,7 +468,7 @@ async fn should_not_allow_reloading_keys_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .reload_keys(Some(headers_with_request_id(request_id))) .await; @@ -482,7 +482,7 @@ async fn should_not_allow_reloading_keys_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .reload_keys(Some(headers_with_request_id(request_id))) .await; @@ -501,7 +501,7 @@ mod deprecated_generate_key_endpoint { use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_core::authentication::Key; - use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; + use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, headers_with_request_id}; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; use uuid::Uuid; @@ -521,7 +521,7 @@ mod deprecated_generate_key_endpoint { let seconds_valid = 60; - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .generate_auth_key(seconds_valid, None) .await; @@ -549,14 +549,14 @@ mod deprecated_generate_key_endpoint { let request_id = Uuid::new_v4(); let seconds_valid = 60; - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .generate_auth_key(seconds_valid, Some(headers_with_request_id(request_id))) .await; assert_token_not_valid(response).await; - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .generate_auth_key(seconds_valid, None) .await; @@ -584,7 +584,7 @@ mod deprecated_generate_key_endpoint { ]; for invalid_key_duration in invalid_key_durations { - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .post_empty(&format!("key/{invalid_key_duration}"), None) .await; @@ -605,7 +605,7 @@ mod deprecated_generate_key_endpoint { let request_id = Uuid::new_v4(); let seconds_valid = 60; - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .generate_auth_key(seconds_valid, Some(headers_with_request_id(request_id))) .await; diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/stats.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/stats.rs index 9d24087ee..610457b18 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/stats.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/stats.rs @@ -3,7 +3,7 @@ use std::str::FromStr; use torrust_info_hash::InfoHash; use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_primitives::peer::fixture::PeerBuilder; -use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; +use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, headers_with_request_id}; use torrust_tracker_rest_api_protocol::v1::context::stats::resources::stats::Stats; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; @@ -26,7 +26,7 @@ async fn should_allow_getting_tracker_statistics() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_tracker_statistics(Some(headers_with_request_id(request_id))) .await; @@ -81,7 +81,7 @@ async fn should_not_allow_getting_tracker_statistics_for_unauthenticated_users() let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .get_tracker_statistics(Some(headers_with_request_id(request_id))) .await; @@ -95,7 +95,7 @@ async fn should_not_allow_getting_tracker_statistics_for_unauthenticated_users() let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .get_tracker_statistics(Some(headers_with_request_id(request_id))) .await; diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs index d46069c96..6d3166d00 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs @@ -4,7 +4,7 @@ use torrust_info_hash::InfoHash; use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_primitives::peer::fixture::PeerBuilder; use torrust_tracker_rest_api_client::common::http::{Query, QueryParam}; -use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; +use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, headers_with_request_id}; use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{self, Torrent}; use torrust_tracker_rest_api_runtime_adapter::v1::conversion; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; @@ -30,7 +30,7 @@ async fn should_allow_getting_all_torrents() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents(Query::empty(), Some(headers_with_request_id(request_id))) .await; @@ -64,7 +64,7 @@ async fn should_allow_limiting_the_torrents_in_the_result() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params([QueryParam::new("limit", "1")].to_vec()), @@ -101,7 +101,7 @@ async fn should_allow_the_torrents_result_pagination() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params([QueryParam::new("offset", "1")].to_vec()), @@ -137,7 +137,7 @@ async fn should_allow_getting_a_list_of_torrents_providing_infohashes() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params( @@ -184,7 +184,7 @@ async fn should_fail_getting_torrents_when_the_offset_query_parameter_cannot_be_ for invalid_offset in &invalid_offsets { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params([QueryParam::new("offset", invalid_offset)].to_vec()), @@ -213,7 +213,7 @@ async fn should_fail_getting_torrents_when_the_limit_query_parameter_cannot_be_p for invalid_limit in &invalid_limits { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params([QueryParam::new("limit", invalid_limit)].to_vec()), @@ -242,7 +242,7 @@ async fn should_fail_getting_torrents_when_the_info_hash_parameter_is_invalid() for invalid_info_hash in &invalid_info_hashes { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrents( Query::params([QueryParam::new("info_hash", invalid_info_hash)].to_vec()), @@ -268,7 +268,7 @@ async fn should_not_allow_getting_torrents_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .get_torrents(Query::empty(), Some(headers_with_request_id(request_id))) .await; @@ -282,7 +282,7 @@ async fn should_not_allow_getting_torrents_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .get_torrents(Query::default(), Some(headers_with_request_id(request_id))) .await; @@ -311,7 +311,7 @@ async fn should_allow_getting_a_torrent_info() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrent(&info_hash.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -340,7 +340,7 @@ async fn should_fail_while_getting_a_torrent_info_when_the_torrent_does_not_exis let request_id = Uuid::new_v4(); let info_hash = InfoHash::from_str("9e0217d0fa71c87332cd8bf9dbeabcb2c2cf3c4d").unwrap(); // DevSkim: ignore DS173237 - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrent(&info_hash.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -359,7 +359,7 @@ async fn should_fail_getting_a_torrent_info_when_the_provided_infohash_is_invali for invalid_infohash in &invalid_infohashes_returning_bad_request() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrent(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -370,7 +370,7 @@ async fn should_fail_getting_a_torrent_info_when_the_provided_infohash_is_invali for invalid_infohash in &invalid_infohashes_returning_not_found() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .get_torrent(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -393,7 +393,7 @@ async fn should_not_allow_getting_a_torrent_info_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .get_torrent(&info_hash.to_string(), Some(headers_with_request_id(request_id))) .await; @@ -407,7 +407,7 @@ async fn should_not_allow_getting_a_torrent_info_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .get_torrent(&info_hash.to_string(), Some(headers_with_request_id(request_id))) .await; diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/whitelist.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/whitelist.rs index 7e5298deb..baa075ac9 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/whitelist.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/whitelist.rs @@ -2,7 +2,7 @@ use std::str::FromStr; use torrust_info_hash::InfoHash; use torrust_tracker_axum_rest_api_server::testing::environment::Started; -use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; +use torrust_tracker_rest_api_client::v1::client::{ApiHttpClient, headers_with_request_id}; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; use uuid::Uuid; @@ -24,7 +24,7 @@ async fn should_allow_whitelisting_a_torrent() { let request_id = Uuid::new_v4(); let info_hash = "9e0217d0fa71c87332cd8bf9dbeabcb2c2cf3c4d".to_owned(); // DevSkim: ignore DS173237 - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .whitelist_a_torrent(&info_hash, Some(headers_with_request_id(request_id))) .await; @@ -49,7 +49,7 @@ async fn should_allow_whitelisting_a_torrent_that_has_been_already_whitelisted() let info_hash = "9e0217d0fa71c87332cd8bf9dbeabcb2c2cf3c4d".to_owned(); // DevSkim: ignore DS173237 - let api_client = Client::new(env.get_connection_info()).unwrap(); + let api_client = ApiHttpClient::new(env.get_connection_info()).unwrap(); let request_id = Uuid::new_v4(); @@ -78,7 +78,7 @@ async fn should_not_allow_whitelisting_a_torrent_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .whitelist_a_torrent(&info_hash, Some(headers_with_request_id(request_id))) .await; @@ -92,7 +92,7 @@ async fn should_not_allow_whitelisting_a_torrent_for_unauthenticated_users() { let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .whitelist_a_torrent(&info_hash, Some(headers_with_request_id(request_id))) .await; @@ -119,7 +119,7 @@ async fn should_fail_when_the_torrent_cannot_be_whitelisted() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .whitelist_a_torrent(&info_hash, Some(headers_with_request_id(request_id))) .await; @@ -143,7 +143,7 @@ async fn should_fail_whitelisting_a_torrent_when_the_provided_infohash_is_invali let request_id = Uuid::new_v4(); for invalid_infohash in &invalid_infohashes_returning_bad_request() { - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .whitelist_a_torrent(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -154,7 +154,7 @@ async fn should_fail_whitelisting_a_torrent_when_the_provided_infohash_is_invali let request_id = Uuid::new_v4(); for invalid_infohash in &invalid_infohashes_returning_not_found() { - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .whitelist_a_torrent(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -183,7 +183,7 @@ async fn should_allow_removing_a_torrent_from_the_whitelist() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .remove_torrent_from_whitelist(&hash, Some(headers_with_request_id(request_id))) .await; @@ -210,7 +210,7 @@ async fn should_not_fail_trying_to_remove_a_non_whitelisted_torrent_from_the_whi let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .remove_torrent_from_whitelist(&non_whitelisted_torrent_hash, Some(headers_with_request_id(request_id))) .await; @@ -229,7 +229,7 @@ async fn should_fail_removing_a_torrent_from_the_whitelist_when_the_provided_inf for invalid_infohash in &invalid_infohashes_returning_bad_request() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .remove_torrent_from_whitelist(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -240,7 +240,7 @@ async fn should_fail_removing_a_torrent_from_the_whitelist_when_the_provided_inf for invalid_infohash in &invalid_infohashes_returning_not_found() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .remove_torrent_from_whitelist(invalid_infohash, Some(headers_with_request_id(request_id))) .await; @@ -270,7 +270,7 @@ async fn should_fail_when_the_torrent_cannot_be_removed_from_the_whitelist() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .remove_torrent_from_whitelist(&hash, Some(headers_with_request_id(request_id))) .await; @@ -303,7 +303,7 @@ async fn should_not_allow_removing_a_torrent_from_the_whitelist_for_unauthentica let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_invalid_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_invalid_token(env.get_connection_info().origin)) .unwrap() .remove_torrent_from_whitelist(&hash, Some(headers_with_request_id(request_id))) .await; @@ -324,7 +324,7 @@ async fn should_not_allow_removing_a_torrent_from_the_whitelist_for_unauthentica let request_id = Uuid::new_v4(); - let response = Client::new(connection_with_no_token(env.get_connection_info().origin)) + let response = ApiHttpClient::new(connection_with_no_token(env.get_connection_info().origin)) .unwrap() .remove_torrent_from_whitelist(&hash, Some(headers_with_request_id(request_id))) .await; @@ -357,7 +357,7 @@ async fn should_allow_reload_the_whitelist_from_the_database() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .reload_whitelist(Some(headers_with_request_id(request_id))) .await; @@ -396,7 +396,7 @@ async fn should_fail_when_the_whitelist_cannot_be_reloaded_from_the_database() { let request_id = Uuid::new_v4(); - let response = Client::new(env.get_connection_info()) + let response = ApiHttpClient::new(env.get_connection_info()) .unwrap() .reload_whitelist(Some(headers_with_request_id(request_id))) .await; diff --git a/packages/rest-api-client/Cargo.toml b/packages/rest-api-client/Cargo.toml index f57aea95d..31e012f20 100644 --- a/packages/rest-api-client/Cargo.toml +++ b/packages/rest-api-client/Cargo.toml @@ -19,5 +19,6 @@ hyper = "1" reqwest = { version = "0", features = [ "json", "query" ] } serde = { version = "1", features = [ "derive" ] } thiserror = "2" +torrust-tracker-rest-api-protocol = { version = "3.0.0-develop", path = "../rest-api-protocol" } url = { version = "2", features = [ "serde" ] } uuid = { version = "1", features = [ "v4" ] } diff --git a/packages/rest-api-client/src/v1/client.rs b/packages/rest-api-client/src/v1/client.rs index fadef6bac..0385e09dc 100644 --- a/packages/rest-api-client/src/v1/client.rs +++ b/packages/rest-api-client/src/v1/client.rs @@ -1,8 +1,15 @@ use std::time::Duration; use hyper::{HeaderMap, header}; -use reqwest::{Error, Response}; +use reqwest::{Response, StatusCode}; use serde::Serialize; +use serde::de::DeserializeOwned; +use thiserror::Error; +// Re-export AddKeyForm from the protocol package for backwards compatibility. +pub use torrust_tracker_rest_api_protocol::v1::context::auth_key::forms::add_key_form::AddKeyForm; +use torrust_tracker_rest_api_protocol::v1::context::auth_key::resources::auth_key::AuthKey; +use torrust_tracker_rest_api_protocol::v1::context::stats::resources::stats::Stats; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; use url::Url; use uuid::Uuid; @@ -15,19 +22,219 @@ pub const AUTH_BEARER_TOKEN_HEADER_PREFIX: &str = "Bearer"; const API_PATH: &str = "api/v1/"; const DEFAULT_REQUEST_TIMEOUT_IN_SECS: u64 = 5; -/// API Client +/// Error type for [`ApiClient`] operations. +#[derive(Debug, Error)] +pub enum ClientError { + /// A transport-level error (connection refused, timeout, DNS failure, etc.). + #[error("transport error: {0}")] + TransportError(#[source] reqwest::Error), + + /// The API returned a non-2xx status code. + #[error("API error: {status} - {body}")] + ApiError { + /// The HTTP status code returned by the API. + status: StatusCode, + /// The response body (error message). + body: String, + }, + + /// Failed to deserialize the API response body into the expected type. + #[error("deserialization error: {0}")] + DeserializationError(#[source] reqwest::Error), + + /// An internal error (URL construction failure, etc.). + #[error("internal error: {0}")] + InternalError(String), +} + +impl From for ClientError { + fn from(err: reqwest::Error) -> Self { + Self::TransportError(err) + } +} + +/// High-level typed client for the Torrust Tracker REST API. +/// +/// Wraps [`ApiHttpClient`] and returns protocol DTOs from `rest-api-protocol`. +/// Never panics — all errors are returned as [`ClientError`]. +pub struct ApiClient { + inner: ApiHttpClient, +} + +impl ApiClient { + /// Creates a new `ApiClient`. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the HTTP client cannot be built. + pub fn new(connection_info: ConnectionInfo) -> Result { + Ok(Self { + inner: ApiHttpClient::new(connection_info).map_err(ClientError::TransportError)?, + }) + } + + /// Returns a reference to the inner [`ApiHttpClient`] for low-level operations. + #[must_use] + pub fn inner(&self) -> &ApiHttpClient { + &self.inner + } + + /// Generates a new random authentication key valid for `seconds_valid`. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + /// Returns [`ClientError::DeserializationError`] if the response cannot be parsed. + pub async fn generate_auth_key(&self, seconds_valid: i32) -> Result { + let response = self.inner.post_empty_result(&format!("key/{seconds_valid}"), None).await?; + Self::parse_response(response).await + } + + /// Adds a new authentication key using the provided form data. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + /// Returns [`ClientError::DeserializationError`] if the response cannot be parsed. + pub async fn add_auth_key(&self, form: AddKeyForm) -> Result { + let response = self.inner.post_form_result("keys", &form, None).await?; + Self::parse_response(response).await + } + + /// Deletes an authentication key. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + pub async fn delete_auth_key(&self, key: &str) -> Result<(), ClientError> { + let response = self.inner.delete_result(&format!("key/{key}"), None).await?; + Self::check_success(response).await + } + + /// Reloads authentication keys from the database. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + pub async fn reload_keys(&self) -> Result<(), ClientError> { + let response = self.inner.get_result("keys/reload", Query::default(), None).await?; + Self::check_success(response).await + } + + /// Whitelists a torrent by info hash. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + pub async fn whitelist_a_torrent(&self, info_hash: &str) -> Result<(), ClientError> { + let response = self.inner.post_empty_result(&format!("whitelist/{info_hash}"), None).await?; + Self::check_success(response).await + } + + /// Removes a torrent from the whitelist. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + pub async fn remove_torrent_from_whitelist(&self, info_hash: &str) -> Result<(), ClientError> { + let response = self.inner.delete_result(&format!("whitelist/{info_hash}"), None).await?; + Self::check_success(response).await + } + + /// Reloads the whitelist from the database. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + pub async fn reload_whitelist(&self) -> Result<(), ClientError> { + let response = self.inner.get_result("whitelist/reload", Query::default(), None).await?; + Self::check_success(response).await + } + + /// Gets a single torrent by info hash. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + /// Returns [`ClientError::DeserializationError`] if the response cannot be parsed. + pub async fn get_torrent(&self, info_hash: &str) -> Result { + let response = self + .inner + .get_result(&format!("torrent/{info_hash}"), Query::default(), None) + .await?; + Self::parse_response(response).await + } + + /// Gets a list of torrents matching the query parameters. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + /// Returns [`ClientError::DeserializationError`] if the response cannot be parsed. + pub async fn get_torrents(&self, params: Query) -> Result, ClientError> { + let response = self.inner.get_result("torrents", params, None).await?; + Self::parse_response(response).await + } + + /// Gets tracker statistics. + /// + /// # Errors + /// + /// Returns [`ClientError::TransportError`] if the request fails. + /// Returns [`ClientError::ApiError`] if the API returns a non-2xx status. + /// Returns [`ClientError::DeserializationError`] if the response cannot be parsed. + pub async fn get_tracker_statistics(&self) -> Result { + let response = self.inner.get_result("stats", Query::default(), None).await?; + Self::parse_response(response).await + } + + /// Parses a successful response into the expected DTO type. + async fn parse_response(response: Response) -> Result { + let status = response.status(); + if !status.is_success() { + let body = response.text().await.map_err(ClientError::TransportError)?; + return Err(ClientError::ApiError { status, body }); + } + response.json::().await.map_err(ClientError::DeserializationError) + } + + /// Checks that the response has a 2xx status code, ignoring the body. + async fn check_success(response: Response) -> Result<(), ClientError> { + let status = response.status(); + if !status.is_success() { + let body = response.text().await.map_err(ClientError::TransportError)?; + return Err(ClientError::ApiError { status, body }); + } + Ok(()) + } +} + +/// Low-level HTTP transport for the Torrust Tracker REST API. +/// +/// Handles connection info, URL building, auth headers, and raw HTTP requests. +/// Returns [`reqwest::Response`] directly. For a typed high-level API, use +/// [`ApiClient`]. #[allow(clippy::struct_field_names)] -pub struct Client { +pub struct ApiHttpClient { connection_info: ConnectionInfo, base_path: String, http_client: reqwest::Client, } -impl Client { +impl ApiHttpClient { /// # Errors /// /// Will return an error if the HTTP client can't be created. - pub fn new(connection_info: ConnectionInfo) -> Result { + pub fn new(connection_info: ConnectionInfo) -> Result { let client = reqwest::Client::builder() .timeout(Duration::from_secs(DEFAULT_REQUEST_TIMEOUT_IN_SECS)) .build()?; @@ -39,61 +246,137 @@ impl Client { }) } + /// Generates a new random authentication key valid for `seconds_valid`. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn generate_auth_key(&self, seconds_valid: i32, headers: Option) -> Response { - self.post_empty(&format!("key/{seconds_valid}"), headers).await + self.post_empty_result(&format!("key/{seconds_valid}"), headers) + .await + .unwrap() } + /// Adds a new authentication key using the provided form data. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn add_auth_key(&self, add_key_form: AddKeyForm, headers: Option) -> Response { - self.post_form("keys", &add_key_form, headers).await + self.post_form_result("keys", &add_key_form, headers).await.unwrap() } + /// Deletes an authentication key. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn delete_auth_key(&self, key: &str, headers: Option) -> Response { - self.delete(&format!("key/{key}"), headers).await + self.delete_result(&format!("key/{key}"), headers).await.unwrap() } + /// Reloads authentication keys from the database. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn reload_keys(&self, headers: Option) -> Response { - self.get("keys/reload", Query::default(), headers).await + self.get_result("keys/reload", Query::default(), headers).await.unwrap() } + /// Whitelists a torrent by info hash. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn whitelist_a_torrent(&self, info_hash: &str, headers: Option) -> Response { - self.post_empty(&format!("whitelist/{info_hash}"), headers).await + self.post_empty_result(&format!("whitelist/{info_hash}"), headers) + .await + .unwrap() } + /// Removes a torrent from the whitelist. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn remove_torrent_from_whitelist(&self, info_hash: &str, headers: Option) -> Response { - self.delete(&format!("whitelist/{info_hash}"), headers).await + self.delete_result(&format!("whitelist/{info_hash}"), headers).await.unwrap() } + /// Reloads the whitelist from the database. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn reload_whitelist(&self, headers: Option) -> Response { - self.get("whitelist/reload", Query::default(), headers).await + self.get_result("whitelist/reload", Query::default(), headers).await.unwrap() } + /// Gets a single torrent by info hash. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn get_torrent(&self, info_hash: &str, headers: Option) -> Response { - self.get(&format!("torrent/{info_hash}"), Query::default(), headers).await + self.get_result(&format!("torrent/{info_hash}"), Query::default(), headers) + .await + .unwrap() } + /// Gets a list of torrents matching the query parameters. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn get_torrents(&self, params: Query, headers: Option) -> Response { - self.get("torrents", params, headers).await + self.get_result("torrents", params, headers).await.unwrap() } + /// Gets tracker statistics. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn get_tracker_statistics(&self, headers: Option) -> Response { - self.get("stats", Query::default(), headers).await + self.get_result("stats", Query::default(), headers).await.unwrap() } + /// Performs a GET request. + /// + /// # Panics + /// + /// Will panic if the request can't be sent. pub async fn get(&self, path: &str, params: Query, headers: Option) -> Response { + self.get_result(path, params, headers).await.unwrap() + } + + /// Fallible version of [`Self::get`] that returns a `Result` instead of panicking. + pub(crate) async fn get_result( + &self, + path: &str, + params: Query, + headers: Option, + ) -> Result { let mut query: Query = params; if let Some(token) = &self.connection_info.api_token { query.add_param(QueryParam::new(TOKEN_PARAM_NAME, token)); } - self.get_request_with_query(path, query, headers).await + self.get_request_with_query_result(path, query, headers).await } /// # Panics /// /// Will panic if the request can't be sent pub async fn post_empty(&self, path: &str, headers: Option) -> Response { - let builder = self.http_client.post(self.base_url(path).clone()); + self.post_empty_result(path, headers).await.unwrap() + } + + /// Fallible version of [`Self::post_empty`] that returns a `Result` instead of panicking. + pub(crate) async fn post_empty_result(&self, path: &str, headers: Option) -> Result { + let builder = self.http_client.post(self.base_url(path)?.clone()); let builder = match headers { Some(headers) => builder.headers(headers), @@ -105,14 +388,24 @@ impl Client { None => builder, }; - builder.send().await.unwrap() + Ok(builder.send().await?) } /// # Panics /// /// Will panic if the request can't be sent pub async fn post_form(&self, path: &str, form: &T, headers: Option) -> Response { - let builder = self.http_client.post(self.base_url(path).clone()).json(&form); + self.post_form_result(path, form, headers).await.unwrap() + } + + /// Fallible version of [`Self::post_form`] that returns a `Result` instead of panicking. + pub(crate) async fn post_form_result( + &self, + path: &str, + form: &T, + headers: Option, + ) -> Result { + let builder = self.http_client.post(self.base_url(path)?.clone()).json(&form); let builder = match headers { Some(headers) => builder.headers(headers), @@ -124,14 +417,12 @@ impl Client { None => builder, }; - builder.send().await.unwrap() + Ok(builder.send().await?) } - /// # Panics - /// - /// Will panic if the request can't be sent - async fn delete(&self, path: &str, headers: Option) -> Response { - let builder = self.http_client.delete(self.base_url(path).clone()); + /// Fallible version of [`Self::delete`] that returns a `Result` instead of panicking. + async fn delete_result(&self, path: &str, headers: Option) -> Result { + let builder = self.http_client.delete(self.base_url(path)?.clone()); let builder = match headers { Some(headers) => builder.headers(headers), @@ -143,13 +434,24 @@ impl Client { None => builder, }; - builder.send().await.unwrap() + Ok(builder.send().await?) } /// # Panics /// /// Will panic if it can't convert the authentication token to a `HeaderValue`. pub async fn get_request_with_query(&self, path: &str, params: Query, headers: Option) -> Response { + self.get_request_with_query_result(path, params, headers).await.unwrap() + } + + /// Fallible version of [`Self::get_request_with_query`] that returns a `Result` instead of panicking. + pub(crate) async fn get_request_with_query_result( + &self, + path: &str, + params: Query, + headers: Option, + ) -> Result { + let url = self.base_url(path)?; match &self.connection_info.api_token { Some(token) => { let headers = if let Some(headers) = headers { @@ -185,18 +487,22 @@ impl Client { headers }; - get(self.base_url(path), Some(params), Some(headers)).await + get_result(url, Some(params), Some(headers)).await } - None => get(self.base_url(path), Some(params), headers).await, + None => get_result(url, Some(params), headers).await, } } + /// # Panics + /// + /// Will panic if the request can't be sent pub async fn get_request(&self, path: &str) -> Response { - get(self.base_url(path), None, None).await + get(self.base_url(path).unwrap(), None, None).await } - fn base_url(&self, path: &str) -> Url { - Url::parse(&format!("{}{}{path}", self.connection_info.origin, self.base_path)).unwrap() + fn base_url(&self, path: &str) -> Result { + Url::parse(&format!("{}{}{path}", self.connection_info.origin, self.base_path)) + .map_err(|e| ClientError::InternalError(format!("invalid URL: {e}"))) } } @@ -204,10 +510,14 @@ impl Client { /// /// Will panic if the request can't be sent pub async fn get(path: Url, query: Option, headers: Option) -> Response { + get_result(path, query, headers).await.unwrap() +} + +/// Fallible version of [`get`] that returns a `Result` instead of panicking. +pub(crate) async fn get_result(path: Url, query: Option, headers: Option) -> Result { let client = reqwest::Client::builder() .timeout(Duration::from_secs(DEFAULT_REQUEST_TIMEOUT_IN_SECS)) - .build() - .unwrap(); + .build()?; let mut request_builder = client.get(path); @@ -219,7 +529,7 @@ pub async fn get(path: Url, query: Option, headers: Option) -> request_builder = request_builder.headers(headers); } - request_builder.send().await.unwrap() + request_builder.send().await.map_err(ClientError::TransportError) } /// Returns a `HeaderMap` with a request id header. @@ -256,10 +566,3 @@ pub fn headers_with_auth_token(token: &str) -> HeaderMap { ); headers } - -#[derive(Serialize, Debug)] -pub struct AddKeyForm { - #[serde(rename = "key")] - pub opt_key: Option, - pub seconds_valid: Option, -} diff --git a/packages/rest-api-client/src/v1/mod.rs b/packages/rest-api-client/src/v1/mod.rs index b9babe5bc..104437df8 100644 --- a/packages/rest-api-client/src/v1/mod.rs +++ b/packages/rest-api-client/src/v1/mod.rs @@ -1 +1,3 @@ pub mod client; + +pub use client::{ApiClient, ApiHttpClient}; diff --git a/src/console/ci/qbittorrent_e2e/tracker/client.rs b/src/console/ci/qbittorrent_e2e/tracker/client.rs index f517d0af5..afb802f4a 100644 --- a/src/console/ci/qbittorrent_e2e/tracker/client.rs +++ b/src/console/ci/qbittorrent_e2e/tracker/client.rs @@ -1,11 +1,11 @@ //! Tracker REST API client, scoped to E2E test needs. //! -//! Wraps the official [`torrust_tracker_rest_api_client::v1::Client`] so that +//! Wraps the official [`torrust_tracker_rest_api_client::v1::client::ApiHttpClient`] so that //! future scenario steps can call any REST API endpoint through the same client //! without having to reconstruct connection details each time. use anyhow::Context; use torrust_tracker_rest_api_client::connection_info::{ConnectionInfo, Origin}; -use torrust_tracker_rest_api_client::v1::client::Client; +use torrust_tracker_rest_api_client::v1::client::ApiHttpClient; use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::Torrent; use super::super::types::InfoHash; @@ -14,9 +14,9 @@ use super::config_builder::TrackerConfig; /// Wrapper around the official Torrust Tracker REST API client. /// /// Provides typed, high-level helpers for the endpoints used in E2E test scenarios. -/// All other endpoints are still reachable through the inner [`Client`]. +/// All other endpoints are still reachable through the inner [`ApiHttpClient`]. pub(crate) struct TrackerApiClient { - inner: Client, + inner: ApiHttpClient, } impl TrackerApiClient { @@ -32,7 +32,7 @@ impl TrackerApiClient { let connection_info = ConnectionInfo::authenticated(origin, tracker_config.access_token()); - let inner = Client::new(connection_info).context("failed to build tracker REST API client")?; + let inner = ApiHttpClient::new(connection_info).context("failed to build tracker REST API client")?; Ok(Self { inner }) } diff --git a/tests/servers/api/contract/stats/mod.rs b/tests/servers/api/contract/stats/mod.rs index 6e1fe8c40..b77863d42 100644 --- a/tests/servers/api/contract/stats/mod.rs +++ b/tests/servers/api/contract/stats/mod.rs @@ -9,7 +9,7 @@ use torrust_tracker_client::http::client::Client as HttpTrackerClient; use torrust_tracker_client::http::client::requests::announce::QueryBuilder; use torrust_tracker_lib::app; use torrust_tracker_rest_api_client::connection_info::{ConnectionInfo, Origin}; -use torrust_tracker_rest_api_client::v1::client::Client as TrackerApiClient; +use torrust_tracker_rest_api_client::v1::client::ApiHttpClient as TrackerApiClient; #[tokio::test] async fn the_stats_api_endpoint_should_return_the_global_stats() {