fieldsim 0.2.0__py3-none-any.whl

fieldsim/core/device.py

@@ -0,0 +1,205 @@
+"""Base class shared by every simulated device."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any, Generic, TypeVar
+
+from fieldsim.config import FaultSpec, ScenarioStep
+from fieldsim.core.clock import Clock, RealClock
+from fieldsim.core.datastore import PointStore, Value
+from fieldsim.core.engine import GeneratorEngine
+from fieldsim.core.faults import ActiveFault, FaultInjector, parse_fault
+from fieldsim.core.generators import Generator
+from fieldsim.core.scenario import ScenarioRunner
+
+StoreT = TypeVar("StoreT", bound=PointStore)
+
+
+class Device(ABC, Generic[StoreT]):
+    """A running (or startable) virtual device.
+
+    Subclasses only implement the network side (:meth:`_start_server`,
+    :meth:`_stop_server`, :attr:`host`, :attr:`port`). Values, generators,
+    faults, scenarios and outages are shared by every protocol.
+
+    All methods must be called from the event loop that runs the device. For
+    use from other threads (for example synchronous tests) see
+    :class:`fieldsim.BackgroundSimulator`.
+    """
+
+    protocol: str = ""
+
+    def __init__(
+        self,
+        name: str,
+        store: StoreT,
+        generators: Mapping[str, Generator],
+        *,
+        update_interval: float,
+        faults: Iterable[FaultSpec] = (),
+        scenario: Sequence[ScenarioStep] = (),
+        seed: int | None = None,
+        clock: Clock | None = None,
+    ):
+        self.name = name
+        self.store = store
+        self.clock: Clock = clock or RealClock()
+        self.faults = FaultInjector(seed=seed)
+        for spec in faults:
+            self.add_fault(spec)
+        self._engine = GeneratorEngine(
+            store, generators, interval=update_interval, clock=self.clock
+        )
+        self.scenario = ScenarioRunner(self, scenario, self.clock)
+        self._running = False
+        self._online = False
+
+    # ------------------------------------------------------------------ network
+
+    @property
+    @abstractmethod
+    def host(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def port(self) -> int:
+        """Listening port. After :meth:`start` this is the real port, even if 0 was configured."""
+
+    @property
+    def address(self) -> tuple[str, int]:
+        return self.host, self.port
+
+    @abstractmethod
+    async def _start_server(self) -> None: ...
+
+    @abstractmethod
+    async def _stop_server(self) -> None: ...
+
+    # ------------------------------------------------------------------ lifecycle
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+    @property
+    def online(self) -> bool:
+        """True while the device accepts connections (False during an outage)."""
+        return self._online
+
+    async def start(self) -> None:
+        if self._running:
+            return
+        await self._start_server()
+        self._online = True
+        self._running = True
+        self._engine.start()
+        self.scenario.start()
+
+    async def stop(self) -> None:
+        if not self._running:
+            return
+        self._running = False
+        await self.scenario.stop()
+        await self._engine.stop()
+        if self._online:
+            self._online = False
+            await self._stop_server()
+
+    async def go_offline(self) -> None:
+        """Simulate a power or network loss: drop every client and refuse new ones.
+
+        Values and generators keep running, as they would on a device whose
+        network link went down.
+        """
+        self._require_running()
+        if self._online:
+            self._online = False
+            await self._stop_server()
+
+    async def go_online(self) -> None:
+        """End an outage; the device listens on the same port again."""
+        self._require_running()
+        if not self._online:
+            await self._start_server()
+            self._online = True
+
+    @asynccontextmanager
+    async def offline(self) -> AsyncIterator[None]:
+        """``async with device.offline(): ...`` - outage for the duration of the block."""
+        await self.go_offline()
+        try:
+            yield
+        finally:
+            if self._running:
+                await self.go_online()
+
+    def _require_running(self) -> None:
+        if not self._running:
+            raise RuntimeError(f"device {self.name!r} is not running")
+
+    async def __aenter__(self) -> Device[StoreT]:
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.stop()
+
+    # ------------------------------------------------------------------ faults
+
+    def validate_fault(self, spec: FaultSpec) -> None:
+        """Reject faults that make no sense for this protocol. Overridden by subclasses."""
+
+    def add_fault(self, spec: FaultSpec) -> ActiveFault:
+        self.validate_fault(spec)
+        return self.faults.add(spec)
+
+    def fault(self, fault_type: str, **params: Any) -> ActiveFault:
+        """Activate a fault, e.g. ``device.fault("latency", delay="200ms")``.
+
+        The returned object is a context manager that removes the fault again::
+
+            with device.fault("drop", count=2) as f:
+                ...
+            assert f.hits == 2
+        """
+        return self.add_fault(parse_fault(fault_type, **params))
+
+    def clear_faults(self) -> None:
+        self.faults.clear()
+
+    # ------------------------------------------------------------------ values
+
+    def get(self, name: str) -> Value:
+        """Current value of a point."""
+        return self.store.get(name)
+
+    def set(self, name: str, value: Value) -> None:
+        """Set a point's value.
+
+        If the point is driven by a generator, the generator is paused until
+        :meth:`release` is called, so the value stays exactly as set.
+        """
+        self.store.set(name, value)
+        self._engine.pin(name)
+
+    def release(self, name: str) -> None:
+        """Hand a point set with :meth:`set` back to its generator."""
+        self.store.get(name)  # validates the name
+        self._engine.release(name)
+
+    @property
+    def generated_points(self) -> frozenset[str]:
+        return self._engine.generated
+
+    def __repr__(self) -> str:
+        state = "stopped" if not self._running else "running" if self._online else "offline"
+        return f"<{type(self).__name__} {self.name!r} {self.host}:{self.port} {state}>"

fieldsim/core/engine.py

@@ -0,0 +1,88 @@
+"""Periodically pushes generator output into a point store."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Mapping
+
+from fieldsim.core.clock import Clock, RealClock
+from fieldsim.core.datastore import PointStore
+from fieldsim.core.generators import Generator
+
+logger = logging.getLogger(__name__)
+
+
+class GeneratorEngine:
+    """Runs every generator of a device on a fixed interval.
+
+    A point can be *pinned*: its generator is paused so a value set by a test
+    stays put instead of being overwritten on the next tick.
+    """
+
+    def __init__(
+        self,
+        store: PointStore,
+        generators: Mapping[str, Generator],
+        *,
+        interval: float,
+        clock: Clock | None = None,
+    ):
+        if interval <= 0:
+            raise ValueError("interval must be > 0")
+        self._store = store
+        self._generators = dict(generators)
+        self._interval = interval
+        self._clock: Clock = clock or RealClock()
+        self._pinned: set[str] = set()
+        self._task: asyncio.Task[None] | None = None
+        self._t0 = 0.0
+
+    @property
+    def generated(self) -> frozenset[str]:
+        return frozenset(self._generators)
+
+    @property
+    def pinned(self) -> frozenset[str]:
+        return frozenset(self._pinned)
+
+    @property
+    def running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    def pin(self, name: str) -> None:
+        if name in self._generators:
+            self._pinned.add(name)
+
+    def release(self, name: str) -> None:
+        self._pinned.discard(name)
+
+    def tick(self, elapsed: float) -> None:
+        """Sample every unpinned generator at ``elapsed`` seconds and store the result."""
+        for name, generator in self._generators.items():
+            if name not in self._pinned:
+                self._store.set(name, generator.sample(elapsed), clamp=True)
+
+    def start(self) -> None:
+        if self.running or not self._generators:
+            return
+        self._t0 = self._clock.time()
+        self.tick(0.0)
+        self._task = asyncio.get_running_loop().create_task(self._run(), name="fieldsim-engine")
+
+    async def stop(self) -> None:
+        task, self._task = self._task, None
+        if task is None:
+            return
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
+
+    async def _run(self) -> None:
+        while True:
+            await self._clock.sleep(self._interval)
+            try:
+                self.tick(self._clock.time() - self._t0)
+            except Exception:  # keep the device alive; one bad generator must not stop the rest
+                logger.exception("generator tick failed")

fieldsim/core/faults.py

@@ -0,0 +1,150 @@
+"""Fault injection: decides, per request, how a device should misbehave.
+
+The injector is protocol independent. It produces a :class:`FaultPlan` and the
+protocol server carries it out (how a "corrupt" response looks is a protocol
+detail; *whether* to corrupt is not).
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Iterable
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any
+
+from pydantic import TypeAdapter, ValidationError
+
+from fieldsim.config import (
+    CorruptFault,
+    DisconnectFault,
+    DropFault,
+    ExceptionFault,
+    FaultSpec,
+    LatencyFault,
+)
+
+_FAULT_ADAPTER: TypeAdapter[FaultSpec] = TypeAdapter(FaultSpec)
+
+
+def parse_fault(fault_type: str, **params: Any) -> FaultSpec:
+    """Build a validated fault spec, e.g. ``parse_fault("latency", delay="200ms")``."""
+    try:
+        return _FAULT_ADAPTER.validate_python({"type": fault_type, **params})
+    except ValidationError as exc:
+        details = "; ".join(
+            f"{'.'.join(str(p) for p in e['loc'][1:]) or 'type'}: {e['msg']}"
+            for e in exc.errors(include_url=False)
+        )
+        raise ValueError(f"invalid {fault_type!r} fault: {details}") from None
+
+
+@dataclass
+class FaultPlan:
+    """What to do with one request."""
+
+    delay: float = 0.0
+    drop: bool = False
+    execute: bool = True
+    disconnect: bool = False
+    exception: int | None = None
+    corrupt: str | None = None
+
+    @property
+    def clean(self) -> bool:
+        return self == FaultPlan()
+
+
+class ActiveFault:
+    """A fault currently attached to a device.
+
+    Usable as a context manager (``with device.fault("drop"): ...``) and keeps
+    count of how many requests it affected.
+    """
+
+    def __init__(self, injector: FaultInjector, spec: FaultSpec):
+        self.spec = spec
+        self.hits = 0
+        self._injector = injector
+
+    @property
+    def kind(self) -> str:
+        """Fault type, e.g. ``"latency"``."""
+        return self.spec.type
+
+    @property
+    def active(self) -> bool:
+        return self in self._injector.active
+
+    def remove(self) -> None:
+        self._injector.remove(self)
+
+    def __enter__(self) -> ActiveFault:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.remove()
+
+    def __repr__(self) -> str:
+        return f"<ActiveFault {self.spec.type} hits={self.hits} active={self.active}>"
+
+
+class FaultInjector:
+    def __init__(self, specs: Iterable[FaultSpec] = (), *, seed: int | None = None):
+        self.rng = random.Random(seed)
+        self._faults: list[ActiveFault] = []
+        for spec in specs:
+            self.add(spec)
+
+    @property
+    def active(self) -> list[ActiveFault]:
+        return list(self._faults)
+
+    def add(self, spec: FaultSpec) -> ActiveFault:
+        fault = ActiveFault(self, spec)
+        self._faults.append(fault)
+        return fault
+
+    def remove(self, fault: ActiveFault) -> None:
+        if fault in self._faults:
+            self._faults.remove(fault)
+
+    def clear(self) -> None:
+        self._faults.clear()
+
+    def plan(self, function_code: int | None = None) -> FaultPlan:
+        """Roll the dice for one request and combine every fault that applies."""
+        plan = FaultPlan()
+        for fault in list(self._faults):
+            spec = fault.spec
+            if (
+                spec.function_codes is not None
+                and function_code is not None
+                and function_code not in spec.function_codes
+            ):
+                continue
+            if spec.probability < 1 and self.rng.random() >= spec.probability:
+                continue
+            fault.hits += 1
+            if spec.count is not None and fault.hits >= spec.count:
+                self.remove(fault)
+            self._apply(spec, plan)
+        return plan
+
+    def _apply(self, spec: FaultSpec, plan: FaultPlan) -> None:
+        if isinstance(spec, LatencyFault):
+            plan.delay += spec.delay + (self.rng.uniform(0, spec.jitter) if spec.jitter else 0.0)
+        elif isinstance(spec, DropFault):
+            plan.drop = True
+            plan.execute = plan.execute and spec.executed
+        elif isinstance(spec, DisconnectFault):
+            plan.disconnect = True
+        elif isinstance(spec, ExceptionFault):
+            plan.exception = spec.code
+        elif isinstance(spec, CorruptFault):
+            plan.corrupt = spec.mode

fieldsim/core/generators.py

@@ -0,0 +1,109 @@
+"""Value generators: functions of elapsed time that drive simulated points."""
+
+from __future__ import annotations
+
+import math
+import random
+from abc import ABC, abstractmethod
+
+from fieldsim.config import (
+    ConstantGenerator,
+    GeneratorSpec,
+    RampGenerator,
+    RandomWalkGenerator,
+    SequenceGenerator,
+    SineGenerator,
+)
+
+
+class Generator(ABC):
+    """Produces a value for a point given the seconds elapsed since the device started."""
+
+    @abstractmethod
+    def sample(self, t: float) -> float: ...
+
+
+class Constant(Generator):
+    def __init__(self, value: float):
+        self.value = value
+
+    def sample(self, t: float) -> float:
+        return self.value
+
+
+class Sine(Generator):
+    def __init__(self, minimum: float, maximum: float, period: float, phase: float = 0.0):
+        if period <= 0:
+            raise ValueError("period must be > 0")
+        self.minimum, self.maximum, self.period, self.phase = minimum, maximum, period, phase
+
+    def sample(self, t: float) -> float:
+        amplitude = (self.maximum - self.minimum) / 2
+        angle = 2 * math.pi * (t + self.phase) / self.period
+        return self.minimum + amplitude * (1 + math.sin(angle))
+
+
+class Ramp(Generator):
+    def __init__(self, start: float, end: float, period: float, mode: str = "sawtooth"):
+        if period <= 0:
+            raise ValueError("period must be > 0")
+        if mode not in ("sawtooth", "triangle", "once"):
+            raise ValueError(f"unknown ramp mode {mode!r}")
+        self.start, self.end, self.period, self.mode = start, end, period, mode
+
+    def sample(self, t: float) -> float:
+        if self.mode == "once":
+            fraction = min(max(t / self.period, 0.0), 1.0)
+        else:
+            fraction = (t % self.period) / self.period
+            if self.mode == "triangle":
+                fraction = 2 * fraction if fraction < 0.5 else 2 - 2 * fraction
+        return self.start + (self.end - self.start) * fraction
+
+
+class RandomWalk(Generator):
+    """Stateful: each call to :meth:`sample` takes one step, regardless of ``t``."""
+
+    def __init__(
+        self, start: float, step: float, minimum: float, maximum: float, seed: int | None = None
+    ):
+        self.value = start
+        self.step, self.minimum, self.maximum = step, minimum, maximum
+        self._rng = random.Random(seed)
+        self._started = False
+
+    def sample(self, t: float) -> float:
+        if self._started:
+            self.value += self._rng.uniform(-self.step, self.step)
+            self.value = min(max(self.value, self.minimum), self.maximum)
+        self._started = True
+        return self.value
+
+
+class Sequence(Generator):
+    def __init__(self, values: list[float], interval: float, repeat: bool = True):
+        if not values:
+            raise ValueError("values must not be empty")
+        if interval <= 0:
+            raise ValueError("interval must be > 0")
+        self.values, self.interval, self.repeat = list(values), interval, repeat
+
+    def sample(self, t: float) -> float:
+        index = max(int(t // self.interval), 0)
+        index = index % len(self.values) if self.repeat else min(index, len(self.values) - 1)
+        return self.values[index]
+
+
+def build_generator(spec: GeneratorSpec) -> Generator:
+    """Create a generator from its configuration model."""
+    if isinstance(spec, ConstantGenerator):
+        return Constant(spec.value)
+    if isinstance(spec, SineGenerator):
+        return Sine(spec.min, spec.max, spec.period, spec.phase)
+    if isinstance(spec, RampGenerator):
+        return Ramp(spec.start, spec.end, spec.period, spec.mode)
+    if isinstance(spec, RandomWalkGenerator):
+        return RandomWalk(spec.start, spec.step, spec.min, spec.max, spec.seed)
+    if isinstance(spec, SequenceGenerator):
+        return Sequence(spec.values, spec.interval, spec.repeat)
+    raise TypeError(f"unsupported generator spec: {type(spec).__name__}")  # pragma: no cover

fieldsim/core/scenario.py

@@ -0,0 +1,140 @@
+"""Plays a device's scenario: a timeline of value changes, faults and outages."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from fieldsim.config import FaultSpec, ScenarioStep
+from fieldsim.core.clock import Clock
+from fieldsim.core.datastore import Value
+from fieldsim.core.faults import ActiveFault
+
+logger = logging.getLogger(__name__)
+
+
+class ScenarioTarget(Protocol):
+    def set(self, name: str, value: Value) -> None: ...
+
+    def release(self, name: str) -> None: ...
+
+    def add_fault(self, spec: FaultSpec) -> ActiveFault: ...
+
+    async def go_offline(self) -> None: ...
+
+    async def go_online(self) -> None: ...
+
+
+Action = Callable[[], Awaitable[None] | None]
+
+
+@dataclass(frozen=True)
+class ScenarioEvent:
+    time: float
+    description: str
+    action: Action
+
+
+def build_events(target: ScenarioTarget, steps: Sequence[ScenarioStep]) -> list[ScenarioEvent]:
+    """Expand steps into a sorted list of instantaneous events.
+
+    A step with a duration becomes two events (start and end). Events at the
+    same time keep the order in which they were written.
+    """
+    events: list[tuple[float, int, ScenarioEvent]] = []
+
+    def add(time: float, description: str, action: Action) -> None:
+        events.append((time, len(events), ScenarioEvent(time, description, action)))
+
+    for step in steps:
+        if step.set is not None:
+            values = dict(step.set)
+
+            def do_set(values: dict[str, Value] = values) -> None:
+                for name, value in values.items():
+                    target.set(name, value)
+
+            add(step.at, f"set {values}", do_set)
+        elif step.release is not None:
+            names = list(step.release)
+
+            def do_release(names: list[str] = names) -> None:
+                for name in names:
+                    target.release(name)
+
+            add(step.at, f"release {', '.join(names)}", do_release)
+        elif step.fault is not None:
+            holder: list[ActiveFault] = []
+            spec = step.fault
+
+            def do_fault(spec: FaultSpec = spec, holder: list[ActiveFault] = holder) -> None:
+                holder.append(target.add_fault(spec))
+
+            add(step.at, f"fault {spec.type} on", do_fault)
+            if step.duration is not None:
+
+                def undo_fault(holder: list[ActiveFault] = holder) -> None:
+                    for fault in holder:
+                        fault.remove()
+
+                add(step.at + step.duration, f"fault {spec.type} off", undo_fault)
+        elif step.offline is not None:
+            add(step.at, "offline", target.go_offline)
+            add(step.at + step.offline, "online", target.go_online)
+
+    return [event for *_, event in sorted(events, key=lambda e: (e[0], e[1]))]
+
+
+class ScenarioRunner:
+    def __init__(self, target: ScenarioTarget, steps: Sequence[ScenarioStep], clock: Clock):
+        self.events = build_events(target, steps)
+        self.history: list[ScenarioEvent] = []
+        self._clock = clock
+        self._task: asyncio.Task[None] | None = None
+        self._t0 = 0.0
+
+    @property
+    def done(self) -> bool:
+        return len(self.history) == len(self.events)
+
+    @property
+    def elapsed(self) -> float:
+        return self._clock.time() - self._t0
+
+    def start(self) -> None:
+        if self._task is not None or not self.events:
+            return
+        self._t0 = self._clock.time()
+        self._task = asyncio.get_running_loop().create_task(self._run(), name="fieldsim-scenario")
+
+    async def stop(self) -> None:
+        task, self._task = self._task, None
+        if task is None:
+            return
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
+
+    async def wait(self) -> None:
+        """Wait until every event has run (returns at once if there are none)."""
+        if self._task is not None:
+            await asyncio.shield(self._task)
+
+    async def _run(self) -> None:
+        for event in self.events:
+            delay = self._t0 + event.time - self._clock.time()
+            if delay > 0:
+                await self._clock.sleep(delay)
+            logger.info("scenario t=%.3fs: %s", event.time, event.description)
+            try:
+                result = event.action()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                logger.exception("scenario action failed: %s", event.description)
+            self.history.append(event)