Backups API: settings, TEST, back up now and runs 2e9188ca4f98

//! The backups API (oxygenhub#179, docs/backups.md §5): what the Backups

//! pages do, for a user's own repositories and an organisation's (its

//! owners only), with the scope `repo:admin`.

use super::{caller, not_found, ApiError, Caller};

use crate::auth;

use crate::backups::{self, Run, Setting};

use crate::db::{self, accounts::Account};

use crate::web::backups::{setting_of, SettingInput};

use crate::Shared;

use axum::extract::{Path, State};

use axum::http::{HeaderMap, StatusCode};

use axum::Json;

use serde::{Deserialize, Serialize};

/// A setting as the API takes it: the page's fields, `keep_days` a number.

#[derive(Deserialize)]

pub struct Body {

    pub every: String,

    #[serde(default)]

    pub destination: String,

    /// A directory destination: one the hub allows.

    #[serde(default)]

    pub dir: String,

    /// A GCS destination: its bucket and workload identity provider.

    #[serde(default)]

    pub bucket: String,

    #[serde(default)]

    pub provider: String,

    #[serde(default)]

    pub prefix: String,

    #[serde(default = "thirty")]

    pub keep_days: i64,

    /// An S3 destination: its bucket, region and the IAM role's ARN.

    #[serde(default)]

    pub s3_bucket: String,

    #[serde(default)]

    pub s3_region: String,

    #[serde(default)]

    pub s3_role: String,

}

fn thirty() -> i64 {

    30

}

#[derive(Serialize)]

pub struct State_ {

    pub setting: Option<Setting>,

    /// Where its runs go, as the pages say it.

    pub place: Option<String>,

    pub runs: Vec<Run>,

}

/// The owner a call acts for: the caller's own account, or an organisation

/// it owns. Someone else's is not found.

async fn owner_of(app: &Shared, c: &Caller, org: Option<&str>) -> Result<(Account, String, &'static str), ApiError> {

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

    match org {

        None => {

            let name = me.username.clone();

            Ok((me, name, "user"))

        }

        Some(name) => {

            let o = db::accounts::org_by_name(&app.db, name).await?.ok_or_else(|| not_found("no such organisation"))?;

            if !auth::roles::is_org_owner(&app.db, &me, o.id).await? {

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

            }

            Ok((me, o.name, "org"))

        }

    }

}

async fn state(app: &Shared, owner: &str) -> Result<State_, ApiError> {

    let setting = backups::setting(&app.db, owner).await?;

    let place = setting.as_ref().map(backups::place);

    Ok(State_ { setting, place, runs: backups::runs(&app.db, owner, 10).await? })

}

async fn get(app: Shared, headers: HeaderMap, org: Option<String>) -> Result<Json<State_>, ApiError> {

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

    let (_, owner, _) = owner_of(&app, &c, org.as_deref()).await?;

    Ok(Json(state(&app, &owner).await?))

}

async fn put(app: Shared, headers: HeaderMap, org: Option<String>, b: Body) -> Result<Json<State_>, ApiError> {

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

    let (me, owner, kind) = owner_of(&app, &c, org.as_deref()).await?;

    let input = SettingInput {

        every: b.every,

        destination: b.destination,

        dir: b.dir,

        bucket: b.bucket,

        provider: b.provider,

        prefix: b.prefix,

        keep_days: b.keep_days.to_string(),

        s3_bucket: b.s3_bucket,

        s3_region: b.s3_region,

        s3_role: b.s3_role,

    };

    let s = setting_of(&app, &owner, kind, &input).map_err(|e| ApiError(StatusCode::BAD_REQUEST, e))?;

    backups::save(&app.db, &s).await?;

    db::accounts::audit(&app.db, Some(&me), "backup.setting", &owner, &format!("{} to {}", s.every, backups::place(&s))).await.ok();

    Ok(Json(state(&app, &owner).await?))

}

async fn test(app: Shared, headers: HeaderMap, org: Option<String>) -> Result<Json<serde_json::Value>, ApiError> {

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

    let (_, owner, _) = owner_of(&app, &c, org.as_deref()).await?;

    let set =

        backups::setting(&app.db, &owner).await?.ok_or_else(|| ApiError(StatusCode::CONFLICT, "save where backups go first".into()))?;

    let dest = backups::destination(&app, &set).map_err(|e| ApiError(StatusCode::CONFLICT, format!("{e:#}")))?;

    tokio::task::spawn_blocking(move || backups::probe(dest.as_ref()))

        .await

        .map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?

        .map_err(|e| ApiError(StatusCode::CONFLICT, format!("TEST failed: {e:#}")))?;

    Ok(Json(serde_json::json!({ "ok": true, "place": backups::place(&set) })))

}

async fn run(app: Shared, headers: HeaderMap, org: Option<String>) -> Result<(StatusCode, Json<serde_json::Value>), ApiError> {

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

    let (_, owner, _) = owner_of(&app, &c, org.as_deref()).await?;

    if backups::setting(&app.db, &owner).await?.is_none() {

        return Err(ApiError(StatusCode::CONFLICT, "save where backups go first".into()));

    }

    let (app2, owner2) = (app.clone(), owner.clone());

    tokio::spawn(async move {

        if let Err(e) = backups::run(&app2, &owner2, "now").await {

            tracing::warn!("backup of {owner2}: {e:#}");

        }

    });

    Ok((StatusCode::ACCEPTED, Json(serde_json::json!({ "owner": owner, "started": true }))))

}

async fn runs(app: Shared, headers: HeaderMap, org: Option<String>) -> Result<Json<Vec<Run>>, ApiError> {

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

    let (_, owner, _) = owner_of(&app, &c, org.as_deref()).await?;

    Ok(Json(backups::runs(&app.db, &owner, 50).await?))

}

pub async fn user_get(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<State_>, ApiError> {

    get(app, headers, None).await

}

pub async fn user_put(State(app): State<Shared>, headers: HeaderMap, Json(b): Json<Body>) -> Result<Json<State_>, ApiError> {

    put(app, headers, None, b).await

}

pub async fn user_test(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<serde_json::Value>, ApiError> {

    test(app, headers, None).await

}

pub async fn user_run(State(app): State<Shared>, headers: HeaderMap) -> Result<(StatusCode, Json<serde_json::Value>), ApiError> {

    run(app, headers, None).await

}

pub async fn user_runs(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<Vec<Run>>, ApiError> {

    runs(app, headers, None).await

}

pub async fn org_get(State(app): State<Shared>, headers: HeaderMap, Path(name): Path<String>) -> Result<Json<State_>, ApiError> {

    get(app, headers, Some(name)).await

}

pub async fn org_put(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(name): Path<String>,

    Json(b): Json<Body>,

) -> Result<Json<State_>, ApiError> {

    put(app, headers, Some(name), b).await

}

pub async fn org_test(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(name): Path<String>,

) -> Result<Json<serde_json::Value>, ApiError> {

    test(app, headers, Some(name)).await

}

pub async fn org_run(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path(name): Path<String>,

) -> Result<(StatusCode, Json<serde_json::Value>), ApiError> {

    run(app, headers, Some(name)).await

}

pub async fn org_runs(State(app): State<Shared>, headers: HeaderMap, Path(name): Path<String>) -> Result<Json<Vec<Run>>, ApiError> {

    runs(app, headers, Some(name)).await

}

mod backups;

        .route("/user/backups", get(backups::user_get).put(backups::user_put))

        .route("/user/backups/test", post(backups::user_test))

        .route("/user/backups/run", post(backups::user_run))

        .route("/user/backups/runs", get(backups::user_runs))

        .route("/orgs/{name}/backups", get(backups::org_get).put(backups::org_put))

        .route("/orgs/{name}/backups/test", post(backups::org_test))

        .route("/orgs/{name}/backups/run", post(backups::org_run))

        .route("/orgs/{name}/backups/runs", get(backups::org_runs))

        place(&self.setting)

    }

}

/// Where a setting's runs go, as a person reads it.

pub fn place(s: &Setting) -> String {

    match s.destination.as_str() {

        "gcs" if s.prefix.is_empty() => format!("gs://{}", s.target),

        "gcs" => format!("gs://{}/{}", s.target, s.prefix),

        "s3" if s.prefix.is_empty() => format!("s3://{} ({})", s.target, s.region),

        "s3" => format!("s3://{}/{} ({})", s.target, s.prefix, s.region),

        _ => format!("{}/{}", s.target, s.owner),

    #[serde(flatten)]

    input: SettingInput,

}

/// What a backup setting is made from, by the page's form or the API

/// (oxygenhub#179): checked the same way either way.

#[derive(Clone, Debug, Default, Deserialize)]

pub(crate) struct SettingInput {

    pub every: String,

    pub destination: String,

    pub dir: String,

    pub bucket: String,

    pub provider: String,

    pub prefix: String,

    pub keep_days: String,

    pub s3_bucket: String,

    pub s3_region: String,

    pub s3_role: String,

pub(crate) fn setting_of(app: &Shared, owner: &str, kind: &str, f: &SettingInput) -> Result<Setting, String> {

    match setting_of(app, owner, kind, &f.input) {

            let place = backups::place(&set);

pub(crate) mod backups;

/// One API call with a bearer token: the status and the JSON answer.

async fn api(

    app: &Shared,

    method: &str,

    path: &str,

    token: &str,

    body: Option<serde_json::Value>,

) -> (axum::http::StatusCode, serde_json::Value) {

    use axum::body::Body;

    use http_body_util::BodyExt;

    use tower::ServiceExt;

    let mut req =

        axum::http::Request::builder().method(method).uri(format!("/api/v1{path}")).header("authorization", format!("Bearer {token}"));

    let body = match body {

        Some(b) => {

            req = req.header("content-type", "application/json");

            Body::from(b.to_string())

        }

        None => Body::empty(),

    };

    let res = oxygenhub::router(app.clone()).oneshot(req.body(body).unwrap()).await.unwrap();

    let st = res.status();

    let bytes = res.into_body().collect().await.unwrap().to_bytes();

    (st, serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null))

}

/// oxygenhub#179: the API does what the Backups pages do, for the caller's

/// own repositories and an organisation it owns, with repo:admin: the

/// setting (checked as the page checks it), TEST, back up now, the runs.

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

async fn backups_are_set_up_and_run_through_the_api() {

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

    let h = hub(store.path()).await;

    let andy = db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", false).await.unwrap();

    let bob = db::accounts::create_account(&h.app.db, "bob", "[email protected]", "x", "salt", false).await.unwrap();

    db::accounts::create_org(&h.app.db, "club", "Club", andy.id).await.unwrap();

    create(&h.app, "andy", "demo", hub_api::Visibility::Public).await;

    create(&h.app, "club", "game", hub_api::Visibility::Private).await;

    let token = |id: i64, scopes: &'static str| {

        let db = h.app.db.clone();

        async move {

            let (t, hash) = oxygenhub::auth::new_token();

            db::accounts::create_token(&db, id, "t", &hash, scopes, "", None).await.unwrap();

            t

        }

    };

    let (andy_t, bob_t, weak) = (token(andy.id, "repo:admin").await, token(bob.id, "repo:admin").await, token(andy.id, "repo:read").await);

    let dir = store.path().display().to_string();

    let (st, empty) = api(&h.app, "GET", "/user/backups", &andy_t, None).await;

    assert_eq!(st, 200);

    assert!(empty["setting"].is_null() && empty["runs"].as_array().unwrap().is_empty(), "{empty}");

    let (st, _) = api(&h.app, "POST", "/user/backups/run", &andy_t, None).await;

    assert_eq!(st, 409, "nothing saved yet");

    let (st, _) =

        api(&h.app, "PUT", "/user/backups", &weak, Some(serde_json::json!({ "every": "hourly", "destination": "dir", "dir": dir }))).await;

    assert_eq!(st, 403, "repo:admin only");

    let (st, bad) = api(

        &h.app,

        "PUT",

        "/user/backups",

        &andy_t,

        Some(serde_json::json!({ "every": "hourly", "destination": "gcs", "bucket": "andy-backup", "provider": "nope" })),

    )

    .await;

    assert_eq!(st, 400, "checked as the page checks it: {bad}");

    let (st, saved) = api(

        &h.app,

        "PUT",

        "/user/backups",

        &andy_t,

        Some(serde_json::json!({ "every": "hourly", "destination": "dir", "dir": dir, "keep_days": 30 })),

    )

    .await;

    assert_eq!(st, 200, "{saved}");

    assert_eq!((saved["setting"]["every"].as_str(), saved["place"].as_str()), (Some("hourly"), Some(format!("{dir}/andy").as_str())));

    let (st, probe) = api(&h.app, "POST", "/user/backups/test", &andy_t, None).await;

    assert_eq!((st.as_u16(), probe["ok"].as_bool()), (200, Some(true)), "{probe}");

    let (st, started) = api(&h.app, "POST", "/user/backups/run", &andy_t, None).await;

    assert_eq!(st, 202, "{started}");

    let mut done = serde_json::Value::Null;

    for _ in 0..200 {

        let (_, runs) = api(&h.app, "GET", "/user/backups/runs", &andy_t, None).await;

        if runs[0]["status"].as_str().is_some_and(|s| s != "running") {

            done = runs[0].clone();

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

    }

    assert_eq!((done["status"].as_str(), done["repos"].as_i64(), done["trigger"].as_str()), (Some("ok"), Some(1), Some("now")), "{done}");

    // An organisation's, by its owner; another account sees no such thing.

    let (st, _) =

        api(&h.app, "PUT", "/orgs/club/backups", &bob_t, Some(serde_json::json!({ "every": "hourly", "destination": "dir", "dir": dir })))

            .await;

    assert_eq!(st, 404);

    let (st, org) = api(

        &h.app,

        "PUT",

        "/orgs/club/backups",

        &andy_t,

        Some(serde_json::json!({ "every": "daily", "destination": "dir", "dir": dir, "keep_days": 90 })),

    )

    .await;

    assert_eq!(st, 200, "{org}");

    assert_eq!((org["setting"]["kind"].as_str(), org["setting"]["keep_days"].as_i64()), (Some("org"), Some(90)));

    let (st, _) = api(&h.app, "GET", "/orgs/club/backups", &bob_t, None).await;

    assert_eq!(st, 404);

}

The API mirrors the pages (built 2026-10-14, oxygenhub#179; scope

`repo:admin`, an organisation's owners only): `GET/PUT /api/v1/user/backups`

and `GET/PUT /api/v1/orgs/{name}/backups` (the setting, checked as the page

checks it, with where its runs go and the newest runs; the body takes the

page's fields, `keep_days` as a number), `POST …/backups/test` (the probe),

`POST …/backups/run` (202: back up now, in the background) and