gomc-rest 0.1.0__py3-none-win_amd64.whl

gomc_rest/__init__.py

@@ -0,0 +1,103 @@
+"""gomc-rest (Python, Pattern B).
+
+Bundles the gomc-rest server binary and offers two entry points over the same
+PLCClient (from gomc-rest-client):
+
+* ``launch()`` — auto-start the bundled server as a subprocess (optionally
+  exposed to the network) and talk to it.
+* ``connect()`` — act as a client to a gomc-rest server that is already
+  running elsewhere, without starting anything.
+
+The HTTP layer is provided entirely by gomc-rest-client; this package only adds
+binary bundling and process lifecycle.
+
+    import gomc_rest
+
+    with gomc_rest.launch(plc_host="192.168.0.1") as plc:
+        plc.read("D100", 3)
+
+    plc = gomc_rest.connect("http://192.168.0.1:8080", token="...")
+    plc.read("D100", 3)
+"""
+
+from __future__ import annotations
+
+from gomc_rest_client import (
+    GomcRestBusyError,
+    GomcRestPLCProtocolError,
+    GomcRestUnauthorizedError,
+    PLCClient,
+)
+
+from ._server import Server
+
+__version__ = "0.1.0"
+
+
+def launch(
+    plc_host: str = "192.168.0.1",
+    plc_port: int = 5007,
+    server_mode: bool = False,
+    token: str | None = None,
+    extra_args: list[str] | None = None,
+    startup_timeout: float = 10.0,
+) -> Server:
+    """Start the bundled gomc-rest server and return a managed Server.
+
+    Use as a context manager to get the PLCClient and auto-stop the server::
+
+        with gomc_rest.launch(plc_host="192.168.0.1") as plc:
+            plc.read("D100", 3)
+
+    A random bearer token is generated per launch and required by the server,
+    so even another process on this host that learns the port cannot call the
+    API. Pass an explicit ``token`` to share with another app, or ``token=""``
+    to disable auth (closed-network use). The token is available as
+    ``server.token``.
+
+    By default the server also binds to loopback only. Set ``server_mode=True``
+    to bind all interfaces and let other apps on the network call the REST API
+    (give them ``server.token``). The server has no TLS — only expose it on a
+    trusted network.
+
+    ``extra_args`` are passed through to the gomc-rest binary (e.g.
+    ``["-enable-remote"]`` or ``["-readonly"]``).
+    """
+    return Server(
+        plc_host=plc_host,
+        plc_port=plc_port,
+        server_mode=server_mode,
+        token=token,
+        extra_args=extra_args,
+        startup_timeout=startup_timeout,
+    )
+
+
+def connect(
+    base_url: str = "http://127.0.0.1:8080",
+    token: str | None = None,
+) -> PLCClient:
+    """Return a PLCClient for a gomc-rest server that is already running.
+
+    Use this to talk to a server started elsewhere — another machine, a shared
+    instance, or one you launched with ``server_mode=True`` — without spawning
+    the bundled binary. Supports the context-manager protocol::
+
+        with gomc_rest.connect("http://192.168.0.1:8080", token="...") as plc:
+            plc.read("D100", 3)
+
+    For the bundled, auto-started server use ``launch()`` instead.
+    """
+    return PLCClient(base_url, token=token)
+
+
+__all__ = [
+    "launch",
+    "connect",
+    "Server",
+    "PLCClient",
+    "GomcRestBusyError",
+    "GomcRestPLCProtocolError",
+    "GomcRestUnauthorizedError",
+    "__version__",
+]

gomc_rest/_binaries.py

@@ -0,0 +1,70 @@
+"""Locate the bundled gomc-rest server binary for the current platform."""
+
+from __future__ import annotations
+
+import platform
+import stat
+from pathlib import Path
+
+_BINARIES_DIR = Path(__file__).parent / "binaries"
+
+# (system, machine) -> bundled binary file name.
+# Machine names are normalised to the keys below before lookup.
+_BINARY_NAMES = {
+    ("windows", "amd64"): "gomc-rest.exe",
+    ("linux", "amd64"): "gomc-rest-linux-amd64",
+    ("linux", "arm64"): "gomc-rest-linux-arm64",
+}
+
+_MACHINE_ALIASES = {
+    "x86_64": "amd64",
+    "amd64": "amd64",
+    "aarch64": "arm64",
+    "arm64": "arm64",
+}
+
+
+def _normalise_platform() -> tuple[str, str]:
+    system = platform.system().lower()
+    machine = _MACHINE_ALIASES.get(platform.machine().lower(), platform.machine().lower())
+    return system, machine
+
+
+def binary_path() -> Path:
+    """Return the path to the bundled server binary for this platform.
+
+    Raises RuntimeError if the platform is unsupported or the binary is missing
+    from the package (e.g. a sdist install without the platform wheel).
+    """
+    system, machine = _normalise_platform()
+    name = _BINARY_NAMES.get((system, machine))
+    if name is None:
+        raise RuntimeError(
+            f"Unsupported platform {system}/{machine}. "
+            f"gomc-rest ships binaries for: {sorted(_BINARY_NAMES)}."
+        )
+
+    path = _BINARIES_DIR / name
+    if not path.exists():
+        raise RuntimeError(
+            f"Bundled server binary '{name}' was not found at {path}. "
+            "Install the platform-specific wheel, or place the binary there "
+            "(see gomc_rest/binaries/README.md)."
+        )
+
+    # Wheels preserve the executable bit set at build time; only repair it when
+    # it is actually missing (e.g. an sdist/VCS checkout). Chmod'ing
+    # unconditionally breaks the common root-installs / non-root-runs setup,
+    # where the running user does not own an already-executable binary.
+    if system != "windows" and not path.stat().st_mode & stat.S_IXUSR:
+        try:
+            mode = path.stat().st_mode
+            path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        except PermissionError as exc:
+            raise RuntimeError(
+                f"Bundled binary {path} is not executable and its permissions "
+                "cannot be changed by this user. Reinstall the wheel or add the "
+                "executable bit."
+            ) from exc
+
+    return path

gomc_rest/_server.py

@@ -0,0 +1,137 @@
+"""Launch and manage the bundled gomc-rest server as a subprocess (Pattern B)."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import secrets
+import socket
+import subprocess
+import time
+
+from gomc_rest_client import PLCClient
+
+from ._binaries import binary_path
+
+
+def _free_port() -> int:
+    """Pick a currently-free TCP port on the loopback interface."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+class Server:
+    """Owns a gomc-rest subprocess and a PLCClient pointed at it.
+
+    Prefer the context-manager form::
+
+        with Server(plc_host="192.168.0.1") as plc:
+            plc.read("D100", 3)
+
+    When not used as a context manager the subprocess is still terminated at
+    interpreter exit via atexit.
+    """
+
+    def __init__(
+        self,
+        plc_host: str = "192.168.0.1",
+        plc_port: int = 5007,
+        server_mode: bool = False,
+        token: str | None = None,
+        extra_args: list[str] | None = None,
+        startup_timeout: float = 10.0,
+    ) -> None:
+        self._port = _free_port()
+        self.base_url = f"http://127.0.0.1:{self._port}"
+
+        # A per-launch random token is generated by default, so even another
+        # process on this host that learns the port cannot call the API without
+        # it. token is None -> generate; token == "" -> disable auth; otherwise
+        # use the given token.
+        if token is None:
+            self.token = secrets.token_urlsafe(24)
+        elif token == "":
+            self.token = None
+        else:
+            self.token = token
+
+        # Default: bind to loopback only, so no other host can reach the
+        # server. server_mode binds all interfaces so other apps on the
+        # network can call the REST API (give them self.token).
+        listen = f":{self._port}" if server_mode else f"127.0.0.1:{self._port}"
+        args = [
+            str(binary_path()),
+            "-listen", listen,
+            "-host", plc_host,
+            "-port", str(plc_port),
+            *(extra_args or []),
+        ]
+        # Pass the token via the environment, not argv, so it is not exposed in
+        # the process list / /proc/<pid>/cmdline. Set GOMCR_TOKEN explicitly
+        # (empty when disabled) so an inherited value can't enable auth on the
+        # server while the client stays unauthenticated.
+        env = os.environ.copy()
+        env["GOMCR_TOKEN"] = self.token or ""
+        self._proc = subprocess.Popen(args, env=env)
+        atexit.register(self.close)
+        self.client = PLCClient(self.base_url, token=self.token)
+        try:
+            self._wait_until_healthy(startup_timeout)
+            self._check_version()
+        except BaseException:
+            # Never leave the subprocess running if startup validation fails;
+            # the caller never receives a Server to close() itself.
+            self.close()
+            raise
+
+    def _wait_until_healthy(self, timeout: float) -> None:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self._proc.poll() is not None:
+                raise RuntimeError(
+                    f"gomc-rest exited during startup (code {self._proc.returncode})."
+                )
+            try:
+                self.client.health()
+                return
+            except Exception:
+                time.sleep(0.1)
+        raise TimeoutError(f"gomc-rest did not become healthy within {timeout}s.")
+
+    def _check_version(self) -> None:
+        if not self.client.is_supported_version():
+            raise RuntimeError(
+                f"Bundled gomc-rest {self.client.version()} is not supported by "
+                "the installed gomc-rest-client. Update the bundled binary."
+            )
+
+    def close(self) -> None:
+        """Release the client session and terminate the subprocess.
+
+        Safe to call more than once.
+        """
+        atexit.unregister(self.close)
+
+        client = getattr(self, "client", None)
+        if client is not None:
+            try:
+                client.__exit__(None, None, None)
+            except Exception:
+                pass
+
+        proc = getattr(self, "_proc", None)
+        if proc is None or proc.poll() is not None:
+            return
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+    def __enter__(self) -> PLCClient:
+        return self.client
+
+    def __exit__(self, *exc) -> None:
+        self.close()

gomc_rest/binaries/.gitignore

@@ -0,0 +1,4 @@
+# Vendored at build time by scripts/vendor_binaries.py — never commit binaries.
+*
+!.gitignore
+!README.md

gomc_rest/binaries/README.md

@@ -0,0 +1,15 @@
+# Bundled server binaries
+
+This directory holds the platform-specific `gomc-rest` server binaries that the
+Python package auto-launches (Pattern B):
+
+| Platform        | File name                |
+| --------------- | ------------------------ |
+| Windows (amd64) | `gomc-rest.exe`          |
+| Linux (amd64)   | `gomc-rest-linux-amd64`  |
+| Linux (arm64)   | `gomc-rest-linux-arm64`  |
+
+The binaries are **not committed to git**. They are vendored in at release time
+from a pinned [gomc-rest](https://github.com/Moge800/gomc-rest) version, and each
+platform wheel ships only its matching binary. `_binaries.py` resolves the
+correct file for the current platform at runtime.

gomc_rest-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: gomc-rest
+Version: 0.1.0
+Summary: Talk to Mitsubishi PLCs from Python over the MC protocol via a bundled, auto-launched gomc-rest server — with optional REST API exposure.
+Project-URL: Homepage, https://github.com/Moge800/gomc_rest_python
+Project-URL: Upstream server, https://github.com/Moge800/gomc-rest
+Project-URL: HTTP client, https://github.com/Moge800/gomc_rest_client
+Author: Moge800
+License: MIT
+License-File: LICENSE
+Keywords: gomc-rest,mc-protocol,mitsubishi,plc,slmp
+Requires-Python: >=3.10
+Requires-Dist: gomc-rest-client<0.11,>=0.10.0
+Description-Content-Type: text/markdown
+
+# gomc-rest (Python)
+
+English / [日本語](https://github.com/Moge800/gomc_rest_python/blob/main/README_JP.md)
+
+**A Python library for talking to Mitsubishi PLCs.** Read and write PLC devices
+over the MC protocol (3E/4E frames) — the protocol is handled for you by a bundled
+[gomc-rest](https://github.com/Moge800/gomc-rest) server that the package
+auto-launches, so you never have to start or distribute an executable yourself.
+
+**Bonus — expose a REST API.** Enable `server_mode` to make the bundled
+server's REST API reachable from other apps on your network (a GUI, another
+machine, another language); and `connect()` talks to a gomc-rest server that is
+already running elsewhere. See [Access control](#access-control).
+
+Under the hood the HTTP layer is provided by
+[gomc-rest-client](https://github.com/Moge800/gomc_rest_client); this package
+adds the bundled binary and its process lifecycle.
+
+```text
+your Python process
+└─ gomc_rest.launch()
+     ├─ spawns the bundled gomc-rest on a free loopback port  ── MC protocol ──▶ PLC
+     └─ returns a Server that provides a PLCClient pointed at it
+```
+
+## Install
+
+```bash
+pip install gomc-rest
+```
+
+## Usage
+
+```python
+import gomc_rest
+
+with gomc_rest.launch(plc_host="192.168.0.1") as plc:
+    values = plc.read("D100", 3)
+    plc.write("D100", [10, 20, 30])
+# the bundled server is stopped automatically on exit
+```
+
+`launch()` returns a `Server`; using it as a context manager yields a
+`PLCClient` (see gomc-rest-client for the full read/write/remote API) and stops
+the server on exit. Without `with`, the server is stopped at interpreter exit.
+
+Pass server flags through `extra_args`:
+
+```python
+with gomc_rest.launch(plc_host="192.168.0.1", extra_args=["-enable-remote"]) as plc:
+    plc.remote_run()
+```
+
+### Client mode (connect to an existing server)
+
+To talk to a gomc-rest server that is already running elsewhere — a shared
+instance, another machine, or one you launched with `server_mode=True` — use
+`connect()` instead of starting the bundled binary:
+
+```python
+with gomc_rest.connect("http://192.168.0.1:8080", token="...") as plc:
+    plc.read("D100", 3)
+```
+
+Both `launch()` and `connect()` hand you the same `PLCClient`, so one package
+covers "bundle and run the server" and "just be a client".
+
+`connect()` needs no bundled binary, so it works even on platforms without a
+prebuilt wheel (macOS, Windows arm64, glibc < 2.34): there `pip install
+gomc-rest` installs from the sdist, and only `launch()` is unavailable (it
+raises a clear error).
+
+## Access control
+
+Two independent layers protect the server, both on by default:
+
+1. **Per-launch bearer token.** A random token is generated each launch and
+   required by the server, so even another process on the same host that
+   discovers the port cannot call the API. It is set automatically on the
+   returned client and exposed as `server.token`. Pass an explicit `token=` to
+   share with another app, or `token=""` to disable auth (closed-network use).
+2. **Loopback binding.** By default the server binds to `127.0.0.1`, so no
+   other host can reach it.
+
+Set `server_mode=True` to bind all interfaces so other apps on the network
+(e.g. gomc-rest-gui, curl from another machine) can call it — give them
+`server.token`:
+
+```python
+server = gomc_rest.launch(plc_host="192.168.0.1", server_mode=True)
+print(server.base_url)   # other apps connect to http://<this-host>:<port>
+print(server.token)      # ...with this bearer token
+try:
+    server.client.read("D100", 3)
+finally:
+    server.close()
+```
+
+The server has no TLS — only enable `server_mode` on a trusted network.
+
+**Threat model.** The token is passed to the server via the `GOMCR_TOKEN`
+environment variable (not the command line), so it does not appear in the
+process list. It protects against other hosts and other OS users. It does
+**not** protect against another process running as the **same OS user**, which
+can read the server's environment (e.g. `/proc/<pid>/environ`); the OS user
+boundary is the trust boundary here.
+
+## Versions
+
+This package bundles a pinned `gomc-rest` binary (currently **v1.4.0**, set in
+`GOMC_REST_VERSION`) that must satisfy `gomc-rest-client`'s
+`MINIMUM_SUPPORTED_GOMC_REST_VERSION`; `launch()` verifies this on startup. The
+`gomc-rest-client` dependency is capped (`>=0.10.0,<0.11`) so a future client
+that raises its minimum server version can't be installed without also bumping
+the bundled binary.
+
+## Releasing / bundled binaries
+
+The bundled server version is pinned in `GOMC_REST_VERSION`. Binaries are not
+committed to git; they are fetched from the matching gomc-rest GitHub release.
+
+- Locally: `python scripts/vendor_binaries.py` downloads all three binaries
+  into `src/gomc_rest/binaries/`, verifying each against the trusted SHA-256
+  values committed in `checksums/<version>.sha256`.
+- On a `v*` tag, `.github/workflows/release.yml` builds one platform-specific
+  wheel per OS (each bundling only its matching binary) and publishes to PyPI
+  via trusted publishing. The release job verifies the tag equals
+  `project.version`; `workflow_dispatch` builds wheels for verification only and
+  never publishes.
+
+To cut a release:
+
+1. To change the bundled server, edit `GOMC_REST_VERSION` (keep it within the
+   range accepted by the pinned `gomc-rest-client`) and add a matching
+   `checksums/<version>.sha256` with the trusted SHA-256 of each asset. If the
+   new binaries change their glibc requirement, update the `plat` tags in
+   `release.yml` accordingly.
+2. Bump the package version in **both** `pyproject.toml` (`project.version`)
+   and `src/gomc_rest/__init__.py` (`__version__`) — they must match.
+3. Tag that exact version, e.g. `git tag v0.2.0 && git push origin v0.2.0`
+   (the tag must equal `project.version` or the release job fails).

gomc_rest-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gomc_rest/__init__.py,sha256=-sTEjHSEuOnept3GO28dl3-PoqLxSECbKa5lsferUl4,3252
+gomc_rest/_binaries.py,sha256=wYhp6VcO5VfmztM2oIZWIVF_QHL0ADixkpCpuPwQ4qk,2521
+gomc_rest/_server.py,sha256=GztYu0DVn3lqSJhjH9-8EkOfpMzJbeumVgtBA3SWx9M,4748
+gomc_rest/binaries/.gitignore,sha256=iLgtA0Ah3vJKRQIDAoelvPL2Msv251d-qTqdFAt6dyo,111
+gomc_rest/binaries/README.md,sha256=pfAsf-Bwa5_NOitEvLKXfp2ROKgQRjmlc35bnyM_1N4,688
+gomc_rest/binaries/gomc-rest.exe,sha256=TTIzwuSsgwQDWOLvJD2GcGy99hQfkvi2Jw-PMrdKEeU,11051520
+gomc_rest-0.1.0.dist-info/METADATA,sha256=R1w5UHJfQ8ury7TqA39QwxLm8_elUc9XvYYBh2TN-c0,6439
+gomc_rest-0.1.0.dist-info/WHEEL,sha256=pp_iTzO0EBcCvlZZV2dJYp6L2tdDWBsn1ceo50wEt8Q,94
+gomc_rest-0.1.0.dist-info/licenses/LICENSE,sha256=z2FbQ_Nsco0Ai59dmX5-WcROjekvhYSkiud0M7Q00Kg,1085
+gomc_rest-0.1.0.dist-info/RECORD,,

gomc_rest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

gomc_rest-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moge800
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.