somestuff-ucmstuff 0.1.3__py3-none-any.whl

somestuff/ucmstuff/__init__.py

@@ -0,0 +1,112 @@
+"""ucmstuff — Grandstream UCM6204 monitor/control package.
+
+Central logging setup lives here (loguru), mirroring dnsstuff's setup. This
+package logs via the stdlib ``logging`` module, so :func:`configure_logging`
+installs an intercept handler that funnels those records into loguru instead of
+rewriting every call site.
+"""
+
+import inspect
+import logging
+import os
+import sys
+from collections.abc import Callable
+from types import FrameType
+from typing import TYPE_CHECKING
+
+from loguru import logger as glogger
+from tabulate import tabulate
+
+if TYPE_CHECKING:
+    from loguru import Record
+
+__version__ = "0.1.3"
+
+__all__ = ["__version__", "configure_logging", "print_banner"]
+
+
+def _loguru_skiplog_filter(record: "Record") -> bool:
+    """Decide whether a loguru record should be emitted.
+
+    Args:
+        record: The loguru record about to be handled by a sink.
+
+    Returns:
+        ``False`` for records whose ``extra['skiplog']`` flag is truthy (they are
+        hidden), ``True`` otherwise.
+    """
+    return not record.get("extra", {}).get("skiplog", False)
+
+
+class _InterceptHandler(logging.Handler):
+    """Route stdlib ``logging`` records into loguru with correct call-site info.
+
+    Every module in this package uses ``logging.getLogger(...)``; installing this
+    on the root logger lets :func:`configure_logging` govern all of them (format,
+    level, colour) without touching the individual call sites.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Forward a single stdlib record to loguru.
+
+        Args:
+            record: The stdlib log record to re-emit through loguru, preserving
+                its level, message, exception info and originating call site.
+        """
+        # Map the stdlib level name to a loguru level, falling back to the number.
+        level: str | int
+        try:
+            level = glogger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+        # Walk out of the logging module so {module}/{function}/{line} point at the
+        # real caller rather than at this handler (canonical loguru intercept recipe).
+        frame: FrameType | None = inspect.currentframe()
+        depth = 0
+        while frame and (depth == 0 or frame.f_code.co_filename == logging.__file__):
+            frame = frame.f_back
+            depth += 1
+        glogger.bind(classname=record.name).opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def configure_logging(
+    verbose: bool = False, loguru_filter: Callable[["Record"], bool] = _loguru_skiplog_filter
+) -> None:
+    """Configure a default ``loguru`` sink and funnel stdlib logging into it.
+
+    Args:
+        verbose: ``True`` logs at DEBUG, otherwise honours ``LOGURU_LEVEL`` (INFO
+            by default).
+        loguru_filter: Predicate deciding, per loguru record, whether it is emitted
+            by the sink. Defaults to :func:`_loguru_skiplog_filter`.
+    """
+    level_name: str = "DEBUG" if verbose else os.getenv("LOGURU_LEVEL", "INFO")
+    os.environ["LOGURU_LEVEL"] = level_name
+    glogger.remove()
+    logger_fmt: str = (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{module}</cyan>::<cyan>{extra[classname]}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
+    )
+    glogger.add(sys.stderr, level=level_name, format=logger_fmt, filter=loguru_filter)  # type: ignore[arg-type]
+    glogger.configure(extra={"classname": "None", "skiplog": False})
+    # Replace any stdlib handlers with the intercept so all ``logging`` output
+    # (this package's and third-party libraries') flows through loguru.
+    logging.basicConfig(handlers=[_InterceptHandler()], level=logging.getLevelNamesMapping()[level_name], force=True)
+
+
+def print_banner() -> None:
+    """Log the startup banner with version, build time and project links."""
+    startup_rows = [
+        ["version", __version__],
+        ["buildtime", os.getenv("BUILDTIME", "unknown")],
+        ["github", "https://github.com/vroomfondel/somestuff/tree/main/somestuff/ucmstuff"],
+        ["Docker Hub", "https://hub.docker.com/r/xomoxcc/somestuff"],
+    ]
+    table_str = tabulate(startup_rows, tablefmt="mixed_grid")
+    lines = table_str.split("\n")
+    table_width = len(lines[0])
+    title = "ucm6204 event monitor starting up"
+    title_border = "┍" + "━" * (table_width - 2) + "┑"
+    title_row = "│ " + title.center(table_width - 4) + " │"
+    separator = lines[0].replace("┍", "┝").replace("┑", "┥").replace("┯", "┿")
+
+    glogger.opt(raw=True).info(f"\n{title_border}\n{title_row}\n{separator}\n{'\n'.join(lines[1:])}\n")

somestuff/ucmstuff/example_router.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Coordinated example: monitor UCM calls over WebSocket and control them via the API.
+
+This wires the two coordinated clients together:
+
+* :class:`~somestuff.ucmstuff.ucm6204_api.UCMEventClient` — receives real-time call events
+  over the WebSocket (authenticated with a *web* user).
+* :class:`~somestuff.ucmstuff.ucm6204_api.UCM6204` — the HTTPS-API control client
+  (authenticated with the *API* user), used to act on those events.
+
+A :class:`~somestuff.ucmstuff.ucm6204_api.TrunkCallRouter` filters incoming calls to the
+configured trunk(s) and hands each one to ``on_incoming``, where the caller-based
+branching lives. Configuration is read from environment variables — see
+``ucm.env.example``.
+
+Run (from the repo root so ``ucmstuff`` is importable)::
+
+    set -a; . somestuff/ucmstuff/ucm.local.env; set +a   # your filled-in copy
+    python3 -m somestuff.ucmstuff.example_router
+"""
+
+import logging
+import os
+import sys
+
+from somestuff.ucmstuff.ucm6204_api import (
+    UCM6204,
+    IncomingCall,
+    TrunkCallRouter,
+    UCMAPIError,
+    UCMEventClient,
+)
+
+
+def main() -> None:
+    """Wire the event and control clients together and run the event loop.
+
+    Reads connection settings from environment variables (see
+    ``ucm.env.example``): ``UCM_HOST`` (required), ``UCM_PORT`` (defaults to
+    ``"8089"``), ``UCM_TRUNKS`` (whitespace-separated inbound trunk names; empty
+    means monitoring only, no call routing), ``UCM_API_USER``/``UCM_API_PASSWORD``
+    (HTTPS-API control credentials) and ``UCM_WEB_USER``/``UCM_WEB_PASSWORD``
+    (WebSocket event credentials).
+
+    Connects the :class:`~somestuff.ucmstuff.ucm6204_api.UCM6204` control client, wires a
+    :class:`~somestuff.ucmstuff.ucm6204_api.TrunkCallRouter` (if trunks are configured) to
+    ``on_incoming``, then runs the
+    :class:`~somestuff.ucmstuff.ucm6204_api.UCMEventClient` event loop, blocking the calling
+    thread until interrupted (``events.run(block=True)`` only returns once the
+    loop is stopped).
+
+    Raises:
+        KeyError: If a required environment variable (``UCM_HOST``,
+            ``UCM_API_USER``, ``UCM_API_PASSWORD``, ``UCM_WEB_USER`` or
+            ``UCM_WEB_PASSWORD``) is not set.
+        somestuff.ucmstuff.ucm6204_api.UCMAPIError: If the initial HTTPS-API login fails.
+    """
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
+
+    host = os.environ["UCM_HOST"]
+    port = int(os.environ.get("UCM_PORT", "8089"))
+    trunks = [t for t in os.environ.get("UCM_TRUNKS", "").split() if t]
+
+    # Control client (HTTPS API, API user) — used to act on calls.
+    api = UCM6204(
+        host=host, port=port, api_user=os.environ["UCM_API_USER"], api_password=os.environ["UCM_API_PASSWORD"]
+    )
+    api.connect()
+
+    # Event client (WebSocket, web user) — receives the call events.
+    events = UCMEventClient(
+        host=host, ws_port=port, web_user=os.environ["UCM_WEB_USER"], web_password=os.environ["UCM_WEB_PASSWORD"]
+    )
+
+    def on_incoming(call: IncomingCall) -> None:
+        """Log the incoming call and branch by caller (demo placeholder).
+
+        Registered as the ``on_call`` callback of
+        :class:`~somestuff.ucmstuff.ucm6204_api.TrunkCallRouter`; fires exactly once per new
+        incoming call on the configured trunk(s). Replace the commented-out rules
+        below with your own caller-based logic, e.g. auto-accepting allow-listed
+        numbers or auto-refusing based on the caller name.
+
+        Args:
+            call: The parsed incoming call (caller number/name, channel, trunk).
+        """
+        logging.info("incoming %s call from %r <%s> on %s", call.trunk, call.name, call.number, call.channel)
+        # --- your caller-based branching goes here, e.g.: ---
+        # try:
+        #     if call.number in {"+491234567"}:
+        #         api.accept_call(call.channel)
+        #     elif call.name.upper().startswith("SPAM"):
+        #         api.refuse_call(call.channel)
+        # except UCMAPIError as exc:
+        #     logging.warning("control action failed: %s", exc)
+
+    if trunks:
+        events.add_event_handler(TrunkCallRouter(trunks, on_call=on_incoming).handle)
+    else:
+        logging.warning("UCM_TRUNKS is empty — monitoring only, no call routing")
+
+    logging.info("monitoring %s:%d, trunks=%s", host, port, trunks or "-")
+    events.run(block=True)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(0)

somestuff/ucmstuff/mqtt_bridge.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Bridge UCM6204 WebSocket events onto MQTT — and optionally act on MQTT commands.
+
+Keeps transport/parsing (:mod:`somestuff.ucmstuff.ucm6204_api`) separate from messaging
+(:mod:`mqttstuff`): this is the *only* module that imports ``mqttstuff``, so the
+core client stays dependency-light and usable without a broker.
+
+Two directions, both optional and independently usable:
+
+* **Outbound (monitor → MQTT).** Register :meth:`MqttEventBridge.publish_event`
+  as a :data:`~somestuff.ucmstuff.ucm6204_api.EventHandler` (every raw event) and/or
+  :meth:`publish_incoming` as a :data:`~somestuff.ucmstuff.ucm6204_api.CallHandler`
+  (parsed incoming calls on routed trunks) with the :class:`UCMEventClient`.
+* **Inbound (MQTT → control).** With ``enable_commands=True`` and an
+  :class:`~somestuff.ucmstuff.ucm6204_api.UCM6204` control client, subscribe to
+  ``<base>/cmd/#`` and dispatch ``accept`` / ``refuse`` / ``hangup`` to the API.
+
+Topic layout (``base_topic`` defaults to ``ucm6204``)::
+
+    ucm6204/events/<eventname>       transient  full notify event as JSON
+    ucm6204/calls/<trunk>/incoming   transient  parsed IncomingCall as JSON
+    ucm6204/calls/<trunk>/ended      transient  same call once its leg terminates
+    ucm6204/cmd/{accept,refuse,hangup}   inbound   {"channel": "PJSIP/..."}
+
+All outbound messages are published with ``retain=False`` — they are point-in-time
+notifications, never retained "last value" state.
+
+Incoming calls are published per inbound trunk (``<trunk>`` is the call's
+``inbound_trunk_name``, MQTT-sanitized); subscribe to ``ucm6204/calls/+/incoming``
+for all trunks or ``ucm6204/calls/<trunk>/incoming`` for one. When the routed
+call leg terminates, the same payload (``state: "Ended"``) is published to
+``.../ended`` — start and end of a call share one stream, matched via
+``channel``.
+
+Serialization note: mqttstuff's ``publish_one`` only wraps ``dict`` values (via
+``json.dumps``); a bare ``list`` — e.g. an ``ActiveCallStatus`` ``eventbody`` — is
+passed straight to paho and raises ``TypeError``. This bridge therefore always
+publishes a ``dict`` (the whole event, or a hand-built payload), never a naked
+list.
+"""
+
+import logging
+from dataclasses import asdict
+from typing import Any, Iterable
+
+from mqttstuff import MosquittoClientWrapper, MWMqttMessage
+
+from somestuff.ucmstuff.ucm6204_api import UCM6204, IncomingCall, NotifyEvent, UCMAPIError, UCMEventClient
+
+# stdlib logger by design: ucm6204_api.configure_logging() routes root-logger
+# records into loguru via its _InterceptHandler, so this output lands there too.
+logger = logging.getLogger(__name__)
+
+# MQTT topic-level separator and single-/multi-level wildcards — illegal inside a
+# topic segment, so any of these in a trunk name would split or break the topic.
+_MQTT_RESERVED = str.maketrans({"/": "_", "+": "_", "#": "_"})
+
+
+def _mqtt_safe(name: str) -> str:
+    """Turn a trunk name into a single, publishable MQTT topic segment.
+
+    Replaces the reserved characters ``/ + #`` with ``_`` and trims surrounding
+    whitespace. An empty or whitespace-only name (e.g. a call with no
+    ``inbound_trunk_name``) collapses to ``"unknown"`` so the topic never contains
+    an empty level.
+
+    Args:
+        name: The raw trunk name (e.g. ``inbound_trunk_name`` from an
+            :class:`~somestuff.ucmstuff.ucm6204_api.ActiveCall`).
+
+    Returns:
+        str: A single MQTT topic segment, never empty.
+    """
+    safe = name.strip().translate(_MQTT_RESERVED)
+    return safe or "unknown"
+
+
+class MqttEventBridge:
+    """Publish UCM events to MQTT and optionally dispatch MQTT commands to the API.
+
+    See the module docstring for the topic layout and the outbound/inbound
+    direction split.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int = 1883,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        base_topic: str = "ucm6204",
+        api: UCM6204 | None = None,
+        tls: bool = False,
+        tls_ca: str | None = None,
+        tls_cert: str | None = None,
+        tls_key: str | None = None,
+        tls_insecure: bool = False,
+    ) -> None:
+        """Initialize the bridge and the underlying MQTT client wrapper.
+
+        Does not connect yet — call :meth:`start` to connect and begin the
+        network loop.
+
+        Args:
+            host: MQTT broker host (e.g. ``mosquitto.mosquitto.svc.cluster.local``).
+            port: Broker port. Defaults to ``1883``; TLS brokers usually listen
+                on ``8883`` — set that explicitly, it is NOT switched
+                automatically.
+            username: Broker username, or ``None`` for anonymous.
+            password: Broker password, or ``None``.
+            base_topic: Root of the topic tree. Defaults to ``"ucm6204"``.
+            api: A connected :class:`UCM6204` control client. Required only when the
+                inbound command path is enabled (:meth:`start` with
+                ``enable_commands=True``); ``None`` disables control.
+            tls: Encrypt the connection with TLS.
+            tls_ca: Path to the CA certificate (PEM) that signed the broker's
+                certificate; ``None`` uses the system CA store.
+            tls_cert: Path to a client certificate (PEM) for mutual TLS, or ``None``.
+            tls_key: Path to the client certificate's private key, or ``None``.
+            tls_insecure: Skip hostname verification (self-signed certificates
+                whose CN/SAN does not match the host). The connection is still
+                encrypted, but vulnerable to MITM — last resort only.
+
+        Raises:
+            ValueError: TLS options are inconsistent — ``tls_cert`` without
+                ``tls_key`` (or vice versa), or ``tls_*`` values given while
+                ``tls`` is off (validated by ``mqttstuff``); unreadable
+                certificate/key files propagate from ``ssl``.
+        """
+        self._base = base_topic.strip("/")
+        self._host = host
+        self._port = port
+        self._api = api
+        # TLS is native in mqttstuff >= 0.0.6 (ca None -> system CA store).
+        self._mq = MosquittoClientWrapper(
+            host=host,
+            port=port,
+            username=username,
+            password=password,
+            tls=tls,
+            tls_ca_certs=tls_ca,
+            tls_certfile=tls_cert,
+            tls_keyfile=tls_key,
+            tls_insecure=tls_insecure,
+        )
+        if tls and tls_insecure:
+            logger.warning("MQTT TLS hostname verification DISABLED (tls_insecure) — encrypted but MITM-able")
+
+    # ── Outbound: UCM → MQTT ────────────────────────────────────────────────
+
+    def publish_event(self, event: NotifyEvent) -> None:
+        """EventHandler: publish one raw notify event to ``<base>/events/<eventname>``.
+
+        Register with :meth:`UCMEventClient.add_event_handler`. Publishes the whole
+        event dict (``eventname`` + ``eventbody`` + ``transactionid``) as JSON.
+        Never raises — a broker hiccup must not kill the WebSocket receive loop.
+
+        Args:
+            event: The notify event delivered by :class:`UCMEventClient`.
+        """
+        name = str(event.get("eventname") or "unknown")
+        self._safe_publish(f"{self._base}/events/{name}", dict(event))
+
+    def publish_incoming(self, call: IncomingCall) -> None:
+        """CallHandler: publish a parsed incoming call to ``<base>/calls/<trunk>/incoming``.
+
+        Register as the ``on_call`` of a :class:`TrunkCallRouter` (or call it from
+        your own router). The inbound trunk becomes a topic segment (MQTT-sanitized,
+        see :func:`_mqtt_safe`), so subscribers can filter per trunk. Drops the bulky
+        ``raw`` leg dict from the payload.
+
+        Args:
+            call: The parsed incoming call, as produced by :class:`TrunkCallRouter`.
+        """
+        payload = {k: v for k, v in asdict(call).items() if k != "raw"}
+        trunk = _mqtt_safe(call.trunk)
+        self._safe_publish(f"{self._base}/calls/{trunk}/incoming", payload)
+
+    def publish_ended(self, call: IncomingCall) -> None:
+        """CallHandler: publish a terminated call to ``<base>/calls/<trunk>/ended``.
+
+        Register as the ``on_end`` of a :class:`TrunkCallRouter`. The payload has
+        the same shape as :meth:`publish_incoming` (``state`` is ``"Ended"``), so
+        subscribers can pair start and end of a call via ``channel``.
+
+        Args:
+            call: The ended call, as produced by :class:`TrunkCallRouter`.
+        """
+        payload = {k: v for k, v in asdict(call).items() if k != "raw"}
+        trunk = _mqtt_safe(call.trunk)
+        self._safe_publish(f"{self._base}/calls/{trunk}/ended", payload)
+
+    def _safe_publish(self, topic: str, payload: dict[str, Any]) -> None:
+        """Publish ``payload`` (always a dict → JSON), swallowing broker errors.
+
+        Always publishes with ``retain=False``: these are point-in-time events
+        (an event fired, a call arrived), so a retained "last value" left on the
+        broker would be replayed as stale state to every late subscriber.
+
+        Args:
+            topic: Full MQTT topic to publish to.
+            payload: The JSON-serializable payload (arbitrary JSON-compatible
+                values, hence ``Any``); ``mqttstuff.publish_one`` wraps it in
+                ``json.dumps``. See the module docstring's serialization note on
+                why this must always be a ``dict``, never a bare ``list``.
+        """
+        try:
+            ok = self._mq.publish_one(topic, payload, retain=False)
+            if not ok:
+                logger.warning("MQTT publish to %s not confirmed", topic)
+        except Exception:
+            logger.exception("MQTT publish to %s failed", topic)
+
+    # ── Inbound: MQTT → UCM control ─────────────────────────────────────────
+
+    def start(self, enable_commands: bool = False) -> None:
+        """Connect to the broker and start the network loop (blocking-in-thread).
+
+        Args:
+            enable_commands: Subscribe to ``<base>/cmd/#`` and dispatch commands to
+                the API control client. Requires ``api=`` to have been supplied.
+
+        Raises:
+            ValueError: ``enable_commands=True`` without an ``api`` control client.
+        """
+        if enable_commands:
+            if self._api is None:
+                raise ValueError("enable_commands=True requires api=UCM6204(...)")
+            cmd_topic = f"{self._base}/cmd/#"
+            # set_topics() records the filter in the client's userdata, so on_connect
+            # issues the actual SUBSCRIBE — on the first connect *and* on every paho
+            # auto-reconnect. add_message_callback() alone only registers client-side
+            # routing and would never make the broker deliver anything.
+            self._mq.set_topics([cmd_topic])
+            self._mq.add_message_callback(cmd_topic, self._on_command, rettype="json")
+            logger.info("MQTT command path enabled on %s", cmd_topic)
+        logger.info("MQTT bridge connecting to host=%s port=%d base=%s", self._host, self._port, self._base)
+        connected = self._mq.wait_for_connect_and_start_loop()
+        if connected:
+            logger.info("MQTT bridge successfully connected to host=%s port=%d", self._host, self._port)
+        else:
+            logger.warning(
+                "MQTT bridge NOT connected to host=%s port=%d within timeout — paho keeps retrying in background",
+                self._host,
+                self._port,
+            )
+
+    def stop(self) -> None:
+        """Disconnect from the broker."""
+        try:
+            self._mq.disconnect()
+        except Exception:
+            logger.exception("MQTT disconnect failed")
+
+    # Command topic suffix → matching :class:`~somestuff.ucmstuff.ucm6204_api.UCM6204` method name.
+    _COMMANDS: dict[str, str] = {"accept": "accept_call", "refuse": "refuse_call", "hangup": "hangup"}
+
+    def _on_command(self, msg: MWMqttMessage, userdata: dict[str, Any]) -> None:
+        """Dispatch one ``<base>/cmd/<action>`` message to the API control client.
+
+        Payload is JSON with at least ``{"channel": "PJSIP/..."}``. Unknown actions,
+        missing channels and API errors are logged, never raised (this runs in the
+        paho network thread).
+
+        Registered via :meth:`start` as the ``mqttstuff`` message callback for
+        ``<base>/cmd/#`` (``rettype="json"``), so ``mqttstuff`` calls it directly —
+        its signature is dictated by :meth:`MosquittoClientWrapper.add_message_callback`.
+
+        Args:
+            msg: The decoded command message; ``msg.value`` is the JSON payload
+                (expected to be a ``dict``) and ``msg.topic`` is the full command
+                topic (``<base>/cmd/<action>``).
+            userdata: ``mqttstuff``'s internal per-client state dict (topic list,
+                QoS, connect condition …). Untouched here — accepted only because
+                ``mqttstuff`` always passes it to message callbacks; its value
+                types are heterogeneous library internals, hence ``Any``.
+        """
+        action = str(msg.topic).rsplit("/", 1)[-1]
+        method = self._COMMANDS.get(action)
+        if method is None:
+            logger.warning("ignoring MQTT command with unknown action %r (topic=%s)", action, msg.topic)
+            return
+        body = msg.value if isinstance(msg.value, dict) else {}
+        channel = body.get("channel")
+        if not isinstance(channel, str) or not channel:
+            logger.warning("MQTT command %s without a 'channel' — ignoring (payload=%r)", action, msg.value)
+            return
+        assert self._api is not None  # guaranteed by start(enable_commands=True)
+        try:
+            getattr(self._api, method)(channel)
+            logger.info("MQTT command %s on %s -> ok", action, channel)
+        except UCMAPIError as exc:
+            logger.warning("MQTT command %s on %s failed: %s", action, channel, exc)
+
+
+def attach_bridge(
+    eventclient: UCMEventClient,
+    bridge: MqttEventBridge,
+    trunks: Iterable[str] = (),
+    *,
+    raw_events: bool = True,
+) -> None:
+    """Convenience wiring: hook a :class:`MqttEventBridge` onto a UCMEventClient.
+
+    Args:
+        eventclient: The :class:`~somestuff.ucmstuff.ucm6204_api.UCMEventClient` to attach the
+            bridge to.
+        bridge: The bridge to attach.
+        trunks: Inbound trunk name(s); if given, a
+            :class:`~somestuff.ucmstuff.ucm6204_api.TrunkCallRouter` is registered that
+            publishes parsed incoming calls via
+            :meth:`MqttEventBridge.publish_incoming` and their termination via
+            :meth:`MqttEventBridge.publish_ended`. Empty → no call routing.
+        raw_events: Also publish every raw event via
+            :meth:`MqttEventBridge.publish_event`. Defaults to ``True``.
+    """
+    # Imported here so the module's import graph doesn't force TrunkCallRouter on
+    # callers that only want raw-event publishing.
+    from somestuff.ucmstuff.ucm6204_api import TrunkCallRouter
+
+    if raw_events:
+        eventclient.add_event_handler(bridge.publish_event)
+    trunk_list = [t for t in trunks if t]
+    if trunk_list:
+        router = TrunkCallRouter(trunk_list, on_call=bridge.publish_incoming, on_end=bridge.publish_ended)
+        eventclient.add_event_handler(router.handle)