ruyi 0.39.0__py3-none-any.whl

ruyi/pluginhost/ctx.py

@@ -0,0 +1,222 @@
+import abc
+import os
+import pathlib
+from typing import (
+    Callable,
+    Final,
+    Generic,
+    MutableMapping,
+    Protocol,
+    TypeVar,
+    TYPE_CHECKING,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+from ..log import RuyiLogger
+from . import api
+from . import paths
+
+
+ENV_PLUGIN_BACKEND_KEY: Final = "RUYI_PLUGIN_BACKEND"
+
+
+class SupportsGetOption(Protocol):
+    def get_option(self, key: str) -> object: ...
+
+
+class SupportsEvalFunction(Protocol):
+    def eval_function(
+        self,
+        function: object,
+        *args: object,
+        **kwargs: object,
+    ) -> object: ...
+
+
+ModuleTy = TypeVar("ModuleTy", bound=SupportsGetOption, covariant=True)
+EvalTy = TypeVar("EvalTy", bound=SupportsEvalFunction, covariant=True)
+
+
+class PluginHostContext(Generic[ModuleTy, EvalTy], metaclass=abc.ABCMeta):
+    @staticmethod
+    def new(
+        host_logger: RuyiLogger,
+        plugin_root: pathlib.Path,
+    ) -> "PluginHostContext[SupportsGetOption, SupportsEvalFunction]":
+        plugin_backend = os.environ.get("RUYI_PLUGIN_BACKEND", "")
+        if not plugin_backend:
+            plugin_backend = "unsandboxed"
+
+        match plugin_backend:
+            case "unsandboxed":
+                return UnsandboxedPluginHostContext(host_logger, plugin_root)
+            case _:
+                raise RuntimeError(f"unsupported plugin backend: {plugin_backend}")
+
+    def __init__(
+        self,
+        host_logger: RuyiLogger,
+        plugin_root: pathlib.Path,
+    ) -> None:
+        self._host_logger = host_logger
+        self._plugin_root = plugin_root
+        # resolved path: finalized module
+        self._module_cache: MutableMapping[str, ModuleTy] = {}
+        # plugin id: finalized plugin module
+        self._loaded_plugins: dict[str, SupportsGetOption] = {}
+        # plugin id: {key: value}
+        self._value_cache: dict[str, dict[str, object]] = {}
+
+    @abc.abstractmethod
+    def make_loader(
+        self,
+        originating_file: pathlib.Path,
+        module_cache: MutableMapping[str, ModuleTy],
+        is_cmd: bool,
+    ) -> "BasePluginLoader[ModuleTy]":
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def make_evaluator(self) -> EvalTy:
+        raise NotImplementedError
+
+    @property
+    def host_logger(self) -> RuyiLogger:
+        return self._host_logger
+
+    @property
+    def plugin_root(self) -> pathlib.Path:
+        return self._plugin_root
+
+    def load_plugin(self, plugin_id: str, is_cmd: bool) -> None:
+        plugin_dir = paths.get_plugin_dir(plugin_id, self._plugin_root)
+
+        loader = self.make_loader(
+            plugin_dir / paths.PLUGIN_ENTRYPOINT_FILENAME,
+            self._module_cache,
+            is_cmd,
+        )
+        loaded_plugin = loader.load_this_plugin()
+        self._loaded_plugins[plugin_id] = loaded_plugin
+
+    def is_plugin_loaded(self, plugin_id: str) -> bool:
+        return plugin_id in self._loaded_plugins
+
+    def get_from_plugin(
+        self,
+        plugin_id: str,
+        key: str,
+        is_cmd_plugin: bool = False,
+    ) -> object | None:
+        if not self.is_plugin_loaded(plugin_id):
+            self.load_plugin(plugin_id, is_cmd_plugin)
+
+        if plugin_id not in self._value_cache:
+            self._value_cache[plugin_id] = {}
+
+        try:
+            return self._value_cache[plugin_id][key]
+        except KeyError:
+            v = self._loaded_plugins[plugin_id].get_option(key)
+            self._value_cache[plugin_id][key] = v
+            return v
+
+
+class BasePluginLoader(Generic[ModuleTy], metaclass=abc.ABCMeta):
+    """Base class for plugin loaders loading from Ruyi repo.
+
+    Load paths take one of the following shapes:
+
+    * relative path: loads the path relative from the originating file's location,
+      but crossing plugin boundary is not allowed
+    * absolute path: similar to above, but relative to the plugin's FS root
+    * `ruyi-plugin://${plugin-id}`: loads from the plugin `plugin-id` residing
+      in the same repo as the originating plugin, the "entrypoint" being hard-coded
+      to whatever the concrete implementation dictates
+    """
+
+    def __init__(
+        self,
+        phctx: PluginHostContext[ModuleTy, SupportsEvalFunction],
+        originating_file: pathlib.Path,
+        module_cache: MutableMapping[str, ModuleTy],
+        is_cmd: bool,
+    ) -> None:
+        self._phctx = phctx
+        self.originating_file = originating_file
+        self.module_cache = module_cache
+        self.is_cmd = is_cmd
+
+    @property
+    def host_logger(self) -> RuyiLogger:
+        return self._phctx.host_logger
+
+    @property
+    def root(self) -> pathlib.Path:
+        return self._phctx.plugin_root
+
+    def make_sub_loader(self, originating_file: pathlib.Path) -> "Self":
+        return self.__class__(
+            self._phctx,
+            originating_file,
+            self.module_cache,
+            self.is_cmd,
+        )
+
+    def load_this_plugin(self) -> ModuleTy:
+        return self._load(str(self.originating_file), True)
+
+    def load(self, path: str) -> ModuleTy:
+        return self._load(path, False)
+
+    def _load(self, path: str, is_root: bool) -> ModuleTy:
+        resolved_path: pathlib.Path
+        if is_root:
+            resolved_path = pathlib.Path(path)
+        else:
+            resolved_path = paths.resolve_ruyi_load_path(
+                path,
+                self.root,
+                False,
+                self.originating_file,
+                self.is_cmd,
+            )
+        resolved_path_str = str(resolved_path)
+        if resolved_path_str in self.module_cache:
+            return self.module_cache[resolved_path_str]
+
+        plugin_id = resolved_path.relative_to(self.root).parts[0]
+        plugin_dir = self.root / plugin_id
+
+        host_bridge = api.make_ruyi_plugin_api_for_module(
+            self._phctx,
+            resolved_path,
+            plugin_dir,
+            self.is_cmd,
+        )
+
+        mod = self.do_load_module(
+            resolved_path,
+            resolved_path.read_text("utf-8"),
+            host_bridge,
+        )
+        self.module_cache[resolved_path_str] = mod
+        return mod
+
+    @abc.abstractmethod
+    def do_load_module(
+        self,
+        resolved_path: pathlib.Path,
+        program: str,
+        ruyi_host_bridge: Callable[[object], api.RuyiHostAPI],
+    ) -> ModuleTy:
+        raise NotImplementedError
+
+
+# import the built-in supported PluginHostContext implementation(s)
+# this must come after the baseclass declarations
+
+# pylint: disable-next=wrong-import-position
+from .unsandboxed import UnsandboxedPluginHostContext  # noqa: E402

ruyi/pluginhost/paths.py

@@ -0,0 +1,135 @@
+import pathlib
+import re
+from typing import Final
+from urllib.parse import unquote, urlparse
+
+PLUGIN_ENTRYPOINT_FILENAME: Final = "mod.star"
+PLUGIN_DATA_DIR: Final = "data"
+PLUGIN_ID_RE: Final = re.compile("^[A-Za-z_][A-Za-z0-9_-]*$")
+
+
+def validate_plugin_id(name: str) -> None:
+    if PLUGIN_ID_RE.match(name) is None:
+        raise RuntimeError(f"invalid plugin ID '{name}'")
+
+
+def get_plugin_dir(plugin_id: str, plugin_root: pathlib.Path) -> pathlib.Path:
+    validate_plugin_id(plugin_id)
+    return plugin_root / plugin_id
+
+
+def resolve_ruyi_load_path(
+    path: str,
+    plugin_root: pathlib.Path,
+    is_for_data: bool,
+    originating_file: pathlib.Path,
+    allow_host_fs_access: bool,
+) -> pathlib.Path:
+    parsed = urlparse(path)
+    if parsed.params or parsed.query or parsed.fragment:
+        raise RuntimeError("fancy URI features are not supported for load paths")
+
+    match parsed.scheme:
+        case "":
+            if parsed.netloc:
+                raise RuntimeError("'//' is not allowed as load path prefix")
+            return resolve_plain_load_path(
+                parsed.path,
+                plugin_root,
+                is_for_data,
+                originating_file=originating_file,
+            )
+
+        case "ruyi-plugin":
+            if is_for_data:
+                raise RuntimeError(
+                    "the ruyi-plugin protocol is not allowed in this context"
+                )
+
+            if parsed.path:
+                raise RuntimeError(
+                    "non-empty path segment is not allowed for ruyi-plugin:// load paths"
+                )
+
+            if not parsed.netloc:
+                raise RuntimeError(
+                    "empty location is not allowed for ruyi-plugin:// load paths"
+                )
+
+            plugin_id = unquote(parsed.netloc)
+            return get_plugin_dir(plugin_id, plugin_root) / PLUGIN_ENTRYPOINT_FILENAME
+
+        case "ruyi-plugin-data":
+            if not is_for_data:
+                raise RuntimeError(
+                    "the ruyi-plugin-data protocol is not allowed in this context"
+                )
+
+            if not parsed.path:
+                raise RuntimeError(
+                    "empty path segment is not allowed for ruyi-plugin-data:// load paths"
+                )
+
+            if not parsed.netloc:
+                raise RuntimeError(
+                    "empty location is not allowed for ruyi-plugin-data:// load paths"
+                )
+
+            return resolve_plain_load_path(
+                parsed.path,
+                plugin_root,
+                True,
+                plugin_id=parsed.netloc,
+            )
+
+        case "host":
+            if not allow_host_fs_access:
+                raise RuntimeError("the host protocol is not allowed in this context")
+
+            if not parsed.path:
+                raise RuntimeError(
+                    "empty path segment is not allowed for host:// load paths"
+                )
+
+            if parsed.netloc:
+                raise RuntimeError(
+                    "non-empty location is not allowed for host:// load paths"
+                )
+
+            return pathlib.Path(parsed.path)
+
+        case _:
+            raise RuntimeError(
+                f"unsupported Ruyi Starlark load path scheme {parsed.scheme}"
+            )
+
+
+def resolve_plain_load_path(
+    path: str,
+    plugin_root: pathlib.Path,
+    is_for_data: bool,
+    *,
+    originating_file: pathlib.Path | None = None,
+    plugin_id: str | None = None,
+) -> pathlib.Path:
+    if originating_file is None and plugin_id is None:
+        raise ValueError("one of originating_file or plugin_id must be specified")
+
+    if plugin_id is None:
+        assert originating_file is not None
+        rel = originating_file.relative_to(plugin_root)
+        plugin_id = rel.parts[0]
+
+    plugin_dir = plugin_root / plugin_id
+    if is_for_data:
+        plugin_dir = plugin_dir / PLUGIN_DATA_DIR
+
+    p = pathlib.PurePosixPath(path)
+    if p.is_absolute():
+        return plugin_dir / p.relative_to("/")
+
+    resolved = (plugin_dir / p).resolve()
+    if not resolved.is_relative_to(plugin_dir):
+        raise ValueError("plain load paths are not allowed to cross plugin boundary")
+
+    return resolved

ruyi/pluginhost/plugin_cli.py

@@ -0,0 +1,37 @@
+import argparse
+from typing import TYPE_CHECKING
+
+from ..cli.cmd import AdminCommand
+
+if TYPE_CHECKING:
+    from ..cli.completion import ArgumentParser
+    from ..config import GlobalConfig
+
+
+class AdminRunPluginCommand(
+    AdminCommand,
+    cmd="run-plugin-cmd",
+    help="Run a plugin-defined command",
+):
+    @classmethod
+    def configure_args(cls, gc: "GlobalConfig", p: "ArgumentParser") -> None:
+        p.add_argument(
+            "cmd_name",
+            type=str,
+            metavar="COMMAND-NAME",
+            help="Command name",
+        )
+        p.add_argument(
+            "cmd_args",
+            type=str,
+            nargs="*",
+            metavar="COMMAND-ARG",
+            help="Arguments to pass to the plugin command",
+        )
+
+    @classmethod
+    def main(cls, cfg: "GlobalConfig", args: argparse.Namespace) -> int:
+        cmd_name = args.cmd_name
+        cmd_args = args.cmd_args
+
+        return cfg.repo.run_plugin_cmd(cmd_name, cmd_args)

ruyi/pluginhost/unsandboxed.py

@@ -0,0 +1,246 @@
+import ast
+import builtins
+import inspect
+import os
+import pathlib
+import sys
+from types import CodeType
+from typing import Callable, Final, MutableMapping, NoReturn, TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from typing_extensions import Buffer
+
+from .api import RuyiHostAPI
+from .ctx import PluginHostContext, BasePluginLoader
+
+
+class UnsandboxedModuleDict(dict[str, object]):
+    def get_option(self, key: str) -> object:
+        return self.get(key, None)
+
+
+class UnsandboxedTrivialEvaluator:
+    def eval_function(
+        self,
+        function: object,
+        *args: object,
+        **kwargs: object,
+    ) -> object:
+        if callable(function):
+            return function(*args, **kwargs)
+        raise RuntimeError(f"the Python value {function!r} is not callable")
+
+
+BUILTINS_TO_EXPOSE: Final = {
+    k: getattr(builtins, k)
+    for k in [
+        "abs",
+        "any",
+        "all",
+        "bool",
+        "bytes",
+        "dict",
+        "dir",
+        "enumerate",
+        "float",
+        "getattr",
+        "hasattr",
+        "hash",
+        "int",
+        "len",
+        "list",
+        "max",
+        "min",
+        "print",
+        "range",
+        "repr",
+        "reversed",
+        "sorted",
+        "str",
+        "tuple",
+        "type",
+        "zip",
+    ]
+}
+
+
+def _fail_helper(*args: object) -> NoReturn:
+    raise RuntimeError(f"fail: {''.join(str(x) for x in args)}")
+
+
+class UnsandboxedPluginHostContext(
+    PluginHostContext[UnsandboxedModuleDict, UnsandboxedTrivialEvaluator]
+):
+    def make_loader(
+        self,
+        originating_file: pathlib.Path,
+        module_cache: MutableMapping[str, UnsandboxedModuleDict],
+        is_cmd: bool,
+    ) -> BasePluginLoader[UnsandboxedModuleDict]:
+        return UnsandboxedRuyiPluginLoader(self, originating_file, module_cache, is_cmd)
+
+    def make_evaluator(self) -> UnsandboxedTrivialEvaluator:
+        return UnsandboxedTrivialEvaluator()
+
+
+def _is_name_private(n: str) -> bool:
+    return n.startswith("_")
+
+
+def _assert_name_is_public(n: str) -> None | NoReturn:
+    if _is_name_private(n):
+        raise RuntimeError(f"error: trying to load private name {n}")
+    return None
+
+
+class UnsandboxedRuyiPluginLoader(BasePluginLoader[UnsandboxedModuleDict]):
+    def do_load_module(
+        self,
+        resolved_path: pathlib.Path,
+        program: str,
+        ruyi_host_bridge: Callable[[object], RuyiHostAPI],
+    ) -> UnsandboxedModuleDict:
+        self.host_logger.D(f"unsandboxed module load: path {resolved_path}")
+
+        sub_loader = self.make_sub_loader(resolved_path)
+
+        def _load_stmt_helper(
+            spec: str,
+            *values_to_bind: str,
+            **renamed_values_to_bind: str,
+        ) -> None:
+            mod = sub_loader.load(spec)
+
+            curr_frame = inspect.currentframe()
+            if curr_frame is None:
+                raise RuntimeError(
+                    "cannot inspect the Python runtime for the current frame"
+                )
+
+            parent_frame = curr_frame.f_back
+            if parent_frame is None:
+                raise RuntimeError(
+                    "internal error: no parent frame for load() statement"
+                )
+
+            g = parent_frame.f_locals
+            for name in values_to_bind:
+                _assert_name_is_public(name)
+                g[name] = mod[name]
+            for dst_name, src_name in renamed_values_to_bind.items():
+                _assert_name_is_public(src_name)
+                g[dst_name] = mod[src_name]
+            return None
+
+        code = self.source_to_code(program, resolved_path)
+        mod_globals: dict[str, object] = {
+            "__builtins__": BUILTINS_TO_EXPOSE,
+            "fail": _fail_helper,
+            "load": _load_stmt_helper,
+            "ruyi_plugin_rev": ruyi_host_bridge,
+        }
+        # pylint: disable-next=exec-used
+        exec(code, mod_globals)
+        return UnsandboxedModuleDict(mod_globals)
+
+    # intentionally follows the importlib.abc.InspectLoader protocol, for
+    # easier refactoring whenever necessary.
+    @staticmethod
+    def source_to_code(
+        data: "Buffer | str | ast.Module",
+        path: "Buffer | str | os.PathLike[str]" = "<string>",
+    ) -> CodeType:
+        mod_ast: ast.Module
+        if isinstance(data, ast.Module):
+            mod_ast = data
+        else:  # isinstance(data, str) or isinstance(data, Buffer)
+            mod_ast = ast.parse(data, path, "exec")
+
+        # lint the module on a best-effort basis to help fight syntax feature
+        # creep
+        lint_module(mod_ast)
+
+        return compile(mod_ast, path, "exec")
+
+
+def lint_module(mod: ast.Module) -> None:
+    if node := GatedLanguageFeaturesPass().visit(mod):
+        raise RuntimeError(f"line {node.lineno}: language feature is gated")
+
+
+class GatedLanguageFeaturesPass(ast.NodeVisitor):
+    def visit(self, node: ast.AST) -> ast.expr | ast.stmt | None:
+        return cast(ast.expr | ast.stmt | None, super().visit(node))
+
+    def generic_visit(self, node: ast.AST) -> ast.expr | ast.stmt | None:
+        """Traverses all types of nodes, bailing if non-minimal language
+        features are found."""
+
+        for _, value in ast.iter_fields(node):
+            if isinstance(value, list):
+                for item in value:
+                    if isinstance(item, ast.AST):
+                        if x := self.visit(item):
+                            return x
+            elif isinstance(value, ast.AST):
+                if x := self.visit(value):
+                    return x
+        return None
+
+    def visit_NamedExpr(self, node: ast.NamedExpr) -> ast.NamedExpr:
+        return node
+
+    def visit_Raise(self, node: ast.Raise) -> ast.Raise:
+        return node
+
+    def visit_Assert(self, node: ast.Assert) -> ast.Assert:
+        return node
+
+    def visit_Import(self, node: ast.Import) -> ast.Import:
+        return node
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> ast.ImportFrom:
+        return node
+
+    def visit_Try(self, node: ast.Try) -> ast.Try:
+        return node
+
+    if sys.version_info >= (3, 11):
+
+        def visit_TryStar(self, node: ast.TryStar) -> ast.TryStar:
+            return node
+
+    def visit_With(self, node: ast.With) -> ast.With:
+        return node
+
+    def visit_Match(self, node: ast.Match) -> ast.Match:
+        return node
+
+    def visit_Yield(self, node: ast.Yield) -> ast.Yield:
+        return node
+
+    def visit_YieldFrom(self, node: ast.YieldFrom) -> ast.YieldFrom:
+        return node
+
+    def visit_Global(self, node: ast.Global) -> ast.Global:
+        return node
+
+    def visit_Nonlocal(self, node: ast.Nonlocal) -> ast.Nonlocal:
+        return node
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:
+        return node
+
+    def visit_AsyncFunctionDef(
+        self, node: ast.AsyncFunctionDef
+    ) -> ast.AsyncFunctionDef:
+        return node
+
+    def visit_Await(self, node: ast.Await) -> ast.Await:
+        return node
+
+    def visit_AsyncFor(self, node: ast.AsyncFor) -> ast.AsyncFor:
+        return node
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> ast.AsyncWith:
+        return node

ruyi/resource_bundle/__init__.py

@@ -0,0 +1,20 @@
+import base64
+import zlib
+
+from .data import RESOURCES, TEMPLATES
+
+
+def _unpack_payload(x: bytes) -> str:
+    return zlib.decompress(base64.b64decode(x)).decode("utf-8")
+
+
+def get_resource_str(template_name: str) -> str | None:
+    if t := RESOURCES.get(template_name):
+        return _unpack_payload(t)
+    return None
+
+
+def get_template_str(template_name: str) -> str | None:
+    if t := TEMPLATES.get(template_name):
+        return _unpack_payload(t)
+    return None