sprint-4: Runtime server base — tag_store + historian + alarm engine + API FastAPI
Arquitectura asincronica completa para correr 24/7 a bordo del buque.
vmssailor/runtime/server/tag_store.py
- TagStore in-memory con pub/sub asyncio.Queue
- register_tag/register_many con valores iniciales
- TagValue dataclass: value + quality + timestamp + raw_value
- subscribe()/unsubscribe() para fan-out
- stats() con breakdown por Quality
vmssailor/runtime/server/historian.py
- Historian DuckDB embebido (in-memory o archivo)
- Reader loop suscrito al tag_store + buffer + flush periodico (1s)
- query(tag_id, since, until, limit) para series temporales
- Soporta valores numericos y boolean separadamente
vmssailor/runtime/server/alarm_engine.py
- Suscriptor al tag_store que evalua AlarmConfig por update
- Operators: >, >=, <, <=, ==, !=
- Hysteresis correcta: aplica al SALIR de alarma, no a entrar
- Delay configurable (persistencia minima antes de disparar)
- Estados: ACTIVE -> ACK (con user) -> CLEARED
- ack(alarm_id, user) reconoce sin clear
vmssailor/runtime/server/drivers.py
- SimulatorDriver: produce valores sinteticos creibles por UnitSI
- Tick configurable (default 0.5s)
- Respeta range_normal_min/max del tag para mantenerse en rango
- Permite probar UI/API sin hardware ni Modbus real
vmssailor/runtime/server/runtime_app.py
- RuntimeApp dataclass ensambla todos los servicios
- build_runtime(project) construye listo para correr
- start()/stop() async lifecycle ordenado
vmssailor/runtime/server/api.py
- FastAPI app con lifespan que arranca/detiene el runtime
- GET /health, /project
- GET /tags, /tags/{id}, /tags/{id}/history
- GET /alarms, POST /alarms/{id}/ack
- WebSocket /ws/realtime con snapshot inicial + push + heartbeat
runtime_server_main.py
- Entry point con argparse: --vmsproj, --host, --port, --db
- Sin --vmsproj usa proyecto demo Sprint 0 (genera simulator vivo)
- Lanza con uvicorn
Tests (tests/runtime/, 16 nuevos, total 142/142):
- test_tag_store: register, update, subscribe, unsubscribe, stats
- test_historian: roundtrip query, stats
- test_alarm_engine: fire when below, hysteresis clears, ack
- test_api: health, project, tags listing, history, alarms via httpx.ASGITransport
Para correr el servidor en vivo:
uv run python runtime_server_main.py --verbose
Luego en otro shell:
curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/tags | jq .
Dependencias agregadas:
- fastapi >=0.110
- uvicorn[standard] >=0.27
- websockets >=12.0
- duckdb >=0.10
- pymodbus >=3.5 (Sprint 5)
- python-can >=4.3 (Sprint 5)
- httpx >=0.27 (testing + cliente HTTP)
142/142 pytest verde, ruff clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
"""Tests del Alarm Engine (Sprint 4)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
import pytest
|
||||
|
||||
from vmssailor.core.alarm import Alarm
|
||||
from vmssailor.core.enums import AlarmPriority, AlarmState, Protocol, UnitSI
|
||||
from vmssailor.core.tag import AlarmConfig, Tag
|
||||
from vmssailor.runtime.server.alarm_engine import AlarmEngine
|
||||
from vmssailor.runtime.server.tag_store import TagStore
|
||||
|
||||
|
||||
def _tag_with_alarm(low_threshold: float = 1.5, delay_s: float = 0.0) -> Tag:
|
||||
return Tag(
|
||||
id="X.PRESS",
|
||||
unit_si=UnitSI.BAR,
|
||||
protocol=Protocol.MODBUS_RTU,
|
||||
address=1,
|
||||
alarms=[
|
||||
AlarmConfig(
|
||||
id="X.PRESS.LOW",
|
||||
threshold=low_threshold,
|
||||
operator="<",
|
||||
priority=AlarmPriority.EMERGENCY,
|
||||
hysteresis=0.2,
|
||||
delay_seconds=delay_s,
|
||||
)
|
||||
],
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_alarm_fires_when_below_threshold():
|
||||
store = TagStore()
|
||||
store.register_tag(_tag_with_alarm(low_threshold=1.5))
|
||||
events: list[Alarm] = []
|
||||
engine = AlarmEngine(store, on_alarm_event=events.append)
|
||||
await engine.start()
|
||||
try:
|
||||
await store.update("X.PRESS", 1.0) # debajo del threshold
|
||||
await asyncio.sleep(0.05)
|
||||
assert len(events) == 1
|
||||
assert events[0].state == AlarmState.ACTIVE
|
||||
assert events[0].priority == AlarmPriority.EMERGENCY
|
||||
finally:
|
||||
await engine.stop()
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_alarm_clears_with_hysteresis():
|
||||
store = TagStore()
|
||||
store.register_tag(_tag_with_alarm(low_threshold=1.5))
|
||||
events: list[Alarm] = []
|
||||
engine = AlarmEngine(store, on_alarm_event=events.append)
|
||||
await engine.start()
|
||||
try:
|
||||
await store.update("X.PRESS", 1.0)
|
||||
await asyncio.sleep(0.05)
|
||||
# Subiendo a 1.6 NO debería limpiar (dentro de la hysteresis +0.2 = 1.7)
|
||||
await store.update("X.PRESS", 1.6)
|
||||
await asyncio.sleep(0.05)
|
||||
# Subiendo a 2.0 SÍ limpia
|
||||
await store.update("X.PRESS", 2.0)
|
||||
await asyncio.sleep(0.05)
|
||||
states = [e.state for e in events]
|
||||
assert AlarmState.ACTIVE in states
|
||||
assert AlarmState.CLEARED in states
|
||||
finally:
|
||||
await engine.stop()
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_alarm_ack():
|
||||
store = TagStore()
|
||||
store.register_tag(_tag_with_alarm(low_threshold=1.5))
|
||||
events: list[Alarm] = []
|
||||
engine = AlarmEngine(store, on_alarm_event=events.append)
|
||||
await engine.start()
|
||||
try:
|
||||
await store.update("X.PRESS", 1.0)
|
||||
await asyncio.sleep(0.05)
|
||||
active = engine.active_alarms()
|
||||
assert len(active) == 1
|
||||
ack = engine.ack(active[0].id, user="operator1")
|
||||
assert ack is not None
|
||||
assert ack.state == AlarmState.ACK
|
||||
assert ack.acknowledged_by == "operator1"
|
||||
finally:
|
||||
await engine.stop()
|
||||
@@ -0,0 +1,92 @@
|
||||
"""Tests de la API FastAPI del Runtime (Sprint 4)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from vmssailor.runtime.server.api import create_app
|
||||
from vmssailor.runtime.server.runtime_app import build_runtime
|
||||
from vmssailor.tools.generate_test_project import build_demo_project
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
async def runtime_client():
|
||||
project = build_demo_project()
|
||||
runtime = build_runtime(project, simulator_tick_s=0.2)
|
||||
app = create_app(runtime)
|
||||
transport = httpx.ASGITransport(app=app)
|
||||
async with (
|
||||
httpx.AsyncClient(transport=transport, base_url="http://test") as client,
|
||||
app.router.lifespan_context(app),
|
||||
):
|
||||
# Dar un tick para que el simulator produzca al menos un valor
|
||||
await asyncio.sleep(0.4)
|
||||
yield client, runtime
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_health_endpoint(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
r = await client.get("/health")
|
||||
assert r.status_code == 200
|
||||
body = r.json()
|
||||
assert body["status"] == "ok"
|
||||
assert "tag_store" in body
|
||||
assert body["tag_store"]["total_tags"] > 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_project_endpoint(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
r = await client.get("/project")
|
||||
assert r.status_code == 200
|
||||
body = r.json()
|
||||
assert body["name"]
|
||||
assert body["vessel"]["loa_m"] > 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_tags_listing_and_simulator_values(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
r = await client.get("/tags")
|
||||
assert r.status_code == 200
|
||||
tags = r.json()
|
||||
assert len(tags) > 0
|
||||
# Al menos alguno debería tener value no nulo después del tick
|
||||
with_value = [t for t in tags if t["value"] is not None]
|
||||
assert len(with_value) > 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_tag_detail_404(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
r = await client.get("/tags/ghost.tag")
|
||||
assert r.status_code == 404
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_history_endpoint(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
# Le damos al simulator más tiempo para que el historian acumule
|
||||
await asyncio.sleep(1.2)
|
||||
# Tomamos un tag con valor numérico
|
||||
list_r = await client.get("/tags")
|
||||
tag_id = next(
|
||||
t["id"] for t in list_r.json() if isinstance(t["value"], (int, float))
|
||||
)
|
||||
r = await client.get(f"/tags/{tag_id}/history")
|
||||
assert r.status_code == 200
|
||||
rows = r.json()
|
||||
# En 1.2s con simulator de 0.2s -> ~6 muestras
|
||||
assert len(rows) >= 3
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_alarms_endpoint(runtime_client):
|
||||
client, _runtime = runtime_client
|
||||
r = await client.get("/alarms")
|
||||
assert r.status_code == 200
|
||||
assert isinstance(r.json(), list)
|
||||
@@ -0,0 +1,56 @@
|
||||
"""Tests del Historian DuckDB (Sprint 4)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
from datetime import UTC, datetime, timedelta
|
||||
|
||||
import pytest
|
||||
|
||||
from vmssailor.core.enums import Protocol, UnitSI
|
||||
from vmssailor.core.tag import Tag
|
||||
from vmssailor.runtime.server.historian import Historian
|
||||
from vmssailor.runtime.server.tag_store import TagStore
|
||||
|
||||
|
||||
def _tag(tag_id: str) -> Tag:
|
||||
return Tag(id=tag_id, unit_si=UnitSI.BAR, protocol=Protocol.MODBUS_RTU, address=1)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_historian_records_updates():
|
||||
store = TagStore()
|
||||
store.register_tag(_tag("X"))
|
||||
h = Historian() # in-memory
|
||||
await h.start(store)
|
||||
try:
|
||||
for v in (4.0, 4.1, 4.2):
|
||||
await store.update("X", v)
|
||||
# Force flush
|
||||
await asyncio.sleep(0.05)
|
||||
await h._flush(force=True)
|
||||
rows = h.query(
|
||||
"X",
|
||||
since=datetime.now(UTC) - timedelta(minutes=1),
|
||||
)
|
||||
assert len(rows) == 3
|
||||
values = [r["value"] for r in rows]
|
||||
assert values == [4.0, 4.1, 4.2]
|
||||
finally:
|
||||
await h.stop()
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_historian_stats():
|
||||
store = TagStore()
|
||||
store.register_tag(_tag("X"))
|
||||
h = Historian()
|
||||
await h.start(store)
|
||||
try:
|
||||
await store.update("X", 1.0)
|
||||
await asyncio.sleep(0.05)
|
||||
await h._flush(force=True)
|
||||
stats = h.stats()
|
||||
assert stats["total_samples"] >= 1
|
||||
finally:
|
||||
await h.stop()
|
||||
@@ -0,0 +1,64 @@
|
||||
"""Tests del TagStore (Sprint 4)."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
import pytest
|
||||
|
||||
from vmssailor.core.enums import Protocol, Quality, UnitSI
|
||||
from vmssailor.core.tag import Tag
|
||||
from vmssailor.runtime.server.tag_store import TagStore
|
||||
|
||||
|
||||
def _make_tag(tag_id: str) -> Tag:
|
||||
return Tag(id=tag_id, unit_si=UnitSI.BAR, protocol=Protocol.MODBUS_RTU, address=1)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_register_and_get():
|
||||
store = TagStore()
|
||||
t = _make_tag("ME_PORT.OIL_PRESS")
|
||||
store.register_tag(t, initial_value=4.5)
|
||||
tv = store.get("ME_PORT.OIL_PRESS")
|
||||
assert tv is not None
|
||||
assert tv.value == 4.5
|
||||
assert tv.quality == Quality.GOOD
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_update_notifies_subscribers():
|
||||
store = TagStore()
|
||||
store.register_tag(_make_tag("X"))
|
||||
q = store.subscribe()
|
||||
await store.update("X", 5.0)
|
||||
tv = await asyncio.wait_for(q.get(), timeout=1.0)
|
||||
assert tv.tag_id == "X"
|
||||
assert tv.value == 5.0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_unsubscribe():
|
||||
store = TagStore()
|
||||
store.register_tag(_make_tag("X"))
|
||||
q = store.subscribe()
|
||||
store.unsubscribe(q)
|
||||
await store.update("X", 5.0)
|
||||
# No debe haber elementos pendientes
|
||||
assert q.qsize() == 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_update_unknown_raises():
|
||||
store = TagStore()
|
||||
with pytest.raises(KeyError):
|
||||
await store.update("GHOST", 1.0)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_stats():
|
||||
store = TagStore()
|
||||
store.register_many([_make_tag("A"), _make_tag("B")])
|
||||
s = store.stats()
|
||||
assert s["total_tags"] == 2
|
||||
assert s["subscribers"] == 0
|
||||
Reference in New Issue
Block a user