可用性改动

webshare/_binary_encode.py

@@ -0,0 +1,325 @@
+"""
+An encoding / decoding format suitable for serializing data structures to binary.
+
+This is based on https://en.wikipedia.org/wiki/Bencode with some extensions.
+
+The following data types may be encoded:
+
+- None
+- int
+- bool
+- bytes
+- str
+- list
+- tuple
+- dict
+
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class DecodeError(Exception):
+    """A problem decoding data."""
+
+
+def dump(data: object) -> bytes:
+    """Encodes a data structure in to bytes.
+
+    Args:
+        data: Data structure
+
+    Returns:
+        A byte string encoding the data.
+    """
+
+    def encode_none(_datum: None) -> bytes:
+        """
+        Encodes a None value.
+
+        Args:
+            datum: Always None.
+
+        Returns:
+            None encoded.
+        """
+        return b"N"
+
+    def encode_bool(datum: bool) -> bytes:
+        """
+        Encode a boolean value.
+
+        Args:
+            datum: The boolean value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"T" if datum else b"F"
+
+    def encode_int(datum: int) -> bytes:
+        """
+        Encode an integer value.
+
+        Args:
+            datum: The integer value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"i%ie" % datum
+
+    def encode_bytes(datum: bytes) -> bytes:
+        """
+        Encode a bytes value.
+
+        Args:
+            datum: The bytes value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"%i:%s" % (len(datum), datum)
+
+    def encode_string(datum: str) -> bytes:
+        """
+        Encode a string value.
+
+        Args:
+            datum: The string value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        encoded_data = datum.encode("utf-8")
+        return b"s%i:%s" % (len(encoded_data), encoded_data)
+
+    def encode_list(datum: list) -> bytes:
+        """
+        Encode a list value.
+
+        Args:
+            datum: The list value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"l%se" % b"".join(encode(element) for element in datum)
+
+    def encode_tuple(datum: tuple) -> bytes:
+        """
+        Encode a tuple value.
+
+        Args:
+            datum: The tuple value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"t%se" % b"".join(encode(element) for element in datum)
+
+    def encode_dict(datum: dict) -> bytes:
+        """
+        Encode a dictionary value.
+
+        Args:
+            datum: The dictionary value to encode.
+
+        Returns:
+            The encoded bytes.
+        """
+        return b"d%se" % b"".join(
+            b"%s%s" % (encode(key), encode(value)) for key, value in datum.items()
+        )
+
+    ENCODERS: dict[type, Callable[[Any], Any]] = {
+        type(None): encode_none,
+        bool: encode_bool,
+        int: encode_int,
+        bytes: encode_bytes,
+        str: encode_string,
+        list: encode_list,
+        tuple: encode_tuple,
+        dict: encode_dict,
+    }
+
+    def encode(datum: object) -> bytes:
+        """Recursively encode data.
+
+        Args:
+            datum: Data suitable for encoding.
+
+        Raises:
+            TypeError: If `datum` is not one of the supported types.
+
+        Returns:
+            Encoded data bytes.
+        """
+        try:
+            decoder = ENCODERS[type(datum)]
+        except KeyError:
+            raise TypeError("Can't encode {datum!r}") from None
+        return decoder(datum)
+
+    return encode(data)
+
+
+def load(encoded: bytes) -> object:
+    """Load an encoded data structure from bytes.
+
+    Args:
+        encoded: Encoded data in bytes.
+
+    Raises:
+        DecodeError: If an error was encountered decoding the string.
+
+    Returns:
+        Decoded data.
+    """
+    if not isinstance(encoded, bytes):
+        raise TypeError("must be bytes")
+    max_position = len(encoded)
+    position = 0
+
+    def get_byte() -> bytes:
+        """Get an encoded byte and advance position.
+
+        Raises:
+            DecodeError: If the end of the data was reached
+
+        Returns:
+            A bytes object with a single byte.
+        """
+        nonlocal position
+        if position >= max_position:
+            raise DecodeError("More data expected")
+        character = encoded[position : position + 1]
+        position += 1
+        return character
+
+    def peek_byte() -> bytes:
+        """Get the byte at the current position, but don't advance position.
+
+        Returns:
+            A bytes object with a single byte.
+        """
+        return encoded[position : position + 1]
+
+    def get_bytes(size: int) -> bytes:
+        """Get a number of bytes of encode data.
+
+        Args:
+            size: Number of bytes to retrieve.
+
+        Raises:
+            DecodeError: If there aren't enough bytes.
+
+        Returns:
+            A bytes object.
+        """
+        nonlocal position
+        bytes_data = encoded[position : position + size]
+        if len(bytes_data) != size:
+            raise DecodeError(b"Missing bytes in {bytes_data!r}")
+        position += size
+        return bytes_data
+
+    def decode_int() -> int:
+        """Decode an int from the encoded data.
+
+        Returns:
+            An integer.
+        """
+        int_bytes = b""
+        while (byte := get_byte()) != b"e":
+            int_bytes += byte
+        return int(int_bytes)
+
+    def decode_bytes(size_bytes: bytes) -> bytes:
+        """Decode a bytes string from the encoded data.
+
+        Returns:
+            A bytes object.
+        """
+        while (byte := get_byte()) != b":":
+            size_bytes += byte
+        bytes_string = get_bytes(int(size_bytes))
+        return bytes_string
+
+    def decode_string() -> str:
+        """Decode a (utf-8 encoded) string from the encoded data.
+
+        Returns:
+            A string.
+        """
+        size_bytes = b""
+        while (byte := get_byte()) != b":":
+            size_bytes += byte
+        bytes_string = get_bytes(int(size_bytes))
+        decoded_string = bytes_string.decode("utf-8", errors="replace")
+        return decoded_string
+
+    def decode_list() -> list[object]:
+        """Decode a list.
+
+        Returns:
+            A list of data.
+        """
+        elements: list[object] = []
+        add_element = elements.append
+        while peek_byte() != b"e":
+            add_element(decode())
+        get_byte()
+        return elements
+
+    def decode_tuple() -> tuple[object, ...]:
+        """Decode a tuple.
+
+        Returns:
+            A tuple of decoded data.
+        """
+        elements: list[object] = []
+        add_element = elements.append
+        while peek_byte() != b"e":
+            add_element(decode())
+        get_byte()
+        return tuple(elements)
+
+    def decode_dict() -> dict[object, object]:
+        """Decode a dict.
+
+        Returns:
+            A dict of decoded data.
+        """
+        elements: dict[object, object] = {}
+        add_element = elements.__setitem__
+        while peek_byte() != b"e":
+            add_element(decode(), decode())
+        get_byte()
+        return elements
+
+    DECODERS = {
+        b"i": decode_int,
+        b"s": decode_string,
+        b"l": decode_list,
+        b"t": decode_tuple,
+        b"d": decode_dict,
+        b"T": lambda: True,
+        b"F": lambda: False,
+        b"N": lambda: None,
+    }
+
+    def decode() -> object:
+        """Recursively decode data.
+
+        Returns:
+            Decoded data.
+        """
+        decoder = DECODERS.get(initial := get_byte(), None)
+        if decoder is None:
+            return decode_bytes(initial)
+        return decoder()
+
+    return decode()

webshare/app_service.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+from pathlib import Path
+
+import asyncio
+import io
+import json
+import os
+from typing import Awaitable, Callable, Literal
+from asyncio.subprocess import Process
+import logging
+
+from importlib.metadata import version
+import uuid
+
+from webshare.download_manager import DownloadManager
+from webshare._binary_encode import load as binary_load
+
+log = logging.getLogger("textual-serve")
+
+
+class AppService:
+    """Creates and manages a single Textual app subprocess.
+
+    When a user connects to the websocket in their browser, a new AppService
+    instance is created to manage the corresponding Textual app process.
+    """
+
+    def __init__(
+        self,
+        command: str,
+        *,
+        write_bytes: Callable[[bytes], Awaitable[None]],
+        write_str: Callable[[str], Awaitable[None]],
+        close: Callable[[], Awaitable[None]],
+        download_manager: DownloadManager,
+        debug: bool = False,
+    ) -> None:
+        self.app_service_id: str = uuid.uuid4().hex
+        """The unique ID of this running app service."""
+        self.command = command
+        """The command to launch the Textual app subprocess."""
+        self.remote_write_bytes = write_bytes
+        """Write bytes to the client browser websocket."""
+        self.remote_write_str = write_str
+        """Write string to the client browser websocket."""
+        self.remote_close = close
+        """Close the client browser websocket."""
+        self.debug = debug
+        """Enable/disable debug mode."""
+
+        self._process: Process | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._stdin: asyncio.StreamWriter | None = None
+        self._exit_event = asyncio.Event()
+        self._download_manager = download_manager
+
+    @property
+    def stdin(self) -> asyncio.StreamWriter:
+        """The processes standard input stream."""
+        assert self._stdin is not None
+        return self._stdin
+
+    def _build_environment(self, width: int = 80, height: int = 24) -> dict[str, str]:
+        """Build an environment dict for the App subprocess.
+
+        Args:
+            width: Initial width.
+            height: Initial height.
+
+        Returns:
+            A environment dict.
+        """
+        environment = dict(os.environ.copy())
+        environment["TEXTUAL_DRIVER"] = "textual.drivers.web_driver:WebDriver"
+        environment["TEXTUAL_FPS"] = "60"
+        environment["TEXTUAL_COLOR_SYSTEM"] = "truecolor"
+        environment["TERM_PROGRAM"] = "textual"
+        environment["TERM_PROGRAM_VERSION"] = version("textual-serve")
+        environment["COLUMNS"] = str(width)
+        environment["ROWS"] = str(height)
+        if self.debug:
+            environment["TEXTUAL"] = "debug,devtools"
+            environment["TEXTUAL_LOG"] = "textual.log"
+        return environment
+
+    async def _open_app_process(self, width: int = 80, height: int = 24) -> Process:
+        """Open a process to run the app.
+
+        Args:
+            width: Width of the terminal.
+            height: height of the terminal.
+        """
+        environment = self._build_environment(width=width, height=height)
+        self._process = process = await asyncio.create_subprocess_shell(
+            self.command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=environment,
+        )
+        assert process.stdin is not None
+        self._stdin = process.stdin
+
+        return process
+
+    @classmethod
+    def encode_packet(cls, packet_type: Literal[b"D", b"M"], payload: bytes) -> bytes:
+        """Encode a packet.
+
+        Args:
+            packet_type: The packet type (b"D" for data or b"M" for meta)
+            payload: The payload.
+
+        Returns:
+            Data as bytes.
+        """
+        return b"%s%s%s" % (packet_type, len(payload).to_bytes(4, "big"), payload)
+
+    async def send_bytes(self, data: bytes) -> bool:
+        """Send bytes to process.
+
+        Args:
+            data: Data to send.
+
+        Returns:
+            True if the data was sent, otherwise False.
+        """
+        stdin = self.stdin
+        try:
+            stdin.write(self.encode_packet(b"D", data))
+        except RuntimeError:
+            return False
+        try:
+            await stdin.drain()
+        except Exception:
+            return False
+        return True
+
+    async def send_meta(self, data: dict[str, str | None | int | bool]) -> bool:
+        """Send meta information to process.
+
+        Args:
+            data: Meta dict to send.
+
+        Returns:
+            True if the data was sent, otherwise False.
+        """
+        stdin = self.stdin
+        data_bytes = json.dumps(data).encode("utf-8")
+        try:
+            stdin.write(self.encode_packet(b"M", data_bytes))
+        except RuntimeError:
+            return False
+        try:
+            await stdin.drain()
+        except Exception:
+            return False
+        return True
+
+    async def set_terminal_size(self, width: int, height: int) -> None:
+        """Tell the process about the new terminal size.
+
+        Args:
+            width: Width of terminal in cells.
+            height: Height of terminal in cells.
+        """
+        await self.send_meta(
+            {
+                "type": "resize",
+                "width": width,
+                "height": height,
+            }
+        )
+
+    async def blur(self) -> None:
+        """Send an (app) blur to the process."""
+        await self.send_meta({"type": "blur"})
+
+    async def focus(self) -> None:
+        """Send an (app) focus to the process."""
+        await self.send_meta({"type": "focus"})
+
+    async def start(self, width: int, height: int) -> None:
+        await self._open_app_process(width, height)
+        self._task = asyncio.create_task(self.run())
+
+    async def stop(self) -> None:
+        """Stop the process and wait for it to complete."""
+        if self._task is not None:
+            await self._download_manager.cancel_app_downloads(
+                app_service_id=self.app_service_id
+            )
+
+            await self.send_meta({"type": "quit"})
+            await self._task
+            self._task = None
+
+    async def run(self) -> None:
+        """Run the Textual app process.
+
+        !!! note
+
+            Do not call this manually, use `start`.
+
+        """
+        META = b"M"
+        DATA = b"D"
+        PACKED = b"P"
+
+        assert self._process is not None
+        process = self._process
+
+        stdout = process.stdout
+        stderr = process.stderr
+        assert stdout is not None
+        assert stderr is not None
+
+        stderr_data = io.BytesIO()
+
+        async def read_stderr() -> None:
+            """Task to read stderr."""
+            try:
+                while True:
+                    data = await stderr.read(1024 * 4)
+                    if not data:
+                        break
+                    stderr_data.write(data)
+            except asyncio.CancelledError:
+                pass
+
+        stderr_task = asyncio.create_task(read_stderr())
+
+        try:
+            ready = False
+            # Wait for prelude text, so we know it is a Textual app
+            for _ in range(10):
+                if not (line := await stdout.readline()):
+                    break
+                if line == b"__GANGLION__\n":
+                    ready = True
+                    break
+
+            if not ready:
+                log.error("Application failed to start")
+                if error_text := stderr_data.getvalue():
+                    import sys
+
+                    sys.stdout.write(error_text.decode("utf-8", "replace"))
+
+            readexactly = stdout.readexactly
+            int_from_bytes = int.from_bytes
+            while True:
+                type_bytes = await readexactly(1)
+                size_bytes = await readexactly(4)
+                size = int_from_bytes(size_bytes, "big")
+                payload = await readexactly(size)
+                if type_bytes == DATA:
+                    await self.on_data(payload)
+                elif type_bytes == META:
+                    await self.on_meta(payload)
+                elif type_bytes == PACKED:
+                    await self.on_packed(payload)
+
+        except asyncio.IncompleteReadError:
+            pass
+        except ConnectionResetError:
+            pass
+        except asyncio.CancelledError:
+            pass
+
+        finally:
+            stderr_task.cancel()
+            await stderr_task
+
+        if error_text := stderr_data.getvalue():
+            import sys
+
+            sys.stdout.write(error_text.decode("utf-8", "replace"))
+
+    async def on_data(self, payload: bytes) -> None:
+        """Called when there is data.
+
+        Args:
+            payload: Data received from process.
+        """
+        await self.remote_write_bytes(payload)
+
+    async def on_meta(self, data: bytes) -> None:
+        """Called when there is a meta packet sent from the running app process.
+
+        Args:
+            data: Encoded meta data.
+        """
+        meta_data: dict[str, object] = json.loads(data)
+        meta_type = meta_data["type"]
+
+        if meta_type == "exit":
+            await self.remote_close()
+        elif meta_type == "open_url":
+            payload = json.dumps(
+                [
+                    "open_url",
+                    {
+                        "url": meta_data["url"],
+                        "new_tab": meta_data["new_tab"],
+                    },
+                ]
+            )
+            await self.remote_write_str(payload)
+        elif meta_type == "deliver_file_start":
+            log.debug("deliver_file_start, %s", meta_data)
+            try:
+                # Record this delivery key as available for download.
+                delivery_key = str(meta_data["key"])
+                await self._download_manager.create_download(
+                    app_service=self,
+                    delivery_key=delivery_key,
+                    file_name=Path(meta_data["path"]).name,
+                    open_method=meta_data["open_method"],
+                    mime_type=meta_data["mime_type"],
+                    encoding=meta_data["encoding"],
+                    name=meta_data.get("name", None),
+                )
+            except KeyError:
+                log.error("Missing key in `deliver_file_start` meta packet")
+                return
+            else:
+                # Tell the browser front-end about the new delivery key,
+                # so that it may hit the "/download/{key}" endpoint
+                # to start the download.
+                json_string = json.dumps(["deliver_file_start", delivery_key])
+                await self.remote_write_str(json_string)
+        else:
+            log.warning(
+                f"Unknown meta type: {meta_type!r}. You may need to update `textual-serve`."
+            )
+
+    async def on_packed(self, payload: bytes) -> None:
+        """Called when there is a packed packet sent from the running app process.
+
+        Args:
+            payload: Encoded packed data.
+        """
+        unpacked = binary_load(payload)
+        if unpacked[0] == "deliver_chunk":
+            # If we receive a chunk, hand it to the download manager to
+            # handle distribution to the browser.
+            _, delivery_key, chunk = unpacked
+            await self._download_manager.chunk_received(delivery_key, chunk)

webshare/download_manager.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+import logging
+from typing import AsyncGenerator, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from webshare.app_service import AppService
+
+log = logging.getLogger("textual-serve")
+
+DOWNLOAD_TIMEOUT = 4
+DOWNLOAD_CHUNK_SIZE = 1024 * 64  # 64 KB
+
+
+@dataclass
+class Download:
+    app_service: "AppService"
+    """The app service that the download is associated with."""
+
+    delivery_key: str
+    """Key which identifies the download."""
+
+    file_name: str
+    """The name of the file to download. This will be used to set
+    the Content-Disposition filename."""
+
+    open_method: str
+    """The method to open the file with. "browser" or "download"."""
+
+    mime_type: str
+    """The mime type of the content."""
+
+    encoding: str | None = None
+    """The encoding of the content.
+    Will be None if the content is binary.
+    """
+
+    name: str | None = None
+    """Optional name set bt the client."""
+
+    incoming_chunks: asyncio.Queue[bytes | None] = field(default_factory=asyncio.Queue)
+    """A queue of incoming chunks for the download.
+    Chunks are sent from the app service to the download handler
+    via this queue."""
+
+
+class DownloadManager:
+    """Class which manages downloads for the server.
+
+    Serves as the link between the web server and app processes during downloads.
+
+    A single server has a single download manager, which manages all downloads for all
+    running app processes.
+    """
+
+    def __init__(self) -> None:
+        self._active_downloads: dict[str, Download] = {}
+        """A dictionary of active downloads.
+
+        When a delivery key is received in a meta packet, it is added to this set.
+        When the user hits the "/download/{key}" endpoint, we ensure the key is in
+        this set and start the download by requesting chunks from the app process.
+
+        When the download is complete, the app process sends a "deliver_file_end"
+        meta packet, and we remove the key from this set.
+        """
+
+    async def create_download(
+        self,
+        *,
+        app_service: "AppService",
+        delivery_key: str,
+        file_name: str,
+        open_method: str,
+        mime_type: str,
+        encoding: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        """Prepare for a new download.
+
+        Args:
+            app_service: The app service to start the download for.
+            delivery_key: The delivery key to start the download for.
+            file_name: The name of the file to download.
+            open_method: The method to open the file with.
+            mime_type: The mime type of the content.
+            encoding: The encoding of the content or None if the content is binary.
+        """
+        self._active_downloads[delivery_key] = Download(
+            app_service,
+            delivery_key,
+            file_name,
+            open_method,
+            mime_type,
+            encoding,
+            name=name,
+        )
+
+    async def download(self, delivery_key: str) -> AsyncGenerator[bytes, None]:
+        """Download a file from the given app service.
+
+        Args:
+            delivery_key: The delivery key to download.
+        """
+
+        app_service = await self._get_app_service(delivery_key)
+        download = self._active_downloads[delivery_key]
+        incoming_chunks = download.incoming_chunks
+
+        while True:
+            # Request a chunk from the app service.
+            send_result = await app_service.send_meta(
+                {
+                    "type": "deliver_chunk_request",
+                    "key": delivery_key,
+                    "size": DOWNLOAD_CHUNK_SIZE,
+                    "name": download.name,
+                }
+            )
+
+            if not send_result:
+                log.warning(
+                    "Download {delivery_key!r} failed to request chunk from app service"
+                )
+                del self._active_downloads[delivery_key]
+                break
+
+            try:
+                chunk = await asyncio.wait_for(incoming_chunks.get(), DOWNLOAD_TIMEOUT)
+            except asyncio.TimeoutError:
+                log.warning(
+                    "Download %r failed to receive chunk from app service within %r seconds",
+                    delivery_key,
+                    DOWNLOAD_TIMEOUT,
+                )
+                chunk = None
+
+            if not chunk:
+                # Empty chunk - the app process has finished sending the file
+                # or the download has been cancelled.
+                incoming_chunks.task_done()
+                del self._active_downloads[delivery_key]
+                break
+            else:
+                incoming_chunks.task_done()
+                yield chunk
+
+    async def chunk_received(self, delivery_key: str, chunk: bytes | str) -> None:
+        """Handle a chunk received from the app service for a download.
+
+        Args:
+            delivery_key: The delivery key that the chunk was received for.
+            chunk: The chunk that was received.
+        """
+
+        download = self._active_downloads.get(delivery_key)
+        if not download:
+            # The download may have been cancelled - e.g. the websocket
+            # was closed before the download could complete.
+            log.debug("Chunk received for cancelled download %r", delivery_key)
+            return
+
+        if isinstance(chunk, str):
+            chunk = chunk.encode(download.encoding or "utf-8")
+        await download.incoming_chunks.put(chunk)
+
+    async def _get_app_service(self, delivery_key: str) -> "AppService":
+        """Get the app service that the given delivery key is linked to.
+
+        Args:
+            delivery_key: The delivery key to get the app service for.
+        """
+        for key in self._active_downloads.keys():
+            if key == delivery_key:
+                return self._active_downloads[key].app_service
+        else:
+            raise ValueError(f"No active download for delivery key {delivery_key!r}")
+
+    async def get_download_metadata(self, delivery_key: str) -> Download:
+        """Get the metadata for a download.
+
+        Args:
+            delivery_key: The delivery key to get the metadata for.
+        """
+        return self._active_downloads[delivery_key]
+
+    async def cancel_app_downloads(self, app_service_id: str) -> None:
+        """Cancel all downloads for the given app service.
+
+        Args:
+            app_service_id: The app service ID to cancel downloads for.
+        """
+        for download in self._active_downloads.values():
+            if download.app_service.app_service_id == app_service_id:
+                await download.incoming_chunks.put(None)

webshare/server.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+import asyncio
+
+import logging
+import os
+from pathlib import Path
+import signal
+import sys
+
+from typing import Any
+
+import aiohttp_jinja2
+from aiohttp import web
+from aiohttp import WSMsgType
+from aiohttp.web_runner import GracefulExit
+import jinja2
+
+from importlib.metadata import version
+
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.highlighter import RegexHighlighter
+
+from webshare.download_manager import DownloadManager
+
+from .app_service import AppService
+
+log = logging.getLogger("textual-serve")
+
+LOGO = r"""[bold magenta]___ ____ _  _ ___ _  _ ____ _       ____ ____ ____ _  _ ____ 
+ |  |___  \/   |  |  | |__| |    __ [__  |___ |__/ |  | |___ 
+ |  |___ _/\_  |  |__| |  | |___    ___] |___ |  \  \/  |___ [not bold]VVVVV
+""".replace("VVVVV", f"v{version('textual-serve')}")
+
+
+WINDOWS = sys.platform == "WINDOWS"
+
+
+class LogHighlighter(RegexHighlighter):
+    base_style = "repr."
+    highlights = [
+        r"(?P<number>(?<!\w)\-?[0-9]+\.?[0-9]*(e[-+]?\d+?)?\b|0x[0-9a-fA-F]*)",
+        r"(?P<path>\[.*?\])",
+        r"(?<![\\\w])(?P<str>b?'''.*?(?<!\\)'''|b?'.*?(?<!\\)'|b?\"\"\".*?(?<!\\)\"\"\"|b?\".*?(?<!\\)\")",
+    ]
+
+
+def to_int(value: str, default: int) -> int:
+    """Convert to an integer, or return a default if that's not possible.
+
+    Args:
+        number: A string possibly containing a decimal.
+        default: Default value if value can't be decoded.
+
+    Returns:
+        Integer.
+    """
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+class Server:
+    """Serve a Textual app."""
+
+    def __init__(
+        self,
+        command: str,
+        host: str = "localhost",
+        port: int = 8000,
+        title: str | None = None,
+        public_url: str | None = None,
+        statics_path: str | os.PathLike = "./static",
+        templates_path: str | os.PathLike = "./templates",
+    ):
+        """
+
+        Args:
+            app_factory: A callable that returns a new App instance.
+            host: Host of web application.
+            port: Port for server.
+            statics_path: Path to statics folder. May be absolute or relative to server.py.
+            templates_path" Path to templates folder. May be absolute or relative to server.py.
+        """
+        self.command = command
+        self.host = host
+        self.port = port
+        self.title = title or command
+        self.debug = False
+
+        if public_url is None:
+            if self.port == 80:
+                self.public_url = f"http://{self.host}"
+            elif self.port == 443:
+                self.public_url = f"https://{self.host}"
+            else:
+                self.public_url = f"http://{self.host}:{self.port}"
+        else:
+            self.public_url = public_url
+
+        base_path = (Path(__file__) / "../").resolve().absolute()
+        self.statics_path = base_path / statics_path
+        self.templates_path = base_path / templates_path
+        self.console = Console()
+        self.download_manager = DownloadManager()
+
+    def initialize_logging(self) -> None:
+        """Initialize logging.
+
+        May be overridden in a subclass.
+        """
+        FORMAT = "%(message)s"
+        logging.basicConfig(
+            level="DEBUG" if self.debug else "INFO",
+            format=FORMAT,
+            datefmt="[%X]",
+            handlers=[
+                RichHandler(
+                    show_path=False,
+                    show_time=False,
+                    rich_tracebacks=True,
+                    tracebacks_show_locals=True,
+                    highlighter=LogHighlighter(),
+                    console=self.console,
+                )
+            ],
+        )
+
+    def request_exit(self) -> None:
+        """Gracefully exit the app."""
+        raise GracefulExit()
+
+    async def _make_app(self) -> web.Application:
+        """Make the aiohttp web.Application.
+
+        Returns:
+            New aiohttp web application.
+        """
+        app = web.Application()
+
+        aiohttp_jinja2.setup(app, loader=jinja2.FileSystemLoader(self.templates_path))
+
+        ROUTES = [
+            web.get("/", self.handle_index, name="index"),
+            web.get("/ws", self.handle_websocket, name="websocket"),
+            web.get("/download/{key}", self.handle_download, name="download"),
+            web.static("/static", self.statics_path, show_index=True, name="static"),
+        ]
+        app.add_routes(ROUTES)
+
+        app.on_startup.append(self.on_startup)
+        app.on_shutdown.append(self.on_shutdown)
+        return app
+
+    async def handle_download(self, request: web.Request) -> web.StreamResponse:
+        """Handle a download request."""
+        key = request.match_info["key"]
+
+        try:
+            download_meta = await self.download_manager.get_download_metadata(key)
+        except KeyError:
+            raise web.HTTPNotFound(text=f"Download with key {key!r} not found")
+
+        response = web.StreamResponse()
+        mime_type = download_meta.mime_type
+
+        content_type = mime_type
+        if download_meta.encoding:
+            content_type += f"; charset={download_meta.encoding}"
+
+        response.headers["Content-Type"] = content_type
+        disposition = (
+            "inline" if download_meta.open_method == "browser" else "attachment"
+        )
+        response.headers["Content-Disposition"] = (
+            f"{disposition}; filename={download_meta.file_name}"
+        )
+
+        await response.prepare(request)
+
+        async for chunk in self.download_manager.download(key):
+            await response.write(chunk)
+
+        await response.write_eof()
+        return response
+
+    async def on_shutdown(self, app: web.Application) -> None:
+        """Called on shutdown.
+
+        Args:
+            app: App instance.
+        """
+
+    async def on_startup(self, app: web.Application) -> None:
+        """Called on startup.
+
+        Args:
+            app: App instance.
+        """
+
+        self.console.print(LOGO, highlight=False)
+        self.console.print(f"Serving {self.command!r} on {self.public_url}")
+        self.console.print("\n[cyan]Press Ctrl+C to quit")
+
+    def serve(self, debug: bool = False) -> None:
+        """Serve the Textual application.
+
+        This will run a local webserver until it is closed with Ctrl+C
+
+        """
+        self.debug = debug
+        self.initialize_logging()
+
+        loop = asyncio.get_event_loop()
+        try:
+            loop.add_signal_handler(signal.SIGINT, self.request_exit)
+            loop.add_signal_handler(signal.SIGTERM, self.request_exit)
+        except NotImplementedError:
+            pass
+
+        if self.debug:
+            log.info("Running in debug mode. You may use textual dev tools.")
+
+        web.run_app(
+            self._make_app(),
+            host=self.host,
+            port=self.port,
+            handle_signals=False,
+            loop=loop,
+            print=lambda *args: None,
+        )
+
+    @aiohttp_jinja2.template("app_index.html")
+    async def handle_index(self, request: web.Request) -> dict[str, Any]:
+        """Serves the HTML for an app.
+
+        Args:
+            request: Request object.
+
+        Returns:
+            Template data.
+        """
+        router = request.app.router
+        font_size = to_int(request.query.get("fontsize", "16"), 16)
+
+        def get_url(route: str, **args) -> str:
+            """Get a URL from the aiohttp router."""
+            path = router[route].url_for(**args)
+            return f"{self.public_url}{path}"
+
+        def get_websocket_url(route: str, **args) -> str:
+            """Get a URL with a websocket prefix."""
+            url = get_url(route, **args)
+
+            if self.public_url.startswith("https"):
+                return "wss:" + url.split(":", 1)[1]
+            else:
+                return "ws:" + url.split(":", 1)[1]
+
+        context = {
+            "font_size": font_size,
+            "app_websocket_url": get_websocket_url("websocket"),
+        }
+        context["config"] = {
+            "static": {
+                "url": get_url("static", filename="/").rstrip("/") + "/",
+            },
+        }
+        context["application"] = {
+            "name": self.title,
+        }
+        return context
+
+    async def _process_messages(
+        self, websocket: web.WebSocketResponse, app_service: AppService
+    ) -> None:
+        """Process messages from the client browser websocket.
+
+        Args:
+            websocket: Websocket instance.
+            app_service: App service.
+        """
+        TEXT = WSMsgType.TEXT
+
+        async for message in websocket:
+            if message.type != TEXT:
+                continue
+            envelope = message.json()
+            assert isinstance(envelope, list)
+            type_ = envelope[0]
+            if type_ == "stdin":
+                data = envelope[1]
+                await app_service.send_bytes(data.encode("utf-8"))
+            elif type_ == "resize":
+                data = envelope[1]
+                await app_service.set_terminal_size(data["width"], data["height"])
+            elif type_ == "ping":
+                data = envelope[1]
+                await websocket.send_json(["pong", data])
+            elif type_ == "blur":
+                await app_service.blur()
+            elif type_ == "focus":
+                await app_service.focus()
+
+    async def handle_websocket(self, request: web.Request) -> web.WebSocketResponse:
+        """Handle the websocket that drives the remote process.
+
+        This is called when the browser connects to the websocket.
+
+        Args:
+            request: Request object.
+
+        Returns:
+            Websocket response.
+        """
+        websocket = web.WebSocketResponse(heartbeat=15)
+
+        width = to_int(request.query.get("width", "80"), 80)
+        height = to_int(request.query.get("height", "24"), 24)
+
+        app_service: AppService | None = None
+        try:
+            await websocket.prepare(request)
+            app_service = AppService(
+                self.command,
+                write_bytes=websocket.send_bytes,
+                write_str=websocket.send_str,
+                close=websocket.close,
+                download_manager=self.download_manager,
+                debug=self.debug,
+            )
+            await app_service.start(width, height)
+            try:
+                await self._process_messages(websocket, app_service)
+            finally:
+                await app_service.stop()
+
+        except asyncio.CancelledError:
+            await websocket.close()
+
+        except Exception as error:
+            log.exception(error)
+
+        finally:
+            if app_service is not None:
+                await app_service.stop()
+
+        return websocket

webshare/static/css/xterm.css

@@ -0,0 +1,191 @@
+/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */
+
+/**
+ *  Default styles for xterm.js
+ */
+
+ .xterm {
+    cursor: text;
+    position: relative;
+    user-select: none;
+    -ms-user-select: none;
+    -webkit-user-select: none;
+}
+
+.xterm.focus,
+.xterm:focus {
+    outline: none;
+}
+
+.xterm .xterm-helpers {
+    position: absolute;
+    top: 0;
+    /**
+     * The z-index of the helpers must be higher than the canvases in order for
+     * IMEs to appear on top.
+     */
+    z-index: 5;
+}
+
+.xterm .xterm-helper-textarea {
+    padding: 0;
+    border: 0;
+    margin: 0;
+    /* Move textarea out of the screen to the far left, so that the cursor is not visible */
+    position: absolute;
+    opacity: 0;
+    left: -9999em;
+    top: 0;
+    width: 0;
+    height: 0;
+    z-index: -5;
+    /** Prevent wrapping so the IME appears against the textarea at the correct position */
+    white-space: nowrap;
+    overflow: hidden;
+    resize: none;
+}
+
+.xterm .composition-view {
+    /* TODO: Composition position got messed up somewhere */
+    background: #000;
+    color: #FFF;
+    display: none;
+    position: absolute;
+    white-space: nowrap;
+    z-index: 1;
+}
+
+.xterm .composition-view.active {
+    display: block;
+}
+
+.xterm .xterm-viewport {
+    /* On OS X this is required in order for the scroll bar to appear fully opaque */
+    background-color: #000;
+    overflow-y: scroll;
+    cursor: default;
+    position: absolute;
+    right: 0;
+    left: 0;
+    top: 0;
+    bottom: 0;
+}
+
+.xterm .xterm-screen {
+    position: relative;
+}
+
+.xterm .xterm-screen canvas {
+    position: absolute;
+    left: 0;
+    top: 0;
+}
+
+.xterm .xterm-scroll-area {
+    visibility: hidden;
+}
+
+.xterm-char-measure-element {
+    display: inline-block;
+    visibility: hidden;
+    position: absolute;
+    top: 0;
+    left: -9999em;
+    line-height: normal;
+}
+
+.xterm.enable-mouse-events {
+    /* When mouse events are enabled (eg. tmux), revert to the standard pointer cursor */
+    cursor: default;
+}
+
+.xterm.xterm-cursor-pointer,
+.xterm .xterm-cursor-pointer {
+    cursor: pointer;
+}
+
+.xterm.column-select.focus {
+    /* Column selection mode */
+    cursor: crosshair;
+}
+
+.xterm .xterm-accessibility,
+.xterm .xterm-message {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    z-index: 10;
+    color: transparent;
+}
+
+.xterm .live-region {
+    position: absolute;
+    left: -9999px;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+}
+
+.xterm-dim {
+    opacity: 0.5;
+}
+
+.xterm-underline-1 { text-decoration: underline; }
+.xterm-underline-2 { text-decoration: double underline; }
+.xterm-underline-3 { text-decoration: wavy underline; }
+.xterm-underline-4 { text-decoration: dotted underline; }
+.xterm-underline-5 { text-decoration: dashed underline; }
+
+.xterm-strikethrough {
+    text-decoration: line-through;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration {
+	z-index: 6;
+	position: absolute;
+}
+
+.xterm-decoration-overview-ruler {
+    z-index: 7;
+    position: absolute;
+    top: 0;
+    right: 0;
+    pointer-events: none;
+}
+
+.xterm-decoration-top {
+    z-index: 2;
+    position: relative;
+}

webshare/templates/app_index.html

@@ -0,0 +1,148 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="{{ config.static.url }}css/xterm.css" />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto%20Mono"/>
+    <script src="{{ config.static.url }}js/textual.js"></script>
+    <style>
+      body {
+        background: #000000;
+      }
+
+      .dialog-container {
+        font-family: "Roboto Mono", menlo, monospace;
+        position: absolute;
+        width: 100vw;
+        height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 10;
+      }
+      .shade {
+        font-family: "Roboto Mono", menlo, monospace;
+        position: absolute;
+        width: 100%;
+        height: 100%;
+      }
+      .intro {
+        font-family: "Roboto Mono", menlo, monospace;
+        width: 640px;
+        height: 240px;
+        z-index: 20;
+        color: rgba(255, 255, 255, 0.95);
+        background-color: #000000;
+        display: flex;
+        align-items: center;
+        text-align: center;
+        justify-content: center;
+      }
+
+      body.-first-byte .intro-dialog,
+      body.-first-byte .intro-dialog .shade {
+        font-family: "Roboto Mono", menlo, monospace;
+        opacity: 0;
+        transition: opacity 0.3s ease-out;
+        display: none;
+      }
+
+      body .textual-terminal {
+        font-family: "Roboto Mono", menlo, monospace;
+        opacity: 0;
+        transition: opacity 0.3s ease-out;
+      }
+
+      body.-first-byte .textual-terminal {
+        font-family: "Roboto Mono", menlo, monospace;
+        opacity: 1;
+        transition: opacity 0.3s ease-out;
+      }
+
+      body Button {
+        font-family: "Roboto Mono", menlo, monospace;
+        background-color: #000000;
+        color: rgba(255, 255, 255, 0.95);
+        display: block;
+      }
+
+      .closed-dialog {
+        font-family: "Roboto Mono", menlo, monospace;
+        opacity: 0;
+        display: none;
+      }
+
+      body.-closed .closed-dialog {
+        font-family: "Roboto Mono", menlo, monospace;
+        opacity: 1;
+        display: flex;
+      }
+
+      #start {
+        font-family: "Roboto Mono", menlo, monospace;
+        display: none;
+      }
+
+      #start.-delay {
+        font-family: "Roboto Mono", menlo, monospace;
+        display: flex;
+      }
+
+      footer {
+        position: fixed;
+        bottom: 0;
+        width: 100%;
+        text-align: center;
+        color: rgba(255, 255, 255, 0.5);
+        font-size: 12px;
+        padding: 10px 0;
+        background-color: #000000;
+        z-index: 5;
+      }
+    </style>
+    <script>
+      function getStartUrl() {
+        const url = new URL(window.location.href);
+        const params = new URLSearchParams(url.search);
+        params.delete("delay");
+        return url.pathname + "?" + params.toString();
+      }
+      async function refresh() {
+        const ping_url = document.body.dataset.pingurl;
+        if (ping_url) {
+          await fetch(ping_url, {
+            method: "GET",
+            mode: "no-cors",
+          });
+        }
+        window.location.href = getStartUrl();
+      }
+    </script>
+  </head>
+  <body data-pingurl="{{ ping_url }}">
+    <div class="dialog-container intro-dialog">
+      <div class="shade"></div>
+      <div class="intro">
+        <div>正加载命令行应用实例...<br><br>
+        确保使用现代浏览器并启用 JavaScript<br>
+      终端模拟器基于 XTerm.js<br>应用程序框架: Textual <br>
+      &copy; Wang Zhiyu 2024-2025, 保留此实例的所有权</div>
+        <button type="button" onClick="refresh()" id="start">启动新实例</button>
+      </div>
+    </div>
+
+    <div class="dialog-container closed-dialog">
+      <div class="shade"></div>
+      <div class="intro">
+        <div class="message">实例程序已终止</div>
+        <button type="button" onClick="refresh()">重新打开实例</button>
+      </div>
+    </div>
+
+    <div
+      id="terminal"
+      class="textual-terminal"
+      data-session-websocket-url="{{ app_websocket_url }}"
+      data-font-size="{{ font_size }}"
+    ></div>
+  </body>
+</html>