ifc_lite_server/routes/parse/

cache_keys.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! Cache-key builders and symbolic-data cache helpers shared by the parse endpoints.

use super::ParseQuery;
use crate::services::cache::DiskCache;
use crate::services::{DataModelEntities, OpeningFilterMode, ParquetLayout};
use ifc_lite_processing::{SymbolicDataWithProvenance, TessellationQuality};

/// Cache-key segment for a tessellation level. Empty for the default level so
/// every pre-existing cache entry (all written at implicit `medium`) stays
/// valid; non-default levels get distinct entries.
pub(super) fn quality_cache_suffix(quality: TessellationQuality) -> String {
    if quality == TessellationQuality::default() {
        String::new()
    } else {
        format!("-q{}", quality.label())
    }
}

/// The seed every derived key is built on: file hash + opening-filter suffix +
/// quality suffix. Endpoints that receive a bare hash (the cache-check and
/// cached-geometry routes) rebuild it from the query rather than from bytes
/// they do not have.
pub(crate) fn cache_key_from_parts(
    hash: &str,
    opening_filter: OpeningFilterMode,
    quality: TessellationQuality,
) -> String {
    format!(
        "{}-{}{}",
        hash,
        opening_filter.cache_key_suffix(),
        quality_cache_suffix(quality)
    )
}

/// Whether `hash` has the shape [`DiskCache::generate_key`] produces: 64
/// lowercase hex characters.
///
/// Lives beside [`cache_key_from_parts`] because that is what it protects. The
/// hash a client supplies is concatenated into `{hash}-{filter}{quality}` and
/// the namespace suffix (`-parquet-v8`, `-datamodel-v8`, ...) is appended after
/// it, so a caller-shaped string is a caller-shaped cache key. Checking the
/// shape keeps the value to the one job it has, naming a file.
///
/// Applied by the hash-only stream probe (#3901). The two older hash-taking
/// endpoints, `check_cache` and `get_cached_geometry`, do NOT call it yet: a
/// malformed hash there names a key nobody wrote and gets a 404, which is a
/// correct answer by a different route. Tightening them is a behaviour change
/// to a published surface and is deliberately not part of #3901.
pub(crate) fn is_file_digest(hash: &str) -> bool {
    hash.len() == 64 && hash.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))
}

/// The one rejection for a path segment that is not a file digest, shared by
/// every route that takes one so the rule is spelled once. The value itself
/// is not echoed: it is caller-controlled text, and its length plus the rule
/// is all a caller needs.
pub(crate) fn not_a_file_digest(value: &str) -> crate::error::ApiError {
    crate::error::ApiError::BadRequest(format!(
        "expected a file's sha256 content hash (64 lowercase hex characters); got {} character(s)",
        value.chars().count()
    ))
}

/// Request-level cache key: file hash + opening-filter suffix + quality suffix.
pub(crate) fn request_cache_key(data: &[u8], query: &ParseQuery, quality: TessellationQuality) -> String {
    cache_key_from_parts(
        &DiskCache::generate_key(data),
        query.opening_filter,
        quality,
    )
}

/// Typed `ParseResponse` cache key for the JSON transport.
///
/// Versioned SEPARATELY from [`request_cache_key`], which is the client-facing
/// identifier and the seed for the parquet keys — bumping that would needlessly
/// invalidate every parquet entry too.
///
/// Introduced at `v2` with issue #1841: the JSON route now emits Y-up meshes
/// like every other transport, so the pre-existing (unversioned) entries hold
/// raw IFC Z-up meshes and would silently serve a ROTATED model to a client
/// that rightly expects the uniform wire frame. A new suffix retires them.
/// v3 adds direct symbolic fill provenance (#4459), retiring otherwise valid
/// JSON responses that cannot suppress duplicate 3D fills.
/// v4 adds the `IfcMapConversionScaled` factors to `metadata.georeferencing`
/// (#4653). A v3 entry has no factor fields, decodes cleanly with every factor
/// defaulted to 1, and a client applying them places a scaled file wrong.
/// v5 carries the embedded `symbolic_data` in the frame this response's own
/// meshes are in (#4706). This entry is the whole response, symbols included,
/// and it is returned BEFORE any extraction runs, so bumping
/// [`symbolic_cache_key`] alone leaves the JSON endpoint replaying old-frame
/// symbols for every file already on disk: measured on a translated, rotated
/// site, a planted v4 entry came back with its grid axis at `(500, -300)`
/// where the live parse puts it at `(0, 0)`.
/// Bump again on any change to what `ParseResponse` means on the wire.
pub(crate) fn json_response_cache_key(cache_key: &str) -> String {
    format!("{cache_key}-json-v6")
}

/// The flat Parquet geometry entry for a request cache key, under the LAYOUT
/// the client asked for.
///
/// THE definition of that suffix. It used to be a `format!` literal repeated in
/// `parse_parquet` (twice), `parse_parquet_stream`, `try_cached_replay` and
/// here, kept equal by a comment saying they bump together -- four writers and
/// readers of one cache slot held together by prose, where a missed bump gives
/// a reader looking up a key nobody writes, or worse a writer storing under a
/// version an old reader still serves.
///
/// The two layouts get SEPARATE namespaces (`-parquet-v8` / `-parquet-v9`,
/// from `ParquetLayout::cache_suffix`) rather than one versioned slot, and the
/// reason is that a version bump cannot do the job here. A cache key
/// namespaces server-side entries; it has no bearing on which client is
/// asking. Bumping one shared key would have retired the v5 entries and then
/// handed every client -- including one pinned to a `@ifc-lite/server-client`
/// that predates #3888 -- a freshly generated v6 blob it decodes without error
/// and draws wrong. Two namespaces plus an opt-in signal means a client that
/// did not ask for the shared layout can never be served it, from cache or
/// from a live parse, and the two entries coexist instead of evicting each
/// other on every request.
///
/// `v8` / `v9` since #5984 added the `metallic` / `roughness` finish columns:
/// an older entry replays with no finish, where absence reads exactly like
/// "unauthored" (the same reason #3215 took the flat layout v4 -> v5 for the
/// source-id columns). Neither reuses `v6`: that was the shared layout's
/// namespace before #5130 moved it to `v7`, and such blobs may still be on disk.
pub(crate) fn parquet_geometry_key(cache_key: &str, layout: ParquetLayout) -> String {
    format!("{cache_key}-{}", layout.cache_suffix())
}

/// The flat Parquet metadata entry (the `X-IFC-Metadata` header) for a request
/// cache key. THE definition of that suffix, for the same reason as above.
///
/// NOT keyed by layout, and not versioned alongside the geometry: it holds the
/// metadata header, whose shape #3888 did not touch and which is identical for
/// both layouts of the same file. A hit needs the geometry entry too, so the
/// layouts still cannot cross-serve.
///
/// `v5` with #4653: the header's `metadata.georeferencing` gained the
/// `IfcMapConversionScaled` factors, and a `v4` header replays them as 1 (see
/// [`json_response_cache_key`]). The geometry keys stay put: a miss here
/// re-parses, and the parse rewrites the geometry entry beside it.
pub(crate) fn parquet_metadata_key(cache_key: &str) -> String {
    format!("{cache_key}-parquet-metadata-v5")
}

/// Build the parquet geometry cache key from a file hash and opening filter,
/// for the endpoints that receive a bare hash rather than the bytes.
pub(crate) fn parquet_cache_key(
    hash: &str,
    opening_filter: OpeningFilterMode,
    quality: TessellationQuality,
    layout: ParquetLayout,
) -> String {
    parquet_geometry_key(&cache_key_from_parts(hash, opening_filter, quality), layout)
}

/// Build the parquet metadata cache key for a given file hash and opening filter.
pub(crate) fn parquet_metadata_cache_key(
    hash: &str,
    opening_filter: OpeningFilterMode,
    quality: TessellationQuality,
) -> String {
    parquet_metadata_key(&cache_key_from_parts(hash, opening_filter, quality))
}

/// Build the optimized-Parquet body cache key for a given file cache key.
///
/// `POST /api/v1/parse/parquet/optimized` was added without a key of its own,
/// so its response had nowhere to be stored and every request re-parsed the
/// file while the flat route beside it replayed from disk (issue #3889). This
/// is that key.
///
/// Deliberately a DIFFERENT namespace from `-parquet-v9`: the two routes emit
/// different payloads (quantized vertices, deduplicated shapes, byte colours),
/// so a hit on one must never satisfy the other.
///
/// `v1` is the ara3d BOS payload as it stands after #3595 (rotation-aware
/// instancing). Bump on EVERY change to the optimized payload's columns, to
/// what one of them means, OR to the geometry pipeline behind them -- this key
/// covers `process_geometry_filtered_with_quality` output just as
/// [`parquet_cache_key`] does, and that key's own `v3` -> `v4` bump was a
/// pipeline change with no column change at all. In practice: a bump of
/// `-parquet-v9` almost always needs a bump here too. Otherwise a warm cache
/// replays a pre-change blob that the decoder reads cleanly, and the change is
/// silently absent.
///
/// `v2` with #5130: `MeshGeometryKey` gained `normals_hash`. The pipeline
/// derives normals from positions and indices, so no optimized payload is
/// expected to change -- bumped under this key's own rule (every change to
/// the dedup behind the payload) rather than on that invariant, at the cost
/// of one re-parse per warm file.
pub(crate) fn parquet_optimized_cache_key(cache_key: &str) -> String {
    format!("{cache_key}-parquet-optimized-v3")
}

/// Build the optimized-Parquet metadata cache key for a given file cache key.
///
/// Holds the serialized `X-IFC-Metadata` header, `optimization_stats` included,
/// so a replay carries the same stats the live parse reported. Distinct from
/// the flat route's `-parquet-metadata-v5` for the same reason the bodies are.
/// A replay needs both entries, so bumping either one retires the pair.
///
/// `v2` with #4653: the header's `metadata.georeferencing` gained the
/// `IfcMapConversionScaled` factors. The body keeps `v1`: a metadata miss
/// re-parses, and the parse rewrites the body in place.
/// `v3` with #5129: the header gained `data_model_stats`, mirroring
/// `ParquetMetadataHeader`. A `v2` header replays with the field absent, which
/// is a correct decode (`#[serde(skip_serializing_if)]`) of a header that
/// silently no longer describes what this route now does -- it produces a
/// data model too. The body keeps `v1`: a metadata miss re-parses, and the
/// parse rewrites the body (and now the data model) in place.
pub(crate) fn parquet_optimized_metadata_cache_key(cache_key: &str) -> String {
    format!("{cache_key}-parquet-optimized-metadata-v3")
}

/// Build the data-model cache key for a given file cache key.
///
/// One definition for the writers (`parse_parquet`, `parse_parquet_stream`) and
/// the reader (`get_data_model`): three separate literals could disagree, and a
/// reader looking up a key nobody writes answers `202` forever.
///
/// The suffix bumps on EVERY change to the data-model payload's columns.
/// `v8` adds complete material association fields (#5296); a warm `v7` cache
/// cannot support material value checks even after the server is upgraded.
///
/// The entities VARIANT (#6034) is a separate namespace, not a version:
/// `-datamodel-v8` for every STEP instance (unchanged, so a default request
/// keeps hitting the entries already on disk) and `-datamodel-rooted-v8` for
/// the rooted-only table. Both carry the one version number, so a payload bump
/// retires both at once. They coexist, and neither can answer for the other:
/// a client that asked for the rooted table must not be handed 60 MB it asked
/// not to download, and one that did not must not lose rows it looks up.
pub(crate) fn data_model_cache_key(cache_key: &str, entities: DataModelEntities) -> String {
    format!("{cache_key}-datamodel{}-v8", entities.cache_infix())
}

/// Whether a data model at the CURRENT payload version is cached for
/// `cache_key`.
///
/// Geometry and the data model are versioned separately, so a geometry entry
/// outlives a data-model bump. Every geometry short-circuit must ask this
/// before returning early: without it a deployment holding pre-bump entries
/// reports a geometry hit, the client skips the upload (or the replay path
/// skips the parse), nothing ever writes the current data-model key, and
/// `fetchDataModel` polls a key nobody writes until it times out — geometry on
/// screen with no properties and no error (issue #3869). Answering `false`
/// costs one re-parse and rewrites both entries.
///
/// A cache read error answers `false`: re-parsing is the safe direction.
///
/// Asks about the entities VARIANT the request selects (#6034): a replay that
/// skips the parse must not strand a client polling for the rooted table when
/// only the full one was ever written, or the reverse.
pub(crate) async fn has_current_data_model(
    cache: &DiskCache,
    cache_key: &str,
    entities: DataModelEntities,
) -> bool {
    has_entry(cache, &data_model_cache_key(cache_key, entities)).await
}

/// Whether the optimized-Parquet metadata header is cached for `cache_key`.
///
/// The cheap pre-filter for the optimized route's `?sha256=` probe (#5128),
/// mirroring [`has_parquet_metadata`] for the flat route: a few hundred bytes,
/// against the body's whole-model size. It is never the decision --
/// [`super::parquet_optimized_replay::try_cached_optimized_parquet`] still
/// makes that, and a metadata entry present with no body beside it (or no
/// symbolic sidecar) still falls through to the 404 the probe answers on a
/// miss.
pub(crate) async fn has_optimized_metadata(cache: &DiskCache, cache_key: &str) -> bool {
    has_entry(cache, &parquet_optimized_metadata_cache_key(cache_key)).await
}

/// Whether the Parquet metadata header is cached for `cache_key`.
///
/// The cheap half of "is this replayable": the header is a few hundred bytes,
/// where the geometry blob is the whole model. The hash-only stream probe
/// (#3901) asks this, plus [`has_current_data_model`], BEFORE it takes an
/// admission slot, so the common miss (a file the server has never seen) is
/// answered by two small reads rather than by charging a parse slot for a disk
/// lookup. `check_cache` asks it too, because its hit sends the client to a
/// fetch that needs the header (#4675). It is a pre-filter, never the
/// decision: [`try_cached_replay`] still makes that, and a metadata entry
/// present here with no geometry beside it falls through to the same 404.
///
/// [`try_cached_replay`]: super::cached_replay::try_cached_replay
pub(crate) async fn has_parquet_metadata(cache: &DiskCache, cache_key: &str) -> bool {
    has_entry(cache, &parquet_metadata_key(cache_key)).await
}

/// Whether `key` has a readable entry.
///
/// Reads the value rather than asking `DiskCache::has`, which is an index
/// lookup only: an index row whose content is gone would answer `true` here
/// while every real reader still gets nothing, and a gate that reports present
/// for an entry nobody can read is worse than no gate.
///
/// A read error answers `false`: re-parsing is the safe direction.
async fn has_entry(cache: &DiskCache, key: &str) -> bool {
    matches!(cache.get_bytes(key).await, Ok(Some(_)))
}

/// Build the symbolic-data cache key for a given file cache key.
/// v2 requires direct fill provenance (#4459); v1 remains decodable but is
/// not a fresh extraction for 3D routing. Geometry namespaces stay unchanged.
/// v3 re-bases the stream by the mesh frame selection, placement-bounds
/// fallback included (#4665). A v2 entry for a model the sampler cannot read
/// is left unshifted, up to the whole offset away from the meshes.
/// v4 re-bases it by the frame the SERVER's own meshes were baked in rather
/// than the overlay frame this route used to resolve for itself (#4706). For a
/// model whose `IfcSite` placement is translated, a v3 entry carries the site
/// translation and the site rotation the meshes in the same response had
/// dropped: it decodes cleanly and draws the 2D symbols hundreds of metres
/// from the geometry they annotate.
///
/// The 2D symbol stream (`IfcAnnotation` + `IfcGrid`) is cached separately
/// from geometry so binary-transport endpoints (Parquet, optimized Parquet,
/// cached geometry) can expose it via `GET /api/v1/parse/symbolic/{cache_key}`,
/// mirroring how the data model is cached and fetched (issue #900). `cache_key`
/// is the full `{hash}-{opening_filter}` key, matching the value embedded in
/// each response's metadata header.
pub(crate) fn symbolic_cache_key(cache_key: &str) -> String {
    format!("{}-symbolic-v4", cache_key)
}

/// Serialize symbolic data and write it to the cache under `{cache_key}-symbolic-v4`.
///
/// Always stores the JSON (even when empty) so the fetch endpoint can return a
/// definitive `200` with empty arrays rather than looping on `202`.
pub(crate) async fn cache_symbolic_data(cache: &DiskCache, cache_key: &str, symbolic: &impl serde::Serialize) {
    match serde_json::to_vec(symbolic) {
        Ok(bytes) => {
            let key = symbolic_cache_key(cache_key);
            if let Err(e) = cache.set_bytes(&key, &bytes).await {
                tracing::error!(error = %e, cache_key = %cache_key, "Failed to cache symbolic data");
            } else {
                tracing::debug!(cache_key = %key, size = bytes.len(), "Symbolic data cached");
            }
        }
        Err(e) => {
            tracing::error!(error = %e, "Failed to serialize symbolic data for caching");
        }
    }
}

/// Whether symbolic data is cached for `cache_key`.
///
/// The optimized-Parquet route's parse is what writes the symbolic sidecar, so
/// a replay that skips the parse must first check the sidecar is there. Without
/// this, a body entry that outlived its symbolic entry replays forever and
/// `GET /api/v1/parse/symbolic/{cache_key}` answers `202` to a key nobody
/// writes -- the same shape as the geometry/data-model trap in #3869.
///
/// [`load_cached_symbolic`] cannot stand in: it answers `SymbolicDataWithProvenance::default()`
/// for an absent entry and for a model with no 2D symbols alike, so absence
/// there is indistinguishable from success.
pub(crate) async fn has_cached_symbolic(cache: &DiskCache, cache_key: &str) -> bool {
    has_entry(cache, &symbolic_cache_key(cache_key)).await
}

/// Load cached symbolic data for `cache_key`, defaulting to empty when the
/// entry is absent or unreadable.
pub(crate) async fn load_cached_symbolic(cache: &DiskCache, cache_key: &str) -> SymbolicDataWithProvenance {
    let key = symbolic_cache_key(cache_key);
    match cache.get_bytes(&key).await {
        Ok(Some(bytes)) => serde_json::from_slice(&bytes).unwrap_or_else(|e| {
            tracing::error!(error = %e, cache_key = %cache_key, "Failed to parse cached symbolic data");
            SymbolicDataWithProvenance::default()
        }),
        Ok(None) => SymbolicDataWithProvenance::default(),
        Err(e) => {
            tracing::error!(error = %e, cache_key = %cache_key, "Failed to read cached symbolic data");
            SymbolicDataWithProvenance::default()
        }
    }
}