feat(extras): add a reference Linux VLC playback agent

[SHAREN]

Stacked PR: depends on #816 (which depends on #815). Please review this after the previous PRs; once they are merged, this diff will automatically shrink to the optional Linux VLC agent only.

Why

Remote playback devices are only useful when there is a simple agent to install on the computer connected to the TV.

This adds a small reference Linux agent that implements the playback-device contract from the previous PR. It lives under extras/, so TorrServer itself gains no Python or VLC runtime dependency.

What it does

• Exposes GET /health and POST /play.
• Opens VLC in a normal window or fullscreen according to the selected device's TorrServer setting.
• Uses normal-window playback by default because the device fullscreen checkbox is off by default.
• Stops only the VLC process previously started by this agent.
• Starts VLC with --no-one-instance, keeping the launched process owned and manageable by the agent.
• Runs commands as an argument list with shell=False.
• Includes a user-level systemd service and installer.
• Generates a random bearer token during installation.
• Includes configuration examples for dark mode, PulseAudio/PipeWire, and HDMI systems.

Fullscreen handling

The /play request contains:

{
  "fullscreen": false
}

The agent appends one final explicit VLC option:

• --no-fullscreen when the value is false or omitted;
• --fullscreen when the value is true.

The final flag is placed after configured player arguments, so a user's saved device checkbox has an unambiguous result. Existing/older requests without the field open VLC normally.

Request validation

Before opening VLC, the agent verifies that:

• path is a safe filename;
• hash is a 40-character torrent hash;
• index is a valid file index;
• fullscreen is a boolean when present;
• stream_url uses HTTP or HTTPS;
• URL credentials and fragments are absent;
• the URL hash, index, filename, and play parameter match the request;
• the stream hostname is in the optional allow-list.

Safe defaults

• Listens on 127.0.0.1 by default.
• A non-loopback listener requires a bearer token unless an explicit unsafe test override is used.
• Fullscreen is not stored in the agent environment and is not enabled by default.
• The generated environment file is mode 0600.
• The installer does not overwrite an existing configuration.
• The service runs as the desktop user, not as root.

Installation

cd extras/vlc-agent
./install-user-service.sh --listen-lan --allowed-host 192.168.1.10

The README explains how to register the generated agent URL and token in TorrServer and how to handle desktop-session variables on Wayland/X11 systems.

Compatibility

• Linux only; the component is optional.
• Python standard library only, Python 3.10+.
• VLC arguments are configurable through the environment file.
• Older requests without fullscreen remain valid and open a normal VLC window.
• This PR is stacked on the playback-device PR because it implements that API contract. It can also be maintained as a separate repository if keeping agents outside the TorrServer tree is preferred.

Tested

Seven Python unit/integration tests cover:

• bearer authentication;
• valid playback requests;
• rejected stream hosts;
• request/URL hash, index, and filename consistency;
• boolean fullscreen validation and backward-compatible default false;
• actual --fullscreen / --no-fullscreen CLI placement;
• token requirement for LAN listeners;
• replacement of only the player process owned by the agent.

Additional checks:

• python3 -m py_compile
• sh -n install-user-service.sh
• offline systemd-analyze verify
• installer test in an isolated temporary HOME with mocked VLC/systemctl:
  • correct install paths;
  • environment file mode 0600;
  • random token generated;
  • LAN and allowed-host values preserved;
  • no persistent --fullscreen option written.