phoenix/icarus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 33 Wiki Activity

tsk-170: Added more documentation

Browse Source
This commit is contained in:
kdeng00
2025-08-22 19:43:08 -04:00
parent 594410cb12
commit 1706eccdf1
2 changed files with 124 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/callers/coverart.rs
+48 -41
View File
@@ -6,9 +6,21 @@ pub struct CoverArtQueue {
} }
pub mod request { pub mod request {
pub mod queue {
#[derive(utoipa::ToSchema)]
pub struct Request {
/// Filename
pub file: String,
#[schema(rename = "type")]
/// File type. Should be a file and not a value
pub file_type: String,
/// Raw data of the cover art file
pub value: Vec<u8>,
}
}
pub mod link { pub mod link {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Request { pub struct Request {
pub coverart_id: uuid::Uuid, pub coverart_id: uuid::Uuid,
pub song_queue_id: uuid::Uuid, pub song_queue_id: uuid::Uuid,
@@ -16,7 +28,7 @@ pub mod request {
} }
pub mod fetch_coverart_no_data { pub mod fetch_coverart_no_data {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Params { pub struct Params {
pub id: Option<uuid::Uuid>, pub id: Option<uuid::Uuid>,
pub song_queue_id: Option<uuid::Uuid>, pub song_queue_id: Option<uuid::Uuid>,
@@ -24,7 +36,7 @@ pub mod request {
} }
pub mod fetch_coverart_with_data { pub mod fetch_coverart_with_data {
#[derive(Debug, serde::Deserialize, serde::Serialize)] #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Params { pub struct Params {
pub id: Option<uuid::Uuid>, pub id: Option<uuid::Uuid>,
pub song_queue_id: Option<uuid::Uuid>, pub song_queue_id: Option<uuid::Uuid>,
@@ -32,7 +44,7 @@ pub mod request {
} }
pub mod create_coverart { pub mod create_coverart {
#[derive(Debug, serde::Deserialize, serde::Serialize)] #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Request { pub struct Request {
pub song_id: uuid::Uuid, pub song_id: uuid::Uuid,
pub coverart_queue_id: uuid::Uuid, pub coverart_queue_id: uuid::Uuid,
@@ -40,14 +52,14 @@ pub mod request {
} }
pub mod wipe_data_from_coverart_queue { pub mod wipe_data_from_coverart_queue {
#[derive(Debug, serde::Deserialize, serde::Serialize)] #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Request { pub struct Request {
pub coverart_queue_id: uuid::Uuid, pub coverart_queue_id: uuid::Uuid,
} }
} }
pub mod get_coverart { pub mod get_coverart {
#[derive(Debug, serde::Deserialize, serde::Serialize)] #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Params { pub struct Params {
pub id: Option<uuid::Uuid>, pub id: Option<uuid::Uuid>,
} }
@@ -55,20 +67,20 @@ pub mod request {
} }
pub mod response { pub mod response {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<uuid::Uuid>, pub data: Vec<uuid::Uuid>,
} }
pub mod link { pub mod link {
#[derive(Debug, serde::Deserialize, serde::Serialize)] #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Id { pub struct Id {
pub coverart_id: uuid::Uuid, pub coverart_id: uuid::Uuid,
pub song_queue_id: uuid::Uuid, pub song_queue_id: uuid::Uuid,
} }
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<Id>, pub data: Vec<Id>,
@@ -76,7 +88,7 @@ pub mod response {
} }
pub mod fetch_coverart_no_data { pub mod fetch_coverart_no_data {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<super::super::CoverArtQueue>, pub data: Vec<super::super::CoverArtQueue>,
@@ -84,7 +96,7 @@ pub mod response {
} }
pub mod fetch_coverart_with_data { pub mod fetch_coverart_with_data {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<Vec<u8>>, pub data: Vec<Vec<u8>>,
@@ -92,7 +104,7 @@ pub mod response {
} }
pub mod create_coverart { pub mod create_coverart {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<icarus_models::coverart::CoverArt>, pub data: Vec<icarus_models::coverart::CoverArt>,
@@ -100,7 +112,7 @@ pub mod response {
} }
pub mod wipe_data_from_coverart_queue { pub mod wipe_data_from_coverart_queue {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<uuid::Uuid>, pub data: Vec<uuid::Uuid>,
@@ -108,7 +120,7 @@ pub mod response {
} }
pub mod get_coverart { pub mod get_coverart {
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<icarus_models::coverart::CoverArt>, pub data: Vec<icarus_models::coverart::CoverArt>,
@@ -465,17 +477,16 @@ pub mod endpoint {
use axum::response::IntoResponse; use axum::response::IntoResponse;
/// Endpoint to queue cover art
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUECOVERART,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::queue::Request,
description = "User Id and queued song id",
content_type = "application/json"
), ),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Successful", body = super::response::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error queueing cover art", body = super::response::Response)
) )
)] )]
pub async fn queue( pub async fn queue(
@@ -523,17 +534,18 @@ pub mod endpoint {
} }
} }
/// Endpoint to link queued cover art
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUECOVERARTLINK,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::link::Request,
description = "User Id and queued song id", description = "Linking queued cover art to queued song",
content_type = "application/json" content_type = "application/json"
), ),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued cover art linked", body = super::response::link::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Linkage failed", body = super::response::link::Response)
) )
)] )]
pub async fn link( pub async fn link(
@@ -563,19 +575,17 @@ pub mod endpoint {
} }
} }
/*
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUECOVERART,
request_body( params(super::request::fetch_coverart_no_data::Params),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued song linked", body = super::response::fetch_coverart_no_data::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Linkage failed", body = super::response::fetch_coverart_no_data::Response)
) )
)] )]
*/
pub async fn fetch_coverart_no_data( pub async fn fetch_coverart_no_data(
axum::Extension(pool): axum::Extension<sqlx::PgPool>, axum::Extension(pool): axum::Extension<sqlx::PgPool>,
axum::extract::Query(params): axum::extract::Query< axum::extract::Query(params): axum::extract::Query<
@@ -623,17 +633,14 @@ pub mod endpoint {
} }
} }
/// Endpoint to fetch the queued cover art data
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUECOVERARTDATA,
request_body( params(("id" = uuid::Uuid, Path, description = "Queued cover art Id")),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued cover art data", body = Vec<u8>),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error fetching queued cover art data", body = Vec<u8>)
) )
)] )]
pub async fn fetch_coverart_with_data( pub async fn fetch_coverart_with_data(
src/callers/song.rs
+76 -84
View File
@@ -142,7 +142,7 @@ pub mod response {
pub new_status: String, pub new_status: String,
} }
#[derive(Default, serde::Deserialize, serde::Serialize)] #[derive(Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<ChangedStatus>, pub data: Vec<ChangedStatus>,
@@ -196,7 +196,7 @@ pub mod response {
pub coverart: icarus_models::coverart::CoverArt, pub coverart: icarus_models::coverart::CoverArt,
} }
#[derive(Debug, Default, serde::Deserialize, serde::Serialize)] #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
pub struct Response { pub struct Response {
pub message: String, pub message: String,
pub data: Vec<SongAndCoverArt>, pub data: Vec<SongAndCoverArt>,
@@ -881,7 +881,7 @@ pub mod endpoint {
/// Endpoint to queue a song. Starts the process and places the song in a queue /// Endpoint to queue a song. Starts the process and places the song in a queue
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue", path = super::super::endpoints::QUEUESONG,
request_body( request_body(
content = super::request::song_queue::SongQueueRequest, content = super::request::song_queue::SongQueueRequest,
description = "Multipart form data for uploading song", description = "Multipart form data for uploading song",
@@ -941,8 +941,8 @@ pub mod endpoint {
/// Endpoint to link a user id to a queued song /// Endpoint to link a user id to a queued song
#[utoipa::path( #[utoipa::path(
post, patch,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUESONGLINKUSERID,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::link_user_id::Request,
description = "User Id and queued song id", description = "User Id and queued song id",
@@ -984,8 +984,9 @@ pub mod endpoint {
} }
} }
/// Endpoint to fetch the next queued song as long as it is available
#[utoipa::path( #[utoipa::path(
post, get,
path = super::super::endpoints::NEXTQUEUESONG, path = super::super::endpoints::NEXTQUEUESONG,
responses( responses(
(status = 200, description = "Queued song is present and available", body = super::response::fetch_queue_song::Response), (status = 200, description = "Queued song is present and available", body = super::response::fetch_queue_song::Response),
@@ -1014,17 +1015,14 @@ pub mod endpoint {
} }
// TODO: Rename // TODO: Rename
/// Endpoint to download the queued song
#[utoipa::path( #[utoipa::path(
post, get,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUESONGDATA,
request_body( params(("id" = uuid::Uuid, Path, description = "Queued song Id")),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued song linked", body = Vec<u8>),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Linkage failed", body = Vec<u8>)
) )
)] )]
pub async fn download_flac( pub async fn download_flac(
@@ -1055,17 +1053,18 @@ pub mod endpoint {
} }
} }
/// Endpoint to update the status of a queued song
#[utoipa::path( #[utoipa::path(
post, patch,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUESONG,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::update_status::Request,
description = "User Id and queued song id", description = "Update the status of a queued song",
content_type = "application/json" content_type = "application/json"
), ),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Status has been updated", body = super::response::update_status::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error updating status of queued song", body = super::response::update_status::Response)
) )
)] )]
pub async fn update_song_queue_status( pub async fn update_song_queue_status(
@@ -1120,17 +1119,20 @@ pub mod endpoint {
} }
} }
/// Endpoint to update the queued song data
#[utoipa::path( #[utoipa::path(
post, patch,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUESONGUPDATE,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::song_queue::SongQueueRequest,
description = "User Id and queued song id", description = "Multipart form data for uploading song",
content_type = "application/json" content_type = "multipart/form-data"
), ),
params(("id" = uuid::Uuid, Path, description = "Queued song Id")),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued song updated", body = super::response::update_song_queue::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error updating queued song", body = super::response::update_song_queue::Response),
(status = 404, description = "Queued song not found", body = super::response::update_song_queue::Response)
) )
)] )]
pub async fn update_song_queue( pub async fn update_song_queue(
@@ -1179,17 +1181,19 @@ pub mod endpoint {
} }
} }
/// Endpoint to create song
#[utoipa::path( #[utoipa::path(
post, post,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUEMETADATA,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::create_metadata::Request,
description = "User Id and queued song id", description = "Data needed to create the song and save it to the filesystem",
content_type = "application/json" content_type = "application/json"
), ),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Song created", body = super::response::create_metadata::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error", body = super::response::create_metadata::Response),
(status = 505, description = "Error creating song", body = super::response::create_metadata::Response)
) )
)] )]
pub async fn create_metadata( pub async fn create_metadata(
@@ -1275,17 +1279,18 @@ pub mod endpoint {
} }
} }
/// Endpoint to wipe the data from a queued song
#[utoipa::path( #[utoipa::path(
post, patch,
path = "/api/v2/song/queue/link", path = super::super::endpoints::QUEUESONGDATAWIPE,
request_body( request_body(
content = super::request::link_user_id::Request, content = super::request::wipe_data_from_song_queue::Request,
description = "User Id and queued song id", description = "Pass the queued song Id to wipe the data",
content_type = "application/json" content_type = "application/json"
), ),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Queued song data wiped", body = super::response::wipe_data_from_song_queue::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 404, description = "Queued song cannot be found", body = super::response::wipe_data_from_song_queue::Response)
) )
)] )]
pub async fn wipe_data_from_song_queue( pub async fn wipe_data_from_song_queue(
@@ -1318,19 +1323,17 @@ pub mod endpoint {
} }
} }
/*
#[utoipa::path( #[utoipa::path(
post, get,
path = "/api/v2/song/queue/link", path = super::super::endpoints::GETSONGS,
request_body( params(super::request::get_songs::Params),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Songs found", body = super::response::get_songs::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 400, description = "Error getting songs", body = super::response::get_songs::Response)
) )
)] )]
*/
pub async fn get_songs( pub async fn get_songs(
axum::Extension(pool): axum::Extension<sqlx::PgPool>, axum::Extension(pool): axum::Extension<sqlx::PgPool>,
axum::extract::Query(params): axum::extract::Query<super::request::get_songs::Params>, axum::extract::Query(params): axum::extract::Query<super::request::get_songs::Params>,
@@ -1359,17 +1362,13 @@ pub mod endpoint {
} }
} }
/// Endpoint to get all songs
#[utoipa::path( #[utoipa::path(
post, get,
path = "/api/v2/song/queue/link", path = super::super::endpoints::GETALLSONGS,
request_body(
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Getting all songs", body = super::response::get_songs::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 404, description = "Song not found", body = super::response::get_songs::Response)
) )
)] )]
pub async fn get_all_songs( pub async fn get_all_songs(
@@ -1393,17 +1392,14 @@ pub mod endpoint {
} }
} }
/// Ednpoint to stream song
#[utoipa::path( #[utoipa::path(
post, get,
path = "/api/v2/song/queue/link", path = super::super::endpoints::STREAMSONG,
request_body( params(("id" = uuid::Uuid, Path, description = "Song Id")),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Stream song", body = Vec<u8>),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 500, description = "Error streaming song", body = (u64, String))
) )
)] )]
pub async fn stream_song( pub async fn stream_song(
@@ -1453,17 +1449,15 @@ pub mod endpoint {
} }
} }
/// Endpoint to download song
#[utoipa::path( #[utoipa::path(
post, get,
path = "/api/v2/song/queue/link", path = super::super::endpoints::DOWNLOADSONG,
request_body( params(("id" = uuid::Uuid, Path, description = "Song Id")),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Download song", body = (u64, Vec<u8>)),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 404, description = "Song not found", body = (u64, Vec<u8>)),
(status = 400, description = "Error downloading song", body = (u64, Vec<u8>))
) )
)] )]
pub async fn download_song( pub async fn download_song(
@@ -1501,17 +1495,15 @@ pub mod endpoint {
} }
} }
/// Endpoint to delete the song
#[utoipa::path( #[utoipa::path(
post, delete,
path = "/api/v2/song/queue/link", path = super::super::endpoints::DELETESONG,
request_body( params(("id" = uuid::Uuid, Path, description = "Song Id")),
content = super::request::link_user_id::Request,
description = "User Id and queued song id",
content_type = "application/json"
),
responses( responses(
(status = 200, description = "Queued song linked", body = super::response::link_user_id::Response), (status = 200, description = "Song deleted", body = super::response::delete_song::Response),
(status = 400, description = "Linkage failed", body = super::response::link_user_id::Response) (status = 404, description = "Song not found", body = super::response::delete_song::Response),
(status = 500, description = "Error deleting song", body = super::response::delete_song::Response)
) )
)] )]
pub async fn delete_song( pub async fn delete_song(