feat: implement SSE-based real-time event distribution system with replay support and heartbeat functionality

2026-05-26 22:27:55 +08:00
parent 5c6ffa4742
commit 645e304b3e
20 changed files with 1449 additions and 119 deletions
@@ -0,0 +1,200 @@
+"""Versioned realtime observation patch normalization."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Iterable, List, Optional
+
+
+SCHEMA_TYPE = "city_observation_patch"
+SCHEMA_VERSION = 1
+EVENT_TYPE = "city_observation_patch.v1"
+
+
+class PatchValidationError(ValueError):
+    """Raised when a collector patch cannot become a replayable observation event."""
+
+
+def _normalize_city(value: Any) -> str:
+    return str(value or "").strip().lower()
+
+
+def _normalize_source(value: Any) -> str:
+    source = str(value or "").strip().lower()
+    return source or "weather"
+
+
+def _finite_number(value: Any) -> Optional[float]:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    if number != number or number in {float("inf"), float("-inf")}:
+        return None
+    return round(number, 2)
+
+
+def _first_number(*values: Any) -> Optional[float]:
+    for value in values:
+        number = _finite_number(value)
+        if number is not None:
+            return number
+    return None
+
+
+def _iter_runway_points(raw_points: Any) -> Iterable[Dict[str, Any]]:
+    if isinstance(raw_points, list):
+        for item in raw_points:
+            if isinstance(item, dict):
+                yield item
+
+
+def _normalize_runway_points(raw_points: Any) -> List[Dict[str, Any]]:
+    points: List[Dict[str, Any]] = []
+    for raw in _iter_runway_points(raw_points):
+        runway = str(raw.get("runway") or raw.get("rwy") or "").strip().upper()
+        temp = _first_number(
+            raw.get("temp"),
+            raw.get("target_runway_max"),
+            raw.get("tdz_temp"),
+            raw.get("mid_temp"),
+            raw.get("end_temp"),
+        )
+        if not runway and temp is None:
+            continue
+
+        point: Dict[str, Any] = {}
+        if runway:
+            point["runway"] = runway
+        if temp is not None:
+            point["temp"] = temp
+        for key in ("tdz_temp", "mid_temp", "end_temp", "target_runway_max"):
+            value = _finite_number(raw.get(key))
+            if value is not None:
+                point[key] = value
+        if isinstance(raw.get("is_settlement"), bool):
+            point["is_settlement"] = raw["is_settlement"]
+        if point:
+            points.append(point)
+    return points
+
+
+def _legacy_changes(patch: Dict[str, Any]) -> Dict[str, Any]:
+    changes = patch.get("changes")
+    return changes if isinstance(changes, dict) else {}
+
+
+def _payload_from_legacy(changes: Dict[str, Any]) -> Dict[str, Any]:
+    amos = changes.get("amos") if isinstance(changes.get("amos"), dict) else {}
+    runway_obs = amos.get("runway_obs") if isinstance(amos.get("runway_obs"), dict) else {}
+
+    payload: Dict[str, Any] = {}
+    temp = _finite_number(changes.get("temp"))
+    if temp is not None:
+        payload["temp"] = temp
+    max_so_far = _first_number(changes.get("max_so_far"), changes.get("current_max_so_far"))
+    if max_so_far is not None:
+        payload["max_so_far"] = max_so_far
+
+    station_code = str(
+        changes.get("station_code")
+        or changes.get("icao")
+        or amos.get("icao")
+        or ""
+    ).strip().upper()
+    if station_code:
+        payload["station_code"] = station_code
+
+    station_label = str(
+        changes.get("station_label")
+        or amos.get("station_label")
+        or amos.get("station_name")
+        or ""
+    ).strip()
+    if station_label:
+        payload["station_label"] = station_label
+
+    series_key = str(changes.get("series_key") or "").strip()
+    if series_key:
+        payload["series_key"] = series_key
+    payload["unit"] = str(changes.get("unit") or "celsius").strip().lower() or "celsius"
+
+    raw_runway_points = changes.get("runway_points")
+    if raw_runway_points is None:
+        raw_runway_points = runway_obs.get("point_temperatures")
+    runway_points = _normalize_runway_points(raw_runway_points)
+    if runway_points:
+        payload["runway_points"] = runway_points
+
+    hourly = changes.get("hourly")
+    if isinstance(hourly, dict):
+        payload["hourly"] = hourly
+
+    return payload
+
+
+def _payload_from_v1(raw_payload: Any) -> Dict[str, Any]:
+    if not isinstance(raw_payload, dict):
+        return {}
+
+    payload: Dict[str, Any] = {}
+    temp = _finite_number(raw_payload.get("temp"))
+    if temp is not None:
+        payload["temp"] = temp
+    max_so_far = _finite_number(raw_payload.get("max_so_far"))
+    if max_so_far is not None:
+        payload["max_so_far"] = max_so_far
+
+    for key in ("station_code", "station_label", "series_key", "unit"):
+        value = raw_payload.get(key)
+        if isinstance(value, str) and value.strip():
+            payload[key] = value.strip()
+    if "unit" not in payload:
+        payload["unit"] = "celsius"
+
+    runway_points = _normalize_runway_points(raw_payload.get("runway_points"))
+    if runway_points:
+        payload["runway_points"] = runway_points
+    if isinstance(raw_payload.get("hourly"), dict):
+        payload["hourly"] = raw_payload["hourly"]
+    return payload
+
+
+def _has_observation(payload: Dict[str, Any]) -> bool:
+    return any(
+        key in payload
+        for key in ("temp", "max_so_far", "runway_points", "hourly")
+    )
+
+
+def normalize_observation_patch(patch: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(patch, dict):
+        raise PatchValidationError("patch must be an object")
+
+    if patch.get("type") == EVENT_TYPE:
+        city = _normalize_city(patch.get("city"))
+        source = _normalize_source(patch.get("source"))
+        obs_time = str(patch.get("obs_time") or "").strip() or None
+        payload = _payload_from_v1(patch.get("payload"))
+    else:
+        changes = _legacy_changes(patch)
+        city = _normalize_city(patch.get("city"))
+        source = _normalize_source(changes.get("source") or patch.get("source"))
+        obs_time = str(changes.get("obs_time") or patch.get("obs_time") or "").strip() or None
+        payload = _payload_from_legacy(changes)
+
+    if not city:
+        raise PatchValidationError("city is required")
+    if not _has_observation(payload):
+        raise PatchValidationError("patch must include temperature, max, runway, or hourly data")
+
+    return {
+        "type": EVENT_TYPE,
+        "schema_type": SCHEMA_TYPE,
+        "schema_version": SCHEMA_VERSION,
+        "city": city,
+        "source": source,
+        "obs_time": obs_time,
+        "ts": int(time.time() * 1000),
+        "payload": payload,
+    }