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")],