appecosystem-client 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,112 @@
1
+ Metadata-Version: 2.4
2
+ Name: appecosystem-client
3
+ Version: 0.3.1
4
+ Summary: Service registration, peer discovery and event bus client for appEcosystem
5
+ Author: Mikel Smart
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/M1K31/appEcosystem
8
+ Project-URL: Source, https://github.com/M1K31/appEcosystem
9
+ Project-URL: Issues, https://github.com/M1K31/appEcosystem/issues
10
+ Keywords: service-discovery,events,microservices,mdns,appecosystem
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: System :: Distributed Computing
21
+ Requires-Python: >=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: httpx>=0.24.0
25
+ Requires-Dist: appecosystem-auth>=0.4.0
26
+ Provides-Extra: mdns
27
+ Requires-Dist: zeroconf>=0.80.0; extra == "mdns"
28
+ Provides-Extra: yaml
29
+ Requires-Dist: pyyaml>=6.0; extra == "yaml"
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=7.0; extra == "dev"
32
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+ # appecosystem-client
36
+
37
+ Client library for joining the
38
+ [appEcosystem](https://github.com/M1K31/appEcosystem) service mesh: register a
39
+ service, discover peers, and publish or subscribe to events.
40
+
41
+ Services find each other through a local registry (or mDNS), so an application
42
+ can react to what other applications on the network are doing — a doorbell
43
+ camera detecting motion, a SIEM raising an alert — without any of them being
44
+ hard-wired to each other.
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install appecosystem-client
50
+ ```
51
+
52
+ Requires Python 3.9+. Pulls in `appecosystem-auth` for request signing.
53
+
54
+ Optional extras:
55
+
56
+ ```bash
57
+ pip install "appecosystem-client[mdns]" # zeroconf peer discovery
58
+ pip install "appecosystem-client[yaml]" # YAML config files
59
+ ```
60
+
61
+ ## Join the ecosystem
62
+
63
+ ```python
64
+ import asyncio
65
+ from ecosystem_client import EcosystemClient
66
+
67
+ async def main():
68
+ eco = EcosystemClient(
69
+ service_name="my-app",
70
+ service_port=9000,
71
+ health_endpoint="/health",
72
+ )
73
+ await eco.start() # registers, then discovers peers
74
+
75
+ await eco.publish("myapp.ready", {"version": "1.0"})
76
+
77
+ peer = await eco.discover("openeye")
78
+ if peer:
79
+ print("found OpenEye at", peer)
80
+
81
+ await eco.stop() # deregisters cleanly
82
+
83
+ asyncio.run(main())
84
+ ```
85
+
86
+ ## Receive events
87
+
88
+ Register a handler for an event pattern. `*` matches one namespace segment:
89
+
90
+ ```python
91
+ @eco.on("camera.*")
92
+ async def on_camera_event(event):
93
+ print(event["type"], event["data"])
94
+ ```
95
+
96
+ Deliver incoming webhooks to `eco.handle_webhook(payload)` from whatever HTTP
97
+ route your framework exposes.
98
+
99
+ ## Event patterns
100
+
101
+ | Pattern | Matches |
102
+ |---|---|
103
+ | `camera.motion` | that exact type |
104
+ | `camera.*` | `camera.motion`, `camera.offline` |
105
+ | `*` | every event with a non-empty type |
106
+
107
+ An event with an empty type matches nothing — a malformed publish from one
108
+ service cannot fan out to every subscriber.
109
+
110
+ ## License
111
+
112
+ MIT — see [LICENSE](https://github.com/M1K31/appEcosystem/blob/main/LICENSE).
@@ -0,0 +1,14 @@
1
+ appecosystem_client-0.3.1.dist-info/licenses/LICENSE,sha256=9pbiGmkcpIANcEL5akiT3goeQqBPFpo1elePA-sy9mM,1073
2
+ ecosystem_client/__init__.py,sha256=DZklEW9PxuozoQrPzubOeKS-qeiLk8qPo-HWpDVt9ZY,9350
3
+ ecosystem_client/config.py,sha256=FF1spzDAitNiPvqXNOml0VtXuPAMTHWcmPV73DaJluE,4678
4
+ ecosystem_client/discovery.py,sha256=vdKQ3HqnvlwsW3U2RkT_JxAqtTJo3V1wJgWXYg-zxFQ,8752
5
+ ecosystem_client/event_publisher.py,sha256=bi02GOejba1K5_-y983MiiqWxYchHiOH-gZSXkxMdPw,5863
6
+ ecosystem_client/event_subscriber.py,sha256=HeNVSpXWDjSlKUNd7WJW53NUjIIiLAu7gYvNJVOdCuE,2787
7
+ ecosystem_client/log_handler.py,sha256=DxmT-7045yZOYTls4pd8DU-rAf0kRQYx50jsRjvAvRE,1728
8
+ ecosystem_client/match.py,sha256=4yznXDlhm_thgb2ER5aE_qjP2IZ1-IDyd6XmILj9JB4,833
9
+ ecosystem_client/peer.py,sha256=e370S2RQ4uSKqgH3a18wXmdDPS38KnoQGvATNVfDTuI,3006
10
+ ecosystem_client/topology.py,sha256=p-USt_DbI1disv71fRE5IMoBxg7sDjhxIvG1twCL66c,3979
11
+ appecosystem_client-0.3.1.dist-info/METADATA,sha256=9ZHjpuLUK4Z2odws00YnVSjPolAaNqvutee0fgV_i8I,3379
12
+ appecosystem_client-0.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
13
+ appecosystem_client-0.3.1.dist-info/top_level.txt,sha256=aVa6-13ez5ALvFIDy1Gdm_vfvlALEP8V5PykvyPfkz4,17
14
+ appecosystem_client-0.3.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-2026 Mikel Smart
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ ecosystem_client
@@ -0,0 +1,237 @@
1
+ """Ecosystem client library for inter-service communication."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import logging
6
+ import socket
7
+ from typing import Any, Callable, Coroutine
8
+
9
+ from .config import EcosystemConfig
10
+ from .discovery import DiscoveryManager, DiscoveryMode
11
+ from .event_publisher import EventPublisher
12
+ from .event_subscriber import EventSubscriber
13
+ from .log_handler import EcosystemLogHandler
14
+ from .peer import Peer
15
+
16
+ # Keep in step with packages/ecosystem-client/pyproject.toml. This drifted to
17
+ # 0.1.0 while pyproject said 0.3.1, so anything reporting the runtime version
18
+ # (logs, diagnostics, compatibility checks) named a release that never shipped.
19
+ __version__ = "0.3.1"
20
+
21
+ logger = logging.getLogger(__name__)
22
+
23
+ HandlerFunc = Callable[[dict[str, Any]], Coroutine[Any, Any, None]]
24
+
25
+
26
+ class EcosystemClient:
27
+ """
28
+ Thin client for ecosystem integration.
29
+
30
+ Handles service discovery, event pub/sub, and direct peer calls
31
+ across three operating modes:
32
+ - REGISTRY: full ecosystem with appEcosystem registry
33
+ - PEER_TO_PEER: direct mDNS or static peer discovery
34
+ - STANDALONE: no-op, project runs independently
35
+ """
36
+
37
+ def __init__(
38
+ self,
39
+ service_name: str,
40
+ service_port: int,
41
+ health_endpoint: str = "/health",
42
+ subscriptions: list[str] | None = None,
43
+ config: EcosystemConfig | None = None,
44
+ priority: int = 0,
45
+ ):
46
+ self._config = config or EcosystemConfig.from_env()
47
+ self._config.service_name = service_name
48
+ self._config.service_port = service_port
49
+ self._config.health_endpoint = health_endpoint
50
+ if priority:
51
+ self._config.priority = priority
52
+
53
+ self._service_name = service_name
54
+ self._service_port = service_port
55
+ self._health_endpoint = health_endpoint
56
+ self._subscriptions = subscriptions or []
57
+
58
+ self._discovery = DiscoveryManager(self._config)
59
+ self._publisher = EventPublisher(
60
+ self._config, mode=DiscoveryMode.STANDALONE, service_name=service_name,
61
+ )
62
+ self._subscriber = EventSubscriber(hmac_secret=self._config.hmac_secret)
63
+
64
+ self._peers: dict[str, dict[str, Any]] = {}
65
+ self._peer_objects: dict[str, Peer] = {}
66
+ self._started = False
67
+ self._refresh_task: asyncio.Task | None = None
68
+ self._advertised_host: str | None = None # last host we registered with
69
+
70
+ @property
71
+ def mode(self) -> DiscoveryMode:
72
+ return self._discovery.mode
73
+
74
+ async def start(self) -> None:
75
+ """Start the ecosystem client: detect mode, register, discover peers."""
76
+ if self._started:
77
+ return
78
+
79
+ mode = await self._discovery.detect_mode()
80
+ self._publisher._mode = mode
81
+
82
+ if mode == DiscoveryMode.REGISTRY:
83
+ await self._register_self()
84
+
85
+ # Discover peers
86
+ await self._refresh_peers()
87
+
88
+ self._started = True
89
+ logger.info(
90
+ f"Ecosystem client started: {self._service_name} in {mode.value} mode"
91
+ )
92
+
93
+ # Start background refresh
94
+ self._refresh_task = asyncio.create_task(self._periodic_refresh())
95
+
96
+ async def stop(self) -> None:
97
+ """Stop the ecosystem client: deregister, cancel background tasks."""
98
+ if self._refresh_task:
99
+ self._refresh_task.cancel()
100
+ try:
101
+ await self._refresh_task
102
+ except asyncio.CancelledError:
103
+ pass
104
+
105
+ if self._discovery.mode == DiscoveryMode.REGISTRY:
106
+ await self._discovery.deregister_self(self._service_name)
107
+
108
+ self._started = False
109
+ logger.info(f"Ecosystem client stopped: {self._service_name}")
110
+
111
+ async def discover(self, service_name: str) -> Peer | None:
112
+ """Get a Peer object for a discovered service, or None if not found."""
113
+ if service_name in self._peer_objects:
114
+ peer = self._peer_objects[service_name]
115
+ if not peer.is_degraded:
116
+ return peer
117
+
118
+ if service_name in self._peers:
119
+ peer_info = self._peers[service_name]
120
+ base_url = peer_info.get("base_url", "")
121
+ if base_url:
122
+ peer = Peer(
123
+ name=service_name,
124
+ base_url=base_url,
125
+ hmac_secret=self._config.hmac_secret,
126
+ timeout=self._config.request_timeout,
127
+ )
128
+ self._peer_objects[service_name] = peer
129
+ return peer
130
+
131
+ return None
132
+
133
+ async def publish(self, event_type: str, data: dict[str, Any]) -> dict:
134
+ """Publish an event to the ecosystem."""
135
+ return await self._publisher.publish(event_type, data)
136
+
137
+ def on(self, event_pattern: str, handler: HandlerFunc | None = None):
138
+ """Register an event handler. Works as method or decorator."""
139
+ result = self._subscriber.on(event_pattern, handler)
140
+ # Update subscriptions list for registration
141
+ if event_pattern not in self._subscriptions:
142
+ self._subscriptions.append(event_pattern)
143
+ return result
144
+
145
+ async def handle_webhook(self, envelope: dict[str, Any]) -> None:
146
+ """Process an incoming webhook event."""
147
+ await self._subscriber.dispatch(envelope)
148
+
149
+ async def _current_advertise_host(self) -> str:
150
+ """The host other services should use to reach us, resolved fresh each
151
+ call so a DHCP/IP change is picked up. Falls back to the legacy local-IP
152
+ probe if the topology helper is unavailable."""
153
+ try:
154
+ from .topology import advertise_host
155
+ return advertise_host()
156
+ except Exception:
157
+ return self._get_local_ip()
158
+
159
+ async def _register_self(self) -> bool:
160
+ """(Re-)register this service with the registry using the current
161
+ advertise host. Idempotent — the registry upserts by name, so calling
162
+ this on an interval acts as a heartbeat that keeps our IP and last-seen
163
+ fresh and re-adds us if we were pruned while unreachable."""
164
+ host = await self._current_advertise_host()
165
+ webhook_url = f"http://{host}:{self._service_port}{self._config.webhook_path}"
166
+ all_subs = list(set(self._subscriptions + self._subscriber.subscriptions))
167
+ ok = await self._discovery.register_self(
168
+ name=self._service_name,
169
+ host=host,
170
+ port=self._service_port,
171
+ health_endpoint=self._health_endpoint,
172
+ webhook_url=webhook_url,
173
+ subscriptions=all_subs,
174
+ priority=self._config.priority,
175
+ )
176
+ if ok:
177
+ self._advertised_host = host
178
+ return ok
179
+
180
+ async def _refresh_peers(self) -> None:
181
+ """Refresh the peer list from discovery."""
182
+ self._peers = await self._discovery.get_peers()
183
+ # Clear cached peer objects for removed peers
184
+ for name in list(self._peer_objects.keys()):
185
+ if name not in self._peers:
186
+ del self._peer_objects[name]
187
+ # Update publisher's peer webhooks for Mode 2
188
+ if self._discovery.mode == DiscoveryMode.PEER_TO_PEER:
189
+ webhooks = {}
190
+ for name, info in self._peers.items():
191
+ base_url = info.get("base_url", "")
192
+ webhooks[name] = {
193
+ "webhook_url": f"{base_url}{self._config.webhook_path}",
194
+ "subscriptions": info.get("subscriptions", ["*"]),
195
+ }
196
+ self._publisher.set_peer_webhooks(webhooks)
197
+
198
+ async def _periodic_refresh(self) -> None:
199
+ """Periodically re-check discovery, re-register self, and refresh peers.
200
+
201
+ Re-registering each interval is what makes dynamic IPs work: if this
202
+ host's address changes (DHCP renewal, reconnect) we push the new
203
+ advertise host to the registry instead of leaving a stale, unreachable
204
+ registration behind. It also re-adds us if the health monitor pruned us
205
+ while we were briefly unreachable."""
206
+ while True:
207
+ await asyncio.sleep(self._config.discovery_interval)
208
+ try:
209
+ old_mode = self._discovery.mode
210
+ new_mode = await self._discovery.detect_mode()
211
+ if new_mode != old_mode:
212
+ logger.info(
213
+ f"Mode changed: {old_mode.value} -> {new_mode.value}"
214
+ )
215
+ self._publisher._mode = new_mode
216
+ if new_mode == DiscoveryMode.REGISTRY:
217
+ prev = self._advertised_host
218
+ await self._register_self() # heartbeat / IP refresh
219
+ if prev and prev != self._advertised_host:
220
+ logger.info(
221
+ f"Advertise host changed {prev} -> {self._advertised_host}; "
222
+ "re-registered with the new address"
223
+ )
224
+ await self._refresh_peers()
225
+ except Exception as e:
226
+ logger.debug(f"Periodic refresh error: {e}")
227
+
228
+ @staticmethod
229
+ def _get_local_ip() -> str:
230
+ try:
231
+ s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
232
+ s.connect(("8.8.8.8", 80))
233
+ ip = s.getsockname()[0]
234
+ s.close()
235
+ return ip
236
+ except Exception:
237
+ return "127.0.0.1"
@@ -0,0 +1,116 @@
1
+ """Configuration for the ecosystem client."""
2
+ from __future__ import annotations
3
+
4
+ import logging
5
+ import os
6
+ from dataclasses import dataclass, field
7
+
8
+ logger = logging.getLogger(__name__)
9
+
10
+
11
+ @dataclass
12
+ class EcosystemConfig:
13
+ """Ecosystem client configuration loaded from env vars, files, or defaults."""
14
+
15
+ registry_url: str = "http://localhost:8500"
16
+ # Fail-closed: no default secret. A committed shared secret is a forgeable
17
+ # credential. Unset => outbound requests are signed with an empty key and
18
+ # rejected by peers (who require a real secret), which is the safe outcome.
19
+ hmac_secret: str = ""
20
+ service_name: str | None = None
21
+ service_port: int | None = None
22
+ health_endpoint: str = "/health"
23
+ webhook_path: str = "/ecosystem/events"
24
+ enabled: bool = True
25
+ discovery_interval: int = 60
26
+ request_timeout: float = 5.0
27
+ event_retry_attempts: int = 3
28
+ event_retry_delay: float = 5.0
29
+ priority: int = 0
30
+ peers: dict[str, str] = field(default_factory=dict)
31
+ # Deployment topology (see topology.py). bind_host is where this service's
32
+ # server should listen; advertise_host is what it registers with the registry
33
+ # so peers can reach it. Defaults resolve from ECOSYSTEM_MODE.
34
+ mode: str = "local"
35
+ bind_host: str = "127.0.0.1"
36
+ advertise_host: str = "127.0.0.1"
37
+
38
+ @classmethod
39
+ def from_env(cls) -> "EcosystemConfig":
40
+ """Load config from environment variables."""
41
+ peers = {}
42
+ peers_str = os.environ.get("ECOSYSTEM_PEERS", "")
43
+ if peers_str:
44
+ for pair in peers_str.split(","):
45
+ pair = pair.strip()
46
+ if "=" in pair:
47
+ name, url = pair.split("=", 1)
48
+ peers[name.strip()] = url.strip()
49
+
50
+ enabled_str = os.environ.get("ECOSYSTEM_ENABLED", "true")
51
+ enabled = enabled_str.lower() not in ("false", "0", "no")
52
+
53
+ port_str = os.environ.get("ECOSYSTEM_SERVICE_PORT")
54
+ port = int(port_str) if port_str else None
55
+
56
+ # Resolve the shared secret the same way the rest of the ecosystem does:
57
+ # ECOSYSTEM_HMAC_SECRET env var first, then the file-backed secret at
58
+ # ~/.config/ecosystem/secret.env. The installers provision the file and
59
+ # deliberately do NOT export the env var (so no per-plist/launchctl setenv
60
+ # is needed), so a client that only checked the env var signed every
61
+ # request with an empty key and got 401'd by the registry.
62
+ hmac_secret = os.environ.get("ECOSYSTEM_HMAC_SECRET", "")
63
+ if not hmac_secret:
64
+ try:
65
+ from ecosystem_auth.tokens import get_ecosystem_secret
66
+
67
+ hmac_secret = get_ecosystem_secret()
68
+ except Exception:
69
+ # No env var, no readable file, or the known dev default: fall
70
+ # through to the empty (fail-closed) secret and warn below.
71
+ hmac_secret = cls.hmac_secret
72
+ if not hmac_secret:
73
+ logger.warning(
74
+ "No ecosystem secret found (ECOSYSTEM_HMAC_SECRET unset and no "
75
+ "readable ~/.config/ecosystem/secret.env) — outbound ecosystem "
76
+ "requests will be unsigned and rejected by peers. Run "
77
+ "`ecosystem secret generate` to provision one."
78
+ )
79
+
80
+ from .topology import advertise_host, bind_host, get_mode
81
+
82
+ return cls(
83
+ registry_url=os.environ.get("ECOSYSTEM_REGISTRY_URL", cls.registry_url),
84
+ hmac_secret=hmac_secret,
85
+ service_name=os.environ.get("ECOSYSTEM_SERVICE_NAME"),
86
+ service_port=port,
87
+ health_endpoint=os.environ.get(
88
+ "ECOSYSTEM_HEALTH_ENDPOINT", cls.health_endpoint
89
+ ),
90
+ enabled=enabled,
91
+ discovery_interval=int(
92
+ os.environ.get("ECOSYSTEM_DISCOVERY_INTERVAL", cls.discovery_interval)
93
+ ),
94
+ priority=int(os.environ.get("ECOSYSTEM_PRIORITY", "0")),
95
+ peers=peers,
96
+ mode=get_mode(),
97
+ bind_host=bind_host(),
98
+ advertise_host=advertise_host(),
99
+ )
100
+
101
+ @classmethod
102
+ def from_peers_file(cls, path: str) -> "EcosystemConfig":
103
+ """Load static peers from a YAML file."""
104
+ import yaml
105
+
106
+ config = cls()
107
+ try:
108
+ with open(path) as f:
109
+ data = yaml.safe_load(f)
110
+ for name, info in (data.get("peers") or {}).items():
111
+ host = info.get("host", "localhost")
112
+ port = info.get("port", 8000)
113
+ config.peers[name] = f"http://{host}:{port}"
114
+ except Exception:
115
+ pass
116
+ return config
@@ -0,0 +1,224 @@
1
+ """Service discovery with three-mode cascade: registry -> mDNS -> static -> standalone."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import logging
6
+ from enum import Enum
7
+ from typing import Any
8
+
9
+ import httpx
10
+
11
+ from .config import EcosystemConfig
12
+
13
+ logger = logging.getLogger(__name__)
14
+
15
+
16
+ def _require_auth():
17
+ """Import ecosystem_auth.tokens, or explain how to install it.
18
+
19
+ appecosystem-auth is now a declared dependency, so pip installs it with this
20
+ package and this branch should not fire. It remains for the cases that
21
+ bypass the resolver — a path/editable install of just this package, or the
22
+ auth package being uninstalled underneath a live environment — where the
23
+ alternative is a bare ModuleNotFoundError deep inside a signed request.
24
+ """
25
+ try:
26
+ from ecosystem_auth import tokens
27
+
28
+ return tokens
29
+ except ImportError as e:
30
+ raise ImportError(
31
+ "appecosystem-client requires the appecosystem-auth package for HMAC "
32
+ "request signing, but it is not installed. Install it with: "
33
+ "pip install appecosystem-auth"
34
+ ) from e
35
+
36
+
37
+ def _detect_resources() -> dict:
38
+ """Best-effort hardware capability report for LLM placement.
39
+
40
+ Uses ecosystem_ai's hardware probe when available; returns {} otherwise so
41
+ registration stays backward-compatible and never fails over this."""
42
+ try:
43
+ from ecosystem_ai import detect
44
+ info, tier = detect()
45
+ return {
46
+ "tier": int(tier),
47
+ "ram_gb": info.ram_gb,
48
+ "has_gpu": info.has_gpu,
49
+ "vram_gb": info.vram_gb,
50
+ "arch": info.arch,
51
+ }
52
+ except Exception:
53
+ return {}
54
+
55
+
56
+ class DiscoveryMode(str, Enum):
57
+ REGISTRY = "registry"
58
+ PEER_TO_PEER = "peer_to_peer"
59
+ STANDALONE = "standalone"
60
+
61
+
62
+ class DiscoveryManager:
63
+ """Detects operating mode and resolves peer locations."""
64
+
65
+ def __init__(self, config: EcosystemConfig):
66
+ self.config = config
67
+ self._mode: DiscoveryMode | None = None
68
+ self._peers: dict[str, dict[str, Any]] = {}
69
+ self._mdns_peers: list[dict] = []
70
+
71
+ @property
72
+ def mode(self) -> DiscoveryMode:
73
+ return self._mode or DiscoveryMode.STANDALONE
74
+
75
+ async def detect_mode(self) -> DiscoveryMode:
76
+ """Run the discovery cascade and return the detected mode."""
77
+ if not self.config.enabled:
78
+ self._mode = DiscoveryMode.STANDALONE
79
+ logger.info("Ecosystem disabled — standalone mode")
80
+ return self._mode
81
+
82
+ # 1. Check registry
83
+ if await self._check_registry():
84
+ self._mode = DiscoveryMode.REGISTRY
85
+ logger.info(f"Registry found at {self.config.registry_url} — registry mode")
86
+ return self._mode
87
+
88
+ # 2. Check mDNS
89
+ self._mdns_peers = await asyncio.to_thread(self._check_mdns)
90
+ if self._mdns_peers:
91
+ self._mode = DiscoveryMode.PEER_TO_PEER
92
+ logger.info(f"Found {len(self._mdns_peers)} peers via mDNS — peer-to-peer mode")
93
+ return self._mode
94
+
95
+ # 3. Check static peers
96
+ if self.config.peers:
97
+ self._mode = DiscoveryMode.PEER_TO_PEER
98
+ logger.info(f"Using {len(self.config.peers)} static peers — peer-to-peer mode")
99
+ return self._mode
100
+
101
+ # 4. Standalone
102
+ self._mode = DiscoveryMode.STANDALONE
103
+ logger.info("No registry or peers found — standalone mode")
104
+ return self._mode
105
+
106
+ async def get_peers(self) -> dict[str, dict[str, Any]]:
107
+ """Return discovered peers based on current mode."""
108
+ if self._mode == DiscoveryMode.REGISTRY:
109
+ services = await self._fetch_registry_services()
110
+ self._peers = {
111
+ svc["name"]: svc for svc in services
112
+ }
113
+ return self._peers
114
+
115
+ if self._mode == DiscoveryMode.PEER_TO_PEER:
116
+ # Merge mDNS and static peers
117
+ peers = {}
118
+ for mdns_peer in self._mdns_peers:
119
+ name = mdns_peer["name"]
120
+ peers[name] = {
121
+ "name": name,
122
+ "base_url": f"http://{mdns_peer['host']}:{mdns_peer['port']}",
123
+ }
124
+ for name, url in self.config.peers.items():
125
+ if name not in peers:
126
+ peers[name] = {"name": name, "base_url": url}
127
+ self._peers = peers
128
+ return self._peers
129
+
130
+ # STANDALONE
131
+ return {}
132
+
133
+ async def _check_registry(self) -> bool:
134
+ """Check if the ecosystem registry is reachable."""
135
+ try:
136
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
137
+ resp = await client.get(f"{self.config.registry_url}/health")
138
+ return resp.status_code == 200
139
+ except Exception:
140
+ return False
141
+
142
+ def _check_mdns(self) -> list[dict]:
143
+ """Scan for ecosystem services via mDNS. Returns list of peer dicts."""
144
+ try:
145
+ from registry.discovery import EcosystemDiscovery
146
+
147
+ disc = EcosystemDiscovery()
148
+ return disc.discover_services()
149
+ except ImportError:
150
+ logger.debug("mDNS discovery not available (zeroconf not installed)")
151
+ return []
152
+ except Exception as e:
153
+ logger.debug(f"mDNS discovery failed: {e}")
154
+ return []
155
+
156
+ async def _fetch_registry_services(self) -> list[dict]:
157
+ """Fetch all services from the registry, sorted by priority (highest first)."""
158
+ try:
159
+ sign_request = _require_auth().sign_request
160
+ url = f"{self.config.registry_url}/services"
161
+ headers = sign_request("GET", url, self.config.hmac_secret)
162
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
163
+ resp = await client.get(url, headers=headers)
164
+ resp.raise_for_status()
165
+ services = resp.json()
166
+ # Sort by priority descending so highest-priority peers are first
167
+ services.sort(key=lambda s: s.get("priority", 0), reverse=True)
168
+ return services
169
+ except Exception as e:
170
+ logger.warning(f"Failed to fetch services from registry: {e}")
171
+ return []
172
+
173
+ async def register_self(self, name: str, host: str | None, port: int,
174
+ health_endpoint: str, webhook_url: str | None = None,
175
+ subscriptions: list[str] | None = None,
176
+ priority: int = 0) -> bool:
177
+ """Register this service with the registry (Mode 1 only).
178
+
179
+ When ``host`` is falsy, the mode-appropriate advertise host is used
180
+ (loopback in local mode, this host's LAN IP in lan mode) so a service
181
+ never has to hardcode where it is reachable."""
182
+ if self._mode != DiscoveryMode.REGISTRY:
183
+ return False
184
+ host = host or self.config.advertise_host
185
+ try:
186
+ payload = {
187
+ "name": name,
188
+ "host": host,
189
+ "port": port,
190
+ "health_endpoint": health_endpoint,
191
+ "webhook_url": webhook_url,
192
+ "subscriptions": subscriptions or [],
193
+ "priority": priority,
194
+ "resources": _detect_resources(),
195
+ }
196
+ sign_request = _require_auth().sign_request
197
+ register_url = f"{self.config.registry_url}/register"
198
+ headers = sign_request("POST", register_url, self.config.hmac_secret, payload)
199
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
200
+ resp = await client.post(
201
+ register_url,
202
+ json=payload,
203
+ headers=headers,
204
+ )
205
+ resp.raise_for_status()
206
+ logger.info(f"Registered with ecosystem registry as '{name}'")
207
+ return True
208
+ except Exception as e:
209
+ logger.warning(f"Failed to register with registry: {e}")
210
+ return False
211
+
212
+ async def deregister_self(self, name: str) -> bool:
213
+ """Deregister this service from the registry (Mode 1 only)."""
214
+ if self._mode != DiscoveryMode.REGISTRY:
215
+ return False
216
+ try:
217
+ url = f"{self.config.registry_url}/deregister/{name}"
218
+ sign_request = _require_auth().sign_request
219
+ headers = sign_request("DELETE", url, self.config.hmac_secret)
220
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
221
+ resp = await client.delete(url, headers=headers)
222
+ return resp.status_code < 400
223
+ except Exception:
224
+ return False
@@ -0,0 +1,144 @@
1
+ """Publish events to the ecosystem via bus (Mode 1) or direct webhooks (Mode 2)."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import logging
6
+ import time
7
+ import uuid
8
+ from typing import Any
9
+
10
+ import httpx
11
+
12
+ from .config import EcosystemConfig
13
+ from .discovery import DiscoveryMode
14
+ from .match import matches_pattern
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+
19
+ class EventPublisher:
20
+ """Publishes events with mode-appropriate delivery."""
21
+
22
+ def __init__(self, config: EcosystemConfig, mode: DiscoveryMode, service_name: str):
23
+ self.config = config
24
+ self._mode = mode
25
+ self._service_name = service_name
26
+ self._peer_webhooks: dict[str, dict[str, Any]] = {}
27
+
28
+ def set_peer_webhooks(self, webhooks: dict[str, dict[str, Any]]) -> None:
29
+ """Set peer webhook URLs and subscriptions (Mode 2)."""
30
+ self._peer_webhooks = webhooks
31
+
32
+ async def publish(self, event_type: str, data: dict[str, Any]) -> dict:
33
+ """Publish an event. Behavior depends on discovery mode."""
34
+ if self._mode == DiscoveryMode.STANDALONE:
35
+ return {"delivered": 0, "failed": 0, "mode": "standalone"}
36
+
37
+ envelope = self._build_envelope(event_type, data)
38
+
39
+ if self._mode == DiscoveryMode.REGISTRY:
40
+ return await self._publish_via_registry(envelope)
41
+
42
+ return await self._publish_direct(envelope)
43
+
44
+ def _build_envelope(self, event_type: str, data: dict[str, Any]) -> dict:
45
+ """Build a signed event envelope."""
46
+ from ecosystem_auth.tokens import sign_payload
47
+
48
+ envelope = {
49
+ "id": str(uuid.uuid4()),
50
+ "type": event_type,
51
+ "source": self._service_name,
52
+ "timestamp": time.time(),
53
+ "data": data,
54
+ }
55
+ signable = {
56
+ "id": envelope["id"],
57
+ "type": envelope["type"],
58
+ "source": envelope["source"],
59
+ "timestamp": envelope["timestamp"],
60
+ "data": envelope["data"],
61
+ }
62
+ envelope["signature"] = sign_payload(signable, self.config.hmac_secret)
63
+ return envelope
64
+
65
+ async def _publish_via_registry(self, envelope: dict) -> dict:
66
+ """Publish by POSTing to the registry's event bus endpoint."""
67
+ try:
68
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
69
+ resp = await client.post(
70
+ f"{self.config.registry_url}/events/publish",
71
+ json=envelope,
72
+ headers={
73
+ "X-Ecosystem-Signature": envelope.get("signature", ""),
74
+ "X-Ecosystem-Event": envelope["type"],
75
+ "X-Ecosystem-Source": envelope["source"],
76
+ },
77
+ )
78
+ resp.raise_for_status()
79
+ return resp.json()
80
+ except Exception as e:
81
+ # Throttle: a persistently slow/unreachable registry would otherwise
82
+ # log one warning PER event (motion can fire many per second). Warn at
83
+ # most once per 60s and demote the rest to debug so logs don't flood.
84
+ # Use {e!r} — some exceptions (e.g. httpx.ReadTimeout('')) have an
85
+ # EMPTY str(), which previously logged a blank, unhelpful reason.
86
+ now = time.monotonic()
87
+ if now - getattr(self, "_last_publish_warn", 0.0) >= 60.0:
88
+ self._last_publish_warn = now
89
+ logger.warning(f"Failed to publish via registry: {e!r}")
90
+ else:
91
+ logger.debug(f"Failed to publish via registry: {e!r}")
92
+ return {"delivered": 0, "failed": 1, "error": str(e)}
93
+
94
+ async def _publish_direct(self, envelope: dict) -> dict:
95
+ """Publish directly to matching peer webhooks (Mode 2)."""
96
+ matching = self._get_matching_peers(envelope["type"])
97
+ if not matching:
98
+ return {"delivered": 0, "failed": 0, "subscribers": []}
99
+
100
+ tasks = [
101
+ self._deliver_to_peer(envelope, name, info["webhook_url"])
102
+ for name, info in matching.items()
103
+ ]
104
+ results = await asyncio.gather(*tasks, return_exceptions=True)
105
+
106
+ delivered = sum(1 for r in results if r is True)
107
+ failed = len(results) - delivered
108
+ return {
109
+ "delivered": delivered,
110
+ "failed": failed,
111
+ "subscribers": list(matching.keys()),
112
+ }
113
+
114
+ async def _deliver_to_peer(self, envelope: dict, name: str, webhook_url: str) -> bool:
115
+ """Deliver event to a single peer with retry."""
116
+ headers = {
117
+ "Content-Type": "application/json",
118
+ "X-Ecosystem-Signature": envelope.get("signature", ""),
119
+ "X-Ecosystem-Event": envelope["type"],
120
+ "X-Ecosystem-Source": envelope["source"],
121
+ }
122
+ for attempt in range(1, self.config.event_retry_attempts + 1):
123
+ try:
124
+ async with httpx.AsyncClient(timeout=self.config.request_timeout) as client:
125
+ resp = await client.post(webhook_url, json=envelope, headers=headers)
126
+ if resp.status_code < 400:
127
+ return True
128
+ except Exception:
129
+ pass
130
+ if attempt < self.config.event_retry_attempts:
131
+ await asyncio.sleep(self.config.event_retry_delay)
132
+
133
+ logger.warning(f"Failed to deliver event to {name} after {self.config.event_retry_attempts} attempts")
134
+ return False
135
+
136
+ def _get_matching_peers(self, event_type: str) -> dict[str, dict]:
137
+ """Filter peers whose subscriptions match the event type."""
138
+ matching = {}
139
+ for name, info in self._peer_webhooks.items():
140
+ for pattern in info.get("subscriptions", []):
141
+ if matches_pattern(event_type, pattern):
142
+ matching[name] = info
143
+ break
144
+ return matching
@@ -0,0 +1,77 @@
1
+ """Event subscriber that receives webhooks and dispatches to registered handlers."""
2
+ from __future__ import annotations
3
+
4
+ import logging
5
+ from collections import defaultdict
6
+ from typing import Any, Callable, Coroutine
7
+
8
+ from .match import matches_pattern
9
+
10
+ logger = logging.getLogger(__name__)
11
+
12
+ HandlerFunc = Callable[[dict[str, Any]], Coroutine[Any, Any, None]]
13
+
14
+
15
+ class EventSubscriber:
16
+ """Receives and dispatches ecosystem events."""
17
+
18
+ def __init__(self, hmac_secret: str):
19
+ self._hmac_secret = hmac_secret
20
+ self._handlers: dict[str, list[HandlerFunc]] = defaultdict(list)
21
+
22
+ def on(self, event_pattern: str, handler: HandlerFunc | None = None):
23
+ """Register an event handler. Works as a method or decorator."""
24
+ if handler is not None:
25
+ self._handlers[event_pattern].append(handler)
26
+ return handler
27
+
28
+ def decorator(fn: HandlerFunc) -> HandlerFunc:
29
+ self._handlers[event_pattern].append(fn)
30
+ return fn
31
+ return decorator
32
+
33
+ async def dispatch(self, envelope: dict[str, Any]) -> None:
34
+ """Verify signature and dispatch event to matching handlers."""
35
+ if not self._verify_envelope(envelope):
36
+ logger.warning(
37
+ f"Rejected event {envelope.get('id', '?')}: invalid signature"
38
+ )
39
+ return
40
+
41
+ event_type = envelope.get("type", "")
42
+ handlers = self._get_matching_handlers(event_type)
43
+ for handler in handlers:
44
+ try:
45
+ await handler(envelope)
46
+ except Exception as e:
47
+ logger.error(f"Handler error for {event_type}: {e}")
48
+
49
+ def _verify_envelope(self, envelope: dict[str, Any]) -> bool:
50
+ """Verify the HMAC signature on an event envelope."""
51
+ from ecosystem_auth.tokens import verify_signature
52
+
53
+ signature = envelope.get("signature")
54
+ if not signature:
55
+ return False
56
+
57
+ signable = {
58
+ "id": envelope.get("id", ""),
59
+ "type": envelope.get("type", ""),
60
+ "source": envelope.get("source", ""),
61
+ "timestamp": envelope.get("timestamp", 0),
62
+ "data": envelope.get("data", {}),
63
+ }
64
+ return verify_signature(signable, signature, self._hmac_secret)
65
+
66
+ def _get_matching_handlers(self, event_type: str) -> list[HandlerFunc]:
67
+ """Find all handlers whose pattern matches the event type."""
68
+ matched = []
69
+ for pattern, handlers in self._handlers.items():
70
+ if matches_pattern(event_type, pattern):
71
+ matched.extend(handlers)
72
+ return matched
73
+
74
+ @property
75
+ def subscriptions(self) -> list[str]:
76
+ """Return list of event patterns this subscriber is listening for."""
77
+ return list(self._handlers.keys())
@@ -0,0 +1,47 @@
1
+ """Standard logging handler that broadcasts natively via EcosystemClient."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import logging
7
+ from typing import TYPE_CHECKING
8
+ import json
9
+
10
+ if TYPE_CHECKING:
11
+ from . import EcosystemClient
12
+
13
+ class EcosystemLogHandler(logging.Handler):
14
+ """
15
+ A persistent logging handler that aggregates Python logging logs seamlessly
16
+ into the Ecosystem SIEM pipeline by natively broadcasting to 'log.<service_name>'.
17
+ Cross-platform macOS and Linux compatible.
18
+ """
19
+
20
+ def __init__(self, client: EcosystemClient, loop: asyncio.AbstractEventLoop = None):
21
+ super().__init__()
22
+ self.client = client
23
+ self.loop = loop or asyncio.get_event_loop()
24
+
25
+ def emit(self, record: logging.LogRecord) -> None:
26
+ """Route standard formatting structures via SIEM broadcast payload natively."""
27
+ if record.levelno < logging.WARNING:
28
+ return
29
+
30
+ try:
31
+ msg = self.format(record)
32
+ payload = {
33
+ "app": self.client._service_name,
34
+ "level": record.levelname,
35
+ "message": msg,
36
+ "source_file": record.filename,
37
+ "line_no": record.lineno,
38
+ }
39
+ topic = f"log.{self.client._service_name}"
40
+
41
+ # Since logging is essentially synchronous globally, wrap the emit safely into the ecosystem's threaded async pipeline
42
+ if self.loop.is_running():
43
+ asyncio.run_coroutine_threadsafe(self.client.publish(topic, payload), self.loop)
44
+ else:
45
+ self.loop.run_until_complete(self.client.publish(topic, payload))
46
+ except Exception:
47
+ self.handleError(record)
@@ -0,0 +1,20 @@
1
+ def matches_pattern(event_type: str, pattern: str) -> bool:
2
+ """
3
+ Decide whether an event type matches a subscription pattern.
4
+
5
+ Supported patterns: "*" (everything), "prefix.*" (that namespace), or an exact
6
+ event type.
7
+
8
+ An empty event type or an empty pattern never matches. This is a guard, not a
9
+ nicety: matches_pattern drives delivery routing, and "" previously matched the
10
+ "*" subscription, so a malformed event with no type was fanned out to every
11
+ wildcard subscriber in the ecosystem. Refusing to route it keeps a publisher bug
12
+ from becoming everyone's problem.
13
+ """
14
+ if not event_type or not pattern:
15
+ return False
16
+ if pattern == "*":
17
+ return True
18
+ if pattern.endswith(".*"):
19
+ return event_type.startswith(pattern[:-2] + ".")
20
+ return event_type == pattern
@@ -0,0 +1,81 @@
1
+ """Peer wrapper for direct API calls with HMAC authentication."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import logging
6
+ import time
7
+ from typing import Any
8
+
9
+ import httpx
10
+
11
+ logger = logging.getLogger(__name__)
12
+
13
+
14
+ class Peer:
15
+ """Represents a discovered ecosystem peer service."""
16
+
17
+ def __init__(self, name: str, base_url: str, hmac_secret: str,
18
+ timeout: float = 5.0):
19
+ self.name = name
20
+ self.base_url = base_url.rstrip("/")
21
+ self._hmac_secret = hmac_secret
22
+ self._timeout = timeout
23
+ self._degraded = False
24
+ self._cached_token = None
25
+ self._token_refresh_at = 0
26
+
27
+ @property
28
+ def is_degraded(self) -> bool:
29
+ return self._degraded
30
+
31
+ def mark_degraded(self) -> None:
32
+ self._degraded = True
33
+ logger.warning(f"Peer '{self.name}' marked as degraded")
34
+
35
+ def mark_healthy(self) -> None:
36
+ self._degraded = False
37
+
38
+ def _auth_headers(self) -> dict[str, str]:
39
+ """Generate HMAC auth headers for the request with token caching."""
40
+ now = int(time.time())
41
+ if not self._cached_token or now > self._token_refresh_at:
42
+ from ecosystem_auth.tokens import create_ecosystem_token
43
+ self._cached_token = create_ecosystem_token(self._hmac_secret, self.name)
44
+ self._token_refresh_at = now + (12 * 3600) # Refresh at 12h
45
+ return {
46
+ "Authorization": f"Bearer {json.dumps(self._cached_token)}",
47
+ "X-Ecosystem-Source": self.name,
48
+ }
49
+
50
+ async def get(self, path: str, **kwargs: Any) -> Any | None:
51
+ """Make an authenticated GET request to this peer."""
52
+ return await self._request("GET", path, **kwargs)
53
+
54
+ async def post(self, path: str, **kwargs: Any) -> Any | None:
55
+ """Make an authenticated POST request to this peer."""
56
+ return await self._request("POST", path, **kwargs)
57
+
58
+ async def put(self, path: str, **kwargs: Any) -> Any | None:
59
+ """Make an authenticated PUT request to this peer."""
60
+ return await self._request("PUT", path, **kwargs)
61
+
62
+ async def delete(self, path: str, **kwargs: Any) -> Any | None:
63
+ """Make an authenticated DELETE request to this peer."""
64
+ return await self._request("DELETE", path, **kwargs)
65
+
66
+ async def _request(self, method: str, path: str, **kwargs: Any) -> Any | None:
67
+ """Execute an HTTP request with auth and error handling."""
68
+ url = f"{self.base_url}{path}"
69
+ headers = kwargs.pop("headers", {})
70
+ headers.update(self._auth_headers())
71
+
72
+ try:
73
+ async with httpx.AsyncClient(timeout=self._timeout) as client:
74
+ resp = await client.request(method, url, headers=headers, **kwargs)
75
+ resp.raise_for_status()
76
+ self.mark_healthy()
77
+ return resp.json()
78
+ except Exception as e:
79
+ self.mark_degraded()
80
+ logger.warning(f"Request to {self.name} ({method} {url}) failed: {e}")
81
+ return None
@@ -0,0 +1,114 @@
1
+ """Deployment-topology resolution shared by every ecosystem app.
2
+
3
+ The same code base runs in two shapes:
4
+
5
+ * ``local`` (default) — every service runs on one machine. Services bind to and
6
+ are advertised on loopback (``127.0.0.1``). Nothing is exposed on the network;
7
+ health checks and peer calls stay on the host.
8
+ * ``lan`` — services are spread across devices on a trusted LAN. Services bind to
9
+ all interfaces (``0.0.0.0``) and are *advertised* on this host's real LAN IP so
10
+ peers and the registry can reach them.
11
+
12
+ The critical distinction is **bind host** (where a server listens) vs **advertise
13
+ host** (the address other services should use to reach it). Conflating the two is
14
+ what made MagicMirror register as ``192.168.50.73`` while actually listening on
15
+ IPv6 ``::1`` — health checks then failed. Mode is selected with
16
+ ``ECOSYSTEM_MODE=local|lan`` and individual values can always be overridden.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import logging
21
+ import os
22
+ import socket
23
+
24
+ logger = logging.getLogger(__name__)
25
+
26
+ LOCAL = "local"
27
+ LAN = "lan"
28
+ _VALID_MODES = (LOCAL, LAN)
29
+
30
+ _LOOPBACK = "127.0.0.1"
31
+ _ALL_INTERFACES = "0.0.0.0"
32
+
33
+
34
+ def get_mode() -> str:
35
+ """Return the deployment mode (``local`` or ``lan``); defaults to ``local``."""
36
+ mode = os.environ.get("ECOSYSTEM_MODE", LOCAL).strip().lower()
37
+ if mode not in _VALID_MODES:
38
+ logger.warning("Unknown ECOSYSTEM_MODE=%r — falling back to %r", mode, LOCAL)
39
+ return LOCAL
40
+ return mode
41
+
42
+
43
+ def is_lan() -> bool:
44
+ return get_mode() == LAN
45
+
46
+
47
+ def detect_lan_ip() -> str:
48
+ """Best-effort detection of this host's primary LAN IPv4 address.
49
+
50
+ Opens a UDP socket toward a public address (no packets are actually sent) and
51
+ reads back the local address the OS would route through. Falls back to
52
+ loopback when there is no usable route, so this never raises.
53
+ """
54
+ override = os.environ.get("ECOSYSTEM_ADVERTISE_HOST", "").strip()
55
+ if override:
56
+ return override
57
+ sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
58
+ try:
59
+ sock.connect(("8.8.8.8", 80))
60
+ ip = sock.getsockname()[0]
61
+ if ip and not ip.startswith("127."):
62
+ return ip
63
+ except OSError:
64
+ pass
65
+ finally:
66
+ sock.close()
67
+ # No route off-box — fall back to a resolvable hostname address, then loopback.
68
+ try:
69
+ ip = socket.gethostbyname(socket.gethostname())
70
+ if ip and not ip.startswith("127."):
71
+ return ip
72
+ except OSError:
73
+ pass
74
+ return _LOOPBACK
75
+
76
+
77
+ def bind_host() -> str:
78
+ """Address a server should bind/listen on for the current mode.
79
+
80
+ ``ECOSYSTEM_BIND_HOST`` overrides; otherwise loopback in local mode and all
81
+ interfaces in LAN mode."""
82
+ override = os.environ.get("ECOSYSTEM_BIND_HOST", "").strip()
83
+ if override:
84
+ return override
85
+ return _ALL_INTERFACES if is_lan() else _LOOPBACK
86
+
87
+
88
+ def advertise_host() -> str:
89
+ """Address peers/registry should use to reach this service.
90
+
91
+ ``ECOSYSTEM_ADVERTISE_HOST`` overrides; otherwise loopback in local mode and
92
+ the detected LAN IP in LAN mode."""
93
+ override = os.environ.get("ECOSYSTEM_ADVERTISE_HOST", "").strip()
94
+ if override:
95
+ return override
96
+ return detect_lan_ip() if is_lan() else _LOOPBACK
97
+
98
+
99
+ def is_loopback(host: str) -> bool:
100
+ """True when ``host`` names this machine's loopback interface."""
101
+ h = (host or "").strip().lower()
102
+ return h in ("localhost", "127.0.0.1", "::1", "ip6-localhost")
103
+
104
+
105
+ def resolve_static_host(host: str) -> str:
106
+ """Resolve a host from static config (e.g. ecosystem.yaml) for the current mode.
107
+
108
+ Loopback placeholders in committed config are single-host defaults; in LAN
109
+ mode a co-located static service should be advertised on the real LAN IP so
110
+ other devices can reach it. Non-loopback hosts (an explicit remote address)
111
+ are returned unchanged."""
112
+ if is_lan() and is_loopback(host):
113
+ return advertise_host()
114
+ return host or _LOOPBACK