Skip to content
1        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}