Skip to content

serve

Serve the local ShadowSim builder page.

HTTPServer

Bases: ThreadingMixIn, HTTPServer

Serve each request on a daemon thread so one run does not block the page.

request_timeout is how long, in seconds, a client may take to send the request line, the headers, and an authenticated body. At most _MAX_HANDLERS connections are handled at once. A further connection is closed so the accept loop can keep serving the page.

Source code in shadowsim/cli/serve.py
class HTTPServer(ThreadingMixIn, _HTTPServer):
    """Serve each request on a daemon thread so one run does not block the page.

    ``request_timeout`` is how long, in seconds, a client may take to send the
    request line, the headers, and an authenticated body. At most
    ``_MAX_HANDLERS`` connections are handled at once. A further connection is
    closed so the accept loop can keep serving the page.
    """

    daemon_threads = True
    token: str | None = None
    output_root: Path | None = None
    tls: bool = False
    accept_query_token: bool = True
    request_timeout: float
    _handler_slots: threading.BoundedSemaphore

    def __init__(
        self,
        server_address: tuple[str, int],
        request_handler_class: type[BaseHTTPRequestHandler],
        bind_and_activate: bool = True,
        *,
        request_timeout: float = _REQUEST_TIMEOUT,
        max_handlers: int = _MAX_HANDLERS,
    ) -> None:
        """Bind the server.

        Args:
            server_address: Address and port to bind.
            request_handler_class: Handler for each accepted connection.
            bind_and_activate: Bind and listen during construction.
            request_timeout: Seconds allowed for the request line, the headers,
                and an authenticated body.
            max_handlers: How many connections may be handled at once. A further
                connection is closed.
        """
        super().__init__(server_address, request_handler_class, bind_and_activate)
        self.request_timeout = request_timeout
        self._handler_slots = threading.BoundedSemaphore(max_handlers)

    def process_request(self, request: Any, client_address: Any) -> None:
        """Handle one connection on a daemon thread.

        When every handler thread is busy, the connection is closed and the
        accept loop continues.

        Args:
            request: Accepted client socket.
            client_address: Address of the client.
        """
        if not self._handler_slots.acquire(blocking=False):
            self.shutdown_request(request)
            return
        try:
            super().process_request(request, client_address)
        except BaseException:
            self._handler_slots.release()
            raise

    def process_request_thread(self, request: Any, client_address: Any) -> None:
        """Handle one request, then free its handler slot.

        Args:
            request: Accepted client socket.
            client_address: Address of the client.
        """
        try:
            super().process_request_thread(request, client_address)
        finally:
            self._handler_slots.release()

__init__

__init__(
    server_address: tuple[str, int],
    request_handler_class: type[BaseHTTPRequestHandler],
    bind_and_activate: bool = True,
    *,
    request_timeout: float = _REQUEST_TIMEOUT,
    max_handlers: int = _MAX_HANDLERS,
) -> None

Bind the server.

Parameters:

  • server_address (tuple[str, int]) –

    Address and port to bind.

  • request_handler_class (type[BaseHTTPRequestHandler]) –

    Handler for each accepted connection.

  • bind_and_activate (bool, default: True ) –

    Bind and listen during construction.

  • request_timeout (float, default: _REQUEST_TIMEOUT ) –

    Seconds allowed for the request line, the headers, and an authenticated body.

  • max_handlers (int, default: _MAX_HANDLERS ) –

    How many connections may be handled at once. A further connection is closed.

Source code in shadowsim/cli/serve.py
def __init__(
    self,
    server_address: tuple[str, int],
    request_handler_class: type[BaseHTTPRequestHandler],
    bind_and_activate: bool = True,
    *,
    request_timeout: float = _REQUEST_TIMEOUT,
    max_handlers: int = _MAX_HANDLERS,
) -> None:
    """Bind the server.

    Args:
        server_address: Address and port to bind.
        request_handler_class: Handler for each accepted connection.
        bind_and_activate: Bind and listen during construction.
        request_timeout: Seconds allowed for the request line, the headers,
            and an authenticated body.
        max_handlers: How many connections may be handled at once. A further
            connection is closed.
    """
    super().__init__(server_address, request_handler_class, bind_and_activate)
    self.request_timeout = request_timeout
    self._handler_slots = threading.BoundedSemaphore(max_handlers)

process_request

process_request(request: Any, client_address: Any) -> None

Handle one connection on a daemon thread.

When every handler thread is busy, the connection is closed and the accept loop continues.

Parameters:

  • request (Any) –

    Accepted client socket.

  • client_address (Any) –

    Address of the client.

Source code in shadowsim/cli/serve.py
def process_request(self, request: Any, client_address: Any) -> None:
    """Handle one connection on a daemon thread.

    When every handler thread is busy, the connection is closed and the
    accept loop continues.

    Args:
        request: Accepted client socket.
        client_address: Address of the client.
    """
    if not self._handler_slots.acquire(blocking=False):
        self.shutdown_request(request)
        return
    try:
        super().process_request(request, client_address)
    except BaseException:
        self._handler_slots.release()
        raise

process_request_thread

process_request_thread(
    request: Any, client_address: Any
) -> None

Handle one request, then free its handler slot.

Parameters:

  • request (Any) –

    Accepted client socket.

  • client_address (Any) –

    Address of the client.

Source code in shadowsim/cli/serve.py
def process_request_thread(self, request: Any, client_address: Any) -> None:
    """Handle one request, then free its handler slot.

    Args:
        request: Accepted client socket.
        client_address: Address of the client.
    """
    try:
        super().process_request_thread(request, client_address)
    finally:
        self._handler_slots.release()

add_serve_parser

add_serve_parser(subparsers: _SubParsersAction) -> None

Register the serve subcommand on subparsers.

Source code in shadowsim/cli/serve.py
def add_serve_parser(subparsers: argparse._SubParsersAction) -> None:
    """Register the ``serve`` subcommand on ``subparsers``."""
    serve_parser = subparsers.add_parser("serve", help="Open the local builder page.")
    serve_parser.add_argument(
        "--host",
        default="127.0.0.1",
        help="Address to bind (default: 127.0.0.1). A non-loopback address requires --allow-remote and TLS.",
    )
    serve_parser.add_argument("--port", type=int, default=8000, help="Port to bind (default: 8000).")
    serve_parser.add_argument(
        "--allow-remote",
        action="store_true",
        help="Bind a non-loopback address over TLS. Anyone with the startup token can submit a run.",
    )
    serve_parser.add_argument(
        "--tls-cert",
        help="PEM certificate file for HTTPS. Required, with --tls-key, for a non-loopback address.",
    )
    serve_parser.add_argument(
        "--tls-key",
        help="PEM private key file for HTTPS. Required, with --tls-cert, for a non-loopback address.",
    )
    serve_parser.add_argument(
        "--output-dir",
        default="results",
        help="Directory save and export paths must stay under (default: results).",
    )
    serve_parser.add_argument("--no-browser", action="store_true", help="Do not open a browser window.")
    serve_parser.set_defaults(handler=run_serve)

run_serve

run_serve(args: Namespace) -> int

Run serve from a parsed serve subcommand namespace.

Source code in shadowsim/cli/serve.py
def run_serve(args: argparse.Namespace) -> int:
    """Run ``serve`` from a parsed ``serve`` subcommand namespace."""
    return serve(
        args.host,
        args.port,
        open_browser=not args.no_browser,
        allow_remote=args.allow_remote,
        output_dir=args.output_dir,
        tls_cert=args.tls_cert,
        tls_key=args.tls_key,
    )

serve

serve(
    host: str,
    port: int,
    *,
    open_browser: bool,
    allow_remote: bool = False,
    output_dir: str | Path = "results",
    tls_cert: str | Path | None = None,
    tls_key: str | Path | None = None,
) -> int

Bind a server and serve the builder page until interrupted.

A loopback bind speaks HTTP and prints a one-time ?token= URL. A non-loopback bind requires allow_remote and both TLS files, speaks HTTPS, and prints the startup token on its own line instead of in the URL. Passing both TLS files on a loopback bind serves HTTPS there too.

Parameters:

  • host (str) –

    Address to bind.

  • port (int) –

    TCP port to bind.

  • open_browser (bool) –

    Open the page in the default browser after the server starts.

  • allow_remote (bool, default: False ) –

    Permit a non-loopback host. Without this, such an address is refused. Anyone who has the startup token can submit a run.

  • output_dir (str | Path, default: 'results' ) –

    Directory save and export paths must stay under. A relative path is resolved from the working directory when the server starts.

  • tls_cert (str | Path | None, default: None ) –

    PEM certificate file used when the server speaks HTTPS. Required with tls_key for a non-loopback host.

  • tls_key (str | Path | None, default: None ) –

    PEM private key file paired with tls_cert.

Returns:

  • int –

    Process exit code. 0 after a clean interrupt, 1 if the port is invalid,

  • int –

    the address is not loopback and allow_remote is false, a non-loopback

  • int –

    address has no TLS files, only one TLS file is set, the certificate cannot

  • int –

    be loaded, or the address cannot be bound.

Source code in shadowsim/cli/serve.py
def serve(
    host: str,
    port: int,
    *,
    open_browser: bool,
    allow_remote: bool = False,
    output_dir: str | Path = "results",
    tls_cert: str | Path | None = None,
    tls_key: str | Path | None = None,
) -> int:
    """Bind a server and serve the builder page until interrupted.

    A loopback bind speaks HTTP and prints a one-time ``?token=`` URL. A
    non-loopback bind requires ``allow_remote`` and both TLS files, speaks HTTPS,
    and prints the startup token on its own line instead of in the URL. Passing
    both TLS files on a loopback bind serves HTTPS there too.

    Args:
        host: Address to bind.
        port: TCP port to bind.
        open_browser: Open the page in the default browser after the server starts.
        allow_remote: Permit a non-loopback ``host``. Without this, such an address
            is refused. Anyone who has the startup token can submit a run.
        output_dir: Directory save and export paths must stay under. A relative
            path is resolved from the working directory when the server starts.
        tls_cert: PEM certificate file used when the server speaks HTTPS. Required
            with ``tls_key`` for a non-loopback ``host``.
        tls_key: PEM private key file paired with ``tls_cert``.

    Returns:
        Process exit code. ``0`` after a clean interrupt, ``1`` if the port is invalid,
        the address is not loopback and ``allow_remote`` is false, a non-loopback
        address has no TLS files, only one TLS file is set, the certificate cannot
        be loaded, or the address cannot be bound.
    """
    if port < 0 or port > 65535:
        print(f"error: port must be between 0 and 65535, got {port}", file=sys.stderr)
        return 1
    if not allow_remote and not _is_loopback_host(host):
        print(
            f"error: refusing to bind {host}: anyone with the startup token can submit a run. "
            "Pass --allow-remote to listen on a non-loopback address.",
            file=sys.stderr,
        )
        return 1
    if (tls_cert is None) != (tls_key is None):
        print("error: --tls-cert and --tls-key must be passed together.", file=sys.stderr)
        return 1
    if not _is_loopback_host(host) and tls_cert is None:
        print(
            f"error: refusing to bind {host}: a remote builder needs TLS so the startup token "
            "is not sent in cleartext. Pass --tls-cert and --tls-key.",
            file=sys.stderr,
        )
        return 1
    try:
        server = HTTPServer((host, port), _Handler)
    except OSError as exc:
        print(f"error: could not bind {host}:{port}: {exc}", file=sys.stderr)
        return 1

    server.tls = False
    if tls_cert is not None and tls_key is not None:
        try:
            _install_tls(server, _server_tls(Path(tls_cert).expanduser(), Path(tls_key).expanduser()))
        except (OSError, ssl.SSLError) as exc:
            server.server_close()
            print(f"error: could not load TLS certificate: {exc}", file=sys.stderr)
            return 1
        server.tls = True
    token = secrets.token_urlsafe(32)
    output_root = Path(output_dir).expanduser().resolve()
    server.token = token
    server.output_root = output_root
    server.accept_query_token = _is_loopback_host(host)
    raw_host, bound_port = server.server_address[:2]
    bound_host = raw_host.decode() if isinstance(raw_host, bytes) else raw_host
    display_host = f"[{bound_host}]" if ":" in bound_host else bound_host
    scheme = "https" if server.tls else "http"
    query = f"?token={token}" if server.accept_query_token else ""
    url = f"{scheme}://{display_host}:{bound_port}/{query}"
    if not _is_loopback_host(host):
        print(
            f"warning: {host} is not a loopback address. Anyone with the startup token can submit a run.",
            file=sys.stderr,
            flush=True,
        )
    print(f"Serving ShadowSim at {url}", flush=True)
    if not server.accept_query_token:
        print(f"Startup token: {token}", flush=True)
    print(f"Saving under {output_root}", flush=True)
    if open_browser:
        webbrowser.open(url)
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nStopped.")
    finally:
        _cancel_run()
        _retain.clear()
        server.server_close()
    return 0