mercury-proxy 2.0.0__py3-none-any.whl

mercury_proxy/__init__.py

@@ -0,0 +1,51 @@
+"""
+Прокси-сервер и REST API для счётчиков Инкотекс Меркурий.
+
+Сервис подключает счётчики по последовательной шине или TCP, ждёт клиента,
+говорящего на протоколе счётчика (обычно Конфигуратор), и пересылает его кадры
+счётчику, которому они адресованы. REST API отдаёт команды ``mercury_base``
+интеграциям вроде Home Assistant.
+
+Конфигурация и цикл работы принадлежат `Service`; консольный скрипт пакета
+собирает его из YAML-файла и останавливает по SIGINT или SIGTERM.
+
+Copyright (c) 2023–2026 webtoucher
+Distributed under the BSD 3-Clause license. See LICENSE.md for more info.
+"""
+
+__version__ = "2.0.0"
+
+from mercury_proxy.api import RestApi
+from mercury_proxy.config import (
+    ApiConfig,
+    Config,
+    LoggingConfig,
+    MeterConfig,
+    ProxyConfig,
+    ServiceConfig,
+    load_config,
+)
+from mercury_proxy.exceptions import ConfigError, ProxyError, UnknownMeterError
+from mercury_proxy.log import configure_logging
+from mercury_proxy.meters import MeterHub
+from mercury_proxy.proxy import SocketProxy
+from mercury_proxy.service import Service
+
+__all__ = [
+    "Config",
+    "MeterConfig",
+    "ProxyConfig",
+    "ApiConfig",
+    "LoggingConfig",
+    "ServiceConfig",
+    "load_config",
+    "configure_logging",
+    "ConfigError",
+    "ProxyError",
+    "UnknownMeterError",
+    "MeterHub",
+    "SocketProxy",
+    "RestApi",
+    "Service",
+    "__version__",
+]

mercury_proxy/__main__.py

@@ -0,0 +1,91 @@
+"""
+Точка входа командной строки: ``python -m mercury_proxy`` или ``mercury-proxy``.
+
+Она загружает конфигурацию, открывает файл лога и работает до прихода SIGINT
+или SIGTERM. Конфигурация, которую не удалось прочитать или понять, сообщается
+в stderr и завершает процесс с кодом 2, чтобы systemd и другие супервизоры
+не перезапускали сервис, который не может стартовать. Флаг ``--print-unit``
+печатает готовый юнит systemd для этой установки и выходит.
+
+Copyright (c) 2023–2026 webtoucher
+Distributed under the BSD 3-Clause license. See LICENSE.md for more info.
+"""
+
+import argparse
+import signal
+import sys
+
+from typing import Any, Optional, Sequence
+
+from mercury_proxy.config import DEFAULT_CONFIG_PATH, load_config
+from mercury_proxy.exceptions import ConfigError, ProxyError
+from mercury_proxy.log import configure_logging
+from mercury_proxy.service import Service
+from mercury_proxy.systemd import render_unit
+
+__all__ = ["main"]
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Запустить сервис из командной строки; возвращает код возврата."""
+    parser = argparse.ArgumentParser(
+        prog="mercury-proxy",
+        description="Proxy server and REST API for Incotex Mercury meters",
+    )
+    parser.add_argument(
+        "-c",
+        "--config",
+        default=DEFAULT_CONFIG_PATH,
+        metavar="FILE",
+        help="YAML configuration file (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--print-unit",
+        action="store_true",
+        help="print a systemd unit for this installation and exit",
+    )
+    arguments = parser.parse_args(argv)
+    if arguments.print_unit:
+        print(render_unit(arguments.config))
+        return 0
+
+    try:
+        config = load_config(arguments.config)
+        logger = configure_logging(config.logging)
+    except ConfigError as error:
+        print("mercury-proxy: %s" % error, file=sys.stderr)
+        return 2
+
+    service = Service(config)
+
+    def on_signal(signum: int, _frame: Any) -> None:
+        logger.info("Signal %d received, stopping", signum)
+        # Только флаг: сокеты закрывает run() в главном потоке.
+        service.request_stop()
+
+    for name in ("SIGINT", "SIGTERM"):
+        number = getattr(signal, name, None)
+        if number is None:
+            continue
+        try:
+            signal.signal(number, on_signal)
+        except (OSError, ValueError):
+            # В Windows нет настоящего SIGTERM, а рабочий поток не может
+            # ставить обработчики; Ctrl+C всё равно работает через
+            # KeyboardInterrupt.
+            pass
+
+    logger.info("Configuration is loaded from %s", arguments.config)
+    try:
+        service.run()
+    except KeyboardInterrupt:
+        logger.info("Interrupted, stopping")
+        service.request_stop()
+    except (ProxyError, OSError) as error:
+        logger.exception("Mercury proxy has stopped: %s", error)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mercury_proxy/api.py

@@ -0,0 +1,337 @@
+"""
+REST API над командами ``mercury_base``.
+
+API — обычный ``http.server``: ни фреймворка, ни лишней зависимости, поток на
+запрос. Каждое обращение к счётчику сериализует хаб, поэтому медленный счётчик
+задерживает только свои запросы, а прокси держит собственное подключение к той
+же шине. Ответы — JSON; команда отвечает ``{"result": ...}``, ошибка —
+``{"error": "..."}``. Если в конфигурации задан ``api.token``, запрос без
+заголовка ``Authorization: Bearer ...`` получает ``401``; без токена API открыт
+всем, кто дотянулся до порта.
+
+Copyright (c) 2023–2026 webtoucher
+Distributed under the BSD 3-Clause license. See LICENSE.md for more info.
+"""
+
+import hmac
+import json
+import logging
+import threading
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+from urllib.parse import parse_qs, unquote, urlsplit
+
+from mercury_base import CommunicationError, MercuryError, UnknownCommandError
+
+from mercury_proxy.config import ApiConfig
+from mercury_proxy.exceptions import UnknownMeterError
+from mercury_proxy.meters import MeterHub
+
+__all__ = ["RestApi", "API_PREFIX"]
+
+#: Все маршруты живут под этим префиксом, чтобы следующая версия могла
+#: существовать рядом.
+API_PREFIX = "/v1.0"
+
+#: Тело запроса больше этого размера отклоняется, а не читается в память.
+_MAX_BODY = 65536
+
+#: Наибольшее значение параметра команды: это один байт кадра.
+_MAX_PARAM = 0xFF
+
+#: Адреса, с которых запрос не выходит за пределы машины.
+_LOOPBACK = ("127.0.0.1", "::1", "localhost")
+
+#: Схема авторизации: заголовок ``Authorization: Bearer <token>``.
+_AUTH_SCHEME = "Bearer"
+
+_STOP_TIMEOUT = 10.0
+
+
+class _BadRequest(Exception):
+    """Сам запрос неверен; отвечается кодом 400."""
+
+
+class _ApiServer(ThreadingHTTPServer):
+    """Слушающий сокет: поток на запрос, хаб для каждого обработчика."""
+
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(self, address: Tuple[str, int], hub: MeterHub, token: Optional[str]) -> None:
+        super().__init__(address, _RequestHandler)
+        self.hub = hub
+        self.token = token
+        self.logger = logging.getLogger(__name__)
+
+
+class _RequestHandler(BaseHTTPRequestHandler):
+    """Разбирает один запрос, зовёт хаб и пишет ответ в JSON."""
+
+    server: _ApiServer
+    protocol_version = "HTTP/1.1"
+
+    def do_GET(self) -> None:
+        self.__dispatch("GET")
+
+    def do_POST(self) -> None:
+        self.__dispatch("POST")
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Направить лог доступа http.server в логгер сервиса."""
+        self.server.logger.debug("%s - %s", self.address_string(), format % args)
+
+    def __dispatch(self, method: str) -> None:
+        if not self.__authorized():
+            self.server.logger.warning(
+                "Rejected a request to %s from %s: the token is missing or wrong",
+                self.path,
+                self.address_string(),
+            )
+            # Тело запроса не читается, поэтому соединение дальше не переиспользуем:
+            # иначе оставшиеся байты были бы разобраны как следующий запрос.
+            self.close_connection = True
+            self.__send(
+                401,
+                {"error": "unauthorized"},
+                {"WWW-Authenticate": '%s realm="mercury-proxy"' % _AUTH_SCHEME},
+            )
+            return
+        segments = self.__segments()
+        if segments is None:
+            self.__send(404, {"error": "unknown path: %s" % self.path})
+            return
+        try:
+            status, payload = self.__serve(method, segments)
+        except _BadRequest as error:
+            status, payload = 400, {"error": str(error)}
+        except UnknownMeterError as error:
+            status, payload = 404, {"error": str(error)}
+        except UnknownCommandError as error:
+            status, payload = 404, {"error": str(error)}
+        except CommunicationError as error:
+            # Счётчик спросили, а он не ответил или ответил мусором.
+            status, payload = 504, {"error": str(error)}
+        except MercuryError as error:
+            status, payload = 502, {"error": str(error)}
+        except Exception:  # noqa: BLE001 - обработчик обязан ответить, а не упасть
+            self.server.logger.exception("Request %s %s failed", method, self.path)
+            status, payload = 500, {"error": "internal error"}
+        self.__send(status, payload)
+
+    def __authorized(self) -> bool:
+        """Проверить токен из заголовка; без настроенного токена пускаем всех."""
+        token = self.server.token
+        if token is None:
+            return True
+        scheme, _, value = self.headers.get("Authorization", "").partition(" ")
+        if scheme.lower() != _AUTH_SCHEME.lower():
+            return False
+        # Сравнение постоянного времени: по задержке нельзя подобрать токен.
+        return hmac.compare_digest(value.strip().encode("utf-8"), token.encode("utf-8"))
+
+    def __serve(self, method: str, segments: List[str]) -> Tuple[int, Any]:
+        """Провести запрос по маршрутам; возвращает код и полезную нагрузку."""
+        if not segments:
+            return 200, {"name": "mercury-proxy", "api": "1.0"}
+        if segments[0] == "health":
+            return 200, {"status": "ok", "meters": len(self.server.hub.meters)}
+        if segments[0] != "meters":
+            raise _BadRequest("unknown path: %s" % self.path)
+        if len(segments) == 1:
+            return 200, {"meters": [self.__info(meter) for meter in self.server.hub.meters]}
+        if len(segments) == 2:
+            return 200, self.__meter(segments[1])
+        if len(segments) == 3 and method in ("GET", "POST"):
+            return 200, self.__command(segments[1], segments[2], method)
+        raise _BadRequest("unknown path: %s" % self.path)
+
+    def __meter(self, raw_serial: str) -> Dict[str, Any]:
+        serial_number = self.__serial(raw_serial)
+        meter = self.server.hub.find_by_serial_number(serial_number)
+        if meter is None:
+            raise UnknownMeterError("meter %s is not connected" % serial_number)
+        return self.__info(meter)
+
+    def __command(self, raw_serial: str, command: str, method: str) -> Dict[str, Any]:
+        serial_number = self.__serial(raw_serial)
+        params = self.__query_params() if method == "GET" else self.__body_params()
+        self.server.logger.debug(
+            "Request %s /v1.0/meters/%s/%s with params %r",
+            method,
+            serial_number,
+            command,
+            params,
+        )
+        return {"result": self.server.hub.command(serial_number, command, params)}
+
+    @staticmethod
+    def __info(meter: Any) -> Dict[str, Any]:
+        """Описание счётчика в том виде, в каком его показывает API."""
+        info = meter.info
+        return {
+            "serial_number": info.serial_number,
+            "model": info.model,
+            "firmware_version": info.firmware_version,
+            "date_of_manufacture": info.date_of_manufacture,
+            "meter_version": info.meter_version,
+            "features": list(info.features),
+            "port": meter.transport.port,
+        }
+
+    def __segments(self) -> Optional[List[str]]:
+        """Сегменты пути после префикса версии; None для чужого префикса."""
+        path = unquote(urlsplit(self.path).path)
+        if path in (API_PREFIX, API_PREFIX + "/"):
+            return []
+        if not path.startswith(API_PREFIX + "/"):
+            return None
+        return [segment for segment in path[len(API_PREFIX) + 1:].split("/") if segment]
+
+    @staticmethod
+    def __serial(text: str) -> int:
+        try:
+            return int(text, 10)
+        except ValueError:
+            raise _BadRequest("the serial number must be an integer, got %r" % text) from None
+
+    def __query_params(self) -> List[int]:
+        """Параметры команды из строки запроса: ``?params=1,0`` или ``?params=1&params=0``."""
+        query = parse_qs(urlsplit(self.path).query, keep_blank_values=False)
+        raw: List[str] = []
+        for value in query.get("params", []):
+            raw.extend(part.strip() for part in value.split(",") if part.strip())
+        params = []
+        for text in raw:
+            base = 16 if text.lower().startswith("0x") else 10
+            try:
+                params.append(int(text, base))
+            except ValueError:
+                raise _BadRequest(
+                    "params must be integers, got %r" % text
+                ) from None
+        return [self.__param(value) for value in params]
+
+    def __body_params(self) -> List[int]:
+        """Параметры команды из тела JSON: ``{"params": [1, 0]}`` или ``[1, 0]``."""
+        try:
+            size = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            raise _BadRequest("invalid Content-Length header") from None
+        if size > _MAX_BODY:
+            raise _BadRequest("the request body must not exceed %d bytes" % _MAX_BODY)
+        if size <= 0:
+            return []
+        body = self.rfile.read(size)
+        try:
+            document = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise _BadRequest("the body is not valid JSON: %s" % error) from None
+        if document is None:
+            return []
+        if isinstance(document, Mapping):
+            unknown = sorted(str(key) for key in document if key != "params")
+            if unknown:
+                raise _BadRequest("unknown keys in the body: %s" % ", ".join(unknown))
+            document = document.get("params") or []
+        if not isinstance(document, list):
+            raise _BadRequest("params must be a list of integers, got %r" % (document,))
+        return [self.__param(value) for value in document]
+
+    @staticmethod
+    def __param(value: Any) -> int:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise _BadRequest("a command parameter must be an integer, got %r" % (value,))
+        if not 0 <= value <= _MAX_PARAM:
+            raise _BadRequest(
+                "a command parameter must be between 0 and %d, got %d"
+                % (_MAX_PARAM, value)
+            )
+        return value
+
+    def __send(
+        self, status: int, payload: Any, headers: Optional[Mapping[str, str]] = None
+    ) -> None:
+        body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+        try:
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            for name, value in (headers or {}).items():
+                self.send_header(name, value)
+            self.end_headers()
+            self.wfile.write(body)
+        except OSError:
+            # Клиент закрыл свою сторону раньше, чем был записан ответ.
+            self.server.logger.debug("The client %s is gone", self.address_string())
+
+
+class RestApi:
+    """Сервер REST API: сокет, поток и порт, который он получил."""
+
+    def __init__(self, hub: MeterHub, config: ApiConfig) -> None:
+        self.__hub = hub
+        self.__config = config
+        self.__logger = logging.getLogger(__name__)
+        self.__server: Optional[_ApiServer] = None
+        self.__thread: Optional[threading.Thread] = None
+
+    @property
+    def is_running(self) -> bool:
+        """True, пока API принимает запросы."""
+        return self.__server is not None
+
+    @property
+    def host(self) -> str:
+        """Адрес, к которому привязан API."""
+        return self.__config.host
+
+    @property
+    def port(self) -> int:
+        """Порт, к которому привязан API; настоящий, если в конфигурации был 0."""
+        server = self.__server
+        if server is None:
+            return self.__config.port
+        return server.server_address[1]
+
+    def start(self) -> None:
+        """Связать адрес и обслуживать в фоновом потоке.
+
+        Поднимает OSError, если порт занять не удалось; тогда вызывается
+        ``server_close()``, и ничего не остаётся открытым.
+        """
+        if self.__server is not None:
+            raise RuntimeError("the API is already running")
+        server = _ApiServer(
+            (self.__config.host, self.__config.port), self.__hub, self.__config.token
+        )
+        self.__server = server
+        self.__thread = threading.Thread(
+            target=server.serve_forever,
+            kwargs={"poll_interval": 0.1},
+            name="mercury-api",
+            daemon=True,
+        )
+        self.__thread.start()
+        self.__logger.info(
+            "API server is listening on %s:%s", self.__config.host, self.port
+        )
+        if self.__config.token is None and self.__config.host not in _LOOPBACK:
+            self.__logger.warning(
+                "API has no token: anyone who can reach %s:%s can read the meters",
+                self.__config.host,
+                self.port,
+            )
+
+    def stop(self) -> None:
+        """Перестать обслуживать и закрыть слушающий сокет. Безопасно вызывать дважды."""
+        server, self.__server = self.__server, None
+        thread, self.__thread = self.__thread, None
+        if server is None:
+            return
+        server.shutdown()
+        server.server_close()
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(_STOP_TIMEOUT)
+        self.__logger.info("API server has stopped")