Cache Module

The Cache module implements a four-layer caching architecture that automatically routes reads and writes through in-process, local, distributed, and persistent cache tiers. It provides decorators for zero-code caching and event-driven invalidation.

Four-Layer Architecture

Layer	Backend	Speed	Scope
`L1`	In-process (LRU dict)	Nanoseconds	Single process
`L2`	Local Redis / Memcached	Sub-millisecond	Single machine
`L3`	Distributed Redis cluster	1-5 ms	Multiple machines
`L4`	Persistent (CDN, S3, file)	10-100 ms	Global

Configuration

example.py

python

Copied!

1	from vorte import Vorte
2
3	app = Vorte(
4	auto_load=True,
5	config={
6	"cache": {
7	"default_ttl": 300,
8	"layers": {
9	"l1": {
10	"enabled": True,
11	"max_size": 1000,
12	"ttl": 60,
13	},
14	"l2": {
15	"enabled": True,
16	"backend": "redis",
17	"url": "redis://localhost:6379/0",
18	"ttl": 300,
19	},
20	"l3": {
21	"enabled": True,
22	"backend": "redis-cluster",
23	"urls": [
24	"redis://node1:6379",
25	"redis://node2:6379",
26	"redis://node3:6379",
27	],
28	"ttl": 3600,
29	},
30	"l4": {
31	"enabled": False,
32	"backend": "s3",
33	"bucket": "my-cache-bucket",
34	"ttl": 86400,
35	},
36	},
37	"key_prefix": "vorte:",
38	"serialization": "msgpack",
39	},
40	},
41	)

Basic Usage

example.py

python

Copied!

1	from vorte.cache import Cache
2
3	cache = Cache()
4
5	await cache.set("user:1", {"id": 1, "name": "Alice"}, ttl=300)
6	user = await cache.get("user:1")
7
8	await cache.delete("user:1")
9
10	exists = await cache.exists("user:1")
11
12	await cache.set("counter", 0, ttl=3600)
13	await cache.increment("counter", amount=1)
14
15	keys = await cache.keys("user:*")
16	await cache.delete_many(keys)
17
18	await cache.flush()

@cached Decorator

Cache the return value of any async function. The decorator generates a cache key from the function name and arguments.

get_user.py

python

Copied!

1	from vorte.cache import cached
2
3	@cached(ttl=300, key="user:{user_id}")
4	async def get_user(user_id: int):
5	user = await db.fetch_one("SELECT * FROM users WHERE id = :id", {"id": user_id})
6	return user
7
8	@cached(ttl=60, layer="l1")
9	async def get_config(key: str):
10	return await db.fetch_val("SELECT value FROM config WHERE key = :key", {"key": key})
11
12	@cached(ttl=3600, tags=["products", "catalog"])
13	async def get_products(category: str):
14	return await db.fetch_all("SELECT * FROM products WHERE category = :cat", {"cat": category})

Cache Tags

Group cached entries by tags for bulk invalidation. This is useful when a single data change should invalidate multiple related cache entries.

example.py

python

Copied!

1	from vorte.cache import Cache
2
3	cache = Cache()
4
5	await cache.set("product:1", product_data, tags=["products", "category:electronics"])
6	await cache.set("product:2", product_data_2, tags=["products", "category:books"])
7	await cache.set("featured:electronics", featured_list, tags=["featured", "category:electronics"])
8
9	await cache.invalidate_tag("category:electronics")
10	# Removes: product:1, featured:electronics
11	# Keeps: product:2

Invalidation Strategies

Time-Based (TTL)

example.py

python

Copied!

1	# Cache expires after TTL
2	await cache.set("key", value, ttl=300)

Event-Driven Invalidation

invalidate_user_cache.py

python

Copied!

1	from vorte.cache import Cache, on_event
2
3	cache = Cache()
4
5	@on_event("user.updated")
6	async def invalidate_user_cache(user_id: int):
7	await cache.delete(f"user:{user_id}")
8	await cache.invalidate_tag(f"user_data:{user_id}")

Write-Through

update_user.py

python

Copied!

1	from vorte.cache import Cache
2
3	cache = Cache()
4
5	@router.put("/users/{user_id}")
6	async def update_user(user_id: int, payload: UpdateUserPayload):
7	user = await db.update_user(user_id, payload)
8	await cache.set(f"user:{user_id}", user, ttl=300)
9	return success_response(data=user)

Cache-Aside (Lazy Loading)

get_user.py

python

Copied!

1	from vorte.cache import Cache
2
3	cache = Cache()
4
5	async def get_user(user_id: int):
6	cached = await cache.get(f"user:{user_id}")
7	if cached:
8	return cached
9
10	user = await db.get_user(user_id)
11	await cache.set(f"user:{user_id}", user, ttl=300)
12	return user

Cache Statistics

example.py

python

Copied!

1	stats = await cache.stats()
2	print(f"Hit rate: {stats.hit_rate:.2%}")
3	print(f"L1 hits: {stats.l1_hits}")
4	print(f"L2 hits: {stats.l2_hits}")
5	print(f"L3 hits: {stats.l3_hits}")
6	print(f"Misses: {stats.misses}")
7	print(f"Total keys: {stats.total_keys}")
8	print(f"Memory used: {stats.memory_used_mb:.1f} MB")

Cache Module

Four-Layer Architecture

Configuration

Basic Usage

@cached Decorator

Cache Tags

Invalidation Strategies

Time-Based (TTL)

Event-Driven Invalidation

Write-Through

Cache-Aside (Lazy Loading)

Cache Statistics

Stay in the loop