This document defines the comprehensive caching strategy for the Nyx Cosmic Observatory platform, covering all cache layers, key structures, TTL policies, invalidation patterns, and integration with the existing @oshun/cache infrastructure.
Table of Contents#
- Overview
- Cache Architecture
- Cache Layers
- Key Structure & Naming
- TTL Policies
- Invalidation Strategies
- Service-Specific Caching
- CDN Integration
- Metrics & Monitoring
- Implementation Guidelines
Overview#
The Nyx Cosmic Observatory platform handles multiple data types with varying access patterns and freshness requirements:
| Data Type | Access Pattern | Update Frequency | Cache Priority |
|---|---|---|---|
| Star field tiles | Read-heavy, spatial | Rarely (catalog) | Critical |
| Ephemeris calculations | Compute-intensive | Hourly/Daily | High |
| Catalog queries | High-frequency reads | Weekly/Monthly | High |
| User observations | User-specific writes | Per-session | Medium |
| Real-time satellite | Streaming, time-based | Every 1-10 seconds | Low (no cache) |
| Event predictions | Scheduled computation | Daily | Medium |
| TLE data | External API | Every 2-3 hours | Medium |
Goals#
- Minimize Computation: Cache expensive ephemeris and position calculations
- Reduce Database Load: Cache catalog queries and user data
- Optimize Tile Delivery: CDN edge caching for map tiles
- Maintain Consistency: Proper invalidation for data accuracy
- Enable Offline: Local caching for mobile/PWA use cases
Cache Architecture#
┌─────────────────────────────────────────────────────────────────────────────┐
│ Client Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Browser │ │ Mobile │ │ Desktop │ │ Service Worker │ │
│ │ Cache │ │ Cache │ │ Cache │ │ (Offline-First) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└───────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CDN Layer (L0) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ CloudFront / Fastly / CloudFlare │ │
│ │ • Star field tiles (PNG/WebP) │ │
│ │ • Constellation boundaries │ │
│ │ • Milky Way overlays │ │
│ │ • Static catalog data │ │
│ │ • Pre-rendered finder charts │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Application Layer │
│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────────────┐│
│ │ In-Memory (L1) │ │ Redis (L2) │ │ PostgreSQL (L3) ││
│ │ OshunMemoryCache │ │ OshunRedisClient │ │ + PostGIS + pgvector ││
│ │ │ │ │ │ ││
│ │ • Hot tiles │ │ • Ephemeris │ │ • Celestial objects ││
│ │ • Current view │ │ • Predictions │ │ • User observations ││
│ │ • Session data │ │ • User prefs │ │ • Historical data ││
│ │ • Recent queries │ │ • Catalog cache │ │ • Complete catalogs ││
│ └───────────────────┘ └───────────────────┘ └───────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
Cache Flow#
Request Flow
│
▼
┌──────────────┐
│ Client? │──────Yes──────► Return
└──────────────┘
│No
▼
┌──────────────┐
│ CDN? │──────Yes──────► Return + Update Client
└──────────────┘
│No
▼
┌──────────────┐
│ Memory L1? │──────Yes──────► Return + Update CDN
└──────────────┘
│No
▼
┌──────────────┐
│ Redis L2? │──────Yes──────► Return + Update L1 + CDN
└──────────────┘
│No
▼
┌──────────────┐
│ Compute/DB │──────────────► Return + Update L2, L1, CDN
└──────────────┘
Cache Layers#
Layer 0: CDN (Edge Cache)#
Purpose: Serve static and semi-static content from edge locations globally.
Provider Options: CloudFront, Fastly, Cloudflare
Cached Content:
| Content Type | TTL | Cache-Control Header |
|---|---|---|
| Star field tiles | 7 days | public, max-age=604800, s-maxage=2592000 |
| Constellation overlays | 30 days | public, max-age=2592000, immutable |
| Milky Way images | 30 days | public, max-age=2592000, immutable |
| Deep sky object images | 7 days | public, max-age=604800, stale-while-rev=86400 |
| Catalog JSON (static) | 1 day | public, max-age=86400, stale-if-error=604800 |
| Finder charts | 24 hours | public, max-age=86400, s-maxage=172800 |
| App assets (JS/CSS) | 1 year | public, max-age=31536000, immutable |
Cache Invalidation:
- Use versioned URLs for tiles:
/tiles/v{VERSION}/stars/{z}/{x}/{y}.webp - CloudFront invalidation API for emergency updates
- Soft purge with stale-while-revalidate for gradual updates
Headers:
Cache-Control: public, max-age=604800, s-maxage=2592000
Vary: Accept-Encoding, Accept
ETag: "tile-v2-stars-12-2048-1024-dark"
Last-Modified: Sat, 01 Jan 2026 00:00:00 GMT
Layer 1: In-Memory Cache (OshunMemoryCache)#
Purpose: Ultra-low latency for hot data, per-service instance caching.
Configuration:
const nyxMemoryCache = new OshunMemoryCache({
name: 'nyx-service',
maxSize: 100 * 1024 * 1024, // 100MB
maxEntries: 10000,
defaultTtl: TTL.MEDIUM, // 5 minutes
cleanupInterval: 60000, // 1 minute
});
Cached Content:
| Content Type | Max Entries | Max Size | TTL |
|---|---|---|---|
| Current viewport tiles | 256 | 50MB | 5 min |
| Recent cone search | 100 | 10MB | 1 min |
| Current ephemeris | 50 | 5MB | 30 sec |
| Session user prefs | 1000 | 5MB | 15 min |
| Hot catalog objects | 500 | 10MB | 5 min |
| Parsed TLE cache | 500 | 5MB | 2 hours |
Eviction Policy: LRU (Least Recently Used) with TTL expiration
Layer 2: Redis Cache (OshunRedisClient)#
Purpose: Shared cache across service instances, distributed invalidation.
Configuration:
const nyxRedisClient = new OshunRedisClient({
host: process.env.REDIS_HOST,
port: parseInt(process.env.REDIS_PORT || '6379'),
password: process.env.REDIS_PASSWORD,
db: 2, // Dedicated DB for Nyx
keyPrefix: 'nyx:',
enableReadyCheck: true,
maxRetriesPerRequest: 3,
});
Cached Content:
| Content Type | Key Pattern | TTL | Size Limit |
|---|---|---|---|
| Ephemeris data | ephemeris:{objectId}:{date} |
1 hour | 10KB/obj |
| Satellite positions | sat:{noradId}:{timestamp} |
5 min | 1KB/sat |
| Planet positions | planet:{name}:{date} |
6 hours | 2KB/planet |
| Event predictions | event:{type}:{date} |
24 hours | 50KB |
| Rise/set times | riseset:{objectId}:{loc}:{date} |
12 hours | 1KB |
| Catalog query results | catalog:query:{hash} |
30 min | 100KB |
| User preferences | user:{userId}:prefs |
7 days | 5KB |
| User saved views | user:{userId}:views |
7 days | 50KB |
| Observation lists | list:{listId} |
7 days | 100KB |
| TLE data | tle:{noradId} |
2 hours | 500B |
| Orbital elements | orbit:{objectId} |
24 hours | 2KB |
| Eclipse predictions | eclipse:{year} |
30 days | 100KB |
| Meteor shower data | meteor:{year} |
30 days | 50KB |
Cluster Configuration (Production):
const nyxRedisCluster = new OshunRedisClusterClient({
nodes: [
{ host: 'redis-1.nyx.internal', port: 6379 },
{ host: 'redis-2.nyx.internal', port: 6379 },
{ host: 'redis-3.nyx.internal', port: 6379 },
],
keyPrefix: 'nyx:',
scaleReads: 'slave',
});
Layer 3: PostgreSQL (Source of Truth)#
Purpose: Persistent storage, complex queries, full catalog data.
Caching Strategy: Use PostgreSQL's built-in caching + connection pooling.
// Connection pool configuration
const pool = new Pool({
host: process.env.NYX_DATABASE_HOST,
database: 'nyx',
max: 20,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 5000,
});
Query Result Caching: Redis L2 for repeated expensive queries.
Key Structure & Naming#
Key Prefix Convention#
All Nyx keys use the nyx: prefix for namespace isolation:
nyx:{service}:{entity}:{identifier}:{qualifiers}
Key Builders#
// libs/nyx/cache/src/key-builders.ts
export const NyxCacheKeys = {
// Catalog Service
object: (objectId: string) => `nyx:catalog:obj:${objectId}`,
objectByName: (name: string) => `nyx:catalog:name:${name.toLowerCase()}`,
coneSearch: (ra: number, dec: number, radius: number, hash: string) =>
`nyx:catalog:cone:${ra.toFixed(3)}_${dec.toFixed(3)}_${radius}:${hash}`,
// Compute Service
ephemeris: (objectId: string, date: string) =>
`nyx:compute:eph:${objectId}:${date}`,
ephemerisBatch: (objectId: string, startDate: string, endDate: string) =>
`nyx:compute:ephbatch:${objectId}:${startDate}_${endDate}`,
planetPosition: (planet: string, jd: number) =>
`nyx:compute:planet:${planet}:${jd.toFixed(2)}`,
satellite: (noradId: number, timestamp: number) =>
`nyx:compute:sat:${noradId}:${Math.floor(timestamp / 60000)}`,
riseSet: (objectId: string, lat: number, lon: number, date: string) =>
`nyx:compute:riseset:${objectId}:${lat.toFixed(2)}_${lon.toFixed(2)}:${date}`,
// Events & Predictions
eclipse: (eclipseId: string) => `nyx:event:eclipse:${eclipseId}`,
eclipsesYear: (year: number) => `nyx:event:eclipses:${year}`,
conjunction: (conjunctionId: string) => `nyx:event:conj:${conjunctionId}`,
meteorShower: (showerId: string) => `nyx:event:meteor:${showerId}`,
eventsRange: (start: string, end: string) =>
`nyx:event:range:${start}_${end}`,
// Render Service
tile: (layer: string, z: number, x: number, y: number, theme: string) =>
`nyx:render:tile:${layer}:${z}:${x}:${y}:${theme}`,
finderChart: (objectId: string, fov: number, format: string) =>
`nyx:render:finder:${objectId}:${fov}:${format}`,
// User Data
userPrefs: (userId: string) => `nyx:user:${userId}:prefs`,
userViews: (userId: string) => `nyx:user:${userId}:views`,
userLists: (userId: string) => `nyx:user:${userId}:lists`,
userObservations: (userId: string) => `nyx:user:${userId}:obs`,
userProgress: (userId: string, programId: string) =>
`nyx:user:${userId}:prog:${programId}`,
userAchievements: (userId: string) => `nyx:user:${userId}:achieve`,
// Session Data
session: (sessionId: string) => `nyx:session:${sessionId}`,
sessionLocation: (sessionId: string) => `nyx:session:${sessionId}:loc`,
// TLE & Orbital Data
tle: (noradId: number) => `nyx:tle:${noradId}`,
tleSet: (category: string) => `nyx:tleset:${category}`,
orbital: (objectId: string) => `nyx:orbital:${objectId}`,
};
// Pattern builders for invalidation
export const NyxCachePatterns = {
allEphemeris: (objectId: string) => `nyx:compute:eph:${objectId}:*`,
allUserData: (userId: string) => `nyx:user:${userId}:*`,
allTiles: (layer: string) => `nyx:render:tile:${layer}:*`,
allEventsDate: (date: string) => `nyx:event:*:${date}*`,
allSatellites: () => `nyx:compute:sat:*`,
allTLE: () => `nyx:tle:*`,
};
TTL Policies#
Domain-Specific TTL Constants#
// libs/nyx/cache/src/ttl.ts
export const NyxTTL = {
// Real-time data (no caching or very short)
SATELLITE_POSITION: 0, // Never cache - always compute
REALTIME_SKY: 0, // Live WebSocket updates
// Very short (< 1 minute)
CURRENT_EPHEMERIS: 30, // 30 seconds - current position
ACTIVE_PASSES: 30, // 30 seconds - visible satellites
// Short (1-5 minutes)
CONE_SEARCH: 60, // 1 minute - viewport queries
HOT_OBJECTS: 60, // 1 minute - frequently accessed
HOURLY_EPHEMERIS: 300, // 5 minutes - next hour positions
// Medium (5-60 minutes)
PLANET_POSITION: 600, // 10 minutes - planet positions
RISE_SET_TIMES: 1800, // 30 minutes - rise/transit/set
DAILY_EPHEMERIS: 3600, // 1 hour - daily ephemeris table
// Long (1-24 hours)
TLE_DATA: 7200, // 2 hours - TLE elements
ORBITAL_ELEMENTS: 14400, // 4 hours - orbital elements
EVENT_PREDICTIONS: 21600, // 6 hours - upcoming events
COMET_DATA: 86400, // 24 hours - comet positions
ASTEROID_DATA: 86400, // 24 hours - asteroid positions
// Very long (days-weeks)
USER_PREFERENCES: 604800, // 7 days - user settings
SAVED_VIEWS: 604800, // 7 days - saved views
OBSERVATION_LISTS: 604800, // 7 days - observing lists
STATIC_CATALOG: 2592000, // 30 days - star catalogs
ECLIPSE_DATA: 2592000, // 30 days - eclipse predictions
METEOR_SHOWER: 2592000, // 30 days - meteor shower data
// Immutable (versioned)
CONSTELLATION_BOUNDARIES: -1, // Immutable - versioned URL
STAR_TILES: -1, // Immutable - versioned URL
MILKY_WAY: -1, // Immutable - versioned URL
} as const;
// Time-based TTL adjusters
export function adjustTTLForFreshness(
baseTTL: number,
dataAge: number
): number {
// Reduce TTL for older data
const ageFactor = Math.max(0.1, 1 - dataAge / (baseTTL * 2));
return Math.floor(baseTTL * ageFactor);
}
// Object-type based TTL
export function getTTLForObjectType(objectType: string): number {
switch (objectType) {
case 'satellite':
case 'space_station':
return NyxTTL.SATELLITE_POSITION;
case 'solar_system_planet':
return NyxTTL.PLANET_POSITION;
case 'asteroid':
return NyxTTL.ASTEROID_DATA;
case 'comet':
return NyxTTL.COMET_DATA;
case 'star':
case 'galaxy':
case 'nebula':
return NyxTTL.STATIC_CATALOG;
default:
return NyxTTL.DAILY_EPHEMERIS;
}
}
TTL Decision Matrix#
┌────────────────────┬────────────────────┬────────────────────┐
│ │ Update Freq │ │
│ Access Freq │ High │ Low │ Strategy │
├────────────────────┼──────────┼─────────┼────────────────────┤
│ High │ No │ Long │ Static or CDN │
│ (Hot Data) │ Cache │ TTL │ with versioning │
├────────────────────┼──────────┼─────────┼────────────────────┤
│ Low │ Short │ Long │ On-demand │
│ (Cold Data) │ TTL │ TTL │ computation │
└────────────────────┴──────────┴─────────┴────────────────────┘
Invalidation Strategies#
Invalidation Manager Configuration#
// libs/nyx/cache/src/invalidation.ts
import { InvalidationManager, OshunPubSubClient } from '@oshun/cache';
const nyxInvalidation = new InvalidationManager(
nyxRedisClient,
new OshunPubSubClient(redisConfig, 'nyx'),
{
strategy: 'immediate',
batchSize: 100,
batchDelayMs: 100,
retryAttempts: 3,
}
);
// Invalidation event handlers
export const NyxInvalidationEvents = {
// TLE update triggers satellite cache invalidation
async onTLEUpdate(noradIds: number[]): Promise<void> {
for (const noradId of noradIds) {
await nyxInvalidation.invalidatePattern(
NyxCachePatterns.allSatellites(),
'tle_update'
);
}
},
// Catalog update triggers object cache invalidation
async onCatalogUpdate(objectIds: string[]): Promise<void> {
for (const objectId of objectIds) {
await nyxInvalidation.invalidateKey(
NyxCacheKeys.object(objectId),
'catalog_update'
);
await nyxInvalidation.invalidatePattern(
NyxCachePatterns.allEphemeris(objectId),
'catalog_update'
);
}
},
// User data change triggers user cache invalidation
async onUserDataChange(userId: string, dataType: string): Promise<void> {
const key =
dataType === 'prefs'
? NyxCacheKeys.userPrefs(userId)
: NyxCacheKeys.userObservations(userId);
await nyxInvalidation.invalidateKey(key, 'user_update');
},
// Tile regeneration triggers CDN purge
async onTileRegeneration(
layer: string,
zoomLevels?: number[]
): Promise<void> {
await nyxInvalidation.invalidatePattern(
NyxCachePatterns.allTiles(layer),
'tile_regen'
);
// Also trigger CDN invalidation
await triggerCDNPurge(`/tiles/*/${layer}/*`);
},
};
Invalidation Channels (Pub/Sub)#
// Pub/Sub channels for distributed invalidation
export const NyxPubSubChannels = {
CACHE_INVALIDATION: 'nyx:cache:invalidation',
TLE_UPDATE: 'nyx:data:tle:update',
CATALOG_UPDATE: 'nyx:data:catalog:update',
TILE_REGEN: 'nyx:render:tile:regen',
USER_UPDATE: 'nyx:user:update',
EVENT_UPDATE: 'nyx:event:update',
};
// Subscribe to invalidation events
nyxPubSub.subscribe(NyxPubSubChannels.TLE_UPDATE, async (message) => {
const { noradIds } = JSON.parse(message);
await NyxInvalidationEvents.onTLEUpdate(noradIds);
});
nyxPubSub.subscribe(NyxPubSubChannels.CATALOG_UPDATE, async (message) => {
const { objectIds } = JSON.parse(message);
await NyxInvalidationEvents.onCatalogUpdate(objectIds);
});
Stale-While-Revalidate Pattern#
// For expensive computations that can tolerate slightly stale data
export async function getWithSWR<T>(
key: string,
computeFn: () => Promise<T>,
options: { ttl: number; staleTime: number }
): Promise<T> {
const cached = await nyxRedisClient.get<{ value: T; timestamp: number }>(key);
if (cached) {
const age = Date.now() - cached.timestamp;
if (age < options.ttl * 1000) {
// Fresh data - return immediately
return cached.value;
}
if (age < options.staleTime * 1000) {
// Stale but acceptable - return stale, refresh in background
recomputeInBackground(key, computeFn, options.ttl);
return cached.value;
}
}
// No cache or too stale - compute and cache
const value = await computeFn();
await nyxRedisClient.set(key, { value, timestamp: Date.now() }, options.ttl);
return value;
}
Service-Specific Caching#
Catalog Service Caching#
// libs/nyx/catalog-service/src/cache/catalog-cache.ts
export class CatalogCache {
private memoryCache: OshunMemoryCache;
private redisClient: OshunRedisClient;
constructor(memoryCache: OshunMemoryCache, redisClient: OshunRedisClient) {
this.memoryCache = memoryCache;
this.redisClient = redisClient;
}
// Cone search with multi-level caching
async coneSearch(
ra: number,
dec: number,
radius: number,
filters: SearchFilters
): Promise<CelestialObject[]> {
const queryHash = this.hashQuery(ra, dec, radius, filters);
const key = NyxCacheKeys.coneSearch(ra, dec, radius, queryHash);
// L1: Memory cache (hot queries)
const memCached = await this.memoryCache.get<CelestialObject[]>(key);
if (memCached) {
return memCached;
}
// L2: Redis cache
const redisCached = await this.redisClient.get<CelestialObject[]>(key);
if (redisCached) {
// Warm L1 cache
await this.memoryCache.set(key, redisCached, NyxTTL.CONE_SEARCH);
return redisCached;
}
// L3: Database query
const results = await this.queryCatalog(ra, dec, radius, filters);
// Cache at both levels
await Promise.all([
this.memoryCache.set(key, results, NyxTTL.CONE_SEARCH),
this.redisClient.set(key, results, NyxTTL.CONE_SEARCH),
]);
return results;
}
// Object lookup with read-through
async getObject(objectId: string): Promise<CelestialObject | null> {
const key = NyxCacheKeys.object(objectId);
return withRedisCache(
this.redisClient,
() => this.loadObjectFromDB(objectId),
{
prefix: key,
ttl: NyxTTL.STATIC_CATALOG,
skipCache: () => false,
}
);
}
private hashQuery(
ra: number,
dec: number,
radius: number,
filters: SearchFilters
): string {
const data = JSON.stringify({ ra, dec, radius, ...filters });
return createHash('sha256').update(data).digest('hex').slice(0, 12);
}
}
Compute Service Caching#
// libs/nyx/compute-service/src/cache/compute-cache.ts
export class ComputeCache {
private memoryCache: OshunMemoryCache;
private redisClient: OshunRedisClient;
private lockManager: OshunLockManager;
// Ephemeris with cache stampede protection
async getEphemeris(
objectId: string,
startTime: Date,
endTime: Date,
intervalMinutes: number
): Promise<EphemerisEntry[]> {
const dateKey = this.formatDateRange(startTime, endTime);
const key = NyxCacheKeys.ephemerisBatch(
objectId,
dateKey.start,
dateKey.end
);
// Try cache first
const cached = await this.redisClient.get<EphemerisEntry[]>(key);
if (cached) return cached;
// Acquire lock to prevent stampede
const lock = await this.lockManager.acquire(
`ephemeris:${objectId}:${dateKey.start}`,
{
ttl: 30000,
retryDelay: 100,
retryCount: 50,
}
);
try {
// Double-check after acquiring lock
const cachedAgain = await this.redisClient.get<EphemerisEntry[]>(key);
if (cachedAgain) return cachedAgain;
// Compute ephemeris
const ephemeris = await this.computeEphemeris(
objectId,
startTime,
endTime,
intervalMinutes
);
// Cache with appropriate TTL based on data freshness
const ttl = this.getTTLForEphemeris(objectId, startTime, endTime);
await this.redisClient.set(key, ephemeris, ttl);
return ephemeris;
} finally {
await lock.release();
}
}
// Satellite position (short-lived cache)
async getSatellitePosition(
noradId: number,
timestamp: Date
): Promise<SatellitePosition> {
// Round timestamp to minute for cache key
const minuteTimestamp = Math.floor(timestamp.getTime() / 60000) * 60000;
const key = NyxCacheKeys.satellite(noradId, minuteTimestamp);
// Memory-only for very short TTL
const cached = await this.memoryCache.get<SatellitePosition>(key);
if (cached) return cached;
// Compute position
const position = await this.computeSatellitePosition(noradId, timestamp);
// Only memory cache for satellites (too short-lived for Redis)
await this.memoryCache.set(key, position, NyxTTL.CURRENT_EPHEMERIS);
return position;
}
// Planet positions (medium cache)
@Memoize({ maxAge: NyxTTL.PLANET_POSITION * 1000 })
async getPlanetPosition(
planet: string,
julianDate: number
): Promise<PlanetPosition> {
// Round JD to avoid cache fragmentation
const roundedJD = Math.round(julianDate * 100) / 100;
const key = NyxCacheKeys.planetPosition(planet, roundedJD);
return withRedisCache(
this.redisClient,
() => this.computePlanetPosition(planet, julianDate),
{
prefix: key,
ttl: NyxTTL.PLANET_POSITION,
}
);
}
}
Render Service Caching#
// libs/nyx/render-service/src/cache/tile-cache.ts
export class TileCache {
private memoryCache: OshunMemoryCache;
private s3Client: S3Client;
// Tile serving with multi-tier caching
async getTile(
layer: string,
z: number,
x: number,
y: number,
theme: string
): Promise<Buffer> {
const key = NyxCacheKeys.tile(layer, z, x, y, theme);
// L1: Memory cache (hot tiles in current viewport)
const memCached = await this.memoryCache.get<Buffer>(key);
if (memCached) {
return memCached;
}
// L2: S3 storage (CDN origin)
const s3Key = `tiles/${layer}/${theme}/${z}/${x}/${y}.webp`;
try {
const s3Result = await this.s3Client.getObject({
Bucket: 'nyx-tiles',
Key: s3Key,
});
const tileBuffer = await s3Result.Body?.transformToByteArray();
if (tileBuffer) {
const buffer = Buffer.from(tileBuffer);
// Warm memory cache
await this.memoryCache.set(key, buffer, NyxTTL.HOURLY_EPHEMERIS);
return buffer;
}
} catch (error) {
// S3 miss - need to generate
}
// Generate tile
const tile = await this.generateTile(layer, z, x, y, theme);
// Store in S3 for CDN
await this.s3Client.putObject({
Bucket: 'nyx-tiles',
Key: s3Key,
Body: tile,
ContentType: 'image/webp',
CacheControl: 'public, max-age=604800',
});
// Warm memory cache
await this.memoryCache.set(key, tile, NyxTTL.HOURLY_EPHEMERIS);
return tile;
}
// Pre-warm tiles for popular regions
async prewarmTiles(
layer: string,
centerRa: number,
centerDec: number,
zoomRange: [number, number],
theme: string
): Promise<void> {
const tiles = this.getTilesInRegion(centerRa, centerDec, zoomRange);
for (const { z, x, y } of tiles) {
// Check if already cached
const key = NyxCacheKeys.tile(layer, z, x, y, theme);
const exists = await this.memoryCache.has(key);
if (!exists) {
// Generate and cache in background
this.getTile(layer, z, x, y, theme).catch(() => {
// Log but don't fail prewarm
});
}
}
}
}
Realtime Service (No Caching)#
// libs/nyx/realtime-service/src/handlers/satellite-tracker.ts
export class SatelliteTracker {
// Real-time tracking does NOT use caching
// Data is streamed directly to clients via WebSocket
async trackSatellite(
noradId: number,
observerLocation: ObserverLocation,
ws: WebSocket
): Promise<void> {
// Always compute fresh positions for tracking
const updateInterval = setInterval(async () => {
const position = await this.computeService.getSatellitePosition(
noradId,
new Date()
);
const visibility = this.calculateVisibility(position, observerLocation);
ws.send(
JSON.stringify({
type: 'satellite_position',
data: { position, visibility },
timestamp: Date.now(),
})
);
}, 1000); // Update every second
ws.on('close', () => clearInterval(updateInterval));
}
// Only cache predictions, not real-time positions
async getPredictedPasses(
noradId: number,
location: ObserverLocation,
hours: number
): Promise<SatellitePass[]> {
const key = `nyx:passes:${noradId}:${this.hashLocation(location)}:${hours}`;
return withRedisCache(
this.redisClient,
() => this.computePasses(noradId, location, hours),
{
prefix: key,
ttl: NyxTTL.RISE_SET_TIMES,
}
);
}
}
CDN Integration#
CloudFront Configuration#
# infrastructure/cloudfront/nyx-tiles.yaml
Distribution:
Origins:
- Id: S3TileOrigin
DomainName: nyx-tiles.s3.amazonaws.com
S3OriginConfig:
OriginAccessIdentity: !Sub origin-access-identity/cloudfront/${CloudFrontOriginAccessIdentity}
- Id: APIOrigin
DomainName: api.nyx.oshun.com
CustomOriginConfig:
OriginProtocolPolicy: https-only
CacheBehaviors:
# Static tiles - long cache
- PathPattern: '/tiles/v*/*/*/*/*.webp'
TargetOriginId: S3TileOrigin
ViewerProtocolPolicy: redirect-to-https
CachePolicyId: !Ref LongCachePolicy
Compress: true
# Dynamic API - no cache or short cache
- PathPattern: '/api/*'
TargetOriginId: APIOrigin
ViewerProtocolPolicy: redirect-to-https
CachePolicyId: !Ref NoCachePolicy
CachePolicies:
LongCachePolicy:
MinTTL: 604800 # 7 days
DefaultTTL: 2592000 # 30 days
MaxTTL: 31536000 # 1 year
ParametersInCacheKeyAndForwardedToOrigin:
EnableAcceptEncodingGzip: true
EnableAcceptEncodingBrotli: true
HeadersConfig:
HeaderBehavior: whitelist
Headers:
- Accept
NoCachePolicy:
MinTTL: 0
DefaultTTL: 0
MaxTTL: 1
Tile URL Versioning#
// Version tiles for cache busting
export const TILE_VERSION = 'v2';
export function getTileUrl(
layer: string,
z: number,
x: number,
y: number,
theme: string = 'dark'
): string {
const baseUrl = process.env.CDN_BASE_URL || 'https://cdn.nyx.oshun.com';
return `${baseUrl}/tiles/${TILE_VERSION}/${layer}/${theme}/${z}/${x}/${y}.webp`;
}
// For cache invalidation, update version and regenerate
export async function invalidateTileLayer(layer: string): Promise<void> {
// Increment version in deployment config
// Old URLs become 404, new URLs are cache misses
// CDN fetches from origin, caches new version
}
Browser Cache Headers#
// Fastify plugin for cache headers
export function cacheHeadersPlugin(fastify: FastifyInstance): void {
fastify.addHook('onSend', async (request, reply, payload) => {
const path = request.url;
if (path.startsWith('/tiles/')) {
// Static tiles - immutable
reply.header('Cache-Control', 'public, max-age=31536000, immutable');
reply.header('Vary', 'Accept-Encoding');
} else if (path.startsWith('/api/catalog/')) {
// Catalog queries - short cache
reply.header('Cache-Control', 'public, max-age=60, s-maxage=300');
} else if (path.startsWith('/api/ephemeris/')) {
// Ephemeris - very short cache
reply.header('Cache-Control', 'public, max-age=30, s-maxage=60');
} else if (path.startsWith('/api/realtime/')) {
// Realtime - no cache
reply.header('Cache-Control', 'no-store, no-cache, must-revalidate');
}
return payload;
});
}
Metrics & Monitoring#
Cache Metrics Configuration#
// libs/nyx/cache/src/metrics.ts
import { createCacheMetrics, CacheMetrics } from '@oshun/cache';
// Create metrics for each cache layer
export const nyxCatalogCacheMetrics = createCacheMetrics({
name: 'nyx_catalog_cache',
labels: { service: 'catalog', layer: 'l2' },
});
export const nyxComputeCacheMetrics = createCacheMetrics({
name: 'nyx_compute_cache',
labels: { service: 'compute', layer: 'l2' },
});
export const nyxTileCacheMetrics = createCacheMetrics({
name: 'nyx_tile_cache',
labels: { service: 'render', layer: 'l1' },
});
// Custom Nyx-specific metrics
export const nyxMetrics = {
// Ephemeris computation time
ephemerisComputeTime: new Histogram({
name: 'nyx_ephemeris_compute_duration_seconds',
help: 'Time to compute ephemeris data',
labelNames: ['object_type', 'cache_status'],
buckets: [0.01, 0.05, 0.1, 0.5, 1, 5, 10],
}),
// Tile generation time
tileGenerationTime: new Histogram({
name: 'nyx_tile_generation_duration_seconds',
help: 'Time to generate a sky tile',
labelNames: ['layer', 'zoom_level'],
buckets: [0.1, 0.5, 1, 2, 5, 10, 30],
}),
// Cache size tracking
cacheSize: new Gauge({
name: 'nyx_cache_size_bytes',
help: 'Current cache size in bytes',
labelNames: ['cache_name', 'layer'],
}),
// TLE freshness
tleFreshness: new Gauge({
name: 'nyx_tle_age_seconds',
help: 'Age of TLE data in seconds',
labelNames: ['norad_id', 'satellite_name'],
}),
};
Health Check Endpoints#
// libs/nyx/common/src/health/cache-health.ts
export async function checkCacheHealth(): Promise<HealthStatus> {
const checks: HealthCheck[] = [];
// Redis connectivity
try {
const start = Date.now();
await nyxRedisClient.ping();
const latency = Date.now() - start;
checks.push({
name: 'redis',
status: latency < 100 ? 'healthy' : 'degraded',
latencyMs: latency,
});
} catch (error) {
checks.push({
name: 'redis',
status: 'unhealthy',
error: error.message,
});
}
// Memory cache stats
const memStats = nyxMemoryCache.stats();
checks.push({
name: 'memory_cache',
status: memStats.hitRate > 0.5 ? 'healthy' : 'degraded',
hitRate: memStats.hitRate,
size: memStats.size,
entries: memStats.entries,
});
// Overall status
const overallStatus = checks.every((c) => c.status === 'healthy')
? 'healthy'
: checks.some((c) => c.status === 'unhealthy')
? 'unhealthy'
: 'degraded';
return { status: overallStatus, checks };
}
Dashboard Queries (Prometheus/Grafana)#
# Cache hit rate by service
sum(rate(nyx_catalog_cache_hits_total[5m])) /
(sum(rate(nyx_catalog_cache_hits_total[5m])) +
sum(rate(nyx_catalog_cache_misses_total[5m])))
# Cache operation latency (p99)
histogram_quantile(0.99,
sum(rate(nyx_catalog_cache_operation_duration_seconds_bucket[5m])) by (le, operation)
)
# Tile generation latency by zoom level
histogram_quantile(0.95,
sum(rate(nyx_tile_generation_duration_seconds_bucket[5m])) by (le, zoom_level)
)
# TLE data freshness alert
max(nyx_tle_age_seconds) > 14400 # Alert if any TLE > 4 hours old
# Memory cache eviction rate
rate(nyx_tile_cache_evictions_total[5m])
Implementation Guidelines#
Cache Integration Checklist#
-
Identify Data Characteristics
- Access pattern (read-heavy, write-heavy, mixed)
- Update frequency (real-time, hourly, daily, static)
- Data size (per entry and total)
- Consistency requirements (strong, eventual)
-
Select Cache Layer
- CDN for static/immutable content
- Memory for hot data with sub-millisecond requirements
- Redis for shared/distributed data
- No cache for real-time streaming data
-
Define Key Structure
- Use consistent naming convention
- Include version/timestamp for cache busting
- Support pattern-based invalidation
-
Configure TTL
- Use NyxTTL constants
- Consider data freshness requirements
- Implement stale-while-revalidate where appropriate
-
Implement Invalidation
- Subscribe to relevant pub/sub channels
- Handle cascade invalidation
- Test invalidation under load
-
Add Metrics
- Instrument with cache metrics
- Set up alerting for low hit rates
- Monitor cache size and eviction rates
-
Error Handling
- Graceful degradation on cache failure
- Circuit breaker for Redis failures
- Fallback to source of truth
Example Implementation Pattern#
// Complete example: Cached ephemeris service
export class CachedEphemerisService {
private memoryCache: OshunMemoryCache;
private redisClient: OshunRedisClient;
private lockManager: OshunLockManager;
private metrics: CacheMetrics;
private circuitBreaker: OshunCircuitBreaker;
async getEphemeris(objectId: string, date: Date): Promise<EphemerisData> {
const key = NyxCacheKeys.ephemeris(objectId, formatDate(date));
// Metrics
const timer = this.metrics.startTimer();
try {
// L1: Memory
const memResult = await this.memoryCache.get<EphemerisData>(key);
if (memResult) {
timer.end({ cache: 'l1_hit' });
this.metrics.hit();
return memResult;
}
// L2: Redis (with circuit breaker)
if (this.circuitBreaker.isAllowed()) {
try {
const redisResult = await this.redisClient.get<EphemerisData>(key);
if (redisResult) {
await this.memoryCache.set(
key,
redisResult,
NyxTTL.HOURLY_EPHEMERIS
);
timer.end({ cache: 'l2_hit' });
this.metrics.hit();
return redisResult;
}
this.circuitBreaker.recordSuccess();
} catch (error) {
this.circuitBreaker.recordFailure();
// Continue to compute
}
}
// Compute with lock
const lock = await this.lockManager.acquire(
`eph:${objectId}:${formatDate(date)}`
);
try {
// Double-check
const recheck = await this.redisClient.get<EphemerisData>(key);
if (recheck) return recheck;
const computed = await this.computeEphemeris(objectId, date);
// Cache at all levels
await Promise.all([
this.memoryCache.set(key, computed, NyxTTL.HOURLY_EPHEMERIS),
this.redisClient.set(key, computed, NyxTTL.DAILY_EPHEMERIS),
]);
timer.end({ cache: 'miss' });
this.metrics.miss();
return computed;
} finally {
await lock.release();
}
} catch (error) {
timer.end({ cache: 'error' });
this.metrics.error();
throw error;
}
}
}
Summary#
The Nyx Cosmic Observatory caching strategy leverages the existing @oshun/cache infrastructure with domain-specific optimizations:
| Layer | Technology | Use Case | TTL Range |
|---|---|---|---|
| L0 | CloudFront CDN | Static tiles, assets | 7d - 1 year |
| L1 | OshunMemoryCache | Hot data, current viewport | 30s - 15min |
| L2 | OshunRedisClient | Shared ephemeris, user data | 1min - 7 days |
| L3 | PostgreSQL | Source of truth | N/A |
Key principles:
- No caching for real-time data (satellite positions, live sky updates)
- Short TTL for computed data (ephemeris, rise/set times)
- Long TTL for static catalogs (star data, constellation boundaries)
- CDN for immutable tiles (versioned URLs for cache busting)
- Distributed invalidation via Redis pub/sub
- Stampede protection with distributed locks
- Graceful degradation with circuit breakers
This strategy ensures low-latency responses for interactive sky exploration while maintaining data accuracy for astronomical computations.