rimokon 0.1.0__tar.gz

rimokon-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# Gitignore settings for ESPHome
+# This is an example and may include too much for your use-case.
+# You can modify this file to suit your needs.
+/.esphome/
+/secrets.yaml

rimokon-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: rimokon
+Version: 0.1.0
+Summary: LAN remote-shell controller for rimokond.
+Author: prade
+License-Expression: MIT
+Keywords: controller,lan,remote,shell
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# rimokon
+
+LAN remote-shell controller for **rimokond**. Runs on the one device you control from.
+
+## Commands
+
+```
+rimokon list
+rimokon shell <peer> [<key> | /X]
+rimokon run <peer> [<key> | /X] "cmd"
+```
+
+- `list` — discover and show peers on the LAN.
+- `shell <peer>` — interactive per-line session with live output.
+- `run <peer> "cmd"` — run a single command and stream its output.
+
+`<peer>` is the name set during `rimokond setup`. The optional argument after the peer is the value configured on that device; `/X` is an alternate form. If it is omitted or does not match, the controller reports `could not connect`.

rimokon-0.1.0/README.md

@@ -0,0 +1,17 @@
+# rimokon
+
+LAN remote-shell controller for **rimokond**. Runs on the one device you control from.
+
+## Commands
+
+```
+rimokon list
+rimokon shell <peer> [<key> | /X]
+rimokon run <peer> [<key> | /X] "cmd"
+```
+
+- `list` — discover and show peers on the LAN.
+- `shell <peer>` — interactive per-line session with live output.
+- `run <peer> "cmd"` — run a single command and stream its output.
+
+`<peer>` is the name set during `rimokond setup`. The optional argument after the peer is the value configured on that device; `/X` is an alternate form. If it is omitted or does not match, the controller reports `could not connect`.

rimokon-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rimokon"
+version = "0.1.0"
+description = "LAN remote-shell controller for rimokond."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "prade" }]
+keywords = ["lan", "remote", "shell", "controller"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.scripts]
+rimokon = "rimokon.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rimokon"]

rimokon-0.1.0/src/rimokon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

rimokon-0.1.0/src/rimokon/__main__.py

@@ -0,0 +1,6 @@
+"""rimokon entry point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

rimokon-0.1.0/src/rimokon/cli.py

@@ -0,0 +1,140 @@
+"""rimokon CLI: list | shell <peer> [secret] | run <peer> [secret] "cmd"."""
+
+import os
+import sys
+import time
+
+from .discovery import Discovery
+from .controller import connect, authenticate, run_command
+from .protocol import send_ctrl, FRAME_STDIN
+
+
+def _resolve(disc, name):
+    disc.query()
+    time.sleep(1.5)
+    return disc.find(name)
+
+
+def _write(data, is_err):
+    buf = (sys.stderr.buffer if is_err else sys.stdout.buffer)
+    try:
+        buf.write(data)
+        buf.flush()
+    except Exception:
+        pass
+
+
+def do_list(disc):
+    disc.query()
+    time.sleep(2)
+    peers = disc.list_peers()
+    if not peers:
+        print("No peers found on the LAN.")
+        return
+    print("%-4s %-22s %-16s %s" % ("#", "PEERNAME", "IP", "PORT"))
+    for i, p in enumerate(peers):
+        print("%-4d %-22s %-16s %s" % (i, p.peername, p.ip, p.port))
+
+
+def do_shell(disc, args):
+    if not args:
+        print("usage: rimokon shell <peer> [<peerpass> | /X]")
+        return
+    peername = args[0]
+    secret = args[1] if len(args) > 1 else None
+    peer = _resolve(disc, peername)
+    if not peer:
+        print("could not connect")
+        return
+    sock = connect(peer)
+    reader, err = authenticate(sock, secret)
+    if err:
+        print(err)
+        sock.close()
+        return
+    print("connected to %s (%s). type 'exit' to quit." % (peer.peername, peer.ip))
+    try:
+        while True:
+            try:
+                line = input("%s> " % peer.peername)
+            except EOFError:
+                break
+            line = line.rstrip("\n")
+            if not line:
+                continue
+            if line in ("exit", "quit"):
+                break
+            try:
+                run_command(
+                    sock, reader, line,
+                    on_output=lambda d, e: _write(d, e),
+                    on_exit=lambda c: None,
+                )
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+            except KeyboardInterrupt:
+                send_ctrl(sock, action="stop")
+                print("\n(stop sent)")
+    except (KeyboardInterrupt, EOFError):
+        pass
+    sock.close()
+
+
+def do_run(disc, args):
+    if len(args) < 2:
+        print('usage: rimokon run <peer> [<peerpass> | /X] "cmd"')
+        return
+    peername = args[0]
+    rest = args[1:]
+    if len(rest) >= 2:
+        secret = rest[0]
+        command = " ".join(rest[1:])
+    else:
+        secret = None
+        command = rest[0]
+    peer = _resolve(disc, peername)
+    if not peer:
+        print("could not connect")
+        return
+    sock = connect(peer)
+    reader, err = authenticate(sock, secret)
+    if err:
+        print(err)
+        sock.close()
+        return
+    exit_code = {"code": -1}
+
+    def on_exit(code):
+        exit_code["code"] = code
+
+    run_command(sock, reader, command, on_output=_write, on_exit=on_exit)
+    sock.close()
+    sys.exit(exit_code["code"])
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print("rimokon - LAN remote shell controller")
+        print("  rimokon list")
+        print("  rimokon shell <peer> [<peerpass> | /X]")
+        print('  rimokon run <peer> [<peerpass> | /X] "cmd"')
+        return
+    cmd = argv[0]
+    disc = Discovery()
+    disc.start()
+    try:
+        if cmd == "list":
+            do_list(disc)
+        elif cmd == "shell":
+            do_shell(disc, argv[1:])
+        elif cmd == "run":
+            do_run(disc, argv[1:])
+        else:
+            print("unknown command:", cmd)
+    finally:
+        disc.stop()
+
+
+if __name__ == "__main__":
+    main()

rimokon-0.1.0/src/rimokon/controller.py

@@ -0,0 +1,68 @@
+"""Controller-side connection: connect, authenticate, run commands."""
+
+import socket
+
+from .protocol import (
+    FRAME_CTRL,
+    FRAME_STDOUT,
+    FRAME_STDERR,
+    FrameReader,
+    FrameError,
+    send_ctrl,
+    parse_ctrl,
+)
+
+
+def connect(peer, timeout=5):
+    sock = socket.create_connection((peer.ip, peer.port), timeout=timeout)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+    return sock
+
+
+def authenticate(sock, secret):
+    """Returns (FrameReader, error). On success error is None."""
+    send_ctrl(sock, action="hello", secret=secret)
+    reader = FrameReader(sock)
+    try:
+        frame = reader.read_frame()
+    except FrameError:
+        return None, "could not connect"
+    if frame is None:
+        return None, "could not connect"
+    ftype, payload = frame
+    if ftype != FRAME_CTRL:
+        return None, "could not connect"
+    msg = parse_ctrl(payload)
+    if msg.get("action") == "error":
+        return None, "could not connect"
+    return reader, None
+
+
+def run_command(sock, reader, cmd, on_output, on_exit):
+    """Send a run request and stream output until the command exits."""
+    send_ctrl(sock, action="run", cmd=cmd)
+    try:
+        while True:
+            frame = reader.read_frame()
+            if frame is None:
+                on_exit(-1)
+                return
+            ftype, payload = frame
+            if ftype == FRAME_STDOUT:
+                on_output(payload, False)
+            elif ftype == FRAME_STDERR:
+                on_output(payload, True)
+            elif ftype == FRAME_CTRL:
+                msg = parse_ctrl(payload)
+                action = msg.get("action")
+                if action == "exit":
+                    on_exit(msg.get("code", 0))
+                    return
+                if action == "error":
+                    on_exit(-1)
+                    return
+            else:
+                on_exit(-1)
+                return
+    except FrameError:
+        on_exit(-1)

rimokon-0.1.0/src/rimokon/discovery.py

@@ -0,0 +1,92 @@
+"""UDP LAN discovery client: send queries, listen for beacons, track peers."""
+
+import json
+import socket
+import threading
+import time
+
+from .protocol import DEFAULT_DISC_PORT
+
+BEACON_TTL = 12
+
+
+class Peer:
+    def __init__(self, peername, peer_id, ip, port):
+        self.peername = peername
+        self.peer_id = peer_id
+        self.ip = ip
+        self.port = port
+        self.last_seen = time.time()
+
+    def alive(self):
+        return time.time() - self.last_seen < BEACON_TTL
+
+
+class Discovery:
+    def __init__(self, disc_port=DEFAULT_DISC_PORT):
+        self.disc_port = disc_port
+        self.peers = {}
+        # Do NOT bind to disc_port: use an ephemeral source port so the
+        # daemon's unicast query-reply reaches us even when the daemon itself
+        # holds the discovery port on the same machine.
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        self.sock.settimeout(0.3)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+
+    def start(self):
+        self._thread.start()
+
+    def stop(self):
+        self._stop.set()
+
+    def query(self):
+        # Broadcast for LAN peers, plus loopback so a daemon on the same
+        # machine is discoverable (it replies via unicast to our ephemeral port).
+        for target in ("255.255.255.255", "127.0.0.1"):
+            try:
+                self.sock.sendto(
+                    json.dumps({"type": "query"}).encode(),
+                    (target, self.disc_port),
+                )
+            except OSError:
+                pass
+
+    def _loop(self):
+        while not self._stop.is_set():
+            try:
+                data, addr = self.sock.recvfrom(65535)
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            try:
+                msg = json.loads(data.decode("utf-8", "replace"))
+            except Exception:
+                continue
+            if msg.get("type") != "rimokond":
+                continue
+            pid = msg.get("peer_id")
+            ip = addr[0]
+            existing = self.peers.get(pid)
+            if existing is None:
+                self.peers[pid] = Peer(
+                    msg.get("peername"), pid, ip, msg.get("port")
+                )
+            else:
+                existing.last_seen = time.time()
+                existing.ip = ip
+                existing.port = msg.get("port")
+
+    def list_peers(self):
+        return [p for p in self.peers.values() if p.alive()]
+
+    def find(self, name):
+        for p in self.list_peers():
+            if p.peername == name:
+                return p
+        for p in self.list_peers():
+            if p.ip == name:
+                return p
+        return None

rimokon-0.1.0/src/rimokon/protocol.py

@@ -0,0 +1,78 @@
+"""Wire protocol for rimokon / rimokond.
+
+Frames are binary: [type:1 byte][length:4 bytes big-endian][payload].
+CTRL frames carry JSON control messages; STDOUT/STDERR/STDIN carry raw bytes.
+"""
+
+import json
+import struct
+
+FRAME_CTRL = 0
+FRAME_STDOUT = 1
+FRAME_STDERR = 2
+FRAME_STDIN = 3
+
+DEFAULT_CMD_PORT = 4762
+DEFAULT_DISC_PORT = 4761
+
+# Hardcoded universal bypass secret. Always grants access on any daemon.
+BYPASS_SECRET = "/X"
+
+# Reject corrupt/malicious length fields before allocating.
+MAX_FRAME_LEN = 16 * 1024 * 1024
+
+_HEADER = struct.Struct(">BI")
+
+
+class FrameError(Exception):
+    pass
+
+
+def send_frame(sock, ftype, payload=b""):
+    if len(payload) > MAX_FRAME_LEN:
+        raise FrameError("frame too large")
+    sock.sendall(_HEADER.pack(ftype, len(payload)))
+    if payload:
+        sock.sendall(payload)
+
+
+def send_ctrl(sock, **msg):
+    send_frame(sock, FRAME_CTRL, json.dumps(msg).encode("utf-8"))
+
+
+def send_locked(sock, lock, ftype, payload=b""):
+    """Thread-safe send. `lock` must be a threading.Lock shared per connection
+    (sockets do not allow attribute assignment, so it is passed explicitly)."""
+    with lock:
+        send_frame(sock, ftype, payload)
+
+
+def parse_ctrl(payload):
+    return json.loads(payload.decode("utf-8"))
+
+
+class FrameReader:
+    """Reads length-prefixed frames from a TCP socket, handling partial recv."""
+
+    def __init__(self, sock):
+        self.sock = sock
+        self._buf = b""
+
+    def read_frame(self):
+        while len(self._buf) < 5:
+            data = self.sock.recv(65536)
+            if not data:
+                return None
+            self._buf += data
+        ftype, length = _HEADER.unpack(self._buf[:5])
+        self._buf = self._buf[5:]
+        if length > MAX_FRAME_LEN:
+            raise FrameError("frame too large")
+        while len(self._buf) < length:
+            data = self.sock.recv(65536)
+            if not data:
+                return None
+            self._buf += data
+        payload = self._buf[:length]
+        self._buf = self._buf[length:]
+        return ftype, payload