virtual-plc 0.3.0__py3-none-any.whl

virtual_plc/faults.py

@@ -0,0 +1,139 @@
+"""Declarative, post-dispatch response faults; no effects until explicitly selected."""
+
+from copy import deepcopy
+import json
+import math
+import os
+from pathlib import Path
+import socket
+import struct
+import threading
+
+from .codec import Layout
+
+
+def _integer(value, minimum, maximum):
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise ValueError(f"expected integer in {minimum}..{maximum}")
+
+
+def _seconds(value):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
+        raise ValueError("seconds must be finite and nonnegative")
+
+
+# Action type -> (required, optional) parameter names; also drives `virtual-plc guide faults`.
+ACTION_FIELDS = {
+    "delay": ({"seconds"}, set()), "drop": (set(), set()),
+    "truncate": ({"n"}, set()), "bad_end_code": ({"code"}, set()),
+    "close_before_response": (set(), set()), "close_after_response": (set(), set()),
+    "rst": (set(), set()), "silent_hold": (set(), set()),
+    "corrupt_header": (set(), {"offset", "xor"}),
+    "partial_send": ({"chunks"}, {"pause"}),
+}
+
+
+def _validate(step):
+    if not isinstance(step, dict) or set(step) - {"match", "times", "action"} or "action" not in step:
+        raise ValueError("a fault step requires action and optional match/times")
+    match = step.setdefault("match", {})
+    if not isinstance(match, dict) or set(match) - {"command", "nth", "connection"}:
+        raise ValueError("unknown match fields")
+    for key, value in match.items():
+        if key == "command" and isinstance(value, str):
+            value = match[key] = int(value, 0)
+        _integer(value, 0 if key == "command" else 1, 0xFFFF if key == "command" else 2**63 - 1)
+    _integer(step.setdefault("times", 1), 1, 2**63 - 1)
+    action = step["action"]
+    if not isinstance(action, dict):
+        raise ValueError("action must be an object")
+    kind = action.get("type")
+    if not isinstance(kind, str) or kind not in ACTION_FIELDS:
+        raise ValueError("unknown fault action")
+    required, optional = ACTION_FIELDS[kind]
+    if not required <= set(action) or set(action) - required - optional - {"type"}:
+        raise ValueError(f"invalid fields for {kind}")
+    if kind == "delay":
+        _seconds(action["seconds"])
+    elif kind == "truncate":
+        _integer(action["n"], 0, 2**63 - 1)
+    elif kind == "bad_end_code":
+        _integer(action["code"], 0, 0xFFFF)
+    elif kind == "corrupt_header":
+        # Common to every response header, including the shortest 3E binary header.
+        _integer(action.setdefault("offset", 0), 0, 8)
+        _integer(action.setdefault("xor", 1), 1, 255)
+    elif kind == "partial_send":
+        if not isinstance(action["chunks"], list) or not action["chunks"]:
+            raise ValueError("chunks must be a nonempty list of positive byte counts")
+        for size in action["chunks"]:
+            _integer(size, 1, 2**63 - 1)
+        _seconds(action.setdefault("pause", 0))
+
+
+class FaultPlan:
+    """First eligible step wins; counts are reserved atomically, never rolled back."""
+
+    def __init__(self, steps):
+        if not isinstance(steps, list):
+            raise ValueError("steps must be a list")
+        self._steps = deepcopy(steps)
+        for step in self._steps:
+            _validate(step)
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_file(cls, path):
+        document = json.loads(Path(path).read_text(encoding="utf-8"))
+        if not isinstance(document, dict) or set(document) != {"steps"}:
+            raise ValueError("fault file must contain only a steps array")
+        return cls(document["steps"])
+
+    def select(self, command, *, nth, connection):
+        context = {"command": command, "nth": nth, "connection": connection}
+        with self._lock:
+            for step in self._steps:
+                if step["times"] and all(context[key] == value for key, value in step["match"].items()):
+                    step["times"] -= 1
+                    return deepcopy(step["action"])
+        return None
+
+
+def send_fault(connection, response, request, action, stopping):
+    """Apply one reserved action. Return False to close; waits cancel on server stop."""
+    kind = action["type"]
+    if kind == "drop":
+        return True
+    if kind == "silent_hold":
+        stopping.wait()
+        return False
+    if kind == "close_before_response":
+        return False
+    if kind == "rst":
+        connection.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("hh" if os.name == "nt" else "ii", 1, 0))
+        return False  # The worker closes without shutdown, preserving abortive-close semantics.
+    if kind == "delay" and stopping.wait(action["seconds"]):
+        return False
+    if kind == "truncate":
+        response = response[:action["n"]]
+    elif kind == "bad_end_code":
+        layout = Layout(request.frame, request.wire)
+        offset = layout.header_size
+        response = response[:offset] + layout.number(action["code"], 2) + response[offset + 2 * layout.scale:]
+    elif kind == "corrupt_header":
+        changed = bytearray(response)
+        changed[action["offset"]] ^= action["xor"]
+        response = bytes(changed)
+    elif kind == "partial_send":
+        offset = 0
+        for size in action["chunks"] + [len(response)]:
+            chunk = response[offset:offset + size]
+            if not chunk:
+                break
+            connection.sendall(chunk)
+            offset += len(chunk)
+            if offset < len(response) and stopping.wait(action["pause"]):
+                return False
+        return True
+    connection.sendall(response)
+    return kind != "close_after_response"

virtual_plc/guide.py

@@ -0,0 +1,343 @@
+"""Token-efficient usage guide for humans and AI agents: `virtual-plc guide [TOPIC] [--json]`.
+
+Hand-written prose lives here. The option, profile, command, device and fault
+tables are generated from the argparse parser and from the profile, command and
+fault tables, so they cannot drift. Output is ASCII-only for legacy consoles.
+"""
+
+import argparse
+import inspect
+import json
+import sys
+import textwrap
+
+from . import __version__
+from .codec import FRAMES, WIRES
+from .commands import COMMAND_NAMES, supported_commands
+from .faults import ACTION_FIELDS
+from .profiles import PROFILES
+from .server import Server
+
+TOPICS = ("run", "options", "client", "profiles", "embed", "faults", "memory", "troubleshoot", "divergences")
+
+# Option -> topic named by error messages; every other option points to `options`.
+OPTION_TOPICS = {"--profile": "profiles", "--fault-plan": "faults", "--init": "memory",
+                 "--dump-on-exit": "memory", "--limit": "memory", "--latch-range": "memory"}
+
+# Mirrored verbatim in the README quickstart (a test fails on drift).
+RECIPES = (
+    "virtual-plc --port 5000 --text-pad 0x20",
+    "virtual-plc --profile iQ-R --port 5001 --initial-state STOP",
+    "virtual-plc --init seed.json --fault-plan faults.json --dump-on-exit saved.json",
+)
+RECIPE_LINES = "\n".join("  " + recipe for recipe in RECIPES)
+
+EFFECTS = {
+    "delay": "wait, then send the reply normally",
+    "drop": "send nothing; the connection stays open",
+    "truncate": "send only the first n bytes",
+    "bad_end_code": "replace the end code (0..65535)",
+    "close_before_response": "close without replying",
+    "close_after_response": "reply, then close",
+    "rst": "abortive close (TCP reset)",
+    "silent_hold": "answer nothing on this connection until the server stops",
+    "corrupt_header": "XOR one header byte (offset 0..8, xor 1..255)",
+    "partial_send": "send in chunks of the given byte counts, pausing between",
+}
+
+RUN = f"""
+Start the simulator (Python 3.10+, stdlib only). The banner and -v logs go to stderr; stdout stays empty.
+  python -m pip install virtual-plc        (from a checkout: python -m pip install -e .)
+{RECIPE_LINES}
+Same program: python -m virtual_plc ...   Every option: virtual-plc guide options.
+Banner: "listening on HOST:PORT (...)". With --port 0 parse the real port from it.
+Stop: Ctrl+C or SIGTERM exits 0 and writes --dump-on-exit; Windows SIGBREAK needs a shared console.
+Exit codes: 0 clean stop, 1 cannot bind, 2 bad configuration (message ends "see: virtual-plc guide TOPIC").
+Default bind is 127.0.0.1. Other hosts print a WARNING: there is no authentication, so never expose it.
+-v logs request summaries (no payloads or passwords) and why each connection closed.
+Idle clients stay connected unless --idle-timeout SECONDS is set.
+""".strip("\n")
+
+CLIENT = """
+Client: pymcprotocol (python -m pip install pymcprotocol). Its plctype must match --profile.
+  from pymcprotocol import Type3E               # Type4E for 4E frames
+  c = Type3E(plctype="Q")                       # Q, L, QnA, iQ-L, iQ-R
+  c.setaccessopt(commtype="ascii")              # default is "binary"
+  c.connect("127.0.0.1", 5000)
+  c.batchwrite_wordunits("D0", [123, -45]); c.batchread_wordunits("D0", 2)   # client signed, server unsigned
+  c.batchwrite_bitunits("M0", [1, 0, 1]);   c.batchread_bitunits("M0", 3)
+  c.randomwrite([], [], ["D0"], [0x12345678]); c.randomread([], ["D0"])      # returns (words, dwords)
+  c.echo_test("ABC"); c.read_cputype()          # CPU name has NUL fill unless --text-pad 0x20
+  c.remote_stop(); c.remote_run(0)              # remote_reset() needs STOP; remote_unlock(pw) needs --password
+  c.close()
+iQ-R: start virtual-plc --profile iQ-R --port 5001 --initial-state STOP, then:
+  c = Type3E(plctype="iQ-R"); c.connect("127.0.0.1", 5001); c.close()
+Hex-numbered devices (X Y B W SB SW DX DY ZR) take hex digits in the client: "X1F". Names are case-sensitive.
+ASCII frames carry device numbers as decimal text (pymcprotocol "compat" numbering); the client handles it.
+setaccessopt(timer_sec=2) sets the PLC monitoring timer (ignored here) and a 3 s client socket timeout.
+""".strip("\n")
+
+TROUBLESHOOT = """
+Symptom -> cause -> fix
+"cannot listen on H:P" (exit 1): port busy or denied -> choose another --port, or --port 0 and read the banner.
+Exit 2 and "see: virtual-plc guide TOPIC": bad option, JSON file or plan -> read that topic; nothing was bound.
+Client times out: wrong host/port, a fault plan that holds or drops replies, or --idle-timeout closed the socket
+  (reconnect). A silent_hold fault ends only when the server stops.
+Large read fails: pymcprotocol reads once with recv(4096); keep batches under ~1000 words (ASCII is 4 chars/word).
+  --max-points is a separate server-side limit (points per request).
+CPU name has NUL bytes: the default fill is 0x00 and the client keeps NULs -> --text-pad 0x20.
+Status 0 on a broken reply: the client never checks subheader or length, so a truncated or closed binary
+  reply can look like success. It is not proof of success.
+Run/stop/pause/latch-clear/reset fail: locked (unlock with the --password text; length per profile in
+  guide profiles) or wrong state: latch clear and reset need STOP, pause needs RUN or PAUSE.
+  A normal reset keeps the connection open.
+iQ-R vs Q mismatch: addressed commands use different subcommands -> set --profile and plctype together.
+Echo rejected: data must be ASCII letters/digits, 1..960 chars (an error end code, no disconnect).
+Client device-name error: names are case-sensitive; hex devices need a digit first ("X0FFF", not "XFFF").
+""".strip("\n")
+
+DIVERGENCES = """
+This is a simulator, not a PLC. These behaviors are synthetic or unverified; do not treat them as vendor facts.
+- CPU identities (VirtualPLC-<profile>), device ranges and the SD203 state codes are synthetic.
+- CPU-name fill defaults to NUL (--text-pad); the fill of a physical PLC is unverified.
+- ASCII frames send device numbers as decimal text even for hex devices (X Y B W SB SW DX DY ZR), as
+  pymcprotocol does ("compat"). The manual's hex policy is not implemented.
+- ASCII dword word order: default swapped (low word first); --ascii-dword-order client keeps high first.
+  The real order is unverified; round trips are symmetric but batch word views differ.
+- The lock is server-wide, survives disconnects and gates only run/stop/pause/latch clear/reset. It is
+  not authentication.
+- iQ-R native dword devices (LTN LSTN LCN LZ) use one 32-bit point per address; word access streams the
+  low/high halves. The stride is unverified.
+- Timers and counters hold plain values; no PLC logic executes. The monitoring timer is parsed and ignored.
+  Every network/PC/station route aliases one memory.
+- Error codes are design values; C200 and C201 may be swapped. Z devices are unsupported.
+- Faults act after execution: a faulted write or reset has already happened.
+""".strip("\n")
+
+PROSE = {"run": RUN, "client": CLIENT, "troubleshoot": TROUBLESHOOT, "divergences": DIVERGENCES}
+
+CONNECT = """
+Connect (python -m pip install pymcprotocol):
+  from pymcprotocol import Type3E
+  c = Type3E(plctype="Q"); c.connect("127.0.0.1", 5000)
+  c.batchwrite_wordunits("D0", [123, -45]); print(c.batchread_wordunits("D0", 2)); c.close()
+""".strip("\n")
+
+PITFALLS = """
+Pitfalls (fix):
+  1. "cannot listen" (exit 1): port busy -> choose another --port, or --port 0 and read the stderr banner.
+  2. iQ-R errors: the client plctype and --profile must both be iQ-R (Q-class names share one wire format).
+  3. CPU name contains NUL bytes: the default fill is 0x00 -> start with --text-pad 0x20.
+  4. Big reads fail in pymcprotocol (one recv of 4096 bytes) -> keep batches under ~1000 words.
+  5. Reset or latch clear returns an error: both need STOP -> start with --initial-state STOP.
+""".strip("\n")
+
+OPTIONS_HEAD = "Options: flag, default ('-' = none), meaning. Bad values exit 2 with an error that ends in 'see: virtual-plc guide TOPIC'."
+OPTIONS_TAIL = ("DEV:LO-HI repeats (--limit D:0-99 --limit M:0-15); its endpoints and --text-pad accept 0x notation.\n"
+                "Same data for programs: virtual-plc guide options --json")
+
+FAULTS_HEAD = """
+Faults change how replies are delivered AFTER the command ran; writes are never rolled back. Opt in with
+--fault-plan FILE or Server(fault_plan=FaultPlan(steps)); without a plan nothing is matched or delayed.
+Schema: {"steps": [STEP, ...]} in a file (no other root keys); Python takes the list. A bad plan exits 2 before bind.
+STEP = {"match": {...}, "times": N, "action": {"type": T, ...}}; match and times are optional (times defaults to 1).
+match keys, ANDed: command (int or "0x0619"), connection (1 = first accepted), nth (1 = first request on it).
+The first step that matches and has uses left wins; one step applies per request.
+Actions (parameters; [optional]):
+""".strip("\n")
+
+FAULTS_TAIL = """
+Examples (each line is a complete valid file):
+  {"steps": [{"match": {"command": "0x0619"}, "action": {"type": "delay", "seconds": 0.5}}]}
+  {"steps": [{"match": {"command": "0x0401"}, "times": 2, "action": {"type": "bad_end_code", "code": 49241}}]}
+  {"steps": [{"match": {"connection": 1, "nth": 1}, "action": {"type": "truncate", "n": 1}}]}
+Reset test: --initial-state STOP plus {"steps": [{"match": {"command": "0x1006"}, "action": {"type": "rst"}}]}
+makes the client reconnect after about 1 s. Give silent_hold its own connection.
+""".strip("\n")
+
+MEMORY_HEAD = """
+Memory JSON: --init FILE loads it before listening; --dump-on-exit FILE saves it after a graceful stop.
+Schema: {"DEVICE": {"HEAD": [values, ...]}}; HEAD is a decimal string and values fill consecutive points.
+  {"D": {"100": [1, 2, 3]}, "M": {"0": [1, 0, 1]}}
+  {"LTN": {"7": [305419896]}}
+Values are unsigned native points: bit 0/1, word 0..65535, dword 0..4294967295 (never signed numbers).
+The whole snapshot is validated before anything is applied; an invalid file exits 2.
+Dumps use the same schema: contiguous runs, explicit zeros kept, plus SD203 (CPU state: STOP=0 RUN=1 PAUSE=2).
+Device names by kind (Q-class profiles lack LT*/LST*/LC*/LZ/RD; see guide profiles):
+""".strip("\n")
+
+MEMORY_TAIL = """
+--limit DEV:LO-HI (repeatable) sets the inclusive valid points of a device; requests outside get an error.
+--latch-range DEV:LO-HI (repeatable) selects latch ranges; default: all of L. SM and SD are never cleared.
+Latch ranges are cleared by latchclear and preserved by remote_run(clear_mode=1).
+Example: virtual-plc --init seed.json --limit D:0-102 --latch-range D:100-101 --dump-on-exit saved.json
+Word access to a bit device needs a head divisible by 16 (a word read of M16 returns M16..M31).
+Bit access to a word device is rejected. Python: Memory.load(dict) and Memory.dump(); see guide embed.
+""".strip("\n")
+
+
+def option_topic(names):
+    """Topic for an argparse argument name such as '--limit' or '-v/--verbose'."""
+    return next((OPTION_TOPICS[name] for name in names.split("/") if name in OPTION_TOPICS), "options")
+
+
+def _option_rows(parser):
+    return [{
+        "name": action.option_strings[-1],
+        "flags": action.option_strings,
+        "metavar": (action.metavar or action.dest.upper()) if action.nargs != 0 else None,
+        "default": None if action.default is argparse.SUPPRESS else action.default,
+        "choices": list(action.choices) if action.choices else None,
+        "help": action.help,
+    } for action in parser._actions]
+
+
+def _default_text(row):
+    default = row["default"]
+    if default is None or default == []:
+        return "-"
+    return "off" if default is False else str(default)
+
+
+def _option_line(row):
+    label = ", ".join(row["flags"]) + (" " + row["metavar"] if row["metavar"] else "")
+    choices = " [" + "|".join(row["choices"]) + "]" if row["choices"] else ""
+    return f"  {label} | {_default_text(row)} | {row['help']}{choices}"
+
+
+def _options(parser):
+    return "\n".join([OPTIONS_HEAD, *map(_option_line, _option_rows(parser)), OPTIONS_TAIL])
+
+
+def _overview(parser):
+    return "\n".join([
+        f"virtual-plc: local Mitsubishi MC-protocol PLC simulator (3E/4E, binary/ASCII; profiles {', '.join(PROFILES)})"
+        " for client tests. Localhost only.",
+        "Run:", RECIPE_LINES,
+        "Options (flag | default | meaning; details: virtual-plc guide options):",
+        *map(_option_line, _option_rows(parser)), CONNECT,
+        f"Topics (virtual-plc guide TOPIC [--json]): {' '.join(TOPICS)}", PITFALLS,
+    ])
+
+
+def _profile_commands():
+    return {profile.name: supported_commands(profile) for profile in PROFILES.values()}
+
+
+def _profiles(parser):
+    commands = _profile_commands()
+    lines = [f"Frames {' '.join(FRAMES)} x encodings {' '.join(WIRES)}: every command works on all four pairs, "
+             "even mixed on one connection.", f"Code  {'Command':<30}Profiles"]
+    for code in sorted({code for codes in commands.values() for code in codes}):
+        names = [name for name, codes in commands.items() if code in codes]
+        where = "all" if len(names) == len(PROFILES) else " ".join(names)
+        lines.append(f"{code:04X}  {COMMAND_NAMES[code]:<30}{where}")
+    groups = {}
+    for profile in PROFILES.values():
+        groups.setdefault((profile.wire_class, tuple(profile.devices)), []).append(profile)
+    for (wire_class, devices), members in groups.items():
+        wire = members[0].wire
+        size = str(wire.password_min) if wire.password_min == wire.password_max else f"{wire.password_min}-{wire.password_max}"
+        lines.append(f"{', '.join(profile.name for profile in members)}: {wire_class} wire, password {size} chars, devices:")
+        lines.append(textwrap.fill(" ".join(devices), 100, initial_indent="  ", subsequent_indent="  "))
+    lines.append("Client plctype must equal --profile for iQ-R; Q-class profiles differ only in CPU identity and code.")
+    return "\n".join(lines)
+
+
+def _profile_data():
+    commands = _profile_commands()
+    return {"frames": list(FRAMES), "encodings": list(WIRES), "profiles": [{
+        "name": profile.name, "wire_class": profile.wire_class, "cpu_name": profile.cpu_name,
+        "devices": [{"name": device.name, "kind": device.kind} for device in profile.devices.values()],
+        "commands": [f"{code:04X}" for code in commands[profile.name]],
+    } for profile in PROFILES.values()]}
+
+
+def _embed(parser):
+    keywords = ", ".join(inspect.signature(Server).parameters)
+    return f"""
+Embed in Python (stdlib only). Leaving the with-block stops the server and joins its workers.
+  from virtual_plc import Server, Memory, FaultPlan
+  memory = Memory()                     # Memory("iQ-R"); Memory(limits=dict(D=(0, 99)))
+  memory.write_words("D", 0, [123])     # seed BEFORE start
+  with Server(memory=memory, port=0) as server:   # port 0 = free port
+      host, port = server.address       # connect clients here
+  snapshot = memory.dump()              # AFTER stop; same JSON schema as --init
+Server keywords: {keywords}.
+Bad values raise ValueError before binding; Server(profile=...) and Memory(profile) must match.
+Memory API: read_words/write_words/read_bits/write_bits(device, head, ...), load(dict), dump().
+Live state: server.state ("RUN"/"STOP"/"PAUSE"), server.set_state(s), server.reset_count, server.locked.
+Memory calls are not synchronized with wire requests: never load, mutate or dump while serving; use a client.
+FaultPlan(steps) or FaultPlan.from_file(path) -> Server(fault_plan=...); schema: virtual-plc guide faults.
+response_hook(bytes) -> bytes transforms every complete reply before it is sent.
+pytest fixture:
+  import pytest
+  from pymcprotocol import Type3E
+  from virtual_plc import Server, Memory
+
+  @pytest.fixture
+  def plc():
+      memory = Memory()
+      memory.write_words("D", 0, [123])
+      with Server(memory=memory, port=0) as server:
+          yield server
+
+  def test_seeded(plc):
+      client = Type3E(plctype="Q")
+      try:
+          client.connect(*plc.address)
+          assert client.batchread_wordunits("D0", 1) == [123]
+      finally:
+          client.close()
+""".strip("\n")
+
+
+def _faults(parser):
+    actions = []
+    for kind, (required, optional) in ACTION_FIELDS.items():
+        parts = sorted(required) + [f"[{name}]" for name in sorted(optional)]
+        signature = f"{kind}({', '.join(parts)})" if parts else kind
+        actions.append(f"  {signature:<34}{EFFECTS[kind]}")
+    return "\n".join([FAULTS_HEAD, *actions, FAULTS_TAIL])
+
+
+def _memory(parser):
+    largest = max(PROFILES.values(), key=lambda profile: len(profile.devices))
+    kinds = {}
+    for device in largest.devices.values():
+        kinds.setdefault(device.kind, []).append(device.name)
+    return "\n".join([MEMORY_HEAD, *(f"  {kind}: {' '.join(names)}" for kind, names in kinds.items()), MEMORY_TAIL])
+
+
+GENERATED = {None: _overview, "options": _options, "profiles": _profiles, "embed": _embed,
+             "faults": _faults, "memory": _memory}
+
+
+def render(parser, topic=None):
+    """Text of one topic (None = overview); `parser` supplies the option table."""
+    return PROSE[topic] if topic in PROSE else GENERATED[topic](parser)
+
+
+def data(parser, topic=None):
+    """JSON-ready document: text, or structured rows for the options and profiles topics."""
+    document = {"version": __version__, "topic": topic or "overview"}
+    if topic == "options":
+        document["options"] = _option_rows(parser)
+    elif topic == "profiles":
+        document.update(_profile_data())
+    else:
+        document["text"] = render(parser, topic)
+    return document
+
+
+def main(argv, parser):
+    """Print one guide topic and return the exit status (2 for an unknown topic)."""
+    arguments = argparse.ArgumentParser(prog="virtual-plc guide", description="Usage guide for humans and AI agents.")
+    arguments.add_argument("topic", nargs="?", help="one of: " + " ".join(TOPICS))
+    arguments.add_argument("--json", action="store_true", help="print JSON instead of text")
+    args = arguments.parse_args(argv)
+    if args.topic is not None and args.topic not in TOPICS:
+        print(f"unknown topic {args.topic!r}; topics: {', '.join(TOPICS)}", file=sys.stderr)
+        return 2
+    print(json.dumps(data(parser, args.topic)) if args.json else render(parser, args.topic))
+    return 0

virtual_plc/memory.py

@@ -0,0 +1,145 @@
+"""Sparse device storage and atomic request operations (M1)."""
+
+from copy import deepcopy
+
+from .profiles import PROFILES
+
+
+class OutOfRange(ValueError):
+    """Access outside the configured device range."""
+
+
+class Memory:
+    """Unsigned point storage per device family; bit devices hold one bit per point."""
+
+    def __init__(self, profile="Q", limits=None):
+        self.profile = PROFILES[profile]
+        self._limits = {name: (spec.minimum, spec.maximum) for name, spec in self.profile.devices.items()}
+        for name, span in (limits or {}).items():
+            spec = self.profile.devices.get(name)
+            if (spec is None or not isinstance(span, (tuple, list)) or len(span) != 2 or any(type(value) is not int for value in span)
+                    or not spec.minimum <= span[0] <= span[1] <= spec.maximum):
+                raise ValueError("invalid memory limit")
+            self._limits[name] = tuple(span)
+        self._cells = {name: {} for name in self.profile.devices}
+
+    def read_words(self, device, head, count):
+        spec = self.check(device, head, count, "word")
+        if spec.kind == "word":
+            return self._load(device, head, count)
+        if spec.kind == "dword":
+            cells = self._cells[device]
+            return [(cells.get(head + i // 2, 0) >> (16 * (i % 2))) & 0xFFFF for i in range(count)]
+        bits = self._load(device, head, count * 16)
+        return [sum(bit << i for i, bit in enumerate(bits[j:j + 16])) for j in range(0, len(bits), 16)]
+
+    def read_bits(self, device, head, count):
+        self.check(device, head, count, "bit")
+        return self._load(device, head, count)
+
+    def write_words(self, device, head, values):
+        values = list(values)
+        if not all(0 <= value <= 0xFFFF for value in values):
+            raise ValueError("word out of range")
+        spec = self.check(device, head, len(values), "word")
+        if spec.kind == "dword":
+            # Heads address native 32-bit points; word counts stream low/high halves.
+            cells = self._cells[device]
+            for i, value in enumerate(values):
+                point, shift = head + i // 2, 16 * (i % 2)
+                cells[point] = (cells.get(point, 0) & ~(0xFFFF << shift)) | (value << shift)
+            return
+        if spec.kind == "bit":
+            values = [value >> i & 1 for value in values for i in range(16)]
+        self._store(device, head, values)
+
+    def write_bits(self, device, head, values):
+        values = list(values)
+        if not all(value in (0, 1) for value in values):
+            raise ValueError("bit must be 0 or 1")
+        self.check(device, head, len(values), "bit")
+        self._store(device, head, values)
+
+    def check(self, device, head, count, unit):
+        """Validate one access; `count` is in `unit`s. Returns the device spec."""
+        spec = self.profile.devices.get(device)
+        if spec is None or count <= 0:
+            raise ValueError(f"invalid access to {device} x{count}")
+        points = count
+        if unit == "bit" and spec.kind != "bit":
+            raise ValueError(f"bit access to word device {device}")
+        if unit == "word" and spec.kind == "bit":
+            if head % 16:
+                raise ValueError("word view of a bit device needs a head that is a multiple of 16")
+            points = count * 16
+        if unit == "word" and spec.kind == "dword":
+            points = (count + 1) // 2
+        minimum, maximum = self._limits[device]
+        if head < minimum or head + points - 1 > maximum:
+            raise OutOfRange(f"{device}{head} x{points} outside {minimum}..{maximum}")
+        return spec
+
+    def _load(self, device, head, count):
+        cells = self._cells[device]
+        return [cells.get(head + i, 0) for i in range(count)]
+
+    def _store(self, device, head, values):
+        self._cells[device].update(enumerate(values, head))
+
+    def clear(self, latch_ranges, mode):
+        """Clear stored points only; the server holds its request lock.
+
+        mode is latch, non_latch, or all. Special devices are always preserved.
+        """
+        for device, cells in self._cells.items():
+            if device in {"SM", "SD"}:
+                continue
+            for head in list(cells):
+                latched = any(low <= head <= high for low, high in latch_ranges.get(device, ()))
+                if mode == "all" or (mode == "latch" and latched) or (mode == "non_latch" and not latched):
+                    del cells[head]
+
+
+    def dump(self):
+        """Return stored points as JSON-compatible contiguous runs (native units).
+
+        Call before start or after stop; direct Memory access is not synchronized.
+        """
+        result = {}
+        for name, cells in self._cells.items():
+            runs = {}
+            previous = None
+            for head, value in sorted(cells.items()):
+                if previous is None or head != previous + 1:
+                    values = []
+                    runs[str(head)] = values
+                values.append(value)
+                previous = head
+            if runs:
+                result[name] = runs
+        return result
+
+    def load(self, data):
+        """Validate a complete snapshot before overlaying it; use before start.
+
+        Values are unsigned bits/words/native dwords, not client signed values.
+        """
+        if not isinstance(data, dict):
+            raise ValueError("memory snapshot must be an object")
+        staged = Memory(self.profile.name, self._limits)
+        staged._cells = deepcopy(self._cells)
+        for name, runs in data.items():
+            spec = self.profile.devices.get(name)
+            if spec is None or not isinstance(runs, dict):
+                raise ValueError("invalid snapshot device or runs")
+            for address, values in runs.items():
+                if not isinstance(address, str) or not isinstance(values, list) or not values:
+                    raise ValueError("snapshot runs need decimal address keys and nonempty lists")
+                head = int(address, 10)
+                maximum = {"bit": 1, "word": 65535, "dword": 0xFFFFFFFF}[spec.kind]
+                if any(type(value) is not int or not 0 <= value <= maximum for value in values):
+                    raise ValueError("snapshot value out of range")
+                if spec.kind == "dword":
+                    values = [half for value in values for half in (value & 0xFFFF, value >> 16)]
+                (staged.write_bits if spec.kind == "bit" else staged.write_words)(name, head, values)
+        self._cells = staged._cells