This commit is contained in:
Ludarium release export
@@ -0,0 +1,474 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Shared control-surface primitives for Ludarium emulator sidecars.
|
||||
|
||||
Every isolated player sidecar exposes the same bounded surface: a token-authenticated
|
||||
HTTP server on :8765 with /health, /v1/status, /v1/launch and /v1/action. Only the
|
||||
emulator binary, its game-path allowlist, its window identity and its hotkey map
|
||||
differ, so a concrete controller supplies only those.
|
||||
|
||||
Keeping the surface in one module is a safety property, not only tidiness. The
|
||||
Xwayland display resolution below was found and fixed against the live Eden runtime;
|
||||
a per-sidecar copy silently missed that fix. Anything a future Azahar, xemu, Cemu or
|
||||
Vita3K controller needs belongs here so it inherits the same behaviour.
|
||||
|
||||
The module has no third-party dependencies: the sidecar images are minimized and must
|
||||
not regain a package manager surface.
|
||||
"""
|
||||
import hmac
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import signal
|
||||
import subprocess
|
||||
import tarfile
|
||||
import tempfile
|
||||
import threading
|
||||
import time
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
from pathlib import Path, PurePosixPath
|
||||
|
||||
CONTROL_PORT = 8765
|
||||
MIN_REQUEST_BYTES = 2
|
||||
MAX_REQUEST_BYTES = 8192
|
||||
# The Ludarium game-data vault stores one revision of at most 64 MiB, so an archive larger than that
|
||||
# could never be kept. Refusing it here keeps the failure at the sidecar instead of half-way upstream.
|
||||
MAX_SAVE_DATA_BYTES = 64 * 1024 * 1024
|
||||
MAX_SAVE_DATA_ENTRIES = 20000
|
||||
MAX_SAVE_DATA_ENTRY_BYTES = 256 * 1024 * 1024
|
||||
MAX_SAVE_DATA_EXPANDED_BYTES = 512 * 1024 * 1024
|
||||
SETUIDGID = "/usr/bin/s6-setuidgid"
|
||||
RUNTIME_USER = "abc"
|
||||
XDOTOOL = "/usr/bin/xdotool"
|
||||
|
||||
|
||||
def respond(handler, status, body):
|
||||
payload = json.dumps(body).encode("utf-8")
|
||||
handler.send_response(status)
|
||||
handler.send_header("Content-Type", "application/json")
|
||||
handler.send_header("Content-Length", str(len(payload)))
|
||||
handler.end_headers()
|
||||
handler.wfile.write(payload)
|
||||
|
||||
|
||||
def authorized(handler, token):
|
||||
supplied = handler.headers.get("X-Ludarium-Control-Token", "")
|
||||
return bool(token) and hmac.compare_digest(token, supplied)
|
||||
|
||||
|
||||
def resolve_game_path(value, games, extensions, platforms=None):
|
||||
"""Resolve a runtime-relative game path to an exact file inside the read-only mount.
|
||||
|
||||
This is the sidecar's last defence. The API already validates and prefixes the path,
|
||||
but the controller must never execute anything it cannot prove lives inside the
|
||||
games mount, carries an allowlisted extension and is a regular file. Symlinks are
|
||||
resolved before the containment check, so a link out of the mount fails closed.
|
||||
"""
|
||||
relative = PurePosixPath(value)
|
||||
if relative.is_absolute() or not relative.parts:
|
||||
raise ValueError("Unsafe game path")
|
||||
if any(part in ("", ".", "..") for part in relative.parts):
|
||||
raise ValueError("Unsafe game path")
|
||||
if platforms is not None and (len(relative.parts) < 2 or relative.parts[0] not in platforms):
|
||||
raise ValueError("Unsafe game path")
|
||||
root = Path(games).resolve()
|
||||
target = (root / Path(*relative.parts)).resolve()
|
||||
if root not in target.parents:
|
||||
raise ValueError("Game is outside the read-only games mount")
|
||||
if target.suffix.lower() not in extensions:
|
||||
raise ValueError("Game is not an allowlisted read-only image")
|
||||
if not target.is_file():
|
||||
raise ValueError("Game is not a present read-only file")
|
||||
return target
|
||||
|
||||
|
||||
def desktop_display(process_name):
|
||||
"""Resolve the Xwayland display owned by the active emulator desktop.
|
||||
|
||||
PixelFlux allocates a new display number after container restarts while retaining
|
||||
older socket files. Reading the running desktop process is authoritative; the newest
|
||||
socket is only a bounded fallback for the short interval before the emulator has
|
||||
published its environment.
|
||||
"""
|
||||
try:
|
||||
process = subprocess.run(
|
||||
["/usr/bin/pgrep", "-o", "-x", process_name], capture_output=True, text=True,
|
||||
timeout=2, check=False)
|
||||
pid = process.stdout.strip()
|
||||
if process.returncode == 0 and pid.isdigit():
|
||||
environment = subprocess.run(
|
||||
[SETUIDGID, RUNTIME_USER, "/bin/cat", f"/proc/{pid}/environ"],
|
||||
capture_output=True, timeout=2, check=False)
|
||||
for item in environment.stdout.split(b"\0"):
|
||||
if item.startswith(b"DISPLAY=:"):
|
||||
display = item.removeprefix(b"DISPLAY=").decode("ascii", errors="ignore")
|
||||
if display[1:].isdigit():
|
||||
return display
|
||||
except (OSError, subprocess.SubprocessError):
|
||||
pass
|
||||
|
||||
sockets = []
|
||||
try:
|
||||
for socket in Path("/tmp/.X11-unix").glob("X*"):
|
||||
if socket.name[1:].isdigit():
|
||||
sockets.append((socket.stat().st_mtime_ns, int(socket.name[1:])))
|
||||
except OSError:
|
||||
pass
|
||||
if sockets:
|
||||
return f":{max(sockets)[1]}"
|
||||
return os.environ.get("DISPLAY", ":0")
|
||||
|
||||
|
||||
def resolve_save_paths(save_root, save_paths):
|
||||
"""Resolve the subdirectories of a profile that actually hold save data.
|
||||
|
||||
An emulator profile is not a save directory. Dolphin's holds shader caches and dumps that dwarf
|
||||
the bounded revision size, so capturing the whole profile would fail on any real installation.
|
||||
Naming the save-bearing subdirectories keeps a capture to what an operator wants back, and
|
||||
resolving them here means a wrong path is visible in /v1/status instead of silently capturing
|
||||
the wrong thing.
|
||||
"""
|
||||
if save_root is None:
|
||||
return []
|
||||
root = Path(save_root)
|
||||
if not root.is_dir():
|
||||
return []
|
||||
root = root.resolve()
|
||||
if not save_paths:
|
||||
return [root]
|
||||
resolved = []
|
||||
for relative in save_paths:
|
||||
candidate = PurePosixPath(relative)
|
||||
if candidate.is_absolute() or any(part in ("", ".", "..") for part in candidate.parts):
|
||||
continue
|
||||
target = (root / Path(*candidate.parts)).resolve()
|
||||
if root in target.parents and target.is_dir():
|
||||
resolved.append(target)
|
||||
return resolved
|
||||
|
||||
|
||||
def export_save_data(save_root, save_paths=()):
|
||||
"""Pack an emulator's app-owned save directories into one bounded gzip archive.
|
||||
|
||||
Only regular files are packed and every ownership, device and symlink attribute is dropped, so
|
||||
the archive describes save content and nothing about the container it came from. Paths stay
|
||||
relative to the profile root, so a restore lands exactly where the capture came from.
|
||||
"""
|
||||
root = Path(save_root).resolve() if save_root is not None else None
|
||||
directories = resolve_save_paths(save_root, save_paths)
|
||||
if not directories:
|
||||
raise ValueError("No save-data directory is present for this runtime")
|
||||
buffer = io.BytesIO()
|
||||
packed = 0
|
||||
with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
|
||||
for directory in directories:
|
||||
for path in sorted(directory.rglob("*")):
|
||||
if path.is_symlink() or not path.is_file():
|
||||
continue
|
||||
packed += 1
|
||||
if packed > MAX_SAVE_DATA_ENTRIES:
|
||||
raise ValueError("The save directories hold more files than one revision may carry")
|
||||
info = archive.gettarinfo(str(path), arcname=str(path.relative_to(root).as_posix()))
|
||||
info.uid = info.gid = 0
|
||||
info.uname = info.gname = ""
|
||||
info.mode = 0o644
|
||||
info.mtime = int(info.mtime)
|
||||
with path.open("rb") as content:
|
||||
archive.addfile(info, content)
|
||||
if buffer.tell() > MAX_SAVE_DATA_BYTES:
|
||||
raise ValueError("The save-data archive exceeds the bounded revision size")
|
||||
if packed == 0:
|
||||
raise ValueError("The configured save directories hold no save data yet")
|
||||
return buffer.getvalue()
|
||||
|
||||
|
||||
def import_save_data(save_root, payload, save_paths=()):
|
||||
"""Restore a previously exported archive over an emulator's save directories.
|
||||
|
||||
The archive is operator data that has travelled through the vault, so every member is checked
|
||||
before extraction: only plain relative files are written, nothing may escape the root, and a
|
||||
member must land inside one of the configured save directories. A restore therefore cannot
|
||||
reach an emulator's configuration even if the stored archive was crafted to try.
|
||||
"""
|
||||
root = Path(save_root).resolve() if save_root is not None else None
|
||||
directories = resolve_save_paths(save_root, save_paths)
|
||||
if root is None or not root.is_dir() or not directories:
|
||||
raise ValueError("No save-data directory is present for this runtime")
|
||||
if len(payload) > MAX_SAVE_DATA_BYTES:
|
||||
raise ValueError("The save-data archive exceeds the bounded revision size")
|
||||
with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
|
||||
members = archive.getmembers()
|
||||
if len(members) > MAX_SAVE_DATA_ENTRIES:
|
||||
raise ValueError("The save-data archive holds more files than one revision may carry")
|
||||
expanded = 0
|
||||
validated = []
|
||||
for member in members:
|
||||
if not member.isfile():
|
||||
raise ValueError(f"The save-data archive contains an unsupported entry '{member.name}'")
|
||||
if member.size < 0 or member.size > MAX_SAVE_DATA_ENTRY_BYTES:
|
||||
raise ValueError(f"The save-data archive entry '{member.name}' is too large")
|
||||
expanded += member.size
|
||||
if expanded > MAX_SAVE_DATA_EXPANDED_BYTES:
|
||||
raise ValueError("The expanded save-data archive exceeds the restore limit")
|
||||
relative = PurePosixPath(member.name)
|
||||
if relative.is_absolute() or any(part in ("", ".", "..") for part in relative.parts):
|
||||
raise ValueError(f"The save-data archive contains an unsafe path '{member.name}'")
|
||||
destination = (root / Path(*relative.parts)).resolve()
|
||||
if root not in destination.parents:
|
||||
raise ValueError(f"The save-data archive escapes the save directory at '{member.name}'")
|
||||
if not any(directory == destination or directory in destination.parents
|
||||
for directory in directories):
|
||||
raise ValueError(f"The save-data archive targets '{member.name}' outside the save directories")
|
||||
validated.append((member, destination))
|
||||
|
||||
restored = 0
|
||||
for member, destination in validated:
|
||||
destination.parent.mkdir(parents=True, exist_ok=True)
|
||||
source = archive.extractfile(member)
|
||||
if source is None:
|
||||
raise ValueError(f"The save-data archive entry '{member.name}' is unreadable")
|
||||
temporary = None
|
||||
try:
|
||||
with source, tempfile.NamedTemporaryFile(dir=destination.parent, delete=False) as output:
|
||||
temporary = Path(output.name)
|
||||
copied = 0
|
||||
while chunk := source.read(1024 * 1024):
|
||||
copied += len(chunk)
|
||||
if copied > member.size or copied > MAX_SAVE_DATA_ENTRY_BYTES:
|
||||
raise ValueError(f"The save-data archive entry '{member.name}' exceeds its declared size")
|
||||
output.write(chunk)
|
||||
if copied != member.size:
|
||||
raise ValueError(f"The save-data archive entry '{member.name}' is truncated")
|
||||
os.chmod(temporary, 0o644)
|
||||
os.replace(temporary, destination)
|
||||
temporary = None
|
||||
restored += 1
|
||||
finally:
|
||||
if temporary is not None:
|
||||
temporary.unlink(missing_ok=True)
|
||||
return restored
|
||||
|
||||
|
||||
def runtime_environment(process_name):
|
||||
return {
|
||||
**os.environ,
|
||||
"HOME": "/config",
|
||||
"DISPLAY": desktop_display(process_name),
|
||||
"XDG_RUNTIME_DIR": "/config/.XDG",
|
||||
"WAYLAND_DISPLAY": "wayland-0",
|
||||
}
|
||||
|
||||
|
||||
def visible_windows(environment, pid=None, name=None):
|
||||
"""List visible window ids for the launched title.
|
||||
|
||||
The launched process id is authoritative: it is the exact emulator Ludarium started,
|
||||
so a hotkey can never reach an unrelated window such as an emulator's own menu or
|
||||
file browser. Matching on the window name stays as a bounded fallback for runtimes
|
||||
that do not publish _NET_WM_PID.
|
||||
"""
|
||||
for query in ([["--pid", str(pid)]] if pid else []) + ([["--name", name]] if name else []):
|
||||
found = subprocess.run(
|
||||
[SETUIDGID, RUNTIME_USER, XDOTOOL, "search", "--onlyvisible", *query],
|
||||
env=environment, capture_output=True, text=True, timeout=5, check=False)
|
||||
windows = [line for line in found.stdout.splitlines() if line.isdigit()]
|
||||
if windows:
|
||||
return windows
|
||||
return []
|
||||
|
||||
|
||||
class EmulatorRuntime:
|
||||
"""Owns the single title process a sidecar may run at a time."""
|
||||
|
||||
def __init__(self, name, process_name, launch_argv, games, extensions, hotkeys,
|
||||
save_mode, platforms=None, window_name=None, ready_seconds=1.0, save_root=None,
|
||||
save_paths=()):
|
||||
self.name = name
|
||||
self.process_name = process_name
|
||||
self.launch_argv = launch_argv
|
||||
self.games = games
|
||||
self.extensions = extensions
|
||||
self.hotkeys = hotkeys
|
||||
self.save_mode = save_mode
|
||||
self.platforms = platforms
|
||||
self.window_name = window_name
|
||||
self.ready_seconds = ready_seconds
|
||||
self.save_root = save_root
|
||||
self.save_paths = tuple(save_paths)
|
||||
self.lock = threading.Lock()
|
||||
self.active = None
|
||||
|
||||
def log(self, message):
|
||||
print(f"{self.name}-controller: {message}", flush=True)
|
||||
|
||||
def resolve(self, value):
|
||||
return resolve_game_path(value, self.games, self.extensions, self.platforms)
|
||||
|
||||
def environment(self):
|
||||
return runtime_environment(self.process_name)
|
||||
|
||||
def resolved_save_paths(self):
|
||||
return resolve_save_paths(self.save_root, self.save_paths)
|
||||
|
||||
@property
|
||||
def save_data_available(self):
|
||||
return len(self.resolved_save_paths()) > 0
|
||||
|
||||
def status(self):
|
||||
directories = self.resolved_save_paths()
|
||||
with self.lock:
|
||||
running = self.active is not None and self.active.poll() is None
|
||||
return {"running": running, "pid": self.active.pid if running else None,
|
||||
"saveMode": self.save_mode, "saveData": len(directories) > 0,
|
||||
# Naming what will be captured makes a misconfigured path visible here rather
|
||||
# than at the moment an operator tries to keep their progress.
|
||||
"saveRoot": self.save_root,
|
||||
"savePaths": [str(directory) for directory in directories]}
|
||||
|
||||
def terminate_locked(self):
|
||||
if self.active is None or self.active.poll() is not None:
|
||||
self.active = None
|
||||
return False
|
||||
self.active.send_signal(signal.SIGTERM)
|
||||
try:
|
||||
self.active.wait(timeout=8)
|
||||
except subprocess.TimeoutExpired:
|
||||
self.active.kill()
|
||||
self.active.wait(timeout=3)
|
||||
self.active = None
|
||||
return True
|
||||
|
||||
def stop(self):
|
||||
with self.lock:
|
||||
return self.terminate_locked()
|
||||
|
||||
def launch(self, target):
|
||||
environment = self.environment()
|
||||
with self.lock:
|
||||
self.terminate_locked()
|
||||
self.active = subprocess.Popen(
|
||||
[SETUIDGID, RUNTIME_USER, *self.launch_argv(target)], env=environment,
|
||||
stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
|
||||
start_new_session=True)
|
||||
process = self.active
|
||||
pid = process.pid
|
||||
time.sleep(self.ready_seconds)
|
||||
if process.poll() is not None:
|
||||
self.log(f"{self.name} exited early with code {process.returncode}; "
|
||||
f"display={environment['DISPLAY']}; game={target}")
|
||||
return None
|
||||
return pid
|
||||
|
||||
def hotkey(self, key):
|
||||
environment = self.environment()
|
||||
with self.lock:
|
||||
pid = self.active.pid if self.active is not None and self.active.poll() is None else None
|
||||
windows = visible_windows(environment, pid, self.window_name)
|
||||
if not windows:
|
||||
self.log(f"no visible {self.name} title window for hotkey {key}; "
|
||||
f"display={environment['DISPLAY']}; pid={pid}")
|
||||
return False
|
||||
subprocess.run(
|
||||
[SETUIDGID, RUNTIME_USER, XDOTOOL, "windowactivate", "--sync", windows[-1], "key", key],
|
||||
env=environment, timeout=5, check=True)
|
||||
return True
|
||||
|
||||
|
||||
def build_handler(runtime, token):
|
||||
class Handler(BaseHTTPRequestHandler):
|
||||
server_version = f"Ludarium{runtime.name.capitalize()}Controller/1"
|
||||
|
||||
def log_message(self, fmt, *args):
|
||||
runtime.log(fmt % args)
|
||||
|
||||
def do_GET(self):
|
||||
if self.path == "/health":
|
||||
return respond(self, 200, {"status": "healthy"})
|
||||
if not authorized(self, token):
|
||||
return respond(self, 404, {"message": "Not found"})
|
||||
if self.path == "/v1/status":
|
||||
return respond(self, 200, runtime.status())
|
||||
if self.path == "/v1/save-data":
|
||||
return self.export_save_data()
|
||||
return respond(self, 404, {"message": "Not found"})
|
||||
|
||||
def export_save_data(self):
|
||||
if not runtime.save_data_available:
|
||||
return respond(self, 409, {"message": f"No {runtime.name} save directory is configured"})
|
||||
try:
|
||||
payload = export_save_data(runtime.save_root, runtime.save_paths)
|
||||
except (ValueError, OSError, tarfile.TarError) as error:
|
||||
runtime.log(f"save-data export failed: {error}")
|
||||
return respond(self, 409, {"message": str(error)})
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/gzip")
|
||||
self.send_header("Content-Length", str(len(payload)))
|
||||
self.end_headers()
|
||||
self.wfile.write(payload)
|
||||
|
||||
def do_POST(self):
|
||||
if not authorized(self, token):
|
||||
return respond(self, 404, {"message": "Not found"})
|
||||
if self.path == "/v1/save-data":
|
||||
return self.import_save_data()
|
||||
body = {}
|
||||
try:
|
||||
length = int(self.headers.get("Content-Length", "0"))
|
||||
if length < MIN_REQUEST_BYTES or length > MAX_REQUEST_BYTES:
|
||||
raise ValueError("Invalid request size")
|
||||
body = json.loads(self.rfile.read(length))
|
||||
if not isinstance(body, dict):
|
||||
raise ValueError("Invalid request body")
|
||||
if self.path == "/v1/launch":
|
||||
return self.launch(body)
|
||||
if self.path == "/v1/action":
|
||||
return self.action(body)
|
||||
return respond(self, 404, {"message": "Not found"})
|
||||
except (ValueError, json.JSONDecodeError) as error:
|
||||
runtime.log(f"rejected {self.path}: {error}; "
|
||||
f"path={body.get('path') if isinstance(body, dict) else None!r}")
|
||||
return respond(self, 400, {"message": str(error)})
|
||||
except (OSError, subprocess.SubprocessError) as error:
|
||||
return respond(self, 503, {"message": f"{runtime.name} control operation failed",
|
||||
"detail": str(error)})
|
||||
|
||||
def import_save_data(self):
|
||||
if not runtime.save_data_available:
|
||||
return respond(self, 409, {"message": f"No {runtime.name} save directory is configured"})
|
||||
length = int(self.headers.get("Content-Length", "0"))
|
||||
if length <= 0 or length > MAX_SAVE_DATA_BYTES:
|
||||
return respond(self, 400, {"message": "The save-data archive is empty or exceeds its bound"})
|
||||
payload = self.rfile.read(length)
|
||||
try:
|
||||
written = import_save_data(runtime.save_root, payload, runtime.save_paths)
|
||||
except (ValueError, OSError, tarfile.TarError, EOFError) as error:
|
||||
runtime.log(f"save-data restore rejected: {error}")
|
||||
return respond(self, 400, {"message": str(error)})
|
||||
runtime.log(f"restored {written} save-data files")
|
||||
return respond(self, 202, {"state": "restored", "files": written})
|
||||
|
||||
def launch(self, body):
|
||||
target = runtime.resolve(body.get("path", ""))
|
||||
pid = runtime.launch(target)
|
||||
if pid is None:
|
||||
return respond(self, 503, {"message": f"{runtime.name} exited before the title started"})
|
||||
return respond(self, 202, {"state": "starting", "pid": pid, "saveMode": runtime.save_mode})
|
||||
|
||||
def action(self, body):
|
||||
action = body.get("action", "")
|
||||
if action == "stop":
|
||||
if not runtime.stop():
|
||||
return respond(self, 409, {"message": f"No Ludarium-started {runtime.name} title is running"})
|
||||
return respond(self, 202, {"state": "accepted", "action": action})
|
||||
if action not in runtime.hotkeys:
|
||||
raise ValueError("Unsupported action")
|
||||
if not runtime.hotkey(runtime.hotkeys[action]):
|
||||
return respond(self, 409, {"message": f"No running {runtime.name} title window was found"})
|
||||
return respond(self, 202, {"state": "accepted", "action": action})
|
||||
|
||||
return Handler
|
||||
|
||||
|
||||
def serve(runtime, token, port=CONTROL_PORT):
|
||||
if not token:
|
||||
raise SystemExit(f"A {runtime.name} control token is required")
|
||||
ThreadingHTTPServer(("0.0.0.0", port), build_handler(runtime, token)).serve_forever()
|
||||
Reference in New Issue
Block a user