LINE1 10 20 30 40 50 60 70 80 90 1001use std::{2 fs::{self, File, OpenOptions},3 io::{Read, Seek, SeekFrom},4 path::{Component, Path, PathBuf},5};67use flate2::{Compression, read::GzDecoder, write::GzEncoder};8use tar::{Archive, Builder, Header};910use crate::error::ContextError;1112use super::{13 error::OnceError,14 model::{AppSettings, Keys, ONCE_LABEL},15 namespace::{Application, Namespace},16};1718const APP_SETTINGS_ENTRY: &str = "once.application.json";19const VOLUME_SETTINGS_ENTRY: &str = "once.volume.json";20const MAX_SETTINGS_SIZE: u64 = 1024 * 1024;2122pub struct RestoreMetadata {23 pub app: AppSettings,24 pub volume_keys: Keys,25}2627pub async fn create(28 namespace: &Namespace,29 app: &Application,30 requested_path: &Path,31) -> Result<PathBuf, OnceError> {32 let filename = if requested_path.is_absolute() {33 requested_path.to_owned()34 } else {35 std::env::current_dir()?.join(requested_path)36 };37 let volume_name = format!("{}-app-{}", namespace.name, app.settings.name);38 let file = create_backup_file(&filename)?;39 let mut cleanup = BackupFileGuard::new(filename.clone());4041 let _ = namespace42 .engine43 .ensure_volume(44 &volume_name,45 std::collections::HashMap::from([(46 ONCE_LABEL.to_owned(),47 serde_json::to_string(&app.settings.keys)?,48 )]),49 )50 .await?;51 let legacy_label = namespace52 .engine53 .volume_label(&volume_name, ONCE_LABEL)54 .await?55 .ok_or_else(|| OnceError::InvalidMetadata("application volume has no Once label".into()))?;56 let legacy_keys = serde_json::from_str::<Keys>(&legacy_label)?;5758 let hook_exists = namespace59 .engine60 .container_path_exists(&app.container_id, "/hooks/pre-backup")61 .await?;62 let hook_succeeded = if hook_exists {63 namespace64 .engine65 .exec_capture(&app.container_id, &["/hooks/pre-backup".to_owned()])66 .await67 .is_ok_and(|(code, _)| code == 0)68 } else {69 false70 };71 let pause = app.running && !hook_succeeded;72 if pause {73 namespace.engine.pause_container(&app.container_id).await?;74 }7576 let backup_result = write_archive(namespace, app, legacy_keys, file).await;77 let unpause_result = if pause {78 namespace.engine.unpause_container(&app.container_id).await79 } else {80 Ok(())81 };8283 if let Err(error) = backup_result {84 if unpause_result.is_ok() {85 cleanup.remove();86 } else {87 cleanup.keep();88 }89 return Err(error);90 }91 if let Err(error) = unpause_result {92 cleanup.keep();93 return Err(OnceError::Docker(format!(94 "failed to unpause container after backup: {error}"95 )));96 }97 cleanup.keep();98 Ok(filename)99}100101struct BackupFileGuard {102 path: PathBuf,103 keep: bool,104}105106impl BackupFileGuard {107 fn new(path: PathBuf) -> Self {108 Self { path, keep: false }109 }110111 fn keep(&mut self) {112 self.keep = true;113 }114115 fn remove(&mut self) {116 let _ = fs::remove_file(&self.path);117 self.keep = true;118 }119}120121impl Drop for BackupFileGuard {122 fn drop(&mut self) {123 if !self.keep {124 let _ = fs::remove_file(&self.path);125 }126 }127}128129async fn write_archive(130 namespace: &Namespace,131 app: &Application,132 volume_keys: Keys,133 file: File,134) -> Result<(), OnceError> {135 let mut storage_tar = tempfile::tempfile()?;136 namespace137 .engine138 .download_container_path(&app.container_id, "/storage", &mut storage_tar)139 .await?;140 storage_tar.seek(SeekFrom::Start(0))?;141142 let encoder = GzEncoder::new(file, Compression::default());143 let mut archive = Builder::new(encoder);144 append_json(&mut archive, APP_SETTINGS_ENTRY, &app.settings)?;145 append_json(&mut archive, VOLUME_SETTINGS_ENTRY, &volume_keys)?;146 append_storage_entries(&mut archive, storage_tar)?;147 let encoder = archive.into_inner()?;148 encoder.finish()?;149 Ok(())150}151152pub fn read_metadata(path: &Path) -> Result<RestoreMetadata, OnceError> {153 let file = open_archive("opening restore archive", path)?;154 let mut archive = Archive::new(GzDecoder::new(file));155 let mut app_settings = None;156 let mut volume_keys = None;157158 for entry in archive.entries()? {159 let mut entry = entry?;160 let path = entry.path()?.into_owned();161 let destination = match path.to_str() {162 Some(APP_SETTINGS_ENTRY) => &mut app_settings,163 Some(VOLUME_SETTINGS_ENTRY) => &mut volume_keys,164 _ => continue,165 };166 if entry.size() > MAX_SETTINGS_SIZE {167 return Err(OnceError::InvalidBackup(format!(168 "metadata entry {} is too large",169 path.display()170 )));171 }172 let mut contents = Vec::with_capacity(usize::try_from(entry.size()).unwrap_or_default());173 entry.read_to_end(&mut contents)?;174 *destination = Some(contents);175 if app_settings.is_some() && volume_keys.is_some() {176 break;177 }178 }179180 let app: AppSettings = app_settings181 .ok_or_else(|| OnceError::InvalidBackup("missing application metadata".into()))182 .and_then(|bytes| {183 serde_json::from_slice(&bytes)184 .map_err(|error| OnceError::InvalidBackup(format!("parsing app settings: {error}")))185 })?;186 let volume_keys: Keys = volume_keys187 .ok_or_else(|| OnceError::InvalidBackup("missing volume metadata".into()))188 .and_then(|bytes| {189 serde_json::from_slice(&bytes).map_err(|error| {190 OnceError::InvalidBackup(format!("parsing volume settings: {error}"))191 })192 })?;193194 if app.image.is_empty() || app.host.is_empty() {195 return Err(OnceError::InvalidBackup(196 "application image and host are required".into(),197 ));198 }199 Ok(RestoreMetadata { app, volume_keys })200}201202pub fn data_archive(path: &Path) -> Result<File, OnceError> {203 let file = open_archive("reading restore archive", path)?;204 let mut source = Archive::new(GzDecoder::new(file));205 let mut temporary = tempfile::tempfile()?;206 {207 let mut destination = Builder::new(&mut temporary);208 for entry in source.entries()? {209 let mut entry = entry?;210 let entry_path = entry.path()?.into_owned();211 let Some(path) = entry_path.to_str() else {212 return Err(OnceError::InvalidBackup("non-UTF8 archive path".into()));213 };214 if path != "data" && !path.starts_with("data/") {215 continue;216 }217 validate_data_entry(path, entry.header())?;218 let mut header = entry.header().clone();219 header.set_cksum();220 destination.append(&header, &mut entry)?;221 }222 destination.finish()?;223 }224 temporary.seek(SeekFrom::Start(0))?;225 Ok(temporary)226}227228fn create_backup_file(path: &Path) -> Result<File, OnceError> {229 OpenOptions::new()230 .write(true)231 .create_new(true)232 .open(path)233 .map_err(|error| {234 let suggestion = match error.kind() {235 std::io::ErrorKind::AlreadyExists => {236 Some("choose a new destination; backups never overwrite existing files")237 }238 std::io::ErrorKind::NotFound => {239 Some("create the parent directory or choose an existing directory")240 }241 std::io::ErrorKind::PermissionDenied => {242 Some("check that you have permission to write to the destination")243 }244 _ => None,245 };246 let context = ContextError::new(247 format!("creating backup archive at `{}`", path.display()),248 error,249 );250 let context = match suggestion {251 Some(suggestion) => context.with_suggestion(suggestion),252 None => context,253 };254 OnceError::Context(context)255 })256}257258fn open_archive(action: &str, path: &Path) -> Result<File, OnceError> {259 File::open(path).map_err(|error| {260 let suggestion = match error.kind() {261 std::io::ErrorKind::NotFound => {262 Some("check that the archive exists and that the path is correct")263 }264 std::io::ErrorKind::PermissionDenied => {265 Some("check that you have permission to read the archive")266 }267 _ => None,268 };269 let context = ContextError::new(format!("{action} `{}`", path.display()), error);270 let context = match suggestion {271 Some(suggestion) => context.with_suggestion(suggestion),272 None => context,273 };274 OnceError::Context(context)275 })276}277278pub fn trim_old_backups(app_name: &str, directory: &Path) -> Result<(), OnceError> {279 let entries = fs::read_dir(directory)?;280 let cutoff = time::OffsetDateTime::now_utc() - time::Duration::days(30);281 for entry in entries {282 let entry = entry?;283 if !entry.file_type()?.is_file() {284 continue;285 }286 let filename = entry.file_name();287 let filename = filename.to_string_lossy();288 let Some(timestamp) = parse_backup_timestamp(app_name, &filename) else {289 continue;290 };291 if timestamp < cutoff {292 fs::remove_file(entry.path())?;293 }294 }295 Ok(())296}297298fn parse_backup_timestamp(app_name: &str, filename: &str) -> Option<time::OffsetDateTime> {299 let middle = filename300 .strip_prefix(&format!("{app_name}-"))?301 .strip_suffix(".tar.gz")?;302 if middle.len() != 15 || middle.as_bytes()[8] != b'-' {303 return None;304 }305 let year = middle[0..4].parse::<i32>().ok()?;306 let month = middle[4..6].parse::<u8>().ok()?;307 let day = middle[6..8].parse::<u8>().ok()?;308 let hour = middle[9..11].parse::<u8>().ok()?;309 let minute = middle[11..13].parse::<u8>().ok()?;310 let second = middle[13..15].parse::<u8>().ok()?;311 let date =312 time::Date::from_calendar_date(year, time::Month::try_from(month).ok()?, day).ok()?;313 let time = time::Time::from_hms(hour, minute, second).ok()?;314 Some(time::PrimitiveDateTime::new(date, time).assume_utc())315}316317fn validate_data_entry(path: &str, header: &Header) -> Result<(), OnceError> {318 let path = Path::new(path);319 if path.is_absolute()320 || path321 .components()322 .any(|component| !matches!(component, Component::Normal(_) | Component::CurDir))323 {324 return Err(OnceError::InvalidBackup("unsafe data path".into()));325 }326 if header.entry_type().is_symlink() || header.entry_type().is_hard_link() {327 let target = header328 .link_name()?329 .ok_or_else(|| OnceError::InvalidBackup("archive link has no target".into()))?;330 if target.is_absolute()331 || target332 .components()333 .any(|component| !matches!(component, Component::Normal(_) | Component::CurDir))334 {335 return Err(OnceError::InvalidBackup(336 "archive link target escapes application storage".into(),337 ));338 }339 }340 Ok(())341}342343fn append_json<T: serde::Serialize>(344 archive: &mut Builder<GzEncoder<File>>,345 name: &str,346 value: &T,347) -> Result<(), OnceError> {348 let data = serde_json::to_vec(value)?;349 let mut header = Header::new_gnu();350 header.set_size(data.len() as u64);351 header.set_mode(0o644);352 header.set_cksum();353 archive.append_data(&mut header, name, data.as_slice())?;354 Ok(())355}356357fn append_storage_entries(358 archive: &mut Builder<GzEncoder<File>>,359 source: File,360) -> Result<(), OnceError> {361 let mut source = Archive::new(source);362 for entry in source.entries()? {363 let mut entry = entry?;364 let original_path = entry.path()?.into_owned();365 let relative = original_path.strip_prefix("storage").map_err(|_| {366 OnceError::InvalidBackup(format!(367 "unexpected Docker storage archive path {}",368 original_path.display()369 ))370 })?;371 if relative372 .components()373 .any(|component| !matches!(component, Component::Normal(_) | Component::CurDir))374 {375 return Err(OnceError::InvalidBackup(format!(376 "unsafe storage archive path {}",377 original_path.display()378 )));379 }380 let path = if relative.as_os_str().is_empty() {381 PathBuf::from("data")382 } else {383 Path::new("data").join(relative)384 };385 let mut header = entry.header().clone();386 header.set_path(path)?;387 header.set_cksum();388 archive.append(&header, &mut entry)?;389 }390 Ok(())391}392393#[cfg(test)]394mod tests {395 use std::{396 fs,397 io::{Read, Seek, SeekFrom, Write},398 };399400 use flate2::{Compression, read::GzDecoder, write::GzEncoder};401 use tar::{Archive, Builder, Header};402403 use crate::error::format_cli_error;404405 use super::{406 APP_SETTINGS_ENTRY, VOLUME_SETTINGS_ENTRY, append_json, append_storage_entries,407 create_backup_file, read_metadata,408 };409410 #[test]411 fn missing_restore_archive_reports_path_and_recovery_hint() {412 let directory = tempfile::tempdir().unwrap();413 let path = directory.path().join("missing.tar.gz");414 let Err(error) = read_metadata(&path) else {415 panic!("missing archive should not be readable");416 };417418 let report = format_cli_error(&error);419 assert!(report.contains("opening restore archive"));420 assert!(report.contains(path.to_string_lossy().as_ref()));421 assert!(report.contains("Caused by: No such file or directory"));422 assert!(report.contains("Try: check that the archive exists and that the path is correct"));423 }424425 #[test]426 fn existing_backup_destination_reports_path_and_never_overwrites() {427 let directory = tempfile::tempdir().unwrap();428 let path = directory.path().join("existing.tar.gz");429 fs::write(&path, "keep this file").unwrap();430431 let error = create_backup_file(&path).unwrap_err();432 let report = format_cli_error(&error);433434 assert!(report.contains("creating backup archive"));435 assert!(report.contains(path.to_string_lossy().as_ref()));436 assert!(report.contains("Caused by:"));437 assert!(438 report439 .contains("Try: choose a new destination; backups never overwrite existing files")440 );441 assert_eq!(fs::read_to_string(path).unwrap(), "keep this file");442 }443444 #[test]445 fn creates_gzip_tar_with_once_metadata_names_and_storage_prefix() {446 let mut source_data = Vec::new();447 {448 let mut source = Builder::new(&mut source_data);449 append_source_file(&mut source, "storage", b"").unwrap();450 append_source_file(&mut source, "storage/db.sqlite3", b"database").unwrap();451 append_source_file(&mut source, "storage/uploads/file.txt", b"upload").unwrap();452 source.finish().unwrap();453 }454 let mut source_file = tempfile::tempfile().unwrap();455 source_file.write_all(&source_data).unwrap();456 source_file.seek(SeekFrom::Start(0)).unwrap();457458 let destination = tempfile::tempfile().unwrap();459 let mut archive = Builder::new(GzEncoder::new(destination, Compression::default()));460 append_json(461 &mut archive,462 APP_SETTINGS_ENTRY,463 &serde_json::json!({"host":"books.test"}),464 )465 .unwrap();466 append_json(467 &mut archive,468 VOLUME_SETTINGS_ENTRY,469 &serde_json::json!({"secretKeyBase":"key"}),470 )471 .unwrap();472 append_storage_entries(&mut archive, source_file).unwrap();473 let encoder = archive.into_inner().unwrap();474 let mut compressed = encoder.finish().unwrap();475 compressed.seek(SeekFrom::Start(0)).unwrap();476477 let mut archive = Archive::new(GzDecoder::new(compressed));478 let mut paths = Vec::new();479 let mut database = Vec::new();480 for entry in archive.entries().unwrap() {481 let mut entry = entry.unwrap();482 let path = entry.path().unwrap().to_string_lossy().into_owned();483 if path == "data/db.sqlite3" {484 entry.read_to_end(&mut database).unwrap();485 }486 paths.push(path);487 }488 assert_eq!(paths[0], APP_SETTINGS_ENTRY);489 assert_eq!(paths[1], VOLUME_SETTINGS_ENTRY);490 assert!(paths.contains(&"data".to_owned()));491 assert!(paths.contains(&"data/uploads/file.txt".to_owned()));492 assert_eq!(database, b"database");493 }494495 #[test]496 fn rejects_storage_archive_path_traversal() {497 let mut source_data = Vec::new();498 {499 let mut source = Builder::new(&mut source_data);500 append_unsafe_source_entry(&mut source, "storage/../outside", b"bad").unwrap();501 source.finish().unwrap();502 }503 let mut source_file = tempfile::tempfile().unwrap();504 source_file.write_all(&source_data).unwrap();505 source_file.seek(SeekFrom::Start(0)).unwrap();506507 let destination = tempfile::tempfile().unwrap();508 let mut archive = Builder::new(GzEncoder::new(destination, Compression::default()));509 assert!(append_storage_entries(&mut archive, source_file).is_err());510 }511512 #[test]513 fn reads_once_app_and_volume_settings_from_archive() {514 let file = tempfile::NamedTempFile::new().unwrap();515 let mut archive = Builder::new(GzEncoder::new(516 file.reopen().unwrap(),517 Compression::default(),518 ));519 append_json(520 &mut archive,521 APP_SETTINGS_ENTRY,522 &serde_json::json!({523 "name":"old-name",524 "image":"basecamp/writebook:latest",525 "host":"books.example.test",526 "keys":{"secretKeyBase":"app-key"}527 }),528 )529 .unwrap();530 append_json(531 &mut archive,532 VOLUME_SETTINGS_ENTRY,533 &serde_json::json!({"secretKeyBase":"legacy-key"}),534 )535 .unwrap();536 archive.into_inner().unwrap().finish().unwrap();537538 let metadata = read_metadata(file.path()).unwrap();539 assert_eq!(metadata.app.name, "old-name");540 assert_eq!(metadata.app.host, "books.example.test");541 assert_eq!(metadata.volume_keys.secret_key_base, "legacy-key");542 }543544 #[test]545 fn rejects_archive_without_volume_metadata() {546 let file = tempfile::NamedTempFile::new().unwrap();547 let mut archive = Builder::new(GzEncoder::new(548 file.reopen().unwrap(),549 Compression::default(),550 ));551 append_json(552 &mut archive,553 APP_SETTINGS_ENTRY,554 &serde_json::json!({"image":"app:latest","host":"app.localhost"}),555 )556 .unwrap();557 archive.into_inner().unwrap().finish().unwrap();558 assert!(read_metadata(file.path()).is_err());559 }560561 fn append_source_file<W: Write>(562 archive: &mut Builder<W>,563 path: &str,564 data: &[u8],565 ) -> std::io::Result<()> {566 let mut header = Header::new_gnu();567 header.set_size(data.len() as u64);568 header.set_mode(0o644);569 header.set_cksum();570 archive.append_data(&mut header, path, data)571 }572573 fn append_unsafe_source_entry<W: Write>(574 archive: &mut Builder<W>,575 path: &str,576 data: &[u8],577 ) -> std::io::Result<()> {578 let mut header = Header::new_gnu();579 header.as_mut_bytes()[..path.len()].copy_from_slice(path.as_bytes());580 header.set_size(data.len() as u64);581 header.set_mode(0o644);582 header.set_cksum();583 archive.append(&header, data)584 }585}