smart-messaging-core 0.1.1__tar.gz

smart_messaging_core-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 allenshie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smart_messaging_core-0.1.1/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: smart-messaging-core
+Version: 0.1.1
+Summary: Messaging helpers for edge/integration services.
+Author: SmartWarehousing Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/allenshie/smart_messaging_core
+Project-URL: Repository, https://github.com/allenshie/smart_messaging_core
+Project-URL: Issues, https://github.com/allenshie/smart_messaging_core/issues
+Keywords: messaging,mqtt,http,kafka,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=1.6.1
+Requires-Dist: kafka-python>=2.0.2
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# smart_messaging_core
+
+可擴充的通訊核心套件，提供統一的 `MessagingClient` facade，並可依 route 將訊息導向不同協議。
+
+## 目前支援的協議
+
+- `mqtt`: publish / subscribe
+- `http`: publish / subscribe（webhook）
+- `kafka`: publish / subscribe
+- `redis`: publish / subscribe
+
+註：`kafka` 與 `redis` 目前已提供 client/config 與文件、測試腳本骨架；若要實際連線驗證，需安裝對應套件並啟動外部服務。
+
+## 安裝（本機）
+
+```bash
+cd /home/allen/Documents/project/asia-bay/SmartWarehousing/test/smart_messaging_core
+pip install -e .
+```
+
+## 文件
+
+- [通訊介面與使用範例](docs/README.md)
+- [MQTT 使用說明](docs/mqtt/README.md)
+- [HTTP 使用說明](docs/http/README.md)
+- [Kafka 使用說明](docs/kafka/README.md)
+- [Redis 使用說明](docs/redis/README.md)
+
+## 設計說明
+
+- 對外 API：`MessagingClient`
+- 協議實作集中在 `protocols/`
+- 每個協議提供對應 `Config` 與 `Client`
+- route-based 設計可讓不同用途走不同 backend/channel
+- 錯誤處理可透過 `failure_mode` 控制（`degraded` 只 log；`strict` 會 raise）

smart_messaging_core-0.1.1/README.md

@@ -0,0 +1,35 @@
+# smart_messaging_core
+
+可擴充的通訊核心套件，提供統一的 `MessagingClient` facade，並可依 route 將訊息導向不同協議。
+
+## 目前支援的協議
+
+- `mqtt`: publish / subscribe
+- `http`: publish / subscribe（webhook）
+- `kafka`: publish / subscribe
+- `redis`: publish / subscribe
+
+註：`kafka` 與 `redis` 目前已提供 client/config 與文件、測試腳本骨架；若要實際連線驗證，需安裝對應套件並啟動外部服務。
+
+## 安裝（本機）
+
+```bash
+cd /home/allen/Documents/project/asia-bay/SmartWarehousing/test/smart_messaging_core
+pip install -e .
+```
+
+## 文件
+
+- [通訊介面與使用範例](docs/README.md)
+- [MQTT 使用說明](docs/mqtt/README.md)
+- [HTTP 使用說明](docs/http/README.md)
+- [Kafka 使用說明](docs/kafka/README.md)
+- [Redis 使用說明](docs/redis/README.md)
+
+## 設計說明
+
+- 對外 API：`MessagingClient`
+- 協議實作集中在 `protocols/`
+- 每個協議提供對應 `Config` 與 `Client`
+- route-based 設計可讓不同用途走不同 backend/channel
+- 錯誤處理可透過 `failure_mode` 控制（`degraded` 只 log；`strict` 會 raise）

smart_messaging_core-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "smart-messaging-core"
+version = "0.1.1"
+description = "Messaging helpers for edge/integration services."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "SmartWarehousing Team" },
+]
+keywords = ["messaging", "mqtt", "http", "kafka", "redis"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Networking",
+]
+dependencies = [
+  "paho-mqtt>=1.6.1",
+  "kafka-python>=2.0.2",
+  "redis>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/allenshie/smart_messaging_core"
+Repository = "https://github.com/allenshie/smart_messaging_core"
+Issues = "https://github.com/allenshie/smart_messaging_core/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "twine>=5.1.1",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

smart_messaging_core-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smart_messaging_core-0.1.1/src/smart_messaging_core/__init__.py

@@ -0,0 +1,37 @@
+"""Public exports for smart_messaging_core."""
+from .base import BaseProtocolClient, BaseProtocolConfig
+from .client import MessagingClient, MessagingConfig, RouteConfig
+from .protocols import (
+    HttpClient,
+    HttpConfig,
+    HttpPublisher,
+    KafkaClient,
+    KafkaConfig,
+    MqttClient,
+    MqttConfig,
+    MqttPublisher,
+    MqttSubscriber,
+    RedisClient,
+    RedisConfig,
+)
+from .registry import CLIENTS
+
+__all__ = [
+    "BaseProtocolClient",
+    "BaseProtocolConfig",
+    "MessagingClient",
+    "MessagingConfig",
+    "RouteConfig",
+    "HttpClient",
+    "HttpConfig",
+    "HttpPublisher",
+    "KafkaClient",
+    "KafkaConfig",
+    "MqttClient",
+    "MqttConfig",
+    "MqttPublisher",
+    "MqttSubscriber",
+    "RedisClient",
+    "RedisConfig",
+    "CLIENTS",
+]

smart_messaging_core-0.1.1/src/smart_messaging_core/base.py

@@ -0,0 +1,42 @@
+"""Base protocol abstractions for smart_messaging_core."""
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass
+class BaseProtocolConfig:
+    """Base configuration for a messaging protocol client."""
+
+    enabled: bool = True
+
+
+class BaseProtocolClient(ABC):
+    """Unified protocol client interface used by MessagingClient."""
+
+    supports_publish: bool = False
+    supports_subscribe: bool = False
+    config_type = BaseProtocolConfig
+
+    def __init__(self, config: BaseProtocolConfig) -> None:
+        self._validate_config(config)
+        self._config = config
+
+    @classmethod
+    def _validate_config(cls, config: BaseProtocolConfig) -> None:
+        if not isinstance(config, cls.config_type):
+            raise TypeError(
+                f"{cls.__name__} requires {cls.config_type.__name__}, got {type(config).__name__}"
+            )
+
+    def publish(self, channel: str, payload: dict[str, Any]) -> bool:
+        raise NotImplementedError(f"{self.__class__.__name__} does not support publish")
+
+    def subscribe(self, channel: str, handler: Callable[[dict[str, Any]], None]) -> None:
+        raise NotImplementedError(f"{self.__class__.__name__} does not support subscribe")
+
+    def close(self) -> None:
+        """Release protocol resources; default is no-op."""
+        return None

smart_messaging_core-0.1.1/src/smart_messaging_core/client.py

@@ -0,0 +1,101 @@
+"""Route-based unified messaging client."""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from smart_messaging_core.protocols.http import HttpConfig
+from smart_messaging_core.protocols.kafka import KafkaConfig
+from smart_messaging_core.protocols.mqtt import MqttConfig
+from smart_messaging_core.protocols.redis import RedisConfig
+from smart_messaging_core.registry import CLIENTS
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class RouteConfig:
+    backend: str
+    channel: str
+
+
+@dataclass
+class MessagingConfig:
+    failure_mode: str = "degraded"
+    mqtt: MqttConfig = field(default_factory=MqttConfig)
+    http: HttpConfig | None = None
+    kafka: KafkaConfig | None = None
+    redis: RedisConfig | None = None
+    routes: dict[str, RouteConfig] = field(default_factory=dict)
+
+
+class MessagingClient:
+    """Facade that routes publish/subscribe calls to protocol-specific clients."""
+
+    def __init__(self, config: MessagingConfig) -> None:
+        self._config = config
+        self._clients: dict[str, Any] = {}
+
+    def publish(self, route_key: str, payload: dict[str, Any]) -> bool:
+        try:
+            backend, channel = self._resolve_route(route_key)
+            client = self._get_client(backend)
+            if not getattr(client, "supports_publish", False):
+                raise ValueError(f"Backend {backend} does not support publish")
+            return client.publish(channel, payload)
+        except Exception as exc:  # pylint: disable=broad-except
+            self._handle_error("publish", route_key, exc)
+            return False
+
+    def subscribe(self, route_key: str, handler: Callable[[dict[str, Any]], None]) -> None:
+        try:
+            backend, channel = self._resolve_route(route_key)
+            client = self._get_client(backend)
+            if not getattr(client, "supports_subscribe", False):
+                raise ValueError(f"Backend {backend} does not support subscribe")
+            client.subscribe(channel, handler)
+        except Exception as exc:  # pylint: disable=broad-except
+            self._handle_error("subscribe", route_key, exc)
+
+    def close(self) -> None:
+        for backend, client in list(self._clients.items()):
+            try:
+                close_fn = getattr(client, "close", None)
+                if callable(close_fn):
+                    close_fn()
+            except Exception as exc:  # pylint: disable=broad-except
+                LOGGER.warning("Messaging close failed (backend=%s): %s", backend, exc)
+        self._clients.clear()
+
+    def _resolve_route(self, route_key: str) -> tuple[str, str]:
+        route = self._config.routes.get(route_key)
+        if route is None:
+            raise ValueError(f"Unknown route: {route_key}")
+        return route.backend, route.channel
+
+    def _get_client(self, backend: str):
+        key = (backend or "").strip().lower()
+        client = self._clients.get(key)
+        if client is not None:
+            return client
+        entry = CLIENTS.get(key)
+        if entry is None:
+            raise ValueError(f"Unsupported backend: {backend}")
+        config_attr, config_cls, client_cls = entry
+        cfg = getattr(self._config, config_attr, None)
+        if cfg is None:
+            raise ValueError(f"Missing config for backend: {backend}")
+        if not isinstance(cfg, config_cls):
+            raise TypeError(
+                f"Config for backend {backend} must be {config_cls.__name__}, got {type(cfg).__name__}"
+            )
+        client = client_cls(cfg)
+        self._clients[key] = client
+        return client
+
+    def _handle_error(self, action: str, route_key: str, exc: Exception) -> None:
+        mode = (self._config.failure_mode or "degraded").strip().lower()
+        if mode == "strict":
+            raise exc
+        LOGGER.warning("Messaging %s failed (route=%s, mode=%s): %s", action, route_key, mode, exc)

smart_messaging_core-0.1.1/src/smart_messaging_core/protocols/__init__.py

@@ -0,0 +1,19 @@
+"""Protocol exports for smart_messaging_core."""
+from .http import HttpClient, HttpConfig, HttpPublisher
+from .kafka import KafkaClient, KafkaConfig
+from .mqtt import MqttClient, MqttConfig, MqttPublisher, MqttSubscriber
+from .redis import RedisClient, RedisConfig
+
+__all__ = [
+    "HttpClient",
+    "HttpConfig",
+    "HttpPublisher",
+    "KafkaClient",
+    "KafkaConfig",
+    "MqttClient",
+    "MqttConfig",
+    "MqttPublisher",
+    "MqttSubscriber",
+    "RedisClient",
+    "RedisConfig",
+]

smart_messaging_core-0.1.1/src/smart_messaging_core/protocols/http.py

@@ -0,0 +1,135 @@
+"""HTTP protocol client."""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable
+
+from smart_messaging_core.base import BaseProtocolClient, BaseProtocolConfig
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class HttpConfig(BaseProtocolConfig):
+    base_url: str = ""
+    timeout_seconds: int = 5
+    listen_host: str = "0.0.0.0"
+    listen_port: int = 9000
+
+
+class HttpClient(BaseProtocolClient):
+    """HTTP client supporting publish + webhook subscribe."""
+
+    supports_publish = True
+    supports_subscribe = True
+    config_type = HttpConfig
+
+    def __init__(self, config: HttpConfig) -> None:
+        super().__init__(config)
+        self._server: ThreadingHTTPServer | None = None
+        self._server_thread: threading.Thread | None = None
+        self._handlers: dict[str, Callable[[dict[str, Any]], None]] = {}
+
+    @property
+    def listening_port(self) -> int:
+        if self._server is None:
+            return self._config.listen_port
+        return int(self._server.server_address[1])
+
+    def publish(self, channel: str, payload: dict[str, Any]) -> bool:
+        if not self._config.base_url:
+            LOGGER.warning("HTTP publish failed: base_url is empty")
+            return False
+        path = channel if channel.startswith("/") else f"/{channel}"
+        url = f"{self._config.base_url.rstrip('/')}{path}"
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=self._config.timeout_seconds):
+                return True
+        except urllib.error.URLError as exc:
+            LOGGER.warning("HTTP publish failed (%s): %s", url, exc)
+            return False
+
+    def subscribe(self, channel: str, handler: Callable[[dict[str, Any]], None]) -> None:
+        path = channel if channel.startswith("/") else f"/{channel}"
+        self._handlers[path] = handler
+        self._ensure_server()
+
+    def close(self) -> None:
+        if self._server is None:
+            return
+        self._server.shutdown()
+        self._server.server_close()
+        if self._server_thread is not None:
+            self._server_thread.join(timeout=2)
+        self._server = None
+        self._server_thread = None
+
+    def _ensure_server(self) -> None:
+        if self._server is not None:
+            return
+
+        owner = self
+
+        class _WebhookHandler(BaseHTTPRequestHandler):
+            def do_POST(self):  # noqa: N802
+                callback = owner._handlers.get(self.path)
+                if callback is None:
+                    self.send_error(HTTPStatus.NOT_FOUND, "unknown path")
+                    return
+
+                length = int(self.headers.get("Content-Length", "0"))
+                body = self.rfile.read(length)
+                try:
+                    payload = json.loads(body.decode("utf-8"))
+                    if not isinstance(payload, dict):
+                        raise ValueError("payload must be JSON object")
+                except Exception as exc:  # pylint: disable=broad-except
+                    LOGGER.warning("HTTP subscribe invalid payload (%s): %s", self.path, exc)
+                    self.send_error(HTTPStatus.BAD_REQUEST, f"invalid payload: {exc}")
+                    return
+
+                try:
+                    callback(payload)
+                except Exception as exc:  # pylint: disable=broad-except
+                    LOGGER.warning("HTTP subscribe callback failed (%s): %s", self.path, exc)
+                    self.send_error(HTTPStatus.INTERNAL_SERVER_ERROR, "callback failed")
+                    return
+
+                self.send_response(HTTPStatus.ACCEPTED)
+                self.end_headers()
+
+            def log_message(self, format, *args):  # noqa: A003, ANN001
+                LOGGER.debug("http-sub %s - %s", self.address_string(), format % args)
+
+        self._server = ThreadingHTTPServer(
+            (self._config.listen_host, self._config.listen_port),
+            _WebhookHandler,
+        )
+        self._server_thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._server_thread.start()
+        LOGGER.info(
+            "HTTP subscribe server listening on %s:%s",
+            self._config.listen_host,
+            self.listening_port,
+        )
+
+
+class HttpPublisher:
+    """Compatibility wrapper for the legacy publish-only HTTP API."""
+
+    def __init__(self, config: HttpConfig, topic_routes: dict[str, str] | None = None) -> None:
+        self._client = HttpClient(config)
+        self._topic_routes = topic_routes or {}
+
+    def publish(self, topic: str, payload: dict[str, Any]) -> bool:
+        channel = self._topic_routes.get(topic, topic)
+        return self._client.publish(channel, payload)

smart_messaging_core-0.1.1/src/smart_messaging_core/protocols/kafka.py

@@ -0,0 +1,60 @@
+"""Kafka protocol client."""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from smart_messaging_core.base import BaseProtocolClient, BaseProtocolConfig
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class KafkaConfig(BaseProtocolConfig):
+    bootstrap_servers: str = "localhost:9092"
+    client_id: str | None = None
+    group_id: str | None = None
+    auto_offset_reset: str = "latest"
+
+
+class KafkaClient(BaseProtocolClient):
+    """Kafka client supporting publish and subscribe."""
+
+    supports_publish = True
+    supports_subscribe = True
+    config_type = KafkaConfig
+
+    def publish(self, channel: str, payload: dict[str, Any]) -> bool:
+        try:
+            from kafka import KafkaProducer  # type: ignore
+        except ModuleNotFoundError as exc:
+            raise RuntimeError("Missing dependency: kafka-python") from exc
+        producer = KafkaProducer(
+            bootstrap_servers=self._config.bootstrap_servers,
+            client_id=self._config.client_id,
+            value_serializer=lambda value: json.dumps(value, ensure_ascii=False).encode("utf-8"),
+        )
+        try:
+            producer.send(channel, payload).get(timeout=5)
+            return True
+        finally:
+            producer.close()
+
+    def subscribe(self, channel: str, handler: Callable[[dict[str, Any]], None]) -> None:
+        try:
+            from kafka import KafkaConsumer  # type: ignore
+        except ModuleNotFoundError as exc:
+            raise RuntimeError("Missing dependency: kafka-python") from exc
+        consumer = KafkaConsumer(
+            channel,
+            bootstrap_servers=self._config.bootstrap_servers,
+            client_id=self._config.client_id,
+            group_id=self._config.group_id,
+            auto_offset_reset=self._config.auto_offset_reset,
+            value_deserializer=lambda value: json.loads(value.decode("utf-8") or "{}"),
+        )
+        for message in consumer:
+            if isinstance(message.value, dict):
+                handler(message.value)

smart_messaging_core-0.1.1/src/smart_messaging_core/protocols/mqtt.py

@@ -0,0 +1,154 @@
+"""MQTT protocol client."""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Callable
+
+from smart_messaging_core.base import BaseProtocolClient, BaseProtocolConfig
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class MqttConfig(BaseProtocolConfig):
+    host: str = "localhost"
+    port: int = 1883
+    qos: int = 1
+    retain: bool = True
+    client_id: str | None = None
+    keepalive: int = 60
+    auth_enabled: bool = False
+    username: str | None = None
+    password: str | None = None
+
+
+class MqttClient(BaseProtocolClient):
+    """MQTT client supporting both publish and subscribe."""
+
+    supports_publish = True
+    supports_subscribe = True
+    config_type = MqttConfig
+
+    def __init__(self, config: MqttConfig) -> None:
+        super().__init__(config)
+        self._client = None
+        self._subscriptions: set[str] = set()
+
+    def publish(self, channel: str, payload: dict[str, object]) -> bool:
+        try:
+            client = self._ensure_client(connect_async=False)
+        except Exception as exc:  # pylint: disable=broad-except
+            LOGGER.warning("MQTT publish client init failed: %s", exc)
+            return False
+
+        message = json.dumps(payload, ensure_ascii=False)
+        result = client.publish(channel, message, qos=self._config.qos, retain=self._config.retain)
+        if result.rc != 0:
+            LOGGER.warning("MQTT publish failed (rc=%s)", result.rc)
+            return False
+        return True
+
+    def subscribe(self, channel: str, handler: Callable[[dict[str, object]], None]) -> None:
+        try:
+            client = self._ensure_client(connect_async=True)
+        except Exception as exc:  # pylint: disable=broad-except
+            LOGGER.warning("MQTT subscribe client init failed: %s", exc)
+            return
+        client.message_callback_add(channel, self._build_message_handler(handler))
+        self._subscriptions.add(channel)
+        if getattr(client, "is_connected", lambda: False)():
+            client.subscribe(channel, qos=self._config.qos)
+
+    def _ensure_client(self, connect_async: bool):
+        if self._client is not None:
+            return self._client
+        try:
+            import paho.mqtt.client as mqtt  # type: ignore
+        except ModuleNotFoundError as exc:
+            raise RuntimeError("Missing dependency: paho-mqtt") from exc
+        client = mqtt.Client(client_id=self._config.client_id)
+        _apply_auth(client, self._config)
+        client.on_connect = self._handle_connect
+        if connect_async:
+            client.reconnect_delay_set(min_delay=1, max_delay=30)
+            client.connect_async(self._config.host, self._config.port, keepalive=self._config.keepalive)
+            client.loop_start()
+        else:
+            client.connect(self._config.host, self._config.port, keepalive=self._config.keepalive)
+            client.loop_start()
+        self._client = client
+        return client
+
+
+    def close(self) -> None:
+        if self._client is None:
+            return
+        try:
+            self._client.loop_stop()
+        except Exception as exc:  # pylint: disable=broad-except
+            LOGGER.debug("MQTT loop_stop failed: %s", exc)
+        try:
+            self._client.disconnect()
+        except Exception as exc:  # pylint: disable=broad-except
+            LOGGER.debug("MQTT disconnect failed: %s", exc)
+        self._client = None
+
+    def _handle_connect(self, client, userdata, flags, rc):  # noqa: ANN001
+        _ = (userdata, flags)
+        if rc != 0:
+            LOGGER.warning("MQTT connect failed (rc=%s)", rc)
+            return
+        for channel in self._subscriptions:
+            client.subscribe(channel, qos=self._config.qos)
+
+    @staticmethod
+    def _build_message_handler(handler: Callable[[dict[str, object]], None]):
+        def _handle_message(client, userdata, msg):  # noqa: ANN001
+            _ = (client, userdata)
+            try:
+                payload = json.loads(msg.payload.decode("utf-8") or "{}")
+            except json.JSONDecodeError:
+                LOGGER.debug("MQTT message ignored: invalid json")
+                return
+            if isinstance(payload, dict):
+                handler(payload)
+
+        return _handle_message
+
+
+class MqttPublisher:
+    """Compatibility wrapper for the legacy MQTT publish API."""
+
+    def __init__(self, config: MqttConfig, topic: str) -> None:
+        self._client = MqttClient(config)
+        self._topic = topic
+
+    def publish(self, payload: dict[str, object]) -> bool:
+        return self._client.publish(self._topic, payload)
+
+
+class MqttSubscriber:
+    """Compatibility wrapper for the legacy MQTT subscribe API."""
+
+    def __init__(
+        self,
+        config: MqttConfig,
+        topic: str,
+        on_message: Callable[[dict[str, object]], None],
+    ) -> None:
+        self._client = MqttClient(config)
+        self._topic = topic
+        self._on_message = on_message
+
+    def start(self) -> None:
+        self._client.subscribe(self._topic, self._on_message)
+
+
+def _apply_auth(client, config: MqttConfig) -> None:  # noqa: ANN001
+    if not config.auth_enabled:
+        return
+    if not config.username:
+        raise ValueError("mqtt auth enabled but username is empty")
+    client.username_pw_set(config.username, config.password)

smart_messaging_core-0.1.1/src/smart_messaging_core/protocols/redis.py

@@ -0,0 +1,56 @@
+"""Redis protocol client."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Callable
+
+from smart_messaging_core.base import BaseProtocolClient, BaseProtocolConfig
+
+
+@dataclass
+class RedisConfig(BaseProtocolConfig):
+    host: str = "localhost"
+    port: int = 6379
+    db: int = 0
+    username: str | None = None
+    password: str | None = None
+
+
+class RedisClient(BaseProtocolClient):
+    """Redis pub/sub client."""
+
+    supports_publish = True
+    supports_subscribe = True
+    config_type = RedisConfig
+
+    def publish(self, channel: str, payload: dict[str, object]) -> bool:
+        client = self._build_client()
+        return client.publish(channel, json.dumps(payload, ensure_ascii=False)) > 0
+
+    def subscribe(self, channel: str, handler: Callable[[dict[str, object]], None]) -> None:
+        client = self._build_client()
+        pubsub = client.pubsub()
+        pubsub.subscribe(channel)
+        for message in pubsub.listen():
+            if message.get("type") != "message":
+                continue
+            data = message.get("data")
+            if isinstance(data, bytes):
+                payload = json.loads(data.decode("utf-8") or "{}")
+                if isinstance(payload, dict):
+                    handler(payload)
+
+    def _build_client(self):
+        try:
+            import redis  # type: ignore
+        except ModuleNotFoundError as exc:
+            raise RuntimeError("Missing dependency: redis") from exc
+        return redis.Redis(
+            host=self._config.host,
+            port=self._config.port,
+            db=self._config.db,
+            username=self._config.username,
+            password=self._config.password,
+            decode_responses=False,
+        )

smart_messaging_core-0.1.1/src/smart_messaging_core/registry.py

@@ -0,0 +1,17 @@
+"""Protocol registry for smart_messaging_core."""
+from __future__ import annotations
+
+from typing import Any
+
+from smart_messaging_core.protocols.http import HttpClient, HttpConfig
+from smart_messaging_core.protocols.kafka import KafkaClient, KafkaConfig
+from smart_messaging_core.protocols.mqtt import MqttClient, MqttConfig
+from smart_messaging_core.protocols.redis import RedisClient, RedisConfig
+
+
+CLIENTS: dict[str, tuple[str, type[Any], type[Any]]] = {
+    "mqtt": ("mqtt", MqttConfig, MqttClient),
+    "http": ("http", HttpConfig, HttpClient),
+    "kafka": ("kafka", KafkaConfig, KafkaClient),
+    "redis": ("redis", RedisConfig, RedisClient),
+}

smart_messaging_core-0.1.1/src/smart_messaging_core.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: smart-messaging-core
+Version: 0.1.1
+Summary: Messaging helpers for edge/integration services.
+Author: SmartWarehousing Team
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/allenshie/smart_messaging_core
+Project-URL: Repository, https://github.com/allenshie/smart_messaging_core
+Project-URL: Issues, https://github.com/allenshie/smart_messaging_core/issues
+Keywords: messaging,mqtt,http,kafka,redis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=1.6.1
+Requires-Dist: kafka-python>=2.0.2
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# smart_messaging_core
+
+可擴充的通訊核心套件，提供統一的 `MessagingClient` facade，並可依 route 將訊息導向不同協議。
+
+## 目前支援的協議
+
+- `mqtt`: publish / subscribe
+- `http`: publish / subscribe（webhook）
+- `kafka`: publish / subscribe
+- `redis`: publish / subscribe
+
+註：`kafka` 與 `redis` 目前已提供 client/config 與文件、測試腳本骨架；若要實際連線驗證，需安裝對應套件並啟動外部服務。
+
+## 安裝（本機）
+
+```bash
+cd /home/allen/Documents/project/asia-bay/SmartWarehousing/test/smart_messaging_core
+pip install -e .
+```
+
+## 文件
+
+- [通訊介面與使用範例](docs/README.md)
+- [MQTT 使用說明](docs/mqtt/README.md)
+- [HTTP 使用說明](docs/http/README.md)
+- [Kafka 使用說明](docs/kafka/README.md)
+- [Redis 使用說明](docs/redis/README.md)
+
+## 設計說明
+
+- 對外 API：`MessagingClient`
+- 協議實作集中在 `protocols/`
+- 每個協議提供對應 `Config` 與 `Client`
+- route-based 設計可讓不同用途走不同 backend/channel
+- 錯誤處理可透過 `failure_mode` 控制（`degraded` 只 log；`strict` 會 raise）

smart_messaging_core-0.1.1/src/smart_messaging_core.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/smart_messaging_core/__init__.py
+src/smart_messaging_core/base.py
+src/smart_messaging_core/client.py
+src/smart_messaging_core/registry.py
+src/smart_messaging_core.egg-info/PKG-INFO
+src/smart_messaging_core.egg-info/SOURCES.txt
+src/smart_messaging_core.egg-info/dependency_links.txt
+src/smart_messaging_core.egg-info/requires.txt
+src/smart_messaging_core.egg-info/top_level.txt
+src/smart_messaging_core/protocols/__init__.py
+src/smart_messaging_core/protocols/http.py
+src/smart_messaging_core/protocols/kafka.py
+src/smart_messaging_core/protocols/mqtt.py
+src/smart_messaging_core/protocols/redis.py
+tests/test_client_routes.py
+tests/test_imports.py
+tests/test_protocol_validation.py

smart_messaging_core-0.1.1/src/smart_messaging_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

smart_messaging_core-0.1.1/src/smart_messaging_core.egg-info/requires.txt

@@ -0,0 +1,7 @@
+paho-mqtt>=1.6.1
+kafka-python>=2.0.2
+redis>=5.0.0
+
+[dev]
+build>=1.2.2
+twine>=5.1.1

smart_messaging_core-0.1.1/src/smart_messaging_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+smart_messaging_core

smart_messaging_core-0.1.1/tests/test_client_routes.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from unittest import TestCase
+from unittest.mock import patch
+
+from smart_messaging_core.base import BaseProtocolClient, BaseProtocolConfig
+from smart_messaging_core.client import MessagingClient, MessagingConfig, RouteConfig
+
+
+@dataclass
+class DummyConfig(BaseProtocolConfig):
+    value: str = "dummy"
+
+
+class DummyClient(BaseProtocolClient):
+    supports_publish = True
+    supports_subscribe = True
+    config_type = DummyConfig
+
+    def __init__(self, config: DummyConfig) -> None:
+        super().__init__(config)
+        self.published: list[tuple[str, dict]] = []
+        self.subscribed: list[str] = []
+        self.closed = False
+
+    def publish(self, channel: str, payload: dict) -> bool:
+        self.published.append((channel, payload))
+        return True
+
+    def subscribe(self, channel: str, handler) -> None:  # noqa: ANN001
+        self.subscribed.append(channel)
+
+    def close(self) -> None:
+        self.closed = True
+
+
+class MessagingClientRouteTests(TestCase):
+    def test_routes_publish_and_subscribe(self) -> None:
+        with patch(
+            "smart_messaging_core.client.CLIENTS",
+            {"dummy": ("dummy", DummyConfig, DummyClient)},
+        ):
+            cfg = MessagingConfig(
+                routes={
+                    "phase_publish": RouteConfig(backend="dummy", channel="integration/phase"),
+                    "edge_events": RouteConfig(backend="dummy", channel="edge/events"),
+                },
+            )
+            cfg.dummy = DummyConfig()  # type: ignore[attr-defined]
+            client = MessagingClient(cfg)
+
+            self.assertTrue(client.publish("phase_publish", {"phase": "working"}))
+            client.subscribe("edge_events", lambda payload: payload)
+
+            dummy = client._clients["dummy"]  # noqa: SLF001
+            self.assertEqual(dummy.published, [("integration/phase", {"phase": "working"})])
+            self.assertEqual(dummy.subscribed, ["edge/events"])
+
+    def test_close_closes_all_created_protocol_clients(self) -> None:
+        with patch(
+            "smart_messaging_core.client.CLIENTS",
+            {"dummy": ("dummy", DummyConfig, DummyClient)},
+        ):
+            cfg = MessagingConfig(routes={"phase_publish": RouteConfig(backend="dummy", channel="phase")})
+            cfg.dummy = DummyConfig()  # type: ignore[attr-defined]
+            client = MessagingClient(cfg)
+            client.publish("phase_publish", {"x": 1})
+
+            dummy = client._clients["dummy"]  # noqa: SLF001
+            self.assertFalse(dummy.closed)
+            client.close()
+            self.assertTrue(dummy.closed)
+            self.assertEqual(client._clients, {})  # noqa: SLF001

smart_messaging_core-0.1.1/tests/test_imports.py

@@ -0,0 +1,20 @@
+def test_imports() -> None:
+    from smart_messaging_core import (  # noqa: F401
+        BaseProtocolClient,
+        BaseProtocolConfig,
+        CLIENTS,
+        HttpClient,
+        HttpConfig,
+        HttpPublisher,
+        KafkaClient,
+        KafkaConfig,
+        MessagingClient,
+        MessagingConfig,
+        MqttClient,
+        MqttConfig,
+        MqttPublisher,
+        MqttSubscriber,
+        RedisClient,
+        RedisConfig,
+        RouteConfig,
+    )

smart_messaging_core-0.1.1/tests/test_protocol_validation.py

@@ -0,0 +1,74 @@
+import json
+import threading
+import urllib.request
+from unittest import TestCase
+
+from smart_messaging_core.base import BaseProtocolConfig
+from smart_messaging_core.client import MessagingClient, MessagingConfig, RouteConfig
+from smart_messaging_core.protocols.http import HttpClient, HttpConfig
+from smart_messaging_core.protocols.mqtt import MqttClient, MqttConfig
+
+
+class WrongConfig(BaseProtocolConfig):
+    pass
+
+
+class ProtocolValidationTests(TestCase):
+    def test_mqtt_client_rejects_wrong_config_type(self) -> None:
+        with self.assertRaises(TypeError):
+            MqttClient(WrongConfig())  # type: ignore[arg-type]
+
+    def test_http_client_rejects_wrong_config_type(self) -> None:
+        with self.assertRaises(TypeError):
+            HttpClient(WrongConfig())  # type: ignore[arg-type]
+
+    def test_messaging_client_strict_mode_raises_for_unsupported_backend(self) -> None:
+        client = MessagingClient(
+            MessagingConfig(
+                failure_mode="strict",
+                mqtt=MqttConfig(),
+                http=HttpConfig(base_url="http://localhost:8080"),
+                routes={"phase_publish": RouteConfig(backend="unsupported", channel="/phase")},
+            )
+        )
+        with self.assertRaises(ValueError):
+            client.publish("phase_publish", {"x": 1})
+
+    def test_messaging_client_strict_mode_raises_for_unknown_route(self) -> None:
+        client = MessagingClient(
+            MessagingConfig(
+                failure_mode="strict",
+                mqtt=MqttConfig(),
+                routes={"edge_events": RouteConfig(backend="mqtt", channel="edge/events")},
+            )
+        )
+        with self.assertRaises(ValueError):
+            client.publish("unknown_route", {"x": 1})
+
+    def test_http_client_subscribe_starts_local_server(self) -> None:
+        received: dict | None = None
+        event = threading.Event()
+
+        cfg = HttpConfig(listen_host="127.0.0.1", listen_port=0)
+        client = HttpClient(cfg)
+
+        def _handler(payload: dict) -> None:
+            nonlocal received
+            received = payload
+            event.set()
+
+        client.subscribe("/edge/events", _handler)
+        port = client.listening_port
+
+        req = urllib.request.Request(
+            f"http://127.0.0.1:{port}/edge/events",
+            data=json.dumps({"camera_id": "cam01"}).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=2):
+            pass
+
+        self.assertTrue(event.wait(timeout=2))
+        self.assertEqual(received, {"camera_id": "cam01"})
+        client.close()