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.
- appecosystem_client-0.3.1.dist-info/METADATA +112 -0
- appecosystem_client-0.3.1.dist-info/RECORD +14 -0
- appecosystem_client-0.3.1.dist-info/WHEEL +5 -0
- appecosystem_client-0.3.1.dist-info/licenses/LICENSE +21 -0
- appecosystem_client-0.3.1.dist-info/top_level.txt +1 -0
- ecosystem_client/__init__.py +237 -0
- ecosystem_client/config.py +116 -0
- ecosystem_client/discovery.py +224 -0
- ecosystem_client/event_publisher.py +144 -0
- ecosystem_client/event_subscriber.py +77 -0
- ecosystem_client/log_handler.py +47 -0
- ecosystem_client/match.py +20 -0
- ecosystem_client/peer.py +81 -0
- ecosystem_client/topology.py +114 -0
|
@@ -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,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
|
ecosystem_client/peer.py
ADDED
|
@@ -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
|