pyweb-stack 0.1.0__py3-none-any.whl

pyweb/db/migrate.py

@@ -0,0 +1,143 @@
+"""Versioned migrations: journal + ordered apply + CLI.
+
+``migrations/`` holds ``NNN_name.up.sql`` / ``NNN_name.down.sql`` pairs.
+Applied versions are recorded in the ``pyweb_migrations`` journal table,
+so ``migrate`` is idempotent and ``status`` shows pending work. Works on
+any driver exposing ``execute()`` + ``transaction()`` (SQLite, Postgres,
+MySQL); the journal DDL is plain standard SQL.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+
+JOURNAL_DDL = (
+    "CREATE TABLE IF NOT EXISTS pyweb_migrations ("
+    "version VARCHAR(255) PRIMARY KEY, applied_at VARCHAR(64) NOT NULL)"
+)
+
+_FILE_RE = re.compile(r"^(\d+)_([A-Za-z0-9_]+)\.(up|down)\.sql$")
+
+
+def _discover(outdir):
+    """Return ``[(version, name)]`` sorted, validating up/down pairs."""
+    pairs: dict[tuple[str, str], set[str]] = {}
+    if os.path.isdir(outdir):
+        for fn in sorted(os.listdir(outdir)):
+            m = _FILE_RE.match(fn)
+            if m:
+                pairs.setdefault((m.group(1), m.group(2)), set()).add(m.group(3))
+    ordered = sorted(pairs)
+    for key, sides in pairs.items():
+        if sides != {"up", "down"}:
+            raise ValueError(f"migration {key[0]}_{key[1]} is missing "
+                             f"{'down' if 'up' in sides else 'up'} file")
+    return ordered
+
+
+def _read(outdir, version, name, direction):
+    path = os.path.join(outdir, f"{version}_{name}.{direction}.sql")
+    with open(path) as fh:
+        return [s.strip() for s in _split(fh.read()) if s.strip()]
+
+
+def _split(script):
+    lines = [ln for ln in script.splitlines() if not ln.strip().startswith("--")]
+    return [s.strip() for s in "\n".join(lines).split(";")]
+
+
+def _applied(db) -> set[str]:
+    db.execute(JOURNAL_DDL)
+    res = db.execute("SELECT version FROM pyweb_migrations")
+    rows = res.fetchall() if hasattr(res, "fetchall") else res
+    out = set()
+    for row in rows or []:
+        if isinstance(row, (list, tuple)):
+            out.add(row[0])
+        elif isinstance(row, dict):
+            out.add(row.get("version"))
+        else:
+            out.add(row)
+    return out
+
+
+def status(db_or_url, outdir="migrations"):
+    """Return ``[(label, applied_bool)]`` for every discovered migration."""
+    from pyweb.db import connect
+    db = connect(db_or_url) if isinstance(db_or_url, str) else db_or_url
+    done = _applied(db)
+    return [(f"{v}_{n}", f"{v}_{n}" in done) for v, n in _discover(outdir)]
+
+
+def migrate(db_or_url, outdir="migrations"):
+    """Apply pending ``*.up.sql`` in version order. Returns applied labels."""
+    from pyweb.db import connect
+    db = connect(db_or_url) if isinstance(db_or_url, str) else db_or_url
+    done = _applied(db)
+    applied = []
+    for version, name in _discover(outdir):
+        label = f"{version}_{name}"
+        if label in done:
+            continue
+        statements = _read(outdir, version, name, "up")
+        ph = "?" if getattr(db, "paramstyle", "qmark") == "qmark" else "%s"
+        with db.transaction():
+            for stmt in statements:
+                db.execute(stmt)
+            db.execute(
+                "INSERT INTO pyweb_migrations (version, applied_at) "
+                f"VALUES ({ph}, {ph})",
+                (label, time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())))
+        applied.append(label)
+    return applied
+
+
+def rollback(db_or_url, outdir="migrations", *, steps=1, to=None):
+    """Apply ``*.down.sql`` for the latest applied migration(s).
+
+    ``steps=N`` rolls back the N most recent applied migrations (default
+    1). ``to=<label>`` rolls back everything applied *after* ``label``,
+    keeping ``label`` itself; unknown labels raise ``ValueError`` without
+    touching the database.
+    """
+    from pyweb.db import connect
+    db = connect(db_or_url) if isinstance(db_or_url, str) else db_or_url
+    done = _applied(db)
+    ordered = [f"{v}_{n}" for v, n in _discover(outdir) if f"{v}_{n}" in done]
+    if to is not None:
+        if to not in ordered:
+            raise ValueError(
+                f"rollback --to {to!r}: not an applied migration; "
+                f"applied: {', '.join(ordered) or 'none'}")
+        targets = ordered[ordered.index(to) + 1:]
+    else:
+        targets = ordered[max(len(ordered) - max(steps, 0), 0):]
+    rolled = []
+    for label in reversed(targets):
+        version, name = label.split("_", 1)
+        with db.transaction():
+            for stmt in _read(outdir, version, name, "down"):
+                db.execute(stmt)
+            ph = "?" if getattr(db, "paramstyle", "qmark") == "qmark" else "%s"
+            db.execute(f"DELETE FROM pyweb_migrations WHERE version = {ph}",
+                       (label,))
+        rolled.append(label)
+    return rolled
+
+
+def new_migration(outdir, name):
+    """Scaffold the next ``NNN_name.{up,down}.sql`` pair. Returns up path."""
+    safe = re.sub(r"[^A-Za-z0-9_]+", "_", name).strip("_") or "migration"
+    os.makedirs(outdir, exist_ok=True)
+    existing = [m.group(1) for m in
+                (_FILE_RE.match(f) for f in os.listdir(outdir)) if m]
+    nxt = f"{(max(map(int, existing)) + 1) if existing else 1:03d}"
+    up = os.path.join(outdir, f"{nxt}_{safe}.up.sql")
+    down = os.path.join(outdir, f"{nxt}_{safe}.down.sql")
+    with open(up, "w") as fh:
+        fh.write(f"-- Migration {nxt}_{safe} (up).\n")
+    with open(down, "w") as fh:
+        fh.write(f"-- Migration {nxt}_{safe} (down).\n")
+    return up

pyweb/decorators.py

@@ -0,0 +1,49 @@
+"""Placement and component markers. All are metadata-only at runtime."""
+
+from __future__ import annotations
+
+
+def _mark(fn_or_cls, **flags):
+    if fn_or_cls is None:
+        def deco(target):
+            return _mark(target, **flags)
+        return deco
+    for key, value in flags.items():
+        setattr(fn_or_cls, f"__pyweb_{key}__", value)
+    return fn_or_cls
+
+
+def component(fn=None):
+    return _mark(fn, component=True) if fn else lambda t: _mark(t, component=True)
+
+
+def server(fn=None):
+    return _mark(fn, location="server") if fn else lambda t: _mark(t, location="server")
+
+
+
+def edge(fn=None):
+    return _mark(fn, location="edge") if fn else lambda t: _mark(t, location="edge")
+
+
+def worker(fn=None):
+    return _mark(fn, location="worker") if fn else lambda t: _mark(t, location="worker")
+
+
+
+def csrf_exempt(fn=None):
+    """Skip the CSRF check for this RPC (safe methods / token endpoints)."""
+    return _mark(fn, csrf_exempt=True) if fn else lambda t: _mark(t, csrf_exempt=True)
+
+
+def auth_required(fn=None):
+    """Require an authenticated session to call this RPC."""
+    return _mark(fn, auth="required") if fn else lambda t: _mark(t, auth="required")
+
+
+def rate_limited(fn=None, *, max_calls=60, window=60.0):
+    """Per-RPC rate-limit hint; enforced when a Server has a limiter."""
+    def apply(target):
+        _mark(target, rate_limit=(max_calls, window))
+        return target
+    return apply(fn) if fn else apply

pyweb/deploy.py

@@ -0,0 +1,102 @@
+"""Deployment: Dockerfile, compose, k8s manifests, env/secret handling."""
+
+from __future__ import annotations
+
+import os
+import re
+
+
+def dockerfile(python="3.12-slim", port=8000, app_file="app.pyweb"):
+    """Dockerfile for an app directory (``app.pyweb`` + optional requirements.txt)."""
+    from pyweb import __version__
+    pin = f"=={__version__}" if __version__[:1].isdigit() and "+" not in __version__ else ""
+    return (
+        f"FROM python:{python}\n"
+        "WORKDIR /app\n"
+        f"RUN pip install --no-cache-dir pyweb-stack{pin}\n"
+        "COPY requirements.tx[t] ./\n"
+        "RUN if [ -f requirements.txt ]; then pip install --no-cache-dir -r requirements.txt; fi\n"
+        "COPY . .\n"
+        f"RUN pyweb build {app_file} --out dist --production\n"
+        "ENV PYWEB_ENV=production\n"
+        f"EXPOSE {port}\n"
+        'HEALTHCHECK --interval=30s --timeout=5s CMD python -c '
+        '"import urllib.request,sys;sys.exit(0 if urllib.request.urlopen('
+        f"'http://127.0.0.1:{port}/healthz').status==200 else 1)\"\n"
+        f'CMD ["pyweb", "serve", "dist", "--host", "0.0.0.0", "--port", "{port}"]\n'
+    )
+
+
+def compose(service="pyweb", port=8000, db_url=""):
+    db = f'\n      - DATABASE_URL={db_url}' if db_url else ""
+    return (
+        "services:\n"
+        f"  {service}:\n"
+        "    build: .\n"
+        "    ports:\n"
+        f'      - "{port}:{port}"\n'
+        "    environment:\n"
+        f"      - PORT={port}{db}\n"
+        "    restart: unless-stopped\n"
+    )
+
+
+def k8s_manifest(app="pyweb", image="pyweb:latest", port=8000, replicas=2):
+    return (
+        "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n"
+        f"  name: {app}\n"
+        "spec:\n"
+        f"  replicas: {replicas}\n"
+        "  selector:\n"
+        "    matchLabels:\n"
+        f"      app: {app}\n"
+        "  template:\n"
+        "    metadata:\n"
+        f"      labels:\n        app: {app}\n"
+        "    spec:\n"
+        "      containers:\n"
+        f"      - name: {app}\n"
+        f"        image: {image}\n"
+        "        ports:\n"
+        f"        - containerPort: {port}\n"
+        "        livenessProbe:\n"
+        "          httpGet:\n"
+        "            path: /healthz\n"
+        f"            port: {port}\n"
+        "          periodSeconds: 30\n"
+        "        readinessProbe:\n"
+        "          httpGet:\n"
+        "            path: /healthz\n"
+        f"            port: {port}\n"
+        "          periodSeconds: 5\n"
+        "        env:\n"
+        "        - name: PORT\n"
+        f'          value: "{port}"\n'
+        "---\n"
+        "apiVersion: v1\nkind: Service\nmetadata:\n"
+        f"  name: {app}\n"
+        "spec:\n"
+        "  selector:\n"
+        f"    app: {app}\n"
+        "  ports:\n"
+        f"  - port: {port}\n"
+    )
+
+
+_ENV_RE = re.compile(r"\$\{(\w+)(?::-([^}]*))?\}")
+
+
+def expand_env(text, env=None):
+    env = env if env is not None else os.environ
+
+    def repl(m):
+        return env.get(m.group(1), m.group(2) if m.group(2) is not None else "")
+    return _ENV_RE.sub(repl, text)
+
+
+def required_env(names, env=None):
+    env = env if env is not None else os.environ
+    missing = [n for n in names if not env.get(n)]
+    if missing:
+        raise RuntimeError(f"missing required env: {', '.join(missing)}")
+    return {n: env[n] for n in names}

pyweb/forms.py

@@ -0,0 +1,108 @@
+"""Forms: single-schema derivation from Model annotations, validation,
+plus rule-based request validation."""
+
+from __future__ import annotations
+
+import html as _html
+import re
+
+MAX_FIELD_LENGTH = 500
+
+_EMAIL_RE = re.compile(r"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$")
+
+
+def _check_rule(value, rule):
+    name, _, arg = rule.partition(":")
+    if name == "required":
+        if value is None or (isinstance(value, str) and not value.strip()):
+            return "this field is required"
+    elif name == "email":
+        if value is not None and not _EMAIL_RE.match(str(value)):
+            return "enter a valid email address"
+    elif name == "max_length":
+        if value is not None and len(str(value)) > int(arg):
+            return f"must be at most {arg} characters"
+    elif name == "min_length":
+        if value is not None and len(str(value)) < int(arg):
+            return f"must be at least {arg} characters"
+    return None
+
+
+def validate_request(data, rules):
+    """Validate ``data`` against ``{field: [rules]}``; return error dict."""
+    errors = {}
+    for field, field_rules in rules.items():
+        value = data.get(field)
+        if isinstance(value, str) and len(value) > MAX_FIELD_LENGTH * 10:
+            errors[field] = ["value too long"]
+            continue
+        for rule in field_rules:
+            err = _check_rule(value, rule)
+            if err:
+                errors.setdefault(field, []).append(err)
+    return errors
+
+
+def _kind(ann):
+    name = getattr(ann, "__name__", str(ann))
+    if name == "Email":
+        return "email"
+    return {"str": "text", "int": "number", "float": "number",
+            "bool": "checkbox"}.get(name, "text")
+
+
+def fields_for(model):
+    fields = []
+    for fname, ann in getattr(model, "_fields", {}).items():
+        name = getattr(ann, "__name__", str(ann))
+        fields.append({"name": fname, "kind": _kind(ann), "type": name,
+                       "required": True})
+    return fields
+
+
+def render_form(model, *, action="", method="post", submit="Submit",
+                csrf_token=None):
+    parts = [f'<form action="{_html.escape(action)}" method="{method}">']
+    if csrf_token:
+        parts.append(f'<input type="hidden" name="csrf_token" '
+                     f'value="{_html.escape(csrf_token)}" />')
+    for f in fields_for(model):
+        if f["kind"] == "checkbox":
+            parts.append(f'<label><input type="checkbox" name="{f["name"]}" /> {f["name"]}</label>')
+        else:
+            parts.append(f'<label>{f["name"]}<input type="{f["kind"]}" name="{f["name"]}" required /></label>')
+    parts.append(f"<button>{_html.escape(submit)}</button></form>")
+    return "".join(parts)
+
+
+def validate(model, data):
+    """Validate a dict against model annotations. Returns (clean, errors)."""
+    clean, errors = {}, {}
+    import datetime
+    from decimal import Decimal
+    for fname, ann in getattr(model, "_fields", {}).items():
+        name = getattr(ann, "__name__", str(ann))
+        raw = (data or {}).get(fname)
+        if raw in (None, ""):
+            errors[fname] = "required"
+            continue
+        try:
+            if name == "Email":
+                if "@" not in str(raw):
+                    raise ValueError("must be a valid email")
+                clean[fname] = str(raw)
+            elif name == "int":
+                clean[fname] = int(raw)
+            elif name == "float":
+                clean[fname] = float(raw)
+            elif name == "Decimal":
+                clean[fname] = Decimal(str(raw))
+            elif name == "bool":
+                clean[fname] = str(raw).lower() in ("1", "true", "yes", "on")
+            elif name == "datetime":
+                clean[fname] = raw if isinstance(raw, datetime.datetime) else datetime.datetime.fromisoformat(str(raw))
+            else:
+                clean[fname] = str(raw)
+        except (ValueError, TypeError, ArithmeticError) as exc:
+            errors[fname] = str(exc)
+    return clean, errors

pyweb/hosting.py

@@ -0,0 +1,139 @@
+"""Hosting glue shared by ``pyweb dev`` and the ASGI adapter.
+
+A :class:`Site` answers one HTTP request: static assets, ``/healthz``,
+pages and RPC (via :class:`pyweb.runtime.server.Server`). It is
+transport-agnostic: callers pass method/path/headers/body and get back
+``(status, [(header, value)], body_bytes)``.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import time
+
+from .runtime.server import Request, Server
+
+RUNTIME_PATH = os.path.join(os.path.dirname(__file__), "runtime", "browser", "runtime.js")
+
+SECURITY_HEADERS = [
+    ("X-Content-Type-Options", "nosniff"),
+    ("Referrer-Policy", "same-origin"),
+    ("X-Frame-Options", "SAMEORIGIN"),
+]
+
+
+def _ctype(path):
+    if path.endswith(".js") or path.endswith(".mjs"):
+        return "text/javascript; charset=utf-8"
+    if path.endswith(".map") or path.endswith(".json"):
+        return "application/json"
+    if path.endswith(".css"):
+        return "text/css; charset=utf-8"
+    return mimetypes.guess_type(path)[0] or "application/octet-stream"
+
+
+class Site:
+    """Serve an app from source (``app.pyweb``) or from a built ``dist/``."""
+
+    def __init__(self, target, *, debug=False, max_body=1_048_576, **server_kwargs):
+        from .app_loader import LoadedApp
+        from .serve import DEFAULT_CSP, load_dist
+        self.debug = debug
+        self.max_body = max_body
+        self.started = time.time()
+        self.csp = os.environ.get("PYWEB_CSP", DEFAULT_CSP)
+        self.server_kwargs = dict(server_kwargs)
+        # Same production defaults as `pyweb serve`.
+        if "rate_limit" not in self.server_kwargs and not debug:
+            from .rpc import RateLimiter
+            self.server_kwargs["rate_limit"] = RateLimiter(max_calls=120, window=60.0)
+        elif self.server_kwargs.get("rate_limit") is False:
+            self.server_kwargs["rate_limit"] = None
+        self.server_kwargs.setdefault("auth_secret", os.environ.get("PYWEB_AUTH_SECRET"))
+        self.server_kwargs.setdefault("csrf_secret", os.environ.get("PYWEB_CSRF_SECRET"))
+        self.server_kwargs.setdefault(
+            "secure_cookies", os.environ.get("PYWEB_COOKIE_SECURE", "").lower() in ("1", "true"))
+        if os.path.isdir(target):
+            manifest, static_dir, _ = load_dist(target)
+            self.static_dirs = [static_dir]
+            self.memory_js = {}
+            asset_urls = {name: f"/static/{p['js']}" for name, p in manifest.get("pages", {}).items()
+                          if p.get("js")}
+            self.app = LoadedApp(os.path.join(target, manifest.get("app") or "app.pyweb"),
+                                 asset_urls=asset_urls)
+            self.source_mode = False
+        else:
+            self.app_path = target
+            self.static_dirs = [os.path.join(os.path.dirname(os.path.abspath(target)), "static")]
+            self.source_mode = True
+            self.app = LoadedApp(target)
+            self._index_memory_js()
+        self.server = Server(app=self.app, debug=debug, max_body=max_body, **server_kwargs)
+
+    def _index_memory_js(self):
+        self.memory_js = {f"{n}.js": p["js"] for n, p in self.app.compiled["pages"].items() if p["js"]}
+
+    def reload(self):
+        """Re-load the app from source (dev hot reload)."""
+        from .app_loader import LoadedApp
+        app = LoadedApp(self.app_path)
+        self.app = app
+        self._index_memory_js()
+        self.server = Server(app=app, debug=self.debug, max_body=self.max_body, **self.server_kwargs)
+
+    # ------------------------------------------------------------ static
+    def static(self, rel):
+        rel = rel.split("?")[0]
+        if self.source_mode:
+            if rel == "runtime.js":
+                with open(RUNTIME_PATH, "rb") as fh:
+                    return 200, [("Content-Type", _ctype(rel)), ("Cache-Control", "no-cache")], fh.read()
+            if rel in self.memory_js:
+                return 200, [("Content-Type", _ctype(rel)), ("Cache-Control", "no-cache")], \
+                    self.memory_js[rel].encode()
+        for base in self.static_dirs:
+            base = os.path.realpath(base)
+            target = os.path.realpath(os.path.join(base, rel))
+            if target != base and not target.startswith(base + os.sep):
+                return 403, [("Content-Type", "text/plain")], b"forbidden"
+            if os.path.isfile(target):
+                with open(target, "rb") as fh:
+                    body = fh.read()
+                cache = "no-cache" if self.source_mode else "public, max-age=31536000, immutable"
+                return 200, [("Content-Type", _ctype(target)), ("Cache-Control", cache)], body
+        return 404, [("Content-Type", "text/plain")], b"not found"
+
+    # ----------------------------------------------------------- request
+    def respond(self, method, path, headers, body=b""):
+        bare = path.split("?")[0]
+        if bare in ("/healthz", "/health", "/readyz"):
+            from . import __version__
+            payload = {"ok": True, "version": __version__, "uptime_s": round(time.time() - self.started, 3)}
+            out = (200, [("Content-Type", "application/json")], json.dumps(payload).encode())
+        elif bare.startswith("/static/") and method in ("GET", "HEAD"):
+            out = self.static(bare[len("/static/"):])
+        elif len(body or b"") > self.max_body:
+            out = (413, [("Content-Type", "application/json")],
+                   json.dumps({"error": {"code": "http_413", "message": "request body too large"}}).encode())
+        else:
+            resp = self.server.handle(Request(method, path, headers, body))
+            hdrs = []
+            for k, v in resp.headers.items():
+                for item in (v if isinstance(v, list) else [v]):
+                    hdrs.append((k, str(item)))
+            raw = resp.body.encode() if isinstance(resp.body, str) else (resp.body or b"")
+            out = (resp.status, hdrs, raw)
+        status, hdrs, raw = out
+        names = {k.lower() for k, _ in hdrs}
+        for k, v in SECURITY_HEADERS:
+            if k.lower() not in names:
+                hdrs.append((k, v))
+        ctype = next((v for k, v in hdrs if k.lower() == "content-type"), "")
+        if ctype.startswith("text/html") and not self.debug and "content-security-policy" not in names:
+            hdrs.append(("Content-Security-Policy", self.csp))
+        if method == "HEAD":
+            hdrs.append(("Content-Length", str(len(raw))))
+            raw = b""
+        return status, hdrs, raw