webdev 2.0.0__py3-none-any.whl

webdev/run.py

@@ -0,0 +1,124 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+High-level runner: select a port, build the app, print the banner and start
+Uvicorn (optionally over HTTPS).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import uvicorn
+
+from .config import Settings
+from .net import NoFreePortError, build_urls, find_free_port, render_qr
+from .server import create_app
+from .tls import ensure_tls_files
+
+log = logging.getLogger('webdev')
+
+
+def _print_banner(settings: Settings, port: int) -> None:
+    """
+    Print the startup banner with the served path and access URLs.
+
+    Builds the list of reachable URLs, prints the bound address and each URL,
+    optionally renders a QR code for the last URL, and reminds the user how to
+    stop the server.
+
+    :param settings: Normalized runtime settings describing the server.
+    :param port: The resolved TCP port the server is bound to.
+    """
+    urls = build_urls(settings.ip, port, settings.https)
+    print('WebDev {} serving {}'.format(_version(), settings.path))
+    print(f'Bound to {settings.ip}:{port}')
+    for url in urls:
+        print(f'  -> {url}')
+    if settings.qr and urls:
+        qr = render_qr(urls[-1])
+        if qr:
+            print(qr)
+    print('Press Ctrl+C to stop.')
+
+
+def _version() -> str:
+    """
+    Return the installed WebDev package version string.
+
+    :return: The value of :data:`webdev.__version__`.
+    """
+    from . import __version__
+
+    return __version__
+
+
+def serve(settings: Settings) -> int:
+    """
+    Resolve a port, build the app and run the server.
+
+    Normalizes the given settings, selects a free port, optionally prepares
+    TLS certificate files for HTTPS, builds the ASGI application, prints the
+    startup banner and runs Uvicorn until interrupted.
+
+    :param settings: The runtime settings controlling how the server runs.
+    :return: A process exit code: ``0`` on success, ``1`` on startup failure.
+    """
+    settings = settings.normalized()
+
+    try:
+        port = find_free_port(settings.ip, settings.port, settings.range)
+    except NoFreePortError as error:
+        log.error(str(error))
+        return 1
+
+    cert_file: str | None = None
+    key_file: str | None = None
+    if settings.https:
+        from .tls import TLSUnavailableError
+
+        try:
+            cert_file, key_file = ensure_tls_files(settings.cert, settings.key)
+        except TLSUnavailableError as error:
+            log.error(str(error))
+            return 1
+
+    app = create_app(settings)
+
+    _print_banner(settings, port)
+
+    log_level = (
+        'debug'
+        if settings.verbose >= 3
+        else ('info' if settings.verbose >= 2 else 'warning')
+    )
+
+    config = uvicorn.Config(
+        app,
+        host=settings.ip,
+        port=port,
+        log_level=log_level,
+        access_log=settings.verbose >= 2,
+        ssl_certfile=cert_file,
+        ssl_keyfile=key_file,
+    )
+    server = uvicorn.Server(config)
+    try:
+        server.run()
+    except KeyboardInterrupt:  # pragma: no cover - handled by uvicorn too
+        print('Good bye!')
+    return 0

webdev/server.py

@@ -0,0 +1,336 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Starlette application factory and Uvicorn runner.
+
+Builds the ASGI application that serves static files and directory listings,
+optionally with live reload, gzip, CORS, SPA fallback, and no-cache headers,
+based on a resolved :class:`~webdev.config.Settings` instance.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.middleware.gzip import GZipMiddleware
+from starlette.requests import Request
+from starlette.responses import (
+    FileResponse,
+    HTMLResponse,
+    RedirectResponse,
+    Response,
+)
+from starlette.routing import Route, WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from .config import Settings
+from .index import render_index, validate_theme
+from .livereload import (
+    CLIENT_SNIPLET,
+    LIVERELOAD_PATH,
+    ReloadHub,
+    watch_tree,
+)
+from .static import (
+    NO_CACHE_HEADERS,
+    find_index_file,
+    guess_media_type,
+    resolve_fs_path,
+)
+
+log = logging.getLogger('webdev')
+
+_HTML_SUFFIXES = ('.html', '.htm')
+
+
+def _inject_livereload(html: bytes, enabled: bool) -> bytes:
+    """
+    Inject the reload snippet before ``</body>`` (or append) when enabled.
+
+    When *enabled* is false the HTML is returned unchanged. Otherwise the
+    client snippet is inserted just before the last ``</body>`` tag, or appended
+    if no such tag exists.
+
+    :param html: The HTML document bytes to augment.
+    :param enabled: Whether live reload injection is active.
+    :return: The HTML bytes, with the snippet injected when *enabled*.
+    """
+    if not enabled:
+        return html
+    snippet = CLIENT_SNIPLET.encode('utf-8')
+    lowered = html.lower()
+    idx = lowered.rfind(b'</body>')
+    if idx != -1:
+        return html[:idx] + snippet + html[idx:]
+    return html + snippet
+
+
+def _cache_headers(settings: Settings) -> dict[str, str]:
+    """
+    Return response headers that control client caching.
+
+    :param settings: The resolved runtime settings.
+    :return: No-cache headers when caching is disabled, else an empty mapping.
+    """
+    return dict(NO_CACHE_HEADERS) if settings.no_cache else {}
+
+
+def _not_found(settings: Settings) -> Response:
+    """
+    Build a plain-text ``404 Not Found`` response.
+
+    :param settings: The resolved runtime settings.
+    :return: A :class:`Response` with status code 404.
+    """
+    return Response('404 Not Found', status_code=404, media_type='text/plain')
+
+
+def _html_response(
+    body: bytes, settings: Settings, status_code: int = 200
+) -> HTMLResponse:
+    """
+    Build an HTML response with live-reload injection and cache headers.
+
+    :param body: The raw HTML document bytes.
+    :param settings: The resolved runtime settings.
+    :param status_code: HTTP status code for the response.
+    :return: An :class:`HTMLResponse` ready to be returned to the client.
+    """
+    body = _inject_livereload(body, settings.reload)
+    return HTMLResponse(body, status_code=status_code, headers=_cache_headers(settings))
+
+
+async def _serve_file(path: Path, settings: Settings) -> Response:
+    """
+    Serve a regular file, injecting live-reload JS into HTML documents.
+
+    HTML files are read into memory so the reload snippet can be injected;
+    other files are streamed via :class:`FileResponse`.
+
+    :param path: Filesystem path of the file to serve.
+    :param settings: The resolved runtime settings.
+    :return: An HTML, file, or 404 response depending on the file and I/O.
+    """
+    if path.suffix.lower() in _HTML_SUFFIXES:
+        try:
+            body = path.read_bytes()
+        except OSError:
+            return _not_found(settings)
+        return _html_response(body, settings)
+    return FileResponse(
+        path,
+        media_type=guess_media_type(path),
+        headers=_cache_headers(settings),
+    )
+
+
+async def _serve_directory(
+    request: Request, fs_dir: Path, settings: Settings
+) -> Response:
+    """
+    Serve a directory as an index page or its index file.
+
+    Redirects to a trailing-slash URL when needed, serves a directory index
+    file if present, and otherwise renders a themed directory listing.
+
+    :param request: The incoming HTTP request.
+    :param fs_dir: Filesystem path of the directory to serve.
+    :param settings: The resolved runtime settings.
+    :return: A redirect, file, or rendered index HTML response.
+    """
+    url_path = request.url.path
+    # Ensure a trailing slash so relative links resolve correctly.
+    if not url_path.endswith('/'):
+        return RedirectResponse(url_path + '/', status_code=308)
+
+    index_file = find_index_file(fs_dir)
+    if index_file is not None:
+        return await _serve_file(index_file, settings)
+
+    html = render_index(
+        fs_dir=fs_dir,
+        url_path=url_path,
+        served_root=Path(settings.path),
+        theme=settings.theme,
+        live_reload=settings.reload,
+    )
+    return _html_response(html.encode('utf-8'), settings)
+
+
+async def _handle(request: Request) -> Response:
+    """
+    Main request handler resolving a URL path to a file or directory.
+
+    Rejects paths that escape the served root, applies the optional SPA
+    fallback for unknown routes, and dispatches to the file or directory
+    handler as appropriate.
+
+    :param request: The incoming HTTP request.
+    :return: The response for the resolved resource, or a 404 response.
+    """
+    settings: Settings = request.app.state.settings
+    root = Path(settings.path)
+    resolved = resolve_fs_path(root, request.url.path)
+
+    if resolved.escapes:
+        return _not_found(settings)
+
+    if resolved.fs_path is None:
+        # SPA fallback: serve the root index.html for unknown routes.
+        if settings.spa:
+            index_file = find_index_file(root)
+            if index_file is not None:
+                return await _serve_file(index_file, settings)
+        return _not_found(settings)
+
+    if resolved.is_dir:
+        return await _serve_directory(request, resolved.fs_path, settings)
+
+    return await _serve_file(resolved.fs_path, settings)
+
+
+async def _drain(websocket: WebSocket) -> None:
+    """
+    Consume inbound frames so client disconnects are detected.
+
+    Runs until the client disconnects, suppressing the resulting
+    :class:`WebSocketDisconnect`.
+
+    :param websocket: The WebSocket connection to drain.
+    """
+    with contextlib.suppress(WebSocketDisconnect):
+        while True:
+            await websocket.receive_text()
+
+
+async def _livereload_endpoint(websocket: WebSocket) -> None:
+    """
+    WebSocket endpoint that pushes live-reload messages to the browser.
+
+    Registers with the reload hub, forwards each reload message to the client,
+    and stops when the client disconnects, cleaning up its registration.
+
+    :param websocket: The incoming WebSocket connection.
+    """
+    hub: ReloadHub = websocket.app.state.hub
+    await websocket.accept()
+    queue = hub.register()
+    receiver = asyncio.create_task(_drain(websocket))
+    try:
+        while True:
+            getter = asyncio.create_task(queue.get())
+            done, _pending = await asyncio.wait(
+                {getter, receiver}, return_when=asyncio.FIRST_COMPLETED
+            )
+            if receiver in done:
+                getter.cancel()
+                break
+            message = getter.result()
+            await websocket.send_text(message)
+    except WebSocketDisconnect:
+        pass
+    finally:
+        receiver.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await receiver
+        hub.unregister(queue)
+
+
+def _build_lifespan(settings: Settings):
+    """
+    Create an ASGI lifespan context manager bound to *settings*.
+
+    The returned lifespan stores settings and a reload hub on the application
+    state and, when live reload is enabled, runs a filesystem watcher for the
+    lifetime of the application.
+
+    :param settings: The resolved runtime settings.
+    :return: An async lifespan context manager for :class:`Starlette`.
+    """
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette):
+        """
+        Manage startup and shutdown of application-wide resources.
+
+        :param app: The Starlette application being started.
+        """
+        app.state.settings = settings
+        app.state.hub = ReloadHub()
+        stop_event = asyncio.Event()
+        watcher: asyncio.Task | None = None
+        if settings.reload:
+            watcher = asyncio.create_task(
+                watch_tree(Path(settings.path), app.state.hub, stop_event)
+            )
+        try:
+            yield
+        finally:
+            stop_event.set()
+            if watcher is not None:
+                watcher.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await watcher
+
+    return lifespan
+
+
+def create_app(settings: Settings) -> Starlette:
+    """
+    Build the Starlette application for the given *settings*.
+
+    Validates the theme, wires up routes (including the live-reload WebSocket
+    when enabled) and optional CORS and gzip middleware, and attaches the
+    settings to the application state.
+
+    :param settings: The resolved runtime settings.
+    :return: A configured :class:`Starlette` application instance.
+    :raises ThemeNotFoundError: If the configured theme does not exist.
+    """
+    validate_theme(settings.theme)
+
+    routes: list = []
+    if settings.reload:
+        routes.append(WebSocketRoute(LIVERELOAD_PATH, _livereload_endpoint))
+    routes.append(Route('/{path:path}', _handle, methods=['GET', 'HEAD']))
+
+    middleware: list[Middleware] = []
+    if settings.cors:
+        middleware.append(
+            Middleware(
+                CORSMiddleware,
+                allow_origins=['*'],
+                allow_methods=['*'],
+                allow_headers=['*'],
+            )
+        )
+    if settings.gzip:
+        middleware.append(Middleware(GZipMiddleware, minimum_size=500))
+
+    app = Starlette(
+        routes=routes,
+        middleware=middleware,
+        lifespan=_build_lifespan(settings),
+    )
+    app.state.settings = settings
+    return app

webdev/static.py

@@ -0,0 +1,195 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Per-request static file resolution.
+
+The core fix over the legacy server: paths are resolved against the **live
+filesystem on every request** instead of relying on the process working
+directory. A missing served directory therefore yields a real ``404`` and
+recovers automatically the instant the directory reappears.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+
+#: Candidate index file names auto-served for a directory.
+INDEX_FILENAMES = ('index.html', 'index.htm')
+
+#: Extra extension -> MIME mappings the stdlib ``mimetypes`` module omits.
+#: Registered so common dev/config/source files render inline instead of being
+#: downloaded as ``application/octet-stream``.
+EXTRA_MIME_TYPES = {
+    '.toml': 'text/plain',
+    '.ini': 'text/plain',
+    '.cfg': 'text/plain',
+    '.conf': 'text/plain',
+    '.lock': 'text/plain',
+    '.log': 'text/plain',
+    '.env': 'text/plain',
+    '.properties': 'text/plain',
+    '.rst': 'text/plain',
+    '.tsx': 'text/plain',
+    '.jsx': 'text/plain',
+    '.vue': 'text/plain',
+    '.svelte': 'text/plain',
+    '.yml': 'text/plain',
+    '.yaml': 'text/plain',
+}
+
+#: Number of bytes inspected when sniffing whether an unknown file is text.
+_SNIFF_BYTES = 8192
+
+
+def register_mime_types() -> None:
+    """
+    Register :data:`EXTRA_MIME_TYPES` with the stdlib ``mimetypes`` module.
+
+    Adds each extension-to-media-type mapping so later lookups via
+    ``mimetypes.guess_type`` recognize these developer-oriented file types.
+    """
+    for ext, media_type in EXTRA_MIME_TYPES.items():
+        mimetypes.add_type(media_type, ext)
+
+
+register_mime_types()
+
+
+def _looks_like_text(path: Path) -> bool:
+    """
+    Heuristically decide whether *path* holds UTF-8 text (no NUL bytes).
+
+    Reads a leading chunk of the file and treats it as text when it contains no
+    NUL byte and decodes as UTF-8, tolerating a multi-byte sequence truncated at
+    the chunk boundary. Unreadable files are reported as non-text.
+
+    :param path: The file to inspect.
+    :return: ``True`` if the file appears to be UTF-8 text, else ``False``.
+    """
+    try:
+        with path.open('rb') as fd:
+            chunk = fd.read(_SNIFF_BYTES)
+    except OSError:
+        return False
+    if b'\x00' in chunk:
+        return False
+    try:
+        chunk.decode('utf-8')
+    except UnicodeDecodeError:
+        # A truncated multi-byte sequence at the boundary is still fine.
+        try:
+            chunk[: chunk.rfind(b' ') + 1 or len(chunk)].decode('utf-8')
+        except UnicodeDecodeError:
+            return False
+    return True
+
+
+def guess_media_type(path: Path) -> str:
+    """
+    Resolve a response ``Content-Type`` for *path*.
+
+    Uses the stdlib ``mimetypes`` registry (augmented by
+    :func:`register_mime_types`). For still-unknown extensions, sniffs the file
+    and falls back to ``text/plain`` when it looks like text, otherwise
+    ``application/octet-stream`` — so arbitrary text files preview inline while
+    binaries still download.
+
+    :param path: The file whose media type should be determined.
+    :return: The resolved MIME type string.
+    """
+    media_type, _encoding = mimetypes.guess_type(path.name)
+    if media_type:
+        return media_type
+    if _looks_like_text(path):
+        return 'text/plain'
+    return 'application/octet-stream'
+
+
+#: Headers that disable caching for fresh dev content.
+NO_CACHE_HEADERS = {
+    'Cache-Control': 'no-store, no-cache, must-revalidate, max-age=0',
+    'Pragma': 'no-cache',
+    'Expires': '0',
+}
+
+
+class ResolvedPath:
+    """
+    Result of resolving a URL path against the served root.
+    """
+
+    __slots__ = ('fs_path', 'is_dir', 'escapes')
+
+    def __init__(self, fs_path: Path | None, is_dir: bool, escapes: bool) -> None:
+        """
+        Initialize the resolution result.
+
+        :param fs_path: The resolved filesystem path, or ``None`` if it does
+            not exist.
+        :param is_dir: Whether the resolved path is a directory.
+        :param escapes: Whether the request attempted to traverse outside the
+            served root.
+        """
+        self.fs_path = fs_path
+        self.is_dir = is_dir
+        self.escapes = escapes
+
+
+def resolve_fs_path(root: Path, url_path: str) -> ResolvedPath:
+    """
+    Resolve *url_path* (the request path) to a filesystem path under *root*.
+
+    Returns a :class:`ResolvedPath`. ``escapes`` is ``True`` when the request
+    attempted to traverse outside *root* (the caller should reject with 404).
+    ``fs_path`` is ``None`` when the target does not exist.
+
+    :param root: The served root directory.
+    :param url_path: The decoded request URL path to resolve.
+    :return: The resolution result describing the target path.
+    """
+    # Normalise: strip leading slash, decode nothing here (Starlette already
+    # provides a decoded path), collapse via Path semantics.
+    relative = url_path.lstrip('/')
+    root_resolved = root.resolve(strict=False)
+    candidate = (root_resolved / relative).resolve(strict=False)
+
+    # Traversal safety: the resolved candidate must live under the root.
+    if candidate != root_resolved and root_resolved not in candidate.parents:
+        return ResolvedPath(None, False, escapes=True)
+
+    if not candidate.exists():
+        return ResolvedPath(None, False, escapes=False)
+
+    return ResolvedPath(candidate, candidate.is_dir(), escapes=False)
+
+
+def find_index_file(directory: Path) -> Path | None:
+    """
+    Return the first existing index file inside *directory*, if any.
+
+    Checks the candidate names in :data:`INDEX_FILENAMES` in order and returns
+    the first one that exists as a regular file.
+
+    :param directory: The directory to search for an index file.
+    :return: The path to the first index file found, or ``None`` if none exist.
+    """
+    for name in INDEX_FILENAMES:
+        candidate = directory / name
+        if candidate.is_file():
+            return candidate
+    return None

webdev/templates/dark/base.html.jinja2

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="{{ theme }}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{% block title %}Index of {{ url_path }}{% endblock %}</title>
+  <style>
+{% include theme ~ "/partials/styles.css.jinja2" %}
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    {% block content %}{% endblock %}
+  </div>
+  {% block scripts %}{% endblock %}
+</body>
+</html>