To improve performance and ensure maximum platform stability, we need to support caching lookup, search, and aggregation operations on DAL and store levels.
The scope of this task is only DAL and Store caching implementation. Store and DAL are unaware of the security context and do not provide access control.
Caching backends (CB)
Corteza supports multiple caching backends and allows the selection and configuration of one or more caching backends for each DAL connection.
In the initial version, corteza supports REDIS, Memcache and an in-memory store.
Future versions might support drivers for Amazon ElastiCache, Google MemoryStore and others.
Caching and invalidation mechanisms
Lookup, search, and aggregation operations can be cached. Each resource type and compose module can select the cache strategy it will use.
Cache item key (CIK) format:
lookup[resource-type]:[module-id]:[resource-id]
search[resource-type]:[module-id]:[filter-values]
aggregate[resource-type]:[module-id]:[filter-values]
(aggregate and search CIK can overlap, expected and ok)
CB implementation can hash CIK value if needed.
Cache parameters and how configured BC can be controlled.
Parameters are propagated through calls via context.
disabled
CB must not serve cached content when the operation is executed with explicitly disabled caching.
max-age
CB must ensure that the max age parameter is respected and that out-of-range cached items are not used.
CLI
Caching is disabled for all operations.
[ ] Explicitly disable caching when executing operations via CLI
Code
Caching package provides utility functions to manipulate disabled & max-age parameters in the context. BC must inspect context values and execute accordingly.
HTTP interface
HTTP header Cache-Control is inspected for the no-cache parameter (sets disabled=true) and max-age parameter (seconds). See documentation for details on headers.
Headers are inspected early on request inside a chi router middleware.
[ ] Cache-Control header inspection middleware and link that middleware in server.BaseMiddleware
Cache invalidation
by directly and indirectly linking resources
Each cached resource is directly or indirectly linked to that cache item. Each CB needs to implement its own dependency checking and invalidate cache items on resource change or removal.
Cache items for lookup operations are linked directly to the resource. CB can always generate CIK from a resource.
For the initial version, cache items for search and aggregate must use intermediate CIKs (example [resource-type]:[module-id]). All cache items related to this resource-type/module-id combo must be invalidated.
This is an oversimplified solution that will cause many cache-miss requests. It will be optimised in the future.
Clean all cache
Cache on a specific connection can be cleaned via API. A new POST endpoint is added, /system/connection/:id/clean-cache. It must be enabled only cache connections. Other connection types should respond with 501 Not Implemented status.
General caching rules
Caching is never enforced and can only be enabled on a CB.
The cache can be ignored when data is requested.
When executing an operation, max-age can be passed along to control.
Max-age value must be within range (5s ... 86400s)
Drivers
Store and DAL will require a cache driver that satisfies a straightforward interface to store and retrieve payload under a specific key.
[ ] Implement generic In-memory cache driver
[ ] Implement generic REDIS cache driver
[ ] Implement generic Memcache cache driver
Store
Configuration
General resource caching is configured in the .env file using the DB_CACHE_DSN key.
Changing store caching configuration requires server restart.
When DB_CACHE_DNS, Corteza provisions DAL connections and adds a new entry to the DB using the corteza::system:primary-cache type and primary-cache handle. Similar as primary store connection, the primary cache connection must also be read-only.
[ ] Provision DAL Connections by adding primary-cache connection
[ ] Ensure the primary cache connection is read-only.
Initialisation
CortezaApp.InitStore is used to initialise the connection to the primary store connection. The function reads the CB configurations from DB_CACHE_DSN option and wraps the primary store connection.
[ ] Implement primary store cache initialisation
Implementation
The caching layer for the primary store is a code similar to the RDBMS layer. Each generated function should appropriately interact with both connections - cache and underlying store.
[ ] Prepare code-gen template for all store cache layer functions
[ ] Implement store cache constructr
DAL
Configuration
[ ] DAL Connection configuration can be configured to use caching as a default for all modules
[ ] DAL configuration on Compose module can reset cache configuration from connection or provide new configuration
[ ] CB is one of the DAL connections with a particular type.
[ ] corteza::dal:cache:memory
[ ] corteza::dal:cache:redis
[ ] corteza::dal:cache:memcache
[ ] Corteza must prevent the use of connections of non-cache type for caching
[ ] Corteza must prevent the use of connections of type cache for storage
Initialisation
DAL service implements per-module cache configuration in the storeOpPrep. The function reads the connection and model cache configuration and constructs (wraps) the connection accordingly. If the operation disallows caching, the function should skip CB wrap.
[ ] Implement DAL service cache initialisation
Implementation
Generic DAL driver provides custom create, search, delete, and update functions that interact with the cache driver to read and write cached items. Other operations are routed directly to the underlying storage connection
[ ] Generic DAL driver initialised with cache driver and underlying storage connection
To improve performance and ensure maximum platform stability, we need to support caching lookup, search, and aggregation operations on DAL and store levels.
The scope of this task is only DAL and Store caching implementation. Store and DAL are unaware of the security context and do not provide access control.
Caching backends (CB)
Corteza supports multiple caching backends and allows the selection and configuration of one or more caching backends for each DAL connection.
In the initial version, corteza supports REDIS, Memcache and an in-memory store.
Future versions might support drivers for Amazon ElastiCache, Google MemoryStore and others.
Caching and invalidation mechanisms
Lookup, search, and aggregation operations can be cached. Each resource type and compose module can select the cache strategy it will use.
Cache item key (CIK) format:
[resource-type]:[module-id]:[resource-id]
[resource-type]:[module-id]:[filter-values]
[resource-type]:[module-id]:[filter-values]
(aggregate and search CIK can overlap, expected and ok)CB implementation can hash CIK value if needed.
Cache parameters and how configured BC can be controlled.
Parameters are propagated through calls via context.
disabled
CB must not serve cached content when the operation is executed with explicitly disabled caching.max-age
CB must ensure that the max age parameter is respected and that out-of-range cached items are not used.CLI
Caching is disabled for all operations.
Code
Caching package provides utility functions to manipulate
disabled
&max-age
parameters in the context. BC must inspect context values and execute accordingly.HTTP interface
HTTP header
Cache-Control
is inspected for theno-cache
parameter (sets disabled=true) andmax-age
parameter (seconds). See documentation for details on headers.Headers are inspected early on request inside a chi router middleware.
Cache-Control
header inspection middleware and link that middleware inserver.BaseMiddleware
Cache invalidation
by directly and indirectly linking resources
Each cached resource is directly or indirectly linked to that cache item. Each CB needs to implement its own dependency checking and invalidate cache items on resource change or removal.
Cache items for lookup operations are linked directly to the resource. CB can always generate CIK from a resource.
For the initial version, cache items for search and aggregate must use intermediate CIKs (example
[resource-type]:[module-id]
). All cache items related to this resource-type/module-id combo must be invalidated.This is an oversimplified solution that will cause many cache-miss requests. It will be optimised in the future.
Clean all cache
Cache on a specific connection can be cleaned via API. A new
POST
endpoint is added,/system/connection/:id/clean-cache
. It must be enabled only cache connections. Other connection types should respond with501 Not Implemented
status.General caching rules
Caching is never enforced and can only be enabled on a CB. The cache can be ignored when data is requested.
When executing an operation, max-age can be passed along to control. Max-age value must be within range (5s ... 86400s)
Drivers
Store and DAL will require a cache driver that satisfies a straightforward interface to store and retrieve payload under a specific key.
Store
Configuration
General resource caching is configured in the
.env
file using theDB_CACHE_DSN
key.Changing store caching configuration requires server restart.
DSN format examples:
Provisioning
When
DB_CACHE_DNS
, Corteza provisions DAL connections and adds a new entry to the DB using thecorteza::system:primary-cache
type andprimary-cache
handle. Similar as primary store connection, the primary cache connection must also be read-only.Initialisation
CortezaApp.InitStore
is used to initialise the connection to the primary store connection. The function reads the CB configurations fromDB_CACHE_DSN
option and wraps the primary store connection.Implementation
The caching layer for the primary store is a code similar to the RDBMS layer. Each generated function should appropriately interact with both connections - cache and underlying store.
DAL
Configuration
Initialisation
DAL service implements per-module cache configuration in the
storeOpPrep
. The function reads the connection and model cache configuration and constructs (wraps) the connection accordingly. If the operation disallows caching, the function should skip CB wrap.Implementation
Generic DAL driver provides custom create, search, delete, and update functions that interact with the cache driver to read and write cached items. Other operations are routed directly to the underlying storage connection