Repository navigation
Expand file tree
/
Copy pathapi.py
More file actions
477 lines (415 loc) · 17.8 KB
/
Copy pathapi.py
File metadata and controls
477 lines (415 loc) · 17.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
"""Async TCP client and UART stream parser for nbe_v16."""
from __future__ import annotations
import asyncio
import re
from dataclasses import dataclass, field
from ipaddress import ip_address
from typing import TYPE_CHECKING
from urllib.parse import parse_qs, urlparse
from .const import (
CONF_RAW_TCP_BIND,
CONF_RAW_TCP_CLIENTS,
CONF_RAW_TCP_ENABLED,
CONF_RAW_TCP_PORT,
CONNECT_TIMEOUT,
LOGGER,
MEASUREMENT_MAX_AGE,
READ_TIMEOUT,
RECONNECT_DELAY,
)
if TYPE_CHECKING:
from .coordinator import NbeDataUpdateCoordinator
# Marker that separates UART frames inside the TCP stream
_FRAME_MARKER = b"???"
# Local safety bound, not a protocol maximum: even 256 Z-value fields at
# 32 bytes each need only 8 KiB, versus 107 fields in the passive capture.
# Allow additional header/noise headroom without accepting unbounded frames.
_MAX_FRAME_BYTES = 32 * 1024
_READ_CHUNK_BYTES = 4096
# Regex to extract a GET request line from a raw UART line.
# The EP20 Telnet port prepends Telnet IAC bytes and sometimes a "login:"
# prompt prefix before the actual HTTP request string. This pattern
# extracts the first occurrence of "GET /v16dev/..." regardless of leading garbage.
_GET_RE = re.compile(r"GET (/v16dev/\S+) HTTP/[0-9]+\.[0-9]+[ \t]*$")
# EP20 endpoint that carries operational Z-value data
_ENDPOINT_OPR = "/v16dev/opr.php"
# EP20 endpoints that are intentionally ignored
_ENDPOINTS_IGNORED = {"/v16dev/events2.php", "/v16dev/setup.php"}
# Keep wire keys unchanged (e.g. z02 and z000); sensor scaling uses integers.
_Z_KEY_RE = re.compile(r"z[0-9]+")
_Z_VALUE_RE = re.compile(r"[+-]?[0-9]+")
# Per-client application queue: at most 64 KiB plus one 4 KiB send.
_RAW_QUEUE_CHUNKS = 16
_RAW_MAX_CLIENTS = 4
_RAW_DRAIN_TIMEOUT = 5.0
def raw_tcp_settings(options: dict) -> tuple[str, int, frozenset[str]]:
"""Validate explicit local addresses; never resolve names or bind wildcards."""
bind = ip_address(options.get(CONF_RAW_TCP_BIND, "127.0.0.1"))
port = int(options.get(CONF_RAW_TCP_PORT, 2323))
clients = frozenset(
str(ip_address(value.strip()))
for value in options.get(CONF_RAW_TCP_CLIENTS, "127.0.0.1").split(",")
)
if not clients or len(clients) > 16 or not 1024 <= port <= 65535:
raise ValueError("Invalid raw TCP port or client list")
for address in (bind, *(ip_address(value) for value in clients)):
if (not address.is_private or address.is_unspecified
or address.is_multicast or (address.is_reserved and not address.is_loopback)
or getattr(address, "scope_id", None)):
raise ValueError("Raw TCP requires explicit private or loopback IPs")
return str(bind), port, clients
async def validate_raw_tcp_listener(bind: str, port: int) -> None:
"""Check whether the endpoint can be bound without accepting clients."""
server = await asyncio.start_server(
lambda _reader, writer: writer.close(), bind, port, start_serving=False
)
server.close()
await server.wait_closed()
@dataclass(eq=False)
class _RawPeer:
reader: asyncio.StreamReader
writer: asyncio.StreamWriter
queue: asyncio.Queue[bytes] = field(
default_factory=lambda: asyncio.Queue(_RAW_QUEUE_CHUNKS)
)
task: asyncio.Task[None] | None = None
synchronized: bool = False
tail: bytes = b""
class _RawTCPForwarder:
"""One-way bounded fan-out. All socket lifecycle stays in this module."""
def __init__(self, allowed: frozenset[str]) -> None:
self.allowed = allowed
self.server: asyncio.Server | None = None
self.connected = False
self.peers: set[_RawPeer] = set()
self.tasks: set[asyncio.Task[None]] = set()
def accept(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
"""Reject before allocating sender tasks or buffering upstream data."""
remote = writer.get_extra_info("peername")
if (not self.connected or not remote or remote[0] not in self.allowed
or len(self.tasks) >= _RAW_MAX_CLIENTS):
# No application bytes have been queued for denied clients.
writer.close()
return
peer = _RawPeer(reader, writer)
self.peers.add(peer)
peer.task = asyncio.create_task(self._serve(peer))
self.tasks.add(peer.task)
peer.task.add_done_callback(self.tasks.discard)
def _drop(self, peer: _RawPeer) -> None:
self.peers.discard(peer)
# Discard queued transport bytes as well as the application queue.
peer.writer.transport.abort()
if peer.task is not None and not peer.task.cancelling():
peer.task.cancel()
def disconnect(self) -> None:
"""Close the current stream epoch, including queued unsent fragments."""
self.connected = False
for peer in tuple(self.peers):
self._drop(peer)
def publish(self, raw: bytes) -> None:
"""Never await downstream I/O in the upstream reader/parser path."""
for peer in tuple(self.peers):
data = raw
if not peer.synchronized:
data = peer.tail + raw
marker = data.find(_FRAME_MARKER)
if marker < 0:
peer.tail = data[-2:]
continue
# Start at the next genuine boundary, with original bytes only.
data = data[marker:]
peer.tail = b""
peer.synchronized = True
# A split marker may add two bytes to an otherwise full read.
for offset in range(0, len(data), _READ_CHUNK_BYTES):
try:
peer.queue.put_nowait(data[offset:offset + _READ_CHUNK_BYTES])
except asyncio.QueueFull:
self._drop(peer)
break
async def _serve(self, peer: _RawPeer) -> None:
async def send() -> None:
while True:
peer.writer.write(await peer.queue.get())
await asyncio.wait_for(peer.writer.drain(), _RAW_DRAIN_TIMEOUT)
# EOF or even a single incoming byte ends the one-way socket.
incoming = asyncio.create_task(peer.reader.read(1))
sender = asyncio.create_task(send())
try:
done, _ = await asyncio.wait(
(incoming, sender), return_when=asyncio.FIRST_COMPLETED
)
for task in done:
task.result()
except (OSError, TimeoutError):
pass
finally:
self.peers.discard(peer)
incoming.cancel()
sender.cancel()
await asyncio.gather(incoming, sender, return_exceptions=True)
peer.writer.close()
try:
await asyncio.wait_for(peer.writer.wait_closed(), 2.0)
except (OSError, TimeoutError):
peer.writer.transport.abort()
async def stop(self) -> None:
# wait_closed() waits for active connections, so close peers first.
if self.server is not None:
self.server.close()
self.disconnect()
await asyncio.gather(*tuple(self.tasks), return_exceptions=True)
if self.server is not None:
await self.server.wait_closed()
self.server = None
class EP20Client:
"""Persistent async TCP client that reads the EP20 UART stream.
Connects to the EP20 Telnet port and forwards parsed Z-value payloads
to the coordinator via async_set_updated_data(). Read-only: nothing
is ever written to the TCP connection.
"""
def __init__(
self,
host: str,
port: int,
coordinator: NbeDataUpdateCoordinator,
) -> None:
"""Initialize the TCP client."""
self._host = host
self._port = port
self._coordinator = coordinator
self._running = False
self._stop_event = asyncio.Event()
self._writer: asyncio.StreamWriter | None = None
self._data_timeout: asyncio.TimerHandle | None = None
self._connection_lost = False
self._forwarder: _RawTCPForwarder | None = None
async def start_forwarding(self, options: dict) -> tuple[str, int] | None:
"""Open an explicitly enabled raw TCP listener before starting the reader."""
if not options.get(CONF_RAW_TCP_ENABLED, False):
return None
bind, port, allowed = raw_tcp_settings(options)
forwarder = _RawTCPForwarder(allowed)
forwarder.server = await asyncio.start_server(
forwarder.accept, bind, port, limit=1024
)
self._forwarder = forwarder
return bind, port
async def run(self) -> None:
"""Connect to the EP20 and read the UART stream indefinitely.
Reconnects automatically after a TCP disconnect. Stops only when
stop() has been called. CancelledError propagates immediately so
that HA can shut down without delay.
"""
self._running = True
self._stop_event.clear()
while self._running:
try:
await self._connect_and_read()
if self._running:
error = ConnectionError("EP20 stream closed")
self._invalidate_data(error)
self._report_connection_lost(error)
except asyncio.CancelledError:
self._invalidate_data(ConnectionError("EP20 reader cancelled"))
LOGGER.debug("NBE V16: TCP reader task cancelled")
raise
except Exception as err: # noqa: BLE001
self._invalidate_data(err)
if not self._running:
break
self._report_connection_lost(err)
if self._running:
try:
await asyncio.wait_for(
self._stop_event.wait(), timeout=RECONNECT_DELAY
)
except TimeoutError:
pass
except asyncio.CancelledError:
self._invalidate_data(ConnectionError("EP20 reader cancelled"))
raise
def _report_connection_lost(self, error: Exception) -> None:
"""Report one warning per TCP outage, with retry details at DEBUG."""
if self._connection_lost:
LOGGER.debug(
"NBE V16: TCP retry failed for %s:%s (%s)",
self._host,
self._port,
error,
)
return
self._connection_lost = True
LOGGER.warning(
"NBE V16: TCP connection to %s:%s lost (%s) - reconnecting in %ds",
self._host,
self._port,
error,
RECONNECT_DELAY,
)
async def stop(self) -> None:
"""Signal the reader loop to stop and close the TCP connection.
Closing the writer causes the pending reader.read() to return
immediately with an empty bytes object, which unblocks the read loop
so the subsequent task.cancel() / await completes without delay.
"""
self._running = False
self._stop_event.set()
self._invalidate_data(ConnectionError("EP20 reader stopped"), planned_stop=True)
if self._forwarder is not None:
await self._forwarder.stop()
self._forwarder = None
if self._writer is not None:
try:
self._writer.close()
await asyncio.wait_for(self._writer.wait_closed(), timeout=2.0)
except Exception: # noqa: BLE001
pass
self._writer = None
def _invalidate_data(self, error: Exception, *, planned_stop: bool = False) -> None:
"""Mark measurements unavailable without replacing the last payload."""
if self._data_timeout is not None:
self._data_timeout.cancel()
self._data_timeout = None
if planned_stop:
self._coordinator.async_set_stopped(error)
else:
self._coordinator.async_set_update_error(error)
def _expire_data(self) -> None:
"""Expire measurements even when unrelated stream traffic continues."""
self._invalidate_data(TimeoutError("EP20 measurements are stale"))
async def _connect_and_read(self) -> None:
"""Read bounded UART frames and resynchronize after oversized input.
A marker completes a frame immediately. Clean EOF also accepts a
complete request; timeout, reset and cancellation discard any remainder.
"""
LOGGER.debug(
"NBE V16: Connecting to EP20 at %s:%s", self._host, self._port
)
reader, writer = await asyncio.wait_for(
asyncio.open_connection(self._host, self._port),
timeout=CONNECT_TIMEOUT,
)
self._writer = writer
if self._forwarder is not None:
self._forwarder.connected = True
if self._connection_lost:
LOGGER.info(
"NBE V16: TCP connection to %s:%s restored",
self._host,
self._port,
)
self._connection_lost = False
LOGGER.debug(
"NBE V16: Connected to EP20 at %s:%s - reading stream",
self._host,
self._port,
)
buffer = b""
discarding = False
try:
while self._running:
raw = await asyncio.wait_for(
reader.read(_READ_CHUNK_BYTES), timeout=READ_TIMEOUT
)
if not raw:
LOGGER.debug(
"NBE V16: TCP connection closed by EP20 (%s:%s)",
self._host,
self._port,
)
break
if self._forwarder is not None:
self._forwarder.publish(raw)
buffer += raw
while _FRAME_MARKER in buffer:
frame, buffer = buffer.split(_FRAME_MARKER, 1)
if not discarding:
if len(frame) <= _MAX_FRAME_BYTES:
self._process_frame(
frame.decode("ascii", errors="replace").splitlines()
)
else:
LOGGER.warning("NBE V16: oversized UART frame discarded")
discarding = False
# Two trailing bytes may be the start of a split marker and
# therefore do not yet count towards the frame size.
if len(buffer) > _MAX_FRAME_BYTES + len(_FRAME_MARKER) - 1:
if not discarding:
LOGGER.warning("NBE V16: oversized UART frame discarded")
discarding = True
if discarding:
buffer = buffer[-(len(_FRAME_MARKER) - 1):]
finally:
if self._forwarder is not None:
self._forwarder.disconnect()
self._writer = None
try:
writer.close()
await asyncio.wait_for(writer.wait_closed(), timeout=2.0)
except Exception: # noqa: BLE001
pass
if (
buffer
and not discarding
and len(buffer) <= _MAX_FRAME_BYTES
and self._running
):
self._process_frame(buffer.decode("ascii", errors="replace").splitlines())
def _process_frame(self, lines: list[str]) -> None:
"""Identify and parse a complete UART frame.
Each frame may contain one GET request line, optionally preceded by
Telnet IAC bytes, a 'login:' prompt, or other noise. We use a regex
to locate the GET line rather than assuming a fixed line structure.
"""
for raw_line in lines:
m = _GET_RE.search(raw_line)
if m is None:
continue
# Extract path without query string
url_part = m.group(1) # e.g. /v16dev/opr.php?mac=...
path = url_part.split("?")[0] # e.g. /v16dev/opr.php
if path == _ENDPOINT_OPR:
# Pass the full url_part directly – no need to reconstruct
# a GET line that _parse_opr_line would only parse again.
self._parse_opr_frame(url_part)
return
if path in _ENDPOINTS_IGNORED:
LOGGER.debug("NBE V16: %s frame received - ignored", path)
return
LOGGER.debug("NBE V16: unknown endpoint '%s' - ignored", path)
return
LOGGER.debug(
"NBE V16: non-GET frame skipped (%d lines)", len(lines)
)
def _parse_opr_frame(self, url_part: str) -> None:
"""Parse Z-values from an opr.php URL part and push to coordinator.
Receives the URL part directly from _process_frame(), e.g.:
/v16dev/opr.php?mac=65506&z000=502&z001=0
Only numeric Z-keys with integer raw values qualify as measurements.
Ignore frames without measurements so they cannot refresh coordinator data.
"""
params = parse_qs(urlparse(url_part).query, keep_blank_values=True)
payload: dict[str, str] = {
key: values[0]
for key, values in params.items()
if _Z_KEY_RE.fullmatch(key) and _Z_VALUE_RE.fullmatch(values[0])
}
if not payload:
LOGGER.warning(
"NBE V16: opr.php frame without valid Z-values ignored"
)
return
z_count = len(payload)
if params.get("mac") and params["mac"][0]:
payload["mac"] = params["mac"][0]
if self._data_timeout is not None:
self._data_timeout.cancel()
self._data_timeout = asyncio.get_running_loop().call_later(
MEASUREMENT_MAX_AGE, self._expire_data
)
self._coordinator.async_set_updated_data(payload)
LOGGER.debug(
"NBE V16: opr.php parsed - %d Z-values pushed to coordinator", z_count
)