Eve library

Nyx Cosmic Observatory - Caching Strategy

Guide

Revision 1

On this page

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#

  1. Overview
  2. Cache Architecture
  3. Cache Layers
  4. Key Structure & Naming
  5. TTL Policies
  6. Invalidation Strategies
  7. Service-Specific Caching
  8. CDN Integration
  9. Metrics & Monitoring
  10. 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#

  1. Minimize Computation: Cache expensive ephemeris and position calculations
  2. Reduce Database Load: Cache catalog queries and user data
  3. Optimize Tile Delivery: CDN edge caching for map tiles
  4. Maintain Consistency: Proper invalidation for data accuracy
  5. Enable Offline: Local caching for mobile/PWA use cases

Cache Architecture#

text
┌─────────────────────────────────────────────────────────────────────────────┐
│                              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#

text
                     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:

http
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:

typescript
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:

typescript
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):

typescript
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.

typescript
// 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:

text
nyx:{service}:{entity}:{identifier}:{qualifiers}

Key Builders#

typescript
// 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#

typescript
// 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#

text
┌────────────────────┬────────────────────┬────────────────────┐
│                    │    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#

typescript
// 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)#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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)#

typescript
// 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#

yaml
# 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#

typescript
// 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#

typescript
// 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#

typescript
// 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#

typescript
// 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)#

promql
# 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#

  1. 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)
  2. 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
  3. Define Key Structure

    • Use consistent naming convention
    • Include version/timestamp for cache busting
    • Support pattern-based invalidation
  4. Configure TTL

    • Use NyxTTL constants
    • Consider data freshness requirements
    • Implement stale-while-revalidate where appropriate
  5. Implement Invalidation

    • Subscribe to relevant pub/sub channels
    • Handle cascade invalidation
    • Test invalidation under load
  6. Add Metrics

    • Instrument with cache metrics
    • Set up alerting for low hit rates
    • Monitor cache size and eviction rates
  7. Error Handling

    • Graceful degradation on cache failure
    • Circuit breaker for Redis failures
    • Fallback to source of truth

Example Implementation Pattern#

typescript
// 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:

  1. No caching for real-time data (satellite positions, live sky updates)
  2. Short TTL for computed data (ephemeris, rise/set times)
  3. Long TTL for static catalogs (star data, constellation boundaries)
  4. CDN for immutable tiles (versioned URLs for cache busting)
  5. Distributed invalidation via Redis pub/sub
  6. Stampede protection with distributed locks
  7. Graceful degradation with circuit breakers

This strategy ensures low-latency responses for interactive sky exploration while maintaining data accuracy for astronomical computations.