diff --git a/README.md b/README.md index 166a7a6..feb46cb 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,8 @@ More in [docs/screenshots](docs/screenshots). server warns players, stops cleanly, backs up, updates, restarts and reports back. A failed update rolls back automatically. - **Server management.** From the app or the CLI, on any machine: watch the live console and send - commands, start, stop and restart, and back up, restore or delete backups. Backups made by mods + commands, start, stop and restart, and back up, restore or delete backups (several at once, or + automatically past a count, size or age limit). Backups made by mods like FTB Backups or Simple Backups show up next to BeaconSync's own. - **Updates.** The app updates itself from GitHub releases (download, verify, restart) and updates `beacon` on your servers with one click: each server checks the new build, warns @@ -133,6 +134,7 @@ beacon server console -s Survival # live console, type commands; tab beacon server cmd -s Survival whitelist add Steve beacon server backups -s Survival # BeaconSync's and backup mods' (FTB Backups, Simple Backups...) beacon server backups -s Survival create | restore | delete +beacon server backups -s Survival keep --last 5 --max-gb 5 --max-days 10 # limits left out are off beacon server stop | start | restart -s Survival beacon server switch "My Pack" # on the server: follow another of your packs (world stays) beacon server rollback # on the server, while it's stopped: back to the newest backup diff --git a/apps/desktop/src/lib/types.ts b/apps/desktop/src/lib/types.ts index 76a47d8..61585ff 100644 --- a/apps/desktop/src/lib/types.ts +++ b/apps/desktop/src/lib/types.ts @@ -198,6 +198,7 @@ export type ServerAction = | { kind: 'command'; arg: string } | { kind: 'start' | 'stop' | 'restart' | 'backup' } | { kind: 'restore' | 'delete_backup'; arg: string } + | { kind: 'set_retention'; arg: Retention } /** Update the server's `beacon` to this BeaconSync version. */ | { kind: 'update'; arg: string } @@ -213,12 +214,21 @@ export interface Backup { full: boolean } +/** Which of BeaconSync's own backups a server keeps; past any limit the oldest go, the newest always stays. null = no limit. */ +export interface Retention { + keep: number | null + max_bytes: number | null + max_days: number | null +} + export interface ConsoleView { lines: string[] next: number backups: Backup[] online: boolean running: boolean + /** null until the server reports it; older servers can't change it. */ + retention: Retention | null } export interface DeployResponse { diff --git a/apps/desktop/src/views/pack/ServerPanel.tsx b/apps/desktop/src/views/pack/ServerPanel.tsx index 4071086..3b1d474 100644 --- a/apps/desktop/src/views/pack/ServerPanel.tsx +++ b/apps/desktop/src/views/pack/ServerPanel.tsx @@ -3,11 +3,11 @@ // so it works wherever the server runs. import { useEffect, useLayoutEffect, useRef, useState } from 'react' -import { Button, Empty, Tabs } from '../../components/ui' +import { Button, Empty, Input, Tabs } from '../../components/ui' import { call } from '../../lib/api' import { ago } from '../../lib/format' import { askConfirm, useApp } from '../../lib/store' -import type { Backup, ConsoleView, Server, ServerAction } from '../../lib/types' +import type { Backup, ConsoleView, Retention, Server, ServerAction } from '../../lib/types' /** Lines kept in memory. */ const KEEP = 5000 @@ -16,7 +16,15 @@ type Live = Omit & { loaded: boolean; error: string | null /** Long polls the server's console through the hub while mounted. */ function useConsole(path: string, server: string): Live { - const [live, setLive] = useState({ lines: [], backups: [], online: false, running: false, loaded: false, error: null }) + const [live, setLive] = useState({ + lines: [], + backups: [], + online: false, + running: false, + retention: null, + loaded: false, + error: null, + }) useEffect(() => { let alive = true let after: number | null = null @@ -64,12 +72,15 @@ export function ServerPanel({ const live = useConsole(path, server.id) const [tab, setTab] = useState<'console' | 'backups'>('console') const set = useApp((s) => s.set) - const send = async (action: ServerAction, done?: string) => { + /** Queues an action on the server; false (after showing why) when the hub refused it. */ + const send: Send = async (action, done) => { try { await call('server_action', { path, server: server.id, action }) if (done) set({ notice: { kind: 'ok', text: done } }) + return true } catch (e) { set({ notice: { kind: 'error', text: e instanceof Error ? e.message : String(e) } }) + return false } } const state = !live.loaded ? 'connecting' : !live.online ? 'offline' : live.running ? 'running' : 'stopped' @@ -148,7 +159,7 @@ export function ServerPanel({ {tab === 'console' ? ( void send({ kind: 'command', arg: c })} /> ) : ( - + )} ) @@ -235,7 +246,36 @@ function Console({ lines, disabled, onSend }: { lines: string[]; disabled: boole ) } -function Backups({ backups, online, send }: { backups: Backup[]; online: boolean; send: (a: ServerAction, done?: string) => Promise }) { +type Send = (a: ServerAction, done?: string) => Promise + +const GB = 2 ** 30 +const DAY = 86_400 +const COLS = 'grid-cols-[16px_140px_120px_80px_110px_minmax(0,1fr)_auto]' + +const total = (bs: Backup[]) => bs.reduce((n, b) => n + b.size, 0) + +function Backups({ + backups, + retention, + online, + send, +}: { + backups: Backup[] + retention: Retention | null + online: boolean + send: Send +}) { + const [selected, setSelected] = useState>(new Set()) + // Ids can go stale as backups are pruned or deleted; only listed ones count. + const picked = backups.filter((b) => selected.has(b.id)) + const all = backups.length > 0 && picked.length === backups.length + const flip = (id: string) => + setSelected((s) => { + const next = new Set(s) + if (!next.delete(id)) next.add(id) + return next + }) + const restore = (b: Backup) => askConfirm({ title: 'Restore this backup?', @@ -244,14 +284,23 @@ function Backups({ backups, online, send }: { backups: Backup[]; online: boolean danger: true, onConfirm: () => void send({ kind: 'restore', arg: b.id }, 'Restoring. Follow along in the console.'), }) - const remove = (b: Backup) => + const remove = (doomed: Backup[]) => { + const [one] = doomed askConfirm({ - title: 'Delete this backup?', - body: `${b.source} backup from ${ago(b.created)} (${size(b.size)}). This can't be undone.`, + title: doomed.length === 1 ? 'Delete this backup?' : `Delete ${doomed.length} backups?`, + body: `${doomed.length === 1 && one ? `${one.source} backup from ${ago(one.created)} (${size(one.size)})` : `${size(total(doomed))} in total`}. This can't be undone.`, action: 'Delete', danger: true, - onConfirm: () => void send({ kind: 'delete_backup', arg: b.id }), + onConfirm: async () => { + // One action per backup: the server works through them in order. Stops at the first + // refusal (e.g. the server went offline), leaving the rest selected. + for (const b of doomed) { + if (!(await send({ kind: 'delete_backup', arg: b.id }))) return + setSelected((s) => new Set([...s].filter((id) => id !== b.id))) + } + }, }) + } return (
@@ -262,10 +311,52 @@ function Backups({ backups, online, send }: { backups: Backup[]; online: boolean Backups are also taken before every update. Backups made by mods like FTB Backups show up here too.
+ {retention && ( + b.full)} + online={online} + send={send} + /> + )}
{backups.length === 0 && {online ? 'No backups yet.' : 'The server is offline.'}} + {backups.length > 0 && ( +
+ { + if (el) el.indeterminate = picked.length > 0 && !all + }} + onChange={() => setSelected(new Set(all ? [] : backups.map((b) => b.id)))} + className="accent-[#7ee8ff]" + /> + + {picked.length ? `${picked.length} selected · ${size(total(picked))}` : `${backups.length} backups · ${size(total(backups))}`} + + + {picked.length > 0 && ( + <> + + + + )} + +
+ )} {backups.map((b) => ( -
+
+ ))}
) } + +/** Parses one limit field: null when empty (no limit), undefined when invalid. Counts and days + * are whole numbers that fit a u32; sizes are GB and become bytes. */ +function limit(text: string, unit: 'count' | 'gb'): number | null | undefined { + if (!text.trim()) return null + const n = Number(text) + if (unit === 'gb') return n > 0 && n * GB <= Number.MAX_SAFE_INTEGER ? Math.max(1, Math.round(n * GB)) : undefined + return Number.isInteger(n) && n >= 1 && n <= 2 ** 32 - 1 ? n : undefined +} + +/** How many of `own` (BeaconSync backups, newest first) `r` keeps. Mirrors `kept` in crates/cli/src/backups.rs. */ +function kept(own: Backup[], r: Retention, now: number) { + let bytes = 0 + const first = own.findIndex((b, i) => { + bytes += b.size + return ( + i > 0 && + ((r.keep !== null && i >= r.keep) || + (r.max_bytes !== null && bytes > r.max_bytes) || + (r.max_days !== null && now - b.created > r.max_days * DAY)) + ) + }) + return first < 0 ? own.length : first +} + +const draftOf = (r: Retention) => ({ + keep: r.keep?.toString() ?? '', + gb: r.max_bytes === null ? '' : String(Math.round((r.max_bytes / GB) * 100) / 100), + days: r.max_days?.toString() ?? '', +}) + +/** The server's retention rule as three editable limits. Remounted (via key) when the server reports a new one. */ +function RetentionRow({ retention, own, online, send }: { retention: Retention; own: Backup[]; online: boolean; send: Send }) { + const saved = draftOf(retention) + const [draft, setDraft] = useState(saved) + // An untouched size keeps its exact bytes; the field only shows it rounded. + const parsed = { + keep: limit(draft.keep, 'count'), + max_bytes: draft.gb === saved.gb ? retention.max_bytes : limit(draft.gb, 'gb'), + max_days: limit(draft.days, 'count'), + } + const { keep, max_bytes, max_days } = parsed + const next: Retention | null = + keep !== undefined && max_bytes !== undefined && max_days !== undefined ? { keep, max_bytes, max_days } : null + const dirty = draft.keep !== saved.keep || draft.gb !== saved.gb || draft.days !== saved.days + const save = (r: Retention) => { + const doomed = own.slice(kept(own, r, Date.now() / 1000)) + const go = () => void send({ kind: 'set_retention', arg: r }, 'Saved') + if (!doomed.length) return go() + askConfirm({ + title: `Delete ${doomed.length} backup${doomed.length === 1 ? '' : 's'} now?`, + body: `They are past the new limits (${size(total(doomed))}). This can't be undone.`, + action: 'Save and delete', + danger: true, + onConfirm: go, + }) + } + const field = (key: keyof typeof draft, value: keyof typeof parsed, label: string, unit: string) => ( + + ) + return ( +
{ + e.preventDefault() + if (next && dirty) save(next) + }} + > + Keep + {field('keep', 'keep', 'last', 'backups')} + {field('gb', 'max_bytes', 'up to', 'GB')} + {field('days', 'max_days', 'up to', 'days old')} + + Oldest BeaconSync backups go first; the newest always stays. +
+ ) +} diff --git a/crates/cli/src/backups.rs b/crates/cli/src/backups.rs index 21b3d27..e6099d1 100644 --- a/crates/cli/src/backups.rs +++ b/crates/cli/src/backups.rs @@ -4,16 +4,16 @@ //! Ids are paths relative to the server folder, and only ids from [`list`] are acted on. use anyhow::{Context, Result, bail}; -use beacon_core::{api::Backup, server as srv}; +use beacon_core::{ + api::{Backup, Retention}, + server as srv, +}; use std::{ fs, path::{Path, PathBuf}, time::UNIX_EPOCH, }; -/// BeaconSync backups kept; older ones are pruned after each new one. -const KEEP: usize = 10; - /// Backup mods by a piece of their jar name, for labels. const MODS: &[(&str, &str)] = &[ ("ftbbackups", "FTB Backups"), @@ -31,6 +31,24 @@ fn own_dir(server: &Path) -> PathBuf { server.join(".beacon/backups") } +/// Kept apart from `server.json` and left out of backups (see [`skip`]), so restoring an older +/// backup doesn't bring back an older rule. +fn retention_path(server: &Path) -> PathBuf { + server.join(".beacon/backup-retention.json") +} + +/// The server's retention rule; the default until the owner sets one. +pub fn retention(server: &Path) -> Retention { + fs::read(retention_path(server)).ok().and_then(|b| serde_json::from_slice(&b).ok()).unwrap_or_default() +} + +/// Saves the rule and prunes by it right away. +pub fn set_retention(server: &Path, r: &Retention) -> Result<()> { + beacon_core::store::write_atomic(&retention_path(server), &serde_json::to_vec_pretty(r)?)?; + prune(server); + Ok(()) +} + fn is_archive(name: &str) -> bool { let n = name.to_ascii_lowercase(); n.ends_with(".zip") || n.ends_with(".tar.gz") || n.ends_with(".tgz") @@ -127,7 +145,8 @@ fn find(server: &Path, id: &str) -> Result { list(server).into_iter().find(|b| b.id == id).with_context(|| format!("no backup {id}")) } -/// Left out of BeaconSync backups: caches, logs, other backups and files being written. +/// Left out of BeaconSync backups: caches, logs, other backups (and their retention rule) and +/// files being written. /// `world` is the world folder, always kept even if its name contains "backup". fn skip(server: &Path, world: &str, rel: &Path) -> bool { let s = rel.to_string_lossy(); @@ -170,15 +189,31 @@ pub fn create(server: &Path, note: &str) -> Result { find(server, &rel(server, &dir.join(name))) } -/// Keeps the newest BeaconSync backups. Separate from [`create`] so a restore can take a safety -/// backup without pruning the one it is about to restore. +/// Deletes the BeaconSync backups past the server's [`retention`]. Separate from [`create`] so a +/// restore can take a safety backup without pruning the one it is about to restore. pub fn prune(server: &Path) { - let mut own: Vec = list(server).into_iter().filter(|b| b.full).collect(); - for old in own.split_off(KEEP.min(own.len())) { + let own: Vec = list(server).into_iter().filter(|b| b.full).collect(); + for old in &own[kept(&own, &retention(server), beacon_core::now())..] { fs::remove_file(server.join(&old.id)).ok(); } } +/// How many of `own` (newest first) `r` keeps. Each limit only grows more exceeded going back +/// in time, so everything from the first backup past one is dropped. The newest always stays. +fn kept(own: &[Backup], r: &Retention, now: i64) -> usize { + let mut total = 0; + own.iter() + .enumerate() + .position(|(i, b)| { + total += b.size; + i > 0 + && (r.keep.is_some_and(|k| i >= k as usize) + || r.max_bytes.is_some_and(|m| total > m) + || r.max_days.is_some_and(|d| now - b.created > i64::from(d) * 86_400)) + }) + .unwrap_or(own.len()) +} + /// The newest BeaconSync backup, e.g. the one taken before the last update. pub fn latest(server: &Path) -> Option { list(server).into_iter().find(|b| b.full) @@ -310,4 +345,42 @@ mod tests { assert!(restore(&d, "backups/incremental.zip").is_err()); fs::remove_dir_all(d).ok(); } + + #[test] + fn retention_drops_the_oldest_past_any_limit_but_keeps_the_newest() { + const DAY: i64 = 86_400; + let gb = 1 << 30; + // Newest first: 1, 2, 3... days old, 1 GB each. + let own: Vec = (1..=6) + .map(|d| Backup { + id: d.to_string(), + source: "BeaconSync".into(), + note: String::new(), + size: gb, + created: -d * DAY, + full: true, + }) + .collect(); + let r = |keep, gbs: Option, max_days| Retention { keep, max_bytes: gbs.map(|g| g * gb), max_days }; + assert_eq!(kept(&own, &r(None, None, None), 0), 6); + assert_eq!(kept(&own, &r(Some(5), None, None), 0), 5); + assert_eq!(kept(&own, &r(None, Some(3), None), 0), 3); + assert_eq!(kept(&own, &r(None, None, Some(4)), 0), 4); + assert_eq!(kept(&own, &r(Some(5), Some(4), Some(2)), 0), 2); + assert_eq!(kept(&own, &r(Some(0), Some(0), Some(0)), 0), 1); + } + + #[test] + fn retention_is_applied_and_survives_a_restore() { + let d = server(); + create(&d, "one").unwrap(); + set_retention(&d, &Retention { keep: Some(5), max_bytes: None, max_days: None }).unwrap(); + create(&d, "two").unwrap(); + set_retention(&d, &Retention { keep: Some(1), max_bytes: None, max_days: None }).unwrap(); + assert_eq!(list(&d).len(), 1); + // Restoring a backup taken under keep 5 leaves keep 1 in place. + restore(&d, &list(&d)[0].id).unwrap(); + assert_eq!(retention(&d).keep, Some(1)); + fs::remove_dir_all(d).ok(); + } } diff --git a/crates/cli/src/server.rs b/crates/cli/src/server.rs index 98b0906..d28c703 100644 --- a/crates/cli/src/server.rs +++ b/crates/cli/src/server.rs @@ -12,8 +12,8 @@ use crate::{ use anyhow::{Context, Result, bail}; use beacon_core::{ api::{ - AgentConsole, AgentReport, AgentTarget, DeployRequest, DeployTargets, NewServer, Pack, Release, Server, ServerAction, - ServerMode, + AgentConsole, AgentReport, AgentTarget, DeployRequest, DeployTargets, NewServer, Pack, Release, Retention, Server, + ServerAction, ServerMode, }, fetch::{Fetcher, Progress}, hash::short, @@ -173,6 +173,17 @@ pub enum BackupCmd { Delete { id: String, }, + /// Set which BeaconSync backups are kept; past any limit the oldest are deleted, the newest + /// always stays. Limits left out are off, e.g. `keep --last 5 --max-gb 5 --max-days 10`. + #[command(arg_required_else_help = true)] + Keep { + #[arg(long, value_parser = clap::value_parser!(u32).range(1..))] + last: Option, + #[arg(long)] + max_gb: Option, + #[arg(long, value_parser = clap::value_parser!(u32).range(1..))] + max_days: Option, + }, } #[derive(clap::ValueEnum, Clone, Copy)] @@ -925,8 +936,9 @@ async fn uploader(hub: Hub, mut rx: mpsc::UnboundedReceiver) { async fn push_state(hub: &Option, dir: &Path, running: bool) { let Some(h) = hub else { return }; let d = dir.to_path_buf(); - let backups = tokio::task::spawn_blocking(move || backups::list(&d)).await.unwrap_or_default(); - let c = AgentConsole { lines: vec![], backups: Some(backups), running: Some(running) }; + let (list, retention) = + tokio::task::spawn_blocking(move || (backups::list(&d), backups::retention(&d))).await.unwrap_or_default(); + let c = AgentConsole { lines: vec![], backups: Some(list), running: Some(running), retention: Some(retention) }; if let Err(e) = h.agent_console(&c).await { tracing::warn!("state upload failed: {e:#}"); } @@ -1030,12 +1042,16 @@ async fn wait_exit(mc: &mut Option) -> std::io::Result, actions: mpsc::Sender) { +/// Long polls the hub for deployments and owner actions. When the hub lacks this server's state (it +/// keeps it in memory, so after a restart), asks on `resync` for it to be sent again. +async fn agent_loop(hub: Hub, targets: mpsc::Sender, actions: mpsc::Sender, resync: mpsc::Sender<()>) { let mut last: Option = None; loop { match hub.agent_poll(25, last.as_deref()).await { Ok(p) => { + if p.resync { + resync.try_send(()).ok(); + } for a in p.actions { if actions.send(a).await.is_err() { return; @@ -1154,8 +1170,9 @@ async fn supervise(dir: PathBuf) -> Result<()> { let (tx_target, mut targets) = mpsc::channel(1); let (tx_action, mut actions) = mpsc::channel(16); + let (tx_resync, mut resync) = mpsc::channel(1); if let Some(h) = agent.clone() { - tokio::spawn(agent_loop(h, tx_target, tx_action)); + tokio::spawn(agent_loop(h, tx_target, tx_action, tx_resync)); } let (tx_in, mut console) = mpsc::channel(16); #[cfg(unix)] @@ -1164,6 +1181,9 @@ async fn supervise(dir: PathBuf) -> Result<()> { #[cfg(unix)] let mut term = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?; + // Age limits pass while nothing new is backed up; apply them on every start too. + let d = dir.clone(); + tokio::task::spawn_blocking(move || backups::prune(&d)).await.ok(); let mut mc = Some(Mc::start(&dir, &cfg)?); report(&agent, None, "running", format!("running {}", cfg.release_name.clone().unwrap_or_default()), cfg.commit.clone()) .await; @@ -1212,6 +1232,7 @@ async fn supervise(dir: PathBuf) -> Result<()> { } push_state(&agent, &dir, mc.is_some()).await; } + Some(()) = resync.recv() => push_state(&agent, &dir, mc.is_some()).await, Some(line) = console.recv() => { if let Some(m) = mc.as_mut() { m.send(&line).await; @@ -1230,6 +1251,19 @@ async fn supervise(dir: PathBuf) -> Result<()> { Ok(()) } +/// E.g. "last 5, up to 5.0 GB, up to 10 days old". +fn retention_text(r: &Retention) -> String { + let parts: Vec = [ + r.keep.map(|k| format!("last {k}")), + r.max_bytes.map(|b| format!("up to {}", size(b))), + r.max_days.map(|d| format!("up to {d} days old")), + ] + .into_iter() + .flatten() + .collect(); + if parts.is_empty() { "all".into() } else { parts.join(", ") } +} + pub(crate) fn size(bytes: u64) -> String { match bytes { ..1_048_576 => format!("{} KB", bytes.div_ceil(1024)), @@ -1319,6 +1353,11 @@ async fn act(dir: &Path, cfg: &mut ServerConfig, agent: &Option, mc: &mut O backups::delete(dir, &id)?; say(format!("deleted backup {id}")); } + ServerAction::SetRetention(r) => { + let d = dir.to_path_buf(); + tokio::task::spawn_blocking(move || backups::set_retention(&d, &r)).await??; + say(format!("backups kept: {}", retention_text(&r))); + } ServerAction::Update(_) => unreachable!("handled by supervise"), } Ok(()) @@ -1648,6 +1687,14 @@ async fn backups_cmd(t: Target, global_dir: Option, action: Option act_remote(t, global_dir, ServerAction::DeleteBackup(id), &["deleted backup"]).await, + Some(BackupCmd::Keep { last, max_gb, max_days }) => { + if max_gb.is_some_and(|g| !(g.is_finite() && g > 0.0)) { + bail!("--max-gb must be above 0"); + } + let max_bytes = max_gb.map(|g| ((g * f64::from(1u32 << 30)) as u64).max(1)); + let r = Retention { keep: last, max_bytes, max_days }; + act_remote(t, global_dir, ServerAction::SetRetention(r), &["backups kept:"]).await + } None => { let (hub, server, _) = remote(t, global_dir).await?; let v = hub.console(&server.id, None, 0).await?; @@ -1657,6 +1704,9 @@ async fn backups_cmd(t: Target, global_dir: Option, action: Option Some("Backing up, follow along in the console"), ServerAction::Restore(_) => Some("Restoring, follow along in the console"), ServerAction::DeleteBackup(_) => Some("Deleting"), + ServerAction::SetRetention(_) => Some("Saving"), ServerAction::Update(_) => Some("Updating beacon, follow along in the console"), }; tokio::spawn(async move { diff --git a/crates/core/src/api.rs b/crates/core/src/api.rs index 3d7d7b3..ce139d2 100644 --- a/crates/core/src/api.rs +++ b/crates/core/src/api.rs @@ -209,6 +209,9 @@ pub struct AgentPoll { /// Things the owner asked for from the app or CLI, oldest first. #[serde(default)] pub actions: Vec, + /// The hub has no backups or state from this agent yet, e.g. after the hub restarted: send them. + #[serde(default)] + pub resync: bool, } /// What an owner can ask a running server to do. Relayed by the hub to the agent. @@ -225,6 +228,8 @@ pub enum ServerAction { /// Restore a backup by id (stops and restarts Minecraft). Restore(String), DeleteBackup(String), + /// Change which of BeaconSync's own backups the server keeps; applied right away. + SetRetention(Retention), /// Update `beacon` itself to this BeaconSync version; Minecraft restarts. Update(String), } @@ -244,6 +249,25 @@ pub struct Backup { pub full: bool, } +/// Which of BeaconSync's own backups a server keeps. Applied after every new backup, on start and +/// when set; past any limit the oldest go first, and the newest is always kept. Backup mods' +/// archives are left to the mod. `None` means no limit. +#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)] +pub struct Retention { + /// At most this many backups. + pub keep: Option, + /// At most this many bytes in total. + pub max_bytes: Option, + /// None older than this many days. + pub max_days: Option, +} + +impl Default for Retention { + fn default() -> Self { + Self { keep: Some(10), max_bytes: None, max_days: None } + } +} + /// Console output and state an agent uploads. #[derive(Serialize, Deserialize, Clone, Debug, Default)] pub struct AgentConsole { @@ -252,6 +276,9 @@ pub struct AgentConsole { pub backups: Option>, /// Whether Minecraft is running, when it changed. pub running: Option, + /// Sent with `backups`. + #[serde(default)] + pub retention: Option, } /// A slice of a server's console for viewers. `next` is the cursor for the next call. @@ -262,6 +289,9 @@ pub struct ConsoleView { pub backups: Vec, pub online: bool, pub running: bool, + /// None until the agent reports it; older agents never do and can't take `SetRetention`. + #[serde(default)] + pub retention: Option, } #[derive(Serialize, Deserialize, Clone, Debug)] diff --git a/crates/hub/src/routes.rs b/crates/hub/src/routes.rs index 3f297d6..ffcd341 100644 --- a/crates/hub/src/routes.rs +++ b/crates/hub/src/routes.rs @@ -50,6 +50,9 @@ struct Console { end: u64, backups: Vec, running: bool, + retention: Option, + /// Whether the agent sent its backups since the hub started. + reported: bool, actions: Vec, /// Wakes viewers waiting for new lines. changed: Arc, @@ -624,9 +627,9 @@ fn agent_state(s: &AppState, srv: &AuthServer, known: Option<&str>) -> Result<(A _ => None, }; drop(db); - let actions = s.console(&srv.id, |c| std::mem::take(&mut c.actions)); + let (actions, resync) = s.console(&srv.id, |c| (std::mem::take(&mut c.actions), !c.reported)); let has = target.as_ref().is_some_and(|t| Some(t.deployment.as_str()) != known) || !actions.is_empty(); - Ok((AgentPoll { target, server, pack_code: code, actions }, has)) + Ok((AgentPoll { target, server, pack_code: code, actions, resync }, has)) } async fn agent_poll(State(s): State, srv: AuthServer, Query(q): Query) -> Result> { @@ -688,6 +691,8 @@ async fn agent_console(State(s): State, srv: AuthServer, Json(c): Json } if let Some(b) = c.backups { con.backups = b; + con.retention = c.retention; + con.reported = true; } if let Some(r) = c.running { con.running = r; @@ -740,7 +745,8 @@ async fn server_console( let fresh = q.after.is_none_or(|a| a > c.end); let from = if fresh { c.end.saturating_sub(CONSOLE_TAIL) } else { q.after.unwrap_or(0) }.max(start); let lines = c.lines.iter().skip((from - start) as usize).cloned().collect(); - (ConsoleView { lines, next: c.end, backups: c.backups.clone(), online, running: c.running && online }, fresh) + let running = c.running && online; + (ConsoleView { lines, next: c.end, backups: c.backups.clone(), online, running, retention: c.retention }, fresh) }); if !view.lines.is_empty() || fresh || tokio::time::Instant::now() >= deadline { return Ok(Json(view)); @@ -766,6 +772,16 @@ async fn server_action( if matches!(a, ServerAction::Update(_)) && server.agent_version.is_none() { return Err(Error::bad("this server's beacon is too old to update itself; run `beacon server install` on it again")); } + if let ServerAction::SetRetention(r) = &a { + // Agents that don't report a rule predate it and would fail to read the action. A current + // one may just not have reported yet since a hub restart. + if s.console(&sid, |c| c.retention.is_none()) { + return Err(Error::bad("this server hasn't reported its backup retention; its beacon may need updating")); + } + if [r.keep.map(u64::from), r.max_bytes, r.max_days.map(u64::from)].contains(&Some(0)) { + return Err(Error::bad("retention limits must be above 0")); + } + } if let ServerAction::Command(c) = &a && (c.trim().is_empty() || c.contains('\n')) { diff --git a/crates/hub/src/tests.rs b/crates/hub/src/tests.rs index 6cdaa12..dbc3b4d 100644 --- a/crates/hub/src/tests.rs +++ b/crates/hub/src/tests.rs @@ -209,7 +209,8 @@ async fn console_and_actions_are_relayed_between_owner_and_server() { .await .unwrap(); let (sid, agent) = (created.server.id.clone(), Hub::new(&base, Some(created.token))); - agent.agent_poll(0, None).await.unwrap(); + // The hub has nothing from the agent yet (as after a hub restart), so it asks for its state. + assert!(agent.agent_poll(0, None).await.unwrap().resync); let backup = Backup { id: "backups/a.zip".into(), @@ -224,11 +225,13 @@ async fn console_and_actions_are_relayed_between_owner_and_server() { lines: vec!["Done (3.2s)!".into()], backups: Some(vec![backup.clone()]), running: Some(true), + retention: None, }) .await .unwrap(); let v = owner.console(&sid, None, 0).await.unwrap(); assert_eq!((v.lines, v.backups, v.running, v.next), (vec!["Done (3.2s)!".to_string()], vec![backup], true, 1)); + assert!(!agent.agent_poll(0, None).await.unwrap().resync); // A viewer waiting after the cursor is woken by the next line. let waiting = tokio::spawn({ @@ -252,6 +255,17 @@ async fn console_and_actions_are_relayed_between_owner_and_server() { assert_eq!(p.actions, vec![ServerAction::Command("list".into())]); assert!(agent.agent_poll(0, None).await.unwrap().actions.is_empty()); + // Retention changes only go to agents that report a rule, as older ones can't read them. + let keep = ServerAction::SetRetention(Retention { keep: Some(3), ..Default::default() }); + assert!(owner.server_action(&sid, &keep).await.is_err()); + let report = AgentConsole { backups: Some(vec![]), retention: Some(Retention::default()), ..Default::default() }; + agent.agent_console(&report).await.unwrap(); + assert_eq!(owner.console(&sid, None, 0).await.unwrap().retention, Some(Retention::default())); + let zero = ServerAction::SetRetention(Retention { keep: Some(0), ..Default::default() }); + assert!(owner.server_action(&sid, &zero).await.is_err()); + owner.server_action(&sid, &keep).await.unwrap(); + assert_eq!(agent.agent_poll(0, None).await.unwrap().actions, vec![keep]); + // Only the owner can watch or control the server. assert!(other.console(&sid, None, 0).await.is_err()); assert!(other.server_action(&sid, &ServerAction::Stop).await.is_err()); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f4254f6..555f8f4 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -152,19 +152,20 @@ GET|POST /api/packs/:id/servers { name, mode, address } -> { server, token } DELETE /api/packs/:id/servers/:sid POST /api/packs/:id/deploy { release, servers: [ids] | "all" } GET /api/servers/:sid/console?after=N&wait=20 - -> { lines, next, backups, online, running } (long poll; no `after` = last 500 lines) + -> { lines, next, backups, online, running, retention } (long poll; no `after` = last 500 lines) POST /api/servers/:sid/actions { kind: "command", arg } | { kind: "start|stop|restart|backup" } | { kind: "restore|delete_backup", arg: backup id } | { kind: "update", arg: BeaconSync version } (refused for agents that don't report a version) + | { kind: "set_retention", arg: { keep, max_bytes, max_days } } (refused for agents that don't report one) ``` Server agent (server token): ``` GET /api/agent/poll?wait=25&known= - -> { target: { commit, release, deployment } | null, actions: [...] } (long poll) + -> { target: { commit, release, deployment } | null, actions: [...], resync } (long poll; resync = hub wants backups and state again) POST /api/agent/report { deployment, status: "applying|done|failed|running|stopped|rolledback", message, commit, agent } -POST /api/agent/console { lines, backups?, running? } +POST /api/agent/console { lines, backups?, running?, retention? } ``` `agent` is the agent's `beacon` version; servers list it as `agent_version`. @@ -179,8 +180,10 @@ agent sends its backups and state again when it starts. 3. Deploy sets the target release on the chosen servers (one, several or all). 4. Each server runs `beacon server run`, which supervises the Minecraft process and long polls the hub. On a new target it warns players, stops the server, backs it up, applies the - new tree, restarts and reports back. It keeps the last 10 BeaconSync backups in - `.beacon/backups`, and also lists world archives backup mods leave in `*backup*` folders. + new tree, restarts and reports back. BeaconSync backups go in `.beacon/backups` and are + pruned by the server's retention rule: the last 10 by default, or a count, total size and + age set from the app or CLI (`.beacon/backup-retention.json`, left out of backups). It also + lists world archives backup mods leave in `*backup*` folders. 5. Players with the companion mod get an in-game toast, can compare their version with the server's and pull configs/resource packs live (mods are staged for the next restart).