Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,18 @@ on:
jobs:
test:
runs-on: ubuntu-latest
services:
redis:
image: redis:7-alpine
ports:
- 6379:6379
options: >-
--health-cmd "redis-cli ping"
--health-interval 5s
--health-timeout 3s
--health-retries 10
env:
TEST_REDIS_URL: redis://localhost:6379
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Redis 없이 인메모리 캐시로 API만 실행하려면 다음 명령을 사
CACHE_BACKEND=memory docker compose up -d mcstatus-api
```

인메모리 캐시는 프로세스별로 독립적이며 재시작하면 초기화됩니다. 만료 항목은 해당 키를 다시 조회할 때 삭제되며, 용량 제한은 없습니다.
인메모리 캐시는 프로세스별로 독립적이며 재시작하면 초기화됩니다. 최대 10,000개를 보관하고, 저장 시 만료 항목과 가장 오래 사용하지 않은 항목을 정리합니다.

```bash
# Check status and logs
Expand All @@ -49,14 +49,16 @@ docker compose down
| 400 | 잘못된 대상 주소 |
| 502 | DNS 환경 또는 서버 응답 오류 |
| 500 | API 내부 오류 |
| 304 | 조건부 요청의 캐시 적중. 이전 응답 재사용 |

`status.latency`는 API 서버에서 Minecraft 서버까지의 status 응답 시간(ms)이며, 측정값이 없으면 `null`입니다. `timestamp`는 조회 완료 시각(UTC)입니다. HTTP 오류를 Minecraft 서버의 오프라인 상태로 판단하지 마세요.

## 조회·캐시 동작

- DNS 조회와 status 요청을 합쳐 3초로 제한합니다.
- 접속 가능·불가 결과를 선택한 백엔드에 60초 캐싱합니다. 캐시 응답은 기존 측정값과 시각을 유지합니다.
- 같은 프로세스에서 같은 주소의 동시 요청은 하나의 조회 결과를 공유하며, 신규 조회를 공유한 응답은 모두 `MISS`로 표시합니다. 다른 주소는 병렬 조회하며, 워커·컨테이너 간 중복 조회는 막지 않습니다.
- 4xx/5xx 오류는 캐싱하지 않습니다.
- `X-FastAPI-Cache: HIT/MISS`로 캐시 사용 여부를 확인할 수 있습니다.
- `X-Cache: HIT/MISS/BYPASS`로 캐시 재사용·신규 저장·우회를 구분합니다.
- `X-Cache-Created-At`은 캐시 저장 시각(UTC)이며 HIT에서도 유지됩니다. 저장하지 않은 응답에는 포함하지 않습니다.
- 요청의 캐시 지시어와 조건부 요청 헤더는 무시하며, 항상 서버의 60초 TTL을 따릅니다.
- Redis 읽기·쓰기 실패는 로그에 기록하며, 캐시 없이 실제 조회 결과를 반환합니다.
196 changes: 196 additions & 0 deletions app/cache.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
import asyncio
import hashlib
import json
import logging
import time
from collections import OrderedDict
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Awaitable, Callable, Protocol

from fastapi import Response
from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse
from redis import asyncio as aioredis

logger = logging.getLogger(__name__)
CACHE_PREFIX = "mcstatus-api:status:v1:"


@dataclass(frozen=True)
class CacheEntry:
body: bytes
created_at: datetime

def encode(self) -> str:
return json.dumps({
"body": self.body.decode("utf-8"),
"created_at": self.created_at.isoformat(),
})

@classmethod
def decode(cls, value: bytes) -> "CacheEntry":
data = json.loads(value)
created_at = datetime.fromisoformat(data["created_at"])
if created_at.tzinfo is None:
raise ValueError("Cache creation time must include a timezone")

return cls(
body=data["body"].encode("utf-8"),
created_at=created_at,
)


class CacheBackend(Protocol):
async def get(self, key: str) -> CacheEntry | None:
...

async def set(self, key: str, entry: CacheEntry, expire: int) -> None:
...


class MemoryCacheBackend:
def __init__(
self,
max_entries: int = 10_000,
clock: Callable[[], float] = time.monotonic,
):
if max_entries < 1:
raise ValueError("max_entries must be positive")

self._store: OrderedDict[str, tuple[float, CacheEntry]] = OrderedDict()
self._max_entries = max_entries
self._clock = clock

async def get(self, key: str) -> CacheEntry | None:
value = self._store.get(key)
if value is None:
return None

deadline, entry = value
if deadline <= self._clock():
del self._store[key]
return None

self._store.move_to_end(key)
return entry

async def set(self, key: str, entry: CacheEntry, expire: int) -> None:
now = self._clock()
expired_keys = [
stored_key
for stored_key, (deadline, _) in self._store.items()
if deadline <= now
]
for expired_key in expired_keys:
del self._store[expired_key]

self._store[key] = (now + expire, entry)
self._store.move_to_end(key)
while len(self._store) > self._max_entries:
self._store.popitem(last=False)


class RedisCacheBackend:
def __init__(self, redis: aioredis.Redis):
self.redis = redis

async def get(self, key: str) -> CacheEntry | None:
value = await self.redis.get(CACHE_PREFIX + key)
if value is None:
return None

return CacheEntry.decode(value)

async def set(self, key: str, entry: CacheEntry, expire: int) -> None:
await self.redis.set(CACHE_PREFIX + key, entry.encode(), ex=expire)


class StatusCache:
def __init__(self, backend: CacheBackend, expire: int = 60):
self.backend = backend
self.expire = expire
self._inflight: dict[str, asyncio.Task[Response]] = {}

async def respond(
self,
address: str,
query: Callable[[str], Awaitable[object]],
) -> Response:
address_hash = hashlib.sha256(address.encode("utf-8"))
cache_key = address_hash.hexdigest()
task = self._inflight.get(cache_key)
if task is None or task.done():
task = asyncio.create_task(self._respond(address, cache_key, query))
self._inflight[cache_key] = task
task.add_done_callback(lambda completed: self._finish_query(cache_key, completed))

# A disconnected client must not cancel the lookup shared by other clients.
return await asyncio.shield(task)

def _finish_query(self, cache_key: str, task: asyncio.Task[Response]) -> None:
if self._inflight.get(cache_key) is task:
del self._inflight[cache_key]

# Observe failures even when all clients stopped waiting for this task.
if not task.cancelled():
task.exception()

async def close(self) -> None:
tasks = list(self._inflight.values())
for task in tasks:
task.cancel()

await asyncio.gather(*tasks, return_exceptions=True)

async def _respond(
self,
address: str,
cache_key: str,
query: Callable[[str], Awaitable[object]],
) -> Response:
read_failed = False

try:
entry = await self.backend.get(cache_key)
except Exception:
logger.warning("Cache read failed; querying server directly", exc_info=True)
read_failed = True
else:
if entry is not None:
return self.cached_response(entry, "HIT")

result = await query(address)
body = JSONResponse(jsonable_encoder(result)).body
if read_failed:
return self.bypass_response(body)

entry = CacheEntry(body=body, created_at=datetime.now(timezone.utc))
try:
await self.backend.set(cache_key, entry, self.expire)
except Exception:
logger.warning("Cache write failed; returning uncached result", exc_info=True)
return self.bypass_response(body)

return self.cached_response(entry, "MISS")

@staticmethod
def bypass_response(body: bytes) -> Response:
return Response(
content=body,
media_type="application/json",
headers={
"X-Cache": "BYPASS",
},
)

@staticmethod
def cached_response(
entry: CacheEntry,
cache_status: str,
) -> Response:
headers = {
"X-Cache": cache_status,
"X-Cache-Created-At": entry.created_at.isoformat(),
}
return Response(content=entry.body, media_type="application/json", headers=headers)
32 changes: 17 additions & 15 deletions app/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,15 @@

from dns.exception import DNSException
from dns.resolver import NXDOMAIN, NoAnswer
from fastapi import FastAPI, HTTPException, Request
from fastapi import FastAPI, HTTPException, Request, Response
from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse
from fastapi_cache import FastAPICache
from fastapi_cache.backends.inmemory import InMemoryBackend
from fastapi_cache.backends.redis import RedisBackend
from fastapi_cache.decorator import cache
from mcstatus import JavaServer
from mcstatus.address import Address
from redis import asyncio as aioredis

from app.cache import MemoryCacheBackend, RedisCacheBackend, StatusCache

CACHE_TTL_SECONDS = 60
QUERY_TIMEOUT_SECONDS = 3

Expand All @@ -33,25 +31,27 @@


@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
async def lifespan(application: FastAPI) -> AsyncIterator[None]:
cache_backend = os.getenv("CACHE_BACKEND", "redis")
redis = None

if cache_backend == "memory":
backend = InMemoryBackend()
backend = MemoryCacheBackend()
elif cache_backend == "redis":
redis_url = os.getenv("REDIS_URL", "redis://localhost")
redis = aioredis.from_url(redis_url)
backend = RedisBackend(redis)
backend = RedisCacheBackend(redis)
else:
raise ValueError("CACHE_BACKEND must be 'memory' or 'redis'")

status_cache = StatusCache(backend, expire=CACHE_TTL_SECONDS)
try:
FastAPICache.init(backend, prefix="mcstatus-api-cache")
application.state.status_cache = status_cache
yield
finally:
await status_cache.close()
if redis is not None:
await redis.close()
await redis.close(close_connection_pool=True)


app = FastAPI(lifespan=lifespan)
Expand All @@ -71,7 +71,6 @@ async def internal_error_handler(request: Request, exc: Exception) -> JSONRespon
return JSONResponse(
status_code=500,
content={"detail": {"code": "INTERNAL_ERROR", "message": "Internal server error"}},
headers={"Cache-Control": "no-store"},
)


Expand Down Expand Up @@ -112,21 +111,25 @@ async def query_status(address: str):

@app.get(
"/java/{address}",
response_model=JavaServerResponse,
responses={
400: {"description": "Invalid target address (INVALID_ADDRESS)"},
502: {"description": "Protocol or lookup infrastructure error (UPSTREAM_ERROR)"},
500: {"description": "Internal API error (INTERNAL_ERROR)"},
},
)
@cache(expire=CACHE_TTL_SECONDS, namespace="java-status")
async def get_java_server(address: str) -> JavaServerResponse:
async def get_java_server(address: str, request: Request) -> Response:
status_cache = request.app.state.status_cache
return await status_cache.respond(address, build_java_server_response)


async def build_java_server_response(address: str) -> JavaServerResponse:
try:
Address.parse_address(address, default_port=JavaServer.DEFAULT_PORT)
except ValueError as exc:
raise HTTPException(
status_code=400,
detail={"code": "INVALID_ADDRESS", "message": "Invalid Minecraft server address"},
headers={"Cache-Control": "no-store"},
) from exc

try:
Expand All @@ -153,7 +156,6 @@ async def get_java_server(address: str) -> JavaServerResponse:
raise HTTPException(
status_code=502,
detail={"code": "UPSTREAM_ERROR", "message": "Failed to query Minecraft server status"},
headers={"Cache-Control": "no-store"},
) from exc

# Preserve the status structure and serialize invalid latency as null.
Expand Down
Loading
Loading