rnet 3.0.0rc6__cp311-abi3-win_arm64.whl → 3.0.0rc8__cp311-abi3-win_arm64.whl

rnet/http2.py

@@ -0,0 +1,352 @@
+"""
+HTTP/2 connection configuration.
+"""
+
+import datetime
+from enum import Enum, auto
+from typing import ClassVar, Self, TypedDict, NotRequired, Unpack
+
+__all__ = [
+    "StreamId",
+    "StreamDependency",
+    "Priority",
+    "Priorities",
+    "PseudoId",
+    "PseudoOrder",
+    "SettingId",
+    "SettingsOrder",
+    "Params",
+    "Http2Options",
+]
+
+
+class PseudoId(Enum):
+    """
+    Represents the order of HTTP/2 pseudo-header fields in the header block.
+
+    HTTP/2 pseudo-header fields are a set of predefined header fields that start with ':'.
+    The order of these fields in a header block is significant. This enum defines the
+    possible pseudo-header fields and their standard order according to RFC 7540.
+    """
+
+    METHOD = auto()
+    SCHEME = auto()
+    AUTHORITY = auto()
+    PATH = auto()
+    PROTOCOL = auto()
+    STATUS = auto()
+
+
+class SettingId(Enum):
+    """
+    An enum that lists all valid settings that can be sent in a SETTINGS frame.
+
+    Each setting has a value that is a 32 bit unsigned integer (6.5.1.).
+
+    See <https://datatracker.ietf.org/doc/html/rfc9113#name-defined-settings>.
+    """
+
+    HEADER_TABLE_SIZE = auto()
+    """
+    This setting allows the sender to inform the remote endpoint
+    of the maximum size of the compression table used to decode field blocks,
+    in units of octets. The encoder can select any size equal to or less than
+    this value by using signaling specific to the compression format inside
+    a field block (see [COMPRESSION]). The initial value is 4,096 octets.
+    
+    [COMPRESSION]: <https://datatracker.ietf.org/doc/html/rfc7541>
+    """
+
+    ENABLE_PUSH = auto()
+    """
+    Enables or disables server push.
+    """
+
+    MAX_CONCURRENT_STREAMS = auto()
+    """
+    Specifies the maximum number of concurrent streams.
+    """
+
+    INITIAL_WINDOW_SIZE = auto()
+    """
+    Sets the initial stream-level flow control window size.
+    """
+
+    MAX_FRAME_SIZE = auto()
+    """
+    Indicates the largest acceptable frame payload size.
+    """
+
+    MAX_HEADER_LIST_SIZE = auto()
+    """
+    Advises the peer of the max field section size.
+    """
+
+    ENABLE_CONNECT_PROTOCOL = auto()
+    """
+    Enables support for the Extended CONNECT protocol.
+    """
+
+    NO_RFC7540_PRIORITIES = auto()
+    """
+    Disable RFC 7540 Stream Priorities.
+    [RFC 9218]: <https://www.rfc-editor.org/rfc/rfc9218.html#section-2.1>
+    """
+
+
+class StreamId:
+    """
+    A stream identifier, as described in [Section 5.1.1] of RFC 7540.
+
+    Streams are identified with an unsigned 31-bit integer. Streams
+    initiated by a client MUST use odd-numbered stream identifiers; those
+    initiated by the server MUST use even-numbered stream identifiers.  A
+    stream identifier of zero (0x0) is used for connection control
+    messages; the stream identifier of zero cannot be used to establish a
+    new stream.
+
+    [Section 5.1.1]: https://tools.ietf.org/html/rfc7540#section-5.1.1
+    """
+
+    ZERO: ClassVar[Self]
+    """Stream ID 0."""
+
+    MAX: ClassVar[Self]
+    """The maximum allowed stream ID."""
+
+    def __init__(self, src: int) -> None:
+        """
+        Create a new StreamId.
+        """
+        ...
+
+
+class StreamDependency:
+    """
+    Represents a stream dependency in HTTP/2 priority frames.
+
+    A stream dependency consists of three components:
+    * A stream identifier that the stream depends on
+    * A weight value between 0 and 255 (representing 1-256 in the protocol)
+    * An exclusive flag indicating whether this is an exclusive dependency
+
+    # Stream Dependencies
+
+    In HTTP/2, stream dependencies form a dependency tree where each stream
+    can depend on another stream. This creates a priority hierarchy that helps
+    determine the relative order in which streams should be processed.
+    """
+
+    def __init__(
+        self, dependency_id: StreamId, weight: int, is_exclusive: bool
+    ) -> None:
+        """
+        Create a new StreamDependency.
+        """
+        ...
+
+
+class Priority:
+    """
+    Represents an HTTP/2 PRIORITY frame (type=0x2).
+
+    The PRIORITY frame specifies the sender-advised priority of a stream,
+    as described in RFC 7540 Section 5.3. It can be sent in any stream state,
+    including idle or closed streams.
+
+    A PRIORITY frame consists of:
+    * The stream identifier whose priority is being set
+    * A StreamDependency object describing the dependency and weight
+
+    [Section 5.3]: https://tools.ietf.org/html/rfc7540#section-5.3
+    """
+
+    def __init__(self, stream_id: StreamId, dependency: StreamDependency) -> None:
+        """
+        Create a new Priority frame description.
+        """
+        ...
+
+
+class Priorities:
+    """
+    A collection of HTTP/2 PRIORITY frames.
+
+    The Priorities class maintains an ordered list of Priority frames,
+    which can be used to represent and manage the stream dependency tree
+    in HTTP/2. This is useful for pre-configuring stream priorities or
+    sending multiple PRIORITY frames at once during connection setup or
+    stream reprioritization.
+    """
+
+    def __init__(self, *priority: Priority) -> None:
+        """
+        Create a new Priorities instance.
+        """
+        ...
+
+
+class PseudoOrder:
+    """
+    Represents the order of HTTP/2 pseudo-header fields in the header block.
+
+    The PseudoOrder class maintains a list of PseudoId values that define
+    the order in which pseudo-header fields should appear in an HTTP/2
+    HEADERS frame. This is important because the order of pseudo-headers
+    is significant and must follow specific rules as defined in RFC 7540.
+    """
+
+    def __init__(self, *pseudo_id: PseudoId) -> None:
+        """
+        Create a new PseudoOrder instance.
+        """
+        ...
+
+
+class SettingsOrder:
+    """
+    Represents the order of HTTP/2 settings parameters in the SETTINGS frame.
+
+    The SettingsOrder class maintains a list of SettingId values that define
+    the order in which settings parameters should appear in an HTTP/2
+    SETTINGS frame. While the order of settings is not strictly enforced
+    by the protocol, having a consistent order can help with readability
+    and debugging.
+    """
+
+    def __init__(self, *setting_id: SettingId) -> None:
+        """
+        Create a new SettingsOrder instance.
+        """
+        ...
+
+
+class Params(TypedDict):
+    """
+    All parameters for HTTP/2 connections.
+    """
+
+    initial_window_size: NotRequired[int]
+    """
+    Initial window size for HTTP/2 streams.
+    """
+
+    initial_connection_window_size: NotRequired[int]
+    """
+    Initial connection-level window size.
+    """
+
+    initial_max_send_streams: NotRequired[int]
+    """
+    Initial maximum number of send streams.
+    """
+
+    initial_stream_id: NotRequired[int]
+    """
+    Initial stream ID for the connection.
+    """
+
+    adaptive_window: NotRequired[bool]
+    """
+    Whether to use adaptive flow control.
+    """
+
+    max_frame_size: NotRequired[int]
+    """
+    Maximum frame size to use for HTTP/2.
+    """
+
+    max_header_list_size: NotRequired[int]
+    """
+    Maximum size of the header list.
+    """
+
+    header_table_size: NotRequired[int]
+    """
+    Header table size for HPACK compression.
+    """
+
+    max_concurrent_streams: NotRequired[int]
+    """
+    Maximum concurrent streams from remote peer.
+    """
+
+    keep_alive_interval: NotRequired[datetime.timedelta]
+    """
+    Interval for HTTP/2 keep-alive ping frames.
+    """
+
+    keep_alive_timeout: NotRequired[datetime.timedelta]
+    """
+    Timeout for keep-alive ping acknowledgements.
+    """
+
+    keep_alive_while_idle: NotRequired[bool]
+    """
+    Whether keep-alive applies while idle.
+    """
+
+    enable_push: NotRequired[bool]
+    """
+    Whether to enable push promises.
+    """
+
+    enable_connect_protocol: NotRequired[bool]
+    """
+    Whether to enable the CONNECT protocol.
+    """
+
+    no_rfc7540_priorities: NotRequired[bool]
+    """
+    Whether to disable RFC 7540 Stream Priorities.
+    """
+
+    max_concurrent_reset_streams: NotRequired[int]
+    """
+    Max concurrent locally reset streams.
+    """
+
+    max_send_buf_size: NotRequired[int]
+    """
+    Maximum send buffer size for streams.
+    """
+
+    max_pending_accept_reset_streams: NotRequired[int]
+    """
+    Max pending accept reset streams.
+    """
+
+    headers_stream_dependency: NotRequired[StreamDependency]
+    """
+    Stream dependency for outgoing HEADERS.
+    """
+
+    headers_pseudo_order: NotRequired[PseudoOrder]
+    """
+    Order of pseudo-header fields in HEADERS.
+    """
+
+    settings_order: NotRequired[SettingsOrder]
+    """
+    Order of settings parameters in SETTINGS frame.
+    """
+
+    priorities: NotRequired[Priorities]
+    """
+    List of PRIORITY frames to send after connection.
+    """
+
+
+class Http2Options:
+    """
+    Configuration for an HTTP/2 connection.
+
+    This struct defines various parameters to fine-tune the behavior of an HTTP/2 connection,
+    including stream management, window sizes, frame limits, and header config.
+    """
+
+    def __init__(self, **kwargs: Unpack[Params]) -> None:
+        """
+        Create a new Http2Options instance.
+        """
+        ...

rnet/tls.py

@@ -8,9 +8,20 @@ These types are typically used to configure client-side TLS authentication and c
 
 from enum import Enum, auto
 from pathlib import Path
-from typing import List
-
-__all__ = ["TlsVersion", "Identity", "CertStore", "KeyLog"]
+from typing import List, NotRequired, TypedDict, Unpack
+
+__all__ = [
+    "TlsVersion",
+    "Identity",
+    "CertStore",
+    "KeyLog",
+    "AlpnProtocol",
+    "AlpsProtocol",
+    "CertificateCompressionAlgorithm",
+    "ExtensionType",
+    "TlsOptions",
+    "Params",
+]
 
 
 class TlsVersion(Enum):
@@ -24,6 +35,74 @@ class TlsVersion(Enum):
     TLS_1_3 = auto()
 
 
+class AlpnProtocol(Enum):
+    """
+    A TLS ALPN protocol.
+    """
+
+    HTTP1 = auto()
+    HTTP2 = auto()
+    HTTP3 = auto()
+
+
+class AlpsProtocol(Enum):
+    """
+    Application-layer protocol settings for HTTP/1.1 and HTTP/2.
+    """
+
+    HTTP1 = auto()
+    HTTP2 = auto()
+    HTTP3 = auto()
+
+
+class CertificateCompressionAlgorithm(Enum):
+    """
+    IANA assigned identifier of compression algorithm.
+    See https://www.rfc-editor.org/rfc/rfc8879.html#name-compression-algorithms
+    """
+
+    ZLIB = auto()
+    BROTLI = auto()
+    ZSTD = auto()
+
+
+class ExtensionType(Enum):
+    """
+    A TLS extension type.
+    """
+
+    SERVER_NAME = auto()
+    STATUS_REQUEST = auto()
+    EC_POINT_FORMATS = auto()
+    SIGNATURE_ALGORITHMS = auto()
+    SRTP = auto()
+    APPLICATION_LAYER_PROTOCOL_NEGOTIATION = auto()
+    PADDING = auto()
+    EXTENDED_MASTER_SECRET = auto()
+    QUIC_TRANSPORT_PARAMETERS_LEGACY = auto()
+    QUIC_TRANSPORT_PARAMETERS_STANDARD = auto()
+    CERT_COMPRESSION = auto()
+    SESSION_TICKET = auto()
+    SUPPORTED_GROUPS = auto()
+    PRE_SHARED_KEY = auto()
+    EARLY_DATA = auto()
+    SUPPORTED_VERSIONS = auto()
+    COOKIE = auto()
+    PSK_KEY_EXCHANGE_MODES = auto()
+    CERTIFICATE_AUTHORITIES = auto()
+    SIGNATURE_ALGORITHMS_CERT = auto()
+    KEY_SHARE = auto()
+    RENEGOTIATE = auto()
+    DELEGATED_CREDENTIAL = auto()
+    APPLICATION_SETTINGS = auto()
+    APPLICATION_SETTINGS_NEW = auto()
+    ENCRYPTED_CLIENT_HELLO = auto()
+    CERTIFICATE_TIMESTAMP = auto()
+    NEXT_PROTO_NEG = auto()
+    CHANNEL_ID = auto()
+    RECORD_SIZE_LIMIT = auto()
+
+
 class Identity:
     """
     Represents a private key and X509 cert as a client certificate.
@@ -149,3 +228,192 @@ class KeyLog:
             path: The file path to log TLS keys to.
         """
         ...
+
+
+class Params(TypedDict):
+    """
+    All parameters for TLS connections.
+    """
+
+    alpn_protocols: NotRequired[List[AlpnProtocol]]
+    """
+    Application-Layer Protocol Negotiation (RFC 7301).
+
+    Specifies which application protocols (e.g., HTTP/2, HTTP/1.1) may be negotiated
+    over a single TLS connection.
+    """
+
+    alps_protocols: NotRequired[List[AlpsProtocol]]
+    """
+    Application-Layer Protocol Settings (ALPS).
+
+    Enables exchanging application-layer settings during the handshake
+    for protocols negotiated via ALPN.
+    """
+
+    alps_use_new_codepoint: NotRequired[bool]
+    """
+    Whether to use an alternative ALPS codepoint for compatibility.
+
+    Useful when larger ALPS payloads are required.
+    """
+
+    session_ticket: NotRequired[bool]
+    """
+    Enables TLS Session Tickets (RFC 5077).
+
+    Allows session resumption without requiring server-side state.
+    """
+
+    min_tls_version: NotRequired[TlsVersion]
+    """
+    Minimum TLS version allowed for the connection.
+    """
+
+    max_tls_version: NotRequired[TlsVersion]
+    """
+    Maximum TLS version allowed for the connection.
+    """
+
+    pre_shared_key: NotRequired[bool]
+    """
+    Enables Pre-Shared Key (PSK) cipher suites (RFC 4279).
+
+    Authentication relies on out-of-band pre-shared keys instead of certificates.
+    """
+
+    enable_ech_grease: NotRequired[bool]
+    """
+    Controls whether to send a GREASE Encrypted ClientHello (ECH) extension
+    when no supported ECH configuration is available.
+
+    GREASE prevents protocol ossification by sending unknown extensions.
+    """
+
+    permute_extensions: NotRequired[bool]
+    """
+    Controls whether ClientHello extensions should be permuted.
+    """
+
+    grease_enabled: NotRequired[bool]
+    """
+    Controls whether GREASE extensions (RFC 8701) are enabled in general.
+    """
+
+    enable_ocsp_stapling: NotRequired[bool]
+    """
+    Enables OCSP stapling for the connection.
+    """
+
+    enable_signed_cert_timestamps: NotRequired[bool]
+    """
+    Enables Signed Certificate Timestamps (SCT).
+    """
+
+    record_size_limit: NotRequired[int]
+    """
+    Sets the maximum TLS record size.
+    """
+
+    psk_skip_session_ticket: NotRequired[bool]
+    """
+    Whether to skip session tickets when using PSK.
+    """
+
+    key_shares_limit: NotRequired[int]
+    """
+    Maximum number of key shares to include in ClientHello.
+    """
+
+    psk_dhe_ke: NotRequired[bool]
+    """
+    Enables PSK with (EC)DHE key establishment (`psk_dhe_ke`).
+    """
+
+    renegotiation: NotRequired[bool]
+    """
+    Enables TLS renegotiation by sending the `renegotiation_info` extension.
+    """
+
+    delegated_credentials: NotRequired[str]
+    """
+    Delegated Credentials (RFC 9345).
+
+    Allows TLS 1.3 endpoints to use temporary delegated credentials
+    for authentication with reduced long-term key exposure.
+    """
+
+    curves_list: NotRequired[str]
+    """
+    List of supported elliptic curves.
+    """
+
+    cipher_list: NotRequired[str]
+    """
+    Cipher suite configuration string.
+
+    Uses BoringSSL's mini-language to select, enable, and prioritize ciphers.
+    """
+
+    sigalgs_list: NotRequired[str]
+    """
+    List of supported signature algorithms.
+    """
+
+    certificate_compression_algorithms: NotRequired[
+        List[CertificateCompressionAlgorithm]
+    ]
+    """
+    Supported certificate compression algorithms (RFC 8879).
+    """
+
+    extension_permutation: NotRequired[List[ExtensionType]]
+    """
+    Supported TLS extensions, used for extension ordering/permutation.
+    """
+
+    aes_hw_override: NotRequired[bool]
+    """
+    Overrides AES hardware acceleration.
+    """
+
+    preserve_tls13_cipher_list: NotRequired[bool]
+    """
+    Sets whether to preserve the TLS 1.3 cipher list as configured by cipher_list.
+
+    By default, BoringSSL does not preserve the TLS 1.3 cipher list. When this option is disabled
+    (the default), BoringSSL uses its internal default TLS 1.3 cipher suites in its default order,
+    regardless of what is set via cipher_list.
+
+    When enabled, this option ensures that the TLS 1.3 cipher suites explicitly set via
+    cipher_list are retained in their original order, without being reordered or
+    modified by BoringSSL's internal logic. This is useful for maintaining specific cipher suite
+    priorities for TLS 1.3. Note that if cipher_list does not include any TLS 1.3
+    cipher suites, BoringSSL will still fall back to its default TLS 1.3 cipher suites and order.
+    """
+
+    random_aes_hw_override: NotRequired[bool]
+    """
+    Overrides the random AES hardware acceleration.
+    """
+
+
+class TlsOptions:
+    """
+    TLS connection configuration options.
+
+    This struct provides fine-grained control over the behavior of TLS
+    connections, including:
+     - **Protocol negotiation** (ALPN, ALPS, TLS versions)
+     - **Session management** (tickets, PSK, key shares)
+     - **Security & privacy** (OCSP, GREASE, ECH, delegated credentials)
+     - **Performance tuning** (record size, cipher preferences, hardware overrides)
+
+    All fields are optional or have defaults. See each field for details.
+    """
+
+    def __init__(self, **kwargs: Unpack[Params]) -> None:
+        """
+        Creates a new TlsOptions.
+        """
+        ...