statusdoc 0.1.0__py3-none-any.whl

statusdoc/__init__.py

@@ -0,0 +1,26 @@
+"""Open Status Document: read, discover and validate service status pages."""
+
+__version__ = "0.1.0"
+
+from .adapters import detect, from_betterstack, load
+from .discover import Discovery, DiscoveryError, discover
+from .model import Component, Document, FormatError, Incident, Update, parse
+from .validate import Issue, validate_document, validate_http
+
+__all__ = [
+    "Component",
+    "Discovery",
+    "DiscoveryError",
+    "Document",
+    "FormatError",
+    "Incident",
+    "Issue",
+    "Update",
+    "detect",
+    "discover",
+    "from_betterstack",
+    "load",
+    "parse",
+    "validate_document",
+    "validate_http",
+]

statusdoc/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

statusdoc/adapters.py

@@ -0,0 +1,237 @@
+"""Readers for status formats that are not OSD yet."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .model import Component, Document, FormatError, Incident, Update, parse
+
+# Better Stack resource states → OSD component statuses.
+_BETTERSTACK_STATUS = {
+    "operational": "operational",
+    "maintenance": "under_maintenance",
+    "degraded": "degraded_performance",
+    "downtime": "major_outage",
+}
+_BETTERSTACK_SEVERITY = {"operational": 0, "under_maintenance": 1, "degraded_performance": 2, "partial_outage": 3, "major_outage": 4}
+_IMPACT_OF = {"degraded_performance": "minor", "partial_outage": "major", "major_outage": "critical"}
+_INDICATOR_OF = {0: "none", 1: "maintenance", 2: "minor", 3: "major", 4: "critical"}
+_DESCRIPTION_OF = {
+    0: "All Systems Operational",
+    1: "Service Under Maintenance",
+    2: "Partially Degraded Service",
+    3: "Partial System Outage",
+    4: "Major System Outage",
+}
+
+
+def detect(data: Any) -> str | None:
+    """Returns the format of a parsed JSON document, or None if unknown."""
+    if not isinstance(data, dict):
+        return None
+    if isinstance(data.get("page"), dict) and isinstance(data.get("status"), dict) and isinstance(data.get("components"), list):
+        return "osd"
+    d = data.get("data")
+    if isinstance(d, dict) and d.get("type") == "status_page" and isinstance(data.get("included"), list):
+        return "betterstack"
+    if isinstance(data.get("status"), str) and isinstance(data.get("active_incidents"), list):
+        return "slack"
+    return None
+
+
+def load(data: Any) -> Document:
+    """Reads a status document in any supported format."""
+    fmt = detect(data)
+    if fmt == "osd":
+        return parse(data)
+    if fmt == "betterstack":
+        return from_betterstack(data)
+    if fmt == "slack":
+        return from_slack(data)
+    raise FormatError("not a status document in a known format")
+
+
+def from_betterstack(data: dict[str, Any]) -> Document:
+    """Converts a Better Stack status page (`/index.json`, JSON:API) to OSD."""
+    page = data["data"].get("attributes", {})
+    included = [x for x in data["included"] if isinstance(x, dict)]
+
+    def of_type(t: str) -> list[dict[str, Any]]:
+        return [x for x in included if x.get("type") == t]
+
+    components: dict[str, Component] = {}
+    sections = {str(s.get("id")): s.get("attributes", {}) for s in of_type("status_page_section")}
+    for s_id, s in sections.items():
+        components["section-" + s_id] = Component(
+            id="section-" + s_id, name=str(s.get("name", "")).strip(), status="operational", group=True, position=s.get("position")
+        )
+    for r in of_type("status_page_resource"):
+        a = r.get("attributes", {})
+        if a.get("status") == "not_monitored":
+            # No data, so no claim either way: leave it out.
+            continue
+        section = a.get("status_page_section_id")
+        c = Component(
+            id=str(r.get("id")),
+            name=str(a.get("public_name", "")),
+            status=_BETTERSTACK_STATUS.get(str(a.get("status")), "degraded_performance"),
+            description=a.get("explanation") or None,
+            group_id=f"section-{section}" if section is not None and str(section) in sections else None,
+            position=a.get("position"),
+        )
+        components[c.id] = c
+    # A section is as bad as its worst resource.
+    for c in components.values():
+        if c.group_id:
+            group = components[c.group_id]
+            if _BETTERSTACK_SEVERITY[c.status] > _BETTERSTACK_SEVERITY[group.status]:
+                group.status = c.status
+
+    updates = {str(u.get("id")): u.get("attributes", {}) for u in of_type("status_update")}
+    incidents: list[Incident] = []
+    maintenances: list[Incident] = []
+    for report in of_type("status_report"):
+        a = report.get("attributes", {})
+        resolved = a.get("aggregate_state") == "resolved" or a.get("ends_at") is not None
+        affected = [
+            components[str(x.get("status_page_resource_id"))] for x in a.get("affected_resources", []) if str(x.get("status_page_resource_id")) in components
+        ]
+        worst = max((_BETTERSTACK_SEVERITY[c.status] for c in affected), default=0)
+        rel = report.get("relationships", {}).get("status_updates", {}).get("data", [])
+        report_updates = [updates[str(x.get("id"))] for x in rel if str(x.get("id")) in updates]
+        report_updates.sort(key=lambda u: str(u.get("published_at", "")), reverse=True)
+        is_maintenance = a.get("report_type") == "maintenance"
+        item = Incident(
+            id=str(report.get("id")),
+            name=str(a.get("title", "")),
+            status=("completed" if resolved else "in_progress") if is_maintenance else ("resolved" if resolved else "investigating"),
+            impact="none" if is_maintenance else _IMPACT_OF.get(_status_of(worst), "minor"),
+            created_at=str(a.get("starts_at", "")),
+            updates=[
+                Update(id=str(i), status="resolved" if resolved else "investigating", body=str(u.get("message", "")), created_at=str(u.get("published_at", "")))
+                for i, u in enumerate(report_updates)
+            ],
+            components=affected,
+            scheduled_for=a.get("starts_at") if is_maintenance else None,
+            scheduled_until=a.get("ends_at") if is_maintenance else None,
+        )
+        if is_maintenance:
+            if not resolved:
+                maintenances.append(item)
+        elif not resolved:
+            incidents.append(item)
+
+    # The page's own aggregate state is the publisher's judgement (spec section 4.3);
+    # fall back to the worst resource when it is missing.
+    aggregate = _BETTERSTACK_STATUS.get(str(page.get("aggregate_state")))
+    worst = _BETTERSTACK_SEVERITY[aggregate] if aggregate else max((_BETTERSTACK_SEVERITY[c.status] for c in components.values() if not c.group), default=0)
+    domain = page.get("custom_domain") or f"{page.get('subdomain', '')}.betteruptime.com"
+    return Document(
+        name=str(page.get("company_name", "")),
+        url=f"https://{domain}",
+        updated_at=str(page.get("updated_at", "")),
+        indicator=_INDICATOR_OF[worst],
+        description=_DESCRIPTION_OF[worst],
+        components=sorted(components.values(), key=lambda c: (c.group_id or c.id, not c.group, c.position or 0)),
+        incidents=incidents,
+        maintenances=maintenances,
+        source_format="betterstack",
+    )
+
+
+def _status_of(severity: int) -> str:
+    for status, s in _BETTERSTACK_SEVERITY.items():
+        if s == severity:
+            return status
+    return "operational"
+
+
+# Services listed by the Slack Status API documentation for /api/v2.0.0/current.
+SLACK_SERVICES = (
+    "Login/SSO",
+    "Messaging",
+    "Notifications",
+    "Search",
+    "Workspace/Org Administration",
+    "Canvases",
+    "Connectivity",
+    "Files",
+    "Huddles",
+    "Apps/Integrations/APIs",
+    "Workflows",
+)
+# Slack issue types → (OSD incident impact, status of the affected services).
+_SLACK_TYPES = {"outage": ("major", "major_outage"), "incident": ("minor", "degraded_performance"), "notice": ("none", "operational")}
+
+
+def from_slack(data: dict[str, Any]) -> Document:
+    """Converts the Slack Status API (`https://slack-status.com/api/v2.0.0/current`) to OSD.
+
+    Slack reports issues, not component states: affected services take the
+    status implied by the issue type (an outage makes them major_outage, an
+    incident degraded_performance, a notice leaves them operational).
+    """
+    services: dict[str, Component] = {}
+
+    def service(name: str) -> Component:
+        if name not in services:
+            slug = "".join(ch if ch.isalnum() else "-" for ch in name.lower()).strip("-")
+            services[name] = Component(id=slug, name=name, status="operational", position=len(services))
+        return services[name]
+
+    for name in SLACK_SERVICES:
+        service(name)
+
+    incidents: list[Incident] = []
+    maintenances: list[Incident] = []
+    worst = 0
+    for item in data.get("active_incidents", []):
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status", ""))
+        kind = str(item.get("type", ""))
+        impact, service_status = _SLACK_TYPES.get(kind, ("minor", "degraded_performance"))
+        notes = [n for n in item.get("notes", []) if isinstance(n, dict)]
+        notes.sort(key=lambda n: str(n.get("date_created", "")), reverse=True)
+        affected = [service(str(s)) for s in item.get("services", []) if isinstance(s, str)]
+        entry = Incident(
+            id=str(item.get("id", "")),
+            name=str(item.get("title", "")),
+            status="",
+            impact=impact,
+            created_at=str(item.get("date_created", "")),
+            updated_at=item.get("date_updated"),
+            shortlink=item.get("url"),
+            updates=[
+                Update(id=f"{item.get('id', '')}-{n}", status="", body=str(note.get("body", "")), created_at=str(note.get("date_created", "")))
+                for n, note in enumerate(notes)
+            ],
+        )
+        if status in ("scheduled", "completed", "cancelled"):
+            if status == "scheduled":
+                entry.status, entry.impact = "scheduled", "none"
+                entry.scheduled_for = entry.created_at
+                maintenances.append(entry)
+            continue
+        entry.status = "resolved" if status == "resolved" else "investigating"
+        for u in entry.updates:
+            u.status = entry.status
+        if not entry.resolved:
+            for c in affected:
+                if _BETTERSTACK_SEVERITY[service_status] > _BETTERSTACK_SEVERITY[c.status]:
+                    c.status = service_status
+            worst = max(worst, {"none": 0, "minor": 2, "major": 3}[impact])
+        entry.components = [Component(id=c.id, name=c.name, status=c.status) for c in affected]
+        incidents.append(entry)
+
+    return Document(
+        name="Slack",
+        url="https://slack-status.com",
+        updated_at=str(data.get("date_updated", "")),
+        indicator=_INDICATOR_OF[worst],
+        description=_DESCRIPTION_OF[worst],
+        components=list(services.values()),
+        incidents=incidents,
+        maintenances=maintenances,
+        source_format="slack",
+    )

statusdoc/cli.py

@@ -0,0 +1,221 @@
+"""Command line: check, discover, validate and convert status documents."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, TextIO
+
+from . import __version__
+from .discover import Discovery, DiscoveryError, discover
+from .fetch import Fetcher, FetchError, get
+from .model import LEVELS, Document
+from .validate import Issue, has_errors, validate_document, validate_http
+
+# Exit codes of `statusdoc check`.
+EXIT_OK, EXIT_DEGRADED, EXIT_USAGE, EXIT_UNREACHABLE = 0, 1, 2, 3
+
+_SYMBOL = {"operational": "✓", "maintenance": "◷", "minor": "!", "major": "✗", "critical": "✗"}
+
+
+def main(argv: list[str] | None = None, *, out: TextIO = sys.stdout, fetch: Fetcher = get, registry: dict[str, dict[str, str]] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="statusdoc", description="Read service status pages in the Open Status Document format.")
+    parser.add_argument("--version", action="version", version=f"statusdoc {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="show the status of services (exit 1 if one is degraded)")
+    p_check.add_argument("targets", nargs="+", metavar="DOMAIN|URL")
+    p_check.add_argument("--json", action="store_true", help="print JSON")
+    p_check.add_argument("--github", action="store_true", help="in GitHub Actions: write a job summary, step outputs and annotations")
+    p_check.add_argument("-v", "--verbose", action="store_true", help="list components that are not operational")
+    p_check.add_argument(
+        "--fail-on", choices=("minor", "major", "critical", "never"), default="minor", help="lowest level that makes the exit code 1 (default: minor)"
+    )
+
+    p_disc = sub.add_parser("discover", help="find the status document of services")
+    p_disc.add_argument("targets", nargs="+", metavar="DOMAIN|URL")
+
+    p_val = sub.add_parser("validate", help="check a status document against the spec")
+    p_val.add_argument("target", metavar="DOMAIN|URL")
+
+    p_conv = sub.add_parser("convert", help="print a status document in OSD form")
+    p_conv.add_argument("target", metavar="DOMAIN|URL")
+
+    args = parser.parse_args(argv)
+    if out is sys.stdout and hasattr(out, "reconfigure"):
+        # Windows consoles and pipes may not encode the status symbols.
+        out.reconfigure(errors="replace")
+    find = lambda t: discover(t, fetch=fetch, registry=registry)
+
+    if args.command == "check":
+        return _check(args, find, out)
+    if args.command == "discover":
+        status = EXIT_OK
+        for target, result in _all(args.targets, find):
+            if isinstance(result, Exception):
+                print(f"{target}: {result}", file=out)
+                status = EXIT_UNREACHABLE
+            else:
+                print(f"{target}: {result.document_url} (via {result.method}, {result.document.source_format})", file=out)
+        return status
+    if args.command == "validate":
+        return _validate(args.target, find, fetch, out)
+    if args.command == "convert":
+        try:
+            d = find(args.target)
+        except (DiscoveryError, FetchError, ValueError) as e:
+            print(f"statusdoc: {e}", file=sys.stderr)
+            return EXIT_UNREACHABLE
+        json.dump(d.document.to_dict(), out, indent=2, ensure_ascii=False)
+        print(file=out)
+        return EXIT_OK
+    return EXIT_USAGE
+
+
+def _all(targets: list[str], find: Any) -> list[tuple[str, Discovery | Exception]]:
+    def one(t: str) -> Discovery | Exception:
+        try:
+            return find(t)
+        except (DiscoveryError, FetchError, ValueError) as e:
+            return e
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        return list(zip(targets, pool.map(one, targets)))
+
+
+def _check(args: argparse.Namespace, find: Any, out: TextIO) -> int:
+    results = _all(args.targets, find)
+    threshold = len(LEVELS) if args.fail_on == "never" else LEVELS.index(args.fail_on)
+    degraded = unreachable = False
+    report = []
+    for target, r in results:
+        if isinstance(r, Exception):
+            unreachable = True
+            report.append({"target": target, "error": str(r)})
+            continue
+        d = r.document
+        degraded |= d.severity >= threshold
+        report.append(_summary(target, r, d))
+
+    if args.json:
+        json.dump(report, out, indent=2, ensure_ascii=False)
+        print(file=out)
+    else:
+        width = max(len(t) for t in args.targets)
+        for item in report:
+            if "error" in item:
+                print(f"? {item['target']:<{width}}  unreachable: {item['error']}", file=out)
+                continue
+            print(f"{_SYMBOL[item['level']]} {item['target']:<{width}}  {item['level']:<11} {item['description']}", file=out)
+            for inc in item["incidents"]:
+                print(f"  {'':<{width}}  • {inc['name']} ({inc['impact']}, {inc['status']})", file=out)
+            for m in item["maintenance"]:
+                print(f"  {'':<{width}}  ◷ {m['name']} (until {m['until'] or 'unknown'})", file=out)
+            if args.verbose:
+                for comp in item["components"]:
+                    print(f"  {'':<{width}}  - {comp['name']}: {comp['status']}", file=out)
+    if args.github:
+        _github(report, threshold, out)
+    if degraded:
+        return EXIT_DEGRADED
+    return EXIT_UNREACHABLE if unreachable else EXIT_OK
+
+
+def _short(error: str) -> str:
+    """Shortens a discovery error that lists every address tried."""
+    head, sep, tried = error.partition(": tried ")
+    return f"{head} (tried {tried.count('; ') + 1} addresses)" if sep else error
+
+
+_EMOJI = {"operational": "✅", "maintenance": "🛠️", "minor": "⚠️", "major": "❌", "critical": "🔥"}
+
+
+def markdown(report: list[dict[str, Any]]) -> str:
+    """Renders a check report as a Markdown table."""
+    lines = ["### Upstream status", "", "| | Service | Status | Details |", "|---|---|---|---|"]
+
+    def cell(text: str) -> str:
+        return text.replace("|", "\\|").replace("\n", " ")
+
+    for item in report:
+        if "error" in item:
+            lines.append(f"| ❓ | {cell(item['target'])} | unreachable | {cell(_short(item['error']))} |")
+            continue
+        details = [cell(item["description"])]
+        for inc in item["incidents"]:
+            name = cell(inc["name"])
+            details.append(f"[{name}]({inc['url']})" if inc.get("url") else name)
+        for m in item["maintenance"]:
+            details.append("Maintenance: " + cell(m["name"]))
+        service = f"[{cell(item['target'])}]({item['page']})" if item.get("page") else cell(item["target"])
+        lines.append(f"| {_EMOJI[item['level']]} | {service} | {item['level']} | {'<br>'.join(details)} |")
+    return "\n".join(lines) + "\n"
+
+
+def _github(report: list[dict[str, Any]], threshold: int, out: TextIO) -> None:
+    """Job summary, step outputs and annotations for GitHub Actions."""
+    import os
+
+    if path := os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(markdown(report))
+    levels = [LEVELS.index(i["level"]) for i in report if "error" not in i]
+    worst = LEVELS[max(levels)] if levels else "unknown"
+    if path := os.environ.get("GITHUB_OUTPUT"):
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(f"worst-level={worst}\n")
+            f.write(f"degraded={'true' if levels and max(levels) >= threshold else 'false'}\n")
+            f.write(f"unreachable={'true' if any('error' in i for i in report) else 'false'}\n")
+            f.write("report=" + json.dumps(report, ensure_ascii=False, separators=(",", ":")) + "\n")
+    for item in report:
+        if "error" in item:
+            print(f"::warning title={item['target']} unreachable::{_short(item['error'])}", file=out)
+        elif item["level"] != "operational":
+            kind = "error" if LEVELS.index(item["level"]) >= threshold else "warning"
+            incidents = "; ".join(i["name"] for i in item["incidents"])
+            print(f"::{kind} title={item['target']} is {item['level']}::{item['description']}{': ' + incidents if incidents else ''}", file=out)
+
+
+def _summary(target: str, r: Discovery, d: Document) -> dict[str, Any]:
+    return {
+        "target": target,
+        "name": d.name,
+        "level": d.level,
+        "indicator": d.indicator,
+        "description": d.description,
+        "page": d.url,
+        "document": r.document_url,
+        "discovered_via": r.method,
+        "incidents": [{"name": i.name, "status": i.status, "impact": i.impact, "url": i.shortlink} for i in d.open_incidents],
+        "maintenance": [{"name": m.name, "status": m.status, "until": m.scheduled_until, "url": m.shortlink} for m in d.active_maintenances],
+        "components": [{"name": c.name, "status": c.status} for c in d.components if not c.group and c.status != "operational"],
+    }
+
+
+def _validate(target: str, find: Any, fetch: Fetcher, out: TextIO) -> int:
+    try:
+        r = find(target)
+    except (DiscoveryError, FetchError, ValueError) as e:
+        print(f"statusdoc: {e}", file=out)
+        return EXIT_UNREACHABLE
+    print(f"document: {r.document_url} (found via {r.method})", file=out)
+    if r.document.source_format != "osd":
+        print(f"MUST   $: the document is in the {r.document.source_format} format, not OSD; `statusdoc convert` shows the OSD equivalent", file=out)
+        return EXIT_DEGRADED
+    issues: list[Issue] = []
+    if r.method != "well-known" and "://" not in target:
+        issues.append(Issue("SHOULD", "discovery", f"https://{target}/.well-known/status does not point to the document (section 3.1)"))
+    resp = r.response or fetch(r.document_url)
+    issues += validate_http(resp) + validate_document(resp.json())
+    for issue in issues:
+        print(issue, file=out)
+    errors = sum(i.level == "MUST" for i in issues)
+    warnings = len(issues) - errors
+    print(f"\n{'not conforming' if has_errors(issues) else 'conforming'} to OSD 0.1: {errors} errors, {warnings} recommendations", file=out)
+    return EXIT_DEGRADED if has_errors(issues) else EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

statusdoc/discover.py

@@ -0,0 +1,129 @@
+"""Finding the status document of a service (SPEC.md, section 3)."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any
+from urllib.parse import urlsplit
+
+from .adapters import detect, load
+from .fetch import Fetcher, FetchError, Response, get
+from .model import Document
+
+
+@dataclass
+class Discovery:
+    target: str
+    document_url: str
+    #: How the document was found: well-known, registry, convention or url.
+    method: str
+    document: Document
+    page_url: str | None = None
+    response: Response | None = None
+
+
+class DiscoveryError(Exception):
+    def __init__(self, target: str, attempts: list[tuple[str, str]]):
+        self.target = target
+        self.attempts = attempts
+        tried = "; ".join(f"{url} ({why})" for url, why in attempts)
+        super().__init__(f"no status document found for {target}: tried {tried}")
+
+
+def load_registry() -> dict[str, dict[str, str]]:
+    data = json.loads(resources.files("statusdoc").joinpath("registry.json").read_text("utf-8"))
+    return data["services"]
+
+
+_DOMAIN = re.compile(r"^[A-Za-z0-9.-]+(:\d+)?$")
+
+
+def discover(target: str, *, fetch: Fetcher = get, registry: dict[str, dict[str, str]] | None = None, scheme: str = "https") -> Discovery:
+    """Finds and reads the status document of a domain, a status page URL or a document URL."""
+    if "://" in target:
+        return _from_url(target, fetch)
+    domain = target.strip().lower().rstrip(".")
+    if not _DOMAIN.match(domain):
+        raise ValueError(f"not a domain or URL: {target!r}")
+    domain = domain.removeprefix("www.")
+    attempts: list[tuple[str, str]] = []
+
+    # 1. The service's own well-known URI.
+    well_known = f"{scheme}://{domain}/.well-known/status"
+    data, resp = _try_json(well_known, fetch, attempts)
+    if isinstance(data, dict):
+        if detect(data):
+            return Discovery(target, resp.url, "well-known", load(data), response=resp)
+        doc_url = data.get("document")
+        if isinstance(doc_url, str) and doc_url.startswith(("https://", f"{scheme}://")):
+            found = _try_document(doc_url, fetch, attempts)
+            if found:
+                page = data.get("page") if isinstance(data.get("page"), str) else None
+                return Discovery(target, found[1].url, "well-known", found[0], page_url=page, response=found[1])
+        else:
+            attempts.append((well_known, "no document URL"))
+
+    # 2. The list of known services, for the domain and its parents.
+    reg = load_registry() if registry is None else registry
+    parts = domain.split(".")
+    for i in range(len(parts) - 1):
+        entry = reg.get(".".join(parts[i:]))
+        if entry:
+            found = _try_document(entry["document"], fetch, attempts)
+            if found:
+                return Discovery(target, found[1].url, "registry", found[0], page_url=entry.get("page"), response=found[1])
+            break
+
+    # 3. Common conventions.
+    host = domain.split(":")[0]
+    label = host.split(".")[-2] if host.count(".") >= 1 else host
+    for page in (f"{scheme}://status.{domain}", f"{scheme}://{label}status.com", f"{scheme}://www.{label}status.com"):
+        for path in ("/api/v2/summary.json", "/index.json"):
+            found = _try_document(page + path, fetch, attempts)
+            if found:
+                return Discovery(target, found[1].url, "convention", found[0], page_url=page, response=found[1])
+    raise DiscoveryError(target, attempts)
+
+
+def _from_url(url: str, fetch: Fetcher) -> Discovery:
+    attempts: list[tuple[str, str]] = []
+    found = _try_document(url, fetch, attempts)
+    if found:
+        return Discovery(url, found[1].url, "url", found[0], response=found[1])
+    # A status page URL: try the usual document paths.
+    parts = urlsplit(url)
+    base = f"{parts.scheme}://{parts.netloc}"
+    for path in ("/api/v2/summary.json", "/index.json"):
+        found = _try_document(base + path, fetch, attempts)
+        if found:
+            return Discovery(url, found[1].url, "convention", found[0], page_url=url, response=found[1])
+    raise DiscoveryError(url, attempts)
+
+
+def _try_json(url: str, fetch: Fetcher, attempts: list[tuple[str, str]]) -> tuple[Any, Response]:
+    try:
+        resp = fetch(url)
+    except FetchError as e:
+        attempts.append((url, str(e).removeprefix(url + ": ")))
+        return None, Response(url, 0)
+    if resp.status != 200:
+        attempts.append((url, f"HTTP {resp.status}"))
+        return None, resp
+    try:
+        return resp.json(), resp
+    except (ValueError, UnicodeDecodeError):
+        attempts.append((url, "not JSON"))
+        return None, resp
+
+
+def _try_document(url: str, fetch: Fetcher, attempts: list[tuple[str, str]]) -> tuple[Document, Response] | None:
+    data, resp = _try_json(url, fetch, attempts)
+    if data is None:
+        return None
+    if not detect(data):
+        attempts.append((url, "JSON, but not a status document"))
+        return None
+    return load(data), resp