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,533 @@
1
+ """Supervisor: owns the set of MappingRunners and applies config changes.
2
+
3
+ The web layer mutates + persists the AppConfig, then calls this to reconcile the
4
+ running bridges. Editing a mapping at runtime stops the old runner (awaiting full
5
+ teardown so the listening socket is released) before starting the new one, which
6
+ avoids address-in-use / port races.
7
+
8
+ A mapping whose listener can't take its address (netguard.BindError: the port is in use,
9
+ or the address is not on this machine yet, as at boot before DHCP) stays in state "error"
10
+ and is started again after a backoff (up to BIND_RETRY_MAX_S between tries), for as long
11
+ as it is meant to run: until it starts, or it is applied, stopped or removed again. Such a
12
+ start opens nothing before its bind (bridge.MappingRunner.start), so a retry neither
13
+ pulses the serial lines nor reconnects to a broker.
14
+
15
+ The operations on one mapping (apply, restart, stop, remove, a bind retry's attempt, and
16
+ its part of start_all / stop_all) take turns: each runs to its end before the next one for
17
+ that mapping begins, so two of them can never build two runners, one of which nobody
18
+ tracks any more while it keeps the port and the serial device. Operations on different
19
+ mappings still run side by side. Given a `lookup`, an operation reads the mapping's config
20
+ when its turn comes, so one that waited (or a copy a request read earlier) can't undo a
21
+ later change.
22
+ """
23
+ from __future__ import annotations
24
+
25
+ import asyncio
26
+ import contextlib
27
+ import functools
28
+ import time
29
+ from typing import Any, Callable, Optional, Protocol
30
+
31
+ from .. import tlsreload
32
+ from ..config import AppConfig, MappingConfig, mqtt_start_warnings, mqtt_warnings
33
+ from . import bindhint, portlist, serial_io
34
+ from .bridge import MappingRunner, RunnerStatus, remove_files
35
+ from .netguard import BindError
36
+ from .serial_link import Backoff
37
+
38
+ # a runner in these states runs: the serial side retries a missing device on its own
39
+ ALIVE_STATES = ("running", "reconnecting", "device-missing")
40
+ # stop_all(): the runners stop side by side, for at most this long together; one that
41
+ # takes longer is left to finish on its own (and logged), so it can't hold up the rest
42
+ STOP_ALL_TIMEOUT_S = 15.0
43
+ # a listener that could not bind is tried again after the serial reconnect's backoff
44
+ # (0.5 s doubling), at most this many seconds apart
45
+ BIND_RETRY_MAX_S = 30.0
46
+
47
+
48
+ class Runner(Protocol):
49
+ """What the supervisor and the web layer use of a mapping's runner: the transparent
50
+ bridge (bridge.MappingRunner) or the Modbus gateway (modbus_gateway.ModbusGatewayRunner)."""
51
+
52
+ mapping: MappingConfig
53
+ status: RunnerStatus
54
+
55
+ async def start(self) -> None: ...
56
+
57
+ async def stop(self) -> None: ...
58
+
59
+ # browser console (what the device sends) and live hex view (both directions)
60
+ def add_monitor(self, mon: Any) -> None: ...
61
+
62
+ def discard_monitor(self, mon: Any) -> None: ...
63
+
64
+ def add_traffic_monitor(self, mon: Any) -> None: ...
65
+
66
+ def discard_traffic_monitor(self, mon: Any) -> None: ...
67
+
68
+ # the browser console typing to the device; False when nothing was written
69
+ async def serial_write(self, data: bytes) -> bool: ...
70
+
71
+
72
+ def make_runner(mapping: MappingConfig, logger, trace_dir: Optional[str] = None,
73
+ state_dir: Optional[str] = None) -> Runner:
74
+ """Pick the runner for a mapping: the Modbus RTU<->TCP gateway when the network
75
+ protocol is 'modbus', otherwise the transparent serial<->network bridge. ``state_dir``:
76
+ the data folder, where a runner keeps state across restarts (None: in memory only)."""
77
+ if mapping.kind == "net" and mapping.network.protocol == "modbus":
78
+ from .modbus_gateway import ModbusGatewayRunner
79
+ return ModbusGatewayRunner(mapping, logger=logger, trace_dir=trace_dir,
80
+ state_dir=state_dir)
81
+ return MappingRunner(mapping, logger=logger, trace_dir=trace_dir)
82
+
83
+
84
+ class _Unbuildable:
85
+ """Stands in for a mapping whose runner can't be built from its settings (a hand-edited
86
+ value of the wrong type), so its status says why and the rest keeps running; starting
87
+ it fails with that error."""
88
+
89
+ def __init__(self, error: Exception):
90
+ self.error = f"its settings can't be used: {error}"
91
+ self.status = RunnerStatus(state="stopped")
92
+ self._viewers: set = set() # consoles and hex views: closed when it is replaced
93
+
94
+ async def start(self) -> None:
95
+ raise RuntimeError(self.error)
96
+
97
+ async def stop(self) -> None:
98
+ for mon in list(self._viewers):
99
+ mon.close()
100
+ self._viewers.clear()
101
+
102
+ # the console and the hex view attach to any runner: there is nothing to watch or
103
+ # write to here
104
+ def add_monitor(self, mon) -> None:
105
+ self._viewers.add(mon)
106
+
107
+ def discard_monitor(self, mon) -> None:
108
+ self._viewers.discard(mon)
109
+
110
+ add_traffic_monitor = add_monitor
111
+ discard_traffic_monitor = discard_monitor
112
+
113
+ async def serial_write(self, data: bytes) -> None:
114
+ pass
115
+
116
+
117
+ def _build_runner(mapping: MappingConfig, logger, trace_dir: Optional[str],
118
+ state_dir: Optional[str] = None):
119
+ try:
120
+ return make_runner(mapping, logger, trace_dir, state_dir)
121
+ except Exception as e: # only this mapping is down
122
+ return _Unbuildable(e)
123
+
124
+
125
+ def _consume_error(task: asyncio.Future) -> None:
126
+ if not task.cancelled():
127
+ task.exception() # a runner that failed to stop: nothing more to do about it
128
+
129
+
130
+ async def _retried_start(runner: Runner, log: Callable[[str], None], backoff: Backoff) -> None:
131
+ """A bind retry's attempt (Supervisor._retry). Once the runner runs, its status stops
132
+ saying it retries and the start is logged in the same step of the event loop, not in
133
+ the next one, when the retry sees the attempt done: a status read in between said
134
+ 'running' and 'retrying' at once."""
135
+ await runner.start()
136
+ runner.status.retry_at = 0.0
137
+ log(f"started after {backoff.attempt} retr{'y' if backoff.attempt == 1 else 'ies'}")
138
+
139
+
140
+ def _name(runner: Any) -> str:
141
+ mapping = getattr(runner, "mapping", None)
142
+ return getattr(mapping, "name", None) or "?"
143
+
144
+
145
+ class Supervisor:
146
+ def __init__(self, logger: Optional[Callable[[str], None]] = None,
147
+ logger_factory: Optional[Callable[[MappingConfig], Callable[[str], None]]] = None,
148
+ trace_dir: Optional[str] = None,
149
+ lookup: Optional[Callable[[str], Optional[MappingConfig]]] = None,
150
+ state_dir: Optional[str] = None):
151
+ self._runners: dict[str, Runner] = {}
152
+ self.trace_dir = trace_dir # data/traces: the only place traces are written
153
+ self.state_dir = state_dir # data/: what runners keep across restarts (Sparkplug bdSeq)
154
+ self._order: list[str] = []
155
+ self.log = logger or (lambda m: None)
156
+ # per-mapping logger: defaults to the global logger with a "[name]" prefix
157
+ self._logger_factory = logger_factory or (
158
+ lambda mapping: (lambda msg: self.log(f"[{mapping.name}] {msg}"))
159
+ )
160
+ # a mapping's config now, by id (AppState: config.get_mapping); None: as passed
161
+ self._lookup = lookup
162
+ # each mapping's turn: id -> [lock, operations holding or waiting for it]
163
+ self._turns: dict[str, list] = {}
164
+ self._stopping: set[asyncio.Future] = set() # stop_all()'s stops still under way
165
+ # the mappings whose stop_all() stop is still under way after its time limit: their
166
+ # turn is held until it ends (start_all and remove_mapping don't wait for it)
167
+ self._late: set[str] = set()
168
+ self._retries: dict[str, asyncio.Task] = {} # mapping id -> its bind retry
169
+ self._ports: Optional[set[str]] = None # the serial ports last seen (ports_changed)
170
+
171
+ @contextlib.asynccontextmanager
172
+ async def _turn(self, mapping_id: str):
173
+ """Wait for the mapping's turn and hold it (see the module docstring). Not
174
+ re-entrant: the public methods take it, the _-helpers they share don't."""
175
+ entry = self._turns.get(mapping_id)
176
+ if entry is None:
177
+ entry = self._turns[mapping_id] = [asyncio.Lock(), 0]
178
+ entry[1] += 1
179
+ try:
180
+ async with entry[0]:
181
+ yield
182
+ finally:
183
+ entry[1] -= 1
184
+ if not entry[1]: # nobody holds or waits for it
185
+ del self._turns[mapping_id]
186
+
187
+ def _current(self, mapping: MappingConfig) -> Optional[MappingConfig]:
188
+ """The mapping's config when its turn has come: None once it was deleted."""
189
+ return mapping if self._lookup is None else self._lookup(mapping.id)
190
+
191
+ # ---------------- bulk ----------------
192
+ async def start_all(self, config: AppConfig) -> None:
193
+ """Start every enabled mapping (a placeholder runner for each disabled one), each in
194
+ its turn. A mapping whose stop_all() stop is still under way (it outlived
195
+ STOP_ALL_TIMEOUT_S) is started in the background once that stop ends, so it can't
196
+ hold up the others (an import or a restore stops all, then starts all)."""
197
+ self._order = [m.id for m in config.mappings]
198
+ # (in one pass: each against those started before it)
199
+ notes = mqtt_start_warnings(config.mappings)
200
+ for m, mqtt_notes in zip(list(config.mappings), notes, strict=True):
201
+ if m.id in self._late:
202
+ self._logger_factory(m)("start waits for the previous stop to end")
203
+ task = asyncio.ensure_future(self.apply_mapping(m, mqtt_notes))
204
+ self._stopping.add(task)
205
+ task.add_done_callback(self._stopping.discard)
206
+ task.add_done_callback(_consume_error)
207
+ continue
208
+ async with self._turn(m.id):
209
+ current = self._current(m)
210
+ if current is None:
211
+ continue # deleted meanwhile
212
+ if current.enabled:
213
+ await self._apply(current.id, current, mqtt_notes)
214
+ else:
215
+ self._ensure_stopped_placeholder(current)
216
+
217
+ async def stop_all(self) -> None:
218
+ """Stop every runner, side by side, each in its mapping's turn, waiting at most
219
+ STOP_ALL_TIMEOUT_S: a stop still under way then (a device or broker that doesn't
220
+ answer, or an operation on that mapping that doesn't end) is logged and left to
221
+ finish in the background, instead of keeping the others running (an import or a
222
+ restore stops all, then starts the new set) or the process from exiting. Loops
223
+ until no runner is left (also one an operation under way adds meanwhile)."""
224
+ loop = asyncio.get_running_loop()
225
+ deadline = loop.time() + STOP_ALL_TIMEOUT_S
226
+ while self._runners:
227
+ stops = {asyncio.ensure_future(self._stop_in_turn(mid)): (mid, _name(runner))
228
+ for mid, runner in list(self._runners.items())}
229
+ for task in stops:
230
+ self._stopping.add(task) # (a task left running must not be garbage-collected)
231
+ task.add_done_callback(self._stopping.discard)
232
+ task.add_done_callback(_consume_error)
233
+ _done, pending = await asyncio.wait(stops, timeout=max(0.0, deadline - loop.time()))
234
+ if pending:
235
+ names = ", ".join(sorted(stops[t][1] for t in pending))
236
+ self.log(f"stopping: {len(pending)} mapping(s) did not stop within "
237
+ f"{STOP_ALL_TIMEOUT_S:g} s, left to finish on their own: {names}")
238
+ for task in pending:
239
+ mid = stops[task][0]
240
+ self._late.add(mid)
241
+ task.add_done_callback(functools.partial(self._stop_ended, mid))
242
+ return
243
+
244
+ def _stop_ended(self, mapping_id: str, _task: asyncio.Future) -> None:
245
+ """A stop that outlived stop_all's limit has ended: its mapping's turn is free."""
246
+ self._late.discard(mapping_id)
247
+
248
+ async def _stop_in_turn(self, mapping_id: str) -> None:
249
+ """stop_all's part for one mapping: its bind retry ends (an attempt under way holds
250
+ the turn, so it ends first) and its runner goes."""
251
+ async with self._turn(mapping_id):
252
+ await self._cancel_retry(mapping_id)
253
+ runner = self._runners.pop(mapping_id, None)
254
+ if runner is not None:
255
+ await self._stop_runner(runner)
256
+
257
+ # ---------------- per-mapping ----------------
258
+ def _ensure_stopped_placeholder(self, mapping: MappingConfig) -> None:
259
+ """Register a non-running runner so status is queryable for disabled mappings."""
260
+ if mapping.id not in self._runners:
261
+ r = _build_runner(mapping, self._logger_factory(mapping), self.trace_dir,
262
+ self.state_dir)
263
+ r.status.state = "stopped"
264
+ self._runners[mapping.id] = r
265
+ if mapping.id not in self._order:
266
+ self._order.append(mapping.id)
267
+
268
+ async def _stop_runner(self, runner: Runner) -> None:
269
+ """Stop a runner to its end. A failure is logged (that runner may still hold its
270
+ port or device), not raised: the operation goes on."""
271
+ try:
272
+ await runner.stop()
273
+ except Exception as e:
274
+ mapping = getattr(runner, "mapping", None)
275
+ log = self._logger_factory(mapping) if mapping is not None else self.log
276
+ log(f"stopping failed: {e!r}")
277
+
278
+ async def apply_mapping(self, mapping: MappingConfig,
279
+ mqtt_notes: Optional[list[str]] = None) -> tuple[bool, str]:
280
+ """Create/replace and (if enabled) start the runner for a mapping, from its config
281
+ when its turn comes. A start that fails because the listener can't bind is tried
282
+ again later (_retry). ``mqtt_notes``: its mqtt_warnings, when the caller has them
283
+ already (start_all)."""
284
+ async with self._turn(mapping.id):
285
+ return await self._apply(mapping.id, self._current(mapping), mqtt_notes)
286
+
287
+ async def _apply(self, mapping_id: str, mapping: Optional[MappingConfig],
288
+ mqtt_notes: Optional[list[str]] = None) -> tuple[bool, str]:
289
+ """apply_mapping in the mapping's turn. None: it was deleted meanwhile, so its
290
+ runner only goes."""
291
+ await self._cancel_retry(mapping_id)
292
+ old = self._runners.pop(mapping_id, None)
293
+ if old is not None:
294
+ await self._stop_runner(old)
295
+ if mapping is None:
296
+ if mapping_id in self._order:
297
+ self._order.remove(mapping_id)
298
+ return False, "the mapping was deleted meanwhile"
299
+
300
+ log = self._logger_factory(mapping)
301
+ runner = _build_runner(mapping, log, self.trace_dir, self.state_dir)
302
+ if mapping.id not in self._order:
303
+ self._order.append(mapping.id)
304
+ self._runners[mapping.id] = runner
305
+
306
+ if not mapping.enabled:
307
+ runner.status.state = "stopped"
308
+ return True, "disabled"
309
+ # what it shares over MQTT with the other enabled mappings (which the edits refuse
310
+ # or warn about), and its own MQTT topics the edits refuse: said at each start
311
+ if mqtt_notes is None:
312
+ mqtt_notes = mqtt_warnings(mapping, [
313
+ r.mapping for mid, r in list(self._runners.items())
314
+ if mid != mapping.id and isinstance(getattr(r, "mapping", None), MappingConfig)])
315
+ for line in mqtt_notes:
316
+ log(f"warning: {line}")
317
+ try:
318
+ # a stored URL port fails the start once, instead of retrying it forever
319
+ for side in mapping.serial_sides():
320
+ serial_io.refuse_url(side.port)
321
+ await runner.start()
322
+ return True, "started"
323
+ except Exception as e:
324
+ runner.status.state = "error"
325
+ runner.status.last_error = str(e)
326
+ # why the system refused a listener's port, and what to do (None otherwise)
327
+ hint = bindhint.for_mapping(e, mapping)
328
+ runner.status.hint = bindhint.note(hint)
329
+ # all.log ("[name] ...") and the mapping's own log
330
+ if isinstance(e, BindError):
331
+ log(f"start failed: {e} — trying again until the address can be used "
332
+ f"(every {BIND_RETRY_MAX_S:g} s at most)")
333
+ self._retry_later(mapping, runner, str(e))
334
+ else:
335
+ log(f"start failed: {e}")
336
+ if hint:
337
+ log(bindhint.explain(hint))
338
+ return False, str(e)
339
+
340
+ def _retry_later(self, mapping: MappingConfig, runner: Runner, error: str) -> None:
341
+ backoff = Backoff(cap=BIND_RETRY_MAX_S)
342
+ pause = backoff.pause()
343
+ runner.status.retry_at = time.monotonic() + pause # (the status says so at once)
344
+ self._retries[mapping.id] = asyncio.create_task(
345
+ self._retry(mapping, runner, error, backoff, pause),
346
+ name=f"bind-retry:{mapping.name}")
347
+
348
+ async def _retry(self, mapping: MappingConfig, runner: Runner, error: str,
349
+ backoff: Backoff, pause: float) -> None:
350
+ """Start ``runner`` again, with a backoff, while its listener can't bind. Each
351
+ attempt runs in the mapping's turn, so no apply, stop or removal overlaps it; they
352
+ end the retry in their turn (_cancel_retry), so the runner a retry starts is
353
+ always the one tracked. Logs a changed error and the start that worked (all.log and
354
+ the mapping's own log, as apply_mapping does); any other error ends the retries."""
355
+ st = runner.status
356
+ log = self._logger_factory(mapping)
357
+ try:
358
+ while True:
359
+ st.retry_at = time.monotonic() + pause
360
+ await asyncio.sleep(pause)
361
+ async with self._turn(mapping.id):
362
+ if self._runners.get(mapping.id) is not runner:
363
+ return # (replaced or removed: that ended this retry too)
364
+ st.retry_at = time.monotonic() # trying now
365
+ # asyncio.wait, which cancels nothing: a cancelled retry (the event loop
366
+ # ending) waits for an attempt under way to end
367
+ attempt = asyncio.ensure_future(_retried_start(runner, log, backoff))
368
+ attempt.add_done_callback(_consume_error)
369
+ try:
370
+ await asyncio.wait((attempt,))
371
+ except asyncio.CancelledError:
372
+ await asyncio.wait((attempt,))
373
+ raise
374
+ e = attempt.exception()
375
+ if e is None:
376
+ return
377
+ st.state, st.last_error = "error", str(e)
378
+ hint = bindhint.for_mapping(e, mapping)
379
+ st.hint = bindhint.note(hint)
380
+ if not isinstance(e, BindError):
381
+ log(f"start failed: {e}")
382
+ return
383
+ if str(e) != error:
384
+ error = str(e)
385
+ log(f"start failed again: {e}")
386
+ if hint:
387
+ log(bindhint.explain(hint))
388
+ pause = backoff.pause()
389
+ finally:
390
+ st.retry_at = 0.0
391
+ if self._retries.get(mapping.id) is asyncio.current_task():
392
+ del self._retries[mapping.id]
393
+
394
+ async def _cancel_retry(self, mapping_id: str) -> None:
395
+ """End a mapping's bind retry before it is applied, stopped or removed: a retry
396
+ left running would undo a Stop. Called in the mapping's turn, so the retry is
397
+ waiting (its pause, or for the turn), never in the middle of an attempt."""
398
+ task = self._retries.pop(mapping_id, None)
399
+ if task is not None:
400
+ task.cancel()
401
+ with contextlib.suppress(asyncio.CancelledError):
402
+ await task
403
+
404
+ async def start_mapping(self, mapping: MappingConfig) -> tuple[bool, str]:
405
+ return await self.apply_mapping(mapping)
406
+
407
+ async def ensure_running(self, mapping: MappingConfig) -> tuple[bool, str, bool]:
408
+ """apply_mapping, unless the mapping's runner is what its config asks for already:
409
+ built from the same settings, and running (ALIVE_STATES) when it is enabled or
410
+ stopped when it is not. So a start of a running mapping keeps its clients, serial
411
+ port and MQTT connection; one that stopped or failed (also one waiting for its bind
412
+ retry) is started again. Returns (ok, message, changed): changed is False when
413
+ nothing was done."""
414
+ async with self._turn(mapping.id):
415
+ current = self._current(mapping)
416
+ runner = self._runners.get(mapping.id)
417
+ built = getattr(runner, "mapping", None)
418
+ if (current is not None and runner is not None and built is not None
419
+ and runner.status.state in (ALIVE_STATES if current.enabled else ("stopped",))
420
+ and built.to_dict() == current.to_dict()):
421
+ return True, "running" if current.enabled else "disabled", False
422
+ ok, message = await self._apply(mapping.id, current)
423
+ return ok, message, True
424
+
425
+ async def stop_mapping(self, mapping_id: str) -> bool:
426
+ """Stop a mapping's runner (kept, stopped, for its status) and its bind retry —
427
+ unless its config has it enabled by now: a start saved after this stop takes its
428
+ own turn. Returns whether a runner was stopped (False: none, or stopped already)."""
429
+ async with self._turn(mapping_id):
430
+ current = self._lookup(mapping_id) if self._lookup is not None else None
431
+ if current is not None and current.enabled:
432
+ return False
433
+ await self._cancel_retry(mapping_id)
434
+ runner = self._runners.get(mapping_id)
435
+ if runner is None or runner.status.state == "stopped":
436
+ return False
437
+ await self._stop_runner(runner)
438
+ return True
439
+
440
+ async def restart_mapping(self, mapping: MappingConfig) -> tuple[bool, str]:
441
+ return await self.apply_mapping(mapping) # which stops the old runner first
442
+
443
+ async def remove_mapping(self, mapping_id: str) -> None:
444
+ if mapping_id in self._late and mapping_id not in self._runners:
445
+ # its stop_all() stop holds the turn and has its runner: nothing left to stop
446
+ # here (an operation waiting for the turn reads the config then: it's gone)
447
+ if mapping_id in self._order:
448
+ self._order.remove(mapping_id)
449
+ return
450
+ async with self._turn(mapping_id):
451
+ await self._cancel_retry(mapping_id)
452
+ runner = self._runners.pop(mapping_id, None)
453
+ if mapping_id in self._order:
454
+ self._order.remove(mapping_id)
455
+ if runner is not None:
456
+ await self._stop_runner(runner)
457
+
458
+ async def remove_trace_files(self, mapping_id: str, paths) -> dict:
459
+ """Delete some of a mapping's trace files in its turn (so no start or stop swaps
460
+ its trace writer meanwhile). While the mapping traces, its writer deletes them
461
+ (bridge.Tracer.remove_files): never in the middle of a rotation, and the file it
462
+ writes is closed first and begun again with the next traffic. Returns path ->
463
+ None (gone) or the OSError that kept it."""
464
+ async with self._turn(mapping_id):
465
+ tracer = getattr(self._runners.get(mapping_id), "tracer", None)
466
+ done = tracer.remove_files(paths) if tracer is not None else None
467
+ if done is not None:
468
+ return await asyncio.wrap_future(done)
469
+ return await asyncio.to_thread(remove_files, paths)
470
+
471
+ async def renew_tls(self, mapping_id: str, build: Callable[[], Any]) -> Optional[str]:
472
+ """In the mapping's turn: its running TLS listener gets a context made by build()
473
+ (tlsreload.prepare) for the connections it accepts from now on; those open keep
474
+ theirs. Returns None when it has none (not running, no TLS), "" once renewed, else
475
+ why not (the context in use stays)."""
476
+ async with self._turn(mapping_id):
477
+ listener = getattr(self._runners.get(mapping_id), "listener", None)
478
+ if listener is None or listener.ssl is None:
479
+ return None
480
+ prepared = await tlsreload.prepare(build)
481
+ if not prepared.usable or prepared.context is None:
482
+ return prepared.error or prepared.later or "no TLS context"
483
+ listener.ssl = prepared.context
484
+ return ""
485
+
486
+ async def renew_traces(self, begun_before: float) -> int:
487
+ """Have every running trace whose file holds traffic from before `begun_before`
488
+ begin a new one (bridge.Tracer.renew_if_older, in its writer thread). Returns how
489
+ many did."""
490
+ waits = []
491
+ for runner in list(self._runners.values()):
492
+ tracer = getattr(runner, "tracer", None)
493
+ done = tracer.renew_if_older(begun_before) if tracer is not None else None
494
+ if done is not None:
495
+ waits.append(asyncio.wrap_future(done))
496
+ results = await asyncio.gather(*waits, return_exceptions=True)
497
+ return sum(r is True for r in results)
498
+
499
+ # ---------------- status ----------------
500
+ def get_runner(self, mapping_id: str) -> Optional[Runner]:
501
+ return self._runners.get(mapping_id)
502
+
503
+ def status(self, mapping_id: str) -> Optional[dict]:
504
+ r = self._runners.get(mapping_id)
505
+ return r.status.as_dict() if r else None
506
+
507
+ def all_status(self) -> dict[str, dict]:
508
+ # iterate a snapshot so a concurrent apply/remove can't change the dict
509
+ # mid-iteration (defensive; also future-proofs against an async as_dict)
510
+ return {mid: r.status.as_dict() for mid, r in list(self._runners.items())}
511
+
512
+ def ports_changed(self, ports: list[dict]) -> None:
513
+ """PortWatcher's on_change: when a serial port appeared, the mappings waiting to
514
+ open theirs again try now (a re-plugged adapter is used within the watcher's poll,
515
+ not after up to 10 s of backoff)."""
516
+ names = {n for p in ports for n in portlist.names(p)}
517
+ new, self._ports = (names - self._ports if self._ports is not None else names), names
518
+ if not new:
519
+ return
520
+ for r in list(self._runners.values()):
521
+ if r.status.state in ("device-missing", "reconnecting"):
522
+ wake = getattr(r, "wake_serial", None)
523
+ if wake is not None:
524
+ wake()
525
+
526
+ def devices_in_use(self) -> set[str]:
527
+ """The serial devices that running mappings hold open (for the Ports page): one per
528
+ mapping, both ports of a serial-to-serial bridge."""
529
+ out: set[str] = set()
530
+ for r in list(self._runners.values()):
531
+ if r.status.state == "running":
532
+ out.update(d for d in r.status.devices if d)
533
+ return out