ser2netweb 3.0.0__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.
Files changed (121) hide show
  1. ser2netweb/__init__.py +20 -0
  2. ser2netweb/__main__.py +6 -0
  3. ser2netweb/accounts.py +503 -0
  4. ser2netweb/cli.py +489 -0
  5. ser2netweb/clock.py +128 -0
  6. ser2netweb/config.py +4491 -0
  7. ser2netweb/console.py +181 -0
  8. ser2netweb/datalock.py +181 -0
  9. ser2netweb/engine/__init__.py +0 -0
  10. ser2netweb/engine/access.py +173 -0
  11. ser2netweb/engine/bindhint.py +115 -0
  12. ser2netweb/engine/bridge.py +1928 -0
  13. ser2netweb/engine/cluster.py +1140 -0
  14. ser2netweb/engine/modbus.py +530 -0
  15. ser2netweb/engine/modbus_gateway.py +1465 -0
  16. ser2netweb/engine/mqtt_pub.py +632 -0
  17. ser2netweb/engine/netguard.py +805 -0
  18. ser2netweb/engine/netinfo.py +199 -0
  19. ser2netweb/engine/portdiag.py +414 -0
  20. ser2netweb/engine/portlist.py +471 -0
  21. ser2netweb/engine/protocols/__init__.py +28 -0
  22. ser2netweb/engine/protocols/base.py +117 -0
  23. ser2netweb/engine/protocols/raw.py +12 -0
  24. ser2netweb/engine/protocols/rfc2217.py +586 -0
  25. ser2netweb/engine/protocols/telnet.py +172 -0
  26. ser2netweb/engine/serial_compat.py +598 -0
  27. ser2netweb/engine/serial_io.py +210 -0
  28. ser2netweb/engine/serial_link.py +414 -0
  29. ser2netweb/engine/sockopts.py +103 -0
  30. ser2netweb/engine/sparkplug.py +538 -0
  31. ser2netweb/engine/sparkplug_node.py +550 -0
  32. ser2netweb/engine/supervisor.py +533 -0
  33. ser2netweb/engine/tls.py +232 -0
  34. ser2netweb/envvars.py +57 -0
  35. ser2netweb/explain.py +117 -0
  36. ser2netweb/healthcheck.py +78 -0
  37. ser2netweb/i18n.py +110 -0
  38. ser2netweb/importer.py +550 -0
  39. ser2netweb/layout.py +118 -0
  40. ser2netweb/licences.py +86 -0
  41. ser2netweb/locale/tr.json +1569 -0
  42. ser2netweb/logsetup.py +253 -0
  43. ser2netweb/logtext.py +23 -0
  44. ser2netweb/notify.py +761 -0
  45. ser2netweb/optional.py +76 -0
  46. ser2netweb/reload.py +295 -0
  47. ser2netweb/runtime.py +762 -0
  48. ser2netweb/sdnotify.py +85 -0
  49. ser2netweb/ser2net_import.py +2001 -0
  50. ser2netweb/signins.py +98 -0
  51. ser2netweb/standalone.py +154 -0
  52. ser2netweb/state.py +1457 -0
  53. ser2netweb/storage.py +130 -0
  54. ser2netweb/textfold.py +51 -0
  55. ser2netweb/tlsreload.py +37 -0
  56. ser2netweb/watchdog.py +201 -0
  57. ser2netweb/web/__init__.py +0 -0
  58. ser2netweb/web/api.py +793 -0
  59. ser2netweb/web/auth.py +699 -0
  60. ser2netweb/web/certinfo.py +144 -0
  61. ser2netweb/web/httpguard.py +413 -0
  62. ser2netweb/web/ldap_auth.py +556 -0
  63. ser2netweb/web/oidc_auth.py +330 -0
  64. ser2netweb/web/proxy.py +398 -0
  65. ser2netweb/web/routes/__init__.py +78 -0
  66. ser2netweb/web/routes/cluster.py +669 -0
  67. ser2netweb/web/routes/common.py +359 -0
  68. ser2netweb/web/routes/console.py +451 -0
  69. ser2netweb/web/routes/forms.py +853 -0
  70. ser2netweb/web/routes/login.py +573 -0
  71. ser2netweb/web/routes/mappings.py +470 -0
  72. ser2netweb/web/routes/ops.py +374 -0
  73. ser2netweb/web/routes/settings.py +2135 -0
  74. ser2netweb/web/routes/system.py +308 -0
  75. ser2netweb/web/routes/totp.py +282 -0
  76. ser2netweb/web/selfsigned.py +129 -0
  77. ser2netweb/web/server.py +483 -0
  78. ser2netweb/web/static/app.css +327 -0
  79. ser2netweb/web/static/app.js +1102 -0
  80. ser2netweb/web/static/htmx.min.js +1 -0
  81. ser2netweb/web/static/points.js +218 -0
  82. ser2netweb/web/static/theme.js +7 -0
  83. ser2netweb/web/static/xterm-addon-fit.js +2 -0
  84. ser2netweb/web/static/xterm.css +218 -0
  85. ser2netweb/web/static/xterm.js +2 -0
  86. ser2netweb/web/templates/_cluster_body.html +109 -0
  87. ser2netweb/web/templates/_console.html +21 -0
  88. ser2netweb/web/templates/_footer.html +13 -0
  89. ser2netweb/web/templates/_login_notice.html +8 -0
  90. ser2netweb/web/templates/_macros.html +21 -0
  91. ser2netweb/web/templates/_mapping_form.html +477 -0
  92. ser2netweb/web/templates/_mapping_log.html +28 -0
  93. ser2netweb/web/templates/_mapping_traces.html +44 -0
  94. ser2netweb/web/templates/_mappings_body.html +149 -0
  95. ser2netweb/web/templates/_modbus_read.html +18 -0
  96. ser2netweb/web/templates/_ports_table.html +37 -0
  97. ser2netweb/web/templates/_serial_port_select.html +48 -0
  98. ser2netweb/web/templates/_shell.html +41 -0
  99. ser2netweb/web/templates/audit.html +55 -0
  100. ser2netweb/web/templates/base.html +77 -0
  101. ser2netweb/web/templates/dashboard.html +72 -0
  102. ser2netweb/web/templates/licenses.html +18 -0
  103. ser2netweb/web/templates/login.html +32 -0
  104. ser2netweb/web/templates/login_totp.html +23 -0
  105. ser2netweb/web/templates/settings.html +830 -0
  106. ser2netweb/web/templates/setup.html +43 -0
  107. ser2netweb/web/templates/totp.html +41 -0
  108. ser2netweb/web/totp.py +94 -0
  109. ser2netweb/winservice.py +1793 -0
  110. ser2netweb-3.0.0.dist-info/METADATA +120 -0
  111. ser2netweb-3.0.0.dist-info/RECORD +121 -0
  112. ser2netweb-3.0.0.dist-info/WHEEL +5 -0
  113. ser2netweb-3.0.0.dist-info/entry_points.txt +2 -0
  114. ser2netweb-3.0.0.dist-info/licenses/COMMERCIAL_LICENSE.md +94 -0
  115. ser2netweb-3.0.0.dist-info/licenses/LICENSE +662 -0
  116. ser2netweb-3.0.0.dist-info/licenses/NOTICE +20 -0
  117. ser2netweb-3.0.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +105 -0
  118. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/htmx.org.txt +13 -0
  119. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm-addon-fit.txt +19 -0
  120. ser2netweb-3.0.0.dist-info/licenses/tools/licenses/npm/xterm.txt +21 -0
  121. ser2netweb-3.0.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,210 @@
1
+ """Low-level async serial open/resolve helpers built on pyserial-asyncio-fast.
2
+
3
+ Kept separate from the bridge so the device-resolution and pyserial-config
4
+ mapping live in one place. ``resolve_device`` re-resolves a stable hardware
5
+ identity (VID/PID/serial) to a current device path so COMx / ttyUSB* renumbering
6
+ doesn't break a mapping across reconnects. The port class, the transport and the stream
7
+ on top of them are serial_compat's (which also holds ser2netweb's fixes for pyserial and
8
+ pyserial-asyncio-fast).
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import contextlib
14
+ import errno
15
+ import sys
16
+ import weakref
17
+ from typing import Any, Optional
18
+
19
+ from ..config import SerialSettings, identity_text, url_port, usb_identity
20
+ from . import portdiag, portlist
21
+
22
+ # StreamReader high-water for the serial side. The default (64 KB) makes the reader
23
+ # pause/resume frequently under load; we read promptly in the bridge and apply our
24
+ # own per-client backpressure, so a larger buffer keeps the serial read flowing.
25
+ SERIAL_STREAM_LIMIT = 1024 * 1024
26
+
27
+
28
+ def _match_listed(p: dict[str, Any], want: dict[str, Any]) -> bool:
29
+ """Whether port ``p`` of portlist's list (IDs as hex strings) has the USB identity
30
+ ``want`` (config.usb_identity: only known keys). A serial number is compared in any
31
+ letter case (Linux and Windows may read one adapter's apart)."""
32
+ for key in ("vid", "pid"):
33
+ if want.get(key) and (p.get(key) or "") != str(want[key]).lower():
34
+ return False
35
+ if want.get("serial_number") and (
36
+ str(p.get("serial_number") or "").casefold() != str(want["serial_number"]).casefold()):
37
+ return False
38
+ if want.get("location") and p.get("location") != want["location"]:
39
+ return False
40
+ return True
41
+
42
+
43
+ class ForeignDevice(OSError):
44
+ """The port a mapping is set to is another USB device now, and the one it is bound to is
45
+ not there: it is not opened (errno ENODEV: the state is device-missing)."""
46
+
47
+
48
+ def _enumerate() -> list[dict[str, Any]]:
49
+ """The serial ports with their USB identities, enumerated now (blocking)."""
50
+ from serial.tools import list_ports
51
+
52
+ return [portlist._normalize(p) for p in list_ports.comports()]
53
+
54
+
55
+ def resolve(settings: SerialSettings,
56
+ ports: Optional[list[dict[str, Any]]] = None) -> tuple[str, list[str]]:
57
+ """The device to open for ``settings``, and the ports that have the USB identity it is
58
+ bound to (sorted; [] for a port opened by its name). ``ports`` is portlist's list; without
59
+ it the ports are enumerated (blocking).
60
+
61
+ Of several ports with that identity (identical adapters without their own serial number,
62
+ the channels of an FT4232H), the configured port is opened when it is one of them (also
63
+ through a /dev/serial/by-id or by-path link), else the first one no other mapping of this
64
+ process has open. When no port has it and the configured port is now another USB device,
65
+ ForeignDevice is raised instead of opening that one; a configured port that is not there
66
+ or has no USB identity is opened by its name (and fails as missing when it is not
67
+ there)."""
68
+ want = usb_identity(settings.match)
69
+ if not want:
70
+ return settings.port, []
71
+ listed = _enumerate() if ports is None else ports
72
+ matches = sorted(p["device"] for p in listed if p.get("device") and _match_listed(p, want))
73
+ if matches:
74
+ mine = next((d for d in matches if portlist.same_port(settings.port, d)), None)
75
+ if mine is None:
76
+ free = [d for d in matches if not portdiag.holder(d)]
77
+ mine = (free or matches)[0]
78
+ return mine, matches
79
+ here = portlist.find(listed, settings.port, resolve=True)
80
+ if here is not None and here.get("vid"):
81
+ raise ForeignDevice(
82
+ errno.ENODEV,
83
+ f"could not open port {settings.port}: it is another USB device now "
84
+ f"({identity_text(here)}), not the one this mapping is bound to "
85
+ f"({identity_text(want)}), so it is not opened; plug that one in, or bind the "
86
+ "mapping to this one in its form")
87
+ return settings.port, []
88
+
89
+
90
+ def resolve_device(settings: SerialSettings,
91
+ ports: Optional[list[dict[str, Any]]] = None) -> str:
92
+ """The device path to open for ``settings`` (resolve)."""
93
+ return resolve(settings, ports)[0]
94
+
95
+
96
+ async def _resolve(settings: SerialSettings) -> tuple[str, list[str]]:
97
+ """resolve without blocking the event loop: from the port list the PortWatcher keeps
98
+ (fresh within a poll or two), else enumerated in a thread."""
99
+ if not settings.identity:
100
+ return settings.port, []
101
+ ports = portlist.recent()
102
+ if ports is not None:
103
+ return resolve(settings, ports)
104
+ return await asyncio.to_thread(resolve, settings)
105
+
106
+
107
+ def refuse_url(device: str) -> None:
108
+ """Raise ValueError for a port written as a URL (socket://, rfc2217://, spy://, loop://
109
+ ...): pyserial would hand it to a URL handler, which opens a network connection or a
110
+ file instead of a serial device. Edits refuse such ports (MappingConfig.validate_input);
111
+ this keeps a stored one (hand-edited, restored, older config) from ever being opened."""
112
+ if url_port(device):
113
+ raise ValueError(f"serial port {device!r} is a URL, not a serial device; "
114
+ "URL ports are not opened")
115
+
116
+
117
+ def port_settings(settings: SerialSettings) -> dict[str, Any]:
118
+ """The pyserial settings a mapping's port is opened with: baud rate, data bits, parity,
119
+ stop bits and flow control (in the order pyserial applies them)."""
120
+ return dict(
121
+ baudrate=settings.baudrate,
122
+ bytesize=settings.bytesize,
123
+ parity=settings.parity,
124
+ stopbits=settings.stopbits,
125
+ xonxoff=(settings.flowcontrol == "xonxoff"),
126
+ rtscts=(settings.flowcontrol == "rtscts"),
127
+ dsrdtr=(settings.flowcontrol == "dsrdtr"),
128
+ )
129
+
130
+
131
+ _LINE_STATES = {"on": True, "off": False} # rts_on_open / dtr_on_open; "keep": pyserial's
132
+
133
+
134
+ async def open_serial(settings: SerialSettings):
135
+ """Open the serial port asynchronously.
136
+
137
+ Returns (reader, writer, serial_instance, device_path). Raises
138
+ serial.SerialException / OSError if the device can't be opened, ValueError for a
139
+ URL port (refuse_url).
140
+
141
+ RTS / DTR set to on or off are in that state from the moment the port opens, and are
142
+ set again once it is open (pyserial skips them quietly when the port has no modem
143
+ lines, a PTY for one). A setting the port did not take (that, or RS-485 mode) does not
144
+ fail the open: open_notes(serial_instance) has it (portdiag.Note) for the caller to
145
+ report, with what else may use the port (portdiag.port_notes: the kernel console, a
146
+ login prompt). A refused RS-485 mode is also taken back, as pyserial keeps it and would
147
+ fail every later change of the port's settings with it (an RFC 2217 client's baud
148
+ rate)."""
149
+ device, matches = await _resolve(settings)
150
+ refuse_url(device) # the one place every serial port is opened
151
+ found: list[portdiag.Note] = await portdiag.about_port(device)
152
+ if len(matches) > 1 and not portlist.same_port(settings.port, device):
153
+ # a guess: identical adapters (no serial number of their own) can't be told apart
154
+ found.append(portdiag.Note("identity_shared", (
155
+ identity_text(settings.match), len(matches), device)))
156
+ kwargs: dict[str, Any] = port_settings(settings)
157
+ # `exclusive` is POSIX-only in pyserial; Windows ports are exclusive anyway.
158
+ if sys.platform != "win32":
159
+ kwargs["exclusive"] = settings.exclusive
160
+
161
+ import serial.rs485
162
+
163
+ from . import serial_compat
164
+
165
+ rts, dtr = _LINE_STATES.get(settings.rts_on_open), _LINE_STATES.get(settings.dtr_on_open)
166
+ adv = settings.advanced
167
+ keep_out = {"tiocexcl": bool(adv.tiocexcl),
168
+ "respect_uucp_locks": bool(adv.respect_uucp_locks)}
169
+ reader, writer = await serial_compat.open_stream(device, SERIAL_STREAM_LIMIT, rts=rts,
170
+ dtr=dtr, keep_out=keep_out, **kwargs)
171
+ transport: Any = writer.transport # serial_compat.Transport
172
+ ser = transport.serial
173
+
174
+ for line, want in (("RTS", rts), ("DTR", dtr)):
175
+ if want is not None:
176
+ try:
177
+ setattr(ser, line.lower(), want)
178
+ except Exception as e: # ENOTTY / EINVAL: no modem lines; Windows: refused
179
+ found.append(portdiag.Note("line", (line, want, portdiag.reason(e))))
180
+
181
+ # RS-485 (hardware/OS dependent): never fatal, so a port without it still opens
182
+ if adv.rs485_enabled:
183
+ try:
184
+ ser.rs485_mode = serial.rs485.RS485Settings(
185
+ rts_level_for_tx=adv.rs485_rts_level_for_tx,
186
+ rts_level_for_rx=not adv.rs485_rts_level_for_tx,
187
+ delay_before_tx=(adv.rs485_delay_before_tx_ms / 1000.0) or None,
188
+ delay_before_rx=(adv.rs485_delay_after_tx_ms / 1000.0) or None,
189
+ )
190
+ except Exception as e: # Linux: ENOTTY on most USB adapters; Windows: delays
191
+ with contextlib.suppress(Exception):
192
+ ser.rs485_mode = None
193
+ found.append(portdiag.Note("rs485", (portdiag.reason(e),)))
194
+
195
+ if found:
196
+ _NOTES[ser] = found
197
+ return reader, writer, ser, device
198
+
199
+
200
+ # what open_serial found about a port it opened (a setting it did not take, ...), by port
201
+ _NOTES: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
202
+
203
+
204
+ def open_notes(ser: Any) -> list[portdiag.Note]:
205
+ """What open_serial found about the open port ``ser`` (portdiag.Note), [] if nothing
206
+ (or for a port it did not open)."""
207
+ try:
208
+ return list(_NOTES.get(ser, ()))
209
+ except TypeError: # (a stand-in that can't be weakly referenced)
210
+ return []
@@ -0,0 +1,414 @@
1
+ """A mapping's serial port, kept open for as long as the mapping runs.
2
+
3
+ Shared by the transparent bridge (bridge.MappingRunner) and the Modbus gateway
4
+ (modbus_gateway.ModbusGatewayRunner), so both open, lose and reopen a port the same way.
5
+ ``SerialLink.run(session)`` opens the port (serial_io.open_serial re-resolves a stable USB
6
+ identity on every open), runs ``session(reader, writer)`` while it is open and, when the
7
+ port can't be opened or goes away, records why in the runner's status and reopens it after
8
+ a capped backoff, until the mapping stops (the runner cancels the task).
9
+
10
+ The link's state, for the runner and anything built on it:
11
+ - ``is_open`` / ``ready``: the port is open right now (``ready`` is the Event to wait on);
12
+ - ``down``: it could not be opened or went away, and is not open again yet; False until
13
+ the first attempt is over (at start-up the port may simply not be open *yet*);
14
+ - ``reader`` / ``writer`` / ``serial`` / ``device``: the open port (None / "" otherwise);
15
+ ``on_change`` (optional) is told each time ``serial`` changes: the pyserial object of
16
+ a port just opened, None when it is closed (what drives the port itself, an RFC 2217
17
+ session, follows it);
18
+ - ``status.state``: ``running`` while it is open, ``device-missing`` / ``reconnecting``
19
+ while it is not (what the dashboard, /metrics and the notifications report):
20
+ ``device-missing`` when the last open found no such device (portdiag.missing),
21
+ ``reconnecting`` otherwise (the port went away, or can't be opened for another reason);
22
+ ``status.open_failures`` / ``status.device_lost`` count failed opens and losses of the
23
+ open port (``reconnects`` both, as before); ``status.hangups`` the losses after which
24
+ the first try opened the same device again (POSIX: a hang-up, by a login prompt on
25
+ the port for one, not an unplug);
26
+ ``status.hint``: what the error of a failed open means (portdiag.explain);
27
+ ``status.warnings``: a setting the open port did not take (serial_io.open_notes),
28
+ logged when it differs from the last open's.
29
+ While the port can't be opened, the log says so once, again only when the error changes or
30
+ every FAILING_SUMMARY_S (FailureLog), and how long it was down once it opens again.
31
+ """
32
+ from __future__ import annotations
33
+
34
+ import asyncio
35
+ import contextlib
36
+ import os
37
+ import sys
38
+ import time
39
+ from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterable, Optional
40
+
41
+ from . import portdiag, portlist, serial_io
42
+
43
+ if TYPE_CHECKING:
44
+ from ..config import SerialSettings
45
+ from .bridge import RunnerStatus
46
+
47
+ # a session runs while the port is open and returns or raises once it is gone
48
+ Session = Callable[[asyncio.StreamReader, asyncio.StreamWriter], Awaitable[None]]
49
+
50
+ # closing a port: what is still waiting to be written to the device gets this long to go
51
+ # out (then it is dropped), and so does the close itself after that
52
+ SERIAL_CLOSE_TIMEOUT_S = 2.0
53
+ _SENT_POLL_S = 0.05 # how often a close looks whether the port has sent everything
54
+ # while something keeps failing in the same way (a port that can't be opened, a connect-out)
55
+ # the log says so again this often, instead of at every attempt (FailureLog)
56
+ FAILING_SUMMARY_S = 900.0
57
+
58
+
59
+ def fmt_duration(secs: float) -> str:
60
+ secs = max(0, int(secs))
61
+ h, rem = divmod(secs, 3600)
62
+ m, s = divmod(rem, 60)
63
+ if h:
64
+ return f"{h}h {m:02d}m"
65
+ if m:
66
+ return f"{m}m {s:02d}s"
67
+ return f"{s}s"
68
+
69
+
70
+ class FailureLog:
71
+ """The log lines of something tried again and again until it works (a serial port that
72
+ can't be opened, a connect-out): the first failure and each change of the error, then
73
+ the same error only every ``every`` seconds, with how many attempts failed since when;
74
+ recovered() ends it, with how long it lasted for the line that says it works again.
75
+ (A missing USB adapter used to write the same line at every retry, about 8,500 a day,
76
+ which pushed what happened first out of the log viewer within hours.)"""
77
+
78
+ def __init__(self, log: Callable[[str], None], prefix: str,
79
+ every: float = FAILING_SUMMARY_S) -> None:
80
+ self._log = log
81
+ self._prefix = prefix
82
+ self._every = every
83
+ self.error = "" # the last failure's error ("" while it works)
84
+ self.failures = 0 # failures since it last worked
85
+ self.since = 0.0 # time.time() of the first of them (the "since" it logs)
86
+ self._since_mono = 0.0 # the same by time.monotonic(): how long it was down
87
+ self._next = 0.0 # time.monotonic() of the next summary
88
+
89
+ def failed(self, error: str) -> bool:
90
+ """Count a failure and log it as said above; True when it is the first one, or
91
+ the error changed."""
92
+ now = time.monotonic()
93
+ if not self.failures:
94
+ self.since, self._since_mono = time.time(), now
95
+ self.failures += 1
96
+ new = error != self.error
97
+ self.error = error
98
+ if new:
99
+ self._log(f"{self._prefix}: {error}")
100
+ elif now >= self._next:
101
+ since = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(self.since))
102
+ self._log(f"{self._prefix}: {error} (still failing: {self.failures} attempts "
103
+ f"since {since})")
104
+ else:
105
+ return False
106
+ self._next = now + self._every
107
+ return new
108
+
109
+ def recovered(self) -> str:
110
+ """It works again: what to add to the line that says so (" (back after 5m 12s)"),
111
+ "" when nothing had failed."""
112
+ if not self.failures:
113
+ return ""
114
+ took = fmt_duration(time.monotonic() - self._since_mono) # (a clock step aside)
115
+ self.error, self.failures, self.since = "", 0, 0.0
116
+ return f" (back after {took})"
117
+
118
+
119
+ class Backoff:
120
+ """The pause between reconnect attempts: 0.5 s doubling up to ``cap`` (10 s), plus up
121
+ to 0.4 s of jitter derived from the attempt number (not an RNG). ``attempt`` counts the
122
+ attempts since the last success; reset() after one. wake() ends a pause under way (a
123
+ serial device just appeared: no need to wait up to 10 s for it)."""
124
+
125
+ def __init__(self, cap: float = 10.0) -> None:
126
+ self.cap = cap
127
+ self.attempt = 0
128
+ self._delay = 0.5
129
+ self._woken: Optional[asyncio.Event] = None # set by wake() while wait() sleeps
130
+
131
+ def reset(self) -> None:
132
+ self.attempt, self._delay = 0, 0.5
133
+
134
+ def pause(self) -> float:
135
+ """The pause before the next attempt (what wait() sleeps), counting that attempt."""
136
+ self.attempt += 1
137
+ pause = min(self._delay, self.cap) + (self.attempt % 5) * 0.1
138
+ self._delay = min(self._delay * 2, self.cap)
139
+ return pause
140
+
141
+ async def wait(self, stop: asyncio.Event) -> bool:
142
+ """Sleep before the next attempt (or until wake()); False when ``stop`` was set
143
+ meanwhile."""
144
+ pause = self.pause()
145
+ woken = self._woken = asyncio.Event()
146
+ waits = (asyncio.ensure_future(stop.wait()), asyncio.ensure_future(woken.wait()))
147
+ try:
148
+ await asyncio.wait(waits, timeout=pause, return_when=asyncio.FIRST_COMPLETED)
149
+ finally:
150
+ for w in waits:
151
+ w.cancel()
152
+ self._woken = None
153
+ return not stop.is_set()
154
+
155
+ def wake(self) -> None:
156
+ """End the pause wait() is in, if any: try again now."""
157
+ if self._woken is not None:
158
+ self._woken.set()
159
+
160
+
161
+ class SerialLink:
162
+ def __init__(self, settings: SerialSettings, status: RunnerStatus, stop: asyncio.Event,
163
+ log: Callable[[str], None],
164
+ on_change: Optional[Callable[[Any], None]] = None, owner: str = "") -> None:
165
+ self.settings = settings
166
+ self.owner = owner # the mapping's name ("mapping X has this port open")
167
+ self.status = status
168
+ self._stop = stop
169
+ self._log = log
170
+ self._on_change = on_change
171
+ self.reader: Optional[asyncio.StreamReader] = None
172
+ self.writer: Optional[asyncio.StreamWriter] = None
173
+ self.serial: Any = None # the pyserial object (an RFC2217 session drives it)
174
+ self.device = ""
175
+ self.ready = asyncio.Event()
176
+ self.down = False
177
+ self._notes = NoteLog(log)
178
+ self._failures = FailureLog(log, "serial error")
179
+ self._backoff: Optional[Backoff] = None # run()'s, while it runs
180
+ # POSIX: the open port's device number, and that of a port that went away while
181
+ # no open has failed since (a hang-up, if the first try opens the same device)
182
+ self._rdev: Optional[int] = None
183
+ self._lost_rdev: Optional[int] = None
184
+
185
+ @property
186
+ def is_open(self) -> bool:
187
+ return self.ready.is_set()
188
+
189
+ async def run(self, session: Session) -> None:
190
+ """Keep the port open until ``stop`` is set: open it, run ``session`` while it is
191
+ open, close it once the session ends, and try again after a backoff."""
192
+ backoff = self._backoff = Backoff()
193
+ self.down = False # the first attempt is under way
194
+ while not self._stop.is_set():
195
+ was_open = False
196
+ try:
197
+ reader, writer, ser, device = await serial_io.open_serial(self.settings)
198
+ was_open = True
199
+ self.attach(reader, writer, ser, device)
200
+ backoff.reset()
201
+ await session(reader, writer)
202
+ if not self._stop.is_set(): # (a session ends by raising why)
203
+ raise ConnectionError("serial EOF / device removed")
204
+ except asyncio.CancelledError:
205
+ raise
206
+ except Exception as e: # SerialException, OSError, the port went away
207
+ if not self._stop.is_set():
208
+ await self._failed(e, was_open)
209
+ finally:
210
+ await self.close()
211
+ if self._stop.is_set():
212
+ break
213
+ self.status.reconnects += 1
214
+ if not await backoff.wait(self._stop):
215
+ break
216
+
217
+ def wake(self) -> None:
218
+ """Try to open the port now if run() is waiting to try again (a serial device was
219
+ plugged in, PortWatcher saw it)."""
220
+ if self._backoff is not None and not self.is_open:
221
+ self._backoff.wake()
222
+
223
+ async def _failed(self, e: Exception, was_open: bool) -> None:
224
+ """The port could not be opened, or went away (``was_open``): say why in the status
225
+ and the log (FailureLog), and what that means."""
226
+ st = self.status
227
+ st.last_error = str(e)
228
+ if was_open:
229
+ st.device_lost += 1
230
+ st.state = "reconnecting"
231
+ self._lost_rdev = self._rdev # (no stat now: an unplug may still be under way)
232
+ else:
233
+ st.open_failures += 1
234
+ st.state = "device-missing" if portdiag.missing(e) else "reconnecting"
235
+ self._lost_rdev = None
236
+ self._failures.failed(str(e))
237
+ # (worked out at every failed open: the same error can come to mean something else,
238
+ # a user just added to the device's group needs a restart)
239
+ st.hint = None if was_open else await asyncio.to_thread(explain, e, self.settings)
240
+
241
+ def attach(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter,
242
+ serial: Any = None, device: str = "") -> None:
243
+ """Mark an open port as the link's: what run() does after each open (a test can
244
+ use it to wire up a stand-in stream pair)."""
245
+ changed = serial is not self.serial
246
+ self.reader, self.writer, self.serial, self.device = reader, writer, serial, device
247
+ self._rdev = _rdev(serial)
248
+ if self._lost_rdev is not None and self._lost_rdev == self._rdev:
249
+ # the port went away and the very next try opened the same device: hung up
250
+ # (a login prompt's vhangup, another program), not unplugged
251
+ self.status.hangups += 1
252
+ self._log("serial port was hung up while open and could be reopened at once: "
253
+ "another program may be using it (a login prompt on it?)")
254
+ self._lost_rdev = None
255
+ notes = serial_io.open_notes(serial)
256
+ hangups = self.status.hangups
257
+ hung_up = (portdiag.Note("hangups", (hangups,)),) if hangups else ()
258
+ self.status.device = device
259
+ self.status.devices = (device,) if device else ()
260
+ self.status.last_error = ""
261
+ self.status.hint = None
262
+ self.status.warnings = tuple(notes) + hung_up
263
+ self.status.state = "running"
264
+ self.down = False
265
+ self.ready.set()
266
+ portdiag.opened(serial, self.owner, device)
267
+ self._log(f"serial open: {device} @ {self.settings.compact()}"
268
+ f"{self._failures.recovered()}")
269
+ self._notes(notes)
270
+ if changed:
271
+ self._changed(serial)
272
+
273
+ async def close(self) -> None:
274
+ """Close the port if it is open; the link is down afterwards (also after an open
275
+ that failed: run() closes after every attempt)."""
276
+ self.down = True
277
+ self.ready.clear()
278
+ w, had_serial = self.writer, self.serial is not None
279
+ self.reader = self.writer = self.serial = None
280
+ self.device = ""
281
+ self.status.warnings = ()
282
+ if had_serial:
283
+ self._changed(None)
284
+ if w is not None:
285
+ await close_stream(w, self._log)
286
+
287
+ def _changed(self, serial: Any) -> None:
288
+ if self._on_change is not None:
289
+ try:
290
+ self._on_change(serial)
291
+ except Exception as e: # what follows the port must not break the link
292
+ self._log(f"serial port change not taken up: {type(e).__name__}: {e}")
293
+
294
+ async def hold_open(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
295
+ """A session for a runner that reads the port only when it needs to (the Modbus
296
+ gateway reads one reply per request): hold the port until it goes away.
297
+
298
+ The stream library reads the port from the moment it opens and closes the
299
+ connection itself on an I/O error (an unplugged USB adapter, a failed write), so a
300
+ loss is noticed here even while no request is in flight, and raised so that run()
301
+ reopens the port. A request that only times out (a silent slave) is not a loss."""
302
+ closed = asyncio.ensure_future(writer.wait_closed())
303
+ # Never cancel that task (stop() cancels this one instead): it would cancel the
304
+ # stream's own close future, which close() waits on as well.
305
+ closed.add_done_callback(_consume_error)
306
+ await asyncio.wait((closed,))
307
+ raise closed.exception() or ConnectionError("serial EOF / device removed")
308
+
309
+
310
+ def _rdev(ser: Any) -> Optional[int]:
311
+ """The device number of an open POSIX port (None elsewhere, or for a stand-in)."""
312
+ if sys.platform == "win32":
313
+ return None
314
+ try:
315
+ return os.fstat(ser.fileno()).st_rdev or None
316
+ except (AttributeError, OSError, ValueError, TypeError):
317
+ return None
318
+
319
+
320
+ def explain(e: BaseException, settings: SerialSettings) -> Optional[portdiag.Note]:
321
+ """portdiag.explain for the device ``settings`` opens (blocking: run it in a thread)."""
322
+ try:
323
+ device = serial_io.resolve_device(settings, portlist.recent())
324
+ except OSError: # (serial_io.ForeignDevice: nothing to add to its own text)
325
+ return None
326
+ return portdiag.explain(e, device)
327
+
328
+
329
+ class NoteLog:
330
+ """Logs what to know about a port just opened (portdiag.Note) when it differs from what
331
+ was logged for the last open: a port that keeps refusing RS-485 says so once, not at
332
+ every reopen."""
333
+
334
+ def __init__(self, log: Callable[[str], None]) -> None:
335
+ self._log = log
336
+ self._last: tuple = ()
337
+
338
+ def __call__(self, notes: Iterable[Any]) -> None:
339
+ notes = tuple(notes)
340
+ for note in notes:
341
+ if note not in self._last:
342
+ self._log(f"serial warning: {note.text()}")
343
+ self._last = notes
344
+
345
+
346
+ async def close_stream(writer: asyncio.StreamWriter,
347
+ log: Optional[Callable[[str], None]] = None) -> None:
348
+ """Close a serial port's stream, in at most about 2 x SERIAL_CLOSE_TIMEOUT_S.
349
+
350
+ What the port still has to send (the transport's buffer, the OS's output queue) gets
351
+ SERIAL_CLOSE_TIMEOUT_S to go out. What the device has not taken by then (CTS low, XOFF,
352
+ a PTY or virtual port nobody reads) is dropped, and ``log`` told how much. The port is
353
+ then closed at once: the stream's own graceful close waits for the OS to drain the port
354
+ (tcdrain, in an executor thread, without a time limit), which kept whoever closed it (a
355
+ mapping's stop() on a save, restart or shutdown) waiting while the device took nothing;
356
+ on some USB adapters that wait even outlived a purge of the output, and kept the
357
+ process from exiting."""
358
+ transport: Any = writer.transport
359
+ closed = asyncio.ensure_future(writer.wait_closed())
360
+ closed.add_done_callback(_consume_error)
361
+ if not transport.is_closing(): # (it is when an I/O error closed it already)
362
+ ser: Any = getattr(transport, "serial", None) # (a test's stand-in stream has none)
363
+ left = await _sent_within(transport, ser, SERIAL_CLOSE_TIMEOUT_S)
364
+ if left and not transport.is_closing():
365
+ with contextlib.suppress(Exception):
366
+ ser.reset_output_buffer() # what the OS holds: the close won't wait for it
367
+ if log is not None:
368
+ log(f"serial close: dropped {left} byte(s) the device did not take within "
369
+ f"{SERIAL_CLOSE_TIMEOUT_S:g} s")
370
+ if not transport.is_closing():
371
+ with contextlib.suppress(Exception):
372
+ transport.abort() # nothing left to send: close without the OS drain
373
+ await _done_within(closed, SERIAL_CLOSE_TIMEOUT_S)
374
+
375
+
376
+ async def sent_within(writer: asyncio.StreamWriter, seconds: float) -> int:
377
+ """Wait until an open port has sent what was written to it (the transport's buffer and
378
+ the OS's output queue), at most ``seconds``; the bytes still waiting then."""
379
+ transport: Any = writer.transport
380
+ return await _sent_within(transport, getattr(transport, "serial", None), seconds)
381
+
382
+
383
+ async def _sent_within(transport: Any, ser: Any, seconds: float) -> int:
384
+ """Wait until the port has sent what it holds, at most ``seconds`` (and only while the
385
+ transport is open); the bytes still waiting then, 0 when all is gone."""
386
+ loop = asyncio.get_running_loop()
387
+ deadline = loop.time() + seconds
388
+ while True:
389
+ left = _unsent(transport, ser)
390
+ if not left or transport.is_closing() or loop.time() >= deadline:
391
+ return left
392
+ await asyncio.sleep(_SENT_POLL_S)
393
+
394
+
395
+ def _unsent(transport: Any, ser: Any) -> int:
396
+ """Bytes the transport holds plus those in the OS's output queue (an unplugged port
397
+ answers neither: 0)."""
398
+ n = 0
399
+ with contextlib.suppress(Exception):
400
+ n += int(transport.get_write_buffer_size())
401
+ with contextlib.suppress(Exception):
402
+ n += int(ser.out_waiting or 0)
403
+ return n
404
+
405
+
406
+ async def _done_within(fut: asyncio.Future, seconds: float) -> bool:
407
+ # asyncio.wait, not wait_for: a timeout must not cancel the stream's own close future
408
+ done, _pending = await asyncio.wait((fut,), timeout=seconds)
409
+ return bool(done)
410
+
411
+
412
+ def _consume_error(fut: asyncio.Future) -> None:
413
+ if not fut.cancelled():
414
+ fut.exception() # mark it seen: it is raised (or dropped on stop), not lost