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
ser2netweb/importer.py ADDED
@@ -0,0 +1,550 @@
1
+ """Importing mappings: parse an uploaded file, plan the change, apply it.
2
+
3
+ The web UI first shows a preview (plan_rows) and only then applies the import, in
4
+ one of two modes:
5
+ * merge — a mapping with the same id, else the same name, is updated in place
6
+ (keeping the existing id, so its log and traces stay attached; a setting
7
+ the file doesn't have — an export of an older version — keeps its current
8
+ value); the others are added; mappings not in the file stay as they are;
9
+ * replace — the file's mappings replace all current ones (the pre-v2.8 behaviour).
10
+ Either way the previous config.json is kept in data/backups/ by ConfigStore.save.
11
+
12
+ A mapping from a ser2netweb export or config.json replaces the one it updates. One from a
13
+ classic ser2net file says only part of what a mapping has here, so a merge takes only
14
+ that part from it and keeps the rest (_overlay): TLS, the bind IP or the allowed clients
15
+ set after the first import, its USB identity, RS-485, MQTT, Modbus points. The preview
16
+ lists what an update changes and what it keeps, and how each mapping will be after the
17
+ import (enabled, TLS, which clients, read-only) with its own warnings.
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import contextvars
22
+ import copy
23
+ import dataclasses
24
+ import ipaddress
25
+ import json
26
+ import re
27
+ from dataclasses import dataclass, field
28
+ from typing import Optional
29
+
30
+ from . import i18n
31
+ from .config import (
32
+ AppConfig, ConfigError, MappingConfig, ModbusPoint, _new_id, check_mqtt_clashes, host_port,
33
+ normalize_cidr,
34
+ )
35
+ from .i18n import _
36
+ from .ser2net_import import Note, looks_yaml, parse_ser2net_config
37
+
38
+ MODES = ("merge", "replace")
39
+ # An import file is read whole and its mappings are previewed and validated at once:
40
+ # limits far above any real export or config.json (and the classic parser has its own).
41
+ MAX_FILE_BYTES = 16 * 1024 * 1024
42
+ MAX_MAPPINGS = 1000
43
+ # An export or config.json nests about 6 deep. Deeper files are refused right after
44
+ # parsing: how deep the parser itself goes depends on the Python version and the stack
45
+ # (3.14 takes far deeper files), and reading a mapping recurses into its values.
46
+ MAX_DEPTH = 64
47
+
48
+
49
+ @dataclass
50
+ class ImportPlan:
51
+ source: str # what the file was, for the preview
52
+ mappings: list[MappingConfig]
53
+ warnings: list[str] = field(default_factory=list)
54
+ classic: bool = False # a classic ser2net file: a merge overlays (_overlay)
55
+ # the source and the warnings in English, for the log and the audit log (which stay
56
+ # English: parse_for_preview); empty: as `source` / `warnings`
57
+ log_source: str = ""
58
+ log_warnings: list[str] = field(default_factory=list)
59
+ # per mapping, the settings the file doesn't have (see absent_settings); a merge keeps
60
+ # their current values. Empty for a classic ser2net configuration.
61
+ absent: list[list[str]] = field(default_factory=list)
62
+
63
+ def split_warnings(self) -> tuple[list[str], list[list[str]]]:
64
+ """The warnings about the file as a whole, and those about each mapping (by its
65
+ position in `mappings`; a classic file's ser2net_import.Note knows its mapping),
66
+ which the preview shows in the mapping's row."""
67
+ general: list[str] = []
68
+ per: list[list[str]] = [[] for _m in self.mappings]
69
+ for w in self.warnings:
70
+ i = getattr(w, "mapping", None)
71
+ (per[i] if i is not None and 0 <= i < len(per) else general).append(w)
72
+ return general, per
73
+
74
+
75
+ def parse_for_preview(raw: bytes, filename: str = "") -> ImportPlan:
76
+ """parse_mappings_file, with the source and the warnings in English as well (log_*):
77
+ applying the import logs them, and the log and the audit log stay English whatever
78
+ the language of the page."""
79
+ plan = parse_mappings_file(raw, filename)
80
+ if i18n.current() == i18n.DEFAULT:
81
+ plan.log_source, plan.log_warnings = plan.source, list(plan.warnings)
82
+ else:
83
+ english = contextvars.copy_context().run(_in_english, raw, filename)
84
+ plan.log_source, plan.log_warnings = english.source, english.warnings
85
+ return plan
86
+
87
+
88
+ def _deeper_than(doc, limit: int) -> bool:
89
+ """Whether a parsed JSON document nests lists / objects more than ``limit`` deep.
90
+ Without recursion, in memory for ``limit`` levels: one iterator per open level."""
91
+ levels = [iter((doc,))]
92
+ while levels:
93
+ for value in levels[-1]:
94
+ if isinstance(value, (dict, list)):
95
+ if len(levels) > limit:
96
+ return True
97
+ levels.append(iter(value.values() if isinstance(value, dict) else value))
98
+ break
99
+ else:
100
+ levels.pop()
101
+ return False
102
+
103
+
104
+ def _in_english(raw: bytes, filename: str) -> ImportPlan:
105
+ i18n.set_language(i18n.DEFAULT) # (in a copy of the context: for this call only)
106
+ return parse_mappings_file(raw, filename)
107
+
108
+
109
+ def parse_mappings_file(raw: bytes, filename: str = "") -> ImportPlan:
110
+ """A ser2netweb mappings export ({"mappings": [...]}), a whole config.json, or a
111
+ classic ser2net configuration (ser2net.yaml of ser2net 4.x / ser2net.conf of 3.x).
112
+ Raises ConfigError with a user-facing message."""
113
+ if len(raw) > MAX_FILE_BYTES:
114
+ raise ConfigError(_("The file is larger than {0} MB.").format(MAX_FILE_BYTES // 2**20))
115
+ try:
116
+ text = raw.decode("utf-8-sig")
117
+ except UnicodeDecodeError:
118
+ raise ConfigError(_("The file is not UTF-8 text.")) from None
119
+ if not text.lstrip().startswith(("{", "[")):
120
+ return _classic_ser2net(text, filename)
121
+ try:
122
+ doc = json.loads(text)
123
+ except (ValueError, RecursionError) as e:
124
+ # where, not the parser's English words ("Expecting ',' delimiter: ...")
125
+ where = (_("line {0}, column {1}").format(e.lineno, e.colno)
126
+ if isinstance(e, json.JSONDecodeError) else
127
+ _("nested too deeply") if isinstance(e, RecursionError) else str(e))
128
+ raise ConfigError(_("The file is not valid JSON ({0}).").format(where)) from None
129
+ if _deeper_than(doc, MAX_DEPTH):
130
+ raise ConfigError(_("The file is not valid JSON ({0}).").format(
131
+ _("nested too deeply")))
132
+ if not isinstance(doc, dict) or not isinstance(doc.get("mappings"), list):
133
+ raise ConfigError(_('Expected a ser2netweb export: a JSON object with a "mappings" list.'))
134
+ if len(doc["mappings"]) > MAX_MAPPINGS:
135
+ raise ConfigError(_("The file has {0} mappings; at most {1} can be imported at once.")
136
+ .format(len(doc["mappings"]), MAX_MAPPINGS))
137
+ mappings: list[MappingConfig] = []
138
+ warnings: list[str] = []
139
+ absent: list[list[str]] = []
140
+ for i, item in enumerate(doc["mappings"], 1):
141
+ if not isinstance(item, dict):
142
+ raise ConfigError(_("Mapping #{0} is not an object.").format(i))
143
+ try:
144
+ m = MappingConfig.from_dict(item)
145
+ # TLS files of a data directory that moved are this one's (tls folder) before an
146
+ # edit's rules ask whether they exist
147
+ moved = AppConfig(mappings=[m]).find_moved_tls_files()
148
+ m.validate_input()
149
+ except (TypeError, ValueError) as e: # ConfigError is a ValueError
150
+ raise ConfigError(_("Mapping #{0} ({1}): {2}").format(i, item.get('name', '?'), e)) from None
151
+ if moved:
152
+ warnings.append(_("Mapping #{0} ({1}): its TLS files are not where the file says; "
153
+ "the files of that name in this data directory's tls folder are "
154
+ "used.").format(i, m.name))
155
+ warnings.extend(_tls_warning(i, m))
156
+ try: # files of another machine: the mapping is taken, its MQTT stays off
157
+ m.check_mqtt_tls_files()
158
+ except ConfigError as e:
159
+ warnings.append(_("Mapping #{0} ({1}): {2} It runs without MQTT until that is "
160
+ "fixed.").format(i, m.name, e))
161
+ warnings.extend(_("Mapping #{0} ({1}): {2}").format(i, m.name, w)
162
+ for w in m.input_warnings() + m.ignored_settings())
163
+ if item.get("id") and item["id"] != m.id:
164
+ warnings.append(_("Mapping #{0} ({1}): {2} is not a valid mapping id (1-64 letters, "
165
+ "digits or _), so it gets a new one.").format(
166
+ i, m.name, repr(item["id"])[:80]))
167
+ absent.append(absent_settings(item))
168
+ if absent[-1]:
169
+ names = list(dict.fromkeys(re.sub(r"\[\d+\]", "[]", p) for p in absent[-1]))
170
+ warnings.append(_("Mapping #{0} ({1}): the file has no {2} (an export of an older "
171
+ "version?). Merged into a mapping of the same name, they keep "
172
+ "their current values; otherwise they take the defaults.").format(
173
+ i, m.name, ", ".join(names[:8]) + (" …" if len(names) > 8 else "")))
174
+ mappings.append(m)
175
+ whole_config = "users" in doc or "admin_ui" in doc
176
+ source = _("ser2netweb config.json") if whole_config else _("ser2netweb export")
177
+ if whole_config:
178
+ warnings.append(_("Only the mappings are imported from a config.json; users, "
179
+ "passwords and settings stay as they are."))
180
+ return ImportPlan(source=source, mappings=mappings, warnings=warnings, absent=absent)
181
+
182
+
183
+ _FULL_MAPPING = MappingConfig().to_dict()
184
+ _FULL_POINT = dataclasses.asdict(ModbusPoint())
185
+ _POINT = re.compile(r"modbus_poll\.points\[(\d+)\]")
186
+
187
+
188
+ def absent_settings(item: dict, full: dict = _FULL_MAPPING, path: str = "") -> list[str]:
189
+ """The settings (paths like "options.trace_max_mb", "modbus_poll.points[2].writable")
190
+ a mapping of an import file doesn't have, e.g. because an older version wrote it."""
191
+ out = []
192
+ for key, default in full.items():
193
+ if key == "id":
194
+ continue
195
+ if not isinstance(item, dict) or key not in item:
196
+ out.append(path + key)
197
+ elif key == "points" and isinstance(item[key], list):
198
+ for i, point in enumerate(item[key]):
199
+ if isinstance(point, dict):
200
+ out += [f"{path}points[{i}].{k}" for k in _FULL_POINT if k not in point]
201
+ elif isinstance(default, dict) and key != "match": # a section (match is a value)
202
+ out += absent_settings(item[key], default, f"{path}{key}.")
203
+ return out
204
+
205
+
206
+ def _keep_absent(m: MappingConfig, target: MappingConfig, absent: list[str]) -> MappingConfig:
207
+ """*m* (merged into *target*) with target's values for the settings the file didn't
208
+ have; a Modbus point's by its name ("writable" only while it is a coil or holding
209
+ register)."""
210
+ if not absent:
211
+ return m
212
+ d, old = m.to_dict(), target.to_dict()
213
+ old_points = {p["name"]: p for p in old["modbus_poll"]["points"]}
214
+ for path in absent:
215
+ head, _dot, key = path.rpartition(".")
216
+ if pm := _POINT.fullmatch(head):
217
+ points, n = d["modbus_poll"]["points"], int(pm.group(1))
218
+ if n < len(points) and (stored := old_points.get(points[n]["name"])) is not None \
219
+ and (key != "writable" or points[n]["fn"] in (1, 3)):
220
+ points[n][key] = copy.deepcopy(stored[key])
221
+ continue
222
+ src, dst = old, d
223
+ for part in head.split(".") if head else ():
224
+ src, dst = src[part], dst[part]
225
+ dst[key] = copy.deepcopy(src[key])
226
+ return MappingConfig.from_dict(d)
227
+
228
+
229
+ def _classic_ser2net(text: str, filename: str) -> ImportPlan:
230
+ """A configuration file of the classic C ser2net, converted (ser2netweb/ser2net_import).
231
+ Nothing importable is an error, so a replace import cannot empty the mappings."""
232
+ dicts, warnings = parse_ser2net_config(text, filename)
233
+ if not dicts:
234
+ raise ConfigError(" ".join(warnings) or _("The file has no ser2net connections to import."))
235
+ source = _("ser2net.yaml (ser2net 4.x)") if looks_yaml(text) else _("ser2net.conf (ser2net 3.x)")
236
+ mappings = [MappingConfig.from_dict(d) for d in dicts]
237
+ for i, m in enumerate(mappings, 1):
238
+ m.validate_input() # the converter skips URL devices already; this backs it up
239
+ for w in _tls_warning(i, m):
240
+ note = Note(w)
241
+ note.mapping = i - 1 # (shown in its row of the preview)
242
+ warnings.append(note)
243
+ return ImportPlan(source=source, mappings=mappings, warnings=warnings, classic=True)
244
+
245
+
246
+ def _tls_warning(i: int, m: MappingConfig) -> list[str]:
247
+ """A TLS mapping whose certificate and key don't load here (a key that needs its
248
+ password, files of another machine) is imported all the same, with a warning: it can't
249
+ start until that is fixed, and never runs without TLS."""
250
+ try:
251
+ m.check_tls_files()
252
+ except ConfigError as e:
253
+ return [_("Mapping #{0} ({1}): {2} It can't start until that is fixed.").format(
254
+ i, m.name, e)]
255
+ return []
256
+
257
+
258
+ def _match(existing: list[MappingConfig], m: MappingConfig):
259
+ return (next((e for e in existing if e.id == m.id), None)
260
+ or next((e for e in existing if e.name == m.name), None))
261
+
262
+
263
+ def _bind_reach(ip: str) -> int:
264
+ """How far a bind IP reaches: 0 the loopback, 1 one address, 2 every interface."""
265
+ try:
266
+ a = ipaddress.ip_address(ip)
267
+ except ValueError:
268
+ return 1
269
+ return 0 if a.is_loopback else 2 if a.is_unspecified else 1
270
+
271
+
272
+ def _reach(net) -> int:
273
+ """How far a listener (NetworkSettings) reaches: _bind_reach, and 3 for every
274
+ interface of both families (dual_stack on 0.0.0.0 / ::)."""
275
+ return 3 if net.both_families else _bind_reach(net.bind_ip)
276
+
277
+
278
+ def _within(inner: list[str], outer: list[str]) -> bool:
279
+ """The clients `inner` allows are all allowed by `outer` too (an empty list: any)."""
280
+ if not outer:
281
+ return True
282
+ if not inner:
283
+ return False
284
+ try:
285
+ nets_in, nets_out = ([ipaddress.ip_network(normalize_cidr(x), strict=False) for x in xs]
286
+ for xs in (inner, outer))
287
+ except ValueError:
288
+ return sorted(inner) == sorted(outer)
289
+ return all(any(n.version == w.version and n.subnet_of(w) for w in nets_out) # type: ignore[arg-type]
290
+ for n in nets_in)
291
+
292
+
293
+ def _overlay(old: MappingConfig, new: MappingConfig) -> MappingConfig:
294
+ """`new`, from a classic ser2net file, merged into `old`, the mapping it updates. The
295
+ file says only part of what a mapping has here (what ser2net_import writes), so only
296
+ that is taken from it, and never so that the mapping gets more open: a disabled
297
+ mapping stays disabled, the bind IP (with the families it takes, dual_stack), the
298
+ allowed clients and read-only are not widened, TLS is not turned off and a TLS client
299
+ CA is not dropped, a Modbus gateway stays one. What the file leaves at ser2netweb's
300
+ default (no banner, no timeout, ...) keeps the mapping's own value, the port locking
301
+ (flock / uucplock) too; the serial framing is always the file's (ser2netweb ran with it,
302
+ 9600N81 by default)."""
303
+ r = MappingConfig.from_dict(old.to_dict())
304
+ plain = MappingConfig()
305
+
306
+ def given(dst, src, default, *attrs): # the values the file sets (not the default)
307
+ for a in attrs:
308
+ if getattr(src, a) != getattr(default, a):
309
+ setattr(dst, a, getattr(src, a))
310
+ r.name, r.kind = new.name, new.kind
311
+ r.enabled = old.enabled and new.enabled
312
+ s, ns = r.serial, new.serial
313
+ s.port, s.baudrate, s.bytesize, s.parity, s.stopbits, s.flowcontrol = (
314
+ ns.port, ns.baudrate, ns.bytesize, ns.parity, ns.stopbits, ns.flowcontrol)
315
+ given(s, ns, plain.serial, "rts_on_open", "dtr_on_open", "exclusive")
316
+ given(s.advanced, ns.advanced, plain.serial.advanced, "hangup_when_done", "nobreak",
317
+ "tiocexcl", "respect_uucp_locks")
318
+ n, nn = r.network, new.network
319
+ n.mode, n.port = nn.mode, nn.port
320
+ if old.network.protocol != "modbus" or nn.mode != "server": # (a gateway is a TCP server)
321
+ n.protocol = nn.protocol
322
+ if _reach(nn) <= _reach(n):
323
+ n.bind_ip, n.dual_stack = nn.bind_ip, nn.dual_stack
324
+ if nn.allowed_client_ips and _within(nn.allowed_client_ips, n.allowed_client_ips):
325
+ n.allowed_client_ips = list(nn.allowed_client_ips)
326
+ n.read_only = n.read_only or nn.read_only
327
+ if nn.tls:
328
+ n.tls, n.tls_cert, n.tls_key = True, nn.tls_cert, nn.tls_key
329
+ if nn.tls_client_ca: # (clientauth with its CA file here; a CA the mapping has stays)
330
+ n.tls_client_ca = nn.tls_client_ca
331
+ given(n, nn, plain.network, "kick_old_user", "max_connections")
332
+ if n.protocol == "rfc2217":
333
+ n.max_connections = 1 # (RFC 2217 takes a single client here: the file's is 1 too)
334
+ o, no = r.options, new.options
335
+ given(o, no, plain.options, "idle_timeout_s", "banner", "openstr", "closestr", "closeon")
336
+ if no.trace_both:
337
+ o.trace_both, o.trace_hexdump, o.trace_timestamp = (
338
+ no.trace_both, no.trace_hexdump, no.trace_timestamp)
339
+ return r
340
+
341
+
342
+ def _merged(target: MappingConfig, m: MappingConfig, classic: bool,
343
+ absent: Optional[list[str]] = None) -> MappingConfig:
344
+ """What `m` makes of the mapping `target` it updates (a copy; `m.id` is not used): a
345
+ classic ser2net file's mapping keeps what such a file can't say (_overlay), any other
346
+ target's values for the settings its file didn't have (`absent`, _keep_absent)."""
347
+ if classic:
348
+ return _overlay(target, m)
349
+ return MappingConfig.from_dict({**_keep_absent(m, target, absent or []).to_dict(),
350
+ "id": target.id})
351
+
352
+
353
+ def apply_import(current: list[MappingConfig], incoming: list[MappingConfig],
354
+ mode: str, classic: bool = False, absent: list[list[str]] | None = None,
355
+ ) -> tuple[list[MappingConfig], list[MappingConfig]]:
356
+ """(new mapping list, mappings that were added or changed). Pure: the inputs
357
+ are not modified. An update in merge mode keeps what the file doesn't say: `classic`
358
+ (a classic ser2net file) what such a file can't say (_overlay); else `absent`, per
359
+ incoming mapping the settings its file didn't have (ImportPlan.absent), keep their
360
+ current values (_keep_absent)."""
361
+ if mode not in MODES:
362
+ raise ConfigError(_("Import mode must be one of {0}.").format(", ".join(MODES)))
363
+ if mode == "replace":
364
+ seen: set[str] = set()
365
+ out = []
366
+ for m in incoming:
367
+ m = MappingConfig.from_dict(m.to_dict())
368
+ if m.id in seen:
369
+ m.id = _new_id()
370
+ seen.add(m.id)
371
+ out.append(m)
372
+ return out, list(out)
373
+ result = [MappingConfig.from_dict(m.to_dict()) for m in current]
374
+ touched = []
375
+ for i, m in enumerate(incoming):
376
+ m = MappingConfig.from_dict(m.to_dict())
377
+ target = _match(result, m)
378
+ if target is not None:
379
+ m = _merged(target, m, classic, absent[i] if absent and i < len(absent) else [])
380
+ if m.to_dict() == target.to_dict():
381
+ continue # identical: nothing to restart
382
+ result[result.index(target)] = m
383
+ else:
384
+ if any(e.id == m.id for e in result):
385
+ m.id = _new_id()
386
+ result.append(m)
387
+ touched.append(m)
388
+ return result, touched
389
+
390
+
391
+ def mqtt_clash(mappings: list[MappingConfig], touched: list[MappingConfig]) -> Optional[str]:
392
+ """Why an import that leaves ``mappings`` (adding or changing ``touched``) can't be
393
+ applied over MQTT (see config.check_mqtt_clashes): a mapping it brings shares its MQTT
394
+ client ID, Sparkplug B edge node or a command topic with another enabled mapping on
395
+ the same broker. None when it doesn't."""
396
+ for m in touched:
397
+ try:
398
+ check_mqtt_clashes(m, mappings)
399
+ except ConfigError as e:
400
+ return _("Mapping '{0}': {1}").format(m.name, e)
401
+ return None
402
+
403
+
404
+ def plan_rows(current: list[MappingConfig], incoming: list[MappingConfig],
405
+ mode: str, classic: bool = False,
406
+ notes: Optional[list[list[str]]] = None,
407
+ absent: list[list[str]] | None = None) -> list[dict]:
408
+ """Preview rows: {name, kind, action: add|update|same|remove, target, changes, after,
409
+ notes}. For an update, `changes` lists what it changes and what it keeps of the
410
+ mapping (_diff); `after` is how the mapping will be (_after); `notes` are its
411
+ warnings (ImportPlan.split_warnings, in the order of `incoming`), those about its
412
+ protection first. `classic` / `absent`: as for apply_import."""
413
+ rows = []
414
+ for i, m in enumerate(incoming):
415
+ target = _match(current, m) if mode == "merge" else None
416
+ changes: list[dict] = []
417
+ result = m
418
+ if target is None:
419
+ action = "add"
420
+ else:
421
+ result = _merged(target, m, classic, absent[i] if absent and i < len(absent) else [])
422
+ action = "same" if result.to_dict() == target.to_dict() else "update"
423
+ changes = _diff(target, m, result)
424
+ own = [{"text": getattr(n, "detail", "") or n, "security": getattr(n, "security", False)}
425
+ for n in (notes[i] if notes and i < len(notes) else [])]
426
+ rows.append({"name": m.name, "kind": _kind(m), "action": action,
427
+ "target": target.name if target is not None else "", "changes": changes,
428
+ "after": _after(result),
429
+ "notes": sorted(own, key=lambda n: not n["security"])})
430
+ if mode == "replace":
431
+ for e in current:
432
+ rows.append({"name": e.name, "kind": _kind(e), "action": "remove", "target": "",
433
+ "changes": [], "after": None, "notes": []})
434
+ return rows
435
+
436
+
437
+ def _after(m: MappingConfig) -> dict:
438
+ """How a mapping will be after the import, for the preview (as the dashboard tags it):
439
+ enabled, TLS, read-only, `clients` (entries of its allow-list; None: it doesn't
440
+ listen) and `open` (enabled and taking any client beyond the loopback)."""
441
+ n = m.network
442
+ listens = m.kind == "net" and n.mode != "client"
443
+ return {"enabled": m.enabled, "tls": listens and n.tls, "read_only": n.read_only,
444
+ "clients": len(n.allowed_client_ips) if listens else None,
445
+ "open": listens and m.enabled and not n.allowed_client_ips
446
+ and _reach(n) > 0}
447
+
448
+
449
+ _CONTROL = re.compile(r"[\x00-\x1f\x7f\u2028\u2029]")
450
+
451
+
452
+ def log_lines(plan: ImportPlan) -> list[str]:
453
+ """The import's warnings for all.log, in English, one line each: a line break or other
454
+ control character from the file is written as its escape (it would start a log line
455
+ of its own)."""
456
+ warnings = plan.log_warnings if plan.log_source else plan.warnings
457
+ return [_CONTROL.sub(lambda m: m.group().encode("unicode_escape").decode(), w)
458
+ for w in warnings]
459
+
460
+
461
+ def audit_detail(plan: ImportPlan, most: int = 500) -> str:
462
+ """The audit record of an import: how many mappings from what, and its warnings (in
463
+ English), cut to `most` characters."""
464
+ source, warnings = ((plan.log_source, plan.log_warnings) if plan.log_source else
465
+ (plan.source, plan.warnings))
466
+ text = f"{len(plan.mappings)} mappings ({source})"
467
+ if warnings:
468
+ text += f"; {len(warnings)} warnings: " + "; ".join(warnings)
469
+ return text if len(text) <= most else text[:most - 1] + "…"
470
+
471
+
472
+ def _shown(value: str, most: int = 60) -> str:
473
+ """A string option in the preview: control characters escaped, cut at `most`, — for
474
+ none."""
475
+ v = value.encode("unicode_escape").decode("ascii") if not value.isprintable() else value
476
+ return "—" if not v else v if len(v) <= most else v[:most - 1] + "…"
477
+
478
+
479
+ def _fields(m: MappingConfig) -> list[tuple[str, str]]:
480
+ """What the preview compares of a mapping: (label, value as shown), in the order of
481
+ the mapping form."""
482
+ s, n, o = m.serial, m.network, m.options
483
+ on, off = _("on"), _("off")
484
+ framing = s.compact() + (f" · {s.flowcontrol}" if s.flowcontrol != "none" else "")
485
+ return [
486
+ (_("State"), _("enabled") if m.enabled else _("disabled")),
487
+ (_("Serial port"), s.port),
488
+ (_("Serial"), framing),
489
+ (_("RTS on open"), s.rts_on_open),
490
+ (_("DTR on open"), s.dtr_on_open),
491
+ (_("Protocol"), f"{n.mode}/{n.protocol}"),
492
+ (_("Bind IP"), _("All interfaces (IPv4 + IPv6)") if n.both_families else n.bind_ip),
493
+ (_("Listen port"), str(n.port)),
494
+ ("TLS", on if n.tls else off),
495
+ (_("Allowed client IPs / CIDRs"), " ".join(n.allowed_client_ips) or _("any client")),
496
+ (_("Read-only"), on if n.read_only else off),
497
+ (_("Max connections"), str(n.max_connections)),
498
+ (_("Kick old client"), on if n.kick_old_user else off),
499
+ (_("Idle timeout (s)"), str(o.idle_timeout_s)),
500
+ (_("Connect banner"), _shown(o.banner)),
501
+ ("openstr", _shown(o.openstr)),
502
+ ("closestr", _shown(o.closestr)),
503
+ (_("Close-on string"), _shown(o.closeon)),
504
+ (_("Trace file name"), _shown(o.trace_both)),
505
+ ]
506
+
507
+
508
+ def _looser(old: MappingConfig, new: MappingConfig) -> set[str]:
509
+ """The fields (labels of _fields) in which `new` is more open than `old`: started,
510
+ TLS off, a wider bind IP or allow-list, writable."""
511
+ a, b = old.network, new.network
512
+ out = set()
513
+ if new.enabled and not old.enabled:
514
+ out.add(_("State"))
515
+ if a.tls and not b.tls:
516
+ out.add("TLS")
517
+ if _reach(b) > _reach(a):
518
+ out.add(_("Bind IP"))
519
+ if not _within(b.allowed_client_ips, a.allowed_client_ips):
520
+ out.add(_("Allowed client IPs / CIDRs"))
521
+ if a.read_only and not b.read_only:
522
+ out.add(_("Read-only"))
523
+ return out
524
+
525
+
526
+ def _diff(old: MappingConfig, file: MappingConfig, result: MappingConfig) -> list[dict]:
527
+ """What an update does to the mapping `old`: each field it changes ({what, before,
528
+ after}) and, for a classic file, each one the file has otherwise that the mapping
529
+ keeps ({what, before, file, kept: True}). `security`: the change opens the mapping
530
+ up, or the file would have."""
531
+ before, given, after = _fields(old), _fields(file), _fields(result)
532
+ looser, would = _looser(old, result), _looser(old, file)
533
+ out = []
534
+ for (what, b), (_l, f), (_m, a) in zip(before, given, after, strict=True):
535
+ if b != a:
536
+ out.append({"what": what, "before": b, "after": a, "kept": False,
537
+ "security": what in looser})
538
+ elif f != a:
539
+ out.append({"what": what, "before": b, "file": f, "kept": True,
540
+ "security": what in would})
541
+ return out
542
+
543
+
544
+ def _kind(m: MappingConfig) -> str:
545
+ if m.kind == "serialbridge":
546
+ return f"{m.serial.port} ↔ {m.serial_b.port}"
547
+ net = m.network
548
+ where = (f"→ {host_port(net.remote_host, net.remote_port)}" if net.mode == "client"
549
+ else f"{net.bind_shown}:{net.port}")
550
+ return f"{m.serial.port} · {net.mode}/{net.protocol} {where}"
ser2netweb/layout.py ADDED
@@ -0,0 +1,118 @@
1
+ """How this copy of ser2netweb is installed, and where it keeps its data by default.
2
+
3
+ source a source checkout (ser2netweb.py, bootstrap.py and ./lib beside the package),
4
+ also the Docker image's /app: data/ in the checkout
5
+ standalone a standalone executable (PyInstaller): data/ next to the executable
6
+ package that executable as the .deb / .rpm package installs it, /usr/bin/ser2netweb:
7
+ /var/lib/ser2netweb, the data directory of the package's service
8
+ pip installed by pip or pipx (the wheel from PyPI: the package in a site-packages
9
+ folder, or wherever --target put it next to its .dist-info): the platform's
10
+ folder for a user's application data, never next to the package, which pip
11
+ owns (and may replace or delete on the next upgrade)
12
+
13
+ --data-dir and --config choose another folder in every case. A pip install gets its
14
+ dependencies from pip, so the offline bootstrap into ./lib (bootstrap.py) is not used there.
15
+ Standard library only (the command line reads this before the dependencies load).
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import functools
20
+ import ntpath
21
+ import os
22
+ import posixpath
23
+ import sys
24
+ from collections.abc import Mapping
25
+ from typing import Optional
26
+
27
+ NAME = "ser2netweb"
28
+ SOURCE, STANDALONE, PACKAGE, PIP = "source", "standalone", "package", "pip"
29
+ # --about's "Build:" line
30
+ LABELS = {SOURCE: "source", STANDALONE: "standalone executable",
31
+ PACKAGE: "standalone executable, .deb / .rpm package",
32
+ PIP: "Python package (pip / pipx)"}
33
+ # where the .deb / .rpm package puts the executable, and its service's data directory
34
+ # (packaging/nfpm.yaml; ser2netweb-install.sh and the standalone unit use /usr/local/bin)
35
+ PACKAGE_EXECUTABLE = "/usr/bin/ser2netweb"
36
+ PACKAGE_DATA_DIR = "/var/lib/ser2netweb"
37
+ PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__)) # this package's folder
38
+ _SITE_FOLDERS = ("site-packages", "dist-packages") # (dist-packages: Debian's Python)
39
+
40
+
41
+ def _dist_infos(folder: str) -> list[str]:
42
+ """The ser2netweb-*.dist-info folders an installer left in `folder`."""
43
+ try:
44
+ names = os.listdir(folder)
45
+ except OSError:
46
+ return []
47
+ return sorted(n for n in names
48
+ if n.lower().startswith(NAME + "-") and n.lower().endswith(".dist-info"))
49
+
50
+
51
+ def detect(frozen: bool, executable: str, package_dir: str,
52
+ platform: str = sys.platform) -> str:
53
+ """The kind of installation (SOURCE, STANDALONE, PACKAGE or PIP) of a copy whose package
54
+ is `package_dir`, run by `executable`."""
55
+ if frozen:
56
+ # (a Linux path, compared as one whatever OS this runs on; a frozen executable's
57
+ # sys.executable is absolute)
58
+ if platform.startswith("linux") and posixpath.normpath(executable) == PACKAGE_EXECUTABLE:
59
+ return PACKAGE
60
+ return STANDALONE
61
+ parent = os.path.dirname(os.path.abspath(package_dir))
62
+ if os.path.basename(parent).lower() in _SITE_FOLDERS or _dist_infos(parent):
63
+ return PIP
64
+ # a source checkout (an editable install `pip install -e .` too: the package stays in
65
+ # the checkout, so its data does as well)
66
+ return SOURCE
67
+
68
+
69
+ @functools.cache
70
+ def kind() -> str:
71
+ """The kind of this installation (detect() for the running copy; found once)."""
72
+ return detect(bool(getattr(sys, "frozen", False)), sys.executable, PACKAGE_DIR)
73
+
74
+
75
+ def user_data_dir(platform: str = sys.platform, environ: Optional[Mapping[str, str]] = None,
76
+ home: Optional[str] = None) -> str:
77
+ """A user's folder for ser2netweb's data: %LOCALAPPDATA%\\ser2netweb on Windows,
78
+ ~/Library/Application Support/ser2netweb on macOS, $XDG_DATA_HOME/ser2netweb (or
79
+ ~/.local/share/ser2netweb) elsewhere, as the XDG base directory spec has it: a
80
+ relative XDG_DATA_HOME is ignored."""
81
+ env = os.environ if environ is None else environ
82
+ path = ntpath if platform == "win32" else posixpath
83
+ if home is None:
84
+ home = os.path.expanduser("~")
85
+ if platform == "win32":
86
+ base = env.get("LOCALAPPDATA", "")
87
+ if not path.isabs(base):
88
+ base = path.join(home, "AppData", "Local")
89
+ elif platform == "darwin":
90
+ base = path.join(home, "Library", "Application Support")
91
+ else:
92
+ base = env.get("XDG_DATA_HOME", "")
93
+ if not path.isabs(base):
94
+ base = path.join(home, ".local", "share")
95
+ return path.join(base, NAME)
96
+
97
+
98
+ def default_data_dir(app_dir: str, kind_: Optional[str] = None) -> str:
99
+ """The data directory without --data-dir / --config: data/ in `app_dir` (a source
100
+ checkout, or the folder of a standalone executable), the package's service's data
101
+ directory, or a pip install's user data folder."""
102
+ k = kind() if kind_ is None else kind_
103
+ if k == PIP:
104
+ return user_data_dir()
105
+ if k == PACKAGE:
106
+ return PACKAGE_DATA_DIR
107
+ return os.path.join(app_dir, "data")
108
+
109
+
110
+ def licence_dir(package_dir: str = PACKAGE_DIR) -> Optional[str]:
111
+ """A pip install's licence texts (LICENSE, NOTICE, ...: the wheel's license-files,
112
+ which an installer puts in <name>.dist-info/licenses next to the package), else None."""
113
+ parent = os.path.dirname(os.path.abspath(package_dir))
114
+ for name in _dist_infos(parent):
115
+ folder = os.path.join(parent, name, "licenses")
116
+ if os.path.isdir(folder):
117
+ return folder
118
+ return None