chunkedte 0.2.0__py3-none-any.whl

chunkedte/__init__.py

@@ -0,0 +1,22 @@
+"""Strict, incremental, typed, zero-dependency codec for HTTP/1.1 chunked transfer coding."""
+
+from __future__ import annotations
+
+from ._decode import Decoder, decode
+from ._encode import Encoder, encode
+from ._errors import ChunkedError, LimitError
+from ._framing import is_chunked
+from ._limits import Limits
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ChunkedError",
+    "Decoder",
+    "Encoder",
+    "LimitError",
+    "Limits",
+    "decode",
+    "encode",
+    "is_chunked",
+]

chunkedte/__main__.py

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

chunkedte/_cli.py

@@ -0,0 +1,87 @@
+"""Command line front end: ``chunkedte decode`` and ``chunkedte encode`` over files or stdio."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import BinaryIO, TextIO
+
+from ._decode import Decoder
+from ._encode import DEFAULT_CHUNK_SIZE, Encoder, encode
+from ._errors import ChunkedError
+
+_BLOCK = 65536
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="chunkedte", description="Decode or encode HTTP/1.1 chunked transfer coding."
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    decode = commands.add_parser("decode", help="print the body; trailers go to stderr")
+    decode.add_argument("file", nargs="?", help="input file (default: stdin)")
+    encode = commands.add_parser("encode", help="frame the input as a chunked body")
+    encode.add_argument("file", nargs="?", help="input file (default: stdin)")
+    encode.add_argument("--chunk-size", type=int, default=DEFAULT_CHUNK_SIZE)
+    encode.add_argument(
+        "--trailer", action="append", default=[], metavar="NAME:VALUE", help="repeatable"
+    )
+    return parser
+
+
+def main(
+    argv: list[str] | None = None,
+    stdin: BinaryIO | None = None,
+    stdout: BinaryIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    """Run the command line tool and return its exit status."""
+    args = _parser().parse_args(argv)
+    out = sys.stdout.buffer if stdout is None else stdout
+    err = sys.stderr if stderr is None else stderr
+    source = (sys.stdin.buffer if stdin is None else stdin) if args.file is None else None
+    try:
+        if source is None:
+            with open(args.file, "rb") as handle:
+                return _run(args, handle, out, err)
+        return _run(args, source, out, err)
+    except (ChunkedError, ValueError, OSError) as error:
+        print(f"chunkedte: {error}", file=err)
+        return 1
+
+
+def _run(args: argparse.Namespace, source: BinaryIO, out: BinaryIO, err: TextIO) -> int:
+    if args.command == "decode":
+        return _decode(source, out, err)
+    if args.chunk_size <= 0:
+        raise ValueError("--chunk-size must be positive")
+    trailers = [_split_trailer(text) for text in args.trailer]
+    closing = encode(b"", trailers=trailers)  # validates the trailers before any output
+    encoder = Encoder()
+    while block := source.read(args.chunk_size):
+        out.write(encoder.write(block))
+    out.write(closing)
+    return 0
+
+
+def _decode(source: BinaryIO, out: BinaryIO, err: TextIO) -> int:
+    decoder = Decoder()
+    while not decoder.is_complete and (block := source.read(_BLOCK)):
+        for piece in decoder.feed(block):
+            out.write(piece)
+    if not decoder.is_complete:
+        raise ChunkedError("incomplete chunked message")
+    if decoder.unused_data or source.read(1):
+        raise ChunkedError("bytes after the end of the chunked message")
+    for name, value in decoder.trailers:
+        # Escape obs-text and C1 bytes so any terminal encoding can print them.
+        safe = value.encode("latin-1").decode("ascii", "backslashreplace")
+        print(f"{name}: {safe}", file=err)
+    return 0
+
+
+def _split_trailer(text: str) -> tuple[str, str]:
+    name, colon, value = text.partition(":")
+    if not colon:
+        raise ValueError(f"--trailer needs NAME:VALUE, got {text!r}")
+    return name, value.strip(" \t")

chunkedte/_decode.py

@@ -0,0 +1,177 @@
+"""Incremental, strict decoder for HTTP/1.1 chunked transfer coding (RFC 9112 section 7.1)."""
+
+from __future__ import annotations
+
+import enum
+
+from ._errors import ChunkedError, LimitError
+from ._grammar import SIZE_LINE, parse_field_line
+from ._limits import Limits
+
+_CR = 0x0D
+# Sixteen significant hex digits hold any value below 2**64; more is never a real size.
+_MAX_SIZE_DIGITS = 16
+
+
+class _State(enum.Enum):
+    SIZE = enum.auto()
+    DATA = enum.auto()
+    DATA_CRLF = enum.auto()
+    TRAILERS = enum.auto()
+    DONE = enum.auto()
+
+
+class Decoder:
+    """Feed chunked bytes in any split and collect the decoded body pieces.
+
+    Size lines, chunk extensions and trailer fields are checked against the RFC 9112
+    grammar; only CRLF ends a line. Extensions are validated and then ignored, trailer
+    fields are kept in :attr:`trailers` (keep them apart from the header section, RFC 9110
+    section 6.5.2). Bytes after the final CRLF land in :attr:`unused_data`. When
+    :meth:`feed` raises, the pieces decoded in that call are dropped, and every later
+    :meth:`feed` raises again.
+    """
+
+    def __init__(self, limits: Limits | None = None) -> None:
+        self._limits = Limits() if limits is None else limits
+        self._buffer = bytearray()
+        self._scanned = 0
+        self._state = _State.SIZE
+        self._remaining = 0
+        self._body_size = 0
+        self._extensions_size = 0
+        self._trailer_size = 0
+        self._trailers: list[tuple[str, str]] = []
+        self._error: ChunkedError | None = None
+
+    @property
+    def is_complete(self) -> bool:
+        """Whether the last chunk and the trailer section have been fully consumed."""
+        return self._state is _State.DONE
+
+    @property
+    def trailers(self) -> list[tuple[str, str]]:
+        """Trailer fields received so far as ``(name, value)`` pairs, in arrival order."""
+        return list(self._trailers)
+
+    @property
+    def unused_data(self) -> bytes:
+        """Bytes received after the end of the chunked message (for example the next request)."""
+        return bytes(self._buffer) if self._state is _State.DONE else b""
+
+    def feed(self, data: bytes | bytearray | memoryview) -> list[bytes]:
+        """Append ``data`` and return every decoded body piece now available."""
+        if self._error is not None:
+            raise ChunkedError(f"the decoder already failed: {self._error}")
+        self._buffer += data
+        out: list[bytes] = []
+        try:
+            while self._step(out):
+                pass
+        except ChunkedError as error:
+            self._error = error
+            raise
+        return out
+
+    def _step(self, out: list[bytes]) -> bool:
+        if self._state is _State.SIZE:
+            return self._read_size()
+        if self._state is _State.DATA:
+            return self._read_data(out)
+        if self._state is _State.DATA_CRLF:
+            return self._read_data_crlf()
+        if self._state is _State.TRAILERS:
+            return self._read_trailer()
+        return False
+
+    def _read_size(self) -> bool:
+        line = self._take_line(self._limits.max_line_size, "chunk-size line")
+        if line is None:
+            return False
+        match = SIZE_LINE.fullmatch(line)
+        if match is None:
+            raise ChunkedError(f"malformed chunk-size line: {line[:64]!r}")
+        digits, extensions = match.group(1, 2)
+        self._extensions_size += len(extensions)
+        if self._extensions_size > self._limits.max_extensions_size:
+            raise LimitError("chunk extensions exceed max_extensions_size")
+        if len(digits.lstrip(b"0")) > _MAX_SIZE_DIGITS:
+            raise LimitError("chunk size exceeds max_chunk_size")
+        size = int(digits, 16)
+        if size > self._limits.max_chunk_size:
+            raise LimitError("chunk size exceeds max_chunk_size")
+        cap = self._limits.max_body_size
+        if cap is not None and self._body_size + size > cap:
+            raise LimitError("body exceeds max_body_size")
+        self._remaining = size
+        self._state = _State.DATA if size else _State.TRAILERS
+        return True
+
+    def _read_data(self, out: list[bytes]) -> bool:
+        if not self._buffer:
+            return False
+        take = min(self._remaining, len(self._buffer))
+        out.append(bytes(self._buffer[:take]))
+        del self._buffer[:take]
+        self._remaining -= take
+        self._body_size += take
+        if self._remaining == 0:
+            self._state = _State.DATA_CRLF
+        return True
+
+    def _read_data_crlf(self) -> bool:
+        # Fail on the first wrong byte: any two bytes here is the h11 smuggling bug.
+        head = bytes(self._buffer[:2])
+        if not b"\r\n".startswith(head):
+            raise ChunkedError("chunk data not followed by CRLF")
+        if len(head) < 2:
+            return False
+        del self._buffer[:2]
+        self._state = _State.SIZE
+        return True
+
+    def _read_trailer(self) -> bool:
+        budget = max(self._limits.max_trailer_size - self._trailer_size - 2, 0)
+        line = self._take_line(budget, "trailer section")
+        if line is None:
+            return False
+        if not line:
+            self._state = _State.DONE
+            return False
+        self._trailer_size += len(line) + 2
+        self._trailers.append(parse_field_line(line))
+        return True
+
+    def _take_line(self, limit: int, what: str) -> bytes | None:
+        """Cut one CRLF-terminated line off the buffer, scanning each byte only once."""
+        end = self._buffer.find(b"\n", self._scanned)
+        if end == -1:
+            self._scanned = len(self._buffer)
+            if self._scanned > limit + 1:
+                raise LimitError(f"{what} exceeds its limit")
+            return None
+        self._scanned = 0
+        if end == 0 or self._buffer[end - 1] != _CR:
+            raise ChunkedError(f"bare LF in the {what}")
+        if end - 1 > limit:
+            raise LimitError(f"{what} exceeds its limit")
+        line = bytes(self._buffer[: end - 1])
+        del self._buffer[: end + 1]
+        if _CR in line:
+            raise ChunkedError(f"bare CR in the {what}")
+        return line
+
+
+def decode(data: bytes | bytearray | memoryview, *, limits: Limits | None = None) -> bytes:
+    """Decode one complete chunked message and return the body.
+
+    Raises :class:`ChunkedError` if the message is malformed, not terminated, or followed
+    by more bytes.
+    """
+    decoder = Decoder(limits)
+    pieces = decoder.feed(data)
+    if not decoder.is_complete:
+        raise ChunkedError("incomplete chunked message")
+    if decoder.unused_data:
+        raise ChunkedError("bytes after the end of the chunked message")
+    return b"".join(pieces)

chunkedte/_encode.py

@@ -0,0 +1,82 @@
+"""Encode bytes as an HTTP/1.1 chunked body, in one call or incrementally."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from ._errors import ChunkedError
+from ._grammar import format_field_line
+
+DEFAULT_CHUNK_SIZE = 8192
+
+Trailers = Mapping[str, str] | Iterable[tuple[str, str]]
+
+
+class Encoder:
+    """Frame body pieces as chunks as they are produced, then close the message.
+
+    :meth:`write` turns one piece into one chunk (an empty piece yields nothing, since a
+    zero-size chunk would end the message); :meth:`finish` writes the last chunk and the
+    optional trailer section. Trailer names must be tokens and values field-values, and
+    fields that frame or route a message (Content-Length, Transfer-Encoding, Host, ...)
+    are refused as trailers.
+    """
+
+    def __init__(self) -> None:
+        self._finished = False
+
+    def write(self, data: bytes | bytearray | memoryview) -> bytes:
+        """Return ``data`` framed as one chunk."""
+        if self._finished:
+            raise ChunkedError("write after finish")
+        piece = _as_bytes(data)
+        if not piece:
+            return b""
+        return b"%x\r\n%b\r\n" % (len(piece), piece)
+
+    def finish(self, trailers: Trailers | None = None) -> bytes:
+        """Return the last chunk, the trailer section and the closing CRLF."""
+        if self._finished:
+            raise ChunkedError("finish called twice")
+        lines = [format_field_line(name, value) + b"\r\n" for name, value in _pairs(trailers)]
+        self._finished = True
+        return b"0\r\n" + b"".join(lines) + b"\r\n"
+
+
+def encode(
+    data: bytes | bytearray | memoryview,
+    *,
+    chunk_size: int = DEFAULT_CHUNK_SIZE,
+    trailers: Trailers | None = None,
+) -> bytes:
+    """Frame ``data`` as a complete chunked body split into ``chunk_size`` pieces.
+
+    The result is ``<hex-size>CRLF<data>CRLF`` chunks, then ``0CRLF``, the trailer fields
+    and the closing CRLF. An empty ``data`` yields just the last chunk.
+    """
+    if not isinstance(chunk_size, int) or isinstance(chunk_size, bool):
+        raise TypeError("chunk_size must be an int")
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+    body = _as_bytes(data)
+    encoder = Encoder()
+    parts = [encoder.write(body[at : at + chunk_size]) for at in range(0, len(body), chunk_size)]
+    parts.append(encoder.finish(trailers))
+    return b"".join(parts)
+
+
+def _as_bytes(data: bytes | bytearray | memoryview) -> bytes:
+    # bytes(5) would silently build five NUL bytes.
+    if not isinstance(data, (bytes, bytearray, memoryview)):
+        raise TypeError(f"expected a bytes-like object, got {type(data).__name__}")
+    return bytes(data)
+
+
+def _pairs(trailers: Trailers | None) -> list[tuple[str, str]]:
+    if trailers is None:
+        return []
+    if isinstance(trailers, (str, bytes)):
+        raise TypeError("trailers must be a mapping or (name, value) pairs")
+    if isinstance(trailers, Mapping):
+        return list(trailers.items())
+    return [(name, value) for name, value in trailers]

chunkedte/_errors.py

@@ -0,0 +1,11 @@
+"""Errors raised for malformed or oversized chunked messages."""
+
+from __future__ import annotations
+
+
+class ChunkedError(ValueError):
+    """A chunked message or a framing field breaks RFC 9112 (answer with 400)."""
+
+
+class LimitError(ChunkedError):
+    """A configured :class:`Limits` bound was passed (answer with 413 or 431)."""

chunkedte/_framing.py

@@ -0,0 +1,66 @@
+"""Decide from Transfer-Encoding and Content-Length whether a body is chunked."""
+
+from __future__ import annotations
+
+import re
+
+from ._errors import ChunkedError
+
+_TOKEN = r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+"
+_QUOTED = r'"(?:[\t \x21\x23-\x5b\x5d-\x7e\x80-\xff]|\\[\t \x21-\x7e\x80-\xff])*"'
+# RFC 9110 section 10.1.4: transfer-coding = token *( OWS ";" OWS transfer-parameter ).
+_CODING = re.compile(rf"({_TOKEN})((?:[ \t]*;[ \t]*{_TOKEN}[ \t]*=[ \t]*(?:{_TOKEN}|{_QUOTED}))*)")
+# The trailing OWS sits inside the optional group: two adjacent OWS runs backtrack
+# quadratically on a long run of spaces.
+_MEMBER = re.compile(rf"[ \t]*(?:{_CODING.pattern}[ \t]*)?(?:,|\Z)")
+
+
+def is_chunked(
+    transfer_encoding: str | None,
+    content_length: str | None = None,
+    *,
+    request: bool = True,
+) -> bool:
+    """Whether a message body is framed by the chunked coding (RFC 9112 sections 6.1, 6.3).
+
+    Pass the field values as received, joining repeated lines with ``", "``, or ``None``
+    when a field is absent. Returns ``False`` when there is no Transfer-Encoding, and for a
+    response whose final coding is not chunked (it is read until the connection closes).
+    Raises :class:`ChunkedError` when both fields are present, when chunked is applied
+    twice or carries parameters, when a request's final coding is not chunked, and when the
+    field is not a valid list of transfer codings.
+
+    The caller still applies the rest of RFC 9112 section 6.3: responses to HEAD, 1xx, 204,
+    304 and 2xx to CONNECT have no body, and an HTTP/1.0 message with Transfer-Encoding has
+    faulty framing (section 6.1).
+    """
+    if transfer_encoding is None:
+        return False
+    if content_length is not None:
+        raise ChunkedError("both Transfer-Encoding and Content-Length are present")
+    codings = _parse_codings(transfer_encoding)
+    if not codings:
+        raise ChunkedError("Transfer-Encoding lists no transfer coding")
+    chunked = [index for index, (name, _) in enumerate(codings) if name == "chunked"]
+    if len(chunked) > 1:
+        raise ChunkedError("chunked is applied more than once")
+    if chunked and codings[chunked[0]][1]:
+        raise ChunkedError("the chunked coding does not take parameters")
+    if chunked and chunked[0] == len(codings) - 1:
+        return True
+    if request:
+        raise ChunkedError("chunked is not the final transfer coding of a request")
+    return False
+
+
+def _parse_codings(value: str) -> list[tuple[str, str]]:
+    codings: list[tuple[str, str]] = []
+    position = 0
+    while position < len(value):
+        match = _MEMBER.match(value, position)
+        if match is None or match.end() == position:
+            raise ChunkedError(f"malformed Transfer-Encoding: {value[:64]!r}")
+        if match.group(1) is not None:
+            codings.append((match.group(1).lower(), match.group(2)))
+        position = match.end()
+    return codings

chunkedte/_grammar.py

@@ -0,0 +1,85 @@
+"""RFC 9112 and RFC 9110 grammar for size lines and field lines, as byte regexes."""
+
+from __future__ import annotations
+
+import re
+
+from ._errors import ChunkedError
+
+# RFC 9110 section 5.6.2: tchar is any VCHAR except the delimiters.
+TCHAR = rb"!#$%&'*+\-.^_`|~0-9A-Za-z"
+TOKEN = rb"[" + TCHAR + rb"]+"
+# RFC 9110 section 5.6.4: qdtext and quoted-pair; obs-text is %x80-FF.
+QDTEXT = rb"[\t \x21\x23-\x5b\x5d-\x7e\x80-\xff]"
+QUOTED_PAIR = rb"\\[\t \x21-\x7e\x80-\xff]"
+QUOTED_STRING = rb'"(?:' + QDTEXT + rb"|" + QUOTED_PAIR + rb')*"'
+BWS = rb"[ \t]*"
+# RFC 9112 section 7.1.1: chunk-ext = *( BWS ";" BWS name [ BWS "=" BWS value ] ).
+CHUNK_EXT = (
+    rb"(?:" + BWS + rb";" + BWS + TOKEN
+    + rb"(?:" + BWS + rb"=" + BWS + rb"(?:" + TOKEN + rb"|" + QUOTED_STRING + rb"))?)*"
+)  # fmt: skip
+SIZE_LINE = re.compile(rb"([0-9A-Fa-f]+)(" + CHUNK_EXT + rb")")
+FIELD_NAME = re.compile(TOKEN + rb":")
+# RFC 9110 section 5.5: field-vchar, SP and HTAB; the ends are checked by stripping OWS.
+FIELD_VALUE = re.compile(rb"[\t \x21-\x7e\x80-\xff]*")
+TOKEN_RE = re.compile(TOKEN)
+
+# Fields needed before the content (framing, routing, connection control, authentication,
+# request modifiers, response controls, content format: RFC 9110 section 6.5.1) cannot be
+# sent as trailers, so the encoder refuses them.
+FORBIDDEN_TRAILERS = frozenset(
+    {
+        "authorization",
+        "cache-control",
+        "connection",
+        "content-encoding",
+        "content-length",
+        "content-range",
+        "content-type",
+        "cookie",
+        "expect",
+        "host",
+        "keep-alive",
+        "max-forwards",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "range",
+        "set-cookie",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+        "www-authenticate",
+    }
+)
+
+
+def parse_field_line(line: bytes) -> tuple[str, str]:
+    """Split one trailer field line into its name and its OWS-trimmed value."""
+    if line[:1] in (b" ", b"\t"):
+        raise ChunkedError("obsolete line folding in the trailer section")
+    match = FIELD_NAME.match(line)
+    if match is None:
+        raise ChunkedError(f"malformed trailer field line: {line[:64]!r}")
+    value = line[match.end() :].strip(b" \t")
+    if not FIELD_VALUE.fullmatch(value):
+        raise ChunkedError(f"invalid byte in trailer field value: {line[:64]!r}")
+    return line[: match.end() - 1].decode("ascii"), value.decode("latin-1")
+
+
+def format_field_line(name: str, value: str) -> bytes:
+    """Validate one trailer field for sending and return ``name: value`` as bytes."""
+    if not isinstance(name, str) or not isinstance(value, str):
+        raise TypeError("trailer names and values must be str")
+    try:
+        raw_name, raw_value = name.encode("ascii"), value.encode("latin-1")
+    except UnicodeEncodeError:
+        raise ChunkedError(f"trailer field {name!r} is not latin-1 text") from None
+    if not TOKEN_RE.fullmatch(raw_name):
+        raise ChunkedError(f"trailer name is not a token: {name!r}")
+    if name.lower() in FORBIDDEN_TRAILERS:
+        raise ChunkedError(f"{name} cannot be sent as a trailer field")
+    if not FIELD_VALUE.fullmatch(raw_value) or raw_value != raw_value.strip(b" \t"):
+        raise ChunkedError(f"invalid trailer value for {name}: {value!r}")
+    return raw_name + b": " + raw_value

chunkedte/_limits.py

@@ -0,0 +1,33 @@
+"""Bounds that keep a decoder's memory and work proportional to what the caller allows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+
+@dataclass(frozen=True)
+class Limits:
+    """Upper bounds applied while decoding; passing one raises :class:`LimitError`.
+
+    ``max_line_size`` bounds one chunk-size line (size plus extensions, CRLF excluded),
+    ``max_extensions_size`` the extension bytes of the whole message, ``max_chunk_size`` the
+    value of one chunk-size, ``max_body_size`` the decoded body (``None`` for no bound) and
+    ``max_trailer_size`` the trailer field lines including their CRLFs.
+    """
+
+    max_line_size: int = 4096
+    max_extensions_size: int = 16384
+    # Below 2**63 so a forwarded size never wraps in a downstream signed 64-bit parser.
+    max_chunk_size: int = 2**63 - 1
+    max_body_size: int | None = None
+    max_trailer_size: int = 16384
+
+    def __post_init__(self) -> None:
+        for field in fields(self):
+            value = getattr(self, field.name)
+            if value is None and field.name == "max_body_size":
+                continue
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise TypeError(f"{field.name} must be an int, got {type(value).__name__}")
+            if value < 0:
+                raise ValueError(f"{field.name} must not be negative")

chunkedte-0.2.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: chunkedte
+Version: 0.2.0
+Summary: Strict, incremental, typed, zero-dependency codec for HTTP/1.1 chunked transfer coding
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/chunkedte
+Project-URL: Issues, https://github.com/JaviLianes8/chunkedte/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/chunkedte/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chunked,codec,http,request-smuggling,rfc9112,trailers,transfer-encoding
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chunkedte
+
+Strict, incremental, typed, zero-dependency codec for HTTP/1.1 chunked transfer coding
+(RFC 9112 section 7.1).
+
+## Install
+
+```
+pip install chunkedte
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Usage
+
+Decode a complete message in one call. `decode` raises `ChunkedError` if the message is
+malformed, unfinished, or followed by more bytes:
+
+```python
+from chunkedte import ChunkedError, decode
+
+print(decode(b"5\r\nhello\r\n0\r\n\r\n"))
+try:
+    decode(b"0x5\r\nhello\r\n0\r\n\r\n")
+except ChunkedError as error:
+    print(error)
+# b'hello'
+# malformed chunk-size line: b'0x5'
+```
+
+Decode incrementally as bytes arrive off a socket. `Decoder.feed` takes any split and
+returns the body pieces available so far; trailer fields and whatever follows the message
+(a pipelined request, say) are kept apart:
+
+```python
+from chunkedte import Decoder
+
+decoder = Decoder()
+body = b""
+for part in [b"4\r\nwi", b"ki\r\n5;sig=ab\r\npedia\r\n0\r\nDigest: x\r\n", b"\r\nGET /"]:
+    for piece in decoder.feed(part):
+        body += piece
+print(body, decoder.is_complete)
+print(decoder.trailers, decoder.unused_data)
+# b'wikipedia' True
+# [('Digest', 'x')] b'GET /'
+```
+
+Bound what a peer can make you buffer. Passing a bound raises `LimitError`, a subclass of
+`ChunkedError`, so a server can answer 413 or 431 instead of 400:
+
+```python
+from chunkedte import Decoder, LimitError, Limits
+
+decoder = Decoder(Limits(max_body_size=1024, max_trailer_size=4096))
+try:
+    decoder.feed(b"10000\r\n")
+except LimitError as error:
+    print(error)
+print(Limits())
+# body exceeds max_body_size
+# Limits(max_line_size=4096, max_extensions_size=16384, max_chunk_size=9223372036854775807, max_body_size=None, max_trailer_size=16384)
+```
+
+Encode in one call, or stream with `Encoder` and close with optional trailer fields:
+
+```python
+from chunkedte import Encoder, encode
+
+print(encode(b"abcd", chunk_size=2))
+encoder = Encoder()
+print(encoder.write(b"hello") + encoder.finish({"X-Checksum": "42"}))
+# b'2\r\nab\r\n2\r\ncd\r\n0\r\n\r\n'
+# b'5\r\nhello\r\n0\r\nX-Checksum: 42\r\n\r\n'
+```
+
+Decide whether a message body is chunked at all from its Transfer-Encoding and
+Content-Length values (`None` when absent). `is_chunked` applies RFC 9112 sections 6.1 and
+6.3 and raises `ChunkedError` on the combinations used for request smuggling:
+
+```python
+from chunkedte import ChunkedError, is_chunked
+
+print(is_chunked("gzip, chunked"), is_chunked(None, "12"))
+print(is_chunked("gzip", request=False))
+for te, cl in [("chunked", "12"), ("chunked, chunked", None), ("chunked, gzip", None)]:
+    try:
+        is_chunked(te, cl)
+    except ChunkedError as error:
+        print(error)
+# True False
+# False
+# both Transfer-Encoding and Content-Length are present
+# chunked is applied more than once
+# chunked is not the final transfer coding of a request
+```
+
+### Command line
+
+```
+$ printf '5\r\nhello\r\n0\r\nX-Sum: 1\r\n\r\n' | chunkedte decode
+hello
+X-Sum: 1
+$ printf 'abc' | chunkedte encode --chunk-size 2 --trailer "X-Sum: 1"
+```
+
+`decode` writes the body to stdout and the trailer fields to stderr; `encode` frames stdin
+(or a file) as a chunked body. Both exit with status 1 and a message on bad input; body
+bytes decoded before the error may already be on stdout, so treat the output of a failed
+run as truncated. Trailer bytes outside printable ASCII are written as escapes.
+`python -m chunkedte` works too.
+
+## What "strict" means here
+
+Every leniency in a chunked parser is a way for two HTTP processors to disagree on where a
+message ends, which is how request smuggling works. So the decoder rejects:
+
+- a chunk size that is not only hex digits (`+5`, `0x5`, `5_0`, ` 5`, `5 `);
+- chunk extensions that do not follow the grammar (whitespace is allowed only around `;`
+  and `=`, values are tokens or quoted strings);
+- a bare LF or a bare CR anywhere a CRLF is expected, including inside an extension;
+- anything other than CRLF right after the chunk data;
+- trailer lines that are not `name: value`, with whitespace before the colon, with control
+  bytes, or folded onto a continuation line (obs-fold).
+
+Extensions are validated and then ignored, as RFC 9112 asks. The default `Limits` cap one
+size line at 4 KiB, all extensions of a message at 16 KiB, the trailer section at 16 KiB and
+a chunk size below 2**63 (so a forwarded size never wraps in a 64-bit parser); the body is
+unbounded unless you set `max_body_size`. A line split over many small reads is scanned
+once, so decoding stays linear in the input. When `feed` raises, the pieces decoded in that
+call are dropped with it. Received trailers are returned as they came: RFC 9110 section
+6.5.2 says not to merge them into the header section, so keep them apart (a `Content-Length`
+trailer, say, must never reach your framing logic). The encoder refuses trailer names that
+are not tokens, values with control bytes or edge whitespace, and the fields RFC 9110
+section 6.5.1 needs before the content: framing and routing (Content-Length,
+Transfer-Encoding, Trailer, TE, Host, Connection, Keep-Alive, Upgrade, Max-Forwards),
+authentication (Authorization, Proxy-Authorization, WWW-Authenticate, Proxy-Authenticate,
+Cookie, Set-Cookie), request modifiers and response controls (Expect, Range,
+Cache-Control) and content format (Content-Type, Content-Encoding, Content-Range).
+`is_chunked` leaves the rest of RFC 9112 section 6.3 to you: responses to HEAD, 1xx, 204,
+304 and 2xx to CONNECT carry no body, and an HTTP/1.0 message with Transfer-Encoding has
+faulty framing. There is no lenient mode.
+
+## Why
+
+Chunked transfer coding is simple to frame and easy to get subtly wrong: the terminating
+`0` chunk, the closing blank line, extensions and trailers are routinely mishandled, and
+the security advisories of the last few years (waitress, h11, aiohttp, netty, Go net/http,
+Node.js) are all variations on a parser accepting bytes another parser reads differently.
+The existing Python options are tied to one HTTP stack (`h11`, `aiohttp`) or to one server.
+This is a standalone, typed, zero-dependency codec with the strict behaviour by default:
+reach for it when you move chunked framing yourself and do not want a whole HTTP stack.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

chunkedte-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+chunkedte/__init__.py,sha256=eq8oeU3qOWLxiwajxdas9IHaF8Gs4Q-Uw9aM6THAoJA,478
+chunkedte/__main__.py,sha256=bkGcWn079Lh8m4EhrjcooxJWrj2JDycl_NG9cYSbEPA,127
+chunkedte/_cli.py,sha256=1BDahA4XtXMTS81S1XJH1wFdBxdu1qD_cMVTo4TcxqA,3364
+chunkedte/_decode.py,sha256=H2OBxW_6x1Ya-cgzzcoXq1YGz7XD8tXEtO8zTspt02Y,6723
+chunkedte/_encode.py,sha256=WuXHQF6Ck-8wGqjUjOixsk_SOpkTOp3PAVDjBUa_It0,3085
+chunkedte/_errors.py,sha256=AwFBoRQ3p7Qe9_YdFolEDbuidgFIWOfRpj25UBWqLGI,333
+chunkedte/_framing.py,sha256=HPq26FW0eIquFKTrZZ47GIig0rtnnYTEWoXPnYlKEFk,2907
+chunkedte/_grammar.py,sha256=fWOOu-wJ49T7K7U6UnrZ2Q8fGa4yhTHmFGzZOkBWQY8,3345
+chunkedte/_limits.py,sha256=jxYokXDOP4adzn978UUwRuiQsxrZy2fYlrRNOMy5N9w,1378
+chunkedte/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chunkedte-0.2.0.dist-info/METADATA,sha256=d-IglDkw9nW13VzBmgR85ddTWur5wkfR14P15LDdKSI,7987
+chunkedte-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+chunkedte-0.2.0.dist-info/entry_points.txt,sha256=gqJM4lraYEUzxKaMMTXz1kPb0vHJXXvZWp9LYKgTo80,50
+chunkedte-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+chunkedte-0.2.0.dist-info/RECORD,,

chunkedte-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

chunkedte-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chunkedte = chunkedte._cli:main

chunkedte-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.