Add 'gambaterm-telnet' server (#24)

* Add telnet server with 60pps paced output

Add gambaterm-telnet server using telnetlib3, with a simplified
architecture compared to the previous NUL-padding approach. Frame
output is paced at 60 packets per second via an asyncio forwarding
task combined with TCP_NODELAY, producing smooth rendering without
complex bandwidth estimation.

- TelnetTerminal blessed subclass (mirrors SSHTerminal pattern)
- Kitty keyboard protocol required for both SSH and telnet
- Per-user save state directories (SHA-256 hashed usernames)
- NAWS terminal resize support
- Connection stats logging and idle timeout
- --max-players and --robot-check support via telnetlib3 guard shells

* Remove telnet_input module

* Remove paced_forward_output since the run function already produces entire frames

* Add ilde-timeout option to gambaterm-telnet and kick idle clients with a graceful shutdown

---------

Co-authored-by: Vincent Michel <vxgmichel@gmail.com>

Author: jquast

README.md

@@ -125,6 +125,25 @@ $ ssh localhost -p 8022
 ```
 
 
+Telnet server
+-------------
+
+The emulator can also be served over telnet, requiring no authentication or SSH keys:
+
+```shell
+$ gambaterm-telnet myrom.gbc
+$ gambaterm-telnet --bind 0.0.0.0 --port 8023 myrom.gbc  # listen on all interfaces
+```
+
+Connect with any telnet client:
+
+```shell
+$ telnet localhost 8023
+```
+
+Clients must use a terminal that supports the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) -- connections without it are rejected. Use `--max-players N` to limit concurrent connections. 24-bit color is always assumed. Audio is not available over telnet.
+
+
 Terminal support
 ----------------
 
@@ -247,6 +266,7 @@ Here is the list of the dependencies used in this project, all great open source
 - [xlib](https://github.com/python-xlib/python-xlib)/[pynput](https://github.com/moses-palmer/pynput) - Getting keyboard inputs
 - [pygame](https://github.com/pygame/pygame) - Getting game controller inputs
 - [asyncssh](https://github.com/ronf/asyncssh) - Running the SSH server
+- [telnetlib3](https://github.com/jquast/telnetlib3) - Running the telnet server
 
 
 Contact

gambaterm/remote_terminal.py

@@ -0,0 +1,69 @@
+"""
+Provide a blessed Terminal subclass for remote (SSH/telnet) streams.
+"""
+
+from __future__ import annotations
+
+import codecs
+import contextlib
+from typing import IO, Generator
+
+from blessed import Terminal as BlessedTerminal
+from blessed.terminal import WINSZ
+
+# Python's curses.setupterm() can only be called once per process — subsequent
+# calls with a different terminal type are silently ignored. Since the SSH
+# server handles multiple concurrent connections in threads, all RemoteTerminal
+# instances share whatever terminal type was initialized first by the local
+# Terminal(). We hardcode 'xterm-256color' as the kind since:
+#   1. It's universally compatible with modern terminals
+#   2. We use standard VT100/ANSI escape codes directly, not terminfo caps
+#   3. It avoids issues where the first client's TERM value differs from subsequent
+REMOTE_TERMINAL_TYPE = "xterm-256color"
+
+
+class RemoteTerminal(BlessedTerminal):
+    """A blessed Terminal subclass for remote streams (SSH, telnet).
+
+    Stubs raw/cbreak mode (the remote connection is already raw) and
+    overrides size detection to use values provided by the server.
+    """
+
+    def __init__(
+        self,
+        stream: IO[str],
+        keyboard_fd: int,
+        rows: int,
+        columns: int,
+    ) -> None:
+        self._rows = rows
+        self._columns = columns
+        super().__init__(kind=REMOTE_TERMINAL_TYPE, stream=stream, force_styling=True)
+        # Blessed only sets _keyboard_fd when stream is sys.__stdout__, so
+        # for remote pipes we must set it and initialize the decoder manually
+        self._keyboard_fd = keyboard_fd  # type: ignore[assignment]
+        self._keyboard_decoder = codecs.getincrementaldecoder("UTF-8")()
+
+    @property
+    def is_a_tty(self) -> bool:
+        return True
+
+    @contextlib.contextmanager
+    def raw(self) -> Generator[None, None, None]:
+        yield
+
+    @contextlib.contextmanager
+    def cbreak(self) -> Generator[None, None, None]:
+        yield
+
+    def _height_and_width(self) -> WINSZ:
+        return WINSZ(
+            ws_row=self._rows,
+            ws_col=self._columns,
+            ws_xpixel=0,
+            ws_ypixel=0,
+        )
+
+    def update_size(self, rows: int, columns: int) -> None:
+        self._rows = rows
+        self._columns = columns

gambaterm/ssh.py

@@ -30,7 +30,8 @@
 from .main import add_base_arguments, add_optional_arguments, AppConfig
 from .console import Console, GameboyColor
 
-from .ssh_app_session import SSHTerminal, process_to_terminal
+from .remote_terminal import RemoteTerminal
+from .ssh_app_session import process_to_terminal
 
 
 def is_x11_display_functional(
@@ -155,7 +156,7 @@ async def ssh_process_handler(process: SSHServerProcess[str]) -> int:
 
 
 def ssh_terminal_handler(
-    terminal: SSHTerminal,
+    terminal: RemoteTerminal,
     console_callback: Callable[[], Console],
     app_config: AppConfig,
     display: str | None,
@@ -206,13 +207,8 @@ def ssh_terminal_handler(
     else:
         assert False
 
-    # Default to 24-bit color since the vast majority of modern terminals
-    # support it.
-    color_mode = (
-        app_config.color_mode
-        if app_config.color_mode is not None
-        else ColorMode.HAS_24_BIT_COLOR
-    )
+    # Kitty keyboard protocol implies 24-bit color support
+    color_mode = app_config.color_mode or ColorMode.HAS_24_BIT_COLOR
 
     print(
         f"[Terminal Info] {username}: {terminal_type}, {input_source}, {terminal.width}x{terminal.height}"

gambaterm/ssh_app_session.py

@@ -1,83 +1,21 @@
 """
-Provide an async context manager to create a blessed SSHTerminal
+Provide an async context manager to create a blessed RemoteTerminal
 from an AsyncSSH process.
 """
 from __future__ import annotations
 
 import os
-import codecs
 import asyncio
-import contextlib
 import subprocess
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager, contextmanager
-from typing import AsyncIterator, Generator, IO, Iterator, TypeVar, Callable
-
-from blessed import Terminal as BlessedTerminal
-from blessed.terminal import WINSZ
+from typing import AsyncIterator, Iterator, TypeVar, Callable
 
 from asyncssh import SSHServerProcess
 
-T = TypeVar("T")
-
-
-# Python's curses.setupterm() can only be called once per process — subsequent
-# calls with a different terminal type are silently ignored. Since the SSH
-# server handles multiple concurrent connections in threads, all SSHTerminal
-# instances share whatever terminal type was initialized first by the local
-# Terminal(). We hardcode 'xterm-256color' as the kind since:
-#   1. It's universally compatible with modern terminals
-#   2. We use standard VT100/ANSI escape codes directly, not terminfo caps
-#   3. It avoids issues where the first SSH client's TERM value differs
-SSH_TERMINAL_TYPE = "xterm-256color"
-
-
-class SSHTerminal(BlessedTerminal):
-    """A blessed Terminal subclass for SSH streams.
-
-    Following the pattern from x84 (x84/terminal.py), this stubs raw/cbreak
-    mode (SSH is already raw) and overrides size detection to use values
-    provided by the SSH server.
-    """
+from .remote_terminal import RemoteTerminal
 
-    def __init__(
-        self,
-        stream: IO[str],
-        keyboard_fd: int,
-        rows: int,
-        columns: int,
-    ) -> None:
-        self._rows = rows
-        self._columns = columns
-        super().__init__(kind=SSH_TERMINAL_TYPE, stream=stream, force_styling=True)
-        # Blessed only sets _keyboard_fd when stream is sys.__stdout__, so
-        # for SSH pipes we must set it and initialize the decoder manually
-        self._keyboard_fd = keyboard_fd  # type: ignore[assignment]
-        self._keyboard_decoder = codecs.getincrementaldecoder("UTF-8")()
-
-    @property
-    def is_a_tty(self) -> bool:
-        return True
-
-    @contextlib.contextmanager
-    def raw(self) -> Generator[None, None, None]:
-        yield
-
-    @contextlib.contextmanager
-    def cbreak(self) -> Generator[None, None, None]:
-        yield
-
-    def _height_and_width(self) -> WINSZ:
-        return WINSZ(
-            ws_row=self._rows,
-            ws_col=self._columns,
-            ws_xpixel=0,
-            ws_ypixel=0,
-        )
-
-    def update_size(self, rows: int, columns: int) -> None:
-        self._rows = rows
-        self._columns = columns
+T = TypeVar("T")
 
 
 @asynccontextmanager
@@ -118,7 +56,7 @@ async def _input_pipe_from_process(
 
 @contextmanager
 def _bind_resize(
-    process: SSHServerProcess[str], ssh_term: SSHTerminal
+    process: SSHServerProcess[str], ssh_term: RemoteTerminal
 ) -> Iterator[None]:
     original_method = process.terminal_size_changed
 
@@ -138,9 +76,9 @@ def terminal_size_changed(
 async def process_to_terminal(
     process: SSHServerProcess[str],
     executor: ThreadPoolExecutor,
-    target: Callable[[SSHTerminal], T],
+    target: Callable[[RemoteTerminal], T],
 ) -> T:
-    """Create a blessed SSHTerminal from an SSH process.
+    """Create a blessed RemoteTerminal from an SSH process.
 
     Once the redirections are set up, I/O become synchronous,
     so we run the target function in a thread executor to avoid blocking the event loop
@@ -151,7 +89,7 @@ async def process_to_terminal(
 
     def _target() -> T:
         with open(write_fd, "w", newline="\r\n") as stream:
-            ssh_term = SSHTerminal(
+            ssh_term = RemoteTerminal(
                 stream=stream,
                 keyboard_fd=keyboard_fd,
                 rows=height,