rutis 0.7.0__tar.gz

rutis-0.7.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: rutis
+Version: 0.7.0
+Summary: Write rutis plugins in Python, and the runtime that runs them
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arcships/rutis
+Project-URL: Documentation, https://github.com/arcships/rutis/tree/main/docs/guide
+Keywords: rutis,plugin,rutis-plugin
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: network
+Requires-Dist: websockets>=13; extra == "network"
+
+# rutis
+
+Write [rutis](https://github.com/arcships/rutis) plugins in Python, and the runtime that runs them.
+
+```python
+from rutis import define_plugin
+
+
+class Weather:
+    def __init__(self, llm, city):
+        self.llm, self.city = llm, city
+
+    async def today(self):
+        return f"{await self.llm.ask(self.city)} in {self.city}"
+
+
+def apply(ctx, config):
+    ctx.provide("weather", Weather(ctx.use("llm"), config["city"]))
+
+
+plugin = define_plugin(apply, inject=["llm"], provides={"weather": Weather})
+```
+
+Test it without a host:
+
+```python
+from rutis.testing import load
+
+async with load(plugin, config={"city": "Oslo"}, services={"llm": FakeLlm()}) as t:
+    assert await t.service("weather").today() == "sunny in Oslo"
+```
+
+A host runs plugins with `python -m rutis <channel> <project>` (it starts that itself); `python -m rutis listen:wss://… --id <id> --peer <controller> <project>` runs a runtime a host on another machine controls (install `rutis[network]`). Packaged plugins register under the entry point group `rutis.plugins`. Python 3.12 or later; no dependencies.
+
+Start a project with `uvx rutis-host new <name> --lang python`. Guide (Chinese): [docs/guide/python-plugin.md](https://github.com/arcships/rutis/blob/main/docs/guide/python-plugin.md).

rutis-0.7.0/README.md

@@ -0,0 +1,35 @@
+# rutis
+
+Write [rutis](https://github.com/arcships/rutis) plugins in Python, and the runtime that runs them.
+
+```python
+from rutis import define_plugin
+
+
+class Weather:
+    def __init__(self, llm, city):
+        self.llm, self.city = llm, city
+
+    async def today(self):
+        return f"{await self.llm.ask(self.city)} in {self.city}"
+
+
+def apply(ctx, config):
+    ctx.provide("weather", Weather(ctx.use("llm"), config["city"]))
+
+
+plugin = define_plugin(apply, inject=["llm"], provides={"weather": Weather})
+```
+
+Test it without a host:
+
+```python
+from rutis.testing import load
+
+async with load(plugin, config={"city": "Oslo"}, services={"llm": FakeLlm()}) as t:
+    assert await t.service("weather").today() == "sunny in Oslo"
+```
+
+A host runs plugins with `python -m rutis <channel> <project>` (it starts that itself); `python -m rutis listen:wss://… --id <id> --peer <controller> <project>` runs a runtime a host on another machine controls (install `rutis[network]`). Packaged plugins register under the entry point group `rutis.plugins`. Python 3.12 or later; no dependencies.
+
+Start a project with `uvx rutis-host new <name> --lang python`. Guide (Chinese): [docs/guide/python-plugin.md](https://github.com/arcships/rutis/blob/main/docs/guide/python-plugin.md).

rutis-0.7.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "rutis"
+version = "0.7.0"
+description = "Write rutis plugins in Python, and the runtime that runs them"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = []
+keywords = ["rutis", "plugin", "rutis-plugin"]
+
+[project.urls]
+Homepage = "https://github.com/arcships/rutis"
+Documentation = "https://github.com/arcships/rutis/tree/main/docs/guide"
+
+[project.optional-dependencies]
+# WebSocket channels: a runtime other machines reach (listen:ws://…, listen:wss://…).
+network = ["websockets>=13"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["rutis"]
+
+[tool.setuptools.package-data]
+rutis = ["py.typed"]

rutis-0.7.0/rutis/__init__.py

@@ -0,0 +1,11 @@
+"""rutis for Python: write plugins (`define_plugin`, `rutis.testing`), and the
+runtime that runs them (`python -m rutis <channel> <project>`, which a rutis
+host starts).
+
+See `rutis.plugin` for how a plugin is written.
+"""
+
+from .peer import RemoteError, SyncWaitCycle
+from .plugin import PLUGIN_API, Context, Plugin, define_plugin
+
+__all__ = ["PLUGIN_API", "Context", "Plugin", "RemoteError", "SyncWaitCycle", "define_plugin"]

rutis-0.7.0/rutis/__main__.py

@@ -0,0 +1,136 @@
+"""`python3 -m rutis <channel> [--id <endpoint>] [--peer <endpoint>] <project>`:
+one runtime process.
+
+The channel is `fd:<n>`, a socket inherited from the process that started
+this one; `unix:<path>` (or a bare path), a socket to dial; or
+`listen:ws://…` / `listen:wss://…`, a WebSocket address to listen on for the
+controlling rutis (the token it must present in RUTIS_TOKEN, a
+listener certificate and key in RUTIS_CERT and RUTIS_KEY).
+Local channels speak the compat protocol; network channels the endpoint
+format, as `--id`, expecting `--peer` as the controller when given.
+"""
+
+import asyncio
+import logging
+import os
+import socket
+import sys
+
+from .peer import Peer
+from .runner import Runtime
+
+
+def open_channel(spec: str):
+    if spec.startswith("fd:"):
+        return socket.socket(fileno=int(spec[len("fd:"):]))
+    path = spec[len("unix:"):] if spec.startswith("unix:") else spec
+    connection = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    connection.connect(path)
+    return connection
+
+
+def parse(argv: list[str]) -> tuple[str, dict | None, str]:
+    """The channel, the endpoint (network channels), and the project."""
+    if not argv:
+        raise ValueError("usage: python3 -m rutis <channel> [--id <endpoint>] [--peer <endpoint>] <project>")
+    channel, rest, flags = argv[0], list(argv[1:]), {}
+    while rest and rest[0].startswith("--"):
+        flag = rest.pop(0)[2:]
+        if not rest:
+            raise ValueError(f"--{flag} needs a value")
+        flags[flag] = rest.pop(0)
+    if len(rest) != 1:
+        raise ValueError("usage: python3 -m rutis <channel> [--id <endpoint>] [--peer <endpoint>] <project>")
+    endpoint = None
+    if channel.startswith("listen:"):
+        if "id" not in flags:
+            raise ValueError(f"a network channel needs --id <endpoint>: {channel}")
+        # A runner is a runtime: the controller manages its rows.
+        endpoint = {"local": flags["id"], "expected": flags.get("peer"), "declare": ["runtime"]}
+    return channel, endpoint, rest[0]
+
+
+class Session:
+    """One control session and the lease it holds: the rows, proxies and
+    references of one controller."""
+
+    def __init__(self, channel, endpoint: dict | None):
+        self.channel = channel
+        self.runtime = Runtime()
+        self.peer = Peer(channel, self.runtime.dispatch, settled=None, endpoint=endpoint)
+        self.runtime.peer = self.peer
+
+    def start(self) -> None:
+        self.peer.start()
+
+    async def end(self, replaced: bool = False) -> None:
+        """End the lease: no frame of this session is read any more, then
+        every row and proxy goes."""
+        if replaced and hasattr(self.channel, "replaced"):
+            self.channel.replaced()
+        self.peer.close(ConnectionError("replaced by a new connection" if replaced else "session ended"))
+        self.runtime.closing = True
+        await self.runtime.dispose()
+
+
+async def run(channel: str, endpoint: dict | None, project: str) -> None:
+    if project and project not in sys.path:
+        sys.path.insert(0, project)
+    if channel.startswith("listen:"):
+        await serve(channel[len("listen:"):], endpoint)
+        return
+    session = Session(open_channel(channel), endpoint)
+    session.start()
+    await session.peer.closed
+    await session.end()
+
+
+async def serve(spec: str, endpoint: dict) -> None:
+    """A runtime that stays up and listens: it serves one controller at a
+    time, a newer connection taking over, and cleans each lease up when it
+    ends. A new session is greeted only once the old lease is gone."""
+    from . import websocket
+    from .peer import ENDPOINT_PROTOCOL
+
+    listener = await asyncio.to_thread(
+        websocket.listen,
+        spec,
+        f"rutis.{ENDPOINT_PROTOCOL}",
+        os.environ.get("RUTIS_TOKEN"),
+        os.environ.get("RUTIS_CERT"),
+        os.environ.get("RUTIS_KEY"),
+    )
+    current: Session | None = None
+    accepting = asyncio.ensure_future(asyncio.to_thread(listener.accept))
+    while True:
+        waiting = {accepting} | ({current.peer.closed} if current else set())
+        done, _ = await asyncio.wait(waiting, return_when=asyncio.FIRST_COMPLETED)
+        if accepting in done:
+            channel = accepting.result()
+            accepting = asyncio.ensure_future(asyncio.to_thread(listener.accept))
+            if current is not None:
+                await current.end(replaced=True)
+            current = Session(channel, endpoint)
+            current.start()
+        elif current is not None and current.peer.closed in done:
+            await current.end()
+            current = None
+
+
+def main() -> None:
+    try:
+        channel, endpoint, project = parse(sys.argv[1:])
+    except ValueError as error:
+        sys.exit(str(error))
+    try:
+        asyncio.run(run(channel, endpoint, project))
+    finally:
+        # Stray plugin threads must not keep the process alive: rutis waits
+        # for it to exit.
+        sys.stdout.flush()
+        sys.stderr.flush()
+        logging.shutdown()
+        os._exit(0)
+
+
+main()

rutis-0.7.0/rutis/channel.py

@@ -0,0 +1,45 @@
+"""Channels a session runs on: ordered, reliable messages with their
+boundaries kept, independent of the encoding of what they carry.
+
+A channel has `send(message: bytes)`, `recv() -> bytes | None` (blocking;
+`None` once the far end finished) and `close(reason)`. `recv` raises
+`ConnectionError` when the channel failed.
+"""
+
+from __future__ import annotations
+
+import socket
+import threading
+
+
+class SocketChannel:
+    """A Unix socket (dialed, or inherited as fd 3), one message per line."""
+
+    def __init__(self, sock: socket.socket):
+        self._sock = sock
+        self._reader = sock.makefile("rb")
+        self._lock = threading.Lock()
+
+    def send(self, message: bytes) -> None:
+        if b"\n" in message:
+            raise ValueError("a message contains a raw newline")
+        with self._lock:
+            self._sock.sendall(message + b"\n")
+
+    def recv(self) -> bytes | None:
+        line = self._reader.readline()
+        if not line:
+            return None
+        if not line.endswith(b"\n"):
+            raise ConnectionError("stream ended inside a message")
+        return line[:-1]
+
+    def close(self, reason: str = "") -> None:
+        try:
+            self._sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        try:
+            self._sock.close()
+        except OSError:
+            pass