GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! # photocraft-format
//!
//! The native, lossless `.pcraft` document bundle (architecture §9).
//!
//! ```text
//! manifest.json            versioned document tree (see [`manifest`])
//! tiles/<blake3>.zst       content-addressed 256×256 tiles (zstd, little-endian samples)
//! blobs/<blake3>.zst       content-addressed binary data (ICC, EXIF, PSD blocks, smart objects)
//! thumb.png                optional thumbnail (caller-rendered)
//! composite/preview.png    optional flattened preview (caller-rendered)
//! composite/full.png       optional flattened composite at the canvas size (caller-rendered)
//! save.lock                directory bundles only: held while a save runs (empty)
//! ```
//!
//! A bundle is either a ZIP archive (STORE entries) or a directory with the
//! same layout. Saving is incremental: [`PcraftWriter`] remembers what it
//! already compressed/wrote, so only new tiles are encoded. Directory saves
//! verify existing content-addressed objects once per writer and folder,
//! rechecking files whose size or modification time changes; they replace
//! damaged or missing objects and garbage-collect unreferenced ones. A directory
//! save holds an OS file lock on `save.lock` throughout, so two writers (or two
//! processes) saving one bundle take turns instead of removing each other's objects.
//!
//! This crate sits at L3 next to the compositor, so it does not render.
//! Callers pass previews in [`SaveOptions`]; `photocraft-io` does that.
#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]

pub mod atomic;
pub mod autosave;
mod convert;
mod finite;
mod import_conversion;
pub mod manifest;
mod migrate;
mod noreplace;
pub mod read;
mod store;
pub mod zip;

use std::path::Path;

use photocraft_doc::Document;
use photocraft_raster::Rgba8Image;

pub use atomic::{atomic_write, atomic_write_no_follow, atomic_write_progress, atomic_write_stream, atomic_write_stream_progress};
#[cfg(not(target_arch = "wasm32"))]
pub use autosave::RecoveryStore;
pub use autosave::{Autosaver, RecoveryEntry, discard_recovery, list_recovery, recover};
pub use convert::MAX_GROUP_DEPTH;
pub use manifest::{FORMAT_VERSION, Manifest};
pub use noreplace::{PublishNewError, rename_noreplace, write_noreplace};
pub use read::{read_file, read_file_limited};
pub use store::{ByteSource, DEFAULT_REVERIFY_BUDGET, PcraftWriter, SaveStats, read_entry};

/// File extension of the native format.
pub use craft_pcraft_format::EXTENSION;

#[derive(Debug, thiserror::Error)]
pub enum FormatError {
    #[error("corrupt .pcraft bundle: {0}")]
    Corrupt(String),
    #[error("unsupported .pcraft feature: {0}")]
    Unsupported(String),
    #[error("bundle written by a newer version (format {found}, this build reads up to {supported})")]
    TooNew { found: u32, supported: u32 },
    #[error("limit exceeded: {0}")]
    LimitExceeded(String),
    #[error("`{path}` is NaN or infinite, which a .pcraft manifest cannot hold; reset that value and save again")]
    NonFinite { path: String },
    #[error("I/O: {0}")]
    Io(#[from] std::io::Error),
    #[error("manifest JSON: {0}")]
    Json(#[from] serde_json::Error),
}

impl FormatError {
    pub(crate) fn corrupt(msg: impl Into<String>) -> Self {
        FormatError::Corrupt(msg.into())
    }
}

impl From<craft_pcraft_format::Error> for FormatError {
    fn from(e: craft_pcraft_format::Error) -> Self {
        use craft_pcraft_format::Error;
        match e {
            Error::Corrupt(m) => FormatError::Corrupt(m),
            Error::Unsupported(m) => FormatError::Unsupported(m),
            Error::TooNew { found, supported, .. } => FormatError::TooNew { found, supported },
            Error::LimitExceeded(m) => FormatError::LimitExceeded(m),
            Error::Json(e) => FormatError::Json(e),
            other => FormatError::Corrupt(other.to_string()),
        }
    }
}

pub type Result<T> = std::result::Result<T, FormatError>;

/// Previews to embed. The format crate cannot render (it sits beside the
/// compositor), so callers provide them.
#[derive(Debug, Clone, Default)]
pub struct SaveOptions {
    pub thumbnail: Option<Rgba8Image>,
    pub composite: Option<Rgba8Image>,
    /// The flattened document at its canvas size, for other apps that read `.pcraft` files. A ZIP
    /// save leaves it out when it would take the archive past 4 GiB or 65,535 entries, and every
    /// save leaves it out when it cannot be encoded.
    pub full_composite: Option<Rgba8Image>,
    /// The ICC profile of `full_composite`'s pixels, embedded in its PNG.
    pub full_composite_icc: Option<Vec<u8>>,
}

/// Limits applied while loading untrusted bundles.
#[derive(Debug, Clone, Copy)]
pub struct LoadOptions {
    /// Maximum size of `manifest.json`.
    pub max_manifest_bytes: usize,
    /// Maximum size of one decompressed blob.
    pub max_blob_bytes: usize,
    /// Maximum total decompressed tile + blob bytes. The default follows the machine
    /// ([`total_budget`]).
    pub max_total_bytes: u64,
    /// Keep document and layer ids from the file (the id counter is advanced
    /// past them). When `false`, fresh ids are assigned.
    pub preserve_ids: bool,
    /// Longest canvas side the manifest may declare (Photoshop's PSB limit, as for PSD and
    /// `file.new`).
    pub max_canvas_side: u32,
    /// Most canvas pixels the manifest may declare. A canvas is a few bytes of JSON, but the
    /// compositor, thumbnails and display textures work in proportion to its area, so a caller
    /// handling untrusted files (a previewer, a batch job) may lower it. The default admits every
    /// canvas the app lets a user create.
    pub max_canvas_pixels: u64,
}

/// Default [`LoadOptions::max_canvas_side`].
pub const MAX_CANVAS_SIDE: u32 = 300_000;
/// Default [`LoadOptions::max_canvas_pixels`]: the full 300000 × 300000 PSB canvas. `file.new`,
/// Canvas Size, Image Size (Resample off) and PSB import all reach it, and a document that can be
/// created and saved must reopen. Loading itself stays proportional to the file: layers, masks
/// and channels are sparse tiles read from the bundle under the byte budgets, so a huge declared
/// canvas with no content allocates nothing for its area.
pub const MAX_CANVAS_PIXELS: u64 = MAX_CANVAS_SIDE as u64 * MAX_CANVAS_SIDE as u64;

/// Byte budgets of a load in the browser build. A wasm32 instance has at most 4 GiB of linear
/// memory, which the editor, the file's own bytes and the loaded document's composites share, so
/// the desktop defaults (1 GiB a blob, 16 GiB in all) would let a small, highly compressible
/// bundle exhaust it before any budget is reached.
#[cfg(target_arch = "wasm32")]
pub const BROWSER_MAX_BLOB_BYTES: usize = 512 << 20;
/// See [`BROWSER_MAX_BLOB_BYTES`].
#[cfg(target_arch = "wasm32")]
pub const BROWSER_MAX_TOTAL_BYTES: u64 = 1 << 30;

/// The least [`total_budget`] gives a machine whose memory is known, so a load isn't refused
/// because RAM is briefly short.
pub const MIN_TOTAL_BUDGET: u64 = 1 << 30;

/// The default [`LoadOptions::max_total_bytes`] (#8595): `cap` (the format's own limit), lowered to
/// what this machine can hold, the available RAM plus the room left on the scratch disk, but not
/// below [`MIN_TOTAL_BUDGET`]. Decoded tiles start in RAM and spill to the scratch disk as memory
/// fills, so both count. A bundle names each tile's decoded size, so a small file of nearly empty,
/// highly compressed tiles can ask for far more than the machine has; past this budget the load
/// stops with an error before decoding more, instead of the process running out of memory. With
/// neither figure known (the browser, an unknown platform), `cap` stands.
pub fn total_budget(cap: u64, available_ram: Option<u64>, scratch_room: Option<u64>) -> u64 {
    match (available_ram, scratch_room) {
        (None, None) => cap,
        (ram, scratch) => ram.unwrap_or(0).saturating_add(scratch.unwrap_or(0)).max(MIN_TOTAL_BUDGET).min(cap),
    }
}

impl Default for LoadOptions {
    fn default() -> Self {
        #[cfg_attr(not(target_arch = "wasm32"), allow(unused_mut))]
        let mut limits = craft_pcraft_format::Limits::default();
        #[cfg(target_arch = "wasm32")]
        {
            limits.max_blob_bytes = limits.max_blob_bytes.min(BROWSER_MAX_BLOB_BYTES);
            limits.max_total_bytes = limits.max_total_bytes.min(BROWSER_MAX_TOTAL_BYTES);
        }
        let ram = photocraft_raster::memory::system::current().available_ram;
        LoadOptions {
            max_manifest_bytes: limits.max_manifest_bytes,
            max_blob_bytes: limits.max_blob_bytes,
            max_total_bytes: total_budget(limits.max_total_bytes, ram, photocraft_raster::spill::scratch_capacity()),
            preserve_ids: true,
            max_canvas_side: MAX_CANVAS_SIDE,
            max_canvas_pixels: MAX_CANVAS_PIXELS,
        }
    }
}

/// `true` when ZIP bytes contain a `manifest.json` entry.
///
/// Bundles written here place the manifest first; re-zipped bundles may reorder entries.
pub fn is_pcraft(bytes: &[u8]) -> bool {
    craft_pcraft_bundle::is_pcraft_zip(bytes)
}

/// Save to an in-memory ZIP bundle (one-shot; use [`PcraftWriter`] for
/// incremental saves).
pub fn save_to_bytes(doc: &Document, opts: &SaveOptions) -> Result<Vec<u8>> {
    PcraftWriter::new().save_zip(doc, opts).map(|(b, _)| b)
}

/// Load a ZIP bundle from memory.
pub fn load_from_bytes(bytes: &[u8]) -> Result<Document> {
    load_from_bytes_with(bytes, &LoadOptions::default())
}

pub fn load_from_bytes_with(bytes: &[u8], opts: &LoadOptions) -> Result<Document> {
    let src = store::ZipSource::new(bytes)?;
    store::load(&src, opts)
}

/// Load while reporting the tile/blob bytes already counted by the native loader.
/// Nested-document consumers can share a byte allowance across embedded bundles, rather than
/// granting the full per-bundle allowance at every nesting level. This is not process RSS.
pub fn load_from_bytes_measured(bytes: &[u8], opts: &LoadOptions) -> Result<(Document, u64)> {
    let src = store::ZipSource::new(bytes)?;
    store::load_measured(&src, opts)
}

/// Load a bundle from a path: a directory bundle or a ZIP file.
pub fn load_path(path: &Path) -> Result<Document> {
    load_path_with(path, &LoadOptions::default())
}

/// Load from any byte source — a directory behind a capability handle, an archive, a test
/// fixture — the same migration and limits as the path loads.
pub fn load_bytes_source(src: &dyn ByteSource, opts: &LoadOptions) -> Result<Document> {
    store::load(src, opts)
}

pub fn load_path_with(path: &Path, opts: &LoadOptions) -> Result<Document> {
    if path.is_dir() {
        let source = store::DirSource::new(path, opts)?;
        store::load(&source, opts)
    } else {
        let bytes = read::read_file(path)?;
        load_from_bytes_with(&bytes, opts)
    }
}

/// Read and migrate only the manifest (fast: no tiles are decoded).
pub fn read_manifest(bytes: &[u8]) -> Result<Manifest> {
    let src = store::ZipSource::new(bytes)?;
    store::read_manifest(&src, &LoadOptions::default())
}

/// The embedded thumbnail, if present (PNG bytes).
pub fn read_thumbnail(bytes: &[u8]) -> Result<Option<Vec<u8>>> {
    let src = store::ZipSource::new(bytes)?;
    let m = store::read_manifest(&src, &LoadOptions::default())?;
    match m.thumbnail {
        Some(p) => Ok(Some(src.get(&p, 64 << 20)?)),
        None => Ok(None),
    }
}

/// The embedded full-size composite (PNG bytes): `None` when the manifest has no
/// `full_composite` member. A member that names any entry other than `composite/full.png` is
/// refused.
pub fn read_full_composite(bytes: &[u8]) -> Result<Option<Vec<u8>>> {
    let src = store::ZipSource::new(bytes)?;
    match store::read_full_composite_entry(&src, &LoadOptions::default())? {
        Some(p) => Ok(Some(src.get(p, bytes.len())?)),
        None => Ok(None),
    }
}