errdown 0.1.0a0__tar.gz

errdown-0.1.0a0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.pyc
+.env
+.DS_Store
+coverage/
+lab/cf-worker/captures/
+lab/cf-zone/captures/
+packages/py/dist/

errdown-0.1.0a0/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/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.

errdown-0.1.0a0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,23 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "errdown"
+version = "0.1.0a0"
+description = "Cloudflare-compatible structured errors (RFC 9457) for every HTTP error your agent hits."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Artem Zabarov" }]
+keywords = ["rfc9457", "problem-details", "errors", "ai-agents", "llm", "mcp", "cloudflare", "http"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://errdown.com"
+Repository = "https://github.com/ArtZab0/errdown"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/errdown"]

errdown-0.1.0a0/src/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-0.1.0a0/src/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-0.1.0a0/src/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-0.1.0a0/src/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