http-fields 0.1.1__tar.gz → 0.1.2__tar.gz

{http_fields-0.1.1 → http_fields-0.1.2}/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project is in its 0.x series;
 the API may still change between minor versions.
 
+## [0.1.2] - 2026-10-21
+
+### Fixed
+
+- `PreferenceApplied.parse()` returned no preferences, without raising, when abnf 2.9.0 or later
+  was installed, which is what a fresh install of 0.1.1 resolves to. abnf 2.9.0 corrected its
+  RFC 7240 grammar so that `Preference-Applied` items are `applied-pref` rather than Prefer's
+  `preference`, and the visitor was still looking for the old name.
+  ([#53](https://github.com/declaresub/http-fields/issues/53))
+
+### Changed
+
+- Requires `abnf>=2.9.0` (was `>=2.6.0`).
+- `PreferenceApplied.parse()` now rejects parameters (e.g. `respond-async; wait=10`), which
+  RFC 7240 §3 does not allow in `Preference-Applied`.
+- `SetCookie.build()` raises `ValueError` for an empty string in `extension`, which would
+  otherwise serialize as a stray `"; "`.
+
+### Documentation
+
+- The design page gains an "On performance" section.
+
 ## [0.1.1] - 2026-07-22
 
 Initial release published to PyPI as **http-fields** (`import http_fields`).
@@ -47,4 +69,5 @@ stability of a 0.x release. Caught on TestPyPI before the PyPI upload.)
 - Each header's serialized `value` (and `str()`/`bytes()`/`asgi_value`) is computed once and cached
   per instance.
 
+[0.1.2]: https://github.com/declaresub/http-fields/releases/tag/v0.1.2
 [0.1.1]: https://github.com/declaresub/http-fields/releases/tag/v0.1.1

{http_fields-0.1.1 → http_fields-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: http-fields
-Version: 0.1.1
+Version: 0.1.2
 Summary: Typed, immutable HTTP header fields for Python, parsed and validated against RFC ABNF grammars
 Project-URL: Homepage, https://github.com/declaresub/http-fields
 Project-URL: Documentation, https://http-fields.readthedocs.io/
@@ -22,12 +22,18 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.10
-Requires-Dist: abnf>=2.6.0
+Requires-Dist: abnf>=2.9.0
 Requires-Dist: typing-extensions>=4.0
 Description-Content-Type: text/markdown
 
 # http-fields
 
+[![PyPI](https://img.shields.io/pypi/v/http-fields)](https://pypi.org/project/http-fields/)
+[![Python versions](https://img.shields.io/pypi/pyversions/http-fields)](https://pypi.org/project/http-fields/)
+[![CI](https://github.com/declaresub/http-fields/actions/workflows/ci.yml/badge.svg)](https://github.com/declaresub/http-fields/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/http-fields/badge/?version=latest)](https://http-fields.readthedocs.io/)
+[![License](https://img.shields.io/pypi/l/http-fields)](LICENSE.txt)
+
 Typed, validated HTTP headers for Python. Each header is an immutable
 [dataclass](https://docs.python.org/3/library/dataclasses.html) whose fields are the structured
 components of the header. [abnf](https://pypi.org/project/abnf/) grammars are used both to

{http_fields-0.1.1 → http_fields-0.1.2}/README.md

@@ -1,5 +1,11 @@
 # http-fields
 
+[![PyPI](https://img.shields.io/pypi/v/http-fields)](https://pypi.org/project/http-fields/)
+[![Python versions](https://img.shields.io/pypi/pyversions/http-fields)](https://pypi.org/project/http-fields/)
+[![CI](https://github.com/declaresub/http-fields/actions/workflows/ci.yml/badge.svg)](https://github.com/declaresub/http-fields/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/http-fields/badge/?version=latest)](https://http-fields.readthedocs.io/)
+[![License](https://img.shields.io/pypi/l/http-fields)](LICENSE.txt)
+
 Typed, validated HTTP headers for Python. Each header is an immutable
 [dataclass](https://docs.python.org/3/library/dataclasses.html) whose fields are the structured
 components of the header. [abnf](https://pypi.org/project/abnf/) grammars are used both to

http_fields-0.1.2/SECURITY.md

@@ -0,0 +1,68 @@
+# Security Policy
+
+`http-fields` parses and validates HTTP header values, often from untrusted input, so
+correctness of that validation is a security property (e.g. rejecting CR/LF/NUL to prevent
+response splitting / header injection).
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately**, not via a public issue:
+
+- Preferred: GitHub's **"Report a vulnerability"** button on the repository's *Security* tab
+  (private vulnerability reporting).
+- Alternatively, email the maintainer at **charles@declaresub.com**.
+
+Please include a description, affected version/commit, and a minimal reproduction. You'll get
+an acknowledgement, and we'll coordinate a fix and disclosure with you.
+
+## Supported versions
+
+This project is in its 0.x series. Security fixes land on the latest released version, so please
+confirm the issue against the newest `0.x` release before reporting.
+
+| Version | Supported                                                     |
+| ------- | ------------------------------------------------------------- |
+| 0.1.x   | ✅                                                            |
+| 0.1.0   | ❌ — tagged but never published to PyPI; use 0.1.1 or later    |
+
+## Verifying a release
+
+Releases are built and published by a GitHub Actions workflow
+([`publish.yml`](.github/workflows/publish.yml)) from a signed tag, using **trusted publishing**
+(OIDC — there are no long-lived PyPI API tokens that could be stolen). Both publish steps require
+a manual approval in a protected environment. Every release is independently verifiable —
+substitute the version you are checking for `0.1.1` below.
+
+### PyPI attestations (PEP 740)
+
+Artifacts on PyPI carry attestations binding them to this repository and workflow:
+
+```sh
+pip download --no-deps http-fields==0.1.1
+uvx pypi-attestations verify pypi \
+  --repository https://github.com/declaresub/http-fields \
+  http_fields-0.1.1-py3-none-any.whl
+```
+
+The provenance can also be inspected directly:
+<https://pypi.org/integrity/http-fields/0.1.1/http_fields-0.1.1-py3-none-any.whl/provenance>
+
+It should name the publisher as repository `declaresub/http-fields`, workflow `publish.yml`,
+environment `pypi`.
+
+### Sigstore bundles
+
+Each GitHub release attaches the wheel and sdist together with a `.sigstore.json` bundle:
+
+```sh
+gh release download v0.1.1 --repo declaresub/http-fields
+uvx sigstore verify identity \
+  --cert-identity "https://github.com/declaresub/http-fields/.github/workflows/publish.yml@refs/tags/v0.1.1" \
+  --cert-oidc-issuer "https://token.actions.githubusercontent.com" \
+  http_fields-0.1.1-py3-none-any.whl http_fields-0.1.1.tar.gz
+```
+
+### SBOM
+
+Each release also attaches a CycloneDX SBOM (`http-fields.cdx.json`) describing the package's
+runtime dependency closure (build and development tooling are excluded).

{http_fields-0.1.1 → http_fields-0.1.2}/docs/explanation/design.md

@@ -56,6 +56,35 @@ There is a single, consistent way to make headers:
 This is a deliberate break from the older overloaded "string *or* pieces" constructors: one
 object, one obvious way to build it, and precise types throughout.
 
+## On performance
+
+Correctness comes first, deliberately. Header handling has a long history of vulnerabilities —
+request smuggling, response splitting, header injection — and they are almost never caused by
+slow code. They come from *disagreement*: two hand-written parsers in a chain resolve the same
+bytes differently (`Content-Length` versus `Transfer-Encoding` precedence, obs-fold continuation
+lines, whitespace before the colon, repeated fields), and the gap between them is the
+vulnerability. Driving every header from its RFC ABNF removes the room in which such a divergence
+can appear — the grammar *is* the specification, so there is no shortcut available to quietly
+disagree with it.
+
+The same reasoning applies on the way out, and that direction is easy to overlook. Response
+splitting usually originates not in a parser but in application code interpolating
+attacker-influenced data *into* a header it is building. That is why validity here is a property
+of the field types rather than a check performed by `parse()`: an invalid value cannot be held in
+the first place, so *every* construction path — not just `parse()` — rejects CR/LF/NUL.
+
+None of this is an argument for being gratuitously slow. A header is parsed at most once (see
+above), and each header's serialized `value` is computed once and cached per instance, so the
+common paths avoid repeated work.
+
+What is deliberately *not* claimed is a throughput figure. There are no benchmarks, and raw
+parsing speed has neither been measured nor tuned. If it ever matters, the measurement worth
+making is not headers per second but **worst-case behaviour on hostile input**: grammar
+backtracking can be super-linear, which turns a pathological value into an algorithmic
+denial of service. That is a correctness property wearing a performance costume — and it is why
+`parse()` bounds the length of its input (`Header.max_length`, 8192 by default and overridable
+per subclass) before running the grammar at all.
+
 ## Shared bases where shapes repeat
 
 Families that share an identical shape are factored onto a common base — dates (`DateHeader`),

{http_fields-0.1.1 → http_fields-0.1.2}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-    "abnf>=2.6.0",
+    "abnf>=2.9.0",
     "typing_extensions>=4.0",
 ]
 dynamic = ["version"]
@@ -77,6 +77,12 @@ testpaths = ["tests"]
 [tool.ruff]
 src = ["src", "tests"]
 
+[tool.ruff.format]
+# Ruff >= 0.16 formats Python code blocks in Markdown by default. Prose snippets are
+# written for reading (aligned trailing comments, elided bodies), not for the formatter,
+# so keep Markdown out of the formatter's scope.
+exclude = ["*.md"]
+
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B"]
 # The formatter owns code line length (88 cols); E501 only fires on strings,

{http_fields-0.1.1 → http_fields-0.1.2}/src/http_fields/setcookie.py

@@ -256,6 +256,10 @@ class SetCookie(Header):
         # the RFC 6265 grammar requires max-age to be positive; this is almost universally
         # ignored, so we go with the crowd and clamp negatives to 0.
         normalized_max_age = 0 if max_age and max_age < 0 else max_age
+        # extension-av's prose rule admits the empty string, but an empty attribute
+        # would serialize as a stray "; ".
+        if extension and not all(extension):
+            raise ValueError("Invalid extension value.")
         try:
             ext = (
                 tuple(

{http_fields-0.1.1 → http_fields-0.1.2}/src/http_fields/visitors/rfc7240.py

@@ -70,8 +70,9 @@ class PreferVisitor(NodeVisitor):
 
 
 class PreferenceAppliedVisitor(PreferVisitor):
-    # RFC 7240's abnf uses the same `preference` production for Preference-Applied.
+    # Preference-Applied items are `applied-pref`: token [ BWS "=" BWS word ], no
+    # parameters -- a subset of `preference`, so visit_preference handles them.
     def visit_preference_applied(self, node: Node) -> list[Preference]:
         return [
-            self.visit_preference(c) for c in node.children if c.name == "preference"
+            self.visit_preference(c) for c in node.children if c.name == "applied-pref"
         ]

{http_fields-0.1.1 → http_fields-0.1.2}/tests/test_prefer.py

@@ -1,3 +1,5 @@
+import pytest
+
 from http_fields import Header, Prefer, PreferenceApplied
 from http_fields.visitors.rfc7240 import Preference
 
@@ -20,6 +22,21 @@ def test_preference_applied_parse():
     assert header.preferences == (Preference("return", "representation"),)
 
 
+def test_preference_applied_parse_multiple():
+    header = PreferenceApplied.parse("return=minimal, respond-async")
+    assert header.preferences == (
+        Preference("return", "minimal"),
+        Preference("respond-async"),
+    )
+
+
+@pytest.mark.parametrize("value", ["respond-async; wait=10", "return=minimal; x"])
+def test_preference_applied_rejects_parameters(value: str):
+    # RFC 7240 section 3: applied-pref carries no parameters, unlike Prefer's preference.
+    with pytest.raises(ValueError):
+        PreferenceApplied.parse(value)
+
+
 def test_prefer_create():
     assert isinstance(Header.create("prefer", "respond-async"), Prefer)
     assert isinstance(

http_fields-0.1.1/SECURITY.md

@@ -1,26 +0,0 @@
-# Security Policy
-
-`http-fields` parses and validates HTTP header values, often from untrusted input, so
-correctness of that validation is a security property (e.g. rejecting CR/LF/NUL to prevent
-response splitting / header injection).
-
-## Reporting a vulnerability
-
-Please report suspected vulnerabilities **privately**, not via a public issue:
-
-- Preferred: GitHub's **"Report a vulnerability"** button on the repository's *Security* tab
-  (private vulnerability reporting).
-- Alternatively, email the maintainer at **charles@declaresub.com**.
-
-Please include a description, affected version/commit, and a minimal reproduction. You'll get
-an acknowledgement, and we'll coordinate a fix and disclosure with you.
-
-## Supported versions
-
-This project is **pre-release** (no tagged release yet); the latest `master` is the supported
-version. Once releases are published, this section will list the supported release lines.
-
-## Verifying a release
-
-Once releases are published to PyPI, this section will describe how to verify a release's
-provenance (build attestations / Sigstore bundle and the attached SBOM).