LINE1 10 20 30 40 50 60 70 80 901use std::collections::HashMap;2use std::fmt::{self, Display, Formatter};34use actix_web::http::StatusCode;5use actix_web::{HttpResponse, ResponseError, web};6use futures_util::StreamExt;7use serde::Deserialize;8use serde_json::{Value, json};910use crate::attachments::{self, AttachmentInfo, MAX_ATTACHMENT_BYTES};11use crate::auth::{Principal, Scope};12use crate::db::Db;13use crate::items::{14 self, Item, ListQuery, Sort, TagCount, check_metadata, normalize_tag, normalize_tags,15};16use crate::tokens;1718pub const MAX_CONTENT_BYTES: usize = 10 * 1024 * 1024;1920pub const MAX_BODY_BYTES: usize = 16 * 1024 * 1024;21const DEFAULT_LIMIT: i64 = 50;22const MAX_LIMIT: i64 = 200;2324#[derive(Debug)]25pub enum ApiError {26 Unauthorized,27 Forbidden,28 NotFound,29 BadRequest(String),30 TooLarge(String),31 Internal(anyhow::Error),32}3334impl ApiError {35 fn message(&self) -> String {36 match self {37 Self::Unauthorized => "missing or invalid access token".to_string(),38 Self::Forbidden => "this token does not have the required scope".to_string(),39 Self::NotFound => "not found".to_string(),40 Self::BadRequest(message) | Self::TooLarge(message) => message.clone(),41 Self::Internal(_) => "internal server error".to_string(),42 }43 }44}4546impl From<anyhow::Error> for ApiError {47 fn from(error: anyhow::Error) -> Self {48 Self::Internal(error)49 }50}5152impl Display for ApiError {53 fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {54 formatter.write_str(&self.message())55 }56}5758impl ResponseError for ApiError {59 fn status_code(&self) -> StatusCode {60 match self {61 Self::Unauthorized => StatusCode::UNAUTHORIZED,62 Self::Forbidden => StatusCode::FORBIDDEN,63 Self::NotFound => StatusCode::NOT_FOUND,64 Self::BadRequest(_) => StatusCode::BAD_REQUEST,65 Self::TooLarge(_) => StatusCode::PAYLOAD_TOO_LARGE,66 Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,67 }68 }6970 fn error_response(&self) -> HttpResponse {71 if let Self::Internal(error) = self {72 log::error!("{error:#}");73 }74 HttpResponse::build(self.status_code()).json(json!({ "error": self.message() }))75 }76}7778pub fn configure(config: &mut web::ServiceConfig) {79 config.service(80 web::scope("/api/v1")81 .route("/me", web::get().to(me))82 .route("/items", web::get().to(list_items))83 .route("/items", web::post().to(create_item))84 .route("/items/{id}", web::get().to(get_item))85 .route("/items/{id}", web::patch().to(update_item))86 .route("/items/{id}", web::delete().to(delete_item))87 .route("/items/{id}/tags", web::post().to(add_tags))88 .route("/items/{id}/tags/{tag}", web::delete().to(remove_tag))89 .route("/items/{id}/attachments", web::post().to(upload_attachment))90 .route("/attachments/{id}", web::get().to(download_attachment))91 .route("/attachments/{id}", web::delete().to(delete_attachment))92 .route("/tags", web::get().to(list_tags))93 .route("/tokens", web::get().to(list_tokens)),94 );95}9697fn require(principal: &Principal, scope: Scope) -> Result<(), ApiError> {98 if principal.allows(scope) {99 Ok(())100 } else {101 Err(ApiError::Forbidden)102 }103}104105fn validate_content(content: &str) -> Result<(), ApiError> {106 if content.trim().is_empty() {107 return Err(ApiError::BadRequest(108 "content must not be empty".to_string(),109 ));110 }111 if content.len() > MAX_CONTENT_BYTES {112 return Err(ApiError::TooLarge(format!(113 "content is limited to {MAX_CONTENT_BYTES} bytes"114 )));115 }116 Ok(())117}118119120fn validate_new_item(title: &str, content: &str) -> Result<(), ApiError> {121 if title.trim().is_empty() && content.trim().is_empty() {122 return Err(ApiError::BadRequest(123 "give content or a title; files can be attached with POST /items/{id}/attachments"124 .to_string(),125 ));126 }127 if content.len() > MAX_CONTENT_BYTES {128 return Err(ApiError::TooLarge(format!(129 "content is limited to {MAX_CONTENT_BYTES} bytes"130 )));131 }132 Ok(())133}134135fn bad_request(message: String) -> ApiError {136 ApiError::BadRequest(message)137}138139async fn me(principal: Principal) -> web::Json<Principal> {140 web::Json(principal)141}142143144145fn list_query(params: &HashMap<String, String>) -> Result<ListQuery, ApiError> {146 let sort = params147 .get("sort")148 .map(|value| {149 Sort::parse(value).ok_or_else(|| {150 bad_request(format!(151 "unknown sort {value:?}; use relevance, created, updated or title"152 ))153 })154 })155 .transpose()?;156 let tag = params157 .get("tag")158 .map(|tag| normalize_tag(tag))159 .transpose()160 .map_err(bad_request)?;161 let ascending = match params.get("order").map(String::as_str) {162 None | Some("desc") => false,163 Some("asc") => true,164 Some(other) => {165 return Err(bad_request(format!(166 "unknown order {other:?}; use asc or desc"167 )));168 }169 };170 let number = |name: &str, default: i64| -> Result<i64, ApiError> {171 params.get(name).map_or(Ok(default), |value| {172 value173 .parse::<i64>()174 .map_err(|_| bad_request(format!("{name} must be a whole number")))175 })176 };177 let mut metadata = Vec::new();178 for (key, value) in params {179 if let Some(name) = key.strip_prefix("meta.") {180 if !items::valid_metadata_key(name) {181 return Err(bad_request(format!(182 "metadata key {name:?} may only contain letters, digits, '_' and '-'"183 )));184 }185 metadata.push((name.to_string(), value.clone()));186 }187 }188 metadata.sort();189 Ok(ListQuery {190 q: params.get("q").filter(|q| !q.trim().is_empty()).cloned(),191 tag,192 metadata,193 sort,194 ascending,195 limit: number("limit", DEFAULT_LIMIT)?.clamp(1, MAX_LIMIT),196 offset: number("offset", 0)?.max(0),197 })198}199200async fn list_items(201 principal: Principal,202 db: web::Data<Db>,203 params: web::Query<HashMap<String, String>>,204) -> Result<web::Json<Vec<Item>>, ApiError> {205 require(&principal, Scope::Read)?;206 let query = list_query(¶ms)?;207 let items = db.call(move |conn| items::list(conn, &query)).await?;208 Ok(web::Json(items))209}210211#[derive(Debug, Deserialize)]212struct CreateItem {213 #[serde(default)]214 title: String,215 #[serde(default)]216 content: String,217 #[serde(default)]218 tags: Vec<String>,219 metadata: Option<Value>,220}221222async fn create_item(223 principal: Principal,224 db: web::Data<Db>,225 body: web::Json<CreateItem>,226) -> Result<HttpResponse, ApiError> {227 require(&principal, Scope::Write)?;228 let CreateItem {229 title,230 content,231 tags,232 metadata,233 } = body.into_inner();234 validate_new_item(&title, &content)?;235 let tags = normalize_tags(&tags).map_err(bad_request)?;236 let metadata = metadata.unwrap_or_else(|| json!({}));237 check_metadata(&metadata).map_err(bad_request)?;238 let item = db239 .call(move |conn| items::create(conn, &title, &content, &tags, &metadata))240 .await?;241 Ok(HttpResponse::Created().json(item))242}243244async fn get_item(245 principal: Principal,246 db: web::Data<Db>,247 path: web::Path<String>,248) -> Result<web::Json<Item>, ApiError> {249 require(&principal, Scope::Read)?;250 let id = path.into_inner();251 let item = db252 .call(move |conn| items::get(conn, &id))253 .await?254 .ok_or(ApiError::NotFound)?;255 Ok(web::Json(item))256}257258#[derive(Debug, Deserialize)]259struct UpdateItem {260 title: Option<String>,261 content: Option<String>,262 metadata: Option<Value>,263}264265async fn update_item(266 principal: Principal,267 db: web::Data<Db>,268 path: web::Path<String>,269 body: web::Json<UpdateItem>,270) -> Result<web::Json<Item>, ApiError> {271 require(&principal, Scope::Write)?;272 let id = path.into_inner();273 let UpdateItem {274 title,275 content,276 metadata,277 } = body.into_inner();278 if let Some(content) = &content {279 validate_content(content)?;280 }281 if let Some(metadata) = &metadata {282 check_metadata(metadata).map_err(bad_request)?;283 }284 let item = db285 .call(move |conn| {286 items::update(287 conn,288 &id,289 title.as_deref(),290 content.as_deref(),291 metadata.as_ref(),292 )293 })294 .await?295 .ok_or(ApiError::NotFound)?;296 Ok(web::Json(item))297}298299async fn delete_item(300 principal: Principal,301 db: web::Data<Db>,302 path: web::Path<String>,303) -> Result<HttpResponse, ApiError> {304 require(&principal, Scope::Write)?;305 let id = path.into_inner();306 if !db.call(move |conn| items::delete(conn, &id)).await? {307 return Err(ApiError::NotFound);308 }309 Ok(HttpResponse::NoContent().finish())310}311312#[derive(Debug, Deserialize)]313struct TagsBody {314 tags: Vec<String>,315}316317async fn add_tags(318 principal: Principal,319 db: web::Data<Db>,320 path: web::Path<String>,321 body: web::Json<TagsBody>,322) -> Result<web::Json<Item>, ApiError> {323 require(&principal, Scope::Write)?;324 let id = path.into_inner();325 let tags = normalize_tags(&body.into_inner().tags).map_err(bad_request)?;326 if tags.is_empty() {327 return Err(bad_request("no tags given".to_string()));328 }329 let item = db330 .call(move |conn| items::add_tags(conn, &id, &tags))331 .await?332 .ok_or(ApiError::NotFound)?;333 Ok(web::Json(item))334}335336async fn remove_tag(337 principal: Principal,338 db: web::Data<Db>,339 path: web::Path<(String, String)>,340) -> Result<web::Json<Item>, ApiError> {341 require(&principal, Scope::Write)?;342 let (id, tag) = path.into_inner();343 let tag = normalize_tag(&tag).map_err(bad_request)?;344 let item = db345 .call(move |conn| items::remove_tag(conn, &id, &tag))346 .await?347 .ok_or(ApiError::NotFound)?;348 Ok(web::Json(item))349}350351352async fn read_upload(mut payload: web::Payload) -> Result<Vec<u8>, ApiError> {353 let mut data = Vec::new();354 while let Some(chunk) = payload.next().await {355 let chunk =356 chunk.map_err(|error| bad_request(format!("could not read upload: {error}")))?;357 if data.len() + chunk.len() > MAX_ATTACHMENT_BYTES {358 return Err(ApiError::TooLarge(format!(359 "files are limited to {MAX_ATTACHMENT_BYTES} bytes"360 )));361 }362 data.extend_from_slice(&chunk);363 }364 if data.is_empty() {365 return Err(bad_request("the file is empty".to_string()));366 }367 Ok(data)368}369370371372async fn upload_attachment(373 principal: Principal,374 db: web::Data<Db>,375 path: web::Path<String>,376 query: web::Query<HashMap<String, String>>,377 payload: web::Payload,378) -> Result<HttpResponse, ApiError> {379 require(&principal, Scope::Write)?;380 let id = path.into_inner();381 let filename = query382 .get("filename")383 .cloned()384 .unwrap_or_else(|| "attachment".to_string());385 let data = read_upload(payload).await?;386 let info: AttachmentInfo = db387 .call(move |conn| attachments::add(conn, &id, &filename, &data))388 .await?389 .ok_or(ApiError::NotFound)?;390 Ok(HttpResponse::Created().json(info))391}392393async fn download_attachment(394 principal: Principal,395 db: web::Data<Db>,396 path: web::Path<String>,397) -> Result<HttpResponse, ApiError> {398 require(&principal, Scope::Read)?;399 let id = path.into_inner();400 let attachment = db401 .call(move |conn| attachments::get(conn, &id))402 .await?403 .ok_or(ApiError::NotFound)?;404 Ok(file_response(attachment))405}406407async fn delete_attachment(408 principal: Principal,409 db: web::Data<Db>,410 path: web::Path<String>,411) -> Result<HttpResponse, ApiError> {412 require(&principal, Scope::Write)?;413 let id = path.into_inner();414 let removed = db.call(move |conn| attachments::delete(conn, &id)).await?;415 if removed.is_none() {416 return Err(ApiError::NotFound);417 }418 Ok(HttpResponse::NoContent().finish())419}420421422423pub fn file_response(attachment: attachments::Attachment) -> HttpResponse {424 let disposition = if attachments::is_inline(&attachment.info.mime) {425 "inline"426 } else {427 "attachment"428 };429 HttpResponse::Ok()430 .content_type(attachment.info.mime.as_str())431 .insert_header(("ETag", format!("\"{}\"", attachment.info.sha256)))432 .insert_header(("X-Content-Type-Options", "nosniff"))433 .insert_header((434 "Content-Disposition",435 format!("{disposition}; filename=\"{}\"", attachment.info.filename),436 ))437 .body(attachment.data)438}439440async fn list_tags(441 principal: Principal,442 db: web::Data<Db>,443) -> Result<web::Json<Vec<TagCount>>, ApiError> {444 require(&principal, Scope::Read)?;445 let tags = db.call(|conn| items::list_tags(conn)).await?;446 Ok(web::Json(tags))447}448449async fn list_tokens(450 principal: Principal,451 db: web::Data<Db>,452) -> Result<web::Json<Vec<tokens::TokenInfo>>, ApiError> {453 require(&principal, Scope::Write)?;454 let tokens = db.call(|conn| tokens::list(conn)).await?;455 Ok(web::Json(tokens))456}457458#[cfg(test)]459mod tests {460 use actix_web::{App, test};461 use serde_json::{Value, json};462463 use super::*;464 use crate::db::open_in_memory;465466 async fn setup() -> (Db, String, String) {467 let db = Db::new(open_in_memory().unwrap());468 let writer = db469 .call(|conn| tokens::create(conn, "writer", &[Scope::Read, Scope::Write]))470 .await471 .unwrap();472 let reader = db473 .call(|conn| tokens::create(conn, "reader", &[Scope::Read]))474 .await475 .unwrap();476 (db, writer.secret, reader.secret)477 }478479 fn bearer(secret: &str) -> (&'static str, String) {480 ("Authorization", format!("Bearer {secret}"))481 }482483 #[actix_web::test]484 async fn items_are_created_searched_changed_and_deleted_with_scopes() {485 let (db, writer, reader) = setup().await;486 let app =487 test::init_service(App::new().app_data(web::Data::new(db)).configure(configure)).await;488489 let unauthenticated = test::call_service(490 &app,491 test::TestRequest::get().uri("/api/v1/items").to_request(),492 )493 .await;494 assert_eq!(unauthenticated.status(), StatusCode::UNAUTHORIZED);495496 let read_only_write = test::call_service(497 &app,498 test::TestRequest::post()499 .uri("/api/v1/items")500 .insert_header(bearer(&reader))501 .set_json(json!({ "content": "nope" }))502 .to_request(),503 )504 .await;505 assert_eq!(read_only_write.status(), StatusCode::FORBIDDEN);506507 let created = test::call_service(508 &app,509 test::TestRequest::post()510 .uri("/api/v1/items")511 .insert_header(bearer(&writer))512 .set_json(json!({513 "content": "Borrow checker notes\nlifetimes",514 "tags": ["Rust"],515 "metadata": { "source": "slack" }516 }))517 .to_request(),518 )519 .await;520 assert_eq!(created.status(), StatusCode::CREATED);521 let item: Value = test::read_body_json(created).await;522 let id = item["id"].as_str().unwrap().to_string();523 assert_eq!(item["title"], "Borrow checker notes");524 assert_eq!(item["tags"], json!(["rust"]));525 assert_eq!(item["metadata"], json!({ "source": "slack" }));526527 let searched: Value = test::call_and_read_body_json(528 &app,529 test::TestRequest::get()530 .uri("/api/v1/items?q=lifetim&tag=rust&meta.source=slack")531 .insert_header(bearer(&reader))532 .to_request(),533 )534 .await;535 assert_eq!(searched.as_array().unwrap().len(), 1);536537 let tagged: Value = test::call_and_read_body_json(538 &app,539 test::TestRequest::post()540 .uri(&format!("/api/v1/items/{id}/tags"))541 .insert_header(bearer(&writer))542 .set_json(json!({ "tags": ["Reference"] }))543 .to_request(),544 )545 .await;546 assert_eq!(tagged["tags"], json!(["reference", "rust"]));547548 let patched: Value = test::call_and_read_body_json(549 &app,550 test::TestRequest::patch()551 .uri(&format!("/api/v1/items/{id}"))552 .insert_header(bearer(&writer))553 .set_json(json!({ "content": "rewritten" }))554 .to_request(),555 )556 .await;557 assert_eq!(patched["content"], "rewritten");558559 let deleted = test::call_service(560 &app,561 test::TestRequest::delete()562 .uri(&format!("/api/v1/items/{id}"))563 .insert_header(bearer(&writer))564 .to_request(),565 )566 .await;567 assert_eq!(deleted.status(), StatusCode::NO_CONTENT);568569 let gone = test::call_service(570 &app,571 test::TestRequest::get()572 .uri(&format!("/api/v1/items/{id}"))573 .insert_header(bearer(&reader))574 .to_request(),575 )576 .await;577 assert_eq!(gone.status(), StatusCode::NOT_FOUND);578 }579580 #[actix_web::test]581 async fn pictures_are_uploaded_served_and_removed() {582 let (db, writer, reader) = setup().await;583 let app =584 test::init_service(App::new().app_data(web::Data::new(db)).configure(configure)).await;585586 let item: Value = test::call_and_read_body_json(587 &app,588 test::TestRequest::post()589 .uri("/api/v1/items")590 .insert_header(bearer(&writer))591 .set_json(json!({ "title": "Holiday" }))592 .to_request(),593 )594 .await;595 let item_id = item["id"].as_str().unwrap().to_string();596597 let png = b"\x89PNG\r\n\x1a\n\0\0\0pixels".to_vec();598 let uploaded: Value = test::call_and_read_body_json(599 &app,600 test::TestRequest::post()601 .uri(&format!(602 "/api/v1/items/{item_id}/attachments?filename=../beach.png"603 ))604 .insert_header(bearer(&writer))605 .set_payload(png.clone())606 .to_request(),607 )608 .await;609 assert_eq!(uploaded["filename"], "beach.png");610 assert_eq!(uploaded["mime"], "image/png");611 let attachment_id = uploaded["id"].as_str().unwrap().to_string();612613 let shown = test::call_service(614 &app,615 test::TestRequest::get()616 .uri(&format!("/api/v1/attachments/{attachment_id}"))617 .insert_header(bearer(&reader))618 .to_request(),619 )620 .await;621 assert_eq!(shown.status(), StatusCode::OK);622 assert_eq!(shown.headers().get("content-type").unwrap(), "image/png");623 assert_eq!(624 shown.headers().get("content-disposition").unwrap(),625 "inline; filename=\"beach.png\""626 );627 assert_eq!(test::read_body(shown).await.to_vec(), png);628629 let item: Value = test::call_and_read_body_json(630 &app,631 test::TestRequest::get()632 .uri(&format!("/api/v1/items/{item_id}"))633 .insert_header(bearer(&reader))634 .to_request(),635 )636 .await;637 assert_eq!(item["attachments"][0]["filename"], "beach.png");638639 let removed = test::call_service(640 &app,641 test::TestRequest::delete()642 .uri(&format!("/api/v1/attachments/{attachment_id}"))643 .insert_header(bearer(&writer))644 .to_request(),645 )646 .await;647 assert_eq!(removed.status(), StatusCode::NO_CONTENT);648 }649650 #[actix_web::test]651 async fn html_uploads_download_instead_of_rendering() {652 let (db, writer, _reader) = setup().await;653 let app =654 test::init_service(App::new().app_data(web::Data::new(db)).configure(configure)).await;655 let item: Value = test::call_and_read_body_json(656 &app,657 test::TestRequest::post()658 .uri("/api/v1/items")659 .insert_header(bearer(&writer))660 .set_json(json!({ "content": "x" }))661 .to_request(),662 )663 .await;664 let item_id = item["id"].as_str().unwrap();665 let uploaded: Value = test::call_and_read_body_json(666 &app,667 test::TestRequest::post()668 .uri(&format!(669 "/api/v1/items/{item_id}/attachments?filename=page.html"670 ))671 .insert_header(bearer(&writer))672 .set_payload("<script>alert(1)</script>")673 .to_request(),674 )675 .await;676 assert_eq!(uploaded["mime"], "application/octet-stream");677 let shown = test::call_service(678 &app,679 test::TestRequest::get()680 .uri(&format!(681 "/api/v1/attachments/{}",682 uploaded["id"].as_str().unwrap()683 ))684 .insert_header(bearer(&writer))685 .to_request(),686 )687 .await;688 assert!(689 shown690 .headers()691 .get("content-disposition")692 .unwrap()693 .to_str()694 .unwrap()695 .starts_with("attachment;")696 );697 assert_eq!(698 shown.headers().get("x-content-type-options").unwrap(),699 "nosniff"700 );701 }702703 #[actix_web::test]704 async fn items_need_text_or_a_title_and_metadata_must_be_an_object() {705 let (db, writer, _reader) = setup().await;706 let app =707 test::init_service(App::new().app_data(web::Data::new(db)).configure(configure)).await;708 let empty = test::call_service(709 &app,710 test::TestRequest::post()711 .uri("/api/v1/items")712 .insert_header(bearer(&writer))713 .set_json(json!({ "content": " " }))714 .to_request(),715 )716 .await;717 assert_eq!(empty.status(), StatusCode::BAD_REQUEST);718719 let not_object = test::call_service(720 &app,721 test::TestRequest::post()722 .uri("/api/v1/items")723 .insert_header(bearer(&writer))724 .set_json(json!({ "content": "x", "metadata": [1] }))725 .to_request(),726 )727 .await;728 assert_eq!(not_object.status(), StatusCode::BAD_REQUEST);729730 let bad_key = test::call_service(731 &app,732 test::TestRequest::get()733 .uri("/api/v1/items?meta.bad%20key=x")734 .insert_header(bearer(&writer))735 .to_request(),736 )737 .await;738 assert_eq!(bad_key.status(), StatusCode::BAD_REQUEST);739 }740741 #[actix_web::test]742 async fn me_reports_the_token_identity() {743 let (db, _writer, reader) = setup().await;744 let app =745 test::init_service(App::new().app_data(web::Data::new(db)).configure(configure)).await;746 let me: Value = test::call_and_read_body_json(747 &app,748 test::TestRequest::get()749 .uri("/api/v1/me")750 .insert_header(bearer(&reader))751 .to_request(),752 )753 .await;754 assert_eq!(me["name"], "reader");755 assert_eq!(me["scopes"], json!(["read"]));756 }757}