Emi Griffith
7989f142a1
The derived store's key/token formats existed in three places — each endpoint, api_cell's slice assembly, and migrate.py — where any drift would silently split the cache (endpoints missing rows the bundle wrote, migrate materializing rows nobody reads). They are now defined once in views.py (grade_key/calendar_key/day_key/forecast_key, history_token/ recent_token/day_token) and consumed everywhere, with a pinning test so a format change is always deliberate. The four data endpoints shared two copy-pasted sequences, now helpers: - _fetch_history: history (+ optional recent bundle) fetch with upstream failures mapped to clean HTTP errors and an empty record to 404. - _cached_response: If-None-Match 304 / token-valid store replay / build + persist + serve, with calendar's dont-persist-placeless rule as an explicit flag. Each endpoint is now its audit run + identity + a build callback (~10 lines); api_day's hourly-token special case moved into day_token. New tests: identity format pins, rate-limit 503 parametrized across all five data routes, prefetch=1 never touching upstream (cold 204, warm history-only slices), and calendar's placeless-payload retry behavior.
584 lines
27 KiB
Python
584 lines
27 KiB
Python
"""Thermograph API — grade recent local weather against ~45 years of climatology."""
|
||
import contextlib
|
||
import datetime
|
||
import functools
|
||
import hashlib
|
||
import json
|
||
import os
|
||
|
||
import pandas as pd
|
||
from fastapi import APIRouter, FastAPI, HTTPException, Query, Request, Response
|
||
from fastapi.middleware.gzip import GZipMiddleware
|
||
from fastapi.responses import RedirectResponse
|
||
from fastapi.staticfiles import StaticFiles
|
||
|
||
import audit
|
||
import climate
|
||
import grid
|
||
import places
|
||
import store
|
||
import views
|
||
|
||
FRONTEND_DIR = os.path.join(os.path.dirname(__file__), "..", "frontend")
|
||
|
||
# Everything (pages, assets, API) is served under this base path so the app can
|
||
# live at https://<host>/thermograph/ behind a shared domain. Override with the
|
||
# THERMOGRAPH_BASE env var. The frontend uses base-relative URLs, so it follows
|
||
# this automatically without hardcoding the prefix.
|
||
BASE = "/" + os.environ.get("THERMOGRAPH_BASE", "/thermograph").strip("/")
|
||
|
||
|
||
def _weather_fetch_error(e) -> HTTPException:
|
||
"""A clean, retryable message for a rate limit; the raw error otherwise."""
|
||
low = str(e).lower()
|
||
reason = (climate._rate_limit_reason(e) or "").lower()
|
||
blob = low + " " + reason
|
||
if climate._is_rate_limit(e) or "429" in low or "rate-limited" in low or "limit" in reason:
|
||
if "daily" in blob or "tomorrow" in blob: # daily quota exhausted — resets tomorrow
|
||
return HTTPException(
|
||
status_code=503,
|
||
detail="Open-Meteo's daily request limit is exhausted — new locations will work again "
|
||
"tomorrow. Places you've already viewed still work.",
|
||
)
|
||
return HTTPException(
|
||
status_code=503,
|
||
detail="The weather service is rate-limited right now — please try again in a minute.",
|
||
)
|
||
return HTTPException(status_code=502, detail=f"weather data fetch failed: {e}")
|
||
|
||
|
||
@contextlib.asynccontextmanager
|
||
async def _lifespan(app):
|
||
# Warm the local place-name index (/suggest's typo tolerance) in the
|
||
# background; the app boots and serves fine without it — suggestions just
|
||
# fall back to the upstream geocoder until it's ready. A server-startup
|
||
# hook (not import time) so offline importers (tests, the migrate script's
|
||
# dependencies) don't kick off a GeoNames download.
|
||
places.start_loading()
|
||
yield
|
||
|
||
|
||
app = FastAPI(title="Thermograph", version="0.2.0", lifespan=_lifespan)
|
||
|
||
# Compress every sizeable response (the 2-year calendar JSON shrinks ~6-8×).
|
||
# Applies to API JSON and static assets alike; tiny responses are left alone.
|
||
app.add_middleware(GZipMiddleware, minimum_size=1024)
|
||
|
||
|
||
@app.middleware("http")
|
||
async def revalidate_static(request, call_next):
|
||
"""Serve the frontend with no-cache (NOT no-store): browsers may keep a copy
|
||
but must revalidate it on every use. Starlette's FileResponse/StaticFiles
|
||
already emit ETag + Last-Modified, so an unchanged asset costs one conditional
|
||
request answered with an empty 304 instead of a full re-download — page-to-page
|
||
navigation stops re-transferring the JS/CSS/HTML while still picking up every
|
||
deploy immediately (no "my change isn't showing" bugs)."""
|
||
response = await call_next(request)
|
||
path = request.url.path
|
||
pages = (BASE, f"{BASE}/", f"{BASE}/calendar", f"{BASE}/day", f"{BASE}/compare", f"{BASE}/legend")
|
||
if path.endswith((".js", ".css", ".html")) or path in pages:
|
||
response.headers["Cache-Control"] = "no-cache"
|
||
return response
|
||
|
||
|
||
# --- derived-store plumbing --------------------------------------------------
|
||
# Every graded payload is cached in SQLite under (kind, cell, key) and validated
|
||
# by a token that encodes what it was computed from (see store.py). The freshness
|
||
# drivers stay where they were — climate.get_history tops up the archive tail
|
||
# hourly and get_recent_forecast refetches hourly — and the tokens are derived
|
||
# from what those return, so a cached payload expires exactly when its inputs
|
||
# change and never before. The same tokens double as ETags: a client sending
|
||
# If-None-Match gets an empty 304 without the payload even being loaded.
|
||
# The payloads themselves are assembled in views.py, shared with the offline
|
||
# migrate script.
|
||
|
||
def _etag_for(kind: str, cell_id: str, key: str, token: str) -> str:
|
||
"""Deterministic weak ETag from a payload's identity + validity token. Weak
|
||
because the same content may be served under different encodings (gzip)."""
|
||
h = hashlib.sha1(f"{kind}:{cell_id}:{key}:{token}".encode()).hexdigest()[:20]
|
||
return f'W/"{h}"'
|
||
|
||
|
||
def _not_modified(request: Request, etag: str) -> bool:
|
||
"""Does the client already hold this exact payload? Answerable from the token
|
||
alone — no payload load needed."""
|
||
inm = request.headers.get("if-none-match")
|
||
if not inm:
|
||
return False
|
||
tags = {t.strip() for t in inm.split(",")}
|
||
return "*" in tags or etag in tags or etag.removeprefix("W/") in tags
|
||
|
||
|
||
def _encode(payload: dict) -> bytes:
|
||
"""Compact JSON bytes, matching store.put_payload's encoding (allow_nan=False
|
||
mirrors Starlette — a NaN from grading should fail loudly, not reach a client)."""
|
||
return json.dumps(payload, default=str, allow_nan=False, separators=(",", ":")).encode()
|
||
|
||
|
||
def _json_response(body: bytes, etag: str | None = None) -> Response:
|
||
headers = {"ETag": etag} if etag else {}
|
||
return Response(content=body, media_type="application/json", headers=headers)
|
||
|
||
|
||
def _fetch_history(run, cell, recent_too=False, recent_phase="recent"):
|
||
"""The shared fetch preamble for every data route: the archive record (and
|
||
optionally the hourly recent/forecast bundle) with upstream failures mapped
|
||
to clean HTTP errors and an empty record to a 404."""
|
||
try:
|
||
with run.phase("history"):
|
||
history, cache_meta = climate.get_history(cell)
|
||
recent = None
|
||
if recent_too:
|
||
with run.phase(recent_phase):
|
||
recent = climate.get_recent_forecast(cell)
|
||
except Exception as e: # noqa: BLE001
|
||
raise _weather_fetch_error(e)
|
||
if history.empty:
|
||
raise HTTPException(status_code=404, detail="No historical data for this cell.")
|
||
return history, cache_meta, recent
|
||
|
||
|
||
def _cached_response(request, run, kind, cell, key, token, build, cache_placeless=True):
|
||
"""The shared derived-store flow behind every per-view endpoint:
|
||
If-None-Match -> empty 304; a token-valid store row -> replay its exact
|
||
bytes; otherwise resolve the place label, build the payload, persist, serve.
|
||
|
||
``build(place) -> payload`` does any endpoint-specific audit tagging itself.
|
||
``cache_placeless=False`` skips persisting a payload whose place label
|
||
failed to resolve (a transient reverse-geocode miss) — otherwise the
|
||
bare-coordinates fallback would stick for the life of the token."""
|
||
cid = cell["id"]
|
||
etag = _etag_for(kind, cid, key, token)
|
||
if _not_modified(request, etag):
|
||
run.set(run_type="cache", not_modified=True)
|
||
return Response(status_code=304, headers={"ETag": etag})
|
||
body = store.get_payload(kind, cid, key, token)
|
||
if body is not None:
|
||
run.set(run_type="cache", history_source="store")
|
||
return _json_response(body, etag)
|
||
with run.phase("reverse_geocode"):
|
||
place = climate.reverse_geocode(cell["center_lat"], cell["center_lon"])
|
||
payload = build(place)
|
||
return _json_response(
|
||
store.put_payload(kind, cid, key, token, payload,
|
||
cache=cache_placeless or place is not None), etag)
|
||
|
||
|
||
|
||
# --- endpoints ----------------------------------------------------------------
|
||
|
||
def api_geocode(q: str = Query(..., min_length=1)):
|
||
try:
|
||
return {"results": climate.geocode(q)}
|
||
except Exception as e: # noqa: BLE001 - surface upstream failures to the client
|
||
raise HTTPException(status_code=502, detail=f"geocoding failed: {e}")
|
||
|
||
|
||
_SUGGEST_LIMIT = 5
|
||
|
||
|
||
@functools.lru_cache(maxsize=1024)
|
||
def _suggest_upstream(q: str) -> tuple:
|
||
"""Open-Meteo lookup for /suggest, memoized per query string — type-ahead
|
||
re-asks the same prefixes constantly (backspacing, retyping). Failures
|
||
raise and are not cached, so a transient upstream error doesn't stick."""
|
||
return tuple(climate.geocode(q, count=_SUGGEST_LIMIT))
|
||
|
||
|
||
def _suggest_score(r: dict, exact: bool) -> int:
|
||
"""Prominence rank with an exactness boost — big enough that a real place
|
||
beats a same-size typo match, small enough that a hamlet spelled exactly
|
||
like the typo can't outrank a metropolis one edit away ("Seatle", a
|
||
village, must not beat Seattle)."""
|
||
pop = r.get("population") or 0
|
||
return pop * 4 + 1 if exact else pop
|
||
|
||
|
||
def _suggest_merge(local: list, upstream: tuple, limit: int) -> list:
|
||
"""Blend local-index and upstream results into one top-`limit` list.
|
||
Everything the user's spelling matches exactly counts as exact; only the
|
||
local index's typo-tolerant matches take the fuzzy (unboosted) score."""
|
||
scored = [(r, _suggest_score(r, r.get("match") != "fuzzy")) for r in local]
|
||
scored += [(r, _suggest_score(r, True)) for r in upstream]
|
||
scored.sort(key=lambda t: t[1], reverse=True)
|
||
out, seen = [], set()
|
||
for r, _ in scored:
|
||
key = ((r.get("name") or "").casefold(), r.get("admin1") or "",
|
||
r.get("country_code") or "")
|
||
if key not in seen:
|
||
seen.add(key)
|
||
out.append(r)
|
||
if len(out) == limit:
|
||
break
|
||
return out
|
||
|
||
|
||
def api_suggest(q: str = Query(..., min_length=1)):
|
||
"""Type-ahead location suggestions: the top 5 places for a (possibly
|
||
typo'd) query prefix. The local GeoNames index answers instantly and
|
||
tolerates a single-letter typo; the upstream geocoder fills remaining slots
|
||
with what the index doesn't know (neighbourhoods, postcodes). When both
|
||
come up empty, one query token is respelled against known place-name tokens
|
||
and retried ("pest seattle" → "west seattle"); `corrected` reports the
|
||
respelling that produced the results."""
|
||
q = q.strip()
|
||
if len(q) < 2:
|
||
return {"results": [], "corrected": None}
|
||
local = places.search(q, _SUGGEST_LIMIT) # None while the index loads
|
||
results = list(local or [])
|
||
upstream_error = None
|
||
# Consult the upstream geocoder unless the local index already answered
|
||
# convincingly: full slots and a substantial place matching the spelling as
|
||
# typed. Fuzzy hits don't count as convincing — they're guesses, and when
|
||
# the query is an alternate name the index doesn't know ("münchen" prefix-
|
||
# matches only small towns; Munich lives upstream), neither those towns nor
|
||
# a coincidental fuzzy big-city hit may suppress the real answer.
|
||
prominent = max((r.get("population") or 0 for r in results
|
||
if r.get("match") == "prefix"), default=0)
|
||
if len(results) < _SUGGEST_LIMIT or prominent < 100_000:
|
||
try:
|
||
results = _suggest_merge(results, _suggest_upstream(q), _SUGGEST_LIMIT)
|
||
except Exception as e: # noqa: BLE001 - local results (if any) still serve
|
||
upstream_error = e
|
||
corrected = None
|
||
if not results and len(q) >= 4:
|
||
for phrase in places.corrections(q):
|
||
hits = places.search(phrase, _SUGGEST_LIMIT) or []
|
||
if not hits:
|
||
try:
|
||
hits = list(_suggest_upstream(phrase))
|
||
except Exception: # noqa: BLE001 - a failed probe just means no hits
|
||
hits = []
|
||
if hits:
|
||
results, corrected = hits[:_SUGGEST_LIMIT], phrase
|
||
break
|
||
if not results and local is None and upstream_error is not None:
|
||
raise HTTPException(status_code=502, detail=f"geocoding failed: {upstream_error}")
|
||
return {"results": results[:_SUGGEST_LIMIT], "corrected": corrected}
|
||
|
||
|
||
def api_place(
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
):
|
||
"""Best-effort neighbourhood/city label for a point — the same string the view
|
||
endpoints expose as ``place`` (snapped to the grid cell, reverse-geocoded and
|
||
cached). Resolved on its own so the compare page can show a location's name as
|
||
soon as it's added, before its full series loads."""
|
||
cell = grid.snap(lat, lon)
|
||
with audit.RunAudit(endpoint="place", lat=round(lat, 4), lon=round(lon, 4),
|
||
cell_id=cell["id"]) as run:
|
||
with run.phase("reverse_geocode"):
|
||
place = climate.reverse_geocode(cell["center_lat"], cell["center_lon"])
|
||
return {"place": place,
|
||
"cell": {"center_lat": cell["center_lat"], "center_lon": cell["center_lon"]}}
|
||
|
||
|
||
def api_grade(
|
||
request: Request,
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
date: str | None = Query(None, description="target date YYYY-MM-DD (default today)"),
|
||
days: int = Query(14, ge=1, le=60, description="days of history to grade before the target"),
|
||
after: int = Query(14, ge=0, le=14,
|
||
description="days to grade after the target (observed, or forecast when future; "
|
||
"the forecast reaches ~7 days out so future days cap there)"),
|
||
):
|
||
target = (
|
||
pd.Timestamp(date).normalize()
|
||
if date
|
||
else pd.Timestamp(datetime.date.today())
|
||
)
|
||
cell = grid.snap(lat, lon)
|
||
|
||
with audit.RunAudit(
|
||
endpoint="grade",
|
||
lat=round(lat, 4),
|
||
lon=round(lon, 4),
|
||
target_date=target.date().isoformat(),
|
||
recent_days=days,
|
||
cell_id=cell["id"],
|
||
) as run:
|
||
history, cache_meta, recent = _fetch_history(run, cell, recent_too=True)
|
||
return _cached_response(
|
||
request, run, "grade", cell,
|
||
views.grade_key(target, days, after), views.recent_token(history, cell["id"]),
|
||
lambda place: views.build_grade(cell, target, days, history, recent,
|
||
cache_meta, place, run, after=after))
|
||
|
||
|
||
def api_calendar(
|
||
request: Request,
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
start: str | None = Query(None, description="first date YYYY-MM-DD (overrides months)"),
|
||
end: str | None = Query(None, description="last date YYYY-MM-DD (default = latest available)"),
|
||
months: int = Query(24, ge=1, le=24, description="months back to grade when no start given"),
|
||
):
|
||
"""Grade every day over a date range (default: last 2 years) for the calendar view.
|
||
|
||
A custom [start, end] range is supported and capped at ~2 years per request;
|
||
the frontend splits longer spans into successive 2-year chunks. Grades against
|
||
the already-cached history record (which reaches to ~6 days ago), so no extra
|
||
fetch is needed. The graded payload is cached in the derived store keyed by
|
||
the clamped span and validated by the record's end date, so a repeat span is
|
||
a database read — across restarts — until new archive days arrive. Returns a
|
||
compact per-day shape (see grading.grade_range). New in API v2.
|
||
"""
|
||
cell = grid.snap(lat, lon)
|
||
|
||
with audit.RunAudit(
|
||
endpoint="calendar",
|
||
lat=round(lat, 4),
|
||
lon=round(lon, 4),
|
||
recent_days=months * 31, # approximate span graded
|
||
cell_id=cell["id"],
|
||
) as run:
|
||
history, cache_meta, _ = _fetch_history(run, cell)
|
||
start_ts, end_ts = views.cal_span(history, start, end, months)
|
||
|
||
def build(place):
|
||
payload = views.build_calendar(cell, history, start_ts, end_ts, months, place, run)
|
||
full = not cache_meta.get("cached", False)
|
||
run.set(run_type="full" if full else "partial",
|
||
history_source="fetch" if full else "cache")
|
||
return payload
|
||
|
||
# Compare loads several cells at once, so a transient reverse-geocode miss
|
||
# is most likely here; cache_placeless=False keeps that miss un-persisted.
|
||
return _cached_response(request, run, "calendar", cell,
|
||
views.calendar_key(start_ts, end_ts, months),
|
||
views.history_token(history), build,
|
||
cache_placeless=False)
|
||
|
||
|
||
def api_day(
|
||
request: Request,
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
date: str | None = Query(None, description="target date YYYY-MM-DD (default = latest available)"),
|
||
):
|
||
"""Full percentile breakdown for a single day: the value at every tier boundary
|
||
in that day-of-year's ±7-day window, plus where the observed values land.
|
||
|
||
Powers the single-day detail page. Grades against the cached history record;
|
||
for a date newer than the cache it pulls the recent window for the observation
|
||
(those payloads expire hourly — the recent bundle's own cadence — while fully
|
||
archived days stay valid until the record itself advances). New in API v2.
|
||
"""
|
||
cell = grid.snap(lat, lon)
|
||
|
||
with audit.RunAudit(
|
||
endpoint="day",
|
||
lat=round(lat, 4),
|
||
lon=round(lon, 4),
|
||
cell_id=cell["id"],
|
||
) as run:
|
||
history, cache_meta, _ = _fetch_history(run, cell)
|
||
last = pd.Timestamp(history["date"].max()).normalize()
|
||
target = pd.Timestamp(date).normalize() if date else last
|
||
run.set(target_date=target.date().isoformat())
|
||
|
||
def build(place):
|
||
payload = views.build_day(cell, history, target, place, run)
|
||
full = not cache_meta.get("cached", False)
|
||
run.set(run_type="full" if full else "partial",
|
||
history_source="fetch" if full else "cache")
|
||
return payload
|
||
|
||
return _cached_response(request, run, "day", cell,
|
||
views.day_key(target), views.day_token(history, target),
|
||
build)
|
||
|
||
|
||
def api_forecast(
|
||
request: Request,
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
days: int = Query(7, ge=1, le=14, description="how many forecast days ahead to grade"),
|
||
):
|
||
"""Grade the next `days` of forecast weather against local climatology.
|
||
|
||
Same shape as /grade (so the frontend renders it identically), but `recent`
|
||
holds the forward forecast — furthest-out day first. The forecast is fetched
|
||
fresh and cached only ~1 hour (see climate.get_recent_forecast) to track
|
||
updates; the graded payload's validity is tied to that fetch stamp, so it
|
||
expires exactly when a new forecast lands. New in API v2.
|
||
"""
|
||
cell = grid.snap(lat, lon)
|
||
|
||
with audit.RunAudit(endpoint="forecast", lat=round(lat, 4), lon=round(lon, 4),
|
||
recent_days=days, cell_id=cell["id"]) as run:
|
||
history, _, fc = _fetch_history(run, cell, recent_too=True, recent_phase="forecast")
|
||
today = pd.Timestamp(datetime.date.today())
|
||
|
||
def build(place):
|
||
payload = views.build_forecast(cell, days, history, fc, today, place, run)
|
||
run.set(run_type="partial")
|
||
return payload
|
||
|
||
return _cached_response(request, run, "forecast", cell,
|
||
views.forecast_key(today, days),
|
||
views.recent_token(history, cell["id"]), build)
|
||
|
||
|
||
def api_cell(
|
||
request: Request,
|
||
lat: float = Query(..., ge=-90, le=90),
|
||
lon: float = Query(..., ge=-180, le=180),
|
||
prefetch: int = Query(0, ge=0, le=1,
|
||
description="1 = warm-only: never fetch weather upstream; 204 for a cold cell"),
|
||
):
|
||
"""One bundle carrying every view's payload for a cell, so the frontend warms
|
||
all views with a single request instead of four.
|
||
|
||
Each slice is the EXACT payload its per-view endpoint returns — built by the
|
||
same builders and cached under the same derived-store keys/tokens — paired
|
||
with the etag that endpoint would emit. The client seeds its per-view cache
|
||
from the slices and later revalidates each view individually with
|
||
If-None-Match, so the bundle and the per-view endpoints stay one cache.
|
||
|
||
prefetch=1 is the neighbor-warming mode with a hard guarantee: it never
|
||
spends weather-API quota. A cell with no cached archive answers 204 (no
|
||
body), and only the history-derived slices (calendar + latest-day detail)
|
||
are built — grading recent/forecast days needs the hourly upstream bundle.
|
||
Reverse geocoding makes at most one Nominatim call for a never-labeled cell;
|
||
the client staggers neighbor prefetches to respect that service. New in API v2.
|
||
"""
|
||
cell = grid.snap(lat, lon)
|
||
today = pd.Timestamp(datetime.date.today())
|
||
|
||
with audit.RunAudit(endpoint="cell", lat=round(lat, 4), lon=round(lon, 4),
|
||
cell_id=cell["id"], prefetch=bool(prefetch)) as run:
|
||
recent = None
|
||
if prefetch:
|
||
history = climate.load_cached_history(cell)
|
||
if history is None or history.empty:
|
||
run.set(run_type="cold-skip")
|
||
return Response(status_code=204)
|
||
cache_meta = {"cached": True}
|
||
else:
|
||
history, cache_meta, recent = _fetch_history(run, cell, recent_too=True)
|
||
|
||
cid = cell["id"]
|
||
last = pd.Timestamp(history["date"].max()).normalize()
|
||
|
||
with run.phase("reverse_geocode"):
|
||
place = climate.reverse_geocode(cell["center_lat"], cell["center_lon"])
|
||
|
||
def slice_for(kind: str, key: str, token: str, build) -> dict:
|
||
"""The endpoint's derived row (or build + store it), paired with the
|
||
etag that endpoint would emit for the same request."""
|
||
etag = _etag_for(kind, cid, key, token)
|
||
data = store.get_json(kind, cid, key, token)
|
||
if data is None:
|
||
data = build()
|
||
store.put_payload(kind, cid, key, token, data)
|
||
return {"etag": etag, "data": data}
|
||
|
||
slices = {}
|
||
hist_token = views.history_token(history)
|
||
# Calendar: the default last-24-months span — what the calendar view (and
|
||
# the cross-view prefetch) requests first.
|
||
start_ts, end_ts = views.cal_span(history, None, None, 24)
|
||
slices["calendar"] = slice_for(
|
||
"calendar", views.calendar_key(start_ts, end_ts, 24), hist_token,
|
||
lambda: views.build_calendar(cell, history, start_ts, end_ts, 24, place, run))
|
||
|
||
if prefetch:
|
||
# Latest archived day: its observation comes from history alone, so
|
||
# it's buildable without the (skipped) recent bundle.
|
||
slices["day"] = slice_for(
|
||
"day", views.day_key(last), hist_token,
|
||
lambda: views.build_day(cell, history, last, place, run))
|
||
else:
|
||
rf_token = views.recent_token(history, cid)
|
||
slices["grade"] = slice_for(
|
||
"grade", views.grade_key(today, 14, 14), rf_token,
|
||
lambda: views.build_grade(cell, today, 14, history, recent, cache_meta, place, run, after=14))
|
||
slices["forecast"] = slice_for(
|
||
"forecast", views.forecast_key(today, 7), rf_token,
|
||
lambda: views.build_forecast(cell, 7, history, recent, today, place, run))
|
||
slices["day"] = slice_for(
|
||
"day", views.day_key(today), views.day_token(history, today),
|
||
lambda: views.build_day(cell, history, today, place, run, recent=recent))
|
||
|
||
# The bundle's identity is the combination of its slices' identities.
|
||
etag = _etag_for("cell", cid, "bundle" + (":p" if prefetch else ""),
|
||
"|".join(s["etag"] for s in slices.values()))
|
||
if _not_modified(request, etag):
|
||
run.set(run_type="cache", not_modified=True)
|
||
return Response(status_code=304, headers={"ETag": etag})
|
||
run.set(run_type="bundle", slices=sorted(slices))
|
||
payload = {
|
||
"api_version": "v2",
|
||
"cell": cell,
|
||
"place": place,
|
||
"today": today.date().isoformat(),
|
||
"slices": slices,
|
||
}
|
||
# Not stored as its own derived row — the slices already are.
|
||
return _json_response(_encode(payload), etag)
|
||
|
||
|
||
# --- API versioning --------------------------------------------------------
|
||
# Non-backward-compatible additions land in a new version; every version stays
|
||
# mounted and served simultaneously. v1 is the original contract (grade/geocode);
|
||
# v2 adds the calendar. The unversioned /api/* paths are kept as aliases of v1 so
|
||
# existing clients keep working.
|
||
v1 = APIRouter(tags=["v1"])
|
||
v1.add_api_route("/geocode", api_geocode, methods=["GET"])
|
||
v1.add_api_route("/grade", api_grade, methods=["GET"])
|
||
|
||
v2 = APIRouter(tags=["v2"])
|
||
v2.add_api_route("/geocode", api_geocode, methods=["GET"])
|
||
v2.add_api_route("/suggest", api_suggest, methods=["GET"])
|
||
v2.add_api_route("/place", api_place, methods=["GET"])
|
||
v2.add_api_route("/grade", api_grade, methods=["GET"])
|
||
v2.add_api_route("/calendar", api_calendar, methods=["GET"])
|
||
v2.add_api_route("/day", api_day, methods=["GET"])
|
||
v2.add_api_route("/forecast", api_forecast, methods=["GET"])
|
||
v2.add_api_route("/cell", api_cell, methods=["GET"])
|
||
|
||
app.include_router(v1, prefix=f"{BASE}/api") # legacy unversioned == v1 (backward compatible)
|
||
app.include_router(v1, prefix=f"{BASE}/api/v1")
|
||
app.include_router(v2, prefix=f"{BASE}/api/v2")
|
||
|
||
|
||
# --- static frontend (served under BASE) -----------------------------------
|
||
def _page(name):
|
||
"""Route handler for one HTML page. Serves the file with its __ORIGIN__
|
||
placeholders (the link-preview/Open Graph tags) filled in as the request's
|
||
scheme://host + BASE — preview crawlers (Discord, Slack, …) need absolute
|
||
URLs, and the host differs between LAN and prod. The scheme comes from
|
||
X-Forwarded-Proto when a reverse proxy (Caddy) fronts the plain-HTTP
|
||
uvicorn; the proxy passes the original Host header through untouched."""
|
||
path = os.path.join(FRONTEND_DIR, name)
|
||
|
||
def route(request: Request):
|
||
with open(path, encoding="utf-8") as f:
|
||
html = f.read()
|
||
proto = request.headers.get("x-forwarded-proto") or request.url.scheme
|
||
host = request.headers.get("host") or request.url.netloc
|
||
html = html.replace("__ORIGIN__", f"{proto}://{host}{BASE}")
|
||
etag = f'W/"{hashlib.sha1(html.encode()).hexdigest()[:20]}"'
|
||
if _not_modified(request, etag):
|
||
return Response(status_code=304, headers={"ETag": etag})
|
||
return Response(html, media_type="text/html", headers={"ETag": etag})
|
||
return route
|
||
|
||
|
||
# The un-slashed base redirects to BASE/ so the frontend's relative asset URLs
|
||
# resolve correctly. The app stays scoped to BASE and never claims "/", leaving
|
||
# the domain root free for another app (e.g. a portfolio) to own via the proxy.
|
||
# Pages also answer HEAD — link-preview crawlers probe with it before fetching.
|
||
app.add_api_route(BASE, lambda: RedirectResponse(url=f"{BASE}/"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/", _page("index.html"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/calendar", _page("calendar.html"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/day", _page("day.html"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/compare", _page("compare.html"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
app.add_api_route(f"{BASE}/legend", _page("legend.html"), methods=["GET", "HEAD"], include_in_schema=False)
|
||
|
||
# Everything else under BASE (app.js, style.css, nav.js, …) is a static asset.
|
||
# Registered last so the explicit page routes above win.
|
||
app.mount(BASE, StaticFiles(directory=FRONTEND_DIR), name="static")
|