toposync-ext-streaming 0.7.9__tar.gz → 0.7.10__tar.gz

toposync_ext_streaming-0.7.9/README.md → toposync_ext_streaming-0.7.10/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: toposync-ext-streaming
+Version: 0.7.10
+Summary: Toposync first-party extension: streaming settings, API surface, and pipeline sink bootstrap.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: opencv-python-headless>=4.10
+Requires-Dist: toposync-core>=0.3.3
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
 # Toposync Streaming Extension
 
 Extension ID: `com.toposync.streaming`
@@ -729,6 +742,15 @@ All endpoints are under `/api/streams`.
 ### Home Assistant
 - `GET /api/streams/home-assistant/cameras`
 
+For Home Assistant running in Docker Compose, the RTSP URL in this manifest must
+use a host reachable from the Home Assistant container. Enable
+`engine.expose_to_lan`, restart the streaming engine, and set
+`TOPOSYNC_HOME_ASSISTANT_RTSP_HOST` to the Compose service name or another
+container-reachable hostname, for example `toposync`. If the endpoint would
+otherwise return a loopback RTSP URL for a non-loopback request host, the
+manifest omits `rtsp_url` and reports a blocking error instead of publishing an
+unusable `rtsp://127.0.0.1:...` URL.
+
 ### Distributed settings
 - `GET /api/streams/distributed/settings/{server_id}`
 
@@ -968,6 +990,10 @@ To enable LAN viewers:
 
 Notes:
 - `GET /api/streams/transmissions/{id}/urls` chooses the host component based on the current request host when `expose_to_lan` is enabled.
+- `GET /api/streams/home-assistant/cameras` follows the same rule, but a
+  Compose-based Home Assistant often needs `TOPOSYNC_HOME_ASSISTANT_RTSP_HOST`
+  so the advertised RTSP host is the Toposync service name visible from the Home
+  Assistant container.
 - If MediaMTX runs behind Docker/NAT, advertise the reachable LAN host with `TOPOSYNC_STREAMING_WEBRTC_ADDITIONAL_HOSTS` and publish the static ICE UDP port configured by `TOPOSYNC_STREAMING_WEBRTC_LOCAL_UDP_ADDRESS`.
 - MediaMTX still restricts publishing and API access to localhost IPs; LAN exposure is for viewer playback only.
 

toposync_ext_streaming-0.7.9/PKG-INFO → toposync_ext_streaming-0.7.10/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: toposync-ext-streaming
-Version: 0.7.9
-Summary: Toposync first-party extension: streaming settings, API surface, and pipeline sink bootstrap.
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: numpy>=1.26
-Requires-Dist: opencv-python-headless>=4.10
-Requires-Dist: toposync-core>=0.3.3
-Requires-Dist: websockets>=12.0
-Description-Content-Type: text/markdown
-
 # Toposync Streaming Extension
 
 Extension ID: `com.toposync.streaming`
@@ -742,6 +729,15 @@ All endpoints are under `/api/streams`.
 ### Home Assistant
 - `GET /api/streams/home-assistant/cameras`
 
+For Home Assistant running in Docker Compose, the RTSP URL in this manifest must
+use a host reachable from the Home Assistant container. Enable
+`engine.expose_to_lan`, restart the streaming engine, and set
+`TOPOSYNC_HOME_ASSISTANT_RTSP_HOST` to the Compose service name or another
+container-reachable hostname, for example `toposync`. If the endpoint would
+otherwise return a loopback RTSP URL for a non-loopback request host, the
+manifest omits `rtsp_url` and reports a blocking error instead of publishing an
+unusable `rtsp://127.0.0.1:...` URL.
+
 ### Distributed settings
 - `GET /api/streams/distributed/settings/{server_id}`
 
@@ -981,6 +977,10 @@ To enable LAN viewers:
 
 Notes:
 - `GET /api/streams/transmissions/{id}/urls` chooses the host component based on the current request host when `expose_to_lan` is enabled.
+- `GET /api/streams/home-assistant/cameras` follows the same rule, but a
+  Compose-based Home Assistant often needs `TOPOSYNC_HOME_ASSISTANT_RTSP_HOST`
+  so the advertised RTSP host is the Toposync service name visible from the Home
+  Assistant container.
 - If MediaMTX runs behind Docker/NAT, advertise the reachable LAN host with `TOPOSYNC_STREAMING_WEBRTC_ADDITIONAL_HOSTS` and publish the static ICE UDP port configured by `TOPOSYNC_STREAMING_WEBRTC_LOCAL_UDP_ADDRESS`.
 - MediaMTX still restricts publishing and API access to localhost IPs; LAN exposure is for viewer playback only.
 

{toposync_ext_streaming-0.7.9 → toposync_ext_streaming-0.7.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toposync-ext-streaming"
-version = "0.7.9"
+version = "0.7.10"
 description = "Toposync first-party extension: streaming settings, API surface, and pipeline sink bootstrap."
 readme = "README.md"
 license = "MIT"

{toposync_ext_streaming-0.7.9 → toposync_ext_streaming-0.7.10}/src/toposync_ext_streaming/api/models.py

@@ -1034,6 +1034,9 @@ class StreamingEngineStatusResponse(BaseModel):
     warnings: list[str] = Field(default_factory=list)
     restart_count: int = Field(default=0, ge=0)
     orphan_pids: list[int] = Field(default_factory=list)
+    port_policy: Literal["stable", "flexible"] = "flexible"
+    port_resolution: str = "preferred"
+    port_blocking_errors: list[str] = Field(default_factory=list)
 
 
 class StreamingMseSidecarStatusResponse(BaseModel):

{toposync_ext_streaming-0.7.9 → toposync_ext_streaming-0.7.10}/src/toposync_ext_streaming/api/routes.py

@@ -33,7 +33,7 @@ from toposync.runtime.pipelines.operators_sinks import _encode_image_bytes
 from toposync.runtime.pipelines.templates import camera_names_by_id, safe_pipeline_name
 from toposync.runtime.services import ServiceRegistry
 
-from ..streaming.engine_manager import MediaMtxEngineManager
+from ..streaming.engine_manager import MediaMtxEngineManager, MediaMtxPortResolutionError
 from ..streaming.go2rtc_binary import extract_go2rtc_binary, find_installed_go2rtc_binary
 from ..streaming.go2rtc_manager import Go2RtcSidecarManager, Go2RtcSidecarStatus
 from ..streaming.camera_ingest import (
@@ -852,7 +852,19 @@ def _build_network_contract(
             media_url_origin=media_url_origin,
         )
 
-    fail_on_mismatch = _env_bool("TOPOSYNC_FAIL_STREAM_URLS_ON_PORT_MISMATCH")
+    explicit_expected_ports = any(
+        value is not None
+        for value in (
+            expected_ports.direct_api,
+            expected_ports.rtsp,
+            expected_ports.hls,
+            expected_ports.webrtc,
+            expected_ports.webrtc_udp,
+            expected_ports.api,
+        )
+    )
+    strict_contract = environment == "home_assistant_addon" or explicit_expected_ports
+    fail_on_mismatch = _env_bool("TOPOSYNC_FAIL_STREAM_URLS_ON_PORT_MISMATCH") or strict_contract
     status: Literal["ok", "port_mismatch", "proxy_required", "proxy_unavailable"] = "ok"
 
     def compare_port(
@@ -869,11 +881,16 @@ def _build_network_contract(
         actual = getattr(actual_ports, key)
         if expected is None or actual is None or int(expected) == int(actual):
             return
-        message = f"{label} active port {actual} does not match expected add-on port {expected}."
+        expected_label = (
+            "expected add-on port"
+            if environment == "home_assistant_addon"
+            else "expected streaming port"
+        )
+        message = f"{label} active port {actual} does not match {expected_label} {expected}."
         warnings.append(message)
         if status == "ok":
             status = "port_mismatch"
-        if blocking_when_failed and fail_on_mismatch:
+        if (blocking_when_failed and fail_on_mismatch) or strict_contract:
             blocking_errors.append(message)
 
     compare_port(
@@ -2626,7 +2643,12 @@ def _url_has_loopback_host(url: str | None) -> bool:
         host = str(urllib_parse.urlsplit(str(url or "")).hostname or "").strip().lower()
     except Exception:
         return False
-    return host in {"localhost", "::1"} or host.startswith("127.")
+    return _host_is_loopback(host)
+
+
+def _host_is_loopback(host: str | None) -> bool:
+    normalized = str(host or "").strip().lower()
+    return normalized in {"localhost", "::1"} or normalized.startswith("127.")
 
 
 def _url_host_for_rtsp(url: str | None) -> str:
@@ -2940,10 +2962,17 @@ async def _build_home_assistant_camera_item(
             blocking_errors.append(f"Failed to resolve remote Home Assistant camera playback: {exc}")
     else:
         engine_path = resolve_output_engine_path(transmission, output)
+        home_assistant_rtsp_host = _home_assistant_rtsp_host(request)
         rtsp_url = await _engine_manager(request).get_read_url_for_path(
             engine_path,
-            host=_home_assistant_rtsp_host(request),
+            host=home_assistant_rtsp_host,
         )
+        if _url_has_loopback_host(rtsp_url) and not _host_is_loopback(home_assistant_rtsp_host):
+            blocking_errors.append(
+                "Local streaming engine returned a loopback RTSP URL for Home Assistant camera playback; "
+                "enable engine.expose_to_lan and set TOPOSYNC_HOME_ASSISTANT_RTSP_HOST to a host reachable by Home Assistant."
+            )
+            rtsp_url = None
         redacted_rtsp_url = _redact_url_credentials(rtsp_url)
 
     role = variant.role if variant is not None else None
@@ -6153,6 +6182,10 @@ def create_streaming_router() -> APIRouter:
                     path_auth=path_auth,
                     path_configs=path_configs,
                 )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -6277,6 +6310,7 @@ def create_streaming_router() -> APIRouter:
 
         warnings: list[str] = []
         warnings.extend(list(status.warnings))
+        warnings.extend(list(status.port_blocking_errors))
         if not settings.engine.enabled:
             warnings.append("Engine is disabled in settings.")
         if settings.engine.enabled and not status.running:
@@ -6354,6 +6388,9 @@ def create_streaming_router() -> APIRouter:
             warnings=warnings,
             restart_count=status.restart_count,
             orphan_pids=orphan_pids,
+            port_policy=status.port_policy if status.port_policy in {"stable", "flexible"} else "flexible",
+            port_resolution=status.port_resolution,
+            port_blocking_errors=list(status.port_blocking_errors),
         )
 
     @router.post("/engine/download", response_model=StreamingEngineStatusResponse)
@@ -6416,6 +6453,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to start streaming engine: {exc}"
@@ -6477,6 +6518,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to restart streaming engine: {exc}"
@@ -6532,6 +6577,12 @@ def create_streaming_router() -> APIRouter:
                     ),
                     path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
                 )
+            except MediaMtxPortResolutionError as exc:
+                suffix = f" (killed {len(killed_pids)} stale process(es))" if killed_pids else ""
+                raise HTTPException(
+                    status_code=409,
+                    detail=f"Streaming engine port contract is blocked: {exc}{suffix}",
+                ) from exc
             except Exception as exc:
                 suffix = f" (killed {len(killed_pids)} stale process(es))" if killed_pids else ""
                 raise HTTPException(
@@ -6864,6 +6915,10 @@ def create_streaming_router() -> APIRouter:
             await _apply_streaming_engine_state(request, settings=saved)
         except HTTPException:
             raise
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -6911,6 +6966,10 @@ def create_streaming_router() -> APIRouter:
             await _apply_streaming_engine_state(request, settings=saved)
         except HTTPException:
             raise
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -7111,6 +7170,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -7202,6 +7265,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -7271,6 +7338,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -7342,6 +7413,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -7390,6 +7465,10 @@ def create_streaming_router() -> APIRouter:
                 ),
                 path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
             )
+        except MediaMtxPortResolutionError as exc:
+            raise HTTPException(
+                status_code=409, detail=f"Streaming engine port contract is blocked: {exc}"
+            ) from exc
         except Exception as exc:
             raise HTTPException(
                 status_code=500, detail=f"Failed to apply streaming settings: {exc}"
@@ -8646,6 +8725,11 @@ def create_streaming_router() -> APIRouter:
                     ),
                     path_configs=build_camera_ingest_path_configs(camera_ingest_by_id),
                 )
+            except MediaMtxPortResolutionError as exc:
+                raise HTTPException(
+                    status_code=409,
+                    detail=f"Streaming engine port contract is blocked: {exc}",
+                ) from exc
             except Exception as exc:
                 raise HTTPException(
                     status_code=500, detail=f"Failed to rotate ingest credentials: {exc}"