bible/server.py

#!/usr/bin/env python3
"""Static file server for the Bible site.

Stdlib only, so the container needs nothing but a Python base image.

It serves two directories as one origin: assets/, which is hand-written, and
books/, which render_books.py generates from bible.json. Nothing is copied
between them -- every file exists once, in the directory that owns it.

Beyond serving files it has three jobs.

The first is the shell. The pages here are fragments; shell.html is the one
document that wraps them, and app.js fills it in from the URL. So every
navigation is answered with shell.html, whatever path it asked for -- exactly
what the service worker does once it is installed, which is why a first visit
needs no special handling and no reload. Requests the worker and htmx make are
ordinary fetches rather than navigations, so they pass straight through and get
the fragment.

The second is stamping the service worker. A browser only notices a new worker
when the bytes of sw.js change, so something has to record what is on disk.
Doing it here rather than in a build step means editing the shell is the whole
job: save the file, reload, and the version the browser fetches already
differs. It also stamps in the list of pages the worker downloads to keep the
whole corpus available offline. See stamp_worker().

The third is cache headers: the worker owns the offline copy, and if the
worker or the shell that registers it are served stale, a new version can never
reach a device that already installed the old one.

Expects to sit behind something that terminates TLS. Without it the app still
works -- the shell and the fragments are plain files -- but there is no offline
copy: browsers only register a service worker in a secure context, and the
bookmark lives in that worker, so over plain http:// from a LAN address the app
reads online-only and the bookmark slot stays empty.
"""

from __future__ import annotations

import argparse
import hashlib
import io
import json
import os
import posixpath
import signal
import sys
from functools import partial
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer

# Revalidate every time: these are what carry an update to an installed app.
NO_CACHE_NAMES = {"sw.js"}
NO_CACHE_EXTS = {".html", ".webmanifest"}

# Served in place of any page a browser navigates to.
SHELL_PAGE = "/shell.html"

WORKER = "sw.js"

# The three lines stamp_worker() rewrites. They are real statements rather than
# placeholders so that assets/sw.js stays valid JavaScript on its own.
VERSION_LINE = "const VERSION = 'dev';"
LIBRARY_VERSION_LINE = "const LIBRARY_VERSION = 'dev';"
LIBRARY_LINE = "const LIBRARY = [];"


def walk(roots):
    """Every served file, as url-relative paths mapped to their disk path.

    Earlier roots win, which is what makes the two directories one origin.
    """
    found = {}
    for root in roots:
        for dirpath, _dirs, names in os.walk(root):
            for name in sorted(names):
                path = os.path.join(dirpath, name)
                rel = os.path.relpath(path, root).replace(os.sep, "/")
                found.setdefault(rel, path)
    return found


def digest(files):
    """A short fingerprint of a set of files, by name, size and mtime.

    Not by contents: it has to change whenever anything changes, and it is
    recomputed on every request for the worker, so reading 9 MB of book
    fragments to hash them would be a poor trade. Touching a file without
    changing it costs one needless refetch, which is harmless.
    """
    out = hashlib.sha256()
    for rel in sorted(files):
        st = os.stat(files[rel])
        out.update(("%s\0%d\0%d\0" % (rel, st.st_size, st.st_mtime_ns)).encode())
    return out.hexdigest()[:12]


def stamp_worker(roots):
    """assets/sw.js with its two versions and its file list filled in.

    The split is by root, which is the same split the project already makes:
    the first root is the hand-written chrome, the rest is what render_books.py
    generates. They get separate versions because they change on completely
    different schedules -- editing the shell should not cost every installed
    device the whole corpus again, which one shared version would.

    LIBRARY is the list the worker downloads in the background. Stamped rather
    than written by hand for the same reason the versions are: what is on disk
    is the only honest source, and there is no build step to ask.
    """
    chrome = walk(roots[:1])
    library = {rel: path for rel, path in walk(roots).items() if rel not in chrome}

    src = chrome.pop(WORKER, None)   # the browser revalidates the worker itself
    if src is None:
        return None
    with open(src, encoding="utf-8") as fh:
        body = fh.read()

    for line, value in (
        (VERSION_LINE, "const VERSION = '%s';" % digest(chrome)),
        (LIBRARY_VERSION_LINE, "const LIBRARY_VERSION = '%s';" % digest(library)),
        (LIBRARY_LINE, "const LIBRARY = %s;"
                       % json.dumps(sorted("./" + rel for rel in library), indent=2)),
    ):
        if line not in body:
            raise RuntimeError("%s: expected to find %r to stamp" % (WORKER, line))
        body = body.replace(line, value, 1)
    return body.encode("utf-8")


class Handler(SimpleHTTPRequestHandler):
    extensions_map = {
        **SimpleHTTPRequestHandler.extensions_map,
        ".html": "text/html; charset=utf-8",
        ".css": "text/css; charset=utf-8",
        ".js": "text/javascript; charset=utf-8",
        ".json": "application/json; charset=utf-8",
        ".webmanifest": "application/manifest+json; charset=utf-8",
        ".png": "image/png",
        ".svg": "image/svg+xml",
    }
    server_version = "bible-static"
    sys_version = ""
    roots = ()

    def translate_path(self, path):
        """Resolve against each root in turn, first hit wins.

        The parent does the sanitising -- it is what keeps ".." from escaping
        the root -- so this only ever swaps which root it resolves against.
        """
        for root in self.roots:
            self.directory = root
            candidate = super().translate_path(path)
            if os.path.exists(candidate):
                return candidate
        self.directory = self.roots[0]
        return super().translate_path(path)

    def send_head(self):
        # Sec-Fetch-Mode is the one signal that separates a browser opening a
        # URL from the worker or htmx fetching a fragment: neither of those is
        # ever in navigate mode. Browsers without the header also have no
        # service worker, and get the fragment -- there is nothing better to
        # give them.
        if self.headers.get("Sec-Fetch-Mode") == "navigate":
            self.path = SHELL_PAGE

        if posixpath.basename(self.path.split("?", 1)[0]) == WORKER:
            return self.send_worker()
        return super().send_head()

    def send_worker(self):
        try:
            body = stamp_worker(self.roots)
        except Exception as err:               # a broken stamp is a 500, not a
            self.log_message("stamp failed: %s", err)   # silently stale worker
            self.send_error(500, "service worker unavailable")
            return None
        if body is None:
            self.send_error(404, "no service worker")
            return None
        self.send_response(200)
        self.send_header("Content-Type", "text/javascript; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        return io.BytesIO(body)

    def end_headers(self):
        path = self.path.split("?", 1)[0]
        name = posixpath.basename(path)
        ext = posixpath.splitext(name)[1].lower()
        if name in NO_CACHE_NAMES or ext in NO_CACHE_EXTS or path.endswith("/"):
            self.send_header("Cache-Control", "no-cache")
        else:
            self.send_header("Cache-Control", "public, max-age=604800")
        # Lets the worker claim the whole origin even if it moves off root.
        self.send_header("Service-Worker-Allowed", "/")
        self.send_header("X-Content-Type-Options", "nosniff")
        super().end_headers()

    def log_message(self, fmt, *args):
        sys.stdout.write("%s %s\n" % (self.address_string(), fmt % args))
        sys.stdout.flush()


def main(argv=None):
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--root", action="append", dest="roots", metavar="DIR",
                    help="directory to serve; repeatable, earlier wins "
                         "(default: assets then books, or $SITE_ROOTS)")
    ap.add_argument("--host", default=os.environ.get("HOST", "0.0.0.0"))
    ap.add_argument("--port", type=int, default=int(os.environ.get("PORT", "8080")))
    args = ap.parse_args(argv)

    names = args.roots or os.environ.get("SITE_ROOTS", "assets:books").split(":")
    roots = tuple(os.path.abspath(name) for name in names if name)
    for root in roots:
        if not os.path.isdir(root):
            sys.exit("site root not found: %s" % root)

    httpd = ThreadingHTTPServer((args.host, args.port),
                                partial(type("Rooted", (Handler,), {"roots": roots}),
                                        directory=roots[0]))
    httpd.daemon_threads = True

    def stop(_signum, _frame):
        httpd.shutdown()

    signal.signal(signal.SIGTERM, stop)
    signal.signal(signal.SIGINT, stop)

    print("serving %s at http://%s:%d" % (" + ".join(roots), args.host, args.port))
    sys.stdout.flush()
    try:
        httpd.serve_forever()
    finally:
        httpd.server_close()
    return 0


if __name__ == "__main__":
    sys.exit(main())