feat(driver-vnc): create vnc driver

Create a vnc driver for jumpstarter that opens a tunnel
to connect vnc clients locally (and opens a browser directly
to that tunnel). If a VNC server is running in the remote
machine it will allow sharing the screen.

Co-Authored-By: Claude noreply@anthropic.com
Signed-off-by: Albert Esteve <aesteve@redhat.com>

Author: aesteve-rh

docs/source/reference/package-apis/drivers/vnc.md

@@ -0,0 +1 @@
+../../../../../packages/jumpstarter-driver-vnc/README.md

packages/jumpstarter-driver-vnc/README.md

@@ -0,0 +1,56 @@
+# Vnc Driver
+
+`jumpstarter-driver-vnc` provides functionality for interacting with VNC servers. It allows you to create a secure, tunneled VNC session in your browser.
+
+## Installation
+
+```shell
+pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-driver-vnc
+```
+
+## Configuration
+
+The VNC driver is a composite driver that requires a TCP child driver to establish the underlying network connection. The TCP driver should be configured to point to the VNC server's host and port, which is often `127.0.0.1` from the perspective of the Jumpstarter server.
+
+Example `exporter.yaml` configuration:
+
+```yaml
+export:
+  vnc:
+    type: jumpstarter_driver_vnc.driver.Vnc
+    children:
+      tcp:
+        type: jumpstarter_driver_network.driver.TcpNetwork
+        config:
+          host: "127.0.0.1"
+          port: 5901 # Default VNC port for display :1
+```
+
+## API Reference
+
+The client class for this driver is `jumpstarter_driver_vnc.client.VNClient`.
+
+### `vnc.session()`
+
+This asynchronous context manager establishes a connection to the remote VNC server and provides a local web server to view the session.
+
+**Usage:**
+
+```python
+async with vnc.session() as novnc_adapter:
+    print(f"VNC session available at: {novnc_adapter.url}")
+    # The session remains open until the context block is exited.
+    await novnc_adapter.wait()
+```
+
+### CLI: `j vnc session`
+
+This driver provides a convenient CLI command within the `jmp shell`.
+
+**Usage:**
+
+```bash
+# This will start the local server and print the URL.
+# It will remain running until you press Ctrl+C.
+j vnc session
+```

packages/jumpstarter-driver-vnc/examples/exporter.yaml

@@ -0,0 +1,17 @@
+apiVersion: jumpstarter.dev/v1alpha1
+kind: ExporterConfig
+metadata:
+  namespace: default
+  name: demo
+endpoint: grpc.jumpstarter.192.168.0.203.nip.io:8082
+token: "<token>"
+export:
+  vnc:
+    type: jumpstarter_driver_vnc.driver.Vnc
+    children:
+      tcp:
+        type: jumpstarter_driver_network.driver.TcpNetwork
+        config:
+          host: "127.0.0.1"
+          port: 5900 # Default VNC port
+

packages/jumpstarter-driver-vnc/jumpstarter_driver_vnc/__init__.py

@@ -0,0 +1,3 @@
+from .client import VNClient
+
+VNClient = VNClient

packages/jumpstarter-driver-vnc/jumpstarter_driver_vnc/client.py

@@ -0,0 +1,57 @@
+import webbrowser
+from dataclasses import dataclass
+
+import click
+from jumpstarter_driver_composite.client import CompositeClient
+from jumpstarter_driver_network.adapters import NovncAdapter
+
+from jumpstarter.client.decorators import driver_click_group
+
+
+@dataclass(kw_only=True)
+class VNClient(CompositeClient):
+    """Client for interacting with a VNC server."""
+
+    def session(self, open_browser: bool = True) -> str:
+        """
+        Starts a noVNC session in the browser.
+
+        param open_browser:
+            type: bool
+            default: True
+            help: Whether to open the browser automatically.
+
+        return:
+            type: str
+            description: The URL to the noVNC session.
+        """
+        with NovncAdapter(client=self.tcp) as url:
+            if open_browser:
+                webbrowser.open(url)
+            return url
+
+    def cli(self) -> click.Command:
+        """
+        Return a click command handler for this driver.
+
+        Returns:
+            The click command handler.
+        """
+
+        @driver_click_group(self)
+        def vnc():
+            """Opens a noVNC session in the browser."""
+
+        @vnc.command()
+        @click.option(
+            "--no-browser",
+            is_flag=True,
+            help="Do not open the browser automatically, just print the URL.",
+        )
+        def session(no_browser: bool):
+            """Opens a noVNC session in the browser."""
+            url = self.session(open_browser=not no_browser)
+            if no_browser:
+                click.echo(f"noVNC session available at: {url}")
+
+        return vnc

packages/jumpstarter-driver-vnc/jumpstarter_driver_vnc/driver.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+
+from jumpstarter.common.exceptions import ConfigurationError
+from jumpstarter.driver import Driver
+
+
+@dataclass(kw_only=True)
+class Vnc(Driver):
+    """Provides access to a VNC server."""
+
+    def __post_init__(self):
+        if hasattr(super(), "__post_init__"):
+            super().__post_init__()
+
+        if "tcp" not in self.children:
+            raise ConfigurationError("A tcp child is required for Vnc")
+
+    @classmethod
+    def client(cls) -> str:
+        return "jumpstarter_driver_vnc.client.VNClient"

packages/jumpstarter-driver-vnc/jumpstarter_driver_vnc/driver_test.py

@@ -0,0 +1,16 @@
+from jumpstarter_driver_composite.client import CompositeClient
+from jumpstarter_driver_network.driver import TcpNetwork
+
+from .driver import Vnc
+from jumpstarter.common.utils import serve
+
+
+def test_vnc_driver_is_composite():
+    """Test that the Vnc driver is a composite driver and requires a tcp child."""
+    instance = Vnc(
+        children={"tcp": TcpNetwork(host="127.0.0.1", port=5900)},
+    )
+
+    with serve(instance) as client:
+        assert isinstance(client, CompositeClient)
+        assert client.tcp

packages/jumpstarter-driver-vnc/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "jumpstarter-driver-vnc"
+dynamic = ["version", "urls"]
+description = "Jumpstarter driver for VNC"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Albert Esteve", email = "aesteve@redhat.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "anyio>=4.10.0",
+    "jumpstarter",
+    "jumpstarter-driver-composite",
+    "jumpstarter-driver-network",
+    "click",
+]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { 'root' = '../../'}
+
+[tool.hatch.metadata.hooks.vcs.urls]
+Homepage = "https://jumpstarter.dev"
+source_archive = "https://github.com/jumpstarter-dev/repo/archive/{commit_hash}.zip"
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=html --cov-report=xml"
+log_cli = true
+log_cli_level = "INFO"
+testpaths = ["jumpstarter_driver_vnc"]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs", "hatch-pin-jumpstarter"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.pin_jumpstarter]
+name = "pin_jumpstarter"
+
+[dependency-groups]
+dev = [
+    "pytest-cov>=6.0.0",
+    "pytest>=8.3.3",
+]

pyproject.toml

@@ -35,6 +35,7 @@ jumpstarter-driver-uboot = { workspace = true }
 jumpstarter-driver-iscsi = { workspace = true }
 jumpstarter-driver-ustreamer = { workspace = true }
 jumpstarter-driver-yepkit = { workspace = true }
+jumpstarter-driver-vnc = { workspace = true }
 jumpstarter-imagehash = { workspace = true }
 jumpstarter-kubernetes = { workspace = true }
 jumpstarter-protocol = { workspace = true }