CANConfigPython 0.1.0a1__py3-none-win_amd64.whl

canconfigpython/__init__.py

@@ -0,0 +1,7 @@
+"""CANConfigPython: subprocess-isolated CAN device configuration."""
+__version__ = "0.1.0a1"
+
+from .client import Client
+from .errors import ConfigError
+
+__all__ = ["Client", "ConfigError", "__version__"]

canconfigpython/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

canconfigpython/cli.py

@@ -0,0 +1,111 @@
+import argparse
+import json
+import os
+import sys
+from . import __version__
+from .client import Client
+from .commands import COMMANDS, AUTH, BOOLS
+from .errors import ConfigError, envelope
+from .resources import export
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        # argparse's raw error can echo sensitive accidental positional arguments.
+        raise ConfigError("invalid_arguments", "Invalid, duplicate or missing arguments; use canconfig --help or canconfig COMMAND --help.")
+
+
+def parser():
+    p = Parser(prog="canconfig", description="CANConfigPython: bundled Qt/WIICAN console backend.", allow_abbrev=False)
+    p.add_argument("--version", action="store_true")
+    p.add_argument("--json", action="store_true", help="emit one compact UTF-8 JSON result")
+    sub = p.add_subparsers(dest="command", parser_class=Parser)
+    descriptions = {
+        "info": "Read identity and capabilities; connection may change device run mode.",
+        "validate": "Validate an INI backup offline.",
+        "export": "Export an INI backup; a successful export replaces an existing file.",
+        "restore": "Restore an INI backup and verify readback.",
+        "apply": "Apply a UTF-8 JSON patch and verify readback.",
+        "change-password": "Change the password of the explicitly identified device.",
+        "firmware-update": "Transfer an .sfb firmware package to a device already in update mode.",
+        "schema": "Show the descriptive backend contract (not a JSON Schema document).",
+    }
+    for name, (allowed, required) in COMMANDS.items():
+        command = sub.add_parser(name, help=descriptions[name], description=descriptions[name], allow_abbrev=False)
+        command.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+        for option in sorted(allowed):
+            kwargs = {"required": option in required, "default": argparse.SUPPRESS}
+            if option in BOOLS:
+                kwargs["action"] = "store_true"
+                kwargs["help"] = "firmware: file-only checks; configuration: live preflight" if option == "dry_run" else None
+            elif option == "timeout_ms":
+                kwargs["type"] = int
+                kwargs["help"] = "backend deadline in milliseconds (default 120000)"
+            command.add_argument("--" + option.replace("_", "-"), **kwargs)
+        if name in AUTH:
+            command.add_argument("--password-env", required=True, help="name of an environment variable; never the password itself")
+        if name == "change-password":
+            command.add_argument("--new-password-env", required=True)
+    doctor = sub.add_parser("doctor", help="Check bundled libraries without opening devices.", allow_abbrev=False)
+    doctor.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+    for name in ("docs", "skill"):
+        group = sub.add_parser(name, help="Export bundled " + name + " to a new directory.", allow_abbrev=False)
+        actions = group.add_subparsers(dest="action", required=True, parser_class=Parser)
+        action = actions.add_parser("export", allow_abbrev=False)
+        action.add_argument("--output", required=True)
+        action.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+    return p
+
+
+def _emit(result, compact):
+    text = json.dumps(result, ensure_ascii=False, allow_nan=False, indent=None if compact else 2) + "\n"
+    if hasattr(sys.stdout, "buffer"):
+        sys.stdout.buffer.write(text.encode("utf-8"))
+        sys.stdout.buffer.flush()
+    else:
+        sys.stdout.write(text)
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    compact = "--json" in argv
+    command = ""
+    try:
+        seen = set()
+        for arg in argv:
+            if arg.startswith("--"):
+                key = arg.split("=", 1)[0]
+                if key in seen:
+                    raise ConfigError("duplicate_argument", "An option was specified more than once.")
+                seen.add(key)
+        args = vars(parser().parse_args(argv))
+        compact = args.pop("json")
+        command = args.pop("command") or ""
+        version = args.pop("version")
+        if version:
+            if command:
+                raise ConfigError("invalid_arguments", "--version cannot be combined with a command.")
+            result = envelope("version", data={"version": __version__, "backend": "2.3", "bridge_api": 1})
+        elif command == "doctor":
+            result = Client().doctor()
+        elif command in ("docs", "skill"):
+            result = envelope(command, data=export(command, args["output"]))
+        elif command:
+            old = args.pop("password_env", None)
+            new = args.pop("new_password_env", None)
+            if new and old.casefold() == new.casefold():
+                raise ConfigError("invalid_arguments", "Old and new password environment names must differ.")
+            password = os.environ.get(old) if old else None
+            new_password = os.environ.get(new) if new else None
+            result = Client().execute(command, password=password, new_password=new_password, **args)
+        else:
+            parser().print_help()
+            return 0
+    except ConfigError as exc:
+        result = envelope(command, exc.exit_code, exc.code, exc.message)
+    except KeyboardInterrupt:
+        result = envelope(command, 12, "cancelled", "Cancelled before starting a device operation.")
+    except OSError:
+        result = envelope(command, 3, "local_io_failed", "Local file access failed before device execution.")
+    _emit(result, compact)
+    return result["exit_code"]

canconfigpython/client.py

@@ -0,0 +1,243 @@
+import contextlib
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import signal
+import stat
+import subprocess
+import sys
+import tempfile
+from . import commands
+from .errors import ConfigError, envelope
+from .runtime import inspect_runtime, child_environment, BACKEND_VERSION, BRIDGE_API
+
+MAX_PATCH = 8 * 1024 * 1024
+
+
+def _unique(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate key")
+        result[key] = value
+    return result
+
+
+def _constant(value):
+    raise ValueError("nonfinite number")
+
+
+def strict_json(data):
+    def finite(value):
+        number = float(value)
+        if not math.isfinite(number):
+            raise ValueError("nonfinite number")
+        return number
+    return json.loads(data, object_pairs_hook=_unique, parse_constant=_constant, parse_float=finite)
+
+
+def _password(value):
+    try:
+        valid = isinstance(value, str) and 1 <= len(value.encode("utf-8")) <= 10 and "\x00" not in value
+    except UnicodeError:
+        valid = False
+    if not valid:
+        raise ConfigError("invalid_credentials", "Passwords must contain 1 to 10 UTF-8 bytes without NUL.", 2)
+    return value
+
+
+@contextlib.contextmanager
+def _port_lock(port):
+    """Per-user OS lock shared by all Python wrapper instances. Never unlink it."""
+    user = str(os.getuid()) if hasattr(os, "getuid") else os.environ.get("USERNAME", "")
+    digest = hashlib.sha256((user + "\0" + port).encode("utf-8")).hexdigest()
+    path = Path(tempfile.gettempdir()) / ("canconfigpython-" + digest + ".lock")
+    try:
+        stream = open(str(path), "a+b")
+    except OSError:
+        raise ConfigError("lock_failed", "Cannot create the per-user device lock.", 1)
+    locked = False
+    try:
+        if os.name == "nt":
+            import msvcrt
+            stream.seek(0, os.SEEK_END)
+            if stream.tell() == 0:
+                stream.write(b"\0")
+                stream.flush()
+            stream.seek(0)
+            try:
+                msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK, 1)
+                locked = True
+            except OSError:
+                pass
+        else:
+            import fcntl
+            try:
+                fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                locked = True
+            except OSError:
+                pass
+        if not locked:
+            raise ConfigError("device_busy", "Another CANConfigPython operation is using this port.", 1)
+        yield
+    finally:
+        if locked:
+            if os.name == "nt":
+                stream.seek(0)
+                msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(stream, fcntl.LOCK_UN)
+        stream.close()
+
+
+def _stop(process):
+    try:
+        process.send_signal(signal.CTRL_BREAK_EVENT if os.name == "nt" else signal.SIGINT)
+        return process.communicate(timeout=5)
+    except (OSError, subprocess.TimeoutExpired, KeyboardInterrupt):
+        try:
+            process.kill()
+        except OSError:
+            pass  # Process may have exited between signal and kill.
+        return process.communicate()
+
+
+def _run(executable, command, args, env, timeout, hardware):
+    kwargs = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if os.name == "nt" else {"start_new_session": True}
+    try:
+        process = subprocess.Popen(
+            [str(executable), command] + args + ["--json"],
+            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            env=env, shell=False, **kwargs)
+    except OSError:
+        return envelope(command, 1, "backend_start_failed", "Cannot start the bundled backend; run canconfig doctor.")
+    stopped = None
+    try:
+        output, _stderr = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        stopped = "backend_timeout"
+        output, _stderr = _stop(process)
+    except KeyboardInterrupt:
+        stopped = "cancelled"
+        output, _stderr = _stop(process)
+    # Never echo unstructured driver diagnostics or arguments containing input data.
+    try:
+        result = strict_json(output.decode("utf-8"))
+        if (not isinstance(result, dict) or type(result.get("schema_version")) is not int or result.get("schema_version") != 1
+                or result.get("command") != command
+                or type(result.get("exit_code")) is not int
+                or not 0 <= result["exit_code"] <= 12
+                or type(result.get("ok")) is not bool
+                or result["ok"] != (result["exit_code"] == 0)
+                or process.returncode != result["exit_code"]
+                or not isinstance(result.get("data"), dict)
+                or not isinstance(result.get("verification"), dict)
+                or not isinstance(result.get("effects"), dict)):
+            raise ValueError("envelope")
+        effects = result["effects"]
+        if effects.get("status") not in ("none", "partial", "unknown", "applied", "transferred"):
+            raise ValueError("effects")
+        for key in ("attempted", "submitted", "acknowledged", "save_acknowledged"):
+            if type(effects.get(key)) is not int or effects[key] < 0:
+                raise ValueError("count")
+        return result
+    except (UnicodeError, ValueError, TypeError, KeyError):
+        code = 8 if hardware else 12 if stopped == "cancelled" else 11 if stopped else 4
+        return envelope(command, code, stopped or "backend_protocol_error",
+                        "No valid final backend result. Stop; do not automatically retry or roll back.",
+                        unknown=hardware)
+
+
+class Client:
+    """Synchronous API; one backend process per call. No automatic retries.
+
+    execute() returns the complete result including nonzero backend exit codes.
+    Local validation/runtime failures raise ConfigError before device execution.
+    """
+    def __init__(self):
+        self._runtime = None
+
+    def _prepare(self):
+        return inspect_runtime(self._runtime)
+
+    def doctor(self):
+        executable, manifest = self._prepare()
+        result = _run(executable, "runtime-check", [], child_environment(executable.parent), 15, False)
+        result["command"] = "doctor"
+        if result["ok"] and (result["data"].get("version") != BACKEND_VERSION
+                             or result["data"].get("bridge_api") != BRIDGE_API):
+            return envelope("doctor", 1, "backend_version_mismatch", "Bundled backend has an incompatible contract.")
+        result["data"]["runtime_manifest"] = manifest
+        return result
+
+    def execute(self, command, *, password=None, new_password=None, **options):
+        options = commands.validate(command, options)
+        secrets = []
+        credential_args = []
+        if command in commands.AUTH:
+            secrets.append(("CANCONFIGPY_PASSWORD", _password(password)))
+            credential_args += ["--password-env", "CANCONFIGPY_PASSWORD"]
+        elif password is not None:
+            raise ConfigError("invalid_arguments", "This command does not accept a password.")
+        if command == "change-password":
+            secrets.append(("CANCONFIGPY_NEW_PASSWORD", _password(new_password)))
+            credential_args += ["--new-password-env", "CANCONFIGPY_NEW_PASSWORD"]
+        elif new_password is not None:
+            raise ConfigError("invalid_arguments", "Only change-password accepts a new password.")
+        executable, _manifest = self._prepare()
+        # Check protocol and dynamic dependencies offline before any device operation.
+        probe = self.doctor()
+        if not probe["ok"]:
+            probe["command"] = command
+            return probe
+        hardware = command in commands.HARDWARE and not (
+            command == "firmware-update" and options.get("dry_run", False))
+        if hardware and sys.platform.startswith("linux"):
+            try:
+                selected = Path(options["port"]).resolve(strict=True)
+                if not str(selected).startswith("/dev/") or not stat.S_ISCHR(selected.stat().st_mode):
+                    raise OSError("not a serial character device")
+                options["port"] = str(selected)
+            except OSError:
+                raise ConfigError("port_not_found", "Selected /dev/ serial path is missing or is not a character device.", 1)
+        with contextlib.ExitStack() as stack:
+            if hardware:
+                stack.enter_context(_port_lock(options["port"]))
+            if command == "apply":
+                try:
+                    with open(options["file"], "rb") as stream:
+                        source = stream.read(MAX_PATCH + 1)
+                    if len(source) > MAX_PATCH:
+                        raise ValueError("size")
+                    patch = strict_json(source.decode("utf-8"))
+                    if (not isinstance(patch, dict) or set(patch) != {"schema_version", "device_uid", "changes"}
+                            or type(patch["schema_version"]) is not int or patch["schema_version"] != 1
+                            or not isinstance(patch["device_uid"], str)
+                            or not isinstance(patch["changes"], dict)):
+                        raise ValueError("shape")
+                    encoded = json.dumps(patch, ensure_ascii=False, allow_nan=False).encode("utf-8")
+                except OSError:
+                    raise ConfigError("file_read_failed", "Cannot read the JSON patch.", 3)
+                except (UnicodeError, ValueError, RecursionError):
+                    raise ConfigError("invalid_patch", "Use a UTF-8 JSON patch without BOM, duplicate keys or nonfinite numbers; required keys: schema_version, device_uid, changes. Maximum 8 MiB.", 7)
+                # Pass an immutable snapshot of exactly the JSON that passed strict parsing.
+                directory = stack.enter_context(tempfile.TemporaryDirectory(prefix="canconfig-patch-"))
+                snapshot = Path(directory) / "changes.json"
+                snapshot.write_bytes(encoded)
+                options["file"] = str(snapshot)
+            args = list(credential_args)
+            for key, value in options.items():
+                if value is False:
+                    continue
+                args.append("--" + key.replace("_", "-"))
+                if value is not True:
+                    args.append(str(value))
+            env = child_environment(executable.parent, secrets)
+            try:
+                return _run(executable, command, args, env,
+                            options.get("timeout_ms", 120000) / 1000.0 + 8, hardware)
+            finally:
+                for key, _value in secrets:
+                    env.pop(key, None)

canconfigpython/commands.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+import re
+import sys
+from .errors import ConfigError
+
+COMMON = {"timeout_ms"}
+DEVICE = COMMON | {"port", "expect_uid"}
+AUTH = {"export", "restore", "apply", "change-password"}
+HARDWARE = AUTH | {"info", "firmware-update"}
+COMMANDS = {
+    "info": (DEVICE, {"port"}),
+    "validate": (COMMON | {"file", "sections"}, {"file"}),
+    "export": (DEVICE | {"file", "sections"}, {"port", "file"}),
+    "restore": (DEVICE | {"file", "sections", "dry_run", "check_device"}, {"port", "file"}),
+    "apply": (DEVICE | {"file", "dry_run"}, {"port", "file"}),
+    "change-password": (DEVICE | {"dry_run"}, {"port", "expect_uid"}),
+    "firmware-update": (COMMON | {"port", "file", "dry_run", "expect_sha256", "expect_usb_serial", "no_dtr"}, {"port", "file"}),
+    "schema": (set(), set()),
+}
+BOOLS = {"dry_run", "check_device", "no_dtr"}
+
+
+def validate(command, options):
+    if command not in COMMANDS:
+        raise ConfigError("invalid_command", "Unknown command; use canconfig --help.")
+    allowed, required = COMMANDS[command]
+    if set(options) - allowed or not required <= set(options):
+        raise ConfigError("invalid_arguments", "Missing or unsupported options for this command.")
+    result = {}
+    for key, value in options.items():
+        if key in BOOLS:
+            if type(value) is not bool:
+                raise ConfigError("invalid_arguments", "Boolean options require true or false.")
+        elif key == "timeout_ms":
+            if type(value) is not int or not 1 <= value <= 3600000:
+                raise ConfigError("invalid_timeout", "timeout_ms must be between 1 and 3600000.")
+        else:
+            if isinstance(value, Path):
+                value = str(value)
+            if not isinstance(value, str) or not value or "\x00" in value or value.startswith("--"):
+                raise ConfigError("invalid_arguments", "Options require nonempty strings without NUL.")
+        result[key] = value
+    if "port" in result:
+        value = result["port"]
+        if sys.platform == "win32":
+            match = re.fullmatch(r"(?:COM)?([0-9]+)", value, re.IGNORECASE)
+            if not match or not 1 <= int(match[1]) <= 65535:
+                raise ConfigError("invalid_port", "Use an explicit COM port, for example COM3.")
+            result["port"] = "COM" + str(int(match[1]))
+        elif sys.platform.startswith("linux"):
+            if not value.startswith("/dev/") or ".." in Path(value).parts:
+                raise ConfigError("invalid_port", "Use an absolute /dev/ serial device path.")
+        else:
+            raise ConfigError("unsupported_platform", "This release supports Windows and Linux.", 5)
+    if "expect_uid" in result and not re.fullmatch(r"[0-9a-fA-F]{4}(?:-[0-9a-fA-F]{4}){5}", result["expect_uid"]):
+        raise ConfigError("invalid_uid", "UID must contain six groups of four hexadecimal digits.")
+    return result

canconfigpython/errors.py

@@ -0,0 +1,19 @@
+class ConfigError(Exception):
+    """A local error before any backend operation was started."""
+    def __init__(self, code, message, exit_code=9):
+        super().__init__(message)
+        self.code, self.message, self.exit_code = code, message, exit_code
+
+
+def envelope(command, code=0, error=None, message=None, data=None, unknown=False):
+    count = None if unknown else 0
+    result = {
+        "schema_version": 1, "command": command, "ok": code == 0, "exit_code": code,
+        "data": data or {},
+        "effects": {key: count for key in ("attempted", "submitted", "acknowledged", "save_acknowledged")},
+        "verification": {"readback": "not_verified", "power_cycle": "not_verified"},
+    }
+    result["effects"]["status"] = "unknown" if unknown else "none"
+    if error:
+        result["error"] = {"code": error, "message": message, "automatic_retry_allowed": False}
+    return result