[Feat] Advanced Performance Caching

[derrickmehaffy]

Summary

Add a proper caching framework (Caffeine or similar) for hot data paths beyond basic ConcurrentHashMap. Profile first to identify actual bottlenecks before optimizing.

Motivation

HyperFactions stores significant state across features (factions, members, claims, power, relations, combat tags, zones). As server scale grows, read-heavy operations on frequently accessed data would benefit from tiered caching with TTL and eviction policies.

Proposed Cache Tiers

Hot (Frequent Access)

• Faction memberships — Player → faction lookup (every protection check)
• Chunk claims — Chunk → faction lookup (every block event)
• Combat tags — Active tags (every combat event)
• Power values — For claim limit calculations

Warm (Moderate Access)

• Faction data — Name, description, home, settings
• Relations — Ally/enemy status between factions
• Player profiles — Last seen, kills, deaths

Cold (Infrequent Access)

• Zone definitions — Rarely change after creation
• Audit logs — Write-heavy, read-infrequent

Cache Configuration

cache:
  enabled: true
  faction-membership:
    ttl: 300  # seconds
    max-size: 1000
  chunk-claims:
    ttl: 60
    max-size: 10000
  power:
    ttl: 30
    max-size: 500

Cache Invalidation Triggers

• Player joins/leaves faction
• Faction created/disbanded
• Territory claimed/unclaimed
• Relation changed
• Power updated
• Config reload

Implementation Notes

• Profile before optimizing — measure actual bottlenecks
• Consider Caffeine (already used by HyperPerms, can share relocation)
• Review HyperPerms caching patterns: PermissionCache, CacheConfiguration, CacheInvalidator
• Ensure thread-safe invalidation across async operations

Origin

Roadmap Research item R.6.