Drops are forked, starred and commented over the API, and with oh drop fork/star/unstar/comments/comment (closes #349) 04f9c984439e

## Unreleased

- **Drops over the API: fork, star and comment (#349).** What a drop's page does, for the VS Code extension and other clients: `POST /api/v1/drops/{id}/fork`, `PUT`/`DELETE /api/v1/drops/{id}/star`, `GET`/`POST /api/v1/drops/{id}/comments` and `DELETE /api/v1/drops/{id}/comments/{n}`, by the web's rules (the owner told of a comment; its author, the owner or an administrator deletes it). A drop over the API now says its stars, whether you starred it, what it was forked from and its embed address. `oh drop fork|star|unstar|comments|comment`.

    /// How many have starred it, and whether the caller has (oxygenhub#349).

    #[serde(default)]

    pub stars: i64,

    #[serde(default)]

    pub starred: bool,

    /// The drop it was forked from, its page, while that drop exists.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub forked_from: Option<String>,

    /// Its files without the site around them, for an `<iframe>` (#280).

    #[serde(default)]

    pub embed_url: String,

}

/// A comment on a drop (oxygenhub#349).

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct DropComment {

    /// Its number on the drop.

    pub id: i64,

    pub author: String,

    /// Markdown.

    pub body: String,

    pub created_ms: i64,

}

/// `POST /drops/{id}/comments`.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct NewDropComment {

    pub body: String,

}

/// A drop's stars after `PUT` or `DELETE /drops/{id}/star`.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct DropStars {

    pub stars: i64,

    pub starred: bool,

        ("DropComment", schemars::schema_for!(DropComment)),

        ("NewDropComment", schemars::schema_for!(NewDropComment)),

        ("DropStars", schemars::schema_for!(DropStars)),

//! administrator, who may also delete it). Forking, starring and comments

//! (oxygenhub#349) need `repo:write` and an account, as on the web.

use hub_api::{Drop, DropComment, DropEdit, DropStars, NewDrop, NewDropComment};

/// The API's shape of a drop, with its files' content when `content`, its

/// stars (and whether `caller` starred it) and where it was forked from.

async fn shape(

    app: &Shared,

    caller: Option<&db::accounts::Account>,

    row: &db::repos::RepoRow,

    files: &[DropFile],

    content: bool,

) -> Result<Drop, ApiError> {

    let starred = match caller {

        Some(a) => db::repos::starred(&app.db, a.id, row.id).await?,

        None => false,

    };

    let forked_from = match row.forked_from {

        Some(id) => db::repos::get_by_id(&app.db, id).await?.map(|f| format!("{base}{}", drops::url_of(&f))),

        None => None,

    };

    Ok(Drop {

        stars: db::repos::star_count(&app.db, row.id).await?,

        starred,

        forked_from,

        embed_url: format!("{base}{url}/embed"),

    })

async fn listed(app: &Shared, caller: Option<&db::accounts::Account>, rows: Vec<db::repos::RepoRow>) -> Result<Vec<Drop>, ApiError> {

        out.push(shape(app, caller, &row, &files, false).await?);

    Ok(Json(listed(&app, Some(&me), rows).await?))

    Ok(Json(listed(&app, c.account.as_ref(), rows).await?))

    Ok((StatusCode::CREATED, Json(shape(&app, Some(&me), &row, &files, true).await?)))

    Ok(Json(shape(&app, c.account.as_ref(), &row, &files, true).await?))

    Ok(Json(shape(&app, Some(&me), &row, &files, true).await?))

    Ok(StatusCode::NO_CONTENT)

}

/// The drop and the signed-in caller, with `repo:write`, for forking,

/// starring and commenting: anyone who may read the drop (its id) may.

async fn reader(app: &Shared, headers: &HeaderMap, id: &str) -> Result<(db::accounts::Account, db::repos::RepoRow), ApiError> {

    let c = caller(app, headers).await?;

    let me = c.require("repo:write")?.clone();

    if me.blocked() {

        return Err(not_found("no such drop"));

    }

    Ok((me, row_of(app, id).await?))

}

/// `POST /drops/{id}/fork` (oxygenhub#349): a new drop of the caller's

/// whose history starts from this one, as the page's FORK.

pub(super) async fn fork(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(id): Path<String>,

) -> Result<(StatusCode, Json<Drop>), ApiError> {

    let (me, row) = reader(&app, &headers, &id).await?;

    let made = drops::fork(&app, &me, &row).await?;

    let (_, files) = drops::files(&app, &made, "").await?;

    Ok((StatusCode::CREATED, Json(shape(&app, Some(&me), &made, &files, true).await?)))

}

/// `PUT /drops/{id}/star` stars the drop, `DELETE` takes the star back;

/// either is the same however often it is asked.

async fn set_star(app: &Shared, headers: &HeaderMap, id: &str, want: bool) -> Result<Json<DropStars>, ApiError> {

    let (me, row) = reader(app, headers, id).await?;

    if db::repos::starred(&app.db, me.id, row.id).await? != want {

        db::repos::toggle_star(&app.db, me.id, row.id).await?;

    }

    Ok(Json(DropStars { stars: db::repos::star_count(&app.db, row.id).await?, starred: want }))

}

pub(super) async fn star(State(app): State<Shared>, headers: HeaderMap, Path(id): Path<String>) -> Result<Json<DropStars>, ApiError> {

    set_star(&app, &headers, &id, true).await

}

pub(super) async fn unstar(State(app): State<Shared>, headers: HeaderMap, Path(id): Path<String>) -> Result<Json<DropStars>, ApiError> {

    set_star(&app, &headers, &id, false).await

}

fn comment_of(c: db::repos::DropComment) -> DropComment {

    DropComment { id: c.id, author: c.author, body: c.body, created_ms: c.created_ms }

}

/// `GET /drops/{id}/comments`: oldest first, to anyone with the id.

pub(super) async fn comments(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(id): Path<String>,

) -> Result<Json<Vec<DropComment>>, ApiError> {

    let c = caller(&app, &headers).await?;

    if c.account.as_ref().is_some_and(|a| a.blocked()) {

        return Err(not_found("no such drop"));

    }

    let row = row_of(&app, &id).await?;

    Ok(Json(db::repos::drop_comments(&app.db, row.id).await?.into_iter().map(comment_of).collect()))

}

/// `POST /drops/{id}/comments`: the drop's owner is told.

pub(super) async fn add_comment(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(id): Path<String>,

    Json(body): Json<NewDropComment>,

) -> Result<(StatusCode, Json<DropComment>), ApiError> {

    let (me, row) = reader(&app, &headers, &id).await?;

    let n = drops::add_comment(&app, &me, &row, &body.body).await?;

    let c = db::repos::drop_comment(&app.db, row.id, n).await?.ok_or_else(|| not_found("no such comment"))?;

    Ok((StatusCode::CREATED, Json(comment_of(c))))

}

/// `DELETE /drops/{id}/comments/{n}`: its author, the drop's owner or a

/// site administrator.

pub(super) async fn delete_comment(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((id, n)): Path<(String, i64)>,

) -> Result<StatusCode, ApiError> {

    let (me, row) = reader(&app, &headers, &id).await?;

    let c = db::repos::drop_comment(&app.db, row.id, n).await?.ok_or_else(|| not_found("no such comment"))?;

    if !drops::may_delete_comment(Some(&me), &row, &c) {

        return Err(super::forbidden("only the comment's author, the drop's owner or a site administrator may delete it"));

    }

    db::repos::delete_drop_comment(&app.db, row.id, n).await?;

        .route("/drops/{id}/fork", post(drops::fork))

        .route("/drops/{id}/star", axum::routing::put(drops::star).delete(drops::unstar))

        .route("/drops/{id}/comments", get(drops::comments).post(drops::add_comment))

        .route("/drops/{id}/comments/{n}", axum::routing::delete(drops::delete_comment))

/// How many have starred one repository.

pub async fn star_count(pool: &Pool, repo_id: i64) -> sqlx::Result<i64> {

    sqlx::query_scalar("SELECT COUNT(*) FROM stars WHERE repo_id = $1").bind(repo_id).fetch_one(pool).await

}

/// The longest comment on a drop, in bytes.

pub const COMMENT_MAX: usize = 64 * 1024;

/// `account` comments on `row` (#280, oxygenhub#349): some Markdown, at most

/// [`COMMENT_MAX`]; the drop's owner is told. The comment's number.

pub async fn add_comment(app: &Shared, account: &Account, row: &RepoRow, body: &str) -> Result<i64, DropError> {

    let body = body.trim();

    if body.is_empty() || body.len() > COMMENT_MAX || account.blocked() {

        return Err(bad("A comment is some text, at most 64 KiB."));

    }

    let n = db::repos::add_drop_comment(&app.db, row.id, account.id, &account.username, body).await?;

    if account.username != row.owner {

        if let Ok(Some(owner)) = db::accounts::account_by_name(&app.db, &row.owner).await {

            let title = format!("{} on your drop {}", account.username, shown_title(row, &[]));

            crate::notify::tell(

                app,

                "drop.comment",

                &title,

                &format!("{}#comment-{n}", url_of(row)),

                &account.username,

                Some(row.id),

                vec![(owner.id, db::notify::Reason::Participating)],

            )

            .await;

        }

    }

    Ok(n)

}

/// Whether `account` may delete comment `c` on `row`: its author, the

/// drop's owner or a site administrator.

pub fn may_delete_comment(account: Option<&Account>, row: &RepoRow, c: &db::repos::DropComment) -> bool {

    account.is_some_and(|a| !a.blocked() && (Some(a.id) == c.author_id || a.username == row.owner || a.is_admin))

}

    drops::may_delete_comment(viewer.account(), row, c)

    let n = drops::add_comment(&app, &me.account, &row, &f.body).await.map_err(|e| Error::bad(shell.clone(), e.to_string()))?;

/// oxygenhub#349: forking, stars and comments over the API, by the web's

/// rules, for the extensions.

#[tokio::test(flavor = "multi_thread")]

async fn drops_are_forked_starred_and_commented_over_the_api() {

    let h = hub().await;

    let app = &h.app;

    register(app, "andy").await;

    register(app, "carol").await;

    register(app, "dave").await;

    let (andy, carol, dave) = (token(app, "andy").await, token(app, "carol").await, token(app, "dave").await);

    let work = tempfile::tempdir().unwrap();

    delegate(app, "carol", work.path()).await;

    let new = serde_json::json!({ "title": "Notes", "description": "", "secret": false, "files": [{ "name": "a.txt", "content": "a" }] });

    let r = api(app, "POST", "/drops", Some(&carol), Some(new)).await;

    assert_eq!(r.status, StatusCode::CREATED, "{}", r.body);

    let source: hub_api::Drop = serde_json::from_str(&r.body).unwrap();

    assert!(source.embed_url.ends_with(&format!("/carol/drops/{}/embed", source.id)) && source.stars == 0);

    // A fork is the caller's, from the source.

    let r = api(app, "POST", &format!("/drops/{}/fork", source.id), Some(&andy), None).await;

    assert_eq!(r.status, StatusCode::CREATED, "{}", r.body);

    let fork: hub_api::Drop = serde_json::from_str(&r.body).unwrap();

    assert_eq!((fork.owner.as_str(), fork.title.as_str()), ("andy", "Notes"));

    assert_eq!(fork.forked_from.as_deref(), Some(source.url.as_str()));

    assert_eq!(fork.files[0].content.as_deref(), Some("a"));

    assert_eq!(api(app, "POST", &format!("/drops/{}/fork", source.id), None, None).await.status, StatusCode::UNAUTHORIZED);

    // Stars: PUT stars, again changes nothing, DELETE takes it back.

    let stars = |tok: String, method: &'static str| {

        let (app, id) = (app.clone(), source.id.clone());

        async move {

            let r = api(&app, method, &format!("/drops/{id}/star"), Some(&tok), None).await;

            assert_eq!(r.status, StatusCode::OK, "{}", r.body);

            serde_json::from_str::<hub_api::DropStars>(&r.body).unwrap()

        }

    };

    assert_eq!(stars(andy.clone(), "PUT").await, hub_api::DropStars { stars: 1, starred: true });

    assert_eq!(stars(andy.clone(), "PUT").await, hub_api::DropStars { stars: 1, starred: true }, "once per account");

    assert_eq!(stars(dave.clone(), "PUT").await.stars, 2);

    assert_eq!(stars(andy.clone(), "DELETE").await, hub_api::DropStars { stars: 1, starred: false });

    let seen: hub_api::Drop =

        serde_json::from_str(&api(app, "GET", &format!("/drops/{}", source.id), Some(&dave), None).await.body).unwrap();

    assert!(seen.stars == 1 && seen.starred, "{seen:?}");

    // Comments: listed oldest first; the owner is told; only the author,

    // the owner or an administrator deletes one.

    let say = |tok: String, body: &'static str| {

        let (app, id) = (app.clone(), source.id.clone());

        async move { api(&app, "POST", &format!("/drops/{id}/comments"), Some(&tok), Some(serde_json::json!({ "body": body }))).await }

    };

    let r = say(andy.clone(), "Nice **notes**").await;

    assert_eq!(r.status, StatusCode::CREATED, "{}", r.body);

    let first: hub_api::DropComment = serde_json::from_str(&r.body).unwrap();

    assert_eq!((first.author.as_str(), first.body.as_str()), ("andy", "Nice **notes**"));

    assert_eq!(say(dave.clone(), "  ").await.status, StatusCode::UNPROCESSABLE_ENTITY, "says something");

    say(dave.clone(), "Thanks").await;

    let listed: Vec<hub_api::DropComment> =

        serde_json::from_str(&api(app, "GET", &format!("/drops/{}/comments", source.id), None, None).await.body).unwrap();

    assert_eq!(listed.iter().map(|c| c.author.as_str()).collect::<Vec<_>>(), ["andy", "dave"]);

    let carol_row = db::accounts::account_by_name(&app.db, "carol").await.unwrap().unwrap();

    let told = db::notify::inbox(&app.db, carol_row.id, 10).await.unwrap();

    assert!(told.iter().any(|n| n.kind == "drop.comment"), "{told:?}");

    let del = |tok: String, n: i64| {

        let (app, id) = (app.clone(), source.id.clone());

        async move { api(&app, "DELETE", &format!("/drops/{id}/comments/{n}"), Some(&tok), None).await.status }

    };

    assert_eq!(del(dave.clone(), first.id).await, StatusCode::FORBIDDEN, "not someone else's");

    assert_eq!(del(carol.clone(), first.id).await, StatusCode::NO_CONTENT, "the drop's owner may");

    assert_eq!(del(carol.clone(), first.id).await, StatusCode::NOT_FOUND);

}

    /// A copy of someone's drop, history and all, as a drop of yours

    Fork {

        /// The drop's id, or its address

        id: String,

    },

    /// Star a drop

    Star {

        /// The drop's id, or its address

        id: String,

    },

    /// Take your star back

    Unstar {

        /// The drop's id, or its address

        id: String,

    },

    /// A drop's comments, oldest first

    Comments {

        /// The drop's id, or its address

        id: String,

    },

    /// Comment on a drop (Markdown); its owner is told

    Comment {

        /// The drop's id, or its address

        id: String,

        /// What to say

        #[arg(long, short = 'm')]

        message: String,

    },

}

/// `oh drop star|unstar` (oxygenhub#349).

fn drop_star(c: &Client, id: &str, method: &str, json: bool) -> Result<()> {

    let s: hub_api::DropStars = c.send(method, &format!("/drops/{}/star", drop_id(id)?), &serde_json::json!({}))?;

    if json {

        println!("{}", serde_json::to_string(&s)?);

    } else {

        println!("{} {} · {} stars", ui::ok("✔"), if s.starred { "starred" } else { "unstarred" }, s.stars);

    }

    Ok(())

        }

        DropCmd::Fork { id } => {

            let d: hub_api::Drop = c.send("POST", &format!("/drops/{}/fork", drop_id(&id)?), &serde_json::json!({}))?;

            if json {

                println!("{}", serde_json::to_string(&d)?);

            } else {

                println!("{} forked as {} {}", ui::ok("✔"), ui::strong(&d.id), ui::dim(&d.url));

            }

        }

        DropCmd::Star { id } => drop_star(c, &id, "PUT", json)?,

        DropCmd::Unstar { id } => drop_star(c, &id, "DELETE", json)?,

        DropCmd::Comments { id } => {

            let path = format!("/drops/{}/comments", drop_id(&id)?);

            if json {

                println!("{}", c.get_text(&path)?);

                return Ok(0);

            }

            let list: Vec<hub_api::DropComment> = c.get(&path)?;

            if list.is_empty() {

                println!("{}", ui::dim("No comments."));

            }

            for m in &list {

                println!("{} {}", ui::strong(&m.author), ui::dim(&format!("#{} · {}", m.id, ui::ago(m.created_ms))));

                println!("{}\n", m.body);

            }

        DropCmd::Comment { id, message } => {

            let m: hub_api::DropComment =

                c.send("POST", &format!("/drops/{}/comments", drop_id(&id)?), &hub_api::NewDropComment { body: message })?;

            if json {

                println!("{}", serde_json::to_string(&m)?);

            } else {

                println!("{} commented (#{})", ui::ok("✔"), m.id);

            }

        }

        for (verb, ok) in [("fork", true), ("star", true), ("unstar", true), ("comments", true)] {

            assert_eq!(Cli::try_parse_from(["oh", "drop", verb, "x"]).is_ok(), ok, "{verb}");

        }

        assert!(Cli::try_parse_from(["oh", "drop", "comment", "x"]).is_err(), "a comment says something");

        match Cli::try_parse_from(["oh", "drop", "comment", "x", "-m", "Nice"]).unwrap().cmd {

            Cmd::Drop { cmd: DropCmd::Comment { message, .. } } => assert_eq!(message, "Nice"),

            _ => panic!("not drop comment"),

        }

| `oh drop fork ID` | A copy of someone's drop, history and all, as a drop of yours (oxygenhub#349) |

| `oh drop star ID` / `oh drop unstar ID` | Star a drop, or take the star back |

| `oh drop comments ID` | A drop's comments, oldest first |

| `oh drop comment ID -m TEXT` | Comment on a drop (Markdown); its owner is told |

- **API:** `GET /api/v1/drops` (yours, `repo:read`), `POST /api/v1/drops` (`NewDrop`, `repo:write`), `GET /api/v1/users/{name}/drops` (someone's public drops), `GET /api/v1/drops/{id}` (anyone with the id; each text file's content up to 512 KiB), `PATCH /api/v1/drops/{id}` (`DropEdit`: title, description, `secret`, and files to write or, with `content: null`, remove; others are kept) and `DELETE /api/v1/drops/{id}`; a drop carries its `stars`, whether the caller `starred` it, `forked_from` and its `embed_url`. Forks, stars and comments (oxygenhub#349, `repo:write`, the web's rules): `POST /api/v1/drops/{id}/fork` (201, the caller's new drop), `PUT`/`DELETE /api/v1/drops/{id}/star` (`DropStars`, the same however often asked), `GET`/`POST /api/v1/drops/{id}/comments` (`DropComment`, `NewDropComment`; the owner is told) and `DELETE /api/v1/drops/{id}/comments/{n}` (its author, the owner or an administrator). `oh drop create|list|view|delete|fork|star|unstar|comments|comment` (docs/oh.md).

- **Later:** drops in backups.