This page lists the caching mechanisms of the platform core: the version counters that let in-process caches notice writes from other workers, the asset stamp that makes web app files cacheable for a year, and the HTTP cache headers that server/app.py sets. The client-side use of the stamp is documented on web app overview.
Scope and source¶
- Defined in:
src/cluster_erp/core/cache_versions.py,src/cluster_erp/core/asset_stamp.py,src/cluster_erp/server/app.py(static mounts and/api/v1/_meta) - Count: 2 cache families; 2 static mounts; 1 cached metadata document
Cache version counters¶
The table core_cache_versions has one row per cache family with a version counter (src/cluster_erp/core/cache_versions.py:25, src/cluster_erp/core/cache_versions.py:39-43). Statement-level triggers from migration perf01 raise the counter on every insert, update, delete, or truncate of the family's tables (src/cluster_erp/core/cache_versions.py:12-16, migrations/versions/perf01_cache_versions.py).
| Family | Tables that move it | Reader | Source |
|---|---|---|---|
auth |
auth_roles, auth_role_permissions, auth_user_roles, auth_abac_policies, auth_permissions |
src/cluster_erp/modules/auth/auth_cache.py:69-77 |
src/cluster_erp/core/cache_versions.py:28-36 |
entitlement |
app_store_installs, app_store_licenses |
src/cluster_erp/server/entitlements.py:68-77 |
src/cluster_erp/core/cache_versions.py:36 |
version_statement(family) returns SELECT version FROM core_cache_versions WHERE name = :family and raises ValueError for an unknown family (src/cluster_erp/core/cache_versions.py:46-51). The module docstring states the reason: the earlier stamp read the latest updated_at and the row count of each table on every guarded request, and a count is a full scan; one primary-key lookup costs the same at any table size (src/cluster_erp/core/cache_versions.py:1-17). The lifetime of the authorisation cache is the setting auth_cache_seconds (src/cluster_erp/config/settings.py:317-320, src/cluster_erp/server/app.py:1308-1310).
Asset stamp¶
asset_stamp(root) returns the first 16 hexadecimal characters of a SHA-256 digest over the relative path, size, and modification time of every file under root, walked in sorted order (src/cluster_erp/core/asset_stamp.py:30-42). The result is memoised for one second (src/cluster_erp/core/asset_stamp.py:26, src/cluster_erp/core/asset_stamp.py:45-54). PLACEHOLDER is __ASSET_STAMP__ (src/cluster_erp/core/asset_stamp.py:25).
webapp/index.html links its files under ./v/__ASSET_STAMP__/. The application server replaces the placeholder with the computed stamp; on a node, nginx serves the files and the release tag is the stamp (src/cluster_erp/core/asset_stamp.py:3-10). See reverse proxy.
HTTP caching in the server¶
| Path | Cache-Control | Validation | Source |
|---|---|---|---|
/app/ and /app/index.html |
no-cache |
ETag of the body with the stamp filled in; If-None-Match answers 304 |
src/cluster_erp/server/app.py:1591-1597, src/cluster_erp/server/app.py:1616-1625 |
other files under /app/ |
no-cache |
Starlette's static file validation | src/cluster_erp/server/app.py:1591-1597 |
/app/v/<current stamp>/<file> |
public, max-age=31536000, immutable |
none needed | src/cluster_erp/server/app.py:1599-1614 |
/app/v/<old stamp>/<file> |
no-cache |
Starlette's static file validation | src/cluster_erp/server/app.py:1610-1613 |
/api/v1/_meta |
private, no-cache |
ETag per representation (identity and gzip); If-None-Match answers 304 |
src/cluster_erp/server/app.py:1518-1556, src/cluster_erp/server/app.py:1102-1108 |
The metadata document is rendered once per process and kept on app.state._meta_cache, together with a pre-compressed gzip form (src/cluster_erp/server/app.py:1530-1543). font/woff2 and font/woff are registered as MIME types so that fonts are served as fonts on every platform (src/cluster_erp/server/app.py:1626-1631).
Constraints and validation¶
- A request for
/app/v/<stamp>without a file path answers 404 (src/cluster_erp/server/app.py:1606-1608). - The web app is mounted only when the
webappfolder exists next to the package (src/cluster_erp/server/app.py:1633-1644). - The metadata cache lives as long as the process; a metadata change takes effect after a restart (
src/cluster_erp/server/app.py:1523-1525).
Terms introduced¶
| Term | Code identifier | Definition | Turkish term | Source |
|---|---|---|---|---|
| asset stamp | asset_stamp |
A short token in the web app's asset URLs that changes when the shipped files change; the server computes it as a digest of the files, and nginx receives the release tag. | varlık damgası | src/cluster_erp/core/asset_stamp.py:45 |
| cache family | FAMILIES |
A named group of tables whose writes invalidate one in-process cache. | önbellek ailesi | src/cluster_erp/core/cache_versions.py:28 |
Related pages¶
Verified against commit 92f8051 on 2026-11-13.