elsewindow 0.1.0__py3-none-any.whl

elsewindow/__init__.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2026 kogeler
+# SPDX-License-Identifier: MIT
+
+"""Xpra application runner over one owned SSH master."""
+
+from __future__ import annotations
+
+
+def _resolve_version() -> str:
+    """Resolve the source-tree or installed distribution version."""
+    try:
+        from pathlib import Path
+
+        root = Path(__file__).resolve().parent.parent
+        if (root / "pyproject.toml").is_file():
+            return (root / ".version").read_text(encoding="utf-8").strip()
+        bundled = Path(__file__).resolve().parent / ".version"
+        if bundled.is_file():
+            return bundled.read_text(encoding="utf-8").strip()
+    except OSError:
+        pass
+
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        return version("elsewindow")
+    except PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

elsewindow/__main__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 kogeler
+# SPDX-License-Identifier: MIT
+
+"""Module entry point for Elsewindow."""
+
+from .cli import main
+
+raise SystemExit(main())

elsewindow/cli.py

@@ -0,0 +1,204 @@
+# Copyright (c) 2026 kogeler
+# SPDX-License-Identifier: MIT
+
+"""Command-line interface for one owned remote Xpra application."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import shutil
+import signal
+import sys
+from collections.abc import Sequence
+from contextlib import suppress
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as distribution_version
+
+from ssh_wrapper.errors import SSHError
+
+from . import __version__
+from .config import (
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_ENCODING_PROFILE,
+    DEFAULT_GRACE_TIMEOUT,
+    DEFAULT_HEARTBEAT_INTERVAL,
+    DEFAULT_LEASE_TIMEOUT,
+    DEFAULT_NETWORK_PROFILE,
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_PROBE_TIMEOUT,
+    DEFAULT_READY_TIMEOUT,
+    SUPPORTED_ENCODING_PROFILES,
+    SUPPORTED_NETWORK_PROFILES,
+    XpraConfig,
+)
+from .session import XpraSession
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the public command-line contract."""
+    parser = argparse.ArgumentParser(
+        prog="elsewindow",
+        description="Run one new remote GUI application through Xpra over owned SSH.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "--diagnose",
+        action="store_true",
+        help="report bundled versions, profile digests, and local prerequisites",
+    )
+    authority = parser.add_mutually_exclusive_group()
+    authority.add_argument("--ssh-alias", help="trusted OpenSSH host alias")
+    authority.add_argument("--host", help="direct SSH host or address")
+    parser.add_argument("--user", help="remote user required with --host")
+    parser.add_argument("--port", type=int, default=22, help="direct SSH port")
+    parser.add_argument(
+        "--encoding-profile",
+        choices=SUPPORTED_ENCODING_PROFILES,
+        default=DEFAULT_ENCODING_PROFILE,
+        help=(
+            "reviewed pixel transport profile; h264 uses native VA-API, "
+            "libyuv, OpenGL, and alpha-capable fallback"
+        ),
+    )
+    parser.add_argument(
+        "--network-profile",
+        choices=SUPPORTED_NETWORK_PROFILES,
+        default=DEFAULT_NETWORK_PROFILE,
+        help="reviewed client quality/network profile (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--connect-timeout", type=float, default=DEFAULT_CONNECT_TIMEOUT
+    )
+    parser.add_argument("--ready-timeout", type=float, default=DEFAULT_READY_TIMEOUT)
+    parser.add_argument("--probe-timeout", type=float, default=DEFAULT_PROBE_TIMEOUT)
+    parser.add_argument("--poll-interval", type=float, default=DEFAULT_POLL_INTERVAL)
+    parser.add_argument(
+        "--heartbeat-interval", type=float, default=DEFAULT_HEARTBEAT_INTERVAL
+    )
+    parser.add_argument("--lease-timeout", type=float, default=DEFAULT_LEASE_TIMEOUT)
+    parser.add_argument("--cleanup-grace", type=float, default=DEFAULT_GRACE_TIMEOUT)
+    parser.add_argument(
+        "application",
+        nargs=argparse.REMAINDER,
+        metavar="APP [ARG ...]",
+        help="application argv after --",
+    )
+    return parser
+
+
+def _diagnose() -> int:
+    """Report immutable bundled inputs and actionable host prerequisites."""
+    from .live_config import LIVE_CLI_PATH, NETWORK_PROFILES_PATH
+
+    failed = False
+    print(f"elsewindow: {__version__}")
+    try:
+        wrapper_version = distribution_version("ssh-wrapper")
+    except PackageNotFoundError:
+        wrapper_version = "missing"
+        failed = True
+    print(f"ssh-wrapper: {wrapper_version}")
+    for label, path in (
+        ("live-cli.yml", LIVE_CLI_PATH),
+        ("profiles.yml", NETWORK_PROFILES_PATH),
+    ):
+        try:
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        except OSError as error:
+            print(f"elsewindow: invalid_resource: {label}: {error}", file=sys.stderr)
+            failed = True
+        else:
+            print(f"{label}: sha256:{digest}")
+    if not sys.platform.startswith("linux"):
+        print(
+            f"elsewindow: unsupported_platform: Linux is required, found {sys.platform}",
+            file=sys.stderr,
+        )
+        failed = True
+    for command in ("ssh", "false", "xpra"):
+        resolved = shutil.which(command)
+        if resolved is None:
+            print(
+                "elsewindow: missing_dependency: "
+                f"required command not found on PATH: {command}",
+                file=sys.stderr,
+            )
+            failed = True
+        else:
+            print(f"{command}: {resolved}")
+    return int(failed)
+
+
+async def _run_with_signals(config: XpraConfig) -> int:
+    session = XpraSession(config)
+    loop = asyncio.get_running_loop()
+    interrupted: asyncio.Future[int] = loop.create_future()
+
+    def stop(exit_code: int) -> None:
+        if not interrupted.done():
+            interrupted.set_result(exit_code)
+
+    installed: list[signal.Signals] = []
+    for selected in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(selected, stop, 128 + selected)
+        except NotImplementedError:
+            continue
+        installed.append(selected)
+
+    run_task = asyncio.create_task(session.run())
+    try:
+        done, _pending = await asyncio.wait(
+            {run_task, interrupted}, return_when=asyncio.FIRST_COMPLETED
+        )
+        if interrupted in done:
+            run_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await run_task
+            return interrupted.result()
+        return run_task.result()
+    finally:
+        if not interrupted.done():
+            interrupted.cancel()
+        for selected in installed:
+            loop.remove_signal_handler(selected)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Validate configuration, run one session, and return a stable exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.diagnose:
+        if (
+            args.ssh_alias is not None
+            or args.host is not None
+            or args.user is not None
+            or args.port != 22
+            or args.application
+        ):
+            parser.error("--diagnose cannot be combined with a session authority")
+        return _diagnose()
+    if args.ssh_alias is None and args.host is None:
+        parser.error("provide either --ssh-alias or --host")
+    try:
+        config = XpraConfig.from_namespace(args)
+    except SSHError as error:
+        parser.error(error.message)
+
+    try:
+        return asyncio.run(_run_with_signals(config))
+    except KeyboardInterrupt:
+        return 130
+    except SSHError as error:
+        print(f"elsewindow: {error.code}: {error.message}", file=sys.stderr)
+        return 1
+    except Exception as error:  # noqa: BLE001 - public diagnostics stay sanitized.
+        print(
+            f"elsewindow: session_failed: {type(error).__name__}",
+            file=sys.stderr,
+        )
+        return 1

elsewindow/config.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2026 kogeler
+# SPDX-License-Identifier: MIT
+
+"""Validated immutable configuration for one remote Xpra session."""
+
+from __future__ import annotations
+
+import argparse
+import math
+from dataclasses import dataclass
+from pathlib import Path
+
+from ssh_wrapper.connection import ConnectionSpec, resolve_program
+from ssh_wrapper.errors import SSHError
+
+from . import live_config
+
+DEFAULT_CONNECT_TIMEOUT = 120.0
+DEFAULT_READY_TIMEOUT = 45.0
+DEFAULT_PROBE_TIMEOUT = 8.0
+DEFAULT_POLL_INTERVAL = 1.0
+DEFAULT_HEARTBEAT_INTERVAL = 10.0
+DEFAULT_LEASE_TIMEOUT = 45.0
+DEFAULT_GRACE_TIMEOUT = 5.0
+MAX_TIMEOUT = 900.0
+MAX_APPLICATION_ARGUMENTS = 256
+MAX_APPLICATION_BYTES = 16 * 1024
+DEFAULT_ENCODING_PROFILE = live_config.DEFAULT_ENCODING_PROFILE
+DEFAULT_NETWORK_PROFILE = live_config.load_network_profiles()[0]
+SUPPORTED_ENCODING_PROFILES = live_config.encoding_profile_names()
+SUPPORTED_NETWORK_PROFILES = live_config.network_profile_names()
+
+
+def _bounded_float(name: str, value: float, minimum: float = 0.1) -> float:
+    if not math.isfinite(value) or not minimum <= value <= MAX_TIMEOUT:
+        raise SSHError(
+            "invalid_configuration",
+            f"{name} must be between {minimum:g} and {MAX_TIMEOUT:g} seconds",
+        )
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class XpraConfig:
+    """All startup policy for one independently owned GUI session."""
+
+    connection: ConnectionSpec
+    application: tuple[str, ...]
+    encoding_profile: str
+    network_profile: str
+    connect_timeout: float
+    ready_timeout: float
+    probe_timeout: float
+    poll_interval: float
+    heartbeat_interval: float
+    lease_timeout: float
+    grace_timeout: float
+    ssh_path: Path
+    false_path: Path
+    xpra_path: Path
+
+    @classmethod
+    def from_namespace(cls, args: argparse.Namespace) -> XpraConfig:
+        """Validate parsed arguments and resolve required local executables."""
+        if args.ssh_alias is not None:
+            if args.host is not None or args.user is not None or args.port != 22:
+                raise SSHError(
+                    "invalid_connection",
+                    "ssh alias cannot be combined with host, user, or a direct port",
+                )
+            connection = ConnectionSpec.from_alias(args.ssh_alias)
+        else:
+            if args.host is None or args.user is None:
+                raise SSHError(
+                    "invalid_connection",
+                    "provide either ssh alias or both host and user",
+                )
+            connection = ConnectionSpec.from_direct(args.host, args.user, args.port)
+
+        application = tuple(args.application)
+        if application and application[0] == "--":
+            application = application[1:]
+        if not application or not application[0]:
+            raise SSHError(
+                "invalid_application", "provide an application argv after --"
+            )
+        if len(application) > MAX_APPLICATION_ARGUMENTS:
+            raise SSHError(
+                "invalid_application",
+                f"application argv is limited to {MAX_APPLICATION_ARGUMENTS} items",
+            )
+        if any("\x00" in item for item in application):
+            raise SSHError("invalid_application", "application argv contains a NUL")
+        if (
+            sum(len(item.encode("utf-8")) for item in application)
+            > MAX_APPLICATION_BYTES
+        ):
+            raise SSHError(
+                "invalid_application",
+                f"application argv is limited to {MAX_APPLICATION_BYTES} UTF-8 bytes",
+            )
+        if args.encoding_profile not in SUPPORTED_ENCODING_PROFILES:
+            raise SSHError(
+                "invalid_configuration",
+                "encoding profile must be one of: "
+                f"{', '.join(SUPPORTED_ENCODING_PROFILES)}",
+            )
+        if args.network_profile not in SUPPORTED_NETWORK_PROFILES:
+            raise SSHError(
+                "invalid_configuration",
+                "network profile must be one of: "
+                f"{', '.join(SUPPORTED_NETWORK_PROFILES)}",
+            )
+        heartbeat_interval = _bounded_float(
+            "heartbeat interval", args.heartbeat_interval
+        )
+        lease_timeout = _bounded_float("lease timeout", args.lease_timeout)
+        if lease_timeout <= heartbeat_interval * 2:
+            raise SSHError(
+                "invalid_configuration",
+                "lease timeout must be greater than twice the heartbeat interval",
+            )
+        return cls(
+            connection=connection,
+            application=application,
+            encoding_profile=args.encoding_profile,
+            network_profile=args.network_profile,
+            connect_timeout=_bounded_float("connect timeout", args.connect_timeout),
+            ready_timeout=_bounded_float("ready timeout", args.ready_timeout),
+            probe_timeout=_bounded_float("probe timeout", args.probe_timeout),
+            poll_interval=_bounded_float("poll interval", args.poll_interval),
+            heartbeat_interval=heartbeat_interval,
+            lease_timeout=lease_timeout,
+            grace_timeout=_bounded_float("cleanup grace", args.cleanup_grace),
+            ssh_path=resolve_program("ssh"),
+            false_path=resolve_program("false"),
+            xpra_path=resolve_program("xpra"),
+        )
+
+    @property
+    def authority_uri(self) -> str:
+        """Return the SSH URI prefix consumed by the local Xpra client."""
+        connection = self.connection
+        if connection.ssh_alias is not None:
+            authority = connection.ssh_alias
+        else:
+            assert connection.host is not None
+            assert connection.user is not None
+            assert connection.port is not None
+            host = f"[{connection.host}]" if ":" in connection.host else connection.host
+            authority = f"{connection.user}@{host}:{connection.port}"
+        return f"ssh://{authority}"

elsewindow/live-cli.yml

@@ -0,0 +1,94 @@
+# Static Xpra CLI blocks used by the live server and client command builders.
+# Values are grouped role -> concern/command/transport -> encoding -> policy;
+# per-run network/quality values live in profiles.yml rather than here.
+# Loader and assembly: infra/live/live_config.py and infra/live/run.py.
+# Generic schema tests: infra/live/test_job.py. Contract and usage:
+# CONTRACT.md and docs/runbooks/live-tests.md.
+schema: 1
+server:
+  base:
+    - "--minimal"
+    - "--backend=wayland"
+    - "--daemon=no"
+    - "--displayfd=1"
+    - "--socket-dir=/tmp/server-runtime/xpra-sockets"
+    - "--socket-dirs=/tmp/server-runtime/xpra-sockets"
+    - "--sessions-dir=/tmp/server-runtime/xpra-sessions"
+  lifecycle:
+    - "--use-display=no"
+    - "--exit-with-client=no"
+    - "--exit-with-children=yes"
+    - "--terminate-children=yes"
+    - "--video-scaling=0"
+    - "--html=off"
+  diagnostics:
+    - "-d"
+    - "wayland,damage,encoding,encoder,argb"
+  commands:
+    version:
+      - "--version"
+    info:
+      - "wayland-0"
+      - "--socket-dir=/tmp/server-runtime/xpra-sockets"
+  transports:
+    rgb:
+      common:
+        - "--video-encoders=none"
+        - "--csc-modules=none"
+      policies:
+        strict:
+          - "--encodings=rgb"
+    h264:
+      common:
+        - "--video=yes"
+        - "--video-encoders=libva"
+        - "--csc-modules=libyuv"
+      policies:
+        strict:
+          - "--encodings=h264"
+        adaptive-alpha:
+          - "--encodings=h264,webp,rgb"
+        fallback-auto:
+          - "--encodings=h264,rgb"
+        fallback-h264:
+          - "--encodings=h264,rgb"
+client:
+  base:
+    - "--minimal"
+    - "--compressors=none"
+    - "--reconnect=no"
+    - "--bandwidth-detection=no"
+  diagnostics:
+    - "-d"
+    - "draw,paint,cairo,window,gtk,alpha,libva"
+  commands:
+    version:
+      - "--version"
+    detach:
+      - "--compressors=none"
+  transports:
+    rgb:
+      common:
+        - "--opengl=no"
+        - "--video-decoders=none"
+        - "--csc-modules=none"
+      policies:
+        strict:
+          - "--encodings=rgb"
+    h264:
+      common:
+        - "--video=yes"
+        - "--opengl=force:native"
+        - "--video-decoders=libva"
+        - "--csc-modules=none"
+      policies:
+        strict:
+          - "--encodings=h264"
+        adaptive-alpha:
+          - "--encodings=h264,webp,rgb"
+          - "--encoding=h264"
+        fallback-auto:
+          - "--encodings=h264,rgb"
+        fallback-h264:
+          - "--encodings=h264,rgb"
+          - "--encoding=h264"