Struct PersonalCacheRoot 

pub struct PersonalCacheRoot { /* private fields */ }

Root directory of the personal thumbnail cache, usually $XDG_CACHE_HOME/thumbnails.

Implementations

impl PersonalCacheRoot

pub fn new(path: impl AsRef<Path>) -> Result<Self>

Creates a cache root from an already resolved absolute thumbnail root path.

Errors

Returns an error when path is not absolute.

pub fn resolve_from_env() -> Result<Self>

Resolves the personal thumbnail cache root from the process environment.

Errors

Returns an error when neither an absolute XDG_CACHE_HOME nor an absolute HOME fallback is available.

pub fn resolve_from_values( xdg_cache_home: Option<&OsStr>, home: Option<&OsStr>, ) -> Result<Self>

Resolves the personal thumbnail cache root from supplied XDG values.

Relative, unset, and blank XDG_CACHE_HOME values are ignored. HOME must be absolute when fallback is needed.

Errors

Returns an error when the resolved thumbnail root would not be absolute.

pub fn as_path(&self) -> &Path

Returns the resolved thumbnail root path.

pub fn cache_entry_path( &self, uri: &PersonalOriginalUri, namespace: &CacheNamespace, ) -> PathBuf

Computes the personal-cache path for an accepted URI and namespace without reading it.

pub fn cache_entry_handle( &self, uri: &PersonalOriginalUri, namespace: &CacheNamespace, ) -> CacheEntryHandle

Returns a safe-removal handle for a computed personal-cache entry path.

The handle uses the same pure path calculation as Self::cache_entry_path and does not check whether the entry currently exists. Removal still performs containment, no-follow, and regular-file checks at deletion time.

pub fn lookup_thumbnail_path( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<ThumbnailPathLookupEntry>>

Returns a validated personal-cache path for integrations that must pass a filename.

The original identity must have already been confirmed readable. The candidate PNG is opened and validated before this method returns. Callers that reopen the returned path accept that another process may replace it after validation.

Errors

Returns an error for unexpected filesystem I/O while reading the candidate or for PNG metadata parse failures after validation succeeds.

pub fn lookup_thumbnail_png_bytes( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<ThumbnailPngBytesLookupEntry>>

Returns exact validated PNG bytes from the personal thumbnail cache.

The original identity must have already been confirmed readable.

Errors

Returns an error for unexpected filesystem I/O while reading the candidate or for PNG metadata parse failures after validation succeeds.

pub fn lookup_thumbnail_rgba8( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<ThumbnailRgba8LookupEntry>>

Returns decoded tightly packed RGBA8 pixels from the personal thumbnail cache.

The original identity must have already been confirmed readable. The returned pixels are row-major [red, green, blue, alpha] bytes with straight alpha and stride == width * 4.

Errors

Returns an error for unexpected filesystem I/O while reading the candidate or for PNG decoding failures after validation succeeds.

pub fn lookup_display_thumbnail_rgba8( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<DisplayThumbnailRgba8LookupEntry>>

Returns decoded RGBA8 display pixels, falling back to larger personal-cache namespaces.

The exact namespace is checked first. If it is missing, larger namespaces are checked in ascending order. The first non-missing candidate controls the result.

Errors

Returns an error for unexpected filesystem I/O while reading the candidate or for PNG decoding failures after validation succeeds.

pub fn install_thumbnail_returning_path( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, rendered_png: &[u8], ) -> Result<InstalledThumbnailPath>

Normalizes rendered PNG data, atomically installs a personal-cache thumbnail, and returns its path.

Errors

Returns an error when rendered PNG normalization fails, final thumbnail validation fails, cache directories are unavailable or insecure, or atomic installation fails.

pub fn install_thumbnail_returning_png_bytes( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, rendered_png: &[u8], ) -> Result<InstalledThumbnailPngBytes>

Normalizes rendered PNG data, atomically installs a personal-cache thumbnail, and returns final PNG bytes.

Errors

Returns an error when rendered PNG normalization fails, final thumbnail validation fails, cache directories are unavailable or insecure, or atomic installation fails.

pub fn install_raw_thumbnail_returning_path( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, image: RawThumbnailImage<'_>, ) -> Result<InstalledThumbnailPath>

Normalizes raw pixel data, atomically installs a personal-cache thumbnail, and returns its path.

Errors

Returns an error when raw conversion or normalization fails, final thumbnail validation fails, cache directories are unavailable or insecure, or atomic installation fails.

pub fn install_raw_thumbnail_returning_png_bytes( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, image: RawThumbnailImage<'_>, ) -> Result<InstalledThumbnailPngBytes>

Normalizes raw pixel data, atomically installs a personal-cache thumbnail, and returns final PNG bytes.

Errors

Returns an error when raw conversion or normalization fails, final thumbnail validation fails, cache directories are unavailable or insecure, or atomic installation fails.

pub fn materialize_thumbnail_from_larger_cache_returning_path( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<MaterializedThumbnailPath>>

Materializes the requested personal-cache namespace from an exact or larger personal entry.

Errors

Returns an error when final PNG normalization, validation, or atomic installation fails.

pub fn materialize_thumbnail_from_larger_cache_returning_png_bytes( &self, original: &ReadablePersonalOriginalIdentity, size: ThumbnailSize, ) -> Result<PersonalThumbnailLookup<MaterializedThumbnailPngBytes>>

Materializes the requested personal-cache namespace and returns final target PNG bytes.

Errors

Returns an error when final PNG normalization, validation, or atomic installation fails.

pub fn materialize_shared_thumbnail_returning_path( &self, shared: &SharedRepositoryContext, original_facts: SharedOriginalFacts, size: ThumbnailSize, ) -> Result<SharedThumbnailLookup<MaterializedThumbnailPath>>

Materializes a shared thumbnail into this personal cache and returns the target path.

Shared repositories are read-only; this method writes only to the receiver personal cache.

Errors

Returns an error when shared facts cannot produce required personal metadata, final PNG normalization fails, or atomic installation fails.

pub fn materialize_shared_thumbnail_returning_png_bytes( &self, shared: &SharedRepositoryContext, original_facts: SharedOriginalFacts, size: ThumbnailSize, ) -> Result<SharedThumbnailLookup<MaterializedThumbnailPngBytes>>

Materializes a shared thumbnail into this personal cache and returns final target PNG bytes.

Shared repositories are read-only; this method writes only to the receiver personal cache.

Errors

Returns an error when shared facts cannot produce required personal metadata, final PNG normalization fails, or atomic installation fails.

pub fn write_failure_entry_returning_path( &self, original: &ReadablePersonalOriginalIdentity, namespace: &FailureNamespace, ) -> Result<InstalledThumbnailPath>

Writes a deterministic 1x1 transparent failure entry and returns its path.

Errors

Returns an error when failure-entry PNG encoding fails, cache directories are unavailable or insecure, or atomic installation fails.

pub fn write_failure_entry_returning_png_bytes( &self, original: &ReadablePersonalOriginalIdentity, namespace: &FailureNamespace, ) -> Result<InstalledThumbnailPngBytes>

Writes a deterministic 1x1 transparent failure entry and returns final PNG bytes.

Errors

Returns an error when failure-entry PNG encoding fails, cache directories are unavailable or insecure, or atomic installation fails.

impl PersonalCacheRoot

pub fn inspect_thumbnails( &self, sizes: &[ThumbnailSize], nonstandard_entry_policy: NonstandardEntryPolicy, ) -> Result<Vec<CacheEntryInspection>>

Inspects standard successful thumbnail size directories.

Errors

Returns an error when a selected namespace directory cannot be inspected.

pub fn inspect_failure_entries( &self, nonstandard_entry_policy: NonstandardEntryPolicy, ) -> Result<Vec<CacheEntryInspection>>

Inspects direct files in immediate real failure-entry namespaces.

Errors

Returns an error when the failure root or a selected failure namespace cannot be inspected.

Trait Implementations

impl AsRef<Path> for PersonalCacheRoot

fn as_ref(&self) -> &Path

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for PersonalCacheRoot

fn clone(&self) -> PersonalCacheRoot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PersonalCacheRoot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for PersonalCacheRoot

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PersonalCacheRoot

fn eq(&self, other: &PersonalCacheRoot) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for PersonalCacheRoot

impl StructuralPartialEq for PersonalCacheRoot