versatiles_container 3.7.0

//! Defines the interface for writing tile data to various container formats.
//!
//! This module provides the object‑safe [`TilesWriter`], which enables writing tiles
//! from any [`TileSource`] source into a file or arbitrary output writer implementing
//! [`DataWriterTrait`].
//!
//! Implementations of this trait are registered in the [`ContainerRegistry`] to handle specific
//! output formats (e.g. `.mbtiles`, `.pmtiles`, `.versatiles`, `.tar`, or directory trees).
//!
//! ## Responsibilities
//! A tile writer must:
//! - Pull tiles from a [`TileSource`] source (possibly streamed)
//! - Serialize them to the target format
//! - Respect [`TilesRuntime`] parameters such as compression and parallelism
//!
//! ## Example
//! ```rust
//! use versatiles_container::*;
//! use versatiles_core::*;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     let runtime = TilesRuntime::default();
//!     let reader = runtime.get_reader_from_str("../testdata/berlin.mbtiles").await?;
//!     let output_path = std::env::temp_dir().join("example.versatiles");
//!
//!     // The runtime automatically dispatches to the correct writer
//!     runtime.write_to_path(reader, &output_path).await?;
//!     Ok(())
//! }
//! ```

use crate::{TileSource, TilesRuntime};
use anyhow::Result;
use async_trait::async_trait;
use std::path::Path;
use versatiles_core::io::{DataWriterFile, DataWriterTrait};

/// Object‑safe interface for writing tiles from a reader into a container format.
///
/// Writers implement serialization to a specific format (e.g., `MBTiles`, `VersaTiles`, TAR),
/// and can operate either on filesystem paths or any sink implementing [`DataWriterTrait`].
///
/// Implementors should handle compression, metadata, and configuration from [`TilesRuntime`].
#[async_trait]
pub trait TilesWriter: Send {
	/// Writes all tile data from `reader` into the file or directory at `path`.
	///
	/// The default implementation wraps `path` in a [`DataWriterFile`] and calls
	/// [`TilesWriter::write_to_writer`]. Implementations may override this for more efficient
	/// file handling.
	///
	/// # Errors
	/// Returns an error if the file cannot be created or the writing operation fails.
	async fn write_to_path(reader: &mut dyn TileSource, path: &Path, runtime: TilesRuntime) -> Result<()> {
		Self::write_to_writer(reader, &mut DataWriterFile::from_path(path)?, runtime).await
	}

	/// Writes tile data from `reader` to the provided [`DataWriterTrait`] sink.
	///
	/// Implementations must serialize tiles according to their format and use the
	/// [`TilesRuntime`] to control parallelism, buffering, compression, and emit events.
	///
	/// # Arguments
	/// - `reader`: Source tile reader providing tile data.
	/// - `writer`: Output sink implementing [`DataWriterTrait`].
	/// - `runtime`: Runtime configuration (cache type, event bus, progress factory, etc.).
	///
	/// # Errors
	/// Returns an error if reading from the source or writing to the sink fails.
	async fn write_to_writer(
		reader: &mut dyn TileSource,
		writer: &mut dyn DataWriterTrait,
		runtime: TilesRuntime,
	) -> Result<()>;
}