localghost 4.2.1__tar.gz → 4.3.0__tar.gz

{localghost-4.2.1 → localghost-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localghost
-Version: 4.2.1
+Version: 4.3.0
 Summary: Localghost serves local applications at friendly .localhost URLs
 Keywords: localghost,localhost,docker,compose,traefik,development,proxy
 Author: SmileyChris
@@ -73,9 +73,10 @@ port 80 available. From an application directory, run:
 uvx localghost run
 ```
 
-Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, and Docker
-Compose projects, starts the shared hub when needed, and keeps the local URL
-visible while the application runs. Press Ctrl+C to stop the application.
+Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, static
+HTML, and Docker Compose projects, starts the shared hub when needed, and
+keeps the local URL visible while the application runs. Press Ctrl+C to stop
+the application.
 
 An unconfigured Compose project asks you to save its routing setup first:
 

{localghost-4.2.1 → localghost-4.3.0}/README.md

@@ -44,9 +44,10 @@ port 80 available. From an application directory, run:
 uvx localghost run
 ```
 
-Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, and Docker
-Compose projects, starts the shared hub when needed, and keeps the local URL
-visible while the application runs. Press Ctrl+C to stop the application.
+Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, static
+HTML, and Docker Compose projects, starts the shared hub when needed, and
+keeps the local URL visible while the application runs. Press Ctrl+C to stop
+the application.
 
 An unconfigured Compose project asks you to save its routing setup first:
 

{localghost-4.2.1 → localghost-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "localghost"
-version = "4.2.1"
+version = "4.3.0"
 description = "Localghost serves local applications at friendly .localhost URLs"
 readme = "README.md"
 requires-python = ">=3.11"

{localghost-4.2.1 → localghost-4.3.0}/src/localghost/cli.py

@@ -1424,7 +1424,7 @@ def _forget_tailscale_credential() -> None:
     if delete_tailscale_credential():
         info("The OAuth credential was removed from the system keyring.")
         info(
-            "The OAuth client itself still exists; revoke it on the Trust "
+            "The OAuth credential still exists in Tailscale; revoke it on the Trust "
             f"credentials page ({OAUTH_CONSOLE_URL}) if no other machine uses it."
         )
     else:

localghost-4.3.0/src/localghost/html_server.js

@@ -0,0 +1,29 @@
+// Served by html_server.py as /__localghost/reload.js. Each event lists the
+// changed files' URL paths, one per line. Changes this page never loaded are
+// ignored; changed stylesheets it links are swapped in place, keeping scroll,
+// form and script state; anything else reloads the page.
+performance.setResourceTimingBufferSize(1000);
+new EventSource("/__localghost/reload").onmessage = (event) => {
+  const page = location.pathname;
+  const used = new Set(
+    page.endsWith("/") ? [page + "index.html", page + "index.htm"] : [page],
+  );
+  for (const entry of performance.getEntriesByType("resource")) {
+    const url = new URL(entry.name);
+    if (url.origin === location.origin) used.add(url.pathname);
+  }
+  const changed = event.data.split("\n").filter((path) => used.has(path));
+  if (!changed.length) return;
+  const links = [...document.querySelectorAll("link[rel=stylesheet]")].filter(
+    (link) => changed.includes(new URL(link.href).pathname),
+  );
+  const linked = new Set(links.map((link) => new URL(link.href).pathname));
+  if (!changed.every((path) => linked.has(path))) return location.reload();
+  for (const old of links) {
+    // The new sheet loads before the old one goes, so nothing flashes unstyled.
+    const link = old.cloneNode();
+    link.href = new URL(old.href).pathname + "?" + Date.now();
+    link.onload = () => old.remove();
+    old.after(link);
+  }
+};

localghost-4.3.0/src/localghost/html_server.py

@@ -0,0 +1,207 @@
+"""Serve the current directory, updating open pages when a file changes.
+
+Run as `python -I -m localghost.html_server PORT BIND`. HTML pages get a
+script (`/__localghost/reload.js`, from html_server.js) that holds an event
+stream open; while one is open the server checks file modification times and
+sends the paths of any that change, and the page swaps changed stylesheets or
+reloads. With no page open, nothing is checked. Dotfiles and dot-directories
+are never served.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import sys
+import threading
+import time
+import urllib.parse
+from functools import partial
+from http import HTTPStatus
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+RELOAD_PATH = "/__localghost/reload"
+# Served from a path rather than inline, so a `script-src 'self'` policy
+# still lets it run.
+RELOAD_SCRIPT_PATH = "/__localghost/reload.js"
+RELOAD_SCRIPT = Path(__file__).with_name("html_server.js").read_bytes()
+SCRIPT = f'<script src="{RELOAD_SCRIPT_PATH}"></script>'.encode()
+_BODY_END = re.compile(rb"</body\s*>", re.IGNORECASE)
+_INTERVAL = 0.5
+# A comment line this often notices a closed tab, so its check stops.
+_HEARTBEAT = 15.0
+_SKIPPED_DIRECTORY = "node_modules"
+# The stdlib server's own index names; its `index_pages` is 3.12+.
+_INDEX_PAGES = ("index.html", "index.htm")
+# Every open page shares one scan per interval rather than walking alone.
+_scan_lock = threading.Lock()
+_last_scan: tuple[Path, float, dict[str, int]] | None = None
+
+
+def snapshot(root: Path) -> dict[str, int]:
+    """Modification times of every file under root.
+
+    Dot-directories and node_modules are skipped: neither is served content
+    anyone edits by hand, and node_modules can hold a hundred thousand files.
+    """
+    times = {}
+    for directory, subdirectories, files in os.walk(root):
+        subdirectories[:] = [
+            name
+            for name in subdirectories
+            if not name.startswith(".") and name != _SKIPPED_DIRECTORY
+        ]
+        for name in files:
+            path = os.path.join(directory, name)
+            # A file removed between the listing and the stat is just gone.
+            with contextlib.suppress(OSError):
+                times[path] = os.stat(path).st_mtime_ns
+    return times
+
+
+def shared_snapshot(root: Path) -> dict[str, int]:
+    """A snapshot at most one interval old, so open pages share the walk.
+
+    A reused snapshot can only predate a change, which errs toward one extra
+    reload rather than a missed one.
+    """
+    global _last_scan
+    with _scan_lock:
+        now = time.monotonic()
+        stale = _last_scan is None or now - _last_scan[1] >= _INTERVAL
+        if stale or _last_scan[0] != root:
+            _last_scan = (root, now, snapshot(root))
+        return _last_scan[2]
+
+
+def changed_paths(
+    root: Path, before: dict[str, int], after: dict[str, int]
+) -> list[str]:
+    """URL paths of every file added, removed or modified between snapshots."""
+    changed = {
+        path
+        for path in before.keys() | after.keys()
+        if before.get(path) != after.get(path)
+    }
+    return sorted(
+        urllib.parse.quote("/" + Path(path).relative_to(root).as_posix())
+        for path in changed
+    )
+
+
+def inject(page: bytes) -> bytes:
+    """Put the reload script before the last </body>, or at the end without one."""
+    matches = list(_BODY_END.finditer(page))
+    if not matches:
+        return page + SCRIPT
+    at = matches[-1].start()
+    return page[:at] + SCRIPT + page[at:]
+
+
+class Handler(SimpleHTTPRequestHandler):
+    def do_GET(self) -> None:
+        route = self.path.split("?", 1)[0]
+        if route == RELOAD_PATH:
+            self._stream_reloads()
+            return
+        if route == RELOAD_SCRIPT_PATH:
+            self._send(RELOAD_SCRIPT, "text/javascript")
+            return
+        self._serve()
+
+    def do_HEAD(self) -> None:
+        self._serve()
+
+    def _serve(self) -> None:
+        """GET and HEAD alike, so both report the injected page's length."""
+        if self._hidden():
+            self.send_error(HTTPStatus.NOT_FOUND, "File not found")
+            return
+        page = self._html_file()
+        if page is None:
+            if self.command == "HEAD":
+                super().do_HEAD()
+            else:
+                super().do_GET()
+            return
+        try:
+            body = inject(page.read_bytes())
+        except OSError:
+            self.send_error(HTTPStatus.NOT_FOUND, "File not found")
+            return
+        # No charset: the page's own <meta charset> or BOM decides, as it
+        # would from the stdlib server. The tag is ASCII, so it fits any.
+        self._send(body, self.guess_type(str(page)))
+
+    def _send(self, body: bytes, content_type: str) -> None:
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(body)
+
+    def _hidden(self) -> bool:
+        """Does the path name a dotfile or anything inside a dot-directory?"""
+        path = urllib.parse.unquote(self.path.split("?", 1)[0].split("#", 1)[0])
+        return any(part.startswith(".") for part in path.split("/"))
+
+    def _html_file(self) -> Path | None:
+        """The HTML file this request serves, leaving redirects and listings alone."""
+        path = Path(self.translate_path(self.path))
+        if path.is_dir():
+            if not self.path.split("?", 1)[0].endswith("/"):
+                return None
+            path = next(
+                (path / name for name in _INDEX_PAGES if (path / name).is_file()),
+                path / "index.html",
+            )
+        if path.suffix.lower() in (".html", ".htm") and path.is_file():
+            return path
+        return None
+
+    def _stream_reloads(self) -> None:
+        # Before the headers, so a save the page races to see is still a change.
+        root = Path(self.directory)
+        before = shared_snapshot(root)
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        quiet_since = time.monotonic()
+        # The stream stays open: a page that swaps a stylesheet rather than
+        # reloading would otherwise miss edits made while it reconnected.
+        try:
+            while True:
+                time.sleep(_INTERVAL)
+                after = shared_snapshot(root)
+                if after != before:
+                    paths = changed_paths(root, before, after)
+                    event = "".join(f"data: {path}\n" for path in paths) + "\n"
+                    before = after
+                elif time.monotonic() - quiet_since > _HEARTBEAT:
+                    event = ": still here\n\n"
+                else:
+                    continue
+                self.wfile.write(event.encode())
+                self.wfile.flush()
+                quiet_since = time.monotonic()
+        except OSError:  # The tab closed, or the connection otherwise went.
+            return
+
+
+def main() -> None:
+    port, bind = int(sys.argv[1]), sys.argv[2]
+    handler = partial(Handler, directory=os.getcwd())
+    with (
+        ThreadingHTTPServer((bind, port), handler) as server,
+        contextlib.suppress(KeyboardInterrupt),
+    ):
+        server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

{localghost-4.2.1 → localghost-4.3.0}/src/localghost/runner.py

@@ -68,6 +68,7 @@ SUPPORTED_TYPES = (
     "cakephp",
     "laravel",
     "php",
+    "html",
 )
 RUN_TYPES = tuple(item for item in SUPPORTED_TYPES if item != "dockerfile")
 # Types the non-Compose save path can persist. Compose is handled separately
@@ -93,6 +94,7 @@ DEFAULT_PORTS = {
     "cakephp": 8765,
     "laravel": 8000,
     "php": 8080,
+    "html": 8080,
 }
 
 COMPOSE_FILENAMES = (
@@ -299,6 +301,8 @@ def build_plan(
             default_port, selected_command, working_directory = php_command(
                 project_root, port
             )
+        elif selected_type == "html":
+            default_port, selected_command = html_command(port)
         else:  # Click validates the public option; retain this for direct callers.
             raise click.ClickException(type_choices("--type"))
         wanted_port = port or default_port
@@ -383,7 +387,9 @@ def discover_type(
 
     Ambiguity is computed after filtering to `allowed`, so a type another
     command handles never blocks this one. Generic `php` defers to anything
-    stronger found further up; see `_php_project_strength`.
+    stronger found further up; see `_php_project_strength`. `html` defers
+    to any other type at the same directory, and to any but a weak `php`
+    further up: the nearer of two fallbacks wins.
     """
     if requested is not None and requested not in SUPPORTED_TYPES:
         raise click.ClickException(type_choices("--type"))
@@ -400,6 +406,10 @@ def discover_type(
     fallback: tuple[str, Path] | None = None
     for candidate in _search_path(start):
         detected = [item for item in _types_at(candidate) if item in allowed]
+        if requested is None and "html" in detected:
+            detected.remove("html")
+            if not detected and fallback is None:
+                fallback = ("html", candidate)
         if requested is not None:
             if requested in detected:
                 if requested == "php" and _php_project_strength(candidate) != "strong":
@@ -531,6 +541,8 @@ def _types_at(cwd: Path) -> list[str]:
     php = _php_type(cwd, _composer_manifest(cwd))
     if php is not None:
         detected.append(php)
+    if (cwd / "index.html").is_file():
+        detected.append("html")
     return detected
 
 
@@ -642,6 +654,18 @@ def php_command(
     )
 
 
+def html_command(requested_port: int | None) -> tuple[int, tuple[str, ...]]:
+    """Serve the directory, reloading open pages on change; see `html_server`.
+
+    -I keeps a stray module in the served directory from being imported.
+    """
+    bind = "127.0.0.1" if forwarder.available() else "0.0.0.0"
+    return (
+        requested_port or DEFAULT_PORTS["html"],
+        (sys.executable, "-I", "-m", "localghost.html_server", "{port}", bind),
+    )
+
+
 def astro_command(cwd: Path, requested_port: int | None) -> tuple[int, tuple[str, ...]]:
     manifest = _astro_manifest(cwd)
     if manifest is None:

{localghost-4.2.1 → localghost-4.3.0}/src/localghost/tailscale.py

@@ -330,7 +330,7 @@ class API:
                 ) from exc
             if exc.code == 403:
                 raise TailscaleError(
-                    f"the OAuth client may not create auth keys: it needs the "
+                    f"the OAuth credential may not create auth keys: it needs the "
                     f"Auth Keys: Write scope with {tag} selected (Trust "
                     f"credentials page, {OAUTH_CONSOLE_URL})"
                 ) from exc
@@ -344,7 +344,7 @@ class API:
     def _dns_scope_guidance(exc: APIError) -> TailscaleError:
         if exc.code == 403:
             return TailscaleError(
-                "the OAuth client lacks the DNS: Write scope; recreate it on the "
+                "the OAuth credential lacks the DNS: Write scope; recreate it on the "
                 f"Trust credentials page ({OAUTH_CONSOLE_URL})"
             )
         return exc