#!/usr/bin/env python3
"""
Teaching project viewer — serves the project tree as a mobile-readable,
markdown-rendered website on the tailnet.
Run:
python3 viewer/serve.py
Override host/port via env:
VIEWER_HOST=0.0.0.0 VIEWER_PORT=8889 python3 viewer/serve.py
"""
import html
import mimetypes
import os
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from urllib.parse import quote, unquote
from markdown_it import MarkdownIt
from pygments import highlight as pyg_highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_by_name, guess_lexer
from pygments.util import ClassNotFound
ROOT = Path(__file__).resolve().parent.parent
HOST = os.environ.get("VIEWER_HOST", "100.83.250.41")
PORT = int(os.environ.get("VIEWER_PORT", "8889"))
SKIP_DIRS = {".git", "__pycache__", "node_modules", ".qdrant", ".venv", "venv", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
SKIP_FILES = {".DS_Store"}
SKIP_EXTS = {".pyc", ".pyo", ".webm", ".mov", ".mp4"}
# Pygments syntax highlighting for fenced code blocks in markdown
try:
_pyg_formatter = HtmlFormatter(style="github-light", cssclass="highlight", nobackground=True)
except Exception:
_pyg_formatter = HtmlFormatter(style="default", cssclass="highlight", nobackground=True)
PYGMENTS_CSS = _pyg_formatter.get_style_defs(".highlight")
def _highlight_code(code: str, lang: str, attrs: str) -> str:
try:
if lang:
lexer = get_lexer_by_name(lang, stripall=True)
else:
lexer = guess_lexer(code)
except (ClassNotFound, ValueError):
return "" # fall through to markdown-it default
return pyg_highlight(code, lexer, _pyg_formatter)
md_renderer = MarkdownIt(
"commonmark",
{"html": False, "linkify": True, "typographer": True, "highlight": _highlight_code},
).enable(["table", "strikethrough"])
GOOGLE_FONTS = (
'teaching ']
accum = ""
pieces = [] if str(rel_path) == "." else list(rel_path.parts)
for piece in pieces:
accum = f"{accum}/{piece}" if accum else f"/{piece}"
parts.append(f'{html.escape(piece)} ')
if file_name is not None:
parts.append(f'{html.escape(file_name)} ')
return ''
def listing_html(target: Path) -> str:
rows = []
try:
entries = sorted(target.iterdir(), key=lambda x: (not x.is_dir(), x.name.lower()))
except PermissionError:
return 'permission denied
'
for p in entries:
if is_hidden(p.name):
continue
rel = p.relative_to(ROOT)
if p.is_dir():
url = "/" + quote(str(rel)) + "/"
try:
count = sum(1 for x in p.iterdir() if not is_hidden(x.name))
except PermissionError:
count = 0
meta = f'{count} '
rows.append(f'{html.escape(p.name)}/{meta} {format_size(p.stat().st_size)} '
except OSError:
meta = ''
rows.append(f'{html.escape(p.name)}{meta} (empty)
'
return ''
def page_html(title: str, body: str, crumbs: str, with_highlight: bool = False) -> bytes:
extra_css = f'' if with_highlight else ''
return (
f'\n'
f'{html.escape(title)} '
f'{GOOGLE_FONTS}'
f''
f'{extra_css}'
f'{crumbs}{body}
'
).encode("utf-8")
def find_hymn() -> Path | None:
"""Locate the most-recently-modified web/hymn.html in the project tree."""
candidates = []
for dirpath, dirnames, filenames in os.walk(ROOT):
dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
if Path(dirpath).name == "web" and "hymn.html" in filenames:
candidates.append(Path(dirpath) / "hymn.html")
if not candidates:
return None
return max(candidates, key=lambda p: p.stat().st_mtime)
class Handler(BaseHTTPRequestHandler):
def log_message(self, fmt, *args):
# quieter logs — just method + path + status
print(f"{self.command} {self.path} → {args[1] if len(args) > 1 else '?'}")
def do_GET(self):
try:
self._handle()
except FileNotFoundError:
self.send_error(404, "not found")
except PermissionError:
self.send_error(403, "forbidden")
def _handle(self):
raw = unquote(self.path).split("?", 1)[0].split("#", 1)[0]
# /hymn.html alias → 302 to the actual web/hymn.html (so relative
# asset URLs in the page resolve correctly at the file's real location)
if raw == "/hymn.html":
target = find_hymn()
if target is None:
self.send_error(404, "no web/hymn.html in project")
return
rel = target.relative_to(ROOT)
self.send_response(302)
self.send_header("Location", "/" + quote(str(rel)))
self.send_header("Cache-Control", "no-store")
self.end_headers()
return
rel = raw.lstrip("/")
target = (ROOT / rel).resolve()
# path traversal guard
if target != ROOT and ROOT not in target.parents:
self.send_error(403, "outside root")
return
if not target.exists():
self.send_error(404, "not found")
return
if target.is_dir():
self._serve_dir(target)
else:
self._serve_file(target)
def _serve_dir(self, target: Path):
rel = target.relative_to(ROOT)
title = "teaching" if str(rel) == "." else f"teaching / {rel}"
crumbs = crumbs_html(rel) if str(rel) != "." else ''
body = listing_html(target)
self._respond(200, "text/html; charset=utf-8", page_html(title, body, crumbs))
def _serve_file(self, target: Path):
ext = target.suffix.lower()
if ext in SKIP_EXTS:
self.send_error(403, "skipped extension")
return
rel = target.relative_to(ROOT)
if ext == ".md":
text = target.read_text(encoding="utf-8", errors="replace")
body = '' + md_renderer.render(text) + ' '
crumbs = crumbs_html(rel.parent, file_name=target.name)
self._respond(200, "text/html; charset=utf-8", page_html(target.name, body, crumbs, with_highlight=True))
return
# HTML files render as actual pages so hymn.html and friends work.
if ext in {".html", ".htm"}:
data = target.read_bytes()
self._respond(200, "text/html; charset=utf-8", data)
return
# Everything else: serve raw with the proper MIME. Browsers will render
# text/* inline as plain text, parse text/css as CSS, etc. Audio gets
# Range support so iOS Safari can stream/seek.
mime, _ = mimetypes.guess_type(str(target))
mime = mime or "application/octet-stream"
self._serve_raw(target, mime)
def _serve_raw(self, target: Path, mime: str):
size = target.stat().st_size
rng = self.headers.get("Range", "")
if rng.startswith("bytes="):
try:
a, b = rng[6:].split("-", 1)
start = int(a) if a else 0
end = int(b) if b else size - 1
end = min(end, size - 1)
if start <= end:
with target.open("rb") as f:
f.seek(start)
chunk = f.read(end - start + 1)
self.send_response(206)
self.send_header("Content-Type", mime)
self.send_header("Content-Length", str(len(chunk)))
self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
self.send_header("Accept-Ranges", "bytes")
self.send_header("Cache-Control", "no-store")
self.end_headers()
self.wfile.write(chunk)
return
except (ValueError, OSError):
pass
data = target.read_bytes()
self.send_response(200)
self.send_header("Content-Type", mime)
self.send_header("Content-Length", str(len(data)))
self.send_header("Accept-Ranges", "bytes")
self.send_header("Cache-Control", "no-store")
self.end_headers()
self.wfile.write(data)
def _respond(self, status: int, content_type: str, body: bytes):
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.end_headers()
self.wfile.write(body)
def main():
print(f"viewer: serving {ROOT}")
print(f"viewer: http://{HOST}:{PORT}/")
httpd = ThreadingHTTPServer((HOST, PORT), Handler)
try:
httpd.serve_forever()
except KeyboardInterrupt:
print("\nviewer: stopped")
httpd.server_close()
if __name__ == "__main__":
main()