ccdirectives 0.2.0__py3-none-any.whl

ccdirectives/__init__.py

@@ -0,0 +1,34 @@
+"""Parse and build the HTTP Cache-Control header as a typed, zero-dependency structure."""
+
+from __future__ import annotations
+
+from ._build import build
+from ._chars import DELTA_MAX
+from ._errors import CacheControlError
+from ._fresh import Freshness, assess, current_age, freshness_lifetime, may_store
+from ._model import CacheControl, DirectiveValue
+from ._parse import parse
+from ._registry import REGISTERED_DIRECTIVES, REQUEST_DIRECTIVES, RESPONSE_DIRECTIVES
+from ._targeted import build_targeted, parse_targeted, select
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "DELTA_MAX",
+    "REGISTERED_DIRECTIVES",
+    "REQUEST_DIRECTIVES",
+    "RESPONSE_DIRECTIVES",
+    "CacheControl",
+    "CacheControlError",
+    "DirectiveValue",
+    "Freshness",
+    "assess",
+    "build",
+    "build_targeted",
+    "current_age",
+    "freshness_lifetime",
+    "may_store",
+    "parse",
+    "parse_targeted",
+    "select",
+]

ccdirectives/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m ccdirectives``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

ccdirectives/_build.py

@@ -0,0 +1,63 @@
+"""Build a Cache-Control field value from a CacheControl structure."""
+
+from __future__ import annotations
+
+from ._chars import DELTA_MAX, delta_seconds, field_names, is_token
+from ._errors import CacheControlError
+from ._model import CacheControl, DirectiveValue
+from ._registry import DELTA_DIRECTIVES, FIELD_DIRECTIVES, argument_rule
+
+
+def build(cache_control: CacheControl) -> str:
+    """Render a CacheControl as a field value, refusing anything the grammar cannot carry.
+
+    Bare flags are written alone and ``False`` is left out. delta-seconds go out in token
+    form and ``no-cache`` and ``private`` field lists in quoted-string form, as RFC 9111
+    section 5.2 asks of senders; other arguments are quoted only when they are not tokens.
+    Names that are not tokens, negative numbers, non-numeric or missing delta-seconds,
+    arguments on registered directives that take none, control characters and non-ASCII
+    text raise ``CacheControlError``, so the output always passes ``parse(strict=True)``.
+    """
+    parts: list[str] = []
+    for name, value in cache_control.directives.items():
+        if value is False:
+            continue
+        if not is_token(name):
+            raise CacheControlError(f"directive name {name!r} is not a token")
+        rule = argument_rule(name, None)
+        if value is True:
+            if rule == "delta":
+                raise CacheControlError(f"{name!r} needs delta-seconds")
+            parts.append(name)
+        elif rule in ("none", "ignored"):
+            raise CacheControlError(f"{name!r} takes no argument")
+        else:
+            parts.append(f"{name}={_argument(name, value)}")
+    return ", ".join(parts)
+
+
+def _argument(name: str, value: DirectiveValue) -> str:
+    if isinstance(value, int):
+        if value < 0:
+            raise CacheControlError(f"{name!r} cannot be negative")
+        # RFC 9111 section 1.2.2: anything past 2^31 means the same, so write the cap.
+        return str(min(value, DELTA_MAX) if name in DELTA_DIRECTIVES else value)
+    if name in DELTA_DIRECTIVES:
+        seconds = delta_seconds(value)
+        if seconds is None:
+            raise CacheControlError(f"{name!r} needs delta-seconds, not {value!r}")
+        return str(seconds)
+    for char in value:
+        code = ord(char)
+        if code > 0x7E or (code < 0x20 and char != "\t") or code == 0x7F:
+            raise CacheControlError(f"{name!r} argument has a character a header cannot carry")
+    if name in FIELD_DIRECTIVES:
+        if field_names(value) is None:
+            raise CacheControlError(f"{name!r} argument is not a list of field names")
+        return _quote(value)
+    return value if is_token(value) else _quote(value)
+
+
+def _quote(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

ccdirectives/_chars.py

@@ -0,0 +1,66 @@
+"""Character classes and value rules shared by the parser and the builder."""
+
+from __future__ import annotations
+
+# RFC 9110 section 5.6.2: tchar is any VCHAR except the delimiters.
+TCHAR = frozenset("!#$%&'*+-.^_`|~0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
+DIGITS = frozenset("0123456789")
+OWS = " \t"
+
+# RFC 9111 section 1.2.2: an overflowing delta-seconds is read as 2^31, meaning "forever".
+DELTA_MAX = 2147483648
+
+
+def is_token(text: str) -> bool:
+    """True when ``text`` is a non-empty RFC 9110 token."""
+    return bool(text) and all(char in TCHAR for char in text)
+
+
+def ascii_lower(text: str) -> str:
+    # str.lower() folds non-ASCII letters too (the Kelvin sign becomes "k"), which would let a
+    # look-alike name match a registered directive.
+    return text.translate(_LOWER)
+
+
+_LOWER = {code: code + 32 for code in range(ord("A"), ord("Z") + 1)}
+
+
+def delta_seconds(text: str) -> int | None:
+    """Read ``1*DIGIT`` as an int capped at 2^31, or None when it is not delta-seconds."""
+    if not text or any(char not in DIGITS for char in text):
+        return None
+    # Compare by length first so a huge string is never converted in full.
+    stripped = text.lstrip("0") or "0"
+    if len(stripped) > len(str(DELTA_MAX)):
+        return DELTA_MAX
+    return min(int(stripped), DELTA_MAX)
+
+
+def is_qdtext(char: str) -> bool:
+    """True for a character allowed unescaped inside an RFC 9110 quoted-string."""
+    code = ord(char)
+    return (
+        code in (0x09, 0x20, 0x21)
+        or 0x23 <= code <= 0x5B
+        or 0x5D <= code <= 0x7E
+        or (0x80 <= code <= 0xFF)
+    )
+
+
+def is_quotable(char: str) -> bool:
+    """True for a character that may follow a backslash in a quoted-pair."""
+    code = ord(char)
+    return code in (0x09, 0x20) or 0x21 <= code <= 0x7E or 0x80 <= code <= 0xFF
+
+
+def field_names(text: str) -> tuple[str, ...] | None:
+    """Split a ``#field-name`` list, lower-cased, or None when an element is not a token."""
+    names: list[str] = []
+    for element in text.split(","):
+        name = element.strip(OWS)
+        if not name:
+            continue
+        if not is_token(name):
+            return None
+        names.append(ascii_lower(name))
+    return tuple(names)

ccdirectives/_cli.py

@@ -0,0 +1,108 @@
+"""Command line: show the cache policy in a header value or a response head as JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ._errors import CacheControlError
+from ._fresh import assess
+from ._head import age_of, field, head_fields, http_date
+from ._model import CacheControl
+from ._parse import parse
+from ._targeted import select
+
+EXIT_INVALID = 1
+
+
+@dataclass
+class _Clock:
+    age: int
+    shared: bool
+    expires: float | None = None
+    date: float | None = None
+
+
+def _report(name: str, policy: CacheControl, clock: _Clock) -> dict[str, object]:
+    verdict = assess(
+        policy, age=clock.age, shared=clock.shared, expires=clock.expires, date=clock.date
+    )
+    return {
+        "field": name,
+        "directives": policy.directives,
+        "duplicates": sorted(policy.duplicates),
+        "extensions": list(policy.extensions()),
+        "lifetime": verdict.lifetime,
+        "age": verdict.age,
+        "fresh": verdict.fresh,
+        "reusable": verdict.reusable,
+        "stale_while_revalidate": verdict.stale_while_revalidate,
+        "stale_if_error": verdict.stale_if_error,
+    }
+
+
+def _from_head(
+    fields: list[tuple[str, str]], args: argparse.Namespace, clock: _Clock
+) -> tuple[str, CacheControl]:
+    targets = args.target or (["CDN-Cache-Control"] if args.shared else [])
+    name, policy = select(fields, targets)
+    if args.strict and name == "Cache-Control":
+        values = [v for n, v in fields if n.lower() == "cache-control"]
+        policy = parse(values, strict=True, context="response")
+    if args.age is None:
+        clock.age = age_of(fields)
+    expires = field(fields, "Expires")
+    if name == "Cache-Control" and expires is not None:
+        # RFC 9111 section 5.3: an Expires that does not parse means already expired.
+        date = http_date(field(fields, "Date"))
+        received = date if date is not None else time.time()
+        stamp = http_date(expires)
+        clock.expires = stamp if stamp is not None else received - 1
+        clock.date = received
+    return name, policy
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line; returns the process exit code."""
+    parser = argparse.ArgumentParser(
+        prog="ccdirectives",
+        description="Show the cache policy of a Cache-Control value, or of a response head "
+        "read from standard input (for example the output of curl -sI). Exit status 1 "
+        "means an invalid value in --strict mode, 2 a usage error.",
+    )
+    parser.add_argument("value", nargs="?", help="a Cache-Control field value")
+    parser.add_argument("--strict", action="store_true", help="reject values outside the RFC")
+    parser.add_argument("--shared", action="store_true", help="judge as a shared cache (a CDN)")
+    parser.add_argument("--age", type=int, help="age in seconds (default: the Age field, or 0)")
+    parser.add_argument(
+        "--target",
+        action="append",
+        help="targeted field to prefer, in order (default CDN-Cache-Control with --shared)",
+    )
+    args = parser.parse_args(argv)
+    if args.age is not None and args.age < 0:
+        parser.error("--age cannot be negative")
+    clock = _Clock(args.age or 0, args.shared)
+    try:
+        if args.value is not None:
+            value = args.value
+            if value.lower().startswith("cache-control:"):
+                value = value.partition(":")[2]
+            name, policy = "Cache-Control", parse(value.strip(), strict=args.strict)
+        else:
+            # ISO-8859-1 maps every octet, so no input byte can stop the program.
+            text = sys.stdin.buffer.read().decode("iso-8859-1")
+            fields = head_fields(text)
+            if fields is None:
+                name, policy = "Cache-Control", parse(text.strip(), strict=args.strict)
+            else:
+                name, policy = _from_head(fields, args, clock)
+    except CacheControlError as error:
+        print(f"ccdirectives: {error}", file=sys.stderr)
+        return EXIT_INVALID
+    print(json.dumps(_report(name, policy, clock), indent=2))
+    return 0

ccdirectives/_errors.py

@@ -0,0 +1,16 @@
+"""The exception raised for input that breaks the rules in strict mode or on build."""
+
+from __future__ import annotations
+
+
+class CacheControlError(ValueError):
+    """A header value or a directive set that breaks the RFC rules.
+
+    ``offset`` is the index in the header value where the problem starts, or None when the
+    error is about a structure rather than a position in text.
+    """
+
+    def __init__(self, message: str, offset: int | None = None) -> None:
+        super().__init__(message if offset is None else f"{message} at offset {offset}")
+        self.reason = message
+        self.offset = offset

ccdirectives/_fresh.py

@@ -0,0 +1,161 @@
+"""Freshness, age and reuse decisions for a stored response (RFC 9111 section 4.2, RFC 5861)."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from ._chars import field_names
+from ._model import CacheControl
+
+
+@dataclass(frozen=True)
+class Freshness:
+    """What a cache may do with a stored response at a given age.
+
+    ``lifetime`` is None when the response carries no explicit expiration; no heuristic is
+    applied, so such a response counts as stale. ``reusable`` means it may be sent without
+    contacting the origin; ``stale_while_revalidate`` that it may be sent while a background
+    revalidation runs; ``stale_if_error`` that it may be sent if the origin fails.
+    """
+
+    lifetime: int | None
+    age: int
+    fresh: bool
+    reusable: bool
+    stale_while_revalidate: bool
+    stale_if_error: bool
+
+    @property
+    def staleness(self) -> int:
+        """Seconds past the end of the lifetime, 0 while fresh."""
+        return max(0, self.age - (self.lifetime or 0))
+
+
+def freshness_lifetime(
+    response: CacheControl,
+    *,
+    shared: bool = False,
+    expires: float | None = None,
+    date: float | None = None,
+) -> int | None:
+    """The freshness lifetime in seconds by the first matching rule of RFC 9111 4.2.1.
+
+    ``s-maxage`` counts for a shared cache, then ``max-age``, then ``expires - date``
+    (both in seconds since the epoch; pass the time of receipt as ``date`` when the
+    response has no Date). A directive that is present but not delta-seconds gives 0, as
+    section 4.2.1 encourages treating invalid freshness information as stale.
+    """
+    for name in ("s-maxage", "max-age") if shared else ("max-age",):
+        if response.has(name):
+            return response.seconds(name) or 0
+    if expires is None:
+        return None
+    if date is None:
+        raise ValueError("pass date (or the time the response was received) with expires")
+    return max(0, math.floor(expires - date))
+
+
+def current_age(
+    *,
+    date_value: float,
+    request_time: float,
+    response_time: float,
+    now: float,
+    age_value: int = 0,
+) -> int:
+    """The current age in whole seconds, rounded up (RFC 9111 section 4.2.3)."""
+    if age_value < 0:
+        raise ValueError("age_value cannot be negative")
+    apparent_age = max(0.0, response_time - date_value)
+    corrected_age_value = age_value + (response_time - request_time)
+    corrected_initial_age = max(apparent_age, corrected_age_value)
+    return max(0, math.ceil(corrected_initial_age + (now - response_time)))
+
+
+def _stale_forbidden(response: CacheControl, shared: bool) -> bool:
+    # RFC 9111 section 4.2.4 lists what forbids serving a stale response.
+    if response.no_cache or response.must_revalidate:
+        return True
+    return shared and (response.proxy_revalidate or response.has("s-maxage"))
+
+
+def assess(
+    response: CacheControl,
+    *,
+    age: int,
+    shared: bool = False,
+    request: CacheControl | None = None,
+    expires: float | None = None,
+    date: float | None = None,
+) -> Freshness:
+    """Decide whether a stored response of ``age`` seconds may be reused.
+
+    The response directives set the lifetime and what forbids stale use (``no-cache``,
+    ``must-revalidate``, and for shared caches ``proxy-revalidate`` and ``s-maxage``);
+    a ``no-cache`` response is never reusable without validation, qualified or not. The
+    optional request directives narrow reuse: ``no-cache``, ``max-age``, ``min-fresh``,
+    and ``max-stale`` to accept a stale response. ``stale-if-error`` in the request takes
+    precedence over the response's for that request (RFC 5861 section 4).
+    """
+    if isinstance(age, bool) or not isinstance(age, int):
+        raise TypeError("age is a whole number of seconds")
+    if age < 0:
+        raise ValueError("age cannot be negative")
+    asked = request if request is not None else CacheControl()
+    lifetime = freshness_lifetime(response, shared=shared, expires=expires, date=date)
+    fresh = lifetime is not None and lifetime > age
+    staleness = max(0, age - (lifetime or 0))
+    forbidden = _stale_forbidden(response, shared)
+    reusable = not response.no_cache and not asked.no_cache
+    if asked.has("max-age"):
+        reusable = reusable and age <= (asked.max_age or 0)
+    if fresh:
+        if asked.has("min-fresh"):
+            reusable = reusable and (lifetime or 0) - age >= (asked.min_fresh or 0)
+    else:
+        allowance = asked.max_stale
+        reusable = reusable and not forbidden and allowance is not None and staleness <= allowance
+    revalidate_window = response.stale_while_revalidate
+    error_window = asked.stale_if_error if asked.has("stale-if-error") else response.stale_if_error
+    stale_ok = not fresh and not forbidden
+    return Freshness(
+        lifetime=lifetime,
+        age=age,
+        fresh=fresh,
+        reusable=reusable,
+        stale_while_revalidate=stale_ok
+        and not asked.no_cache
+        and revalidate_window is not None
+        and staleness <= revalidate_window,
+        stale_if_error=stale_ok and error_window is not None and staleness <= error_window,
+    )
+
+
+def may_store(
+    response: CacheControl,
+    *,
+    shared: bool = False,
+    authorized: bool = False,
+    understood_status: bool = False,
+) -> bool:
+    """Whether the response directives let a cache store the response (RFC 9111 3 and 3.5).
+
+    ``authorized`` is True when the request carried Authorization; ``understood_status``
+    when the cache implements the caching rules of the response's status code, which is
+    what ``must-understand`` asks for and what lets it override ``no-store``. A qualified
+    ``private`` still allows a shared cache to store the response without those fields.
+    Only directives are judged: method, status and freshness rules stay with the caller.
+    """
+    if response.must_understand:
+        if not understood_status:
+            return False
+    elif response.no_store:
+        return False
+    qualifier = response.get("private")
+    unqualified = not isinstance(qualifier, str) or field_names(qualifier) is None
+    if shared and response.private and unqualified:
+        return False
+    if shared and authorized:
+        return response.must_revalidate or response.public or response.has("s-maxage")
+    return True

ccdirectives/_head.py

@@ -0,0 +1,57 @@
+"""Read the fields of a response head, as printed by ``curl -sI``, for the command line."""
+
+from __future__ import annotations
+
+import email.utils
+
+from ._chars import ascii_lower, delta_seconds
+
+
+def head_fields(text: str) -> list[tuple[str, str]] | None:
+    """The fields of the last response head in a dump, or None when it holds no head.
+
+    A redirect chain prints one head per response; the last is the one a cache stores.
+    Continuation lines (obs-fold) join the previous field with a space, as RFC 9112
+    section 5.2 allows a recipient to do.
+    """
+    lines = text.split("\n")
+    starts = [i for i, line in enumerate(lines) if line.startswith("HTTP/")]
+    if not starts:
+        return None
+    fields: list[tuple[str, str]] = []
+    for raw in lines[starts[-1] + 1 :]:
+        line = raw.rstrip("\r")
+        if not line:
+            break
+        if line[0] in " \t":
+            if fields:
+                name, value = fields[-1]
+                fields[-1] = (name, (value + " " + line.strip(" \t")).strip())
+            continue
+        name, colon, value = line.partition(":")
+        if colon and name and name == name.strip():
+            fields.append((name, value.strip(" \t")))
+    return fields
+
+
+def field(fields: list[tuple[str, str]], name: str) -> str | None:
+    """The first value of ``name``, compared case-insensitively."""
+    wanted = ascii_lower(name)
+    return next((value for key, value in fields if ascii_lower(key) == wanted), None)
+
+
+def age_of(fields: list[tuple[str, str]]) -> int:
+    """The Age field as delta-seconds, 0 when absent or invalid (RFC 9111 section 5.1)."""
+    value = field(fields, "Age")
+    return (delta_seconds(value.strip()) or 0) if value is not None else 0
+
+
+def http_date(value: str | None) -> float | None:
+    """Seconds since the epoch for an HTTP-date, or None when it does not parse."""
+    if value is None:
+        return None
+    try:
+        parsed = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError, IndexError):
+        return None
+    return parsed.timestamp() if parsed.tzinfo is not None else None