//! Species domain endpoints: read-only access to the Species table. use axum::Json; use axum::extract::Path; use axum::http::StatusCode; use gnauth_macros::gnauth; use crate::auth::AuthToken; use crate::db; use crate::error::{ApiError, Unauthorized}; use crate::response::{Ctx, Envelope, path_segment}; #[utoipa::path(get, path = "/species", summary = "List all species in the database", responses( (status = 200, description = "All species in the database", body = Envelope>), Unauthorized, (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn species( ctx: Ctx, _token: AuthToken, ) -> Result>>, ApiError> { let rid = ctx.request_info(); // mysql's Conn is blocking; run it on a blocking thread so it doesn't // stall the async runtime. tokio::task::spawn_blocking(db::get_all_species) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "species", ) .with_request_id(rid.clone()) })? .map(|species| { // A `next` link has to be a call a client can make, so the // one-species link points at one of the species just listed // rather than at the `/species/{species}` template: the template // is a description, not an address, and following it verbatim is a // 404 (tests/envelope.rs walks every link it is offered). let example = species.first().map(|first| { ( format!("/species/{}", path_segment(&first.name)), format!( "One species' full record -- {} here; put any other name from the \ list in its place", first.name ), ) }); let mut envelope = ctx .envelope(species) .with_next( "/groups", "Groups (populations); add ?species= to list one species' groups", ) .with_links(crate::suggest::root_links()); if let Some((href, description)) = example { envelope = envelope.with_next(&href, &description); } Json(envelope) }) .map_err(|e| ApiError::from_db(e, "species").with_request_id(rid)) } #[utoipa::path(get, path = "/species/{species}", summary = "Get one species' full record by name", params( ("species" = String, Path, description = "Species Name, FullName or SpeciesName") ), responses( (status = 200, description = "The matching row of the Species table", body = Envelope), Unauthorized, (status = 404, description = "No matching species", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn species_by_name( ctx: Ctx, Path(species): Path, _token: AuthToken, ) -> Result>, ApiError> { let rid = ctx.request_info(); let not_found_name = species.clone(); tokio::task::spawn_blocking(move || db::get_species_by_name(&species)) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "species_by_name", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "species_by_name").with_request_id(rid.clone()))? .map(|detail| { let name = path_segment(&detail.name); Json( ctx.envelope(detail) .with_next( &format!("/species/{name}/datasets"), "Expression datasets of this species", ) .with_next(&format!("/groups?species={name}"), "Groups of this species") .with_links(crate::suggest::root_links()), ) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "species_not_found", "Species not found", format!("No species matching '{not_found_name}'."), "species_by_name", ) .with_request_id(rid) .with_next("/species") }) } #[utoipa::path(get, path = "/species/{species}/datasets", summary = "List the expression (ProbeSet) datasets belonging to a species", params( ("species" = String, Path, description = "Species Name, FullName or SpeciesName") ), responses( (status = 200, description = "The expression (ProbeSet) datasets belonging to the species", body = Envelope>), Unauthorized, (status = 404, description = "No matching species", body = ApiError), (status = 500, description = "Database error", body = ApiError) ))] #[gnauth(token_only)] pub async fn species_datasets( ctx: Ctx, Path(species): Path, _token: AuthToken, ) -> Result>>, ApiError> { let rid = ctx.request_info(); let not_found_name = species.clone(); tokio::task::spawn_blocking(move || { db::get_species_by_name(&species).and_then(|species| match species { Some(species) => db::get_species_datasets(species.id).map(Some), None => Ok(None), }) }) .await .map_err(|e| { ApiError::new( StatusCode::INTERNAL_SERVER_ERROR, "internal_error", "Internal error", e.to_string(), "species_datasets", ) .with_request_id(rid.clone()) })? .map_err(|e| ApiError::from_db(e, "species_datasets").with_request_id(rid.clone()))? .map(|datasets| { // One real dataset of this species, for the reason given in // `/species`: a template is a shape, not an address a client can // follow. let example = datasets.first().map(|dataset| { ( format!("/datasets/{}", path_segment(&dataset.name)), format!( "One dataset's record -- {} here; put any other name from \ the list in its place", dataset.name ), ) }); let mut envelope = ctx .envelope(datasets) .with_next( &format!("/species/{}", path_segment(¬_found_name)), "The species these datasets belong to", ) .with_links(crate::suggest::root_links()); if let Some((href, description)) = example { envelope = envelope.with_next(&href, &description); } Json(envelope) }) .ok_or_else(|| { ApiError::new( StatusCode::NOT_FOUND, "species_not_found", "Species not found", format!("No species matching '{not_found_name}'."), "species_datasets", ) .with_request_id(rid) .with_next("/species") }) }