codekingpro/portable-devtools

1from __future__ import annotations
2
3from collections.abc import Sequence
4
5from ..frames import Frame
6from ..typing import ExtensionName, ExtensionParameter
7
8
9__all__ = ["Extension", "ClientExtensionFactory", "ServerExtensionFactory"]
10
11
12class Extension:
13    """
14    Base class for extensions.
15
16    """
17
18    name: ExtensionName
19    """Extension identifier."""
20
21    def decode(self, frame: Frame, *, max_size: int | None = None) -> Frame:
22        """
23        Decode an incoming frame.
24
25        Args:
26            frame: Incoming frame.
27            max_size: Maximum payload size in bytes.
28
29        Returns:
30            Decoded frame.
31
32        Raises:
33            PayloadTooBig: If decoding the payload exceeds ``max_size``.
34
35        """
36        raise NotImplementedError
37
38    def encode(self, frame: Frame) -> Frame:
39        """
40        Encode an outgoing frame.
41
42        Args:
43            frame: Outgoing frame.
44
45        Returns:
46            Encoded frame.
47
48        """
49        raise NotImplementedError
50
51
52class ClientExtensionFactory:
53    """
54    Base class for client-side extension factories.
55
56    """
57
58    name: ExtensionName
59    """Extension identifier."""
60
61    def get_request_params(self) -> Sequence[ExtensionParameter]:
62        """
63        Build parameters to send to the server for this extension.
64
65        Returns:
66            Parameters to send to the server.
67
68        """
69        raise NotImplementedError
70
71    def process_response_params(
72        self,
73        params: Sequence[ExtensionParameter],
74        accepted_extensions: Sequence[Extension],
75    ) -> Extension:
76        """
77        Process parameters received from the server.
78
79        Args:
80            params: Parameters received from the server for this extension.
81            accepted_extensions: List of previously accepted extensions.
82
83        Returns:
84            An extension instance.
85
86        Raises:
87            NegotiationError: If parameters aren't acceptable.
88
89        """
90        raise NotImplementedError
91
92
93class ServerExtensionFactory:
94    """
95    Base class for server-side extension factories.
96
97    """
98
99    name: ExtensionName
100    """Extension identifier."""
101
102    def process_request_params(
103        self,
104        params: Sequence[ExtensionParameter],
105        accepted_extensions: Sequence[Extension],
106    ) -> tuple[list[ExtensionParameter], Extension]:
107        """
108        Process parameters received from the client.
109
110        Args:
111            params: Parameters received from the client for this extension.
112            accepted_extensions: List of previously accepted extensions.
113
114        Returns:
115            To accept the offer, parameters to send to the client for this
116            extension and an extension instance.
117
118        Raises:
119            NegotiationError: To reject the offer, if parameters received from
120                the client aren't acceptable.
121
122        """
123        raise NotImplementedError
124