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/index.md

@@ -42,6 +42,7 @@ Drivers that provide various communication interfaces:
   Protocol
 * **[TFTP](tftp.md)** (`jumpstarter-driver-tftp`) - Trivial File Transfer
   Protocol
+* **[VNC](vnc.md)** (`jumpstarter-driver-vnc`) - VNC (Virtual Network Computing) remote desktop protocol
 
 ### Storage and Data Drivers
 
@@ -111,5 +112,6 @@ tmt.md
 tftp.md
 uboot.md
 ustreamer.md
+vnc.md
 yepkit.md
 ```

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,58 @@
+# 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`. By default, it will open the session URL in your default web browser.
+
+**Usage:**
+
+```shell
+# This will start the local server and open a browser.
+j vnc session
+
+# To prevent it from opening a browser automatically:
+j vnc session --no-browser
+```

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

@@ -0,0 +1,16 @@
+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: 5901 # Default VNC port for display :1

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,58 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import typing
+import webbrowser
+
+import anyio
+import click
+from jumpstarter_driver_composite.client import CompositeClient
+from jumpstarter_driver_network.adapters.novnc import NovncAdapter
+
+from jumpstarter.client.decorators import driver_click_group
+
+if typing.TYPE_CHECKING:
+    from jumpstarter_driver_network.client import TCPClient
+
+
+class VNClient(CompositeClient):
+    """Client for interacting with a VNC server."""
+
+    @property
+    def tcp(self) -> TCPClient:
+        """Get the TCP client."""
+        return self.children["tcp"]
+
+    @contextlib.contextmanager
+    def session(self) -> typing.Iterator[str]:
+        """Create a new VNC session."""
+        with NovncAdapter(client=self.tcp, method="connect") as adapter:
+            yield adapter
+
+    def cli(self) -> click.Command:
+        """Return a click command handler for this driver."""
+
+        @driver_click_group(self)
+        def vnc():
+            """Open a VNC session."""
+
+        @vnc.command()
+        @click.option("--browser/--no-browser", default=True, help="Open the session in a web browser.")
+        def session(browser: bool):
+            """Open a VNC session."""
+            # The NovncAdapter is a blocking context manager that runs in a thread.
+            # We can enter it, open the browser, and then just wait for the user
+            # to press Ctrl+C to exit. The adapter handles the background work.
+            with self.session() as url:
+                click.echo(f"To connect, please visit: {url}")
+                if browser:
+                    webbrowser.open(url)
+                click.echo("Press Ctrl+C to close the VNC session.")
+                try:
+                    # Use the client's own portal to wait for cancellation.
+                    self.portal.call(asyncio.Event().wait)
+                except (KeyboardInterrupt, anyio.get_cancelled_exc_class()):
+                    click.echo("\nClosing VNC session.")
+
+        return vnc

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

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from jumpstarter.common.exceptions import ConfigurationError
+from jumpstarter.driver import Driver
+
+
+class Vnc(Driver):
+    """A driver for VNC."""
+
+    def __post_init__(self):
+        """Initialize the VNC driver."""
+        super().__post_init__()
+        if "tcp" not in self.children:
+            raise ConfigurationError("A tcp child is required for Vnc")
+
+    @classmethod
+    def client(cls) -> str:
+        """Return the client class path for this driver."""
+        return "jumpstarter_driver_vnc.client.VNClient"

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

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import pytest
+from jumpstarter_driver_composite.client import CompositeClient
+
+from jumpstarter.common.exceptions import ConfigurationError
+from jumpstarter.common.utils import serve
+from jumpstarter.driver import Driver
+
+
+class FakeTcpDriver(Driver):
+    @classmethod
+    def client(cls) -> str:
+        return "jumpstarter.client.DriverClient"
+
+
+class Vnc(Driver):
+    """A mock VNC driver for testing."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+    def __post_init__(self):
+        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"
+
+
+def test_vnc_client_is_composite():
+    """Test that the Vnc driver produces a composite client."""
+    instance = Vnc(
+        children={"tcp": FakeTcpDriver()},
+    )
+
+    with serve(instance) as client:
+        assert isinstance(client, CompositeClient)
+        assert client.tcp
+
+
+def test_vnc_driver_raises_error_without_tcp_child():
+    """Test that the Vnc driver raises a ConfigurationError if the tcp child is missing."""
+    with pytest.raises(ConfigurationError, match="A tcp child is required for Vnc"):
+        Vnc(children={})

packages/jumpstarter-driver-vnc/pyproject.toml

@@ -0,0 +1,48 @@
+[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",
+]
+
+[project.entry-points."jumpstarter.drivers"]
+vnc = "jumpstarter_driver_vnc.driver:Vnc"
+
+[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 }