primarysource 0.1.0__py3-none-any.whl

primarysource/draft/status.py

@@ -0,0 +1,146 @@
+"""A draft's life cycle as the datatracker last reported it, and what that means for someone about to cite it.
+
+`Status` is a snapshot with the time it was taken. It is stored beside the draft's revisions and printed by
+`info`, and every read and cite result puts its verdict in the `warning:` line, so a caller never quotes a dead
+draft without being told: RFC 2026 §2.2 says an Internet-Draft is removed after six months unchanged, has no
+formal status and is subject to change or removal at any time.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, date, datetime
+from typing import Any
+
+from primarysource.errors import LibError
+
+STALE_DAYS = 14
+
+ACTIVE = "active"
+EXPIRED = "expired"
+REPLACED = "replaced"
+RFC = "rfc"
+WITHDRAWN = "withdrawn"
+UNKNOWN = "unknown"
+
+_LEVELS = {
+    "active": ACTIVE,
+    "expired": EXPIRED,
+    "replaced": REPLACED,
+    "rfc": RFC,
+    "withdrawn by submitter": WITHDRAWN,
+    "withdrawn by ietf": WITHDRAWN,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Status:
+    """What the datatracker said about `name` at `checked`. `rev` is the latest revision it knew then;
+    `revisions` are (revision, publication date) pairs; `replaced_by` are the drafts that replace this one and
+    `became_rfc` the RFC it was published as (`RFC8210`), if any."""
+
+    name: str
+    title: str
+    state: str
+    rev: str
+    expires: str
+    replaced_by: tuple[str, ...]
+    became_rfc: str | None
+    revisions: tuple[tuple[str, str], ...]
+    authors: tuple[str, ...]
+    group: str
+    stream: str
+    pages: int | None
+    checked: str
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=1, ensure_ascii=False) + "\n"
+
+    @staticmethod
+    def from_json(text: str) -> Status:
+        """Read a stored snapshot; a damaged one is a LibError that names the command that rewrites it."""
+        try:
+            raw: dict[str, Any] = json.loads(text)
+            return Status(
+                name=str(raw["name"]),
+                title=str(raw["title"]),
+                state=str(raw["state"]),
+                rev=str(raw["rev"]),
+                expires=str(raw["expires"]),
+                replaced_by=tuple(str(x) for x in raw["replaced_by"]),
+                became_rfc=None if raw["became_rfc"] is None else str(raw["became_rfc"]),
+                revisions=tuple((str(a), str(b)) for a, b in raw["revisions"]),
+                authors=tuple(str(x) for x in raw["authors"]),
+                group=str(raw["group"]),
+                stream=str(raw["stream"]),
+                pages=None if raw["pages"] is None else int(raw["pages"]),
+                checked=str(raw["checked"]),
+            )
+        except (ValueError, KeyError, TypeError) as exc:
+            raise LibError("a stored status snapshot is damaged", "", "primarysource draft refresh") from exc
+
+    def published(self, rev: str) -> str:
+        """The date revision `rev` was posted (YYYY-MM-DD), or ''."""
+        for known, when in self.revisions:
+            if known == rev:
+                return when[:10]
+        return ""
+
+
+def _day(text: str) -> date | None:
+    try:
+        return datetime.fromisoformat(text.replace("Z", "+00:00")).date() if text else None
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class Lifecycle:
+    """`level` is one of the module constants; `text` is one sentence for a person; `alive` is True only for a
+    draft that is active and not past its expiry date."""
+
+    level: str
+    text: str
+    alive: bool
+
+
+def lifecycle(status: Status, today: date | None = None) -> Lifecycle:
+    """The verdict on a snapshot. A draft whose datatracker state is still Active but whose expiry date has
+    passed is reported as expired by date, because the snapshot may simply be old."""
+    today = today or datetime.now(UTC).date()
+    level = _LEVELS.get(status.state.strip().lower(), UNKNOWN)
+    when = status.expires[:10]
+    if level == RFC or (status.became_rfc and level != REPLACED):
+        rfc = status.became_rfc or "an RFC"
+        return Lifecycle(RFC, f"published as {rfc}: cite the RFC, not this draft", False)
+    if level == REPLACED:
+        by = ", ".join(status.replaced_by) or "another draft"
+        return Lifecycle(REPLACED, f"replaced by {by}: this draft is dead, read and cite its successor", False)
+    if level == WITHDRAWN:
+        return Lifecycle(WITHDRAWN, f"{status.state.lower()}: do not rely on it", False)
+    if level == EXPIRED:
+        return Lifecycle(
+            EXPIRED,
+            f"expired on {when or 'an unknown date'}: not an active draft, and may have been abandoned",
+            False,
+        )
+    if level == ACTIVE:
+        end = _day(status.expires)
+        if end is not None and end < today:
+            return Lifecycle(
+                EXPIRED,
+                f"past its expiry date {when} though the datatracker listed it Active at the last check",
+                False,
+            )
+        return Lifecycle(
+            ACTIVE, f"active, expires {when}: work in progress" if when else "active: work in progress", True
+        )
+    return Lifecycle(UNKNOWN, f"the datatracker reported the state {status.state!r}: check it before citing", False)
+
+
+def staleness(status: Status, today: date | None = None) -> int:
+    """Days since the snapshot was taken (0 if its date cannot be read)."""
+    today = today or datetime.now(UTC).date()
+    taken = _day(status.checked)
+    return max(0, (today - taken).days) if taken else 0

primarysource/draft/store.py

@@ -0,0 +1,199 @@
+"""The on-disk library: `$PRIMARYSOURCE_HOME/draft/<name>/<rev>/` per revision, `<name>/status.json` per draft.
+
+    draft-x-y/status.json        the datatracker's last word (status.py), replaced on every refresh
+    draft-x-y/03/draft.txt       the archive's text, byte for byte as fetched
+    draft-x-y/03/draft.xml       the author's source, when the archive has one
+    draft-x-y/03/meta.json       what was fetched, from where, its sha256, and its licence legend
+    draft-x-y/03/sections.json   a cache of the segmentation; rebuilt from draft.txt when missing or stale
+
+A revision directory appears whole or not at all (it is built beside the others and renamed into place), and
+`meta.json` is what a reader trusts. A stored revision is never overwritten: the archive's revisions do not
+change, so a different digest for one is an error to report, not an update to apply.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import secrets
+import shutil
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+from typing import Any
+
+from primarysource.draft import names, segment
+from primarysource.draft.status import Status
+from primarysource.errors import LibError
+from primarysource.home import atomic_write
+from primarysource.home import collection_home as core_collection_home
+
+COLLECTION = "draft"
+READONLY_VARIABLE = "PRIMARYSOURCE_READONLY"
+_REV_DIR = re.compile(r"[0-9]{2}")
+
+
+def readonly() -> bool:
+    """True when `primarysource mcp --read-only` (or the variable) asked for no writes and no fetching."""
+    return os.environ.get(READONLY_VARIABLE, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass(frozen=True, slots=True)
+class RevMeta:
+    """What one stored revision is. `xml_state` is `v2`, `v3`, `absent`, `refused`, `unparseable` or `skipped`."""
+
+    name: str
+    rev: str
+    title: str
+    published: str
+    authors: tuple[str, ...]
+    txt_sha256: str
+    txt_bytes: int
+    encoding: str
+    xml_state: str
+    xml_sha256: str
+    xml_bytes: int
+    restriction: str
+    copyright_year: int
+    ipr: str
+    imported: str
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), indent=1, ensure_ascii=False) + "\n"
+
+    @staticmethod
+    def from_json(text: str) -> RevMeta:
+        try:
+            raw: dict[str, Any] = json.loads(text)
+            values = {f.name: raw[f.name] for f in fields(RevMeta)}
+            values["authors"] = tuple(str(a) for a in values["authors"])
+            for key in ("txt_bytes", "xml_bytes", "copyright_year"):
+                values[key] = int(values[key])
+            for key in set(values) - {"authors", "txt_bytes", "xml_bytes", "copyright_year"}:
+                values[key] = str(values[key])
+            return RevMeta(**values)
+        except (ValueError, KeyError, TypeError) as exc:
+            raise LibError(
+                "a stored revision's meta.json is damaged",
+                "",
+                "import that revision again: primarysource draft import",
+            ) from exc
+
+
+class Store:
+    """One draft library. `root` is the collection's directory; by default `$PRIMARYSOURCE_HOME/draft`."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root if root is not None else core_collection_home(COLLECTION)
+
+    def _dir(self, name: str, rev: str | None = None) -> Path:
+        base = self.root / names.parse_name(name)
+        return base if rev is None else base / names.valid_revision(rev)
+
+    def path(self, name: str, rev: str) -> Path:
+        """Where one revision lives (it may not exist)."""
+        return self._dir(name, rev)
+
+    def names(self) -> list[str]:
+        """Drafts with at least one stored revision, sorted."""
+        if not self.root.is_dir():
+            return []
+        return sorted(p.name for p in self.root.iterdir() if p.is_dir() and self.revisions(p.name))
+
+    def revisions(self, name: str) -> list[str]:
+        """Stored revisions of `name`, oldest first. A directory without `meta.json` is a failed import: ignored."""
+        base = self._dir(name)
+        if not base.is_dir():
+            return []
+        return sorted(p.name for p in base.iterdir() if _REV_DIR.fullmatch(p.name) and (p / "meta.json").is_file())
+
+    def has(self, name: str, rev: str) -> bool:
+        return (self._dir(name, rev) / "meta.json").is_file()
+
+    def resolve(self, name: str, rev: str | None) -> tuple[str, bool]:
+        """The revision to read and whether it was chosen (True) because none was named: the latest stored."""
+        stored = self.revisions(name)
+        if rev is not None:
+            if rev not in stored:
+                have = ", ".join(stored) or "none"
+                raise LibError(
+                    f"revision {rev} of {name} is not stored (stored: {have})",
+                    f"draft_info('{name}') says which revisions exist",
+                    f"primarysource draft import {name}-{rev}",
+                )
+            return rev, False
+        if not stored:
+            raise LibError(
+                f"{name} is not stored", "draft_list lists what is stored", f"primarysource draft import {name}"
+            )
+        return stored[-1], True
+
+    def meta(self, name: str, rev: str) -> RevMeta:
+        path = self._dir(name, rev) / "meta.json"
+        try:
+            return RevMeta.from_json(path.read_text(encoding="utf-8"))
+        except OSError as exc:
+            raise LibError(
+                f"{name}-{rev} is not stored",
+                "draft_info says which revisions are",
+                f"primarysource draft import {name}-{rev}",
+            ) from exc
+
+    def status(self, name: str) -> Status | None:
+        """The datatracker snapshot for `name`, or None if it was never fetched."""
+        path = self._dir(name) / "status.json"
+        try:
+            return Status.from_json(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+
+    def write_status(self, status: Status) -> None:
+        atomic_write(self._dir(status.name) / "status.json", status.to_json().encode("utf-8"))
+
+    def raw_text(self, name: str, rev: str) -> bytes:
+        try:
+            return (self._dir(name, rev) / "draft.txt").read_bytes()
+        except OSError as exc:
+            raise LibError(
+                f"{name}-{rev} has no stored text", "", f"primarysource draft import {name}-{rev}"
+            ) from exc
+
+    def segmented(self, name: str, rev: str) -> segment.Segmented:
+        """The sections of a stored revision, from the cache when it is current, else from the stored text (and the
+        cache is rewritten unless the library is read-only)."""
+        folder = self._dir(name, rev)
+        try:
+            cached = segment.Segmented.from_json((folder / "sections.json").read_text(encoding="utf-8"))
+        except OSError:
+            cached = None
+        if cached is not None:
+            return cached
+        text, _encoding = segment.decode(self.raw_text(name, rev))
+        found = segment.segment(text)
+        if not readonly():
+            with contextlib.suppress(OSError):  # a read-only volume is a supported place to serve from
+                atomic_write(folder / "sections.json", found.to_json().encode("utf-8"))
+        return found
+
+    def install(self, meta: RevMeta, txt: bytes, xml: bytes | None, found: segment.Segmented) -> Path:
+        """Write one revision whole, or not at all. Refuses to replace a stored revision."""
+        target = self._dir(meta.name, meta.rev)
+        if (target / "meta.json").is_file():
+            raise LibError(f"{meta.name}-{meta.rev} is already stored", "")
+        base = target.parent
+        base.mkdir(parents=True, exist_ok=True)
+        staging = base / f".{meta.rev}.part-{secrets.token_hex(4)}"
+        staging.mkdir()
+        try:
+            atomic_write(staging / "draft.txt", txt)
+            if xml is not None:
+                atomic_write(staging / "draft.xml", xml)
+            atomic_write(staging / "sections.json", found.to_json().encode("utf-8"))
+            atomic_write(staging / "meta.json", meta.to_json().encode("utf-8"))
+            if target.exists():  # a failed earlier import left a directory without meta.json
+                shutil.rmtree(target)
+            os.replace(staging, target)
+        finally:
+            shutil.rmtree(staging, ignore_errors=True)
+        return target

primarysource/draft/tracked.json

@@ -0,0 +1,104 @@
+{
+ "schema": 1,
+ "terms": {
+  "licence": "IETF Trust Legal Provisions 5.0 §3.c, with BCP 78 (RFC 5378)",
+  "placement": "volume",
+  "terms_url": "https://trustee.ietf.org/documents/trust-legal-provisions/tlp-5/",
+  "terms_read": "2026-11-13",
+  "summary": "Authors keep the copyright in their Internet-Drafts (RFC 5378 §3.6); the IETF Trust may sublicense. TLP 5.0 §3.c allows copying and distributing a Contribution in full and without modification, or unmodified portions with attribution, but only for Contributions submitted after 2015-03-25 and not where a draft's own legend forbids it. Drafts are fetched by the reader onto a volume; none is shipped in an image."
+ },
+ "drafts": [
+  {
+   "name": "draft-ietf-sidrops-8210bis",
+   "why": "RPKI-to-Router protocol version 2 and the ASPA PDU: the specification rtrkit implements beyond RFC 8210.",
+   "consumers": [
+    "rtrkit"
+   ],
+   "rev_read": "29",
+   "state": "Active",
+   "replaced_by": [],
+   "became_rfc": null,
+   "expires": "2027-05-16",
+   "checked": "2026-11-13",
+   "pins": {
+    "29": {
+     "txt": "9519b014550e43630ba484c2eda50c48a2a6bad4ec286690e695b9b6aa9681cf",
+     "xml": "1ce63b8f7338d9e2a073e47b8f82012f8c9f86ead6d0afe9d71b4986a0841292"
+    }
+   }
+  },
+  {
+   "name": "draft-ietf-sidrops-aspa-profile",
+   "why": "The ASPA signed-object profile that draft-ietf-sidrops-8210bis section 1.2 cites for the ASPA PDU; no portfolio row names it yet.",
+   "consumers": [],
+   "rev_read": "31",
+   "state": "Active",
+   "replaced_by": [],
+   "became_rfc": null,
+   "expires": "2027-05-14",
+   "checked": "2026-11-13",
+   "pins": {
+    "31": {
+     "txt": "6f4b8381e1ef85164dd855a04c7692c476ae454b7e269d56d023df8b94db5b56",
+     "xml": "762ebb9587b186fe29b9a9e133f6572daaa4286fd0854dc5ba6c8278b3d14199"
+    }
+   }
+  },
+  {
+   "name": "draft-ietf-sidrops-aspa-verification",
+   "why": "ASPA-based AS_PATH verification. RFC 9774 section 9.2 cites it as a Work in Progress.",
+   "consumers": [
+    "routevalid",
+    "asnkit"
+   ],
+   "rev_read": "29",
+   "state": "Active",
+   "replaced_by": [],
+   "became_rfc": null,
+   "expires": "2027-04-19",
+   "checked": "2026-11-13",
+   "pins": {
+    "29": {
+     "txt": "3203e57006b2700b67570394951b94f68b98967afc14d75f4b52b2e90220b699",
+     "xml": "bdf3e0200c22eefab17264bf2abd89adcad73d88dc6397aadea84aaa4874fccb"
+    }
+   }
+  },
+  {
+   "name": "draft-koch-librepgp",
+   "why": "LibrePGP message format, an extension of OpenPGP (RFC 4880, 5581, 6637, all since obsoleted by RFC 9580, which is a different line): what pgpenv needs for LibrePGP.",
+   "consumers": [
+    "pgpenv"
+   ],
+   "rev_read": "06",
+   "state": "Active",
+   "replaced_by": [],
+   "became_rfc": null,
+   "expires": "2027-03-11",
+   "checked": "2026-11-13",
+   "pins": {
+    "06": {
+     "txt": "c82a7412d728408ed442b2c940e225a58f3db96d288008290e31f45741b2fdc1"
+    }
+   }
+  },
+  {
+   "name": "draft-uberti-behave-turn-rest",
+   "why": "A REST API for obtaining ephemeral TURN credentials. The datatracker shows it expired in 2014, neither replaced nor published as an RFC.",
+   "consumers": [
+    "turnkit"
+   ],
+   "rev_read": "00",
+   "state": "Expired",
+   "replaced_by": [],
+   "became_rfc": null,
+   "expires": "2014-01-16",
+   "checked": "2026-11-13",
+   "pins": {
+    "00": {
+     "txt": "ebcd0450f37481dfb2817482af1bc09532fdf7691016542498b6e4a64bbb7636"
+    }
+   }
+  }
+ ]
+}