Source code for pyModbusTCP.server.wrappers

""" pyModbusTCP server: store wrappers, access rules stacked on a data store.

A wrapper is a data store that checks each access of a client request, then passes it to the store it wraps::

    store = AccessControl(ReadOnly(MemoryStore(), spaces=[Space.COILS]), write_hosts=['192.168.1.20'])

The rules only apply to the client requests: the application (store.app, transactions without context) always has a
full access. A refused access raises a ModbusException (the client gets the exception response).
"""

from __future__ import annotations

from collections.abc import Callable, Generator, Iterable
from contextlib import contextmanager
from typing import Any, Literal

from . import _validators
from ._common import client_ip
from .errors import IllegalDataAddress, IllegalFunction
from .store import AppAccess, DataStore, Listener, RequestContext, Space, Transaction

# the kind of access checked by a wrapper
Access = Literal['read', 'write']


class _CheckedTransaction(Transaction):
    """A transaction that asks the wrapper before each access."""

    def __init__(self, wrapper: StoreWrapper, tx: Transaction, ctx: RequestContext) -> None:
        # ctx (public, of Transaction) is "RequestContext | None"; _ctx keeps the type of a client request (never
        # None here) for check(), without a narrowed override of ctx (a mutable attribute)
        self.ctx = ctx
        self._ctx = ctx
        self._wrapper = wrapper
        self._tx = tx

    def read(self, space: Space, address: int, count: int = 1) -> list[Any]:
        self._wrapper.check(self._ctx, 'read', space, address, count)
        return self._tx.read(space, address, count)

    def write(self, space: Space, address: int, values: Iterable[Any]) -> None:
        values = list(values)
        self._wrapper.check(self._ctx, 'write', space, address, len(values))
        self._tx.write(space, address, values)


[docs] class StoreWrapper(DataStore): """Base class of the wrappers: override check() to refuse some accesses of the clients. The other attributes of the wrapped store (like MemoryStore.map()) are available on the wrapper. """ def __init__(self, store: DataStore) -> None: if not isinstance(store, DataStore): raise TypeError('store must be a DataStore') self.store = store def __repr__(self) -> str: return f'{type(self).__name__}({self.store!r})' def __getattr__(self, name: str) -> Any: # only called for a missing attribute: the extras of the wrapped store (map(), size()...) if name == 'store': raise AttributeError(name) return getattr(self.store, name)
[docs] def check(self, ctx: RequestContext, access: Access, space: Space, address: int, count: int) -> None: """Check an access of a client request: raise a ModbusException to refuse it (default: allowed)."""
@contextmanager def transaction(self, ctx: RequestContext | None = None) -> Generator[Transaction, None, None]: with self.store.transaction(ctx) as tx: yield tx if ctx is None else _CheckedTransaction(self, tx, ctx) def subscribe(self, listener: Listener, app_writes: bool = False, threaded: bool = False) -> Callable[[], None]: return self.store.subscribe(listener, app_writes, threaded) @property def app(self) -> AppAccess: return self.store.app
[docs] class ReadOnly(StoreWrapper): """Refuse the client writes ("illegal function" exception), in every space or in some of them.""" def __init__(self, store: DataStore, spaces: Iterable[Space] | None = None) -> None: """ :param store: the wrapped store :param spaces: the read-only spaces (default: every space) """ super().__init__(store) self.spaces = frozenset(Space) if spaces is None else frozenset(spaces) def check(self, ctx: RequestContext, access: Access, space: Space, address: int, count: int) -> None: if access == 'write' and space in self.spaces: raise IllegalFunction(f'{space.value} are read-only')
[docs] class AccessControl(StoreWrapper): """Allow the reads and the writes only to some client addresses or networks ("illegal function" exception). This filters on the source IP address, it's not an authentication. """ def __init__(self, store: DataStore, read_hosts: Iterable[str] | None = None, write_hosts: Iterable[str] | None = None) -> None: """ :param store: the wrapped store :param read_hosts: IP addresses or networks allowed to read (like ['192.168.1.0/24']), None for every client, an empty list for no client :param write_hosts: IP addresses or networks allowed to write, None for every client, an empty list for no client """ super().__init__(store) self._read_networks = _validators.validate_allowed_hosts(read_hosts, 'read_hosts') self._write_networks = _validators.validate_allowed_hosts(write_hosts, 'write_hosts') def check(self, ctx: RequestContext, access: Access, space: Space, address: int, count: int) -> None: networks = self._read_networks if access == 'read' else self._write_networks if networks is None: return ip = client_ip((ctx.client.address, ctx.client.port)) if ip is None or not any(ip in network for network in networks): raise IllegalFunction(f'{access} not allowed for {ctx.client.address}')
[docs] class Guard(StoreWrapper): """Check each client access with a function: check(ctx, access, space, address, count). The function returns True to allow the access, False to refuse it ("illegal data address" exception), or raises a ModbusException for another exception code. """ def __init__(self, store: DataStore, check: Callable[[RequestContext, Access, Space, int, int], bool]) -> None: super().__init__(store) self._check = check def check(self, ctx: RequestContext, access: Access, space: Space, address: int, count: int) -> None: allowed = self._check(ctx, access, space, address, count) if allowed is True: return raise IllegalDataAddress(f'{access} of {space.value} @{address} refused')