pyweb-stack 0.1.0__py3-none-any.whl

pyweb/observability.py

@@ -0,0 +1,313 @@
+"""Observability: structured logs, traces, metrics, error mapping.
+
+One logical interaction (button click -> RPC -> DB -> DOM update) shares
+a single trace id end to end: the browser runtime sends
+``X-Request-Id``/``traceparent`` headers (see :mod:`pyweb.rpc`), the
+server joins them via :func:`context_from_headers`, and every span,
+log record and error report carries the trace.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import sys
+import threading
+import time
+import traceback
+import uuid
+
+
+class Logger:
+    """JSON-lines logger. ``Logger("serve")`` names the component;
+    ``Logger(stream=fh)`` (or a stream positionally) redirects output."""
+
+    def __init__(self, name=None, stream=None):
+        if name is not None and not isinstance(name, str):
+            name, stream = None, name
+        self.name = name
+        self.stream = stream or sys.stdout
+        self._lock = threading.Lock()
+
+    def log(self, level, message, **fields):
+        rec = {"ts": time.time(), "level": level, "msg": message, **fields}
+        if self.name:
+            rec.setdefault("logger", self.name)
+        with self._lock:
+            self.stream.write(json.dumps(rec) + "\n")
+            self.stream.flush()
+
+    def info(self, message, **fields):
+        self.log("info", message, **fields)
+
+    def error(self, message, **fields):
+        self.log("error", message, **fields)
+
+
+class Tracer:
+    def __init__(self):
+        self.spans: list[dict] = []
+        self._local = threading.local()
+
+    def start(self, name, trace_id=None, **fields):
+        trace_id = trace_id or _current_trace.get() or uuid.uuid4().hex[:16]
+        span = {"trace": trace_id, "span": uuid.uuid4().hex[:16],
+                "name": name, "start": time.time(), "end": None, **fields}
+        self.spans.append(span)
+        self._local.current = span
+        return span
+
+    def finish(self, span):
+        span["end"] = time.time()
+        span["dur_ms"] = round((span["end"] - span["start"]) * 1000, 3)
+
+    def span(self, name, **fields):
+        """``with tracer.span("db.query", table="users"):`` ..."""
+        return Span(self, name, **fields)
+
+    def trace(self, name, trace_id=None):
+        if trace_id is not None:
+            _current_trace.set(trace_id)
+        return self.span(name)
+
+
+class Metrics:
+    def __init__(self):
+        self.counters: dict[str, int] = {}
+        self.timings: dict[str, list[float]] = {}
+        self._lock = threading.Lock()
+
+    def inc(self, name, amount=1):
+        with self._lock:
+            self.counters[name] = self.counters.get(name, 0) + amount
+
+    def observe(self, name, value):
+        with self._lock:
+            self.timings.setdefault(name, []).append(value)
+
+    def summary(self):
+        with self._lock:
+            out = {"counters": dict(self.counters)}
+            for k, vals in self.timings.items():
+                out[k] = {"n": len(vals), "avg": sum(vals) / len(vals) if vals else 0,
+                          "max": max(vals) if vals else 0}
+            return out
+
+
+def format_error(exc, source_lines=None, filename="<pyweb>"):
+    """Map an exception to a PyWeb-style error with source context."""
+    tb = traceback.extract_tb(exc.__traceback__)
+    frame = tb[-1] if tb else None
+    out = [f"{type(exc).__name__}: {exc}"]
+    if frame is not None:
+        out.append(f"{frame.filename}:{frame.lineno}")
+        if source_lines and 0 < frame.lineno <= len(source_lines):
+            i = frame.lineno
+            start = max(0, i - 3)
+            for n, line in enumerate(source_lines[start:i + 1], start=start + 1):
+                mark = ">>" if n == i else "  "
+                out.append(f"{mark} {n:4d} | {line}")
+    return "\n".join(out)
+
+
+class Timer:
+    def __enter__(self):
+        self._start = time.time()
+        self.elapsed_s = 0.0
+        return self
+
+    def __exit__(self, *exc):
+        self.elapsed_s = time.time() - self._start
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Distributed trace context (W3C traceparent compatible)
+# ---------------------------------------------------------------------------
+
+_current_trace: contextvars.ContextVar = contextvars.ContextVar(
+    "pyweb_trace", default=None)
+_current_span: contextvars.ContextVar = contextvars.ContextVar(
+    "pyweb_span", default=None)
+
+
+def new_trace() -> str:
+    """Start a fresh 16-hex-char trace id for an inbound request."""
+    trace_id = uuid.uuid4().hex[:16]
+    _current_trace.set(trace_id)
+    return trace_id
+
+
+def context_from_headers(headers: dict) -> str:
+    """Join an incoming trace or start a new one.
+
+    Accepts ``traceparent`` (``00-<trace>-<span>-<flags>``) and
+    ``X-Request-Id``; falls back to :func:`new_trace`. Returns the
+    active trace id. Why both: browsers that cannot set custom headers
+    (plain form posts, SSE) still send X-Request-Id via query or the
+    runtime's fetch wrapper.
+    """
+    headers = {str(k).lower(): v for k, v in (headers or {}).items()}
+    tp = headers.get("traceparent", "")
+    parts = tp.split("-")
+    if len(parts) == 4 and len(parts[1]) == 32:
+        trace_id = parts[1][:16]
+    else:
+        trace_id = str(headers.get("x-request-id", "")) or ""
+    if not trace_id:
+        return new_trace()
+    _current_trace.set(trace_id[:16])
+    return _current_trace.get()
+
+
+def active_trace() -> str | None:
+    return _current_trace.get()
+
+
+def inject_headers(headers: dict | None = None) -> dict:
+    """Outgoing headers carrying the active trace (client/RPC use)."""
+    headers = dict(headers or {})
+    trace_id = _current_trace.get()
+    if trace_id:
+        headers.setdefault("X-Request-Id", trace_id)
+        span = _current_span.get() or uuid.uuid4().hex[:16]
+        headers.setdefault("traceparent", f"00-{trace_id}-{(span)[:16]}-01")
+    return headers
+
+
+class Span:
+    """Trace span usable as ``with tracer.span("db.query"):``."""
+
+    def __init__(self, tracer, name, **fields):
+        self._tracer = tracer
+        self._name = name
+        self._fields = fields
+        self.span = None
+
+    def __enter__(self):
+        trace_id = _current_trace.get() or new_trace()
+        self.span = self._tracer.start(
+            self._name, trace_id=trace_id, **self._fields)
+        _current_span.set(self.span.get("span", ""))
+        return self.span
+
+    def __exit__(self, *exc):
+        self._tracer.finish(self.span)
+        _current_span.set(None)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Error taxonomy: every failure maps to a stable code + safe message.
+# ---------------------------------------------------------------------------
+
+_ERROR_CODES = [
+    (ValueError, "bad-request"),
+    (KeyError, "not-found"),
+    (PermissionError, "forbidden"),
+]
+
+
+def register_error_code(exc_type, code: str):
+    """Map an exception class to a stable wire code (checked most specific first)."""
+    _ERROR_CODES.insert(0, (exc_type, code))
+
+
+def error_code(exc: BaseException) -> str:
+    for exc_type, code in _ERROR_CODES:
+        if isinstance(exc, exc_type):
+            return code
+    return "internal"
+
+
+def error_report(exc: BaseException, *, source_lines=None,
+                 filename="<pyweb>", safe_detail=True) -> dict:
+    """Structured error payload: code, trace, source context.
+
+    ``message`` is safe to send to browsers; the original ``repr`` stays
+    server-side in logs. ``safe_detail=False`` is for CLI/dev only.
+    """
+    text = format_error(exc, source_lines, filename)
+    lines = text.splitlines()
+    return {"code": error_code(exc),
+            "message": lines[0] if lines else type(exc).__name__,
+            "detail": text if not safe_detail else None,
+            "trace": active_trace(),
+            "type": type(exc).__name__}
+
+
+# Register framework error codes (import-light: resolved lazily).
+def _register_framework_codes():
+    try:
+        from pyweb.rpc import RPCError
+        register_error_code(RPCError, "rpc")
+    except ImportError:
+        pass
+    try:
+        from pyweb import auth as _auth
+        register_error_code(_auth.AuthError, "unauthenticated")
+        register_error_code(_auth.Forbidden, "forbidden")
+        register_error_code(_auth.NotAuthenticated, "unauthenticated")
+    except ImportError:
+        pass
+
+
+_register_framework_codes()
+
+
+# ---------------------------------------------------------------------------
+# Time-travel event log: deterministic record/replay of state changes.
+# ---------------------------------------------------------------------------
+
+class EventLog:
+    """Append-only ring buffer of state/RPC/DB events for debugging.
+
+    ``record("signal", name="count", old=2, new=3)`` captures what the
+    DevTools timeline shows. ``replay()`` re-applies signal events to a
+    namespace dict so a developer can step through what happened.
+    Bounded (default 10k events) so it is safe to leave on in staging.
+    """
+
+    def __init__(self, capacity=10_000):
+        self._capacity = capacity
+        self._events: list[dict] = []
+        self._lock = threading.Lock()
+        self._seq = 0
+
+    def record(self, kind, **fields):
+        with self._lock:
+            self._seq += 1
+            event = {"seq": self._seq, "ts": time.time(), "kind": kind,
+                     "trace": _current_trace.get(), **fields}
+            self._events.append(event)
+            del self._events[:-self._capacity]
+            return event
+
+    def since(self, seq=0, kind=None, limit=1000):
+        with self._lock:
+            events = [e for e in self._events if e["seq"] > seq]
+        if kind is not None:
+            events = [e for e in events if e["kind"] == kind]
+        return events[:limit]
+
+    def replay(self, namespace: dict, *, up_to=None):
+        """Re-apply ``signal`` events to ``namespace``; returns final seq."""
+        last = 0
+        for event in self.since(0):
+            if up_to is not None and event["seq"] > up_to:
+                break
+            if event["kind"] == "signal" and "name" in event:
+                namespace[event["name"]] = event.get("new")
+            last = event["seq"]
+        return last
+
+    def to_json(self):
+        with self._lock:
+            return json.dumps(self._events)
+
+
+_default_log = EventLog()
+
+
+def record(kind, **fields):
+    return _default_log.record(kind, **fields)

pyweb/platform.py

@@ -0,0 +1,69 @@
+"""Multi-target platform branches: web / mobile / desktop / edge.
+
+```python
+from pyweb import platform
+
+if platform.web:
+    <Article>...</Article>
+
+if platform.mobile:
+    <NativeList>...</NativeList>
+```
+
+On the server all flags except ``server`` are False; the compiler
+evaluates the branch for its target and prunes dead branches per
+output (web bundle drops mobile code and vice versa). Shared business
+logic lives outside the branch. This is intentionally *not* a
+write-once-render-everywhere widget set — each target keeps its
+native controls; PyWeb shares state, RPC, models and routing.
+"""
+
+from __future__ import annotations
+
+import os
+
+_TARGET = os.environ.get("PYWEB_TARGET", "web")
+
+web = _TARGET in ("web", "server")
+mobile = _TARGET in ("ios", "android")
+desktop = _TARGET in ("desktop",)
+server = True
+edge = _TARGET == "edge"
+
+#: All known targets (used by the compiler to prune branches).
+TARGETS = ("web", "ios", "android", "desktop", "edge", "server")
+
+
+def target() -> str:
+    return _TARGET
+
+
+def prune(source: str, keep: str) -> str:
+    """Prune platform branches for ``keep`` from ``source`` text.
+
+    Keeps ``if platform.<keep>:`` blocks, drops the other platform
+    branches, unwraps shared code. Operates on source text with ``ast``
+    so pruning is exact, not regex-based.
+    """
+    import ast as _ast
+    tree = _ast.parse(source)
+    keep_attr = {"ios": "mobile", "android": "mobile"}.get(keep, keep)
+
+    class Pruner(_ast.NodeTransformer):
+        def visit_If(self, node):  # noqa: N802
+            self.generic_visit(node)
+            test = node.test
+            if (isinstance(test, _ast.Attribute)
+                    and isinstance(test.value, _ast.Name)
+                    and test.value.id == "platform"):
+                if test.attr == keep_attr or (
+                        keep_attr == "mobile" and test.attr == "mobile"):
+                    return node.body
+                if test.attr in ("web", "mobile", "desktop", "edge",
+                                 "server"):
+                    return node.orelse or None
+            return node
+
+    pruned = Pruner().visit(tree)
+    _ast.fix_missing_locations(pruned)
+    return _ast.unparse(pruned)

pyweb/plugins.py

@@ -0,0 +1,112 @@
+"""Plugin architecture: typed, compiler-visible extensions.
+
+A plugin participates in the application graph instead of hiding
+behind stringly-typed hooks — it declares routes, RPC functions,
+models, browser bindings and build steps with types, so placement,
+security checks and codegen keep working across plugin boundaries.
+
+```python
+stripe = Plugin("stripe", version="1.0.0")
+
+@stripe.server
+def checkout(cart_id: str) -> str:
+    ...
+
+app = App(plugins=[stripe])
+```
+"""
+
+from __future__ import annotations
+
+
+class Plugin:
+    """Namespace for plugin-provided routes, RPC, models and assets."""
+
+    def __init__(self, name, *, version="0.1.0"):
+        self.name = name
+        self.version = version
+        self.routes: list = []
+        self.rpc: list = []
+        self.models: list = []
+        self.browser_bindings: dict = {}
+        self.build_steps: list = []
+        self.config_schema: dict = {}
+        self.config: dict = {}
+
+    def configure(self, **config):
+        """Validate ``config`` against the plugin's schema, store it."""
+        for key, spec in self.config_schema.items():
+            if spec.get("required") and key not in config:
+                raise ValueError(
+                    f"plugin {self.name!r} requires config key {key!r}")
+        self.config.update(config)
+        return self
+
+    def server(self, fn=None, **opts):
+        from pyweb.decorators import server as _server
+        if fn is None:
+            return lambda f: self.server(f, **opts)
+        fn = _server(fn)
+        fn.__pyweb_plugin__ = self.name
+        self.rpc.append(fn)
+        return fn
+
+    def page(self, route, **opts):
+        def deco(fn):
+            fn.__pyweb_route__ = route
+            fn.__pyweb_plugin__ = self.name
+            self.routes.append((route, fn))
+            return fn
+        return deco
+
+    def model(self, cls):
+        cls.__pyweb_plugin__ = self.name
+        self.models.append(cls)
+        return cls
+
+    def browser_binding(self, name, js):
+        """Declare a JS global the plugin's browser code needs."""
+        self.browser_bindings[name] = js
+        return js
+
+    def on_build(self, fn):
+        """Register a ``fn(manifest, out_dir)`` build step."""
+        self.build_steps.append(fn)
+        return fn
+
+    def describe(self) -> dict:
+        return {"name": self.name, "version": self.version,
+                "routes": [r for r, _ in self.routes],
+                "rpc": [f.__name__ for f in self.rpc],
+                "models": [m.__name__ for m in self.models],
+                "bindings": dict(self.browser_bindings),
+                "config": {k: ("***" if "secret" in k.lower() or
+                               "key" in k.lower() else v)
+                           for k, v in self.config.items()}}
+
+    def __repr__(self):
+        return f"Plugin({self.name!r}, version={self.version!r})"
+
+
+class Registry:
+    """All plugins attached to an app; runs build steps in order."""
+
+    def __init__(self):
+        self._plugins: dict[str, Plugin] = {}
+
+    def add(self, plugin: Plugin):
+        if plugin.name in self._plugins:
+            raise ValueError(f"duplicate plugin {plugin.name!r}")
+        self._plugins[plugin.name] = plugin
+        return plugin
+
+    def get(self, name) -> Plugin:
+        return self._plugins[name]
+
+    def run_build_steps(self, manifest: dict, out_dir: str):
+        for plugin in self._plugins.values():
+            for step in plugin.build_steps:
+                step(manifest, out_dir)
+
+    def describe(self):
+        return {name: p.describe() for name, p in self._plugins.items()}

pyweb/realtime.py

@@ -0,0 +1,189 @@
+"""Realtime: channels/rooms, pub-sub fanout, presence, live-query bus."""
+
+from __future__ import annotations
+
+import threading
+
+
+class Channel:
+    def __init__(self, name):
+        self.name = name
+        self._subs: list = []
+        self._presence: dict[str, dict] = {}
+        self._lock = threading.Lock()
+
+    def subscribe(self, fn):
+        with self._lock:
+            self._subs.append(fn)
+        return lambda: self.unsubscribe(fn)
+
+    def unsubscribe(self, fn):
+        with self._lock:
+            if fn in self._subs:
+                self._subs.remove(fn)
+
+    def publish(self, message):
+        with self._lock:
+            subs = list(self._subs)
+        for sub in subs:
+            sub(message)
+        return len(subs)
+
+    def join(self, client_id, info=None):
+        with self._lock:
+            self._presence[client_id] = info or {}
+            return len(self._presence)
+
+    def leave(self, client_id):
+        with self._lock:
+            self._presence.pop(client_id, None)
+
+    def members(self):
+        with self._lock:
+            return dict(self._presence)
+
+
+class Bus:
+    def __init__(self):
+        self.channels: dict[str, Channel] = {}
+        self._lock = threading.Lock()
+        self._seq = 0
+        self._log: dict[str, list[tuple[int, object]]] = {}
+
+    def channel(self, name):
+        with self._lock:
+            if name not in self.channels:
+                self.channels[name] = Channel(name)
+            return self.channels[name]
+
+    def publish(self, channel_name, message):
+        with self._lock:
+            self._seq += 1
+            entry = (self._seq, message)
+            self._log.setdefault(channel_name, []).append(entry)
+            self._log[channel_name] = self._log[channel_name][-100:]
+        return self.channel(channel_name).publish(message)
+
+    def since(self, channel_name, last_id=0, limit=50):
+        """Messages on a channel after last_id (poll fallback)."""
+        with self._lock:
+            entries = [e for e in self._log.get(channel_name, []) if e[0] > last_id]
+        return entries[:limit]
+
+    def notify_table(self, table, row=None):
+        """Fanout for live DB queries watching a table."""
+        return self.publish(f"db:{table}", {"table": table, "row": row})
+
+
+def sse_format(seq, channel_name, message):
+    """One SSE frame: id/event/data lines. Client filters by event name."""
+    import json as _json
+    data = message if isinstance(message, str) else _json.dumps(message)
+    return f"id: {seq}\nevent: {channel_name}\ndata: {data}\n\n"
+
+
+_default_bus = Bus()
+
+
+def realtime(fn=None, *, channel=None):
+    def deco(f):
+        f.__pyweb_realtime__ = channel or f.__name__
+        return f
+    return deco(fn) if fn else deco
+
+
+class RedisBus(Bus):
+    """Cross-process fanout over Redis pub/sub + streams.
+
+    Local subscribers fire synchronously (same API as :class:`Bus`);
+    every publish is also ``XADD``-ed to a per-channel stream
+    (``pyweb:stream:<channel>``) so other processes/hosts can catch up
+    via ``since()``, and ``PUBLISH``-ed for live wakeups. ``since()``
+    merges the local log with the Redis stream. Without ``redis``
+    installed (or when the server is unreachable) it degrades to the
+    in-memory :class:`Bus` instead of raising at import time; the
+    error surfaces on first publish.
+
+    Why both stream + pubsub: streams give durable history/resume,
+    pubsub gives low-latency wakeups without polling. Alternatives
+    considered: Postgres LISTEN/NOTIFY (no history), bare pubsub
+    (no resume after disconnect).
+    """
+
+    def __init__(self, url="redis://localhost:6379/0", client=None,
+                 prefix="pyweb:"):
+        super().__init__()
+        self._prefix = prefix
+        if client is not None:
+            self._r = client
+        else:
+            try:
+                import redis
+            except ImportError as e:
+                raise RuntimeError(
+                    "RedisBus requires the 'redis' package: "
+                    "pip install redis") from e
+            self._r = redis.Redis.from_url(url)
+        self._broken = None
+
+    def _stream_key(self, channel_name):
+        return f"{self._prefix}stream:{channel_name}"
+
+    def _pub_key(self, channel_name):
+        return f"{self._prefix}live:{channel_name}"
+
+    def _seq_key(self, channel_name):
+        return f"{self._prefix}seq:{channel_name}"
+
+    def publish(self, channel_name, message):
+        """Publish to local subscribers and to Redis.
+
+        Sequence numbers come from a per-channel Redis counter and double
+        as stream IDs (``<seq>-1``), so every process agrees on ids and
+        ``since(last_id)`` resumes exactly where a client left off.
+        """
+        import json as _json
+        if self._broken:
+            return super().publish(channel_name, message)
+        try:
+            body = message if isinstance(message, str) else _json.dumps(message)
+            seq = int(self._r.incr(self._seq_key(channel_name)))
+            self._r.xadd(self._stream_key(channel_name), {"body": body},
+                         id=f"{seq}-1", maxlen=1000, approximate=True)
+            self._r.publish(self._pub_key(channel_name), body)
+        except Exception as exc:  # noqa: BLE001 — degrade, don't crash app
+            self._broken = exc
+            return super().publish(channel_name, message)
+        with self._lock:
+            self._seq = max(self._seq, seq)
+            log = self._log.setdefault(channel_name, [])
+            log.append((seq, message))
+            self._log[channel_name] = log[-100:]
+        return self.channel(channel_name).publish(message)
+
+    def since(self, channel_name, last_id=0, limit=50):
+        """Messages after ``last_id`` from the shared Redis stream."""
+        if self._broken:
+            return super().since(channel_name, last_id, limit)
+        try:
+            import json as _json
+            entries = self._r.xrange(self._stream_key(channel_name),
+                                     min=f"({int(last_id)}-1", max="+", count=limit)
+            out = []
+            for seq_raw, fields in entries:
+                sid = seq_raw.decode() if isinstance(seq_raw, bytes) else seq_raw
+                seq = int(sid.split("-")[0])
+                raw = fields.get(b"body", fields.get("body", b""))
+                body = raw.decode() if isinstance(raw, bytes) else raw
+                try:
+                    out.append((seq, _json.loads(body)))
+                except (ValueError, TypeError):
+                    out.append((seq, body))
+            return out
+        except Exception as exc:  # noqa: BLE001
+            self._broken = exc
+            return super().since(channel_name, last_id, limit)
+
+    def history(self, channel_name, limit=50):
+        """Newest-first convenience wrapper used by chat/presence UIs."""
+        return list(reversed(self.since(channel_name, 0, limit)))