feat: [#974] new API endpoint to upload pre-existing keys

You can test it with:

```console
curl -X POST http://localhost:1212/api/v1/keys?token=MyAccessToken \
     -H "Content-Type: application/json" \
     -d '{
           "key": "Xc1L4PbQJSFGlrgSRZl8wxSFAuMa21z7",
           "seconds_valid": 7200
         }'
```

The `key` field is optional. If it's not provided a random key will be
generated.

src/core/auth.rs

@@ -152,7 +152,7 @@ pub struct Key(String);
 /// ```
 ///
 /// If the string does not contains a valid key, the parser function will return this error.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, PartialEq, Eq, Display)]
 pub struct ParseKeyError;
 
 impl FromStr for Key {

src/core/mod.rs

@@ -453,16 +453,17 @@ use std::panic::Location;
 use std::sync::Arc;
 use std::time::Duration;
 
+use auth::ExpiringKey;
 use databases::driver::Driver;
 use derive_more::Constructor;
 use tokio::sync::mpsc::error::SendError;
 use torrust_tracker_clock::clock::Time;
 use torrust_tracker_configuration::v2::database;
 use torrust_tracker_configuration::{AnnouncePolicy, Core, TORRENT_PEERS_LIMIT};
 use torrust_tracker_primitives::info_hash::InfoHash;
-use torrust_tracker_primitives::peer;
 use torrust_tracker_primitives::swarm_metadata::SwarmMetadata;
 use torrust_tracker_primitives::torrent_metrics::TorrentsMetrics;
+use torrust_tracker_primitives::{peer, DurationSinceUnixEpoch};
 use torrust_tracker_torrent_repository::entry::EntrySync;
 use torrust_tracker_torrent_repository::repository::Repository;
 use tracing::debug;
@@ -804,6 +805,37 @@ impl Tracker {
     /// Will return a `database::Error` if unable to add the `auth_key` to the database.
     pub async fn generate_auth_key(&self, lifetime: Duration) -> Result<auth::ExpiringKey, databases::error::Error> {
         let auth_key = auth::generate(lifetime);
+
+        self.database.add_key_to_keys(&auth_key)?;
+        self.keys.write().await.insert(auth_key.key.clone(), auth_key.clone());
+        Ok(auth_key)
+    }
+
+    /// It adds a pre-generated authentication key.
+    ///
+    /// Authentication keys are used by HTTP trackers.
+    ///
+    /// # Context: Authentication
+    ///
+    /// # Errors
+    ///
+    /// Will return a `database::Error` if unable to add the `auth_key` to the
+    /// database. For example, if the key already exist.
+    ///
+    /// # Arguments
+    ///
+    /// * `lifetime` - The duration in seconds for the new key. The key will be
+    ///   no longer valid after `lifetime` seconds.
+    pub async fn add_auth_key(
+        &self,
+        key: Key,
+        valid_until: DurationSinceUnixEpoch,
+    ) -> Result<auth::ExpiringKey, databases::error::Error> {
+        let auth_key = ExpiringKey { key, valid_until };
+
+        // code-review: should we return a friendly error instead of the DB
+        // constrain error when the key already exist? For now, it's returning
+        // the specif error for each DB driver when a UNIQUE constrain fails.
         self.database.add_key_to_keys(&auth_key)?;
         self.keys.write().await.insert(auth_key.key.clone(), auth_key.clone());
         Ok(auth_key)
@@ -816,10 +848,6 @@ impl Tracker {
     /// # Errors
     ///
     /// Will return a `database::Error` if unable to remove the `key` to the database.
-    ///
-    /// # Panics
-    ///
-    /// Will panic if key cannot be converted into a valid `Key`.
     pub async fn remove_auth_key(&self, key: &Key) -> Result<(), databases::error::Error> {
         self.database.remove_key_from_keys(key)?;
         self.keys.write().await.remove(key);

src/servers/apis/v1/context/auth_key/forms.rs

@@ -0,0 +1,8 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+pub struct AddKeyForm {
+    #[serde(rename = "key")]
+    pub opt_key: Option<String>,
+    pub seconds_valid: u64,
+}

src/servers/apis/v1/context/auth_key/handlers.rs

@@ -3,17 +3,66 @@ use std::str::FromStr;
 use std::sync::Arc;
 use std::time::Duration;
 
-use axum::extract::{Path, State};
+use axum::extract::{self, Path, State};
 use axum::response::Response;
 use serde::Deserialize;
+use torrust_tracker_clock::clock::Time;
 
+use super::forms::AddKeyForm;
 use super::responses::{
-    auth_key_response, failed_to_delete_key_response, failed_to_generate_key_response, failed_to_reload_keys_response,
+    auth_key_response, failed_to_add_key_response, failed_to_delete_key_response, failed_to_generate_key_response,
+    failed_to_reload_keys_response, invalid_auth_key_duration_response, invalid_auth_key_response,
 };
 use crate::core::auth::Key;
 use crate::core::Tracker;
 use crate::servers::apis::v1::context::auth_key::resources::AuthKey;
 use crate::servers::apis::v1::responses::{invalid_auth_key_param_response, ok_response};
+use crate::CurrentClock;
+
+/// It handles the request to add a new authentication key.
+///
+/// It returns these types of responses:
+///
+/// - `200` with a json [`AuthKey`]
+///    resource. If the key was generated successfully.
+/// - `400` with an error if the key couldn't been added because of an invalid
+///    request.
+/// - `500` with serialized error in debug format. If the key couldn't be
+///    generated.
+///
+/// Refer to the [API endpoint documentation](crate::servers::apis::v1::context::auth_key#generate-a-new-authentication-key)
+/// for more information about this endpoint.
+pub async fn add_auth_key_handler(
+    State(tracker): State<Arc<Tracker>>,
+    extract::Json(add_key_form): extract::Json<AddKeyForm>,
+) -> Response {
+    match add_key_form.opt_key {
+        Some(pre_existing_key) => {
+            let Some(valid_until) = CurrentClock::now_add(&Duration::from_secs(add_key_form.seconds_valid)) else {
+                return invalid_auth_key_duration_response(add_key_form.seconds_valid);
+            };
+
+            let key = pre_existing_key.parse::<Key>();
+
+            match key {
+                Ok(key) => match tracker.add_auth_key(key, valid_until).await {
+                    Ok(auth_key) => auth_key_response(&AuthKey::from(auth_key)),
+                    Err(e) => failed_to_add_key_response(e),
+                },
+                Err(e) => invalid_auth_key_response(&pre_existing_key, &e),
+            }
+        }
+        None => {
+            match tracker
+                .generate_auth_key(Duration::from_secs(add_key_form.seconds_valid))
+                .await
+            {
+                Ok(auth_key) => auth_key_response(&AuthKey::from(auth_key)),
+                Err(e) => failed_to_generate_key_response(e),
+            }
+        }
+    }
+}
 
 /// It handles the request to generate a new authentication key.
 ///

src/servers/apis/v1/context/auth_key/mod.rs

@@ -119,6 +119,7 @@
 //!     "status": "ok"
 //! }
 //! ```
+pub mod forms;
 pub mod handlers;
 pub mod resources;
 pub mod responses;

src/servers/apis/v1/context/auth_key/responses.rs

@@ -4,8 +4,9 @@ use std::error::Error;
 use axum::http::{header, StatusCode};
 use axum::response::{IntoResponse, Response};
 
+use crate::core::auth::ParseKeyError;
 use crate::servers::apis::v1::context::auth_key::resources::AuthKey;
-use crate::servers::apis::v1::responses::unhandled_rejection_response;
+use crate::servers::apis::v1::responses::{bad_request_response, unhandled_rejection_response};
 
 /// `200` response that contains the `AuthKey` resource as json.
 ///
@@ -22,12 +23,20 @@ pub fn auth_key_response(auth_key: &AuthKey) -> Response {
         .into_response()
 }
 
+// Error responses
+
 /// `500` error response when a new authentication key cannot be generated.
 #[must_use]
 pub fn failed_to_generate_key_response<E: Error>(e: E) -> Response {
     unhandled_rejection_response(format!("failed to generate key: {e}"))
 }
 
+/// `500` error response when the provide key cannot be added.
+#[must_use]
+pub fn failed_to_add_key_response<E: Error>(e: E) -> Response {
+    unhandled_rejection_response(format!("failed to add key: {e}"))
+}
+
 /// `500` error response when an authentication key cannot be deleted.
 #[must_use]
 pub fn failed_to_delete_key_response<E: Error>(e: E) -> Response {
@@ -40,3 +49,13 @@ pub fn failed_to_delete_key_response<E: Error>(e: E) -> Response {
 pub fn failed_to_reload_keys_response<E: Error>(e: E) -> Response {
     unhandled_rejection_response(format!("failed to reload keys: {e}"))
 }
+
+#[must_use]
+pub fn invalid_auth_key_response(auth_key: &str, error: &ParseKeyError) -> Response {
+    bad_request_response(&format!("Invalid URL: invalid auth key: string \"{auth_key}\", {error}"))
+}
+
+#[must_use]
+pub fn invalid_auth_key_duration_response(duration: u64) -> Response {
+    bad_request_response(&format!("Invalid URL: invalid auth key duration: \"{duration}\""))
+}

src/servers/apis/v1/context/auth_key/routes.rs

@@ -11,7 +11,7 @@ use std::sync::Arc;
 use axum::routing::{get, post};
 use axum::Router;
 
-use super::handlers::{delete_auth_key_handler, generate_auth_key_handler, reload_keys_handler};
+use super::handlers::{add_auth_key_handler, delete_auth_key_handler, generate_auth_key_handler, reload_keys_handler};
 use crate::core::Tracker;
 
 /// It adds the routes to the router for the [`auth_key`](crate::servers::apis::v1::context::auth_key) API context.
@@ -30,5 +30,9 @@ pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
                 .with_state(tracker.clone()),
         )
         // Keys command
-        .route(&format!("{prefix}/keys/reload"), get(reload_keys_handler).with_state(tracker))
+        .route(
+            &format!("{prefix}/keys/reload"),
+            get(reload_keys_handler).with_state(tracker.clone()),
+        )
+        .route(&format!("{prefix}/keys"), post(add_auth_key_handler).with_state(tracker))
 }

src/servers/apis/v1/responses.rs

@@ -61,7 +61,8 @@ pub fn invalid_auth_key_param_response(invalid_key: &str) -> Response {
     bad_request_response(&format!("Invalid auth key id param \"{invalid_key}\""))
 }
 
-fn bad_request_response(body: &str) -> Response {
+#[must_use]
+pub fn bad_request_response(body: &str) -> Response {
     (
         StatusCode::BAD_REQUEST,
         [(header::CONTENT_TYPE, "text/plain; charset=utf-8")],