Skip to content

api-cache-server

Audience: Agent

Purpose

HTTP GET/POST proxy with in-memory caching and a queued upstream fetch. All use of community-maintained third-party APIs from this ecosystem should go through this service (or a deployment with the same contract): those endpoints are volunteer-run, typically without DDoS protection, and the cache is the fair-use strategy so apps do not hammer upstream services. The surface map uses it via fetchWithCache — not for journal files.

Tech stack

  • Runtime: Bun
  • Framework: Elysia (api-cache-server/api/src/app.ts)
  • CORS: @elysiajs/cors (broad origin in current code)
  • Prisma: src/prisma/ scaffold exists; not imported by app.ts — verify before relying on DB features

Layout

Path Role
api/package.json Scripts: dev (watch), start → src/app.ts
api/src/app.ts Routes: GET /, POST / with ?url= and optional maxCacheAge
api/src/cache.ts, queue.ts Cache + request queue
Dockerfile, docker-compose.yml Container deployment

Integration points

  • Consumers: any client that can fetch the service; in this ecosystem elite-dangerous-surface-map/ui/src/logic/externalDataLoaders/fetchWithCache.ts targets https://api-cache.howfe.org (not a relative path).

Extension points

  • Add routes or middleware in app.ts; keep cache key semantics (method:url:body) in mind when changing request shape.
  • If enabling Prisma, wire src/prisma/index.ts into handlers and document migrations.

Pitfalls / checks

  • Query param url required — missing url returns JSON error object.
  • Production URL is external — local dev needs a running api server and optionally a dev override in fetchWithCache (currently none).
  • Secrets: proxy can reach arbitrary URLs — restrict in production if the service is exposed.