Skip to content
1        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;19/// Upper bound for a whole JSON body; leaves room for escaping and metadata around content.20pub 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}118119/// A new item needs some text or a title. Pictures and files are attached afterwards.120fn 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}142143/// Reads `q`, `tag`, `sort`, `order`, `limit`, `offset`, and any number of `meta.<key>=<value>`144/// filters. Unrecognised parameters are ignored.145fn 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(&params)?;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}350351/// Collects a raw request body, refusing anything over the per-file limit while reading.352async 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}369370/// Uploads one file as the raw request body. The file type is detected from its bytes;371/// `?filename=` sets the name it is shown and downloaded under.372async 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}420421/// Serves stored bytes. Only sniffed images display inline; everything else downloads.422/// `nosniff` stops browsers from second-guessing the type.423pub 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}