alizarin_core/
tile_source.rs

1// SPDX-License-Identifier: AGPL-3.0-or-later
2// Copyright (C) 2026 Flax & Teal Limited
3
4//! Pluggable tile source trait for loading tiles from external backends.
5//!
6//! This trait allows compiled-in tile sources (e.g. Rós Madair index files)
7//! to provide tiles directly in Rust, avoiding FFI overhead when the tile
8//! source and alizarin are compiled into the same binary.
9//!
10//! Platform wrappers (WASM, Python) check for a registered `TileSource`
11//! before falling back to their platform-specific callback mechanisms.
12
13use crate::graph::StaticTile;
14use std::fmt;
15
16/// Error type for tile source operations.
17#[derive(Debug, Clone)]
18pub enum TileSourceError {
19    /// The requested resource was not found in this tile source.
20    /// Callers may fall through to alternative tile loading mechanisms.
21    ResourceNotFound { resource_id: String },
22    /// A hard error occurred during tile loading.
23    /// Callers should propagate this rather than falling through.
24    LoadError(String),
25}
26
27impl fmt::Display for TileSourceError {
28    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
29        match self {
30            TileSourceError::ResourceNotFound { resource_id } => {
31                write!(f, "Resource not found: {}", resource_id)
32            }
33            TileSourceError::LoadError(msg) => {
34                write!(f, "Tile load error: {}", msg)
35            }
36        }
37    }
38}
39
40impl std::error::Error for TileSourceError {}
41
42/// A synchronous source of tile data for resource instances.
43///
44/// Implementations provide tiles from various backends (index files, databases,
45/// in-memory caches) without the consumer needing to know the specifics.
46///
47/// This trait is intentionally synchronous. For async tile sources (e.g. JS
48/// callbacks fetching over HTTP), platform wrappers use their own callback
49/// mechanisms. `TileSource` is the fast path for compiled-together Rust code.
50pub trait TileSource: Send + Sync {
51    /// Load tiles for a resource.
52    ///
53    /// # Parameters
54    /// - `resource_id`: Bare resource instance UUID (not a full URI).
55    ///   The implementation handles URI construction internally.
56    /// - `nodegroup_id`: Optional filter hint. If `Some`, implementations
57    ///   may return only tiles for that nodegroup. If `None`, all tiles
58    ///   for the resource should be returned.
59    fn load_tiles(
60        &self,
61        resource_id: &str,
62        nodegroup_id: Option<&str>,
63    ) -> Result<Vec<StaticTile>, TileSourceError>;
64}
alizarin_core/tile_source.rs

alizarin_core/
tile_source.rs
