Define data types for ID-based resource handling (#4168)

* Add resource lib

* rename ResourceSource to ResourceInput

* Rename ResourceInput -> DataSource and improve API

* Review

---------

Co-authored-by: Dennis Kobert <dennis@kobert.dev>

node-graph/libraries/resources/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "graphene-resource"
+version = "0.1.0"
+edition = "2024"
+description = "graphene resource interface"
+authors = ["Graphite Authors <contact@graphite.art>"]
+license = "MIT OR Apache-2.0"
+
+[features]
+default = ["serde"]
+serde = ["dep:serde", "url/serde"]
+
+[dependencies]
+# Local dependencies
+dyn-any = { workspace = true }
+core-types = { workspace = true }
+
+# Workspace dependencies
+blake3 = { workspace = true }
+url = { workspace = true }
+
+# Optional workspace dependencies
+serde = { workspace = true, optional = true }

node-graph/libraries/resources/src/lib.rs

@@ -0,0 +1,269 @@
+use core_types::resource::Resource;
+use core_types::{CacheHash, graphene_hash};
+use dyn_any::DynAny;
+use std::collections::HashMap;
+use std::fmt;
+use std::future::Future;
+use std::hash::Hash;
+use std::pin::Pin;
+
+pub trait LoadResource: Send + Sync {
+	fn load(&self, hash: ResourceHash) -> ResourceFuture;
+}
+
+pub type ResourceFuture = Pin<Box<dyn Future<Output = Option<Resource>> + Send + 'static>>;
+
+pub trait ResourceStorage: LoadResource {
+	fn store(&mut self, data: &[u8]) -> ResourceHash;
+	fn contains(&mut self, hash: &ResourceHash) -> bool;
+	fn garbage_collect(&mut self, used: &[ResourceHash]);
+}
+
+#[repr(transparent)]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, graphene_hash::CacheHash, PartialOrd, Ord, DynAny)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct ResourceId(pub u64);
+
+impl ResourceId {
+	pub fn new() -> Self {
+		Self(core_types::uuid::generate_uuid())
+	}
+}
+
+impl std::fmt::Display for ResourceId {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		write!(f, "{}", self.0)
+	}
+}
+
+/// Blake3 content hash of a resource, represented as 32 bytes
+#[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq, PartialOrd, Ord, DynAny)]
+pub struct ResourceHash([u8; 32]);
+
+impl From<&[u8]> for ResourceHash {
+	fn from(data: &[u8]) -> Self {
+		Self(blake3::hash(data).into())
+	}
+}
+
+impl From<[u8; 32]> for ResourceHash {
+	fn from(bytes: [u8; 32]) -> Self {
+		Self(bytes)
+	}
+}
+
+impl From<&ResourceHash> for [u8; 32] {
+	fn from(hash: &ResourceHash) -> Self {
+		hash.0
+	}
+}
+
+impl From<&ResourceHash> for String {
+	fn from(hash: &ResourceHash) -> Self {
+		const HEX: &[u8; 16] = b"0123456789abcdef";
+		let mut out = String::with_capacity(hash.0.len() * 2);
+		for byte in &hash.0 {
+			out.push(HEX[(byte >> 4) as usize] as char);
+			out.push(HEX[(byte & 0x0f) as usize] as char);
+		}
+		out
+	}
+}
+
+impl fmt::Display for ResourceHash {
+	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+		f.write_str(&String::from(self))
+	}
+}
+
+impl std::str::FromStr for ResourceHash {
+	type Err = ResourceHashParseError;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		fn decode_hex_nibble(byte: u8, position: usize) -> Result<u8, ResourceHashParseError> {
+			match byte {
+				b'0'..=b'9' => Ok(byte - b'0'),
+				b'a'..=b'f' => Ok(byte - b'a' + 10),
+				b'A'..=b'F' => Ok(byte - b'A' + 10),
+				_ => Err(ResourceHashParseError::InvalidCharacter { byte, position }),
+			}
+		}
+
+		let bytes = s.as_bytes();
+		if bytes.len() != 64 {
+			return Err(ResourceHashParseError::InvalidLength { found: bytes.len() });
+		}
+
+		let mut out = [0u8; 32];
+		for (index, chunk) in bytes.chunks_exact(2).enumerate() {
+			let high = decode_hex_nibble(chunk[0], index * 2)?;
+			let low = decode_hex_nibble(chunk[1], index * 2 + 1)?;
+			out[index] = (high << 4) | low;
+		}
+
+		Ok(Self(out))
+	}
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ResourceHashParseError {
+	InvalidLength { found: usize },
+	InvalidCharacter { byte: u8, position: usize },
+}
+
+impl fmt::Display for ResourceHashParseError {
+	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+		match self {
+			Self::InvalidLength { found } => write!(f, "resource hash must be 64 hex characters, got {found}"),
+			Self::InvalidCharacter { byte, position } => write!(f, "resource hash contains non-hex byte {byte:#04x} at position {position}"),
+		}
+	}
+}
+
+impl std::error::Error for ResourceHashParseError {}
+
+impl TryFrom<&str> for ResourceHash {
+	type Error = ResourceHashParseError;
+
+	fn try_from(value: &str) -> Result<Self, Self::Error> {
+		value.parse()
+	}
+}
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for ResourceHash {
+	fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+		if serializer.is_human_readable() {
+			serializer.serialize_str(&String::from(self))
+		} else {
+			serializer.serialize_bytes(&self.0)
+		}
+	}
+}
+
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for ResourceHash {
+	fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+		struct ResourceHashVisitor;
+
+		impl<'de> serde::de::Visitor<'de> for ResourceHashVisitor {
+			type Value = ResourceHash;
+
+			fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+				formatter.write_str("a 64-character hex string or 32 raw bytes")
+			}
+
+			fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<Self::Value, E> {
+				ResourceHash::try_from(value).map_err(E::custom)
+			}
+
+			fn visit_bytes<E: serde::de::Error>(self, value: &[u8]) -> Result<Self::Value, E> {
+				let bytes: [u8; 32] = value.try_into().map_err(|_| E::invalid_length(value.len(), &"32 bytes"))?;
+				Ok(ResourceHash(bytes))
+			}
+
+			fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
+				let mut bytes = [0u8; 32];
+				for (i, slot) in bytes.iter_mut().enumerate() {
+					*slot = seq.next_element()?.ok_or_else(|| serde::de::Error::invalid_length(i, &"32 bytes"))?;
+				}
+				Ok(ResourceHash(bytes))
+			}
+		}
+
+		if deserializer.is_human_readable() {
+			deserializer.deserialize_str(ResourceHashVisitor)
+		} else {
+			deserializer.deserialize_bytes(ResourceHashVisitor)
+		}
+	}
+}
+
+impl CacheHash for ResourceHash {
+	fn cache_hash<H: core::hash::Hasher>(&self, state: &mut H) {
+		core::hash::Hash::hash(self, state);
+	}
+}
+
+#[derive(Clone, Debug)]
+pub struct ResourceInfo {
+	pub id: ResourceId,
+	pub hash: Option<ResourceHash>,
+	pub inputs: DataSources,
+}
+
+pub type DataSources = Box<[DataSource]>;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum DataSource {
+	Embedded,
+	Url(url::Url),
+	Font { family: String, style: Option<String> },
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct ResourceRegistry {
+	hashes: HashMap<ResourceId, ResourceHash>,
+	sources: HashMap<ResourceId, Vec<DataSource>>,
+}
+
+impl ResourceRegistry {
+	pub fn new() -> Self {
+		Self::default()
+	}
+
+	pub fn is_empty(&self) -> bool {
+		self.hashes.is_empty() && self.sources.is_empty()
+	}
+
+	pub fn contains(&self, id: &ResourceId) -> bool {
+		self.hashes.contains_key(id) || self.sources.contains_key(id)
+	}
+
+	pub fn ids(&self) -> impl Iterator<Item = ResourceId> + '_ {
+		self.hashes.keys().chain(self.sources.keys().filter(|id| !self.hashes.contains_key(id))).copied()
+	}
+
+	pub fn info(&self, id: &ResourceId) -> Option<ResourceInfo> {
+		self.contains(id).then(|| ResourceInfo {
+			id: *id,
+			hash: self.hashes.get(id).copied(),
+			inputs: self.sources.get(id).cloned().unwrap_or_default().into_boxed_slice(),
+		})
+	}
+
+	pub fn push_source_back(&mut self, id: &ResourceId, source: DataSource) {
+		self.sources.entry(*id).or_default().push(source);
+	}
+
+	pub fn push_source_front(&mut self, id: &ResourceId, source: DataSource) {
+		self.sources.entry(*id).or_default().insert(0, source);
+	}
+
+	pub fn delete(&mut self, id: &ResourceId) -> Option<ResourceInfo> {
+		let hash = self.hashes.remove(id);
+		let sources = self.sources.remove(id);
+		if hash.is_none() && sources.is_none() {
+			return None;
+		}
+		Some(ResourceInfo {
+			id: *id,
+			hash,
+			inputs: sources.unwrap_or_default().into_boxed_slice(),
+		})
+	}
+
+	pub fn resolve(&mut self, id: &ResourceId, hash: ResourceHash) -> Option<ResourceHash> {
+		self.hashes.insert(*id, hash)
+	}
+
+	pub fn hash(&self, id: &ResourceId) -> Option<ResourceHash> {
+		self.hashes.get(id).copied()
+	}
+
+	pub fn unresolved(&self) -> impl Iterator<Item = (ResourceId, &[DataSource])> + '_ {
+		self.sources.iter().filter(|(id, _)| !self.hashes.contains_key(id)).map(|(id, sources)| (*id, sources.as_slice()))
+	}
+}