piphi-runtime-kit-python 0.9.3__py3-none-any.whl → 0.11.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.
- piphi_runtime_kit_python/__init__.py +23 -0
- piphi_runtime_kit_python/onboarding.py +34 -0
- piphi_runtime_kit_python/runtime/__init__.py +12 -0
- piphi_runtime_kit_python/runtime/errors.py +14 -0
- piphi_runtime_kit_python/runtime/network.py +33 -0
- piphi_runtime_kit_python/runtime/source_telemetry.py +251 -0
- {piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/METADATA +52 -2
- {piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/RECORD +11 -8
- {piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/WHEEL +0 -0
- {piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/entry_points.txt +0 -0
- {piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/licenses/LICENSE +0 -0
|
@@ -33,6 +33,11 @@ from .camera import (
|
|
|
33
33
|
CameraSourceResolver,
|
|
34
34
|
CameraWebRtcOffer,
|
|
35
35
|
)
|
|
36
|
+
from .onboarding import (
|
|
37
|
+
OnboardingDeclaration,
|
|
38
|
+
OnboardingMode,
|
|
39
|
+
validate_onboarding_declaration,
|
|
40
|
+
)
|
|
36
41
|
from .runtime.auth import (
|
|
37
42
|
RUNTIME_CONTAINER_ID_HEADER_NAME,
|
|
38
43
|
RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
|
|
@@ -85,6 +90,7 @@ from .runtime.errors import (
|
|
|
85
90
|
CoreDeliveryError,
|
|
86
91
|
CoreRouteNotFoundError,
|
|
87
92
|
CoreServerError,
|
|
93
|
+
CoreSourceUnavailableError,
|
|
88
94
|
CoreTimeoutError,
|
|
89
95
|
CoreUnavailableError,
|
|
90
96
|
CoreUnexpectedResponseError,
|
|
@@ -128,6 +134,7 @@ from .runtime.mqtt import (
|
|
|
128
134
|
build_source_status_topic,
|
|
129
135
|
build_source_topic_root,
|
|
130
136
|
)
|
|
137
|
+
from .runtime.network import RUNTIME_PORT_ENV_NAME, runtime_port
|
|
131
138
|
from .runtime.registry import RuntimeRegistry
|
|
132
139
|
from .runtime.starter import (
|
|
133
140
|
RuntimeStarter,
|
|
@@ -136,6 +143,12 @@ from .runtime.starter import (
|
|
|
136
143
|
)
|
|
137
144
|
from .runtime.state import RuntimeProcessState
|
|
138
145
|
from .runtime.state_service import RuntimeStateService, StateReader
|
|
146
|
+
from .runtime.source_telemetry import (
|
|
147
|
+
SourceBinding,
|
|
148
|
+
SourceTelemetryClient,
|
|
149
|
+
SourceTelemetryPage,
|
|
150
|
+
SourceTelemetryPoint,
|
|
151
|
+
)
|
|
139
152
|
from .runtime.tasks import (
|
|
140
153
|
BackgroundTaskLimitError,
|
|
141
154
|
create_tracked_task,
|
|
@@ -189,6 +202,7 @@ __all__ = [
|
|
|
189
202
|
"RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME",
|
|
190
203
|
"RUNTIME_CONTAINER_ID_HEADER_NAME",
|
|
191
204
|
"RUNTIME_INTERNAL_TOKEN_HEADER_NAME",
|
|
205
|
+
"RUNTIME_PORT_ENV_NAME",
|
|
192
206
|
"AutomationActionDefinition",
|
|
193
207
|
"AutomationActionRequest",
|
|
194
208
|
"AutomationActionResult",
|
|
@@ -218,6 +232,7 @@ __all__ = [
|
|
|
218
232
|
"CoreEventPayload",
|
|
219
233
|
"CoreRouteNotFoundError",
|
|
220
234
|
"CoreServerError",
|
|
235
|
+
"CoreSourceUnavailableError",
|
|
221
236
|
"CoreTimeoutError",
|
|
222
237
|
"CoreUnavailableError",
|
|
223
238
|
"CoreUnexpectedResponseError",
|
|
@@ -233,6 +248,8 @@ __all__ = [
|
|
|
233
248
|
"IntegrationEventRequest",
|
|
234
249
|
"MqttBrokerConfig",
|
|
235
250
|
"MqttJsonClient",
|
|
251
|
+
"OnboardingDeclaration",
|
|
252
|
+
"OnboardingMode",
|
|
236
253
|
"RuntimeAuthContext",
|
|
237
254
|
"RuntimeAuthHeaders",
|
|
238
255
|
"RuntimeConfig",
|
|
@@ -256,6 +273,10 @@ __all__ = [
|
|
|
256
273
|
"RuntimeStarter",
|
|
257
274
|
"RuntimeStateService",
|
|
258
275
|
"SQLiteAutomationIdempotencyStore",
|
|
276
|
+
"SourceBinding",
|
|
277
|
+
"SourceTelemetryClient",
|
|
278
|
+
"SourceTelemetryPage",
|
|
279
|
+
"SourceTelemetryPoint",
|
|
259
280
|
"StateReader",
|
|
260
281
|
"TelemetryClient",
|
|
261
282
|
"TelemetryPayload",
|
|
@@ -311,10 +332,12 @@ __all__ = [
|
|
|
311
332
|
"resolve_device_id",
|
|
312
333
|
"resolve_runtime_config_snapshot_path",
|
|
313
334
|
"runtime_lifespan",
|
|
335
|
+
"runtime_port",
|
|
314
336
|
"schedule_event_delivery",
|
|
315
337
|
"schedule_telemetry_delivery",
|
|
316
338
|
"shutdown_background_tasks",
|
|
317
339
|
"track_background_task",
|
|
318
340
|
"validate_typed_config",
|
|
319
341
|
"validate_typed_configs",
|
|
342
|
+
"validate_onboarding_declaration",
|
|
320
343
|
]
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Typed homeowner onboarding declarations for PiPhi manifests."""
|
|
2
|
+
|
|
3
|
+
from enum import Enum
|
|
4
|
+
from typing import Any, Mapping
|
|
5
|
+
|
|
6
|
+
from pydantic import BaseModel, ConfigDict
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class OnboardingMode(str, Enum):
|
|
10
|
+
"""The first homeowner-facing action after a package is installed."""
|
|
11
|
+
|
|
12
|
+
MANUAL = "manual"
|
|
13
|
+
DISCOVERY = "discovery"
|
|
14
|
+
ACCOUNT = "account"
|
|
15
|
+
SERVICE = "service"
|
|
16
|
+
NONE = "none"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class OnboardingDeclaration(BaseModel):
|
|
20
|
+
"""Manifest declaration consumed by PiPhi Core's setup planner."""
|
|
21
|
+
|
|
22
|
+
model_config = ConfigDict(extra="forbid")
|
|
23
|
+
|
|
24
|
+
mode: OnboardingMode
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def validate_onboarding_declaration(
|
|
28
|
+
value: OnboardingDeclaration | Mapping[str, Any],
|
|
29
|
+
) -> OnboardingDeclaration:
|
|
30
|
+
"""Validate and normalize a manifest ``onboarding`` object."""
|
|
31
|
+
|
|
32
|
+
if isinstance(value, OnboardingDeclaration):
|
|
33
|
+
return value
|
|
34
|
+
return OnboardingDeclaration.model_validate(dict(value))
|
|
@@ -39,6 +39,7 @@ from .errors import (
|
|
|
39
39
|
CoreDeliveryError,
|
|
40
40
|
CoreRouteNotFoundError,
|
|
41
41
|
CoreServerError,
|
|
42
|
+
CoreSourceUnavailableError,
|
|
42
43
|
CoreTimeoutError,
|
|
43
44
|
CoreUnavailableError,
|
|
44
45
|
CoreUnexpectedResponseError,
|
|
@@ -65,6 +66,12 @@ from .lifespan import (
|
|
|
65
66
|
from .registry import RuntimeRegistry
|
|
66
67
|
from .starter import RuntimeStarter, create_runtime_starter
|
|
67
68
|
from .state import RuntimeProcessState
|
|
69
|
+
from .source_telemetry import (
|
|
70
|
+
SourceBinding,
|
|
71
|
+
SourceTelemetryClient,
|
|
72
|
+
SourceTelemetryPage,
|
|
73
|
+
SourceTelemetryPoint,
|
|
74
|
+
)
|
|
68
75
|
from .tasks import (
|
|
69
76
|
BackgroundTaskLimitError,
|
|
70
77
|
create_tracked_task,
|
|
@@ -91,6 +98,7 @@ __all__ = [
|
|
|
91
98
|
"CoreDeliveryError",
|
|
92
99
|
"CoreRouteNotFoundError",
|
|
93
100
|
"CoreServerError",
|
|
101
|
+
"CoreSourceUnavailableError",
|
|
94
102
|
"CoreTimeoutError",
|
|
95
103
|
"CoreUnavailableError",
|
|
96
104
|
"CoreUnexpectedResponseError",
|
|
@@ -103,6 +111,10 @@ __all__ = [
|
|
|
103
111
|
"RuntimeProcessState",
|
|
104
112
|
"RuntimeRegistry",
|
|
105
113
|
"RuntimeStarter",
|
|
114
|
+
"SourceBinding",
|
|
115
|
+
"SourceTelemetryClient",
|
|
116
|
+
"SourceTelemetryPage",
|
|
117
|
+
"SourceTelemetryPoint",
|
|
106
118
|
"TelemetryClient",
|
|
107
119
|
"TelemetryReading",
|
|
108
120
|
"TelemetryValue",
|
|
@@ -58,6 +58,11 @@ class CoreUnexpectedResponseError(CoreDeliveryError):
|
|
|
58
58
|
"""Raised when PiPhi Core returns an unexpected non-success response."""
|
|
59
59
|
|
|
60
60
|
|
|
61
|
+
@dataclass(eq=False)
|
|
62
|
+
class CoreSourceUnavailableError(CoreDeliveryError):
|
|
63
|
+
"""Raised when a bound source was deleted, retired, or deactivated."""
|
|
64
|
+
|
|
65
|
+
|
|
61
66
|
def classify_core_delivery_error(
|
|
62
67
|
*,
|
|
63
68
|
exc: Exception,
|
|
@@ -104,6 +109,15 @@ def classify_core_delivery_error(
|
|
|
104
109
|
status_code=status_code,
|
|
105
110
|
timeout_seconds=timeout_seconds,
|
|
106
111
|
)
|
|
112
|
+
if status_code == 410:
|
|
113
|
+
return CoreSourceUnavailableError(
|
|
114
|
+
operation=operation,
|
|
115
|
+
url=url,
|
|
116
|
+
message="The bound PiPhi source is unavailable",
|
|
117
|
+
retryable=False,
|
|
118
|
+
status_code=status_code,
|
|
119
|
+
timeout_seconds=timeout_seconds,
|
|
120
|
+
)
|
|
107
121
|
if 500 <= status_code <= 599:
|
|
108
122
|
return CoreServerError(
|
|
109
123
|
operation=operation,
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Managed runtime network configuration helpers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from collections.abc import Mapping
|
|
7
|
+
|
|
8
|
+
RUNTIME_PORT_ENV_NAME = "PORT"
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def runtime_port(default: int, *, environ: Mapping[str, str] | None = None) -> int:
|
|
12
|
+
"""Return the Core-assigned listener port, or ``default`` outside Core.
|
|
13
|
+
|
|
14
|
+
A present but invalid ``PORT`` is a contract error. Silently falling back in
|
|
15
|
+
that case can bind a managed runtime to a port owned by another service.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
_validate_port(default, source="default")
|
|
19
|
+
environment = os.environ if environ is None else environ
|
|
20
|
+
raw = environment.get(RUNTIME_PORT_ENV_NAME)
|
|
21
|
+
if raw is None:
|
|
22
|
+
return default
|
|
23
|
+
try:
|
|
24
|
+
port = int(raw)
|
|
25
|
+
except ValueError as exc:
|
|
26
|
+
raise ValueError("PORT must be an integer between 1 and 65535") from exc
|
|
27
|
+
return _validate_port(port, source=RUNTIME_PORT_ENV_NAME)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _validate_port(port: int, *, source: str) -> int:
|
|
31
|
+
if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
|
|
32
|
+
raise ValueError(f"{source} must be an integer between 1 and 65535")
|
|
33
|
+
return port
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
"""Typed, authorized reads from Core-owned source telemetry bindings."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import AsyncIterator
|
|
6
|
+
from contextlib import asynccontextmanager
|
|
7
|
+
from datetime import datetime
|
|
8
|
+
from typing import Any, Literal, TypeVar
|
|
9
|
+
from urllib.parse import quote
|
|
10
|
+
|
|
11
|
+
import httpx
|
|
12
|
+
from pydantic import BaseModel, ConfigDict, Field, ValidationError
|
|
13
|
+
|
|
14
|
+
from .auth import RuntimeAuthContext, build_runtime_auth_headers
|
|
15
|
+
from .errors import CoreUnexpectedResponseError, classify_core_delivery_error
|
|
16
|
+
from .identity import RuntimeIdentityError
|
|
17
|
+
from .state import RuntimeProcessState
|
|
18
|
+
|
|
19
|
+
DEFAULT_CORE_BASE_URL = "http://127.0.0.1:31419"
|
|
20
|
+
DEFAULT_SOURCE_BINDINGS_PATH = "/api/v2/integrations/source-bindings"
|
|
21
|
+
DEFAULT_SOURCE_PAGE_SIZE = 100
|
|
22
|
+
MAX_SOURCE_PAGE_SIZE = 500
|
|
23
|
+
DEFAULT_TIMEOUT_SECONDS = 3.0
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class _SourceContract(BaseModel):
|
|
27
|
+
model_config = ConfigDict(extra="ignore", frozen=True)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
_SourceContractT = TypeVar("_SourceContractT", bound=_SourceContract)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class SourceBinding(_SourceContract):
|
|
34
|
+
"""One Core-authorized canonical source available to this runtime config."""
|
|
35
|
+
|
|
36
|
+
binding_id: str = Field(min_length=1)
|
|
37
|
+
binding_key: str = Field(min_length=1)
|
|
38
|
+
consumer_config_id: str = Field(min_length=1)
|
|
39
|
+
source_identity_id: str = Field(min_length=1)
|
|
40
|
+
canonical_device_id: str = Field(min_length=1)
|
|
41
|
+
source_status: Literal["active", "unavailable"]
|
|
42
|
+
stale_after_seconds: int = Field(gt=0)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class SourceTelemetryPoint(_SourceContract):
|
|
46
|
+
"""One deduplicatable metric event from a bound source."""
|
|
47
|
+
|
|
48
|
+
event_id: str = Field(min_length=1)
|
|
49
|
+
metric: str | None
|
|
50
|
+
value: float | str | None
|
|
51
|
+
value_kind: Literal["number", "string"]
|
|
52
|
+
unit: str | None
|
|
53
|
+
collected_at: datetime
|
|
54
|
+
received_at: datetime
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class SourceTelemetryPage(_SourceContract):
|
|
58
|
+
"""One bounded replay page; commit state before persisting ``next_cursor``."""
|
|
59
|
+
|
|
60
|
+
binding_id: str = Field(min_length=1)
|
|
61
|
+
canonical_device_id: str = Field(min_length=1)
|
|
62
|
+
points: list[SourceTelemetryPoint]
|
|
63
|
+
next_cursor: str = Field(min_length=1)
|
|
64
|
+
has_more: bool
|
|
65
|
+
stale: bool
|
|
66
|
+
latest_collected_at: datetime | None
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class _SourceBindingList(_SourceContract):
|
|
70
|
+
bindings: list[SourceBinding]
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class SourceTelemetryClient:
|
|
74
|
+
"""Small interface over Core source binding and durable telemetry routes.
|
|
75
|
+
|
|
76
|
+
Reads exactly one page per call. The caller owns cursor persistence so it can
|
|
77
|
+
atomically commit domain state and replay position after a restart.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
def __init__(
|
|
81
|
+
self,
|
|
82
|
+
*,
|
|
83
|
+
process_state: RuntimeProcessState,
|
|
84
|
+
core_base_url: str = DEFAULT_CORE_BASE_URL,
|
|
85
|
+
source_bindings_path: str = DEFAULT_SOURCE_BINDINGS_PATH,
|
|
86
|
+
timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
|
|
87
|
+
) -> None:
|
|
88
|
+
self.process_state = process_state
|
|
89
|
+
self.core_base_url = core_base_url
|
|
90
|
+
self.source_bindings_path = source_bindings_path
|
|
91
|
+
self.timeout_seconds = timeout_seconds
|
|
92
|
+
|
|
93
|
+
@property
|
|
94
|
+
def source_bindings_url(self) -> str:
|
|
95
|
+
return f"{self.core_base_url.rstrip('/')}{self.source_bindings_path}"
|
|
96
|
+
|
|
97
|
+
@asynccontextmanager
|
|
98
|
+
async def borrow_http_client(self) -> AsyncIterator[httpx.AsyncClient]:
|
|
99
|
+
if self.process_state.core_http_client is not None:
|
|
100
|
+
yield self.process_state.core_http_client
|
|
101
|
+
return
|
|
102
|
+
async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
|
|
103
|
+
yield client
|
|
104
|
+
|
|
105
|
+
def _auth_headers(
|
|
106
|
+
self,
|
|
107
|
+
*,
|
|
108
|
+
auth_context: RuntimeAuthContext,
|
|
109
|
+
container_id: str | None,
|
|
110
|
+
) -> dict[str, str]:
|
|
111
|
+
resolved_container_id, internal_token = auth_context.resolve(
|
|
112
|
+
container_id=container_id
|
|
113
|
+
)
|
|
114
|
+
if not resolved_container_id:
|
|
115
|
+
raise RuntimeIdentityError(
|
|
116
|
+
"Source telemetry reads require the Core-managed runtime container "
|
|
117
|
+
"identity. Synchronize RuntimeAuthContext before polling bindings."
|
|
118
|
+
)
|
|
119
|
+
return build_runtime_auth_headers(
|
|
120
|
+
container_id=resolved_container_id,
|
|
121
|
+
internal_token=internal_token,
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
async def _get_json(
|
|
125
|
+
self,
|
|
126
|
+
*,
|
|
127
|
+
url: str,
|
|
128
|
+
headers: dict[str, str],
|
|
129
|
+
params: dict[str, str | int] | None = None,
|
|
130
|
+
operation: str,
|
|
131
|
+
) -> Any:
|
|
132
|
+
async with self.borrow_http_client() as client:
|
|
133
|
+
try:
|
|
134
|
+
response = await client.get(
|
|
135
|
+
url,
|
|
136
|
+
headers=headers,
|
|
137
|
+
params=params,
|
|
138
|
+
timeout=self.timeout_seconds,
|
|
139
|
+
)
|
|
140
|
+
response.raise_for_status()
|
|
141
|
+
return response.json()
|
|
142
|
+
except (httpx.HTTPStatusError, httpx.TransportError) as exc:
|
|
143
|
+
raise classify_core_delivery_error(
|
|
144
|
+
exc=exc,
|
|
145
|
+
operation=operation,
|
|
146
|
+
url=url,
|
|
147
|
+
timeout_seconds=self.timeout_seconds,
|
|
148
|
+
) from exc
|
|
149
|
+
except ValueError as exc:
|
|
150
|
+
raise CoreUnexpectedResponseError(
|
|
151
|
+
operation=operation,
|
|
152
|
+
url=url,
|
|
153
|
+
message="PiPhi Core returned invalid source telemetry JSON",
|
|
154
|
+
retryable=False,
|
|
155
|
+
timeout_seconds=self.timeout_seconds,
|
|
156
|
+
) from exc
|
|
157
|
+
|
|
158
|
+
@staticmethod
|
|
159
|
+
def _validate_contract(
|
|
160
|
+
model: type[_SourceContractT],
|
|
161
|
+
payload: Any,
|
|
162
|
+
*,
|
|
163
|
+
operation: str,
|
|
164
|
+
url: str,
|
|
165
|
+
timeout_seconds: float,
|
|
166
|
+
) -> _SourceContractT:
|
|
167
|
+
try:
|
|
168
|
+
return model.model_validate(payload)
|
|
169
|
+
except ValidationError as exc:
|
|
170
|
+
raise CoreUnexpectedResponseError(
|
|
171
|
+
operation=operation,
|
|
172
|
+
url=url,
|
|
173
|
+
message="PiPhi Core returned an invalid source telemetry contract",
|
|
174
|
+
retryable=False,
|
|
175
|
+
timeout_seconds=timeout_seconds,
|
|
176
|
+
) from exc
|
|
177
|
+
|
|
178
|
+
async def list_bindings(
|
|
179
|
+
self,
|
|
180
|
+
*,
|
|
181
|
+
consumer_config_id: str,
|
|
182
|
+
auth_context: RuntimeAuthContext,
|
|
183
|
+
container_id: str | None = None,
|
|
184
|
+
) -> list[SourceBinding]:
|
|
185
|
+
"""Return active and unavailable canonical bindings owned by one config."""
|
|
186
|
+
normalized_config_id = str(consumer_config_id or "").strip()
|
|
187
|
+
if not normalized_config_id:
|
|
188
|
+
raise ValueError("consumer_config_id cannot be empty")
|
|
189
|
+
url = (
|
|
190
|
+
f"{self.source_bindings_url}/configs/"
|
|
191
|
+
f"{quote(normalized_config_id, safe='')}"
|
|
192
|
+
)
|
|
193
|
+
operation = "source_binding_list"
|
|
194
|
+
payload = await self._get_json(
|
|
195
|
+
url=url,
|
|
196
|
+
headers=self._auth_headers(
|
|
197
|
+
auth_context=auth_context,
|
|
198
|
+
container_id=container_id,
|
|
199
|
+
),
|
|
200
|
+
operation=operation,
|
|
201
|
+
)
|
|
202
|
+
result = self._validate_contract(
|
|
203
|
+
_SourceBindingList,
|
|
204
|
+
payload,
|
|
205
|
+
operation=operation,
|
|
206
|
+
url=url,
|
|
207
|
+
timeout_seconds=self.timeout_seconds,
|
|
208
|
+
)
|
|
209
|
+
return result.bindings
|
|
210
|
+
|
|
211
|
+
async def read_telemetry(
|
|
212
|
+
self,
|
|
213
|
+
*,
|
|
214
|
+
binding_id: str,
|
|
215
|
+
auth_context: RuntimeAuthContext,
|
|
216
|
+
cursor: str | None = None,
|
|
217
|
+
limit: int = DEFAULT_SOURCE_PAGE_SIZE,
|
|
218
|
+
container_id: str | None = None,
|
|
219
|
+
) -> SourceTelemetryPage:
|
|
220
|
+
"""Read one page without mutating caller-owned replay state."""
|
|
221
|
+
normalized_binding_id = str(binding_id or "").strip()
|
|
222
|
+
if not normalized_binding_id:
|
|
223
|
+
raise ValueError("binding_id cannot be empty")
|
|
224
|
+
if not 1 <= limit <= MAX_SOURCE_PAGE_SIZE:
|
|
225
|
+
raise ValueError("limit must be between 1 and 500")
|
|
226
|
+
url = (
|
|
227
|
+
f"{self.source_bindings_url}/"
|
|
228
|
+
f"{quote(normalized_binding_id, safe='')}/telemetry"
|
|
229
|
+
)
|
|
230
|
+
params: dict[str, str | int] = {"limit": limit}
|
|
231
|
+
normalized_cursor = str(cursor or "").strip()
|
|
232
|
+
if normalized_cursor:
|
|
233
|
+
params["cursor"] = normalized_cursor
|
|
234
|
+
operation = "source_telemetry_read"
|
|
235
|
+
payload = await self._get_json(
|
|
236
|
+
url=url,
|
|
237
|
+
headers=self._auth_headers(
|
|
238
|
+
auth_context=auth_context,
|
|
239
|
+
container_id=container_id,
|
|
240
|
+
),
|
|
241
|
+
params=params,
|
|
242
|
+
operation=operation,
|
|
243
|
+
)
|
|
244
|
+
result = self._validate_contract(
|
|
245
|
+
SourceTelemetryPage,
|
|
246
|
+
payload,
|
|
247
|
+
operation=operation,
|
|
248
|
+
url=url,
|
|
249
|
+
timeout_seconds=self.timeout_seconds,
|
|
250
|
+
)
|
|
251
|
+
return result
|
{piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/METADATA
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: piphi-runtime-kit-python
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.11.1
|
|
4
4
|
Summary: PiPhi Network runtime integration helpers
|
|
5
5
|
Keywords: piphi,runtime,integration,iot
|
|
6
6
|
Author-Email: KelvinSan <support@piphi.network>
|
|
@@ -31,12 +31,31 @@ Description-Content-Type: text/markdown
|
|
|
31
31
|
|
|
32
32
|
Small Python helpers for building PiPhi runtime integrations.
|
|
33
33
|
|
|
34
|
+
## Managed listener port
|
|
35
|
+
|
|
36
|
+
Core assigns the primary listener through `PORT`. Use `runtime_port(default)` when starting the server. The default is only for unmanaged local development; an invalid managed assignment raises an error rather than risking a collision.
|
|
37
|
+
|
|
34
38
|
This package is intentionally thin. It removes repetitive PiPhi runtime
|
|
35
39
|
plumbing without hiding the HTTP contract behind a large framework. The goal
|
|
36
40
|
is to help developers move faster while still understanding what their runtime
|
|
37
41
|
is doing.
|
|
38
42
|
|
|
39
|
-
Version `0.
|
|
43
|
+
Version `0.10.0` is the current documented baseline.
|
|
44
|
+
|
|
45
|
+
## Onboarding declarations
|
|
46
|
+
|
|
47
|
+
Runtime discovery and homeowner onboarding are separate contracts. Validate a
|
|
48
|
+
manifest's explicit first-use declaration without inferring it from `/discover`:
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
from piphi_runtime_kit_python import OnboardingMode, validate_onboarding_declaration
|
|
52
|
+
|
|
53
|
+
onboarding = validate_onboarding_declaration({"mode": OnboardingMode.MANUAL})
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The supported modes are `manual`, `discovery`, `account`, `service`, and
|
|
57
|
+
`none`. Runtime strategies such as `passive` or `mdns` belong in runtime
|
|
58
|
+
discovery metadata, not in `onboarding.mode`.
|
|
40
59
|
|
|
41
60
|
> New to PiPhi? Start with [First 15 Minutes](#first-15-minutes), then read [The Golden Path](#the-golden-path), then compare your code to the example app.
|
|
42
61
|
|
|
@@ -91,6 +110,7 @@ The SDK is meant to own the shared PiPhi runtime plumbing:
|
|
|
91
110
|
- process state
|
|
92
111
|
- background task tracking
|
|
93
112
|
- telemetry delivery to PiPhi Core
|
|
113
|
+
- authorized reads from Core-owned source telemetry bindings
|
|
94
114
|
- event delivery to PiPhi Core
|
|
95
115
|
- config sync helpers
|
|
96
116
|
- typed config validation helpers
|
|
@@ -171,6 +191,36 @@ The SDK remains intentionally thin: it validates and sends the data, while
|
|
|
171
191
|
PiPhi Core owns state-change derivation, persistence policy, and automation
|
|
172
192
|
semantics.
|
|
173
193
|
|
|
194
|
+
## Source telemetry bindings
|
|
195
|
+
|
|
196
|
+
An integration that derives monitoring state from another integration must use
|
|
197
|
+
Core's authorized source binding rather than reading the producer's storage.
|
|
198
|
+
`SourceTelemetryClient` discovers only bindings owned by the calling runtime and
|
|
199
|
+
reads committed telemetry in bounded replay pages:
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from piphi_runtime_kit_python import SourceTelemetryClient
|
|
203
|
+
|
|
204
|
+
sources = SourceTelemetryClient(process_state=starter.runtime.process_state)
|
|
205
|
+
bindings = await sources.list_bindings(
|
|
206
|
+
consumer_config_id=config.config_id,
|
|
207
|
+
auth_context=starter.runtime.auth,
|
|
208
|
+
)
|
|
209
|
+
page = await sources.read_telemetry(
|
|
210
|
+
binding_id=bindings[0].binding_id,
|
|
211
|
+
cursor=state.source_cursor,
|
|
212
|
+
limit=100,
|
|
213
|
+
auth_context=starter.runtime.auth,
|
|
214
|
+
)
|
|
215
|
+
|
|
216
|
+
# Persist derived domain state and page.next_cursor in one transaction.
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Do not persist `next_cursor` before the corresponding domain-state update is
|
|
220
|
+
durable. Reusing the previous cursor after a crash intentionally replays events;
|
|
221
|
+
deduplicate them by `SourceTelemetryPoint.event_id`. See
|
|
222
|
+
[`docs/source-telemetry.md`](docs/source-telemetry.md) for recovery semantics.
|
|
223
|
+
|
|
174
224
|
## Automation SDK
|
|
175
225
|
|
|
176
226
|
`behaviors.json` and the Automation SDK solve two different halves of the same
|
{piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/RECORD
RENAMED
|
@@ -1,32 +1,35 @@
|
|
|
1
|
-
piphi_runtime_kit_python-0.
|
|
2
|
-
piphi_runtime_kit_python-0.
|
|
3
|
-
piphi_runtime_kit_python-0.
|
|
4
|
-
piphi_runtime_kit_python-0.
|
|
5
|
-
piphi_runtime_kit_python/__init__.py,sha256=
|
|
1
|
+
piphi_runtime_kit_python-0.11.1.dist-info/METADATA,sha256=0hMxLd5isZMpF_0UY8X-JyhxWHfj5yaNyn6mkRR1xjk,39607
|
|
2
|
+
piphi_runtime_kit_python-0.11.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
|
|
3
|
+
piphi_runtime_kit_python-0.11.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
|
|
4
|
+
piphi_runtime_kit_python-0.11.1.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
|
|
5
|
+
piphi_runtime_kit_python/__init__.py,sha256=fnF7yQS0wF1_DRNWoWAjNwCd2JrJ2GD2nAaCXRlnDDc,9912
|
|
6
6
|
piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
|
|
7
7
|
piphi_runtime_kit_python/adapters/fastapi.py,sha256=4BP_Ewm2K4NmyUvhgOzCUH7-fN3JwQFRwSUVxrHptQI,3099
|
|
8
8
|
piphi_runtime_kit_python/automations.py,sha256=mDK62mo0hbsXGU48zEp-W7Q9MSzO9CsjnUEf75X6Yvw,20545
|
|
9
9
|
piphi_runtime_kit_python/camera.py,sha256=37LCMzRvP1NxCWXa4Z7WmWWRLsw92MM3CZLNscTdMe8,9093
|
|
10
10
|
piphi_runtime_kit_python/fastapi.py,sha256=xvHU19-CVDPKjmXW6nW72mpdbJEOLZzT8Twal7lCCkc,453
|
|
11
|
+
piphi_runtime_kit_python/onboarding.py,sha256=ZnCmQxb6hWp6L1RxbrqpziScnW9BONhXKapOiFu9kYo,898
|
|
11
12
|
piphi_runtime_kit_python/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
12
|
-
piphi_runtime_kit_python/runtime/__init__.py,sha256=
|
|
13
|
+
piphi_runtime_kit_python/runtime/__init__.py,sha256=hE2O11WdDc5f_i_Kdg7jNyTzrwvUEyIVVgX5r-UvAKg,4383
|
|
13
14
|
piphi_runtime_kit_python/runtime/auth.py,sha256=SDfQ1zSWR5zg3fGYMpr0Az9zkvDwgrrtcQVtyeFU0NI,4728
|
|
14
15
|
piphi_runtime_kit_python/runtime/config_sync.py,sha256=kHCCfcU8MwYU1mfODoZu7dme-7I0rjObunvxSVGqkmE,16086
|
|
15
16
|
piphi_runtime_kit_python/runtime/configuration.py,sha256=JQlpAoarKXaewUNwMXUPjHNqjWVzA-1Q5PvJwvf8LKE,3791
|
|
16
17
|
piphi_runtime_kit_python/runtime/context.py,sha256=NFBX_nPVvJUjOQk1m8k-rvz0yOm1ZdL5n9bu1i06iSM,1110
|
|
17
18
|
piphi_runtime_kit_python/runtime/discovery.py,sha256=DNqK9dTbsNpzfIqjoGXZUr2fiQlyNe565lPHJtNktns,2301
|
|
18
19
|
piphi_runtime_kit_python/runtime/dispatch.py,sha256=cEK7f4KcDFmOzFnyTyie_rPc6XNZV2VYDCQdtUhj-Og,9146
|
|
19
|
-
piphi_runtime_kit_python/runtime/errors.py,sha256=
|
|
20
|
+
piphi_runtime_kit_python/runtime/errors.py,sha256=r-o2xrTYZvvgNzuFtSI88rRY0zAdCecV5GUNYbtiMkg,4620
|
|
20
21
|
piphi_runtime_kit_python/runtime/events.py,sha256=hM67eBJzpEAwV2640nHxTeUkJPFTjVMhrzZ62x7HXG4,7849
|
|
21
22
|
piphi_runtime_kit_python/runtime/health.py,sha256=D5aGvsuIHAFCEq6tw6o0qOuRhiC-NxDpc4Tnd-8nbNI,2217
|
|
22
23
|
piphi_runtime_kit_python/runtime/identity.py,sha256=RyTIF8ZA7Kt-xmloYG9J6GuDZ_UcdPPoSA1TEqC6YKU,5098
|
|
23
24
|
piphi_runtime_kit_python/runtime/lifespan.py,sha256=fHBwM9-2OskRwRIklK1PG0f_Y77guZoL1qJ7Y4jks7g,3037
|
|
24
25
|
piphi_runtime_kit_python/runtime/mqtt.py,sha256=QC6C017stmmjD89tMFvrRyazpANuIBCN3KrYodjiTrE,6178
|
|
26
|
+
piphi_runtime_kit_python/runtime/network.py,sha256=pWQg_9VjprrDhQ5iSo7PhAW1kETFWpe7zxyj6zMg5jE,1138
|
|
25
27
|
piphi_runtime_kit_python/runtime/registry.py,sha256=nO7qoc0JVBjUhqsvAubMN0DH5hNcZmWtnVY0l-G5KN8,3418
|
|
28
|
+
piphi_runtime_kit_python/runtime/source_telemetry.py,sha256=RCWs6kjPJwl_7nW9qrN53O6ARpGiUPM0Clbt2HbEs9I,8558
|
|
26
29
|
piphi_runtime_kit_python/runtime/starter.py,sha256=0D54HeKHK1veb1F-DfgC46UkUp6B0DtJS97ga_EslJ8,7043
|
|
27
30
|
piphi_runtime_kit_python/runtime/state.py,sha256=OIwVxAzX2ErsZ2XdrWlIP5r3GHHub5y9PDtoqNDlwkQ,952
|
|
28
31
|
piphi_runtime_kit_python/runtime/state_service.py,sha256=bWxQD9JJRJsOA2k1S_TttFx4raUtAdRdfbSGCK7Z51Y,5308
|
|
29
32
|
piphi_runtime_kit_python/runtime/tasks.py,sha256=E9WoE75NQiJp3buJYexysl3NuP8HJHJ3KfaGVKLdiw0,3238
|
|
30
33
|
piphi_runtime_kit_python/runtime/telemetry.py,sha256=b08Faq0CBrTqc5MCDjRUnX0KVT-MN8n4Le_FE-b2BVo,6719
|
|
31
34
|
piphi_runtime_kit_python/schemas.py,sha256=eXb_WEEGREGTRWkhShaof9N64vlrsHhVKAJECSia_to,10435
|
|
32
|
-
piphi_runtime_kit_python-0.
|
|
35
|
+
piphi_runtime_kit_python-0.11.1.dist-info/RECORD,,
|
{piphi_runtime_kit_python-0.9.3.dist-info → piphi_runtime_kit_python-0.11.1.dist-info}/WHEEL
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|