errdown 0.1.0a0__py3-none-any.whl

errdown/__init__.py

@@ -0,0 +1,10 @@
+"""errdown: Cloudflare-compatible structured errors (RFC 9457) for every HTTP error an agent hits.
+
+Pre-release (alpha). Zero dependencies. `normalize()` never raises.
+"""
+from ._decide import agent_accept_header, backoff, decide
+from ._normalize import normalize, sanitize
+from ._render import ordered, to_json, to_markdown
+
+__all__ = ["normalize", "to_markdown", "to_json", "ordered", "decide", "backoff", "agent_accept_header", "sanitize"]
+__version__ = "0.1.0a0"

errdown/_decide.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import random as _random
+from typing import Any, Callable, Dict, Optional
+
+_ESCALATE = {"challenge", "access_denied", "legal", "auth_required"}
+
+
+def decide(p: Dict[str, Any]) -> Dict[str, Any]:
+    """Cloudflare's recommended control flow: retryable -> wait; owner action -> escalate; else fail fast."""
+    cat = p.get("error_category")
+    if cat == "challenge":
+        return {"action": "escalate", "reason": "challenge"}
+    if p.get("retryable"):
+        ra = p.get("retry_after")
+        return {"action": "retry", "after_seconds": 5 if ra is None else ra}
+    if p.get("owner_action_required"):
+        return {"action": "escalate", "reason": "owner_action_required"}
+    if cat in _ESCALATE:
+        return {"action": "escalate", "reason": cat}
+    return {"action": "fail", "reason": p.get("error_name")}
+
+
+def backoff(attempt: int, *, base: float = 1, max: float = 60, min: float = 0,
+            random: Optional[Callable[[], float]] = None) -> float:
+    """Exponential backoff with full jitter. attempt starts at 0. Honors a server-given minimum."""
+    rand = random or _random.random
+    ceiling = _min(max, base * 2 ** _max(0, attempt))
+    return _max(min, rand() * ceiling)
+
+
+_min, _max = min, max  # keyword args above shadow the builtins inside backoff()
+
+
+def agent_accept_header(mode: str = "markdown") -> str:
+    """The Accept header Cloudflare recommends for agents."""
+    return "application/json, */*" if mode == "json" else "text/markdown, */*"

errdown/_fingerprints.py

@@ -0,0 +1,130 @@
+"""Port of packages/js/src/fingerprints.ts. Keep in the same order; JS `$` is written `\\Z`."""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+I = re.I
+
+
+def _fp(id: str, source: str, confidence: float, *, status: Optional[List[int]] = None,
+        header: Optional[tuple] = None, body: Optional[List[Any]] = None, **over: Any) -> Dict[str, Any]:
+    return {"id": id, "source": source, "confidence": confidence, "status": status,
+            "header": (header[0], re.compile(header[1], header[2] if len(header) > 2 else 0)) if header else None,
+            "body": [re.compile(b) if isinstance(b, str) else re.compile(*b) for b in body] if body else None,
+            **over}
+
+
+CHALLENGES: List[Dict[str, Any]] = [
+    _fp("cloudflare_challenge", "cloudflare", 0.95, header=("cf-mitigated", r"challenge", I),
+        error_name="cloudflare_challenge", title="Bot verification required"),
+    _fp("cloudflare_challenge_page", "cloudflare", 0.9,
+        body=[(r"<title>Just a moment\.\.\.</title>|challenges\.cloudflare\.com|cf-chl-|_cf_chl_opt", I)],
+        error_name="cloudflare_challenge", title="Bot verification required"),
+    _fp("recaptcha", "unknown", 0.85,
+        body=[(r"google\.com/recaptcha|g-recaptcha", I), (r"captcha|verify you are human|unusual traffic", I)],
+        error_name="recaptcha_challenge", title="CAPTCHA required"),
+    _fp("hcaptcha", "unknown", 0.85, body=[(r"hcaptcha\.com|h-captcha", I)],
+        error_name="hcaptcha_challenge", title="CAPTCHA required"),
+    _fp("aws_waf_captcha", "aws-cloudfront", 0.9, header=("x-amzn-waf-action", r"captcha|challenge", I),
+        error_name="aws_waf_challenge", title="Bot verification required"),
+    _fp("datadome", "unknown", 0.85, header=("x-datadome", r"."),
+        body=[(r"captcha-delivery\.com|datadome", I)],
+        error_name="datadome_challenge", title="Bot verification required"),
+    _fp("perimeterx", "unknown", 0.85, body=[(r"px-captcha|perimeterx|_pxCaptcha", I)],
+        error_name="perimeterx_challenge", title="Bot verification required"),
+    _fp("indeed_bot_detection", "unknown", 0.85, body=[(r"from=bot-detection", I)],
+        error_name="bot_detection_redirect", title="Bot verification required"),
+    _fp("linkedin_999", "linkedin", 0.85, status=[999], header=("x-li-fabric", r"."),
+        error_name="linkedin_bot_block", title="Blocked as automated traffic"),
+    _fp("network_security_block", "unknown", 0.85, status=[403], body=[(r"blocked by network security", I)],
+        category="access_denied", error_name="network_security_block", title="Blocked by network security"),
+    _fp("akamai_bot", "akamai", 0.8, status=[403],
+        body=[(r"<title>Access Denied</title>", I), (r"Reference #[0-9]+\.[0-9a-f]+", I)],
+        category="access_denied", error_name="akamai_access_denied", title="Access denied"),
+]
+
+PAGES: List[Dict[str, Any]] = [
+    _fp("cloudflare_blocked", "cloudflare", 0.9,
+        body=[(r"cf-error-details", I), (r"Sorry, you have been blocked", I)],
+        category="access_denied", error_name="cloudflare_blocked", title="Blocked by the site's firewall",
+        retryable=False, owner_action_required=False,
+        detail="The site's Cloudflare firewall blocked this request."),
+    _fp("cloudflare_legacy", "cloudflare", 0.9, body=[(r"cf-error-details|cf-wrapper|Cloudflare Ray ID", I)]),
+    _fp("nginx_default", "nginx", 0.9, body=[(r"<center>nginx(/[0-9.]+)?</center>", I)]),
+    _fp("apache_default", "apache", 0.9, body=[(r"<address>Apache(/[0-9.]+)?[^<]*Server at", I)]),
+    _fp("apache_header", "apache", 0.7, header=("server", r"^Apache", I),
+        body=[(r"<title>[0-9]{3} [^<]+</title>", I)]),
+    _fp("caddy", "caddy", 0.75, header=("server", r"^Caddy", I)),
+    _fp("envoy_upstream", "envoy", 0.9,
+        body=[(r"upstream connect error or disconnect/reset before headers|no healthy upstream", I)],
+        category="upstream_unavailable", error_name="envoy_upstream_unavailable",
+        title="Upstream unavailable", retryable=True),
+    _fp("envoy_timeout", "envoy", 0.9, body=[r"^upstream request timeout\s*\Z"],
+        category="upstream_unavailable", error_name="envoy_upstream_timeout",
+        title="Upstream timeout", retryable=True),
+    _fp("envoy_empty", "envoy", 0.75, header=("server", r"^envoy\Z", I), body=[r"^\s*\Z"]),
+    _fp("traefik_404", "traefik", 0.8, body=[r"^404 page not found\s*\Z"]),
+    _fp("traefik", "traefik", 0.65,
+        body=[r"^(Bad Gateway|Gateway Timeout|Service Unavailable|Too Many Requests|Request Entity Too Large)\s*\Z"]),
+    _fp("aws_alb", "aws-alb", 0.9, header=("server", r"^awselb", I)),
+    _fp("aws_apigateway", "aws-apigateway", 0.85, header=("x-amzn-errortype", r".")),
+    _fp("aws_cloudfront", "aws-cloudfront", 0.9, body=[(r"Generated by cloudfront \(CloudFront\)", I)]),
+    _fp("vercel", "vercel", 0.85, header=("x-vercel-error", r".")),
+    _fp("vercel_hosted", "vercel", 0.6, header=("x-vercel-id", r".")),
+    _fp("github_pages", "github-pages", 0.85, status=[404], header=("server", r"^GitHub\.com\Z", I),
+        body=[(r"GitHub Pages|There isn't a GitHub Pages site here|Site not found", I)]),
+    _fp("netlify", "netlify", 0.8, header=("server", r"^Netlify", I)),
+    _fp("heroku_no_such_app", "heroku", 0.95, body=[(r"<title>No such app</title>", I)],
+        category="not_found", error_name="heroku_no_such_app", title="No such app",
+        retryable=False, detail="There is no Heroku app at this address."),
+    _fp("heroku_app_error", "heroku", 0.9,
+        body=[(r"herokucdn\.com/error-pages|Application error", I), (r"heroku", I)],
+        category="server_error", error_name="heroku_application_error",
+        title="Application error", retryable=True),
+    _fp("render_no_server", "render", 0.9, header=("x-render-routing", r"no-server", I),
+        category="not_found", error_name="render_no_server", title="No service at this address",
+        detail="There is no Render service at this address."),
+    _fp("render", "render", 0.75, header=("x-render-origin-server", r".")),
+    _fp("gfe_default", "google-frontend", 0.8,
+        body=[(r"<h1>Error: (Page )?Not Found</h1>", I), (r"The requested URL was not found on this server", I)]),
+    _fp("google_404", "google-frontend", 0.8, body=[r"<title>Error 404 \(Not Found\)!!1</title>"]),
+    _fp("gfe", "google-frontend", 0.8, header=("server", r"^(Google Frontend|GFE|gws)", I)),
+    _fp("express_default", "express", 0.85, header=("x-powered-by", r"^Express\Z", I),
+        body=[(r"<title>Error</title>", I), (r"<pre>", I)]),
+    _fp("werkzeug_default", "werkzeug", 0.85,
+        body=[(r"<title>[0-9]{3} [^<]+</title>\s*<h1>[^<]+</h1>\s*<p>", I),
+              (r"(If you entered the URL manually please check your spelling|The server encountered an internal error and was unable to complete your request|You don't have the permission to access the requested resource)", I)]),
+    _fp("django_default", "django", 0.85,
+        body=[(r"(<title>Server Error \(500\)</title>|The requested resource was not found on this server\.|<title>403 Forbidden</title>[\s\S]{0,200}<h1>403 Forbidden</h1>)", I)]),
+    _fp("tomcat_default", "tomcat", 0.9, body=[r"<title>HTTP Status [0-9]{3} – [^<]+</title>"]),
+    _fp("jetty_default", "jetty", 0.9, body=[r"<h2>HTTP ERROR [0-9]{3}"]),
+    _fp("python_http_server", "python-http-server", 0.8,
+        body=[r"<title>Error response</title>", r"Error code explanation:"]),
+    _fp("uvicorn_plain", "uvicorn", 0.7, header=("server", r"^uvicorn\Z", I),
+        body=[r"^(Internal Server Error|Not Found|Method Not Allowed)\s*\Z"]),
+    _fp("envoy_plain", "envoy", 0.75, header=("server", r"^envoy\Z", I), body=[r"^[A-Z][A-Za-z -]{2,40}\Z"]),
+    _fp("fastly", "fastly", 0.8, body=[(r"Varnish cache server|Fastly error", I)]),
+]
+
+
+def matches(fp: Dict[str, Any], status: int, h: Dict[str, str], body: str) -> bool:
+    if fp["status"] and status not in fp["status"]:
+        return False
+    if fp["header"]:
+        name, pat = fp["header"]
+        v = h.get(name)
+        if v is None or not pat.search(v):
+            return False
+    if fp["body"]:
+        for rx in fp["body"]:
+            if not rx.search(body):
+                return False
+    return bool(fp["header"] or fp["body"])
+
+
+def find_fingerprint(lst: List[Dict[str, Any]], status: int, h: Dict[str, str], body: str) -> Optional[Dict[str, Any]]:
+    for fp in lst:
+        if matches(fp, status, h, body):
+            return fp
+    return None

errdown/_headers.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, Optional
+
+from ._util import js_round
+
+HeaderMap = Dict[str, str]
+
+
+def to_header_map(h: Any) -> HeaderMap:
+    """Accepts dict, list of pairs, or anything with .items() (httpx/requests/aiohttp headers)."""
+    m: HeaderMap = {}
+    if not h:
+        return m
+
+    def put(k: Any, v: Any) -> None:
+        if not isinstance(k, str) or v is None:
+            return
+        m[k.lower()] = ", ".join(str(x) for x in v) if isinstance(v, (list, tuple)) else str(v)
+
+    try:
+        if hasattr(h, "multi_items"):  # httpx: keep repeated headers
+            seen: Dict[str, list] = {}
+            for k, v in h.multi_items():
+                seen.setdefault(k.lower(), []).append(v)
+            for k, vs in seen.items():
+                put(k, vs if len(vs) > 1 else vs[0])
+        elif hasattr(h, "items"):
+            for k, v in h.items():
+                put(k, v)
+        else:
+            for pair in h:
+                if isinstance(pair, (list, tuple)) and len(pair) >= 2:
+                    put(pair[0], pair[1])
+    except Exception:
+        pass
+    return m
+
+
+_MAX_RETRY = 86400
+_DIGITS = re.compile(r"[0-9]+\Z")
+_NUM = re.compile(r"[0-9]+(\.[0-9]+)?\Z")
+
+
+def _clamp(n: float) -> int:
+    return max(0, min(_MAX_RETRY, js_round(n)))
+
+
+def _parse_date_ms(s: str) -> Optional[float]:
+    try:
+        dt = parsedate_to_datetime(s)
+    except Exception:
+        dt = None
+    if dt is None:
+        try:
+            dt = datetime.fromisoformat(s.replace("Z", "+00:00"))
+        except Exception:
+            return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.timestamp() * 1000
+
+
+def retry_after_from_headers(h: HeaderMap, now_ms: float) -> Optional[int]:
+    ra = (h.get("retry-after") or "").strip()
+    if ra:
+        if _DIGITS.match(ra):
+            return _clamp(int(ra))
+        t = _parse_date_ms(ra)
+        if t is not None:
+            return _clamp((t - now_ms) / 1000)
+    for name in ("ratelimit-reset", "x-ratelimit-reset", "x-rate-limit-reset"):
+        v = (h.get(name) or "").strip()
+        if v and _NUM.match(v):
+            n = float(v)
+            return _clamp(n - now_ms / 1000 if n > 1e9 else n)
+    return None

errdown/_normalize.py

@@ -0,0 +1,476 @@
+"""Port of packages/js/src/normalize.ts. Must produce identical output on every fixture."""
+from __future__ import annotations
+
+import re
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urlsplit
+
+from ._fingerprints import CHALLENGES, PAGES, find_fingerprint
+from ._headers import HeaderMap, retry_after_from_headers, to_header_map
+from ._status import classify_status, default_retry_after, guidance
+from ._util import is_num, js_parse, js_str, js_trim
+
+Problem = Dict[str, Any]
+
+MAX_BODY = 256 * 1024
+TYPE_BASE = "https://errdown.com/errors/"
+CF_DOCS = "https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/"
+
+_BODY_PAGES = [f for f in PAGES if f["body"]]
+_HEADER_PAGES = [f for f in PAGES if not f["body"]]
+
+
+def _body_to_str(body: Any) -> str:
+    try:
+        if body is None:
+            return ""
+        if isinstance(body, str):
+            return body[:MAX_BODY]
+        if isinstance(body, (bytes, bytearray, memoryview)):
+            return bytes(body[:MAX_BODY]).decode("utf-8-sig", errors="replace")
+        return ""
+    except Exception:
+        return ""
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
+
+
+def _parse_now(now: Any) -> Tuple[str, float]:
+    """Returns (timestamp string, now in ms). A string `now` is kept verbatim, as in TS."""
+    try:
+        if isinstance(now, datetime):
+            d = now if now.tzinfo else now.replace(tzinfo=timezone.utc)
+            return _iso(d), d.timestamp() * 1000
+        if isinstance(now, str) and now:
+            d = datetime.fromisoformat(now.replace("Z", "+00:00"))
+            if d.tzinfo is None:
+                d = d.replace(tzinfo=timezone.utc)
+            return now, d.timestamp() * 1000
+    except Exception:
+        pass
+    ms = time.time() * 1000
+    return _iso(datetime.fromtimestamp(ms / 1000, tz=timezone.utc)), ms
+
+
+def _host_of(url: Optional[str]) -> Optional[str]:
+    if not url:
+        return None
+    try:
+        u = urlsplit(url)
+        if not u.scheme or not u.hostname:
+            return None
+        host = u.hostname
+        if ":" in host:
+            host = f"[{host}]"
+        port = u.port
+        default = {"http": 80, "https": 443, "ws": 80, "wss": 443}.get(u.scheme.lower())
+        return f"{host}:{port}" if port is not None and port != default else host
+    except Exception:
+        return None
+
+
+_CTRL = re.compile("[\u0000-\u001f\u007f-\u009f

]+")
+_WS = re.compile(r"\s+")
+
+
+def sanitize(text: str, max_len: int = 200) -> str:
+    """Strip control chars/newlines and truncate, for quoting untrusted text (SPEC §7)."""
+    clean = js_trim(_WS.sub(" ", _CTRL.sub(" ", text)))
+    return clean[: max_len - 1] + "…" if len(clean) > max_len else clean
+
+
+def _try_json(body: str) -> Any:
+    t = body.lstrip()
+    if not t or t[0] not in "{[":
+        return _MISSING
+    try:
+        return js_parse(body)
+    except Exception:
+        return _MISSING
+
+
+_MISSING = object()
+
+# [category, error_name, title, owner_action_required?, retryable?]
+CF_CODES: Dict[int, tuple] = {
+    1000: ("dns", "dns_loop", "DNS points to prohibited IP", True, False),
+    1001: ("dns", "dns_resolution_error", "DNS resolution error", True),
+    1003: ("config", "direct_ip_access_not_allowed", "Direct IP access not allowed"),
+    1006: ("access_denied", "access_denied_ip_banned", "Access denied"),
+    1007: ("access_denied", "access_denied_ip_banned", "Access denied"),
+    1008: ("access_denied", "access_denied_ip_banned", "Access denied"),
+    1009: ("access_denied", "access_denied_country", "Access denied (country or region banned)"),
+    1010: ("access_denied", "access_denied_browser_signature", "Access denied (browser signature)"),
+    1012: ("access_denied", "access_denied", "Access denied"),
+    1014: ("config", "cname_cross_user_banned", "CNAME cross-user banned", True),
+    1015: ("rate_limit", "rate_limited", "You are being rate limited"),
+    1016: ("dns", "origin_dns_error", "Origin DNS error", True, False),
+    1020: ("access_denied", "access_denied", "Access denied (firewall rule)"),
+    1034: ("config", "edge_ip_restricted", "Edge IP restricted"),
+    520: ("upstream_unavailable", "origin_unknown_error", "Web server returned an unknown error", False, True),
+    521: ("upstream_unavailable", "origin_down", "Web server is down", False, True),
+    522: ("upstream_unavailable", "origin_connection_timed_out", "Connection timed out", False, True),
+    523: ("upstream_unavailable", "origin_unreachable", "Origin is unreachable", False, True),
+    524: ("upstream_unavailable", "origin_timeout", "A timeout occurred", False, True),
+    525: ("tls", "ssl_handshake_failed", "SSL handshake failed", True, False),
+    526: ("tls", "invalid_ssl_certificate", "Invalid SSL certificate", True, False),
+    1101: ("worker", "worker_threw_exception", "Worker threw exception", True, False),
+    1102: ("worker", "worker_exceeded_resource_limits", "Worker exceeded resource limits", True),
+}
+
+# ---------- Cloudflare Markdown ----------
+
+_FM = re.compile(r"^?---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)\Z")
+_KV = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*):\s?(.*)\Z", re.S)
+_NUMERIC = re.compile(r"-?[0-9]+(\.[0-9]+)?\Z")
+_TITLE = re.compile(r"^#\s+(.+)$", re.M)
+_FOOTER = re.compile(r"\n---[ \t]*\r?\n([\s\S]*?)\s*\Z")
+
+
+def _parse_scalar(v: str) -> Any:
+    s = js_trim(v)
+    if s == "true":
+        return True
+    if s == "false":
+        return False
+    if s in ("null", "~", ""):
+        return _MISSING
+    if _NUMERIC.match(s):
+        return float(s) if "." in s else int(s)
+    if len(s) >= 2 and ((s[0] == '"' and s[-1] == '"') or (s[0] == "'" and s[-1] == "'")):
+        return s[1:-1]
+    if s in ('"', "'"):
+        return s
+    return s
+
+
+def _section(rest: str, name: str) -> Optional[str]:
+    rx = re.compile(r"^##\s+" + name + r"\s*$([\s\S]*?)(?=^##\s|^---\s*$|\Z)", re.M | re.I)
+    m = rx.search(rest)
+    return js_trim(m.group(1)) if m else None
+
+
+def _parse_cf_markdown(body: str) -> Optional[Dict[str, Any]]:
+    m = _FM.match(body)
+    if not m:
+        return None
+    fm: Dict[str, Any] = {}
+    for line in re.split(r"\r?\n", m.group(1)):
+        kv = _KV.match(line)
+        if kv:
+            v = _parse_scalar(kv.group(2))
+            if v is not _MISSING:
+                fm[kv.group(1)] = v
+    if "error_code" not in fm:
+        return None
+    rest = m.group(2)
+    t = _TITLE.search(rest)
+    title = js_trim(t.group(1)) if t else None
+    if title:
+        fm["title"] = title
+    detail = _section(rest, "What Happened")
+    if detail:
+        fm["detail"] = detail
+    todo = _section(rest, "What You Should Do")
+    if todo:
+        fm["what_you_should_do"] = todo
+    f = _FOOTER.search(rest)
+    footer = js_trim(f.group(1)) if f else None
+    if footer:
+        fm["footer"] = footer
+    return fm
+
+
+# ---------- Assembly ----------
+
+class _Ctx:
+    __slots__ = ("status", "h", "url", "timestamp", "now_ms")
+
+    def __init__(self, status: int, h: HeaderMap, url: Optional[str], timestamp: str, now_ms: float):
+        self.status, self.h, self.url, self.timestamp, self.now_ms = status, h, url, timestamp, now_ms
+
+
+def _nn(v: Any, d: Any) -> Any:
+    """JS `v ?? d`."""
+    return d if v is None else v
+
+
+def _finish(p: Dict[str, Any], ctx: _Ctx) -> Problem:
+    status = p["status"]
+    base = classify_status(status)
+    category = _nn(p.get("error_category"), base["category"])
+    retryable = _nn(p.get("retryable"), base["retryable"])
+    owner = _nn(p.get("owner_action_required"), base["owner_action_required"])
+    retry_after = p.get("retry_after")
+    if retry_after is None and retryable:
+        retry_after = _nn(retry_after_from_headers(ctx.h, ctx.now_ms), default_retry_after(status))
+    error_name = _nn(p.get("error_name"), base["error_name"])
+
+    out: Dict[str, Any] = {
+        "type": _nn(p.get("type"), TYPE_BASE + js_str(error_name)),
+        "title": _nn(p.get("title"), base["title"]),
+        "status": status,
+        "detail": _nn(p.get("detail"), f"The server returned HTTP {status}."),
+        "instance": _nn(p.get("instance"), ctx.url),
+        "error_code": _nn(p.get("error_code"), status),
+        "error_name": error_name,
+        "error_category": category,
+        "retryable": retryable,
+        "retry_after": retry_after,
+        "owner_action_required": owner,
+        "what_you_should_do": _nn(p.get("what_you_should_do"), guidance(category, bool(retryable), bool(owner), retry_after)),
+        "timestamp": _nn(p.get("timestamp"), ctx.timestamp),
+        "zone": _nn(p.get("zone"), _host_of(ctx.url)),
+        "footer": p.get("footer"),
+        "ray_id": p.get("ray_id"),
+        "cloudflare_error": p.get("cloudflare_error"),
+        "errdown_synthesized": _nn(p.get("errdown_synthesized"), True),
+        "errdown_source": _nn(p.get("errdown_source"), "unknown"),
+        "errdown_confidence": _nn(p.get("errdown_confidence"), 0.5),
+    }
+    for k, v in p.items():
+        if k not in out:
+            out[k] = v
+    # TS deletes `undefined` core members; extension members are kept as-is (ordered() drops nulls).
+    return {k: v for k, v in out.items() if not (k in _CORE and v is None)}
+
+
+_CORE = {"type", "title", "status", "detail", "instance", "error_code", "error_name", "error_category",
+         "retryable", "retry_after", "owner_action_required", "what_you_should_do", "timestamp", "zone",
+         "footer", "ray_id", "cloudflare_error", "errdown_synthesized", "errdown_source", "errdown_confidence"}
+
+_RAY_HDR = re.compile(r"[0-9a-f]{8,32}\Z", re.I)
+_RAY_BODY = re.compile(r"Ray ID:?\s*(?:<[^>]{0,80}>\s*)?([0-9a-f]{16})", re.I)
+
+
+def _ray_id(ctx: _Ctx, body: str = "") -> Optional[str]:
+    hdr = ctx.h.get("cf-ray")
+    if hdr is not None:
+        first = js_trim(hdr).split("-")[0]
+        if first and _RAY_HDR.match(first):
+            return first.lower()
+    m = _RAY_BODY.search(body)
+    return m.group(1) if m else None
+
+
+def _cf_meta(ctx: _Ctx, body: str = "") -> Dict[str, Any]:
+    ray = _ray_id(ctx, body)
+    meta: Dict[str, Any] = {"errdown_source": "cloudflare", "cloudflare_error": True}
+    if ray:
+        meta["ray_id"] = ray
+    return meta
+
+
+def _from_fp(fp: Dict[str, Any], ctx: _Ctx, challenge: bool, body: str = "") -> Problem:
+    base = classify_status(ctx.status)
+    category = "challenge" if challenge else _nn(fp.get("category"), base["category"])
+    label = "" if fp["source"] == "unknown" else fp["source"].replace("-", "_") + "_"
+    error_name = _nn(fp.get("error_name"), label + base["error_name"])
+    if challenge:
+        what = "a bot-verification challenge page"
+    elif fp["source"] == "unknown":
+        what = "a block page"
+    else:
+        what = f"an error page from {fp['source']}"
+    p: Dict[str, Any] = {
+        "status": ctx.status,
+        "title": _nn(fp.get("title"), base["title"]),
+        "detail": _nn(fp.get("detail"), f"The server returned HTTP {ctx.status} with {what}."),
+        "error_name": error_name,
+        "error_category": category,
+        "retryable": False if challenge else _nn(fp.get("retryable"), base["retryable"]),
+        "owner_action_required": _nn(fp.get("owner_action_required"), base["owner_action_required"]),
+        "errdown_source": fp["source"],
+        "errdown_confidence": fp["confidence"],
+    }
+    if fp["source"] == "cloudflare":
+        p.update(_cf_meta(ctx, body))
+    return _finish(p, ctx)
+
+
+def _str(v: Any) -> Optional[str]:
+    if isinstance(v, str) and js_trim(v):
+        return v
+    if is_num(v):
+        return js_str(v)
+    return None
+
+
+def _first(*vals: Optional[str]) -> Optional[str]:
+    for v in vals:
+        if v is not None:
+            return v
+    return None
+
+
+def _message_from_json(j: Any) -> Optional[Dict[str, Optional[str]]]:
+    if not isinstance(j, dict):
+        return None
+    j = {str(k).lower(): v for k, v in j.items()}
+    errors = j.get("errors")
+    if isinstance(errors, list) and errors:
+        e = errors[0]
+        if isinstance(e, dict):
+            ext = e.get("extensions") if isinstance(e.get("extensions"), dict) else {}
+            return {"message": _str(e.get("message")), "code": _first(_str(ext.get("code")), _str(e.get("code")))}
+        if isinstance(e, str):
+            return {"message": e, "code": None}
+    if isinstance(errors, str):
+        return {"message": errors, "code": None}
+    detail = j.get("detail")
+    if isinstance(detail, list) and detail and isinstance(detail[0], dict):
+        d0 = detail[0]
+        return {"message": _first(_str(d0.get("msg")), _str(d0.get("message"))), "code": _str(d0.get("type"))}
+    err = j.get("error")
+    if isinstance(err, str) and isinstance(j.get("error_description"), str):
+        return {"message": j["error_description"], "code": err}
+    if isinstance(err, dict):
+        return {"message": _first(_str(err.get("message")), _str(err.get("detail"))),
+                "code": _first(_str(err.get("code")), _str(err.get("type")))}
+    if isinstance(err, str):
+        return {"message": _first(_str(j.get("message")), err), "code": _str(j.get("code"))}
+    if _str(j.get("message")) or _str(detail):
+        return {"message": _first(_str(j.get("message")), _str(detail)), "code": _str(j.get("code"))}
+    return None
+
+
+_XML_HEAD = re.compile(r"^\s*(<\?xml[^>]{0,200}\?>\s*)?<(Error|ErrorResponse)[\s>]")
+
+
+def _message_from_xml(body: str) -> Optional[Dict[str, Optional[str]]]:
+    if not _XML_HEAD.search(body):
+        return None
+
+    def tag(t: str) -> Optional[str]:
+        m = re.search("<" + t + ">([^<]{1,500})</" + t + ">", body)
+        return js_trim(m.group(1)) if m else None
+
+    code, message = tag("Code"), tag("Message")
+    return {"code": code, "message": message} if (code or message) else None
+
+
+_XML_SOURCES = [
+    ("server", re.compile(r"^AmazonS3\Z", re.I), "aws-s3"),
+    ("server", re.compile(r"^UploadServer\Z", re.I), "google-cloud-storage"),
+    ("x-amzn-requestid", re.compile(r"."), "aws"),
+    ("x-ms-request-id", re.compile(r"."), "azure"),
+]
+_PLAIN_CF = re.compile(r"^\s*error code: (1[0-9]{3}|5[0-9]{2})\s*\Z")
+
+
+def normalize(status: int, headers: Any = None, body: Any = None, *, url: Optional[str] = None,
+              now: Any = None) -> Optional[Problem]:
+    """Convert an HTTP response into a Cloudflare-compatible Problem, or None if not an error.
+
+    Never raises. `body` may be str or bytes; `headers` a dict, list of pairs, or any object
+    with .items() (httpx, requests, aiohttp). `now` (datetime or ISO string) pins the timestamp.
+    """
+    try:
+        timestamp, now_ms = _parse_now(now)
+        st = status if isinstance(status, int) and not isinstance(status, bool) else 0
+        ctx = _Ctx(st, to_header_map(headers), url, timestamp, now_ms)
+    except Exception:
+        return None
+    try:
+        return _run(ctx, _body_to_str(body))
+    except Exception:
+        if ctx.status < 400:
+            return None
+        try:
+            return _finish({"status": ctx.status, "errdown_confidence": 0.3}, ctx)
+        except Exception:
+            return None
+
+
+def scan_window(body: str) -> str:
+    """Fingerprints only look at the head and tail of large bodies (SPEC §5)."""
+    return body[:32768] + "\n" + body[-8192:] if len(body) > 40960 else body
+
+
+def _run(ctx: _Ctx, full_body: str) -> Optional[Problem]:
+    status, h = ctx.status, ctx.h
+    body = scan_window(full_body)
+    is_error = 400 <= status <= 999
+
+    challenge = find_fingerprint(CHALLENGES, status, h, body)
+    if challenge and (is_error or challenge.get("category") != "access_denied"):
+        return _from_fp(challenge, ctx, challenge.get("category") != "access_denied", body)
+    if not is_error:
+        return None
+
+    ctype = h.get("content-type", "")
+    j = _try_json(full_body)
+
+    # 1. Structured pass-through.
+    if isinstance(j, dict) and ("problem+json" in ctype or ("type" in j and "status" in j) or "error_code" in j):
+        cf = is_num(j.get("error_code")) and ("ray_id" in j or "cf-error-type" in h)
+        p: Dict[str, Any] = {"errdown_synthesized": False, "errdown_source": "cloudflare" if cf else "origin",
+                             "errdown_confidence": 1}
+        if cf:
+            p["cloudflare_error"] = True
+        p.update(j)
+        p["status"] = j["status"] if is_num(j.get("status")) else status
+        return _finish(p, ctx)
+    md = _parse_cf_markdown(full_body) if ("markdown" in ctype or body.lstrip().startswith("---")) else None
+    if md:
+        cf = "ray_id" in md or "cf-error-type" in h
+        p = {"errdown_synthesized": False, "errdown_source": "cloudflare" if cf else "origin", "errdown_confidence": 1}
+        if cf:
+            p["cloudflare_error"] = True
+        p.update(md)
+        p["status"] = md["status"] if is_num(md.get("status")) else status
+        return _finish(p, ctx)
+
+    if "cf-error-type" in h:
+        p = {"status": status, **_cf_meta(ctx), "errdown_confidence": 0.85,
+             "detail": f"Cloudflare returned HTTP {status} ({sanitize(h.get('cf-error-type') or '', 40)})."}
+        return _finish(p, ctx)
+
+    plain = _PLAIN_CF.match(body)
+    if plain and re.search("cloudflare", h.get("server", ""), re.I):
+        code = int(plain.group(1))
+        known = CF_CODES.get(code)
+        p = {"status": status, **_cf_meta(ctx), "type": CF_DOCS, "error_code": code,
+             "error_name": known[1] if known else f"cloudflare_{code}"}
+        if known:
+            p["error_category"] = known[0]
+            p["title"] = f"Error {code}: {known[2]}"
+        else:
+            p["title"] = f"Cloudflare error {code}"
+        if known and len(known) > 3:
+            p["owner_action_required"] = known[3]
+        if known and len(known) > 4:
+            p["retryable"] = known[4]
+        if code < 1000 and not known:
+            p["error_category"] = classify_status(code)["category"]
+        p["detail"] = f"Cloudflare returned error {code}{f' ({known[2]})' if known else ''} with HTTP {status}."
+        p["errdown_confidence"] = 0.9 if known else 0.75
+        return _finish(p, ctx)
+
+    fp = find_fingerprint(_BODY_PAGES, status, h, body)
+    if fp:
+        return _from_fp(fp, ctx, False, body)
+    hfp = find_fingerprint(_HEADER_PAGES, status, h, body)
+
+    m = _message_from_json(j) if j is not _MISSING else _message_from_xml(full_body)
+    xml_source = None
+    if j is _MISSING:
+        for name, rx, src in _XML_SOURCES:
+            if rx.search(h.get(name, "")):
+                xml_source = src
+                break
+    if m and (m.get("message") or m.get("code")):
+        said = (f" The server's message (untrusted, quoted): \"{sanitize(m['message']).replace(chr(34), chr(39))}\""
+                if m.get("message") else "")
+        code_s = f" (code: {sanitize(m['code'], 60)})" if m.get("code") else ""
+        return _finish({"status": status, "detail": f"The server returned HTTP {status}{code_s}.{said}",
+                        "errdown_source": xml_source or (hfp["source"] if hfp else "origin"),
+                        "errdown_confidence": 0.7}, ctx)
+    if hfp:
+        return _from_fp(hfp, ctx, False, body)
+
+    return _finish({"status": status, "errdown_confidence": 0.3 if status >= 600 else 0.5}, ctx)

errdown/_render.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict
+
+from ._util import is_num, js_str, js_stringify
+
+_ORDER = [
+    "type", "title", "status", "detail", "instance", "error_code", "error_name", "error_category",
+    "ray_id", "timestamp", "zone", "cloudflare_error", "retryable", "retry_after", "owner_action_required",
+    "what_you_should_do", "footer", "errdown_synthesized", "errdown_source", "errdown_confidence",
+]
+_FM_KEYS = [
+    "error_code", "error_name", "error_category", "status", "ray_id", "timestamp", "zone",
+    "cloudflare_error", "retryable", "retry_after", "owner_action_required",
+    "errdown_synthesized", "errdown_source", "errdown_confidence",
+]
+
+
+def ordered(p: Dict[str, Any]) -> Dict[str, Any]:
+    """Ordered copy (Cloudflare's member order) with None members removed."""
+    out = {k: p[k] for k in _ORDER if p.get(k) is not None}
+    for k, v in p.items():
+        if k not in out and v is not None:
+            out[k] = v
+    return out
+
+
+def to_json(p: Dict[str, Any], indent: Any = None) -> str:
+    return js_stringify(ordered(p), indent)
+
+
+_SAFE = re.compile(r"[A-Za-z0-9_.:/+@-][A-Za-z0-9_ .:/+@-]*\Z")
+_RESERVED = re.compile(r"(true|false|null|~|-?[0-9]+(\.[0-9]+)?)\Z")
+
+
+def _yaml_scalar(v: Any) -> str:
+    if is_num(v) or isinstance(v, bool):
+        return js_str(v)
+    s = re.sub(r"[\r\n]+", " ", js_str(v))
+    if _SAFE.match(s) and not _RESERVED.match(s) and not re.search(r":\s", s):
+        return s
+    return json.dumps(s, ensure_ascii=False)
+
+
+def to_markdown(p: Dict[str, Any]) -> str:
+    fm = [f"{k}: {_yaml_scalar(p[k])}" for k in _FM_KEYS if p.get(k) is not None]
+    md = (f"---\n" + "\n".join(fm) + f"\n---\n\n# {js_str(p.get('title'))}\n\n## What Happened\n\n"
+          f"{js_str(p.get('detail'))}\n\n## What You Should Do\n\n{js_str(p.get('what_you_should_do'))}\n")
+    if p.get("footer"):
+        md += f"\n---\n\n{js_str(p['footer'])}\n"
+    return md

errdown/_status.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def _c(category: str, error_name: str, title: str, retryable: bool = False, owner: bool = False) -> Dict[str, Any]:
+    return {"category": category, "error_name": error_name, "title": title,
+            "retryable": retryable, "owner_action_required": owner}
+
+
+_TABLE: Dict[int, Dict[str, Any]] = {
+    400: _c("bad_request", "bad_request", "Bad request"),
+    401: _c("auth_required", "auth_required", "Authentication required"),
+    403: _c("access_denied", "forbidden", "Access denied"),
+    404: _c("not_found", "not_found", "Not found"),
+    405: _c("bad_request", "method_not_allowed", "Method not allowed"),
+    406: _c("bad_request", "not_acceptable", "Not acceptable"),
+    407: _c("auth_required", "proxy_auth_required", "Proxy authentication required"),
+    408: _c("upstream_unavailable", "request_timeout", "Request timeout", True),
+    409: _c("bad_request", "conflict", "Conflict"),
+    410: _c("not_found", "gone", "Gone"),
+    411: _c("bad_request", "length_required", "Length required"),
+    412: _c("bad_request", "precondition_failed", "Precondition failed"),
+    413: _c("bad_request", "payload_too_large", "Payload too large"),
+    414: _c("bad_request", "uri_too_long", "URI too long"),
+    415: _c("bad_request", "unsupported_media_type", "Unsupported media type"),
+    422: _c("bad_request", "unprocessable_content", "Unprocessable content"),
+    429: _c("rate_limit", "rate_limited", "Rate limited", True),
+    431: _c("bad_request", "request_header_fields_too_large", "Request header fields too large"),
+    451: _c("legal", "unavailable_for_legal_reasons", "Unavailable for legal reasons"),
+    500: _c("server_error", "internal_server_error", "Internal server error", True),
+    501: _c("unsupported", "not_implemented", "Not implemented"),
+    502: _c("upstream_unavailable", "bad_gateway", "Bad gateway", True),
+    503: _c("upstream_unavailable", "service_unavailable", "Service unavailable", True),
+    504: _c("upstream_unavailable", "gateway_timeout", "Gateway timeout", True),
+}
+
+
+def classify_status(status: int) -> Dict[str, Any]:
+    hit = _TABLE.get(status)
+    if hit:
+        return dict(hit)
+    if status >= 600:
+        return _c("bad_request", "nonstandard_status", "Nonstandard error status")
+    if status >= 500:
+        return _c("server_error", "server_error", "Server error", True)
+    return _c("bad_request", "client_error", "Client error")
+
+
+def default_retry_after(status: int) -> int:
+    return 60 if status == 429 else 5
+
+
+def guidance(category: str, retryable: bool, owner: bool, retry_after: Optional[Any]) -> str:
+    if category == "challenge":
+        return ("Stop. This site requires a human to complete a check (CAPTCHA or bot verification). "
+                "Do not retry automatically and do not attempt to bypass it. Ask the user to open the page in a browser.")
+    if owner:
+        return "This needs the site owner to fix. Do not retry. Report the error to the user or the site operator."
+    if retryable:
+        n = retry_after if retry_after is not None else 5
+        from ._util import js_str
+        return (f"Wait {js_str(n)} seconds, then retry with exponential backoff. "
+                "Stop after a few attempts and report the error if it persists.")
+    return {
+        "access_denied": "Do not retry. Access was intentionally blocked. Tell the user; they may need to request access from the site owner.",
+        "legal": "Do not retry. This content is unavailable in this location for legal reasons.",
+        "auth_required": "Do not retry without credentials. Ask the user to authenticate or provide credentials.",
+        "not_found": "Do not retry. Check the URL for mistakes, or search for the resource elsewhere.",
+        "bad_request": "Do not retry the same request. Check the URL, method, headers and body, then fix the request.",
+        "unsupported": "Do not retry. The server does not support this request.",
+    }.get(category, "Do not retry the same request. Report the error to the user.")

errdown/_util.py

@@ -0,0 +1,64 @@
+"""Helpers that reproduce JavaScript semantics so output matches the TypeScript reference exactly."""
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+
+def is_num(v: Any) -> bool:
+    """JS `typeof v === "number"` (bool is not a number)."""
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def js_num(v: Any) -> Any:
+    """Integral floats become ints (JS has one number type: 1.0 prints as 1)."""
+    if isinstance(v, float) and v.is_integer() and math.isfinite(v):
+        return int(v)
+    return v
+
+
+def js_str(v: Any) -> str:
+    """JS String(v) for numbers, booleans and strings."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float):
+        if v.is_integer() and math.isfinite(v):
+            return str(int(v))
+        r = repr(v)
+        return r
+    return str(v)
+
+
+def js_round(x: float) -> int:
+    """JS Math.round: halves round toward +infinity."""
+    return int(math.floor(x + 0.5))
+
+
+def _plain(v: Any) -> Any:
+    if isinstance(v, dict):
+        return {k: _plain(x) for k, x in v.items()}
+    if isinstance(v, list):
+        return [_plain(x) for x in v]
+    return js_num(v)
+
+
+def js_stringify(v: Any, indent: Any = None) -> str:
+    """JSON.stringify: compact separators, no ASCII escaping, integral floats as ints."""
+    if indent:
+        return json.dumps(_plain(v), ensure_ascii=False, indent=indent)
+    return json.dumps(_plain(v), ensure_ascii=False, separators=(",", ":"))
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(name)
+
+
+def js_parse(s: str) -> Any:
+    """JSON.parse: rejects NaN/Infinity, which Python's json accepts."""
+    return json.loads(s, parse_constant=_reject_constant)
+
+
+def js_trim(s: str) -> str:
+    # JS trim() strips whitespace + line terminators incl. U+FEFF; Python strip() lacks U+FEFF.
+    return s.strip().strip("").strip()

errdown-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: errdown
+Version: 0.1.0a0
+Summary: Cloudflare-compatible structured errors (RFC 9457) for every HTTP error your agent hits.
+Project-URL: Homepage, https://errdown.com
+Project-URL: Repository, https://github.com/ArtZab0/errdown
+Author: Artem Zabarov
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-agents,cloudflare,errors,http,llm,mcp,problem-details,rfc9457
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# errdown
+
+> **Pre-release (alpha).** API and output may change.
+
+Cloudflare-compatible structured errors (RFC 9457 Problem Details) for every HTTP error your
+agent hits: nginx, AWS, Vercel, framework defaults, JSON/XML API errors, bot challenges.
+Zero dependencies, pure function, never throws. Independent project, not affiliated with Cloudflare.
+
+```python
+import httpx
+from errdown import normalize, to_markdown, decide, agent_accept_header
+
+res = httpx.get(url, headers={"accept": agent_accept_header()})
+if res.is_error:
+    problem = normalize(res.status_code, res.headers, res.content, url=url)
+    if problem:
+        to_markdown(problem)  # Cloudflare-format Markdown for the model
+        decide(problem)       # {"action": "retry", "after_seconds": 5} | escalate | fail
+```
+
+Spec and conformance fixtures: https://github.com/ArtZab0/errdown
+
+License: Apache-2.0. Spec and fixtures: CC0 (captured third-party responses excepted).

errdown-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,14 @@
+errdown/__init__.py,sha256=etZd_UyhaGoDNjs68e8yz8DfahLI3kFwxtbOhBMNpQg,467
+errdown/_decide.py,sha256=NVtxg-V7nOiDk_h-QZw4_8nNGpC7NmT7uZOBJyfGs9I,1512
+errdown/_fingerprints.py,sha256=1bjf9ljg7qus5qA26_CkFW_ft8-MpBQq7WqDiX2hXZo,8485
+errdown/_headers.py,sha256=VVXB_VzW_syctLSNakNCkzZih_sw5BmNTZ2_5GfYG68,2353
+errdown/_normalize.py,sha256=9w5O3iUoHPAk3oLDWrjM42izQaMXN3WLFbgtg7pqLAE,19311
+errdown/_render.py,sha256=j3Zvuntuti1r6TfrO2FZXDUFJNAAX-8ckWS3rcQ4q5w,1952
+errdown/_status.py,sha256=i3ojcm_runtzEjslWp3IDmd-ubvLtugHD4fqOK2BNEg,4077
+errdown/_util.py,sha256=wTuzAWuLGrAX48a7rPgo8DdI_aG4DTGsLHxKGX5YtL0,1903
+errdown/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+errdown-0.1.0a0.dist-info/METADATA,sha256=RGLfBemC5nOe1FgvRw3OJ3wZB3kBbbe9OVfWDZObu3U,1551
+errdown-0.1.0a0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+errdown-0.1.0a0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+errdown-0.1.0a0.dist-info/licenses/NOTICE,sha256=_DDDFjHvuxj1Z9rYTR3wCAoDlWx-Xg1EFKPjBSBMqxY,274
+errdown-0.1.0a0.dist-info/RECORD,,

errdown-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

errdown-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

errdown-0.1.0a0.dist-info/licenses/NOTICE

@@ -0,0 +1,7 @@
+errdown
+Copyright 2026 Artem Zabarov
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+errdown is an independent project and is not affiliated with or endorsed by Cloudflare, Inc.
+It follows Cloudflare's published structured error format for interoperability.