mirror of
https://github.com/zvx-echo6/central.git
synced 2026-05-21 18:14:44 +02:00
ead6ef8ce1
Adds an optional async hook on SourceAdapter so any adapter can surface a
settings-driven preview on its /adapters/<name> edit page. The framework
renders the result generically as a table — no adapter-name branches in
GUI templates or route code.
Framework changes:
- src/central/adapter.py: new async preview_for_settings(self, settings)
on the base class, default returns None. Adapters opt in by overriding;
non-overriding adapters render unchanged.
- src/central/gui/routes.py: GET /adapters/{name} instantiates the adapter
with a no-op _PreviewConfigStore stub and a /dev/null cursor path (GUI
has no live ConfigStore), constructs settings_obj via the schema, and
calls preview_for_settings inside a try/except. Result lands in template
context as preview_rows / preview_error.
- src/central/gui/templates/_adapter_preview.html: new partial. Generic
table with columns derived from the first dict's keys; error banner
mirrors the existing last_error article style.
- src/central/gui/templates/adapters_edit.html: one-line include between
the Region fieldset and Save/Cancel.
NWIS opt-in:
- New NWIS_MONITORING_LOCATIONS_URL constant and _PREVIEW_LIMIT cap of 50.
- preview_for_settings returns None when region is None, otherwise one-shot
fetches monitoring-locations within the bbox via a fresh aiohttp session.
Must work even when adapter is not started -- the GUI process never calls
startup(). Returns list[dict] with the contract column order: site_id,
name, site_type, state. Errors propagate so the framework can render the
operator-visible banner.
- HTTP call factored into _fetch_preview_text so tests mock cleanly.
Tests (7 new):
- tests/test_preview_hook.py: default returns None; partial renders list
with correct headers/rows/count; partial renders error banner; partial
renders empty when both context values are None.
- tests/test_nwis.py adds TestNWISPreview: returns None without region,
returns rows with correct column order, propagates HTTP errors.
Verification:
- 457/457 full suite green (was 450; +7 new tests).
- Live /adapters/nwis preview returns 50 rows with the contract keys
against the current production Iowa bbox.
- /adapters/eonet preview_for_settings returns None via base default --
proves framework is duck-typed, no NWIS-specific code in framework.
89 lines
3 KiB
Python
89 lines
3 KiB
Python
"""Base adapter interface for event sources."""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from collections.abc import AsyncIterator
|
|
from typing import TYPE_CHECKING
|
|
|
|
from pydantic import BaseModel
|
|
|
|
if TYPE_CHECKING:
|
|
from central.config_models import AdapterConfig
|
|
|
|
from central.models import Event
|
|
|
|
|
|
class SourceAdapter(ABC):
|
|
"""
|
|
Abstract base class for event source adapters.
|
|
|
|
Adapters yield Events. The supervisor handles scheduling,
|
|
CloudEvents wrapping, publish, and metadata heartbeats.
|
|
|
|
Class attributes that subclasses must define:
|
|
name: Short identifier, e.g. "nws"
|
|
display_name: Human-readable name for GUI
|
|
description: Short description of the adapter
|
|
settings_schema: Pydantic model class for adapter settings
|
|
requires_api_key: Key alias if API key required, else None
|
|
wizard_order: Order in setup wizard (None = not in wizard)
|
|
default_cadence_s: Default polling interval in seconds
|
|
"""
|
|
|
|
name: str
|
|
display_name: str
|
|
description: str
|
|
settings_schema: type[BaseModel]
|
|
requires_api_key: str | None = None
|
|
api_key_field: str | None = None
|
|
"""Names the settings_schema field that holds an api_key alias reference, if any.
|
|
The GUI renders this field as a select populated from config.api_keys;
|
|
the wizard validates it against staged api_keys state."""
|
|
wizard_order: int | None = None
|
|
default_cadence_s: int
|
|
|
|
@abstractmethod
|
|
async def poll(self) -> AsyncIterator[Event]:
|
|
"""
|
|
Poll the source for new events.
|
|
|
|
Yields Event objects for each new/updated event found.
|
|
"""
|
|
...
|
|
|
|
@abstractmethod
|
|
async def apply_config(self, new_config: "AdapterConfig") -> None:
|
|
"""
|
|
Apply new configuration to the adapter.
|
|
|
|
Called by supervisor when config changes via hot-reload.
|
|
The adapter should extract relevant settings from
|
|
new_config.settings and update its internal state.
|
|
"""
|
|
...
|
|
|
|
@abstractmethod
|
|
def subject_for(self, event: Event) -> str:
|
|
"""
|
|
Compute the NATS subject for an event.
|
|
|
|
Each adapter knows its own subject hierarchy. The supervisor
|
|
calls this to determine where to publish each event.
|
|
"""
|
|
...
|
|
|
|
async def startup(self) -> None:
|
|
"""Optional lifecycle hook called before first poll."""
|
|
pass
|
|
|
|
async def shutdown(self) -> None:
|
|
"""Optional lifecycle hook called on graceful shutdown."""
|
|
pass
|
|
|
|
async def preview_for_settings(self, settings: BaseModel) -> list[dict] | None:
|
|
"""Optional. Override to surface a settings-driven preview on the edit page.
|
|
|
|
Return list[dict] (framework renders as a generic table; columns come from
|
|
the first dict's keys, in insertion order). Return None to skip preview.
|
|
Raise to surface an error banner — framework catches at the route boundary.
|
|
"""
|
|
return None
|