rnet 3.0.0rc1__cp311-abi3-musllinux_1_2_aarch64.whl

rnet/header.py

@@ -0,0 +1,431 @@
+"""
+HTTP Header Management
+
+This module provides efficient storage and manipulation of HTTP headers with
+support for multiple values per header name. The HeaderMap class is designed
+to handle the complexities of HTTP header processing, including case-insensitive
+header names and multiple header values.
+
+The implementation follows HTTP specifications (RFC 7230) for header handling,
+including proper support for headers that can have multiple values (like
+Set-Cookie, Accept-Encoding, etc.).
+"""
+
+from typing import List, Optional, Tuple
+
+
+class HeaderMap:
+    r"""
+    A case-insensitive HTTP header map supporting multiple values per header.
+
+    This class provides efficient storage and retrieval of HTTP headers,
+    automatically handling case-insensitive header names and supporting
+    headers with multiple values (such as Set-Cookie or Accept-Encoding).
+
+    The implementation follows HTTP/1.1 specifications for header handling
+    and provides both dictionary-like access and specialized methods for
+    HTTP header manipulation.
+    """
+
+    def __getitem__(self, key: str) -> Optional[bytes]:
+        """Get the first value for a header name (case-insensitive)."""
+        ...
+
+    def __setitem__(self, key: str, value: str) -> None:
+        """Set a header to a single value, replacing any existing values."""
+        ...
+
+    def __delitem__(self, key: str) -> None:
+        """Remove all values for a header name."""
+        ...
+
+    def __contains__(self, key: str) -> bool:
+        """Check if a header name exists (case-insensitive)."""
+        ...
+
+    def __len__(self) -> int:
+        """Return the total number of header values (not unique names)."""
+        ...
+
+    def __iter__(self) -> "HeaderMapKeysIter":
+        """Iterate over unique header names."""
+        ...
+
+    def __str__(self) -> str:
+        """Return a string representation of all headers."""
+        ...
+
+    def __new__(
+        cls, init: Optional[dict] = None, capacity: Optional[int] = None
+    ) -> "HeaderMap":
+        """
+        Create a new HeaderMap.
+
+        Args:
+            init: Optional dictionary to initialize headers from
+            capacity: Optional initial capacity hint for performance
+
+        Returns:
+            A new HeaderMap instance
+
+        Example:
+            ```python
+            # Empty header map
+            headers = HeaderMap()
+
+            # Initialize from dictionary
+            headers = HeaderMap({
+                'Content-Type': 'text/html',
+                'Cache-Control': 'no-cache'
+            })
+
+            # Pre-allocate capacity for performance
+            headers = HeaderMap(capacity=50)
+            ```
+        """
+
+    def contains_key(self, key: str) -> bool:
+        r"""
+        Check if the header map contains the given key.
+
+        This is equivalent to using the 'in' operator but provides
+        an explicit method name. Header name comparison is case-insensitive.
+
+        Args:
+            key: The header name to check
+
+        Returns:
+            True if the header exists, False otherwise
+        """
+
+    def insert(self, key: str, value: str) -> None:
+        r"""
+        Insert a header, replacing any existing values.
+
+        This method replaces all existing values for the given header name
+        with the new value. For adding additional values, use append() instead.
+
+        Args:
+            key: The header name (case-insensitive)
+            value: The header value to set
+
+        Example:
+            ```python
+            headers.insert('Content-Type', 'application/json')
+            # Replaces any existing Content-Type header
+            ```
+        """
+
+    def append(self, key: str, value: str) -> None:
+        r"""
+        Append a value to an existing header or create a new one.
+
+        If the header already exists, this adds an additional value.
+        If the header doesn't exist, it creates a new header with this value.
+        This is useful for headers that can have multiple values.
+
+        Args:
+            key: The header name (case-insensitive)
+            value: The header value to append
+
+        Example:
+            ```python
+            headers.append('Accept-Encoding', 'gzip')
+            headers.append('Accept-Encoding', 'deflate')
+            # Results in: Accept-Encoding: gzip, deflate
+            ```
+        """
+
+    def remove(self, key: str) -> None:
+        r"""
+        Remove all values for a header name.
+
+        This removes the header entirely from the map. If the header
+        doesn't exist, this method does nothing.
+
+        Args:
+            key: The header name to remove (case-insensitive)
+        """
+
+    def get(self, key: str, default: Optional[bytes] = None) -> Optional[bytes]:
+        r"""
+        Get the first value for a header name with optional default.
+
+        Returns the first value associated with the header name, or the
+        default value if the header doesn't exist. For headers with multiple
+        values, use get_all() to retrieve all values.
+
+        Args:
+            key: The header name (case-insensitive)
+            default: Value to return if header doesn't exist
+
+        Returns:
+            The first header value as bytes, or the default value
+
+        Example:
+            ```python
+            content_type = headers.get('Content-Type', b'text/plain')
+            auth = headers.get('Authorization')  # Returns None if missing
+            ```
+        """
+
+    def get_all(self, key: str) -> "HeaderMapValuesIter":
+        r"""
+        Get all values for a header name.
+
+        Returns an iterator over all values associated with the header name.
+        This is useful for headers that can have multiple values, such as
+        Set-Cookie, Accept-Encoding, or custom headers.
+
+        Args:
+            key: The header name (case-insensitive)
+
+        Returns:
+            An iterator over all header values
+
+        Example:
+            ```python
+            # Get all Set-Cookie headers
+            cookies = list(headers.get_all('Set-Cookie'))
+
+            # Process multiple Accept-Encoding values
+            for encoding in headers.get_all('Accept-Encoding'):
+                print(f"Accepts: {encoding.decode()}")
+            ```
+        """
+
+    def len(self) -> int:
+        """
+        Get the total number of header values.
+
+        This returns the total count of header values, which can be greater
+        than the number of unique header names if some headers have multiple
+        values.
+
+        Returns:
+            Total number of header values stored
+        """
+
+    def keys_len(self) -> int:
+        """
+        Get the number of unique header names.
+
+        This returns the count of unique header names, regardless of how
+        many values each header has.
+
+        Returns:
+            Number of unique header names
+        """
+
+    def is_empty(self) -> bool:
+        """
+        Check if the header map is empty.
+
+        Returns:
+            True if no headers are stored, False otherwise
+        """
+
+    def clear(self) -> None:
+        """
+        Remove all headers from the map.
+
+        After calling this method, the header map will be empty and
+        is_empty() will return True.
+        """
+
+    def items(self) -> "HeaderMapItemsIter":
+        r"""
+        Get an iterator over all header name-value pairs.
+
+        Returns an iterator that yields tuples of (name, value) for each
+        header value. Headers with multiple values will appear multiple
+        times with different values.
+
+        Returns:
+            Iterator over (name, value) tuples
+
+        Example:
+            ```python
+            for name, value in headers.items():
+                print(f"{name.decode()}: {value.decode()}")
+            ```
+        """
+
+
+class OrigHeaderMap:
+    """
+    A map from header names to their original casing as received in an HTTP message.
+
+    OrigHeaderMap not only preserves the original case of each header name as it appeared
+    in the HTTP message, but also maintains the insertion order of headers. This makes
+    it suitable for use cases where the order of headers matters, such as HTTP/1.x message
+    serialization, proxying, or reproducing requests/responses exactly as received.
+
+    The map stores a mapping between the case-insensitive (standard) header name and the
+    original case-sensitive header name as it appeared in the HTTP message.
+
+    Example:
+        If an HTTP message included the following headers:
+
+            x-Bread: Baguette
+            X-BREAD: Pain
+            x-bread: Ficelle
+
+        Then the OrigHeaderMap would preserve both the exact casing and order of these headers:
+        - Standard name "x-bread" maps to original "x-Bread"
+        - Standard name "x-bread" maps to original "X-BREAD"
+        - Standard name "x-bread" maps to original "x-bread"
+
+        This allows the client to reproduce the exact header casing when forwarding or
+        reconstructing the HTTP message.
+    """
+
+    def __init__(
+        self,
+        init: Optional[List[str]] = None,
+        capacity: Optional[int] = None,
+    ) -> None:
+        """
+        Creates a new OrigHeaderMap from an optional list of header names.
+
+        Args:
+            init: Optional list of header names to initialize with.
+            capacity: Optional initial capacity for the map.
+        """
+        ...
+
+    def insert(self, value: str) -> bool:
+        """
+        Insert a new header name into the collection.
+
+        If the map did not previously have this key present, then False is returned.
+        If the map did have this key present, the new value is pushed to the end
+        of the list of values currently associated with the key. The key is not
+        updated, though; this matters for types that can be == without being identical.
+
+        Args:
+            value: The header name to insert.
+
+        Returns:
+            True if the key was newly inserted, False if it already existed.
+        """
+        ...
+
+    def extend(self, other: "OrigHeaderMap") -> None:
+        """
+        Extends the map with all entries from another OrigHeaderMap, preserving order.
+
+        Args:
+            other: Another OrigHeaderMap to extend from.
+        """
+        ...
+
+    def items(self) -> "OrigHeaderMapIter":
+        """
+        Returns an iterator over the (standard_name, original_name) pairs.
+
+        Returns:
+            An iterator over header name pairs.
+        """
+        ...
+
+    def __len__(self) -> int:
+        """
+        Returns the number of header names stored in the map.
+        """
+        ...
+
+
+class HeaderMapItemsIter:
+    r"""
+    Iterator over header name-value pairs in a HeaderMap.
+
+    Yields tuples of (header_name, header_value) where both are bytes.
+    Headers with multiple values will appear as separate tuples.
+    """
+
+    def __iter__(self) -> "HeaderMapItemsIter":
+        """Return self as iterator."""
+        ...
+
+    def __next__(self) -> Optional[Tuple[bytes, bytes]]:
+        """
+        Get the next header name-value pair.
+
+        Returns:
+            Tuple of (header_name, header_value) or None when exhausted
+        """
+        ...
+
+
+class HeaderMapKeysIter:
+    r"""
+    Iterator over unique header names in a HeaderMap.
+
+    Yields each unique header name as bytes, regardless of how many
+    values each header has.
+    """
+
+    def __iter__(self) -> "HeaderMapKeysIter":
+        """Return self as iterator."""
+        ...
+
+    def __next__(self) -> Optional[bytes]:
+        """
+        Get the next unique header name.
+
+        Returns:
+            Header name as bytes, or None when exhausted
+        """
+        ...
+
+
+class HeaderMapValuesIter:
+    r"""
+    Iterator over header values in a HeaderMap.
+
+    Yields header values as bytes. When used with get_all(), yields
+    all values for a specific header name. When used independently,
+    yields all values in the entire map.
+    """
+
+    def __iter__(self) -> "HeaderMapValuesIter":
+        """Return self as iterator."""
+        ...
+
+    def __next__(self) -> Optional[bytes]:
+        """
+        Get the next header value.
+
+        Returns:
+            Header value as bytes, or None when exhausted
+        """
+        ...
+
+
+class OrigHeaderMapIter:
+    """
+    An iterator over the items in an OrigHeaderMap.
+
+    Yields tuples of (standard_header_name, original_header_name) where:
+    - standard_header_name is the normalized header name
+    - original_header_name is the header name as originally received/specified
+    """
+
+    def __iter__(self) -> "OrigHeaderMapIter":
+        """
+        Returns the iterator itself.
+        """
+        ...
+
+    def __next__(self) -> Tuple[bytes, bytes]:
+        """
+        Returns the next (standard_name, original_name) pair.
+
+        Returns:
+            A tuple of (standard_header_name, original_header_name) as bytes.
+
+        Raises:
+            StopIteration: When there are no more items.
+        """
+        ...

rnet/tls.py

@@ -0,0 +1,161 @@
+"""
+TLS Utilities and Types
+
+This module provides types and utilities for configuring TLS (Transport Layer Security) in HTTP clients.
+
+These types are typically used to configure client-side TLS authentication and certificate verification in HTTP requests.
+"""
+
+from enum import Enum, auto
+from pathlib import Path
+from typing import List, Optional
+
+
+class TlsVersion(Enum):
+    r"""
+    The TLS version.
+    """
+
+    TLS_1_0 = auto()
+    TLS_1_1 = auto()
+    TLS_1_2 = auto()
+    TLS_1_3 = auto()
+
+
+class Identity:
+    """
+    Represents a private key and X509 cert as a client certificate.
+    """
+
+    @staticmethod
+    def from_pkcs12_der(buf: bytes, pass_: str) -> "Identity":
+        """
+        Parses a DER-formatted PKCS #12 archive, using the specified password to decrypt the key.
+
+        The archive should contain a leaf certificate and its private key, as well any intermediate
+        certificates that allow clients to build a chain to a trusted root.
+        The chain certificates should be in order from the leaf certificate towards the root.
+
+        PKCS #12 archives typically have the file extension `.p12` or `.pfx`, and can be created
+        with the OpenSSL `pkcs12` tool:
+
+            openssl pkcs12 -export -out identity.pfx -inkey key.pem -in cert.pem -certfile chain_certs.pem
+        """
+        ...
+
+    @staticmethod
+    def from_pkcs8_pem(buf: bytes, key: bytes) -> "CertStore":
+        """
+        Parses a chain of PEM encoded X509 certificates, with the leaf certificate first.
+        `key` is a PEM encoded PKCS #8 formatted private key for the leaf certificate.
+
+        The certificate chain should contain any intermediate certificates that should be sent to
+        clients to allow them to build a chain to a trusted root.
+
+        A certificate chain here means a series of PEM encoded certificates concatenated together.
+        """
+        ...
+
+
+class CertStore:
+    """
+    Represents a certificate store for verifying TLS connections.
+    """
+
+    def __new__(
+        cls,
+        der_certs: Optional[List[bytes]] = None,
+        pem_certs: Optional[List[str]] = None,
+        default_paths: Optional[bool] = None,
+    ) -> "CertStore":
+        """
+        Creates a new CertStore.
+
+        Args:
+            der_certs: Optional list of DER-encoded certificates (as bytes).
+            pem_certs: Optional list of PEM-encoded certificates (as str).
+            default_paths: If True, use system default certificate paths.
+        """
+        ...
+
+    @staticmethod
+    def from_der_certs(certs: List[bytes]) -> "CertStore":
+        """
+        Creates a CertStore from a collection of DER-encoded certificates.
+
+        Args:
+            certs: List of DER-encoded certificates (as bytes).
+        """
+        ...
+
+    @staticmethod
+    def from_pem_certs(certs: List[str]) -> "CertStore":
+        """
+        Creates a CertStore from a collection of PEM-encoded certificates.
+
+        Args:
+            certs: List of PEM-encoded certificates (as str).
+        """
+        ...
+
+    @staticmethod
+    def from_pem_stack(certs: bytes) -> "CertStore":
+        """
+        Creates a CertStore from a PEM-encoded certificate stack.
+
+        Args:
+            certs: PEM-encoded certificate stack (as bytes).
+        """
+        ...
+
+
+class KeyLogPolicy:
+    """
+    Specifies the intent for a (TLS) keylogger to be used in a client or server configuration.
+
+    This type allows you to control how TLS session keys are logged for debugging or analysis.
+    You can either use the default environment variable (SSLKEYLOGFILE) or specify a file path
+    directly. This is useful for tools like Wireshark that can decrypt TLS traffic if provided
+    with the correct session keys.
+
+    Static Methods:
+        environment() -> KeyLogPolicy
+            Use the SSLKEYLOGFILE environment variable for key logging.
+        file(path: Path) -> KeyLogPolicy
+            Log keys to the specified file path.
+
+    Methods:
+        is_environment() -> bool
+            Returns True if this policy uses the environment variable.
+        is_file() -> bool
+            Returns True if this policy logs to a specific file.
+    """
+
+    @staticmethod
+    def environment() -> "KeyLogPolicy":
+        """
+        Use the SSLKEYLOGFILE environment variable for key logging.
+        """
+        ...
+
+    @staticmethod
+    def file(path: Path) -> "KeyLogPolicy":
+        """
+        Log keys to the specified file path.
+
+        Args:
+            path: The file path to log TLS keys to.
+        """
+        ...
+
+    def is_environment(self) -> bool:
+        """
+        Returns True if this policy uses the environment variable.
+        """
+        ...
+
+    def is_file(self) -> bool:
+        """
+        Returns True if this policy logs to a specific file.
+        """
+        ...